spine-rigc 0.20.2 → 0.21.0

package/src/compile.ts

@@ -35,6 +35,10 @@ import {
 } from './depth.ts';
 import { CompileError, NotImplementedError } from './errors.ts';
 import { parseJsonWithPosition } from './json-position.ts';
+// The "did you mean" list on a missing atlas region, from the one implementation
+// of it — the same search serves `refuseUnknownKeys`, and a second copy here with
+// a threshold edited is how such a pair drifts apart.
+import { nearMisses } from './keys.ts';
 import { parseMotionSpec } from './motion.ts';
 import {
   parseRigSpec,
@@ -42,6 +46,7 @@ import {
   RIG_PATH_POSITION_MODES,
   RIG_PATH_ROTATE_MODES,
   RIG_PATH_SPACING_MODES,
+  RIG_SCALE_Y_MODES,
   RIG_SKIN_CONSTRAINT_KEYS,
   splitRigSkin,
   type RigAttachment,
@@ -136,6 +141,335 @@ export const SPINE_VERSION = '4.3.13';
 
 const FRAME = 1 / 60;
 
+/**
+ * The order the emitted `animations` object is keyed in: **the Spine editor's own
+ * comparator, as far as anybody has measured it** — natural and case-insensitive
+ * (#539) — with every name set refused on which one of that comparator's four
+ * UNMEASURED choices could decide a pair.
+ *
+ * ⚠️ This emitted **codepoint** order until issue #543, and the refusal was the
+ * thing that made codepoint agree with the editor: every pair the two could order
+ * differently was a `CompileError`. That is sound and it over-refuses by
+ * construction, because codepoint is not a member of the family it is being
+ * defended against — it is neither natural nor case-insensitive — so `Turn`
+ * against `sweep` and `turn10` against `turn2`, **the two pairs the editor was
+ * directly measured on**, were refused rather than emitted in the order the
+ * editor was measured returning. Sorting by a member of the measured family
+ * instead moves the refusal onto what is actually unmeasured, and moves no byte:
+ * on every set the codepoint rule accepted, the two orders are the same (that is
+ * what the rule guaranteed), which is why this change is invisible to every rig
+ * in the tree.
+ *
+ * ## Why the emitter has an opinion about this at all
+ *
+ * A `slider` constraint names the animation it applies, and in JSON that is a
+ * name on both sides. The **binary** format is where the same reference is an
+ * ordinal — `SkeletonBinary.js`: `constraint.animation = animations[readInt()]`
+ * — and an editor whose own model holds that ordinal reads the name at import
+ * and writes back whatever now stands at that position. Round-tripped through a
+ * licensed editor (data version 4.3.26), `gallery/look` went in as
+ * `turn, tilt, sweep` with `yaw -> "turn"` and came back as `sweep, tilt, turn`
+ * with **`yaw -> "sweep"`** (issue #535). Nothing in the returned file says so;
+ * it parses, it validates, and it applies the wrong animation.
+ *
+ * ⭐ The second slider is the control that names the mechanism rather than a
+ * second victim: `tilt` survived because it sat at index 1 in *both* orderings
+ * and index 1 is called `tilt` in both.
+ *
+ * ⇒ Emitting in the editor's own order makes its re-sort a no-op, so no index
+ * moves and no reference is repointed. Measured on the same rig through the
+ * same editor: mean absolute error over the re-rendered frames fell from
+ * 10.4655 / 8.4961 / 8.7140 to 0.3035 / 0.0769 / 0.0588, and `yaw -> "turn"`
+ * came back intact.
+ *
+ * ## What the editor's comparator is, and which parts of it are known
+ *
+ * ⚠️ This comment used to say that codepoint order "is what every editor-authored
+ * file on hand is in", and that sentence was false when it was written. The
+ * counterexample ships with the tests: `examples/spineboy/export/spineboy-pro.json`
+ * keys `portal-flare9` **before** `portal-flare10` — in its default skin's
+ * attachment map and in two of `portal`'s timeline maps — and no codepoint sort
+ * produces that.
+ *
+ * 🔢 The survey behind that, stated so it can be re-taken rather than believed:
+ * over the 12 skeletons in `examples/`, take **every object the format keys by a
+ * NAME that carries more than one key** — `animations` and `events`; each skin's
+ * `attachments` map and each per-slot map inside it; each animation's `bones`,
+ * `slots`, `ik`, `transform`, `path`, `physics`, `events`, and its deform
+ * `attachments` at **all three** of its levels (skin, then slot, then attachment
+ * name). Arrays are excluded because the editor leaves them alone. That is
+ * **105** collections, of which **102** are consistent with a codepoint sort and
+ * **3** are not; all 12 natural comparators and all 8 `Intl.Collator`
+ * configurations tried reproduce every one of the 105.
+ *
+ * ⚠️ The deform clause is the whole of what makes it 105 rather than 104, and it
+ * is one collection: `animations.hoverboard.attachments.default` in
+ * `spineboy-pro.json`, whose four keys are slot names. Counting the skin level
+ * of a deform block and stopping there needs an exception the sentence above
+ * cannot state — every level of it is keyed by a name, and the editor re-keys
+ * each one — so the rule is "every level", and that collection is in.
+ *
+ * The editor was then measured directly (issue #539). Two rigs, each varying one
+ * axis: `Turn, sweep, wave` came back `sweep, Turn, wave`, and
+ * `turn10, turn2, zoom` came back `turn2, turn10, zoom`. The intersection leaves
+ * one hypothesis — **natural order, case-insensitive**.
+ *
+ * ⚠️ "Natural, case-insensitive" is a **family** of comparators rather than one.
+ * Leading zeros (`turn01` against `turn1`), a pure case tie (`Turn` against
+ * `turn`), whether a digit run sorts before a word, and what a separator is worth
+ * are each a free choice, and **the editor's answers to them are not measured**.
+ * Writing a comparator that sorts every name set means choosing all four, and a
+ * chosen-but-unmeasured comparator is exactly how #537 landed.
+ *
+ * ⇒ 🔑 **So the family is never asked to sort a pair one of those four decides.**
+ * `measuredOrder` returns a verdict only where every member of the family must
+ * agree, and `refuseNamesTheEditorCouldKeyDifferently` stops the build on any pair
+ * where it cannot — which means the four choices below are **unobservable in the
+ * output**, and the claim the emit makes is the one #542 established, widened:
+ * *on this name set, every comparator consistent with what has been measured
+ * produces this order.* Checkable inside rigc, with no editor and no oracle.
+ *
+ * 🔒 The emitted key order is still the one claim in the emitter no gate can see.
+ * spine-core reads back everything else rigc writes; it does not sort. What
+ * replaces an oracle is the quantifier: the order is not *a* comparator's answer,
+ * it is the answer they all give.
+ *
+ * ⭐ The two-sided result is on editor-written data. Sorting each of the 105
+ * collections above by `measuredOrder` reproduces **105 of 105** — including the
+ * three no codepoint sort can — and refuses **none** of them. The codepoint rule
+ * reproduced 102 and refused those same 3.
+ *
+ * The family is hand-rolled and locale-independent, which `A18` requires:
+ * `localeCompare` would make the emitted bytes a property of the machine.
+ */
+function editorAnimationOrder<T>(animations: Record<string, T>): Record<string, T> {
+  const names = Object.keys(animations);
+  // ⭐ The sort is the check's own OUTPUT rather than a second reading of the same
+  // names: the refusal walks every pair and hands back the verdict it certified
+  // for each, so "the order rigc emits" and "the order rigc checked" cannot drift
+  // into two readings the way a shared comparator still can.
+  const verdicts = refuseNamesTheEditorCouldKeyDifferently(names);
+  // Nested rather than keyed on a joined string: any character this could join
+  // on is one an animation name is allowed to contain, and two pairs that
+  // collided would silently share one verdict.
+  names.sort((a, b) => verdicts.get(a)?.get(b) ?? 0);
+  const ordered: Record<string, T> = {};
+  for (const name of names) ordered[name] = animations[name];
+  return ordered;
+}
+
+/**
+ * The characters whose relative order every member of the measured family agrees
+ * on: the digits and, once case is folded, the lower-case ASCII letters.
+ * Everything else — `-`, `_`, a space, an accented letter — is worth something
+ * different to a collator that ignores punctuation than to one that does not, so
+ * a pair those decide is not settled.
+ */
+const SETTLED_CHARS = /[0-9a-z]/;
+
+/** Maximal runs of digits and of non-digits, which is what "natural" compares. */
+const runsOf = (name: string): string[] => name.match(/\d+|\D+/g) ?? [];
+
+const codepoint = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+/** What made a pair's order a matter of opinion, and what the author has to do. */
+interface Ambiguity {
+  kind: 'case' | 'number' | 'separator';
+  because: string;
+  repair: string;
+}
+
+/**
+ * How the editor's comparator orders these two names — or, when one of its four
+ * unmeasured choices is what decides them, what that choice is and what the
+ * author has to do about it.
+ *
+ * ## It is a certificate, not a hazard list
+ *
+ * Issue #539 proposed checking for "two names differing only in case, or sharing
+ * a prefix followed by digit runs of unequal length". **That list misses the rig
+ * that produced the measurement**: `Turn` and `sweep` differ in much more than
+ * case and carry no digits, and they are the pair the editor reordered. A list of
+ * hazards is open-ended — one was missing the day it was written — so what is
+ * implemented is the other direction: a verdict is returned only where the
+ * position that decides the pair is one **every** comparator consistent with the
+ * measurement must read the same way, and everything else stops the build.
+ *
+ * ## The four choices this returns an `Ambiguity` for, and why each is free
+ *
+ * - **case** (`Turn` against `turn`) — the two fold together, so only a tie-break
+ *   separates them and nobody has measured which way it breaks.
+ * - **number**, one number written twice (`turn01` against `turn1`) — the runs are
+ *   numerically equal, so again only a tie-break separates them: shorter-first,
+ *   longer-first and lexicographic are all real implementations.
+ * - **number**, a digit run against a word (`1turn` against `turn`) — comparators
+ *   differ on whether a number sorts before a word.
+ * - **separator** — the deciding character is neither a letter nor a digit. This
+ *   one covers two adversaries at once: a collator that treats `-` or a space as
+ *   ignorable, and the plain fact that `_` sits *between* `Z` and `a`, so
+ *   `x.toUpperCase()` and `x.toLowerCase()` order `wave_x` against `wavea`
+ *   oppositely. Neither name needs a capital in it for that to bite.
+ *
+ * ⚠️ There used to be a fifth and a sixth, and both were artefacts of emitting
+ * codepoint rather than facts about the editor (issue #543). A pair folding the
+ * other way (`Turn` against `sweep`) and two digit runs of unequal width
+ * (`turn10` against `turn2`) are exactly the two pairs the editor **was**
+ * measured on, and every comparator in the family orders them the same way — so
+ * they are now emitted in that order rather than refused. `flare1` against
+ * `flare10`, the over-refusal #542 named and accepted, goes with them.
+ *
+ * ## What it was tested against
+ *
+ * 22 comparators — 12 hand-rolled naturals (fold up/down × three leading-zero
+ * tie-breaks × digits-before/after words), 2 plain case-insensitive ones, and 8
+ * `Intl.Collator`s (`numeric: true`, four sensitivities × `ignorePunctuation`) —
+ * over every pair of names up to 4 characters from `{a B 0 1 2 - _ space}`:
+ * **10,948,860 pairs**. Three figures come off that bank and each is load-bearing:
+ *
+ * - **0 escapes**, where an escape is a pair some comparator orders differently
+ *   from the verdict returned here. Measured over the **20 natural** members —
+ *   the 12 hand-rolled and the 8 collators, all of which read a digit run as a
+ *   number. The 2 plain case-insensitive comparators do dissent (291,684 pairs),
+ *   and they are the two #539's own measurement refutes: a comparator that reads
+ *   `turn10` as text cannot return `turn2, turn10`.
+ * - **0 pairs move.** On every pair the codepoint rule accepted, this returns the
+ *   codepoint order — which is why no emitted byte in the tree changes.
+ * - the refusal covers **9,140,115** pairs where the codepoint rule covered
+ *   10,218,136: 1,078,021 pairs are now built instead of renamed.
+ *
+ * ⭐ And the two-sided result is on real data: across the 105 editor-written
+ * collections the survey above defines, sorting by this reproduces all 105 and
+ * refuses none. No false positive, no false negative, against names the editor
+ * itself wrote.
+ */
+function measuredOrder(a: string, b: string): number | Ambiguity {
+  const caseRepair = 'rename one of them so they differ by more than letter case';
+  const zerosRepair = 'write the number one way — rename so the digit run has a single spelling, with leading zeros or without';
+  const wordRepair = 'rename so a run of digits never has to be compared against a word';
+  const separatorRepair = 'rename so the first character that differs is a letter or a digit';
+  const la = a.toLowerCase();
+  const lb = b.toLowerCase();
+  if (la === lb) {
+    return {
+      kind: 'case',
+      because: `they are one name in two cases, and which of them the editor puts first is not measured`,
+      repair: caseRepair,
+    };
+  }
+  let i = 0;
+  while (i < la.length && i < lb.length && la[i] === lb[i]) i++;
+  if (i === la.length || i === lb.length) {
+    const longer = la.length > lb.length ? a : b;
+    const rest = (la.length > lb.length ? la : lb).slice(i);
+    if (!SETTLED_CHARS.test(rest)) {
+      return {
+        kind: 'separator',
+        because:
+          `"${longer}" is the other name followed by ${JSON.stringify(rest)}, which a comparator that ignores ` +
+          'punctuation reads as the same name',
+        repair: separatorRepair,
+      };
+    }
+  } else if (!SETTLED_CHARS.test(la[i]) || !SETTLED_CHARS.test(lb[i])) {
+    const deciding = SETTLED_CHARS.test(la[i]) ? lb[i] : la[i];
+    return {
+      kind: 'separator',
+      because:
+        `the first character that differs is ${JSON.stringify(deciding)}, which is neither a letter nor a digit, ` +
+        'and what that is worth is a property of the comparator',
+      repair: separatorRepair,
+    };
+  }
+  const ra = runsOf(la);
+  const rb = runsOf(lb);
+  for (let k = 0; k < Math.min(ra.length, rb.length); k++) {
+    const x = ra[k];
+    const y = rb[k];
+    if (x === y) continue;
+    const xIsDigits = /^\d/.test(x);
+    const yIsDigits = /^\d/.test(y);
+    if (xIsDigits && yIsDigits) {
+      const nx = BigInt(x);
+      const ny = BigInt(y);
+      if (nx === ny) {
+        return {
+          kind: 'number',
+          because: `"${x}" and "${y}" are the same number written two ways, so only a tie-break separates them`,
+          repair: zerosRepair,
+        };
+      }
+      return nx < ny ? -1 : 1;
+    }
+    if (xIsDigits !== yIsDigits) {
+      return {
+        kind: 'number',
+        because:
+          `one has the digits "${xIsDigits ? x : y}" where the other has "${xIsDigits ? y : x}", and comparators ` +
+          'differ on whether a number sorts before a word',
+        repair: wordRepair,
+      };
+    }
+    return codepoint(x, y);
+  }
+  // One name's runs are a prefix of the other's — `wave` against `wave1`. Every
+  // comparator puts the shorter first; `la === lb` above already took the case
+  // where neither is longer.
+  return ra.length < rb.length ? -1 : 1;
+}
+
+/** How many pairs a refusal spells out before it starts counting them instead. */
+const PAIRS_SPELLED_OUT = 8;
+
+/**
+ * Refuse a set of animation names the editor could key in an order rigc did not
+ * emit, and hand back the verdict for every pair that survived — the check that
+ * lets `editorAnimationOrder` sort by the measured family without choosing a
+ * member of it.
+ *
+ * It is deliberately **not** conditional on anything: not on the rig declaring a
+ * slider, and not on the rig declaring the editor as a consumer. A slider is what
+ * makes the difference bite today and `invariants.editorRoundTrip` is how a rig
+ * says the editor is downstream, but the emitted order is a claim about the
+ * editor either way, and a check that only ran for some rigs would make the claim
+ * hold for some and not others with nothing in the file saying which — adding the
+ * slider, or the declaration, would then be the edit that refuses a rig that built
+ * yesterday. What issue #543 changed is the size of what is claimed, not who it is
+ * claimed for.
+ */
+function refuseNamesTheEditorCouldKeyDifferently(names: readonly string[]): Map<string, Map<string, number>> {
+  const verdicts = new Map<string, Map<string, number>>();
+  const put = (x: string, y: string, v: number): void => {
+    const row = verdicts.get(x) ?? new Map<string, number>();
+    row.set(y, v);
+    verdicts.set(x, row);
+  };
+  const found: string[] = [];
+  for (let i = 0; i < names.length; i++) {
+    put(names[i], names[i], 0);
+    for (let j = i + 1; j < names.length; j++) {
+      const verdict = measuredOrder(names[i], names[j]);
+      if (typeof verdict === 'number') {
+        put(names[i], names[j], verdict);
+        put(names[j], names[i], -verdict);
+      } else {
+        found.push(`"${names[i]}" / "${names[j]}" (${verdict.kind}) — ${verdict.because}; ${verdict.repair}`);
+      }
+    }
+  }
+  if (!found.length) return verdicts;
+  const spelled = found.slice(0, PAIRS_SPELLED_OUT);
+  throw new CompileError(
+    `${found.length} pair(s) of animation names have no one order: rigc keys the emitted "animations" object in ` +
+      "the Spine editor's own comparator, which is natural and case-insensitive (#539) — but four of that " +
+      'comparator\'s choices have never been measured (a pure case tie, one number written two ways, a run of ' +
+      'digits against a word, and what a separator is worth), and each pair below is decided by one of them. A ' +
+      "slider's animation is an ORDINAL in the format's binary half, and an editor that keys these differently " +
+      'repoints every slider whose animation moves index — silently, in a file that still parses (#535). ' +
+      `${spelled.join('. ')}` +
+      (found.length > spelled.length ? `. …and ${found.length - spelled.length} more pair(s)` : ''),
+  );
+}
+
 // ---------------------------------------------------------------------------
 // number formatting — deterministic, and free of "-0"
 // ---------------------------------------------------------------------------
@@ -751,44 +1085,6 @@ function readAtlasIn(path: string): AtlasSource {
   return { path, dir: dirname(path), parsed, byName };
 }
 
-/**
- * How far apart two names are, for the "did you mean" list on a missing region.
- *
- * Plain Levenshtein. An atlas has tens of regions and this runs once per
- * refusal, so the O(n*m) table is free and a cheaper heuristic (shared prefix,
- * substring) would miss the commonest real case — a transposition or one wrong
- * character in a hand-typed `image`.
- */
-function nameDistance(a: string, b: string): number {
-  const rows = a.length + 1;
-  const cols = b.length + 1;
-  let previous = new Array<number>(cols);
-  for (let j = 0; j < cols; j++) previous[j] = j;
-  for (let i = 1; i < rows; i++) {
-    const current = new Array<number>(cols);
-    current[0] = i;
-    for (let j = 1; j < cols; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost);
-    }
-    previous = current;
-  }
-  return previous[cols - 1];
-}
-
-/** Up to five region names closest to the one that was not found. */
-function nearMisses(wanted: string, known: Iterable<string>): string[] {
-  const scored: Array<{ name: string; d: number }> = [];
-  for (const name of known) {
-    const d = nameDistance(wanted.toLowerCase(), name.toLowerCase());
-    // Half the name's length, floored at 2: "leg" must not suggest "arm", and a
-    // long name may still be recognisable through several typos.
-    if (d <= Math.max(2, Math.floor(wanted.length / 2))) scored.push({ name, d });
-  }
-  scored.sort((x, y) => x.d - y.d || (x.name < y.name ? -1 : 1));
-  return scored.slice(0, 5).map((s) => s.name);
-}
-
 /**
  * One part resolved out of a region of a pre-packed atlas — CLI `--atlas-in`.
  *
@@ -1810,7 +2106,13 @@ export function compile(opts: CompileOptions): CompileResult {
     // conditional spread rather than an assignment after the literal, so the key
     // lands in that position instead of at the end.
     ...(Object.keys(events).length ? { events } : {}),
-    animations,
+    // Keyed in the editor's own order rather than the motion spec's, because a
+    // slider's reference to an animation is an ordinal in the format and the
+    // editor re-sorts this object — see `editorAnimationOrder`. The sort is
+    // applied HERE and not to the loop above, so what the compiler reads, the
+    // order it reports durations in, and which animation a CompileError names
+    // first are all still the spec's own; only the emitted key order moves.
+    animations: editorAnimationOrder(animations),
   };
   if (constraints.length) skeleton.constraints = constraints;
 
@@ -3421,7 +3723,12 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
   if (spec.type === 'ik') {
     out.bones = boneList();
     out.target = needBone(spec.target, 'target');
-    copy(['scaleY', 'mix', 'softness', 'bendPositive', 'compress', 'stretch', 'skin']);
+    // `scaleY` is the `ScaleYMode` enum, not a number or a flag: the parser runs
+    // it through `Utils.enumValue` (`:150`), which resolves an unknown name to
+    // `undefined` and assigns it without a word. Out of `copy` for that reason —
+    // see `RIG_SCALE_Y_MODES`.
+    if (spec.scaleY !== undefined) out.scaleY = needEnum(spec.scaleY, 'scaleY', RIG_SCALE_Y_MODES);
+    copy(['mix', 'softness', 'bendPositive', 'compress', 'stretch', 'skin']);
     return out;
   }
   if (spec.type === 'transform') {
@@ -3807,13 +4114,15 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
   }
   if (spec.type === 'physics') {
     out.bone = needBone(spec.bone, 'bone');
+    // The same `ScaleYMode` enum an ik constraint carries, under the same key
+    // and through the same silent `Utils.enumValue` (`:301`).
+    if (spec.scaleY !== undefined) out.scaleY = needEnum(spec.scaleY, 'scaleY', RIG_SCALE_Y_MODES);
     copy([
       'x',
       'y',
       'rotate',
       'scaleX',
       'shearX',
-      'scaleY',
       'limit',
       'fps',
       'inertia',
@@ -3916,6 +4225,7 @@ function buildRigInfo(
     meshKinds,
     meshSoftBones,
     deformMayFold,
+    editorRoundTrip: rig.invariants?.editorRoundTrip === true,
     meshSlotBudget: rig.invariants?.meshSlots ?? null,
     meshTriangleBudget: rig.invariants?.meshTriangles ?? null,
     contactDepth,

package/src/keys.ts

@@ -0,0 +1,117 @@
+/**
+ * The other half of "the compiler never invents a value that is not in the
+ * spec": **the compiler never discards a value that is in the spec.**
+ *
+ * `src/compile.ts` reads an input object by naming the fields it knows — a
+ * literal list walked by a `copy` helper, or a run of `if (spec.x !== undefined)`
+ * lines. Either spelling asks the same question, *what does the emitter want?*,
+ * and neither ever asks the opposite one, *what does this file actually say?* So
+ * a key outside the known set was never looked at, never mentioned and never
+ * emitted, and the build exited 0 with every assertion green (issue #545).
+ *
+ * That is the input-side twin of the silence the whole tool exists to remove.
+ * A missing number is already a `CompileError` naming the field; an extra one
+ * was nothing at all — and the extra one is the worse of the two, because an
+ * invented value at least appears in the output where somebody can see it.
+ *
+ * ## What this module is, and what it is not
+ *
+ * It is one refusal and the near-miss search that makes the refusal a repair. It
+ * is **not** a schema: the known-key sets live beside the shapes they describe
+ * (`RIG_KEYS` in [`rig.ts`](rig.ts), `MOTION_KEYS` in [`motion.ts`](motion.ts)),
+ * because a set of key names two files away from its interface is a set that
+ * drifts from it. `KEY01` in `selftest.ts` derives each set from the interface's
+ * own source text and compares, so the pair cannot drift in silence, and `KEY02`
+ * refuses a declared key that occurs nowhere else in the tree — which is the
+ * exact shape `scaleYMode` had.
+ *
+ * ## Why the refusal is at parse time rather than at emit time
+ *
+ * The alternative considered was to record the keys the emitter actually
+ * touches and subtract them afterwards — no table at all, and therefore no
+ * drift. It is rejected for two measured reasons:
+ *
+ *   - **It answers a different question.** `buildRigMesh` returns at
+ *     `if (att.generator)` before reading `width`, `hull` or `edges`, so a
+ *     recorder would refuse `"width"` on a generated mesh and accept it on an
+ *     authored one. That makes the accepted key set a property of the file's own
+ *     values rather than of the format, and the format's key set is what an
+ *     agent authoring against it has to be told.
+ *   - **It cannot reach what the emitter never visits.** The emit loop walks the
+ *     rig's slots and skips one with no attachments before it reads `setup` —
+ *     the blind spot issue #293 was lost in for three weeks and `parseMotionSpec`
+ *     was written to remove. A recorder rebuilds it.
+ */
+import { CompileError } from './errors.ts';
+
+/**
+ * Levenshtein distance. Only ever called on the losing side of a refusal, so the
+ * O(n*m) table is free and a cheaper heuristic (shared prefix, substring) would
+ * miss the commonest real case — a transposition or one wrong character in a
+ * hand-typed name.
+ */
+export function nameDistance(a: string, b: string): number {
+  const rows = a.length + 1;
+  const cols = b.length + 1;
+  let previous = new Array<number>(cols);
+  for (let j = 0; j < cols; j++) previous[j] = j;
+  for (let i = 1; i < rows; i++) {
+    const current = new Array<number>(cols);
+    current[0] = i;
+    for (let j = 1; j < cols; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost);
+    }
+    previous = current;
+  }
+  return previous[cols - 1];
+}
+
+/** Up to five known names closest to the one that was not found. */
+export function nearMisses(wanted: string, known: Iterable<string>): string[] {
+  const scored: Array<{ name: string; d: number }> = [];
+  for (const name of known) {
+    const d = nameDistance(wanted.toLowerCase(), name.toLowerCase());
+    // Half the name's length, floored at 2: "leg" must not suggest "arm", and a
+    // long name may still be recognisable through several typos.
+    if (d <= Math.max(2, Math.floor(wanted.length / 2))) scored.push({ name, d });
+  }
+  scored.sort((x, y) => x.d - y.d || (x.name < y.name ? -1 : 1));
+  return scored.slice(0, 5).map((s) => s.name);
+}
+
+/**
+ * Refuse every key of `node` that `known` does not carry.
+ *
+ * ⭐ **Every** one of them, in one message, rather than the first. The four keys
+ * issue #545 planted into a single constraint were four separate mistakes an
+ * author had made in one place, and a refusal that names one of them buys three
+ * more round trips through a compile that is not cheap.
+ *
+ * ⭐ The near miss is what makes this a repair rather than a lecture. Both sides
+ * are lower-cased before the distance is taken, so `ROTATE` is distance 0 from
+ * `rotate` and comes back first — a real key in the wrong case is the commonest
+ * of these and the one an author is least likely to spot by re-reading.
+ *
+ * `known` may be empty (a shape with no fields at all); the message then says so
+ * rather than printing `known: ` with nothing after it.
+ */
+export function refuseUnknownKeys(
+  node: Record<string, unknown>,
+  known: readonly string[],
+  where: string,
+  what: string,
+): void {
+  const strays = Object.keys(node).filter((key) => !known.includes(key));
+  if (strays.length === 0) return;
+  const named = strays.map((key) => {
+    const near = nearMisses(key, known);
+    return near.length === 0 ? `"${key}"` : `"${key}" (did you mean ${near.map((n) => `"${n}"`).join(', ')}?)`;
+  });
+  throw new CompileError(
+    `${where}: ${what} has ${strays.length === 1 ? 'a key' : `${strays.length} keys`} this compiler does not read: ` +
+      `${named.join(', ')}. Nothing reads such a key, so it would be dropped from the emitted skeleton in silence — ` +
+      'fix the spelling or remove it. ' +
+      (known.length === 0 ? 'This shape has no fields at all.' : `Known here: ${[...known].sort().join(', ')}.`),
+  );
+}