spine-rigc 1.5.1 → 1.5.3

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.
  *
@@ -159,8 +159,10 @@ export const FLOAT32_MAX = 3.4028234663852886e38;
  * 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 the reader downstream
- * that coerces it is a type question this walk does not answer.
+ * 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.
  */
@@ -202,3 +204,283 @@ export function dottedPath(path: ReadonlyArray<string | number>): string {
   }
   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. Every `enum` row has an entry in the
+ *     shape's enum table (`RIG_ENUMS`, `MOTION_ENUMS`, `MANIFEST_ENUMS`, typed by
+ *     `SpecEnumTable`), which either states the set — and
+ *     `refuseValuesOutsideTheirSet` refuses a value outside it — or names the
+ *     reader that refuses it where it reads it, 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`,
+      );
+    }
+  }
+}
+
+/**
+ * Who refuses a value outside an `enum` row's closed set (issue #900).
+ *
+ *   - `set` — the names the row accepts, refused from one place by
+ *     `refuseValuesOutsideTheirSet`; `readAs` is what the readers did with any
+ *     other value before the set was stated, which the refusal says, because
+ *     "one of" alone does not tell an author that the build they had was wrong;
+ *   - `owner` — the function that reads the value and refuses one outside its
+ *     set by name there, listing the names that exist. It keeps its own sentence,
+ *     which often says more than a set can (a first letter whose case is free, a
+ *     row chosen by the value itself).
+ */
+export type SpecEnumRule = { readonly set: readonly string[]; readonly readAs: string } | { readonly owner: string };
+
+/** The keys of a type row whose type is `enum`. */
+type EnumKeysOf<R> = { [K in keyof R]: R[K] extends 'enum' ? K : never }[keyof R];
+
+/**
+ * A type table's enum table: one entry per `enum` row, and nothing else.
+ *
+ * 🔒 `satisfies SpecEnumTable<typeof X_TYPES>` is what makes a fourth unowned
+ * enum a type error rather than a row nobody holds: a shape with an `enum` row
+ * must appear, with exactly its `enum` keys, and a key of another type cannot.
+ * A selftest control holds the same claim at runtime and reads each `owner`'s
+ * body for the key it is said to own.
+ */
+export type SpecEnumTable<T extends Readonly<Record<string, SpecTypeRow>>> = {
+  readonly [S in keyof T as [EnumKeysOf<T[S]>] extends [never] ? never : S]: { readonly [K in EnumKeysOf<T[S]>]: SpecEnumRule };
+};
+
+/**
+ * Refuse the first value of an `enum` row whose enum table states a set and
+ * that is not in it (issue #900).
+ *
+ * 🚨 The defect this closes was a green build again, one step past #890's:
+ * the type walk does not check `enum` (a name's type says nothing about which
+ * names exist), and three rows had nobody holding the name — `boneIndexing`,
+ * a bone's `from.rotation` and the cut manifest's `mesh.kind`. `"foo"` and `5`
+ * were each read as something the spec never said, in silence.
+ *
+ * It runs after the type walk and over the same visits, so a key the scan
+ * refused is never judged here, and before every reader. A row whose table
+ * entry names an `owner` is passed over: that reader refuses it with its own
+ * sentence. The order is the type walk's — visits in the scan's order, keys in
+ * the document's — so the refusal names the same value on every run.
+ */
+export function refuseValuesOutsideTheirSet(
+  visits: readonly ShapeVisit[],
+  types: Readonly<Record<string, SpecTypeRow>>,
+  enums: Readonly<Record<string, Readonly<Record<string, SpecEnumRule>>>>,
+  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)) {
+      if (row[key] !== 'enum') continue;
+      const rule = enums[visit.shape]?.[key];
+      if (rule === undefined) throw new Error(`${visit.shape}.${key} is an enum row with no entry in its enum table`);
+      if (!('set' in rule)) continue;
+      const value = visit.node[key];
+      if (typeof value === 'string' && rule.set.includes(value)) continue;
+      throw new CompileError(
+        `${where}: ${visit.name([key])} is ${JSON.stringify(value) ?? String(value)}; one of ` +
+          `${rule.set.map((name) => JSON.stringify(name)).join(', ')} — ${rule.readAs}`,
+      );
+    }
+  }
+}

package/src/motion.ts

@@ -54,7 +54,8 @@
  * [`keys.ts`](keys.ts) shared with the rig parser.
  */
 import { CompileError } from './errors.ts';
-import { dottedPath, refuseNumbersTheFileCannotCarry, refuseUnknownKeys } from './keys.ts';
+import { dottedPath, refuseNumbersTheFileCannotCarry, refuseUnknownKeys, refuseValuesOfTheWrongType, refuseValuesOutsideTheirSet } from './keys.ts';
+import type { ShapeVisit, SpecEnumTable, 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,97 @@ 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: an `enum` row — the entry `MOTION_ENUMS`
+ * has for it, below, which is a table a control reads rather than a list here;
+ * `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;
+
+/**
+ * Who refuses each `enum` row of `MOTION_TYPES` outside its set (issue #900);
+ * `SpecEnumTable` in [`keys.ts`](keys.ts) says what an entry means. Every one
+ * is an owner: measured when this table was written, a planted `5` and `"foo"`
+ * on each row was refused by name by the reader named here, listing the names
+ * that exist, so none of them states a set. A deform transform's and a derive's
+ * `kind` choose the row they are checked against, as a generator's does.
+ */
+export const MOTION_ENUMS = {
+  MotionSpec: { spec: { owner: 'parseMotionSpecInto' } },
+  MotionTrack: { property: { owner: 'compileTrack' } },
+  TrackDeriveTurn: { kind: { owner: 'evaluateTrackDerive' } },
+  DeformTurn: { kind: { owner: 'evaluateDeformTransform' } },
+  DeformAffine: { kind: { owner: 'evaluateDeformTransform' } },
+  DeformWave: { kind: { owner: 'evaluateDeformTransform' }, along: { owner: 'evaluateDeformTransform' }, axis: { owner: 'evaluateDeformTransform' } },
+  DeformBend: { kind: { owner: 'evaluateDeformTransform' }, along: { owner: 'evaluateDeformTransform' }, axis: { owner: 'evaluateDeformTransform' } },
+} as const satisfies SpecEnumTable<typeof MOTION_TYPES>;
+
 /** 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 +291,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 +743,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,6 +785,20 @@ 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);
+  // Every `enum` row here names an owner, so this refuses nothing today; it is
+  // called so that a row given a set is refused from the day it is given one.
+  refuseValuesOutsideTheirSet(visits, MOTION_TYPES, MOTION_ENUMS, 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

package/src/pose.ts

@@ -706,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;
 }
 
 /**
@@ -1089,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;
@@ -1165,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.
  *
@@ -2009,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) {