spine-rigc 1.5.0 → 1.5.2

package/src/keys.ts

@@ -20,8 +20,8 @@
  * 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`
+ * drifts from it. `CUR17` in `selftest.ts` derives each set from the interface's
+ * own source text and compares, so the pair cannot drift in silence, and `CUR18`
  * refuses a declared key that occurs nowhere else in the tree — which is the
  * exact shape `scaleYMode` had.
  *
@@ -115,3 +115,298 @@ export function refuseUnknownKeys(
       (known.length === 0 ? 'This shape has no fields at all.' : `Known here: ${[...known].sort().join(', ')}.`),
   );
 }
+
+/**
+ * The largest float32, `3.4028234663852886e38`. The skeleton file is written at
+ * float32 precision (`f32` in `src/compile.ts` rounds every emitted number), so
+ * this is the largest magnitude a stated number can have and still come out of
+ * the emitter as a number.
+ */
+export const FLOAT32_MAX = 3.4028234663852886e38;
+
+/**
+ * Refuse the first number in an input file that the skeleton file cannot carry
+ * — one that is not finite, or that is finite only as a double (issue #881).
+ *
+ * 🚨 The defect this closes was a green build. `JSON.parse` reads `1e309` as
+ * `Infinity`, the emitter wrote it, and `JSON.stringify(Infinity)` is `null`:
+ * a bone stated at `x: 1e309` built green on the overlay probe as `"x": null`
+ * and was read as 0, a value the spec never stated. `1e308` did exactly the same
+ * — it is a finite double, but every emitted number is rounded to a float32 and
+ * `Math.fround(1e308)` is `Infinity` — so the line is float32's range and not
+ * the double's: `3.4028234663852886e38` built green and was emitted as itself,
+ * the next double up that rounds past it (`3.4028235677973366e38`) was emitted
+ * as `null`. The predicate is therefore `Number.isFinite(Math.fround(n))`,
+ * which is `NaN`, both infinities and exactly that overflow.
+ *
+ * ⭐ It walks the file, not the emitter's route — `checkRigSpecKeys`'s design
+ * and its reason. Before this, a handful of readers in `compile.ts` carried a
+ * finite check of their own (vertex arrays, a path's lengths, a segments
+ * falloff, a slider's mapping, an event's payload), each right about its own
+ * field, and none of them was a rule. Measured when this was written, planting
+ * `1e309` at every numeric leaf of nine rig specs — 610 plants over 57 kinds
+ * of field: 19 kinds were refused by a rule of their own (30 of those 70
+ * refusals printing the Infinity as `null`, and some only by a later symptom
+ * such as *hull Infinity disagrees with the triangles*), 1 was caught only by
+ * the gate, and 37 built green with a `null` in them on at least one rig. One
+ * pass over every number the document holds cannot miss a reader added next
+ * month, and it runs before any of them — so a range rule further down (a
+ * radius that is positive, a weight in 0..1) never has to print `NaN`.
+ *
+ * 🔒 The report order is fixed: `Object.keys` of parsed JSON is the
+ * document's key order (integer-like keys first, as the language orders them)
+ * and arrays are visited by index, so the refusal names the same number on
+ * every run.
+ *
+ * ⚠️ What it cannot see is a number spelled as something else. `"x": "NaN"`
+ * is a string; there is no number here to refuse, and that is
+ * `refuseValuesOfTheWrongType`'s question (issue #890), which the parsers ask
+ * before this walk on the rig spec and the manifest, and after the motion
+ * spec's own field checks.
+ *
+ * `place` turns a path into the words the refusal uses for it.
+ */
+export function refuseNumbersTheFileCannotCarry(
+  raw: unknown,
+  where: string,
+  place: (path: ReadonlyArray<string | number>) => string,
+): void {
+  const visit = (node: unknown, path: Array<string | number>): void => {
+    if (typeof node === 'number') {
+      if (Number.isFinite(Math.fround(node))) return;
+      const why = Number.isNaN(node)
+        ? ''
+        : Number.isFinite(node)
+          ? ' This one is finite as a double and has no float32 but Infinity.'
+          : ' JSON has no spelling for Infinity: a literal past ±1.7976931348623157e308, such as 1e309, parses to it.';
+      throw new CompileError(
+        `${where}: ${place(path)} is ${String(node)}; a number in this file is finite at float32 precision, at most ` +
+          `±${String(FLOAT32_MAX)}, because the skeleton is written as float32 — past that it would be emitted as ` +
+          `Infinity, which JSON writes as null, a value the file never stated.${why}`,
+      );
+    }
+    if (Array.isArray(node)) {
+      node.forEach((child, i) => visit(child, [...path, i]));
+    } else if (node !== null && typeof node === 'object') {
+      const record = node as Record<string, unknown>;
+      for (const key of Object.keys(record)) visit(record[key], [...path, key]);
+    }
+  };
+  visit(raw, []);
+}
+
+/** A path as the file spells it: `.key`, `."odd key"`, `[3]`. */
+export function dottedPath(path: ReadonlyArray<string | number>): string {
+  let out = '';
+  for (const step of path) {
+    if (typeof step === 'number') out += `[${step}]`;
+    else out += /^[A-Za-z_][A-Za-z0-9_]*$/.test(step) ? `${out === '' ? '' : '.'}${step}` : `${out === '' ? '' : '.'}${JSON.stringify(step)}`;
+  }
+  return out;
+}
+
+/**
+ * The type a field of an input file holds — the vocabulary of the per-shape
+ * type tables (`RIG_TYPES` in [`rig.ts`](rig.ts), `MOTION_TYPES` in
+ * [`motion.ts`](motion.ts), `MANIFEST_TYPES` in [`types.ts`](types.ts)).
+ *
+ * The first twelve are **checked** by `refuseValuesOfTheWrongType`. The last
+ * six are named so that every key has a type, and are deliberately not checked
+ * here, because each already has an owner that says more than a type could:
+ *
+ *   - `object`, `object[]`, `object[][]`, `map of object` — a nested shape. Its
+ *     own keys are typed in its own row, and whether the container is the right
+ *     kind of container is the refusal of the reader that walks it (a rig spec's
+ *     `"bones"` that is not an array is *a rig spec needs a non-empty "bones"
+ *     array*);
+ *   - `enum` — a closed set of names, refused by name where it is read, with the
+ *     names that exist listed (a slot's `blend`, a constraint's `type`);
+ *   - `mixed` — a union of kinds whose owner decides by the value (`MotionKey.v`
+ *     is numbers on `rotate`, a name on `attachment`, a member map on a group).
+ */
+export const SPEC_VALUE_TYPES = [
+  'number',
+  'string',
+  'boolean',
+  'number | null',
+  'string | null',
+  'number[]',
+  'number[] | null',
+  'string[]',
+  'number[][]',
+  'map of number[]',
+  'map of string[]',
+  'map of string | null',
+  'object',
+  'object[]',
+  'object[][]',
+  'map of object',
+  'enum',
+  'mixed',
+] as const;
+
+export type SpecValueType = (typeof SPEC_VALUE_TYPES)[number];
+
+/** A shape's keys and the type each one holds. */
+export type SpecTypeRow = Readonly<Record<string, SpecValueType>>;
+
+/** One node of an input file that a key scan visited, as the type walk needs it. */
+export interface ShapeVisit {
+  node: Record<string, unknown>;
+  /** The row of the type table this node's keys are typed by. */
+  shape: string;
+  /** The words a refusal uses for a path below this node — `x`, `weights[3][1]`, `color[2]`. */
+  name: (tail: ReadonlyArray<string | number>) => string;
+}
+
+/** What a JSON value is, in the words the type refusal uses: `a string "5"`, `an array [1]`, `null`. */
+function typeFound(value: unknown): string {
+  if (value === null) return 'null';
+  const kind = Array.isArray(value) ? 'array' : typeof value === 'object' ? 'object' : typeof value;
+  const shown = JSON.stringify(value) ?? String(value);
+  return `${/^[aeiou]/.test(kind) ? 'an' : 'a'} ${kind} ${shown.length > 60 ? `${shown.slice(0, 57)}...` : shown}`;
+}
+
+/** A checked type as the refusal requires it: `a number`, `an array of numbers`, `a string or null`. */
+const REQUIRED: Record<string, string> = {
+  number: 'a number',
+  string: 'a string',
+  boolean: 'a boolean (true or false)',
+  'number | null': 'a number or null',
+  'string | null': 'a string or null',
+  'number[]': 'an array of numbers',
+  'number[] | null': 'an array of numbers, or null',
+  'string[]': 'an array of strings',
+  'number[][]': 'an array of arrays of numbers',
+  'map of number[]': 'an object whose every value is an array of numbers',
+  'map of string[]': 'an object whose every value is an array of strings',
+  'map of string | null': 'an object whose every value is a string or null',
+};
+
+/** The types `refuseValuesOfTheWrongType` checks — every one `REQUIRED` can word. */
+export const CHECKED_SPEC_VALUE_TYPES: readonly SpecValueType[] = SPEC_VALUE_TYPES.filter((t) => REQUIRED[t] !== undefined);
+
+/**
+ * The first place under `value` that is not of `type`, and what was required
+ * there — or `null` when it is. An element fault names its own index, so an
+ * array of numbers with a string in slot 3 is refused at `[3]` rather than as
+ * a whole array.
+ */
+function wrongTypeAt(
+  value: unknown,
+  type: SpecValueType,
+): { tail: Array<string | number>; value: unknown; required: string } | null {
+  const is = (v: unknown, t: SpecValueType): boolean => {
+    switch (t) {
+      case 'number':
+        return typeof v === 'number';
+      case 'string':
+        return typeof v === 'string';
+      case 'boolean':
+        return typeof v === 'boolean';
+      case 'number | null':
+        return v === null || typeof v === 'number';
+      case 'string | null':
+        return v === null || typeof v === 'string';
+      default:
+        return true;
+    }
+  };
+  const fault = (tail: Array<string | number>, v: unknown, t: SpecValueType) => ({ tail, value: v, required: REQUIRED[t] });
+  const list = (v: unknown, element: SpecValueType, whole: SpecValueType, tail: Array<string | number>) => {
+    if (!Array.isArray(v)) return fault(tail, v, whole);
+    for (const [i, item] of v.entries()) if (!is(item, element)) return fault([...tail, i], item, element);
+    return null;
+  };
+  const map = (v: unknown, each: SpecValueType, whole: SpecValueType) => {
+    if (v === null || typeof v !== 'object' || Array.isArray(v)) return fault([], v, whole);
+    const record = v as Record<string, unknown>;
+    for (const key of Object.keys(record)) {
+      const inner = wrongTypeAt(record[key], each);
+      if (inner !== null) return { ...inner, tail: [key, ...inner.tail] };
+    }
+    return null;
+  };
+  switch (type) {
+    case 'number':
+    case 'string':
+    case 'boolean':
+    case 'number | null':
+    case 'string | null':
+      return is(value, type) ? null : fault([], value, type);
+    case 'number[]':
+      return list(value, 'number', type, []);
+    case 'number[] | null':
+      return value === null ? null : list(value, 'number', type, []);
+    case 'string[]':
+      return list(value, 'string', type, []);
+    case 'number[][]': {
+      if (!Array.isArray(value)) return fault([], value, type);
+      for (const [i, row] of value.entries()) {
+        const inner = list(row, 'number', 'number[]', [i]);
+        if (inner !== null) return inner;
+      }
+      return null;
+    }
+    case 'map of number[]':
+      return map(value, 'number[]', type);
+    case 'map of string[]':
+      return map(value, 'string[]', type);
+    case 'map of string | null':
+      return map(value, 'string | null', type);
+    default:
+      return null;
+  }
+}
+
+/**
+ * Refuse the first value in an input file whose JSON type is not the one its
+ * field holds (issue #890).
+ *
+ * 🚨 The defect this closes was a green build, and it sat directly under the
+ * rule #881 wrote. A number that is not a number is coerced by the arithmetic
+ * that reads it before any rule sees a number at all: measured on the root bone
+ * of the generated probes, `"x": "5"` built as `5`, `"rotation": "90"` as `90`,
+ * `"x": true` as `1`, `"x": [1]` as `1` and `"x": "NaN"` as `null`, every one
+ * green. The compiler was writing a value the spec never stated, or one it
+ * guessed.
+ *
+ * ⭐ It walks the nodes the key scan visited, not the emitter's route, and it
+ * reads the type table that sits beside the key table — so a key cannot be
+ * admitted by the scan and untyped here (a selftest control holds the two
+ * tables equal, and so does `satisfies` over the key table's own type). The
+ * refusal names the field, the value found and the type required:
+ * `bone "hip" x is a string "5"; a number is required`.
+ *
+ * 🔒 The report order is fixed — visits in the scan's order, keys in the
+ * document's order, arrays by index — so the refusal names the same value on
+ * every run.
+ *
+ * ⚠️ A JSON `null` is a value, not an absence. It is accepted only where the
+ * field's type says `null` (a slot's setup `attachment`, a stage stated absent);
+ * everywhere else it is refused as `null`, because the readers downstream
+ * treated it as whatever `null` coerces to in the arithmetic they happened to do
+ * — measured, a bone's `"rotation": null` built green with its bytes moved.
+ */
+export function refuseValuesOfTheWrongType(
+  visits: readonly ShapeVisit[],
+  types: Readonly<Record<string, SpecTypeRow>>,
+  where: string,
+): void {
+  for (const visit of visits) {
+    const row = types[visit.shape];
+    if (row === undefined) throw new Error(`no type row for shape ${visit.shape} (a key scan visited a shape the type table does not have)`);
+    for (const key of Object.keys(visit.node)) {
+      const type = row[key];
+      // An unknown key is the key scan's refusal and it has already run; a
+      // shape without a scan (the cut manifest) tolerates keys it does not
+      // read, and this walk does not change what a shape accepts.
+      if (type === undefined) continue;
+      const wrong = wrongTypeAt(visit.node[key], type);
+      if (wrong === null) continue;
+      throw new CompileError(
+        `${where}: ${visit.name([key, ...wrong.tail])} is ${typeFound(wrong.value)}; ${wrong.required} is required`,
+      );
+    }
+  }
+}

package/src/motion.ts

@@ -54,7 +54,8 @@
  * [`keys.ts`](keys.ts) shared with the rig parser.
  */
 import { CompileError } from './errors.ts';
-import { refuseUnknownKeys } from './keys.ts';
+import { dottedPath, refuseNumbersTheFileCannotCarry, refuseUnknownKeys, refuseValuesOfTheWrongType } from './keys.ts';
+import type { ShapeVisit, SpecValueType } from './keys.ts';
 import { SEQUENCE_MODES } from './timelines.ts';
 import type { MotionSpec } from './types.ts';
 
@@ -112,7 +113,7 @@ const CONSTRAINT_GROUPS = ['ik', 'transform'] as const;
  * it — the runtime shadow of types TypeScript erases, and the other half of
  * `RIG_KEYS` in [`rig.ts`](rig.ts).
  *
- * 🔒 Held to those interfaces by `KEY01` in `selftest.ts`, which reads the
+ * 🔒 Held to those interfaces by `CUR17` in `selftest.ts`, which reads the
  * declaring source and compares. The interfaces are spread over three modules —
  * `types.ts` for the format, [`trackgen.ts`](trackgen.ts) for a track's `derive`
  * and [`deformgen.ts`](deformgen.ts) for a deform key's `transform` — and the
@@ -152,6 +153,80 @@ export const MOTION_KEYS = {
   DeformBend: ['kind', 'amount', 'from', 'to', 'power', 'along', 'axis'],
 } as const satisfies Record<string, readonly string[]>;
 
+/**
+ * The type every key of `MOTION_KEYS` holds, shape by shape — what
+ * `refuseValuesOfTheWrongType` refuses a value against (issue #890), held to
+ * the key table by `satisfies MotionTypeTable` and by the selftest, exactly as
+ * `RIG_TYPES` is.
+ *
+ * ⚠️ The walk runs LAST in `parseMotionSpec`, after every field check above,
+ * so a field this file already checks keeps its own sentence (a physics tuning
+ * number, a key's `t`, an easing's handles) and the walk is what covers the
+ * fields nothing here reads — an ik key's `mix`, a deform key's `offset`, an
+ * event key's `float`, a derive's `degrees`.
+ *
+ * Where an unchecked type is refused: `spec` — the version check; a track's
+ * `property` — `compileTrack`; a derive's `kind` — `evaluateTrackDerive`; a deform
+ * transform's `kind`, `along` and `axis` — `evaluateDeformTransform`;
+ * `MotionKey.v`, a key's `curve`, a derive's `depth` and `mix.pairs` (`mixed`)
+ * — the track compiler by property, the curve reader, the derive evaluator and
+ * `parseMix`. A sequence key's `mode` is a closed set too, but its interface
+ * declares it `string` and so does this row: `parseSequence` refuses a name
+ * outside `SEQUENCE_MODES` before the walk runs, and a non-string with it.
+ */
+type MotionTypeTable = {
+  readonly [S in keyof typeof MOTION_KEYS]: { readonly [K in (typeof MOTION_KEYS)[S][number]]: SpecValueType };
+};
+
+export const MOTION_TYPES = {
+  MotionSpec: {
+    spec: 'enum', archetype: 'string', cut: 'string', note: 'string', easings: 'map of number[]', groups: 'map of string[]',
+    setup: 'map of object', physics: 'map of object', animations: 'map of object', mix: 'object',
+  },
+  MotionMix: { default: 'number', pairs: 'mixed' },
+  MotionSetupSlot: { attachment: 'string | null', color: 'number[]' },
+  MotionPhysics: {
+    bone: 'string', x: 'number', y: 'number', rotate: 'number', scaleX: 'number', shearX: 'number', inertia: 'number',
+    strength: 'number', damping: 'number', mass: 'number', wind: 'number', gravity: 'number', mix: 'number',
+    fps: 'number', limit: 'number', note: 'string',
+  },
+  MotionAnimation: {
+    duration: 'number', loop: 'boolean', note: 'string', tracks: 'object[]', ik: 'object[]', transform: 'object[]',
+    deform: 'object[]', sequence: 'object[]', drawOrder: 'object[]', events: 'object[]',
+  },
+  MotionTrack: {
+    slot: 'string', group: 'string', bone: 'string', physics: 'string', path: 'string', slider: 'string',
+    property: 'enum', lag: 'number', stagger: 'number', keys: 'object[]',
+  },
+  MotionKey: { t: 'number', v: 'mixed', derive: 'object', ease: 'string', curve: 'mixed' },
+  MotionIkTrack: { constraint: 'string', keys: 'object[]' },
+  MotionIkKey: {
+    t: 'number', mix: 'number', softness: 'number', bendPositive: 'boolean', compress: 'boolean', stretch: 'boolean',
+    ease: 'string', curve: 'mixed',
+  },
+  MotionTransformTrack: { constraint: 'string', keys: 'object[]' },
+  MotionTransformKey: {
+    t: 'number', mixRotate: 'number', mixX: 'number', mixY: 'number', mixScaleX: 'number', mixScaleY: 'number',
+    mixShearY: 'number', ease: 'string', curve: 'mixed',
+  },
+  MotionDeformTrack: { skin: 'string', slot: 'string', attachment: 'string', keys: 'object[]' },
+  MotionDeformKey: {
+    t: 'number', offset: 'number', fromVertex: 'number', vertices: 'number[] | null', transform: 'object', ease: 'string', curve: 'mixed',
+  },
+  MotionSequenceTrack: { skin: 'string', slot: 'string', attachment: 'string', keys: 'object[]' },
+  MotionSequenceKey: { t: 'number', mode: 'string', index: 'number', delay: 'number' },
+  MotionDrawOrderKey: { t: 'number', offsets: 'object[]' },
+  MotionDrawOrderOffset: { slot: 'string', offset: 'number' },
+  MotionEventKey: {
+    t: 'number', name: 'string', int: 'number', float: 'number', string: 'string', volume: 'number', balance: 'number',
+  },
+  TrackDeriveTurn: { kind: 'enum', degrees: 'number', depth: 'mixed', carried: 'number', about: 'number' },
+  DeformTurn: { kind: 'enum', radius: 'number', depth: 'boolean', degrees: 'number', about: 'number' },
+  DeformAffine: { kind: 'enum', scale: 'number[]', about: 'number[]' },
+  DeformWave: { kind: 'enum', amplitude: 'number', wavelength: 'number', phase: 'number', along: 'enum', axis: 'enum' },
+  DeformBend: { kind: 'enum', amount: 'number', from: 'number', to: 'number', power: 'number', along: 'enum', axis: 'enum' },
+} as const satisfies MotionTypeTable;
+
 /** A deform key's `transform` kinds, and the shape each one's keys come from. */
 const DEFORM_TRANSFORM_SHAPE: Record<string, keyof typeof MOTION_KEYS> = {
   yaw: 'DeformTurn',
@@ -199,9 +274,27 @@ function refuse(where: string, key: string, is: unknown, hint: string): never {
  * the wrong field.
  */
 function known(node: unknown, shape: keyof typeof MOTION_KEYS, where: string, at: string): void {
-  if (isObj(node)) refuseUnknownKeys(node, MOTION_KEYS[shape], where, `\`${at}\``);
+  if (!isObj(node)) return;
+  refuseUnknownKeys(node, MOTION_KEYS[shape], where, `\`${at}\``);
+  // The root is named by its keys alone — `archetype`, not `this motion spec.archetype`.
+  const prefix = shape === 'MotionSpec' ? '' : at;
+  visiting?.push({
+    node,
+    shape,
+    name: (tail) => `\`${prefix}${tail.map((step, i) => (typeof step === 'number' ? `[${step}]` : prefix === '' && i === 0 ? step : `.${step}`)).join('')}\``,
+  });
 }
 
+/**
+ * The nodes `known` admitted during the parse in progress, in the order it
+ * admitted them — what `refuseValuesOfTheWrongType` walks at the end of
+ * `parseMotionSpec`. Module state rather than a parameter because `known` is
+ * called from a dozen readers that would otherwise each carry it; it is set and
+ * cleared by `parseMotionSpec` alone, around a parse that is synchronous and
+ * does not re-enter, so no two parses ever share it.
+ */
+let visiting: ShapeVisit[] | null = null;
+
 // --- the leaf checks, each returning the value it just proved ---------------
 
 function needObj(v: unknown, where: string, key: string, hint: string): Record<string, unknown> {
@@ -633,6 +726,16 @@ function parseAnimation(raw: unknown, where: string, name: string): void {
  * otherwise no way to tell which of them is at fault (issue #227).
  */
 export function parseMotionSpec(raw: unknown, where: string): MotionSpec {
+  const visits: ShapeVisit[] = [];
+  visiting = visits;
+  try {
+    return parseMotionSpecInto(raw, where, visits);
+  } finally {
+    visiting = null;
+  }
+}
+
+function parseMotionSpecInto(raw: unknown, where: string, visits: readonly ShapeVisit[]): MotionSpec {
   if (!isObj(raw)) {
     throw new CompileError(`${where}: a motion spec must be a JSON object, and this file holds ${describe(raw)}`);
   }
@@ -665,5 +768,22 @@ export function parseMotionSpec(raw: unknown, where: string): MotionSpec {
     parseAnimation(anim, where, name);
   }
 
+  // After every field check above, so a field this file checks keeps its own
+  // sentence, and before the finite walk, so a value that is not a number is
+  // named as that rather than skipped (issue #890). What reaches this line is a
+  // field nothing above reads. Measured before the walk, every one of 303
+  // wrong-typed plants over 18 motion shapes was refused somewhere — but later,
+  // by the timeline compiler, and 7 of those sentences named the wrong fault:
+  // an event key's `"float": "1"` as *float 1 is not finite*, a `"volume": "1"`
+  // as an event with no audio, a yaw transform's `"depth": "true"` as a radius
+  // that is undefined.
+  refuseValuesOfTheWrongType(visits, MOTION_TYPES, where);
+
+  // Last, so every field check above keeps its own sentence for a number that
+  // is not finite; what reaches this line is a finite double the float32 file
+  // cannot carry — a key at 1e308 built green with a `null` in it before issue
+  // #881 — and any number in a field no check above reads.
+  refuseNumbersTheFileCannotCarry(raw, where, (path) => `\`${dottedPath(path)}\``);
+
   return raw as unknown as MotionSpec;
 }

package/src/pose.ts

@@ -274,8 +274,9 @@ const MINIMA_PER_SCALE = 5;
 const REFINE_CANDIDATES = 15;
 
 /**
- * The factor a converged full-resolution polish tries its scale up by before it
- * stops — half a coarse scale rung, the resolution the coarse ladder itself had.
+ * The factors a converged full-resolution polish tries its scale up by before it
+ * stops — half a coarse scale rung, the resolution the coarse ladder itself had,
+ * and a quarter of one (issue #886); the better of the two re-fits wins.
  *
  * 🔍 What the pattern search cannot do, and the trace table of issue #877 is
  * how it was seen: every probe moves ONE degree of freedom, and the objective
@@ -306,8 +307,32 @@ const REFINE_CANDIDATES = 15;
  * margin, and the blurred 24 px front shin (walk) now places AT its truth
  * (0.03 px, 0.00989) where it placed 0.57 px off at 0.0191 — the old answer is
  * still reported beside it, 0.0094 above, inside the 0.01 absolute margin.
+ *
+ * 🔍 The quarter rung is issue #886, and the fixed-scale profile is what
+ * named it. MOTION.md §6's post (14x96, pose A, `--scale 0.85,1.2`) came back
+ * at scale 0.917 and residual 0.0649 where the page had recorded 0.975 at
+ * 0.0589 — the old placement still scores 0.0589 on this objective, so the
+ * search missed it. The trace: the coarse cell nearest the truth (2.4 px off
+ * it, at the 2x level) kept a half-turned post, its polish ended 6.7 px from
+ * the truth, the full-resolution rotation re-grid set it upright there, and
+ * the polish climbed the scale–position valley to 0.917.
+ * The half-rung escape then tried 1.029: best position there 0.0980, worse
+ * than 0.0649, so it declined — while the best position at every scale
+ * between 0.94 and 1.00 scores 0.0619–0.0589. A part whose material fills its
+ * image pays for every pixel pushed past the figure, so its profile above the
+ * truth is a cliff, and half a rung stepped over the basin onto it. A quarter
+ * rung lands at 0.971 (0.0593, 0.1 px off the page's placement).
+ *
+ * 📏 Both, not the quarter alone, and measured on the grid rather than argued:
+ * the quarter alone found 234 (3 gained, 6 lost — the native arms #877 was
+ * made for need the half); half then quarter, the quarter tried only when the
+ * half declines, 237 (1, 1); both, the better kept, 238 (2 gained, 1 lost) and
+ * misses 8 → 6, for 16% more user CPU over the grid. The one it loses is a
+ * margin reading of the kind named above: the blurred 32 px front shin (walk)
+ * now reports its truth as its BEST (0.07 px, 0.00968) with the old 0.51 px
+ * answer 0.0045 above it, inside the 0.01 absolute margin.
  */
-const POLISH_SCALE_ESCAPE = 2 ** (1 / (2 * SCALE_STEPS_PER_OCTAVE));
+const POLISH_SCALE_ESCAPES = [2 ** (1 / (4 * SCALE_STEPS_PER_OCTAVE)), 2 ** (1 / (2 * SCALE_STEPS_PER_OCTAVE))];
 
 /** Sample budgets per stage. The reported residual uses every pixel regardless. */
 const COARSE_SAMPLES = 96;
@@ -347,8 +372,8 @@ export const POSE_FLOOR = {
   span: 24,
   detail: 0.5,
   /** Found share of the grid's trials under `detail`, and over it — both measured by `deriveFloor`. */
-  rateBelow: 0.074,
-  rateAbove: 0.765,
+  rateBelow: 0.066,
+  rateAbove: 0.772,
 };
 
 /** Which side of `POSE_FLOOR` a part is on, from its own longest side in part pixels and its detail. */
@@ -681,6 +706,15 @@ export interface PoseTraceLevel {
   out: PoseTraceCandidate[];
   /** This level's objective at `PoseTrace.probe`, when one was given. */
   probeResidual: number | null;
+  /**
+   * At the coarse level only, and `null` on every other (issue #892): the
+   * rotation ladder the coarse field scanned, and per seed the field's own
+   * objective at that seed's anchor cell and scale for every rung of it, in
+   * ladder order — the numbers the field picked the seed's one rotation from.
+   * Computed with the field's arithmetic, so the rung a seed carries reads the
+   * least value of its row.
+   */
+  coarseRotations: { ladder: number[]; residuals: number[][] } | null;
 }
 
 /**
@@ -1064,6 +1098,22 @@ function residualAt(level: Level, plate: Plate, s: Samples, cand: Candidate, smo
  * A per-cell best rather than a global top-K, because the thing this instrument
  * must not lose is the SECOND place a part could sit — and a global top-K fills
  * up with a hundred neighbours of the single best cell before it ever reaches it.
+ *
+ * 📏 ONE rotation per cell, and issue #892 measured what that costs rather than
+ * assuming it. Over `tools/pose_floor.ts`'s 420 trials, the coarse seed nearest
+ * the truth is within 2.4 px of it and a half-turn off on 2 of the 238 found
+ * trials (both a mouth at 48 px, both found anyway) and on none of the 6
+ * misses; every failed trial whose nearest seed is a quarter- or half-turn off
+ * but one is a flat part, and none of those 26 is a miss: each is the objective
+ * preferring another placement or the truth reported and tied. MOTION.md
+ * §6's post is the one case, and a second rotation per cell would not reach it:
+ * at its nearest cell the upright rung scores 0.305 against the half-turn's
+ * 0.168 — 1.8 times, wider than the 1.73 band `REFINE_CANDIDATES` rejected.
+ * The other two levers the card named were measured on the grid and lost found
+ * trials outside the ambiguity margin: re-gridding rotation at this level
+ * rather than the next (238 → 236: 7 gained, 9 lost, six of them native, three
+ * guns now 37–151 px off), and suppressing minima only within a rotation family
+ * (238 → 231: 2 gained, 10 lost, among them the 48 px fist `PO23` holds).
  */
 interface CoarseField {
   residual: Float64Array;
@@ -1140,6 +1190,25 @@ function coarseScan(level: Level, s: Samples, scale: number, rotations: number[]
   return field;
 }
 
+/**
+ * The coarse field's objective at one anchor, scale and rotation, summed in the
+ * order `coarseScan` sums it and without its early exit — the trace's reading of
+ * a cell, never the search's.
+ */
+function coarseCellResidual(level: Level, s: Samples, scale: number, rotDeg: number, ax: number, ay: number): number {
+  if (s.count === 0) return Infinity;
+  const k = scale / level.reduction;
+  const cos = Math.cos(rotDeg * DEG) * k;
+  const sin = Math.sin(rotDeg * DEG) * k;
+  let acc = 0;
+  for (let i = 0; i < s.count; i++) {
+    const dx = s.u[i] * cos - s.v[i] * sin;
+    const dy = s.u[i] * sin + s.v[i] * cos;
+    acc += s.w[i] * errNearest(level, ax + dx, ay + dy, s.r[i], s.g[i], s.b[i]);
+  }
+  return acc / s.weight;
+}
+
 /**
  * The distinct places a part could sit, best first.
  *
@@ -1934,7 +2003,7 @@ function placePart(
     }
     const paths = seeds.map((): { start: number; steps: PoseTraceStep[] } => ({ start: 0, steps: [] }));
     candidates = seeds.map((seed, i) =>
-      polish(level, plate, s, seed, step, floor, smooth, scaleBounds, rotationBounds, li === 0 ? [POLISH_SCALE_ESCAPE] : [], trace === undefined ? undefined : paths[i]),
+      polish(level, plate, s, seed, step, floor, smooth, scaleBounds, rotationBounds, li === 0 ? POLISH_SCALE_ESCAPES : [], trace === undefined ? undefined : paths[i]),
     );
     const polished = candidates.slice();
     candidates.sort((a, b) => a.residual - b.residual);
@@ -1984,6 +2053,15 @@ function placePart(
         polished: polished.map(said),
         out: candidates.map(said),
         probeResidual,
+        coarseRotations:
+          li === coarseIndex
+            ? {
+                ladder: searchRotations.slice(),
+                residuals: seeds.map((seed) =>
+                  searchRotations.map((rotDeg) => coarseCellResidual(level, coarseSamples, seed.scale, rotDeg, seed.cx, seed.cy)),
+                ),
+              }
+            : null,
       });
     }
     if (li > 0) {

package/src/render.ts

@@ -1288,6 +1288,38 @@ function firstNonFinite(where: string, entries: readonly PosedVertices[], bones:
   return null;
 }
 
+/**
+ * The same sentence for one skeleton as it stands posed now — its bones, then
+ * the vertices of every region and mesh its slots show, in draw order — or
+ * `null` when every one of those numbers is finite.
+ *
+ * ⭐ This is how `A10_NO_NAN_AFTER_STEPPING` reads each pose it steps (issue
+ * #882), so the gate and the renderer hold one definition of "not finite": the
+ * six terms `firstNonFinite` reads off a bone, and the vertices the runtime
+ * computes from them. Before it A10 read the world POSITION alone, and a bone at
+ * `rotation: 1e309` — finite position, NaN `a`, `b`, `c`, `d` — was gated green
+ * and then refused here. The vertices are read too because a bone can be finite
+ * and still carry one that is not: a two-bone `scaleX` chain of 1e154 × 1e154
+ * leaves the child's `a` at 1e308, finite, and every vertex of its attachment
+ * past the largest double. Only computed once every bone is finite, so a
+ * broken bone is named as the cause rather than through its vertices.
+ */
+export function nonFiniteOfPosed(where: string, skeleton: Skeleton): string | null {
+  const bones: WorldTransform[] = skeleton.bones.map((bone) => {
+    const { a, b, c, d, worldX, worldY } = bone.appliedPose;
+    return { name: bone.data.name, a, b, c, d, worldX, worldY };
+  });
+  const found = firstNonFinite(where, [], bones);
+  if (found !== null) return found;
+  const entries: PosedVertices[] = [];
+  for (const slot of skeleton.drawOrder.appliedPose) {
+    const attachment = slot.appliedPose.attachment;
+    if (!(attachment instanceof MeshAttachment) && !(attachment instanceof RegionAttachment)) continue;
+    entries.push({ slot: slot.data.name, attachment: attachment.name, vertices: worldVerticesOf(skeleton, slot, attachment) });
+  }
+  return firstNonFinite(where, entries, []);
+}
+
 /**
  * How a sampled frame is named in that sentence: the animation, the frame's
  * index at the rate it was sampled and its time — or the bare index for the one