spine-rigc 1.5.1 → 1.5.3

package/src/rig.ts

@@ -60,7 +60,8 @@
  * with no manifest at all declares them here.
  */
 import { CompileError, NotImplementedError } 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';
 
 export { CompileError, NotImplementedError };
 
@@ -1776,11 +1777,11 @@ function isObj(v: unknown): v is Record<string, unknown> {
  * Every key each shape of this format owns, keyed by the interface above that
  * declares it — the runtime shadow of the types, which TypeScript erases.
  *
- * 🔒 **Hand-written and mechanically held to the interfaces.** `KEY01` in
+ * 🔒 **Hand-written and mechanically held to the interfaces.** `CUR17` in
  * `selftest.ts` reads this file's own source, extracts each named interface's
  * field list and compares it to the entry here, so the pair cannot drift: adding
  * a field and forgetting this table is a red run, not a key an author cannot
- * write. `KEY02` closes the other direction — a key declared here and occurring
+ * write. `CUR18` closes the other direction — a key declared here and occurring
  * nowhere else in the tree is refused, which is exactly what `scaleYMode` was.
  *
  * ⚠️ `RigUnimplementedAttachment` is deliberately absent. It carries
@@ -1854,6 +1855,204 @@ export const RIG_KEYS = {
   RigSoftRegion: ['bone', 'mask'],
 } as const satisfies Record<string, readonly string[]>;
 
+/**
+ * The type every key of `RIG_KEYS` holds, shape by shape — what
+ * `refuseValuesOfTheWrongType` refuses a value against (issue #890).
+ *
+ * 🔒 **Beside the key table, and held equal to it twice.** `satisfies` over
+ * `RigTypeTable` makes a key typed here and absent there, or admitted there and
+ * untyped here, a type error; the selftest compares the two at runtime as well,
+ * and derives each checked type from the interface the row is named for, so a
+ * field declared `number` and typed `string` here is a red run rather than a
+ * refusal of correct work.
+ *
+ * Where an unchecked `object` or `mixed` row is refused: a nested shape by the
+ * reader that walks it; `RigSegmentsGenerator.bones` (`mixed`: a name, a chain
+ * of names or a span) by the segments generator, by index. Where an `enum` row
+ * is refused is not a list in prose any more: `RIG_ENUMS`, below, has one entry
+ * per `enum` row — a set refused by `refuseValuesOutsideTheirSet`, or the
+ * reader that refuses it — and `satisfies` makes a row without one a type error.
+ *
+ * ⚠️ Until issue #900 this comment carried that list, and ended by naming three
+ * `enum` keys with **no** owner: `boneIndexing`, `from.rotation` and a
+ * generator `kind`. The list was right about the three and wrong by omission
+ * about a fourth — the cut manifest's `mesh.kind`, which `MANIFEST_TYPES` said
+ * "the manifest mesh reader" held and which that reader read as a ribbon in one
+ * place and a ring in another. A list of owners in a comment is a claim nothing
+ * checks; the table is one a control reads.
+ */
+type RigTypeTable = {
+  readonly [S in keyof typeof RIG_KEYS]: { readonly [K in (typeof RIG_KEYS)[S][number]]: SpecValueType };
+};
+
+export const RIG_TYPES = {
+  RigSpec: {
+    spec: 'enum', name: 'string', note: 'string', skeleton: 'object', images: 'string', bones: 'object[]', slots: 'object[]',
+    skins: 'map of object', constraints: 'object[]', events: 'map of object', invariants: 'object',
+  },
+  RigSkeletonHeader: {
+    x: 'number', y: 'number', width: 'number | null', height: 'number | null', fps: 'number', referenceScale: 'number',
+    images: 'string', audio: 'string | null',
+  },
+  RigBone: {
+    name: 'string', parent: 'string', length: 'number', x: 'number', y: 'number', rotation: 'number', scaleX: 'number',
+    scaleY: 'number', shearX: 'number', shearY: 'number', inherit: 'enum', skin: 'boolean', color: 'string', icon: 'string',
+    from: 'object',
+  },
+  RigBoneFrom: { anchor: 'string', slotWindow: 'string', meshCenter: 'string', rotation: 'enum' },
+  RigSlot: { name: 'string', bone: 'string', attachment: 'string | null', color: 'string', dark: 'string', blend: 'enum' },
+  RigEvent: { int: 'number', float: 'number', string: 'string', audio: 'string', volume: 'number', balance: 'number' },
+  RigInvariants: {
+    meshSlots: 'number', meshTriangles: 'number', axisBone: 'string', massBone: 'string', detached: 'object[]',
+    deformMayFold: 'object[]', editorRoundTrip: 'boolean', consumerDrivenMix: 'object[]', idleDrivesMeshes: 'object',
+  },
+  RigIdleDrivesMeshes: { why: 'string' },
+  RigDetachedRule: { bone: 'string', notUnder: 'string', why: 'string' },
+  RigDeformFoldExemption: { slot: 'string', why: 'string' },
+  RigConsumerDrivenMix: { constraint: 'string', type: 'enum', why: 'string' },
+  RigSkinEntry: {
+    attachments: 'map of object', bones: 'string[]', ik: 'string[]', transform: 'string[]', path: 'string[]',
+    physics: 'string[]', slider: 'string[]',
+  },
+  RigIkConstraint: {
+    name: 'string', skin: 'boolean', type: 'enum', bones: 'string[]', target: 'string', scaleY: 'enum', mix: 'number',
+    softness: 'number', bendPositive: 'boolean', compress: 'boolean', stretch: 'boolean',
+  },
+  RigTransformConstraint: {
+    name: 'string', skin: 'boolean', type: 'enum', bones: 'string[]', source: 'string', localSource: 'boolean',
+    localTarget: 'boolean', additive: 'boolean', clamp: 'boolean', properties: 'map of object',
+    rotation: 'number', x: 'number', y: 'number', scaleX: 'number', scaleY: 'number', shearY: 'number',
+    mixRotate: 'number', mixX: 'number', mixY: 'number', mixScaleX: 'number', mixScaleY: 'number', mixShearY: 'number',
+  },
+  RigPathConstraint: {
+    name: 'string', skin: 'boolean', type: 'enum', bones: 'string[]', slot: 'string', positionMode: 'enum',
+    spacingMode: 'enum', rotateMode: 'enum', rotation: 'number', position: 'number', spacing: 'number',
+    mixRotate: 'number', mixX: 'number', mixY: 'number',
+  },
+  RigPhysicsConstraint: {
+    name: 'string', skin: 'boolean', type: 'enum', bone: 'string', x: 'number', y: 'number', rotate: 'number',
+    scaleX: 'number', shearX: 'number', scaleY: 'enum', limit: 'number', fps: 'number', inertia: 'number',
+    strength: 'number', damping: 'number', mass: 'number', wind: 'number', gravity: 'number', mix: 'number',
+    inertiaGlobal: 'boolean', strengthGlobal: 'boolean', dampingGlobal: 'boolean', massGlobal: 'boolean',
+    windGlobal: 'boolean', gravityGlobal: 'boolean', mixGlobal: 'boolean',
+  },
+  RigSliderConstraint: {
+    name: 'string', skin: 'boolean', type: 'enum', animation: 'string', mix: 'number', additive: 'boolean',
+    loop: 'boolean', bone: 'string', property: 'enum', from: 'number', to: 'number', scale: 'number', max: 'number',
+    local: 'boolean', time: 'number',
+  },
+  RigTransformProperty: { offset: 'number', to: 'map of object' },
+  RigTransformTo: { offset: 'number', max: 'number', scale: 'number' },
+  RigRegionAttachment: {
+    type: 'enum', name: 'string', path: 'string', image: 'string', x: 'number', y: 'number', rotation: 'number',
+    scaleX: 'number', scaleY: 'number', width: 'number', height: 'number', color: 'string', sequence: 'object',
+  },
+  RigMeshAttachment: {
+    type: 'enum', name: 'string', path: 'string', image: 'string', uvs: 'number[]', triangles: 'number[]',
+    vertices: 'number[]', weights: 'object[][]', boneIndexing: 'enum', hull: 'number', edges: 'number[]',
+    width: 'number', height: 'number', color: 'string', generator: 'object', sequence: 'object',
+  },
+  RigLinkedMeshAttachment: {
+    type: 'enum', name: 'string', path: 'string', image: 'string', source: 'string', slot: 'string', skin: 'string',
+    timelines: 'boolean', width: 'number', height: 'number', color: 'string', sequence: 'object',
+    uvs: 'number[]', triangles: 'number[]', vertices: 'number[]', weights: 'object[][]', boneIndexing: 'enum',
+    hull: 'number', edges: 'number[]', generator: 'object',
+  },
+  RigMeshBinding: { bone: 'string', x: 'number', y: 'number', weight: 'number' },
+  RigSequence: { count: 'number', start: 'number', digits: 'number', setup: 'number' },
+  RigBoundingBoxAttachment: {
+    vertexCount: 'number', vertices: 'number[]', weights: 'object[][]', boneIndexing: 'enum', color: 'string', type: 'enum', name: 'string',
+  },
+  RigClippingAttachment: {
+    vertexCount: 'number', vertices: 'number[]', weights: 'object[][]', boneIndexing: 'enum', color: 'string', type: 'enum', name: 'string',
+    end: 'string', convex: 'boolean', inverse: 'boolean',
+  },
+  RigPathAttachment: {
+    vertexCount: 'number', vertices: 'number[]', weights: 'object[][]', boneIndexing: 'enum', color: 'string', type: 'enum', name: 'string',
+    closed: 'boolean', constantSpeed: 'boolean', lengths: 'number[]',
+  },
+  RigRingGenerator: {
+    kind: 'enum', hull: 'number[][]', center: 'number[]', inner: 'number', size: 'number[]', bias: 'object',
+    controls: 'string[]',
+  },
+  RigRibbonGenerator: { kind: 'enum', size: 'number[]', rows: 'number', chain: 'string[]' },
+  RigContourGenerator: {
+    kind: 'enum', tolerance: 'number', margin: 'number', maxVertices: 'number', alpha: 'number', depth: 'object',
+    soft: 'object',
+  },
+  RigGridGenerator: { kind: 'enum', us: 'number[]', vs: 'number[]', cols: 'number', rows: 'number', depth: 'object', soft: 'object' },
+  RigSegmentsGenerator: { kind: 'enum', cell: 'number', bones: 'mixed', falloff: 'object', alpha: 'number', anchor: 'number[]' },
+  RigSegmentsFalloff: { power: 'number', radius: 'number', maxBones: 'number', minWeight: 'number' },
+  RigSegmentSpan: { bone: 'string', from: 'number[]', to: 'number[]' },
+  RigMeshBias: { axis_deg: 'number', ramp: 'number[]' },
+  RigDepthMap: { image: 'string', near: 'enum', zScale: 'number', gamma: 'number', contrast: 'number', bias: 'number' },
+  RigSoftRegion: { bone: 'string', mask: 'string' },
+} as const satisfies RigTypeTable;
+
+/** The two sources a bone's `from.rotation` names (`RigBoneFrom.rotation`). */
+export const RIG_FROM_ROTATIONS = ['axis', 'anchor'] as const satisfies ReadonlyArray<NonNullable<RigBoneFrom['rotation']>>;
+
+/** The two ways a weighted `vertices` run names its bones (`RigMeshAttachment.boneIndexing`). */
+export const RIG_BONE_INDEXING = ['name', 'raw'] as const satisfies ReadonlyArray<NonNullable<RigMeshAttachment['boneIndexing']>>;
+
+/** What `boneIndexing` outside its set was read as, measured before issue #900. */
+const BONE_INDEXING_READ_AS =
+  'anything else was read as the default "name" in silence: a weighted "vertices" run was refused as unflagged, ' +
+  'and every other attachment built byte for byte as if the key were absent';
+
+/**
+ * Who refuses each `enum` row of `RIG_TYPES` outside its set (issue #900) —
+ * `SpecEnumTable` in [`keys.ts`](keys.ts) says what the two kinds of entry
+ * mean, and `satisfies` makes an `enum` row without one a type error.
+ *
+ * ⭐ A `set` is stated for exactly the rows nobody held: measured when this
+ * table was written, `boneIndexing` built green at `5`, `"foo"` and `"named"`
+ * (the spelling the issue itself used) as the default, and `from.rotation`
+ * built green at `5` and `"foo"` with the bone's setup rotation dropped. Every
+ * other row already had a reader that refused a planted `5` and `"foo"` by
+ * name, and keeps it; the generator's `kind` is the one of those that is a
+ * dispatch, and its refusal is new — it threw a `TypeError` (*undefined is not
+ * an object (evaluating 'generator.size')*), because the scan skipped a `kind`
+ * it had no row for and the mesh builder fell through to the ring branch.
+ */
+export const RIG_ENUMS = {
+  RigSpec: { spec: { owner: 'parseRigSpec' } },
+  RigBone: { inherit: { owner: 'parseRigSpec' } },
+  RigBoneFrom: {
+    rotation: {
+      set: RIG_FROM_ROTATIONS,
+      readAs: 'anything else was read as no rotation source, and the bone was emitted without the setup rotation it asked for',
+    },
+  },
+  RigSlot: { blend: { owner: 'parseRigSpec' } },
+  RigConsumerDrivenMix: { type: { owner: 'parseRigSpec' } },
+  RigIkConstraint: { type: { owner: 'buildRigConstraint' }, scaleY: { owner: 'buildRigConstraint' } },
+  RigTransformConstraint: { type: { owner: 'buildRigConstraint' } },
+  RigPathConstraint: {
+    type: { owner: 'buildRigConstraint' },
+    positionMode: { owner: 'buildRigConstraint' },
+    spacingMode: { owner: 'buildRigConstraint' },
+    rotateMode: { owner: 'buildRigConstraint' },
+  },
+  RigPhysicsConstraint: { type: { owner: 'buildRigConstraint' }, scaleY: { owner: 'buildRigConstraint' } },
+  RigSliderConstraint: { type: { owner: 'buildRigConstraint' }, property: { owner: 'buildRigConstraint' } },
+  RigRegionAttachment: { type: { owner: 'buildRigAttachment' } },
+  RigMeshAttachment: { type: { owner: 'buildRigAttachment' }, boneIndexing: { set: RIG_BONE_INDEXING, readAs: BONE_INDEXING_READ_AS } },
+  RigLinkedMeshAttachment: { type: { owner: 'buildRigAttachment' }, boneIndexing: { set: RIG_BONE_INDEXING, readAs: BONE_INDEXING_READ_AS } },
+  RigBoundingBoxAttachment: { type: { owner: 'buildRigAttachment' }, boneIndexing: { set: RIG_BONE_INDEXING, readAs: BONE_INDEXING_READ_AS } },
+  RigClippingAttachment: { type: { owner: 'buildRigAttachment' }, boneIndexing: { set: RIG_BONE_INDEXING, readAs: BONE_INDEXING_READ_AS } },
+  RigPathAttachment: { type: { owner: 'buildRigAttachment' }, boneIndexing: { set: RIG_BONE_INDEXING, readAs: BONE_INDEXING_READ_AS } },
+  // The generator's `kind` chooses the row its other keys are checked against,
+  // so a `kind` outside the five has no row to be visited in: the scan that
+  // dispatches on it is where it is refused.
+  RigRingGenerator: { kind: { owner: 'checkRigSpecKeys' } },
+  RigRibbonGenerator: { kind: { owner: 'checkRigSpecKeys' } },
+  RigContourGenerator: { kind: { owner: 'checkRigSpecKeys' } },
+  RigGridGenerator: { kind: { owner: 'checkRigSpecKeys' } },
+  RigSegmentsGenerator: { kind: { owner: 'checkRigSpecKeys' } },
+  RigDepthMap: { near: { owner: 'sampleMeshDepth' } },
+} as const satisfies SpecEnumTable<typeof RIG_TYPES>;
+
 /**
  * The five constraint `type` names, and the shape each one's keys come from.
  *
@@ -1880,7 +2079,7 @@ const ATTACHMENT_SHAPE: Record<string, keyof typeof RIG_KEYS> = {
 };
 
 /** The generator `kind` names, and the shape each one's keys come from. */
-const GENERATOR_SHAPE: Record<string, keyof typeof RIG_KEYS> = {
+const GENERATOR_SHAPE: Record<(typeof RIG_GENERATOR_KINDS)[number], keyof typeof RIG_KEYS> = {
   ring: 'RigRingGenerator',
   ribbon: 'RigRibbonGenerator',
   contour: 'RigContourGenerator',
@@ -1984,22 +2183,25 @@ function checkRigSequence(att: Record<string, unknown>, who: string, where: stri
  * refusal, and naming its keys would be a second opinion on a fault already
  * reported (see the note at the head of `parseMotionSpec`).
  */
-function checkRigSpecKeys(raw: Record<string, unknown>, where: string): void {
-  const at = (node: unknown, shape: keyof typeof RIG_KEYS, what: string): void => {
-    if (isObj(node)) refuseUnknownKeys(node, RIG_KEYS[shape], where, what);
+function checkRigSpecKeys(raw: Record<string, unknown>, where: string): Array<{ node: Record<string, unknown>; shape: keyof typeof RIG_KEYS; path: Array<string | number> }> {
+  const visits: Array<{ node: Record<string, unknown>; shape: keyof typeof RIG_KEYS; path: Array<string | number> }> = [];
+  const at = (node: unknown, shape: keyof typeof RIG_KEYS, what: string, path: Array<string | number>): void => {
+    if (!isObj(node)) return;
+    refuseUnknownKeys(node, RIG_KEYS[shape], where, what);
+    visits.push({ node, shape, path });
   };
 
-  at(raw, 'RigSpec', 'this rig spec');
-  at(raw.skeleton, 'RigSkeletonHeader', '"skeleton"');
+  at(raw, 'RigSpec', 'this rig spec', []);
+  at(raw.skeleton, 'RigSkeletonHeader', '"skeleton"', ['skeleton']);
 
   for (const [i, bone] of (Array.isArray(raw.bones) ? raw.bones : []).entries()) {
     const who = isObj(bone) && typeof bone.name === 'string' ? `bone "${bone.name}"` : `bones[${i}]`;
-    at(bone, 'RigBone', who);
-    if (isObj(bone)) at(bone.from, 'RigBoneFrom', `${who}'s "from"`);
+    at(bone, 'RigBone', who, ['bones', i]);
+    if (isObj(bone)) at(bone.from, 'RigBoneFrom', `${who}'s "from"`, ['bones', i, 'from']);
   }
 
   for (const [i, slot] of (Array.isArray(raw.slots) ? raw.slots : []).entries()) {
-    at(slot, 'RigSlot', isObj(slot) && typeof slot.name === 'string' ? `slot "${slot.name}"` : `slots[${i}]`);
+    at(slot, 'RigSlot', isObj(slot) && typeof slot.name === 'string' ? `slot "${slot.name}"` : `slots[${i}]`, ['slots', i]);
   }
 
   for (const [i, constraint] of (Array.isArray(raw.constraints) ? raw.constraints : []).entries()) {
@@ -2010,32 +2212,32 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): void {
     // that exist; there is no key set to check it against and no honest one to
     // guess, so it goes past here to the message that can say something.
     if (shape === undefined) continue;
-    at(constraint, shape, `${named} (${String(constraint.type)})`);
+    at(constraint, shape, `${named} (${String(constraint.type)})`, ['constraints', i]);
     for (const [from, entry] of Object.entries(isObj(constraint.properties) ? constraint.properties : {})) {
-      at(entry, 'RigTransformProperty', `${named} properties."${from}"`);
+      at(entry, 'RigTransformProperty', `${named} properties."${from}"`, ['constraints', i, 'properties', from]);
       if (!isObj(entry)) continue;
       for (const [to, driven] of Object.entries(isObj(entry.to) ? entry.to : {})) {
-        at(driven, 'RigTransformTo', `${named} properties."${from}".to."${to}"`);
+        at(driven, 'RigTransformTo', `${named} properties."${from}".to."${to}"`, ['constraints', i, 'properties', from, 'to', to]);
       }
     }
   }
 
   for (const [name, event] of Object.entries(isObj(raw.events) ? raw.events : {})) {
-    at(event, 'RigEvent', `event "${name}"`);
+    at(event, 'RigEvent', `event "${name}"`, ['events', name]);
   }
 
   if (isObj(raw.invariants)) {
-    at(raw.invariants, 'RigInvariants', '"invariants"');
+    at(raw.invariants, 'RigInvariants', '"invariants"', ['invariants']);
     for (const [i, rule] of (Array.isArray(raw.invariants.detached) ? raw.invariants.detached : []).entries()) {
-      at(rule, 'RigDetachedRule', `invariants.detached[${i}]`);
+      at(rule, 'RigDetachedRule', `invariants.detached[${i}]`, ['invariants', 'detached', i]);
     }
     for (const [i, rule] of (Array.isArray(raw.invariants.deformMayFold) ? raw.invariants.deformMayFold : []).entries()) {
-      at(rule, 'RigDeformFoldExemption', `invariants.deformMayFold[${i}]`);
+      at(rule, 'RigDeformFoldExemption', `invariants.deformMayFold[${i}]`, ['invariants', 'deformMayFold', i]);
     }
     for (const [i, rule] of (Array.isArray(raw.invariants.consumerDrivenMix) ? raw.invariants.consumerDrivenMix : []).entries()) {
-      at(rule, 'RigConsumerDrivenMix', `invariants.consumerDrivenMix[${i}]`);
+      at(rule, 'RigConsumerDrivenMix', `invariants.consumerDrivenMix[${i}]`, ['invariants', 'consumerDrivenMix', i]);
     }
-    at(raw.invariants.idleDrivesMeshes, 'RigIdleDrivesMeshes', 'invariants.idleDrivesMeshes');
+    at(raw.invariants.idleDrivesMeshes, 'RigIdleDrivesMeshes', 'invariants.idleDrivesMeshes', ['invariants', 'idleDrivesMeshes']);
   }
 
   for (const [skinName, skin] of Object.entries(isObj(raw.skins) ? raw.skins : {})) {
@@ -2044,6 +2246,10 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): void {
     // likeliest cause (a slot left outside `attachments`), so it is reused
     // rather than restated — one refusal per fault.
     const parts = splitRigSkin(skin as RigSkin, `${where}: skin "${skinName}"`);
+    // The long form's own lists are typed too; `splitRigSkin` has just refused
+    // a key outside them, so the row's keys are the node's keys.
+    if (parts.explicit) visits.push({ node: skin, shape: 'RigSkinEntry', path: ['skins', skinName] });
+    const base: Array<string | number> = parts.explicit ? ['skins', skinName, 'attachments'] : ['skins', skinName];
     for (const [slot, placeholders] of Object.entries(parts.attachments)) {
       if (!isObj(placeholders)) continue;
       for (const [placeholder, att] of Object.entries(placeholders)) {
@@ -2075,33 +2281,46 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): void {
               'series would be dropped in silence. Remove it, or put it on a region or a mesh.',
           );
         }
-        at(att, shape, `${who} (${type})`);
+        const here = [...base, slot, placeholder];
+        at(att, shape, `${who} (${type})`, here);
         if (att.sequence !== undefined) {
-          at(att.sequence, 'RigSequence', `${who} "sequence"`);
+          at(att.sequence, 'RigSequence', `${who} "sequence"`, [...here, 'sequence']);
           checkRigSequence(att, who, where);
         }
         for (const [i, vertex] of (Array.isArray(att.weights) ? att.weights : []).entries()) {
           for (const [j, binding] of (Array.isArray(vertex) ? vertex : []).entries()) {
-            at(binding, 'RigMeshBinding', `${who} weights[${i}][${j}]`);
+            at(binding, 'RigMeshBinding', `${who} weights[${i}][${j}]`, [...here, 'weights', i, j]);
           }
         }
         if (!isObj(att.generator)) continue;
         const gen = att.generator;
-        const genShape = GENERATOR_SHAPE[String(gen.kind)];
-        // Same rule as an unknown attachment type: an unknown `kind` is the mesh
-        // builder's refusal, which can name the four that exist.
-        if (genShape === undefined) continue;
-        at(gen, genShape, `${who} generator (${String(gen.kind)})`);
-        at(gen.bias, 'RigMeshBias', `${who} generator.bias`);
-        at(gen.depth, 'RigDepthMap', `${who} generator.depth`);
-        at(gen.soft, 'RigSoftRegion', `${who} generator.soft`);
-        at(gen.falloff, 'RigSegmentsFalloff', `${who} generator.falloff`);
+        const kind = RIG_GENERATOR_KINDS.find((k) => k === gen.kind);
+        const genShape = kind === undefined ? undefined : GENERATOR_SHAPE[kind];
+        // 🚨 An unknown `kind` used to be skipped here as "the mesh builder's
+        // refusal", and the mesh builder had none: `buildGeneratedMesh` fell
+        // through to the ring branch and threw a TypeError reading
+        // `generator.size` (issue #900). `kind` chooses the row every other key
+        // of the generator is checked against, so this dispatch is the one
+        // place that can refuse it — before any of those keys is judged.
+        if (genShape === undefined) {
+          const stated = gen.kind === undefined ? 'absent' : (JSON.stringify(gen.kind) ?? String(gen.kind));
+          throw new CompileError(
+            `${where}: ${who} generator.kind is ${stated}; one of ${RIG_GENERATOR_KINDS.map((k) => JSON.stringify(k)).join(', ')} — ` +
+              'the kind names the builder, and each builder reads its own keys, so nothing about the mesh can be checked or built without one',
+          );
+        }
+        at(gen, genShape, `${who} generator (${String(gen.kind)})`, [...here, 'generator']);
+        at(gen.bias, 'RigMeshBias', `${who} generator.bias`, [...here, 'generator', 'bias']);
+        at(gen.depth, 'RigDepthMap', `${who} generator.depth`, [...here, 'generator', 'depth']);
+        at(gen.soft, 'RigSoftRegion', `${who} generator.soft`, [...here, 'generator', 'soft']);
+        at(gen.falloff, 'RigSegmentsFalloff', `${who} generator.falloff`, [...here, 'generator', 'falloff']);
         for (const [i, entry] of (Array.isArray(gen.bones) ? gen.bones : []).entries()) {
-          at(entry, 'RigSegmentSpan', `${who} generator.bones[${i}]`);
+          at(entry, 'RigSegmentSpan', `${who} generator.bones[${i}]`, [...here, 'generator', 'bones', i]);
         }
       }
     }
   }
+  return visits;
 }
 
 
@@ -2176,11 +2395,26 @@ export function parseRigSpec(raw: unknown, where: string): RigSpec {
   // compiler does not read" for a format it has never read at all. The three
   // throws directly below are the required-key checks, and each of them is the
   // consequence a typo at the root produces.
-  checkRigSpecKeys(raw, where);
+  const visits = checkRigSpecKeys(raw, where);
+  const place = rigPlace(raw);
+  // Every value the scan admitted, against the type its key holds, before any
+  // reader — here or in `compile` — has done arithmetic on it (issue #890).
+  // ⚠️ It runs ahead of this function's own field checks on purpose: those read
+  // values too, and a reader that meets a wrong type names the wrong fault —
+  // `constraint.skin === true` reads `"skin": "true"` as a constraint that asks
+  // for no skin. The price, measured, is three controls whose type half pinned an
+  // older sentence (RF86, PS177, PS189); their other halves are unchanged.
+  const shapeVisits: ShapeVisit[] = visits.map((v) => ({ node: v.node, shape: v.shape, name: (tail) => place([...v.path, ...tail]) }));
+  refuseValuesOfTheWrongType(shapeVisits, RIG_TYPES, where);
+  // A name outside an `enum` row's stated set (issue #900), after the type walk
+  // and over the same visits: `boneIndexing: "foo"` built as the default and
+  // `from.rotation: "foo"` as no rotation, both green. A row whose entry names
+  // an owner is that reader's to refuse, in its own words.
+  refuseValuesOutsideTheirSet(shapeVisits, RIG_TYPES, RIG_ENUMS, where);
   // After the key check, so a misspelled key is named as a misspelling before
   // its value is judged, and before every reader below, so no range rule or
   // derived number ever meets a value the file cannot carry (issue #881).
-  refuseNumbersTheFileCannotCarry(raw, where, rigPlace(raw));
+  refuseNumbersTheFileCannotCarry(raw, where, place);
 
   if (typeof raw.name !== 'string' || raw.name.length === 0) {
     throw new CompileError(`${where}: a rig spec needs a "name" — a motion spec names it to pick this rig`);

package/src/types.ts

@@ -17,6 +17,7 @@
 import type { AtlasRegion } from './atlas.ts';
 import type { DeformTransform, DeformTransformReport } from './deformgen.ts';
 import type { TurnCeiling } from './depth.ts';
+import type { SpecEnumTable, SpecTypeRow } from './keys.ts';
 import type { MeshKind } from './mesh.ts';
 import type { TrackDerive, TrackDeriveReport } from './trackgen.ts';
 
@@ -169,6 +170,75 @@ export interface FaceManifest {
   anchors?: Record<string, number[]>;
 }
 
+/**
+ * The type every field of the cut manifest holds, shape by shape — what
+ * `refuseValuesOfTheWrongType` refuses a manifest value against (issue #890).
+ * The three interfaces above name three rows; the inline object types they
+ * declare (`crop`, `axis`, `stroke`, `roi`, `mesh.bias`) are rows named
+ * `<interface>.<field>`, and the selftest derives every row's keys and checked
+ * types from the declarations here.
+ *
+ * ⚠️ A manifest has no key scan, and this table does not add one: a manifest is
+ * often also the record of the pipeline that made the art and carries fields
+ * rigc does not read. A key outside a row is left alone, exactly as before; a
+ * key inside one must hold its type. Measured before the walk existed, 62 of 84
+ * wrong-typed plants on the three fixture manifests built green —
+ * `crop.h: "256"` among them — and 4 threw a TypeError from `node:path`.
+ *
+ * Unchecked by this walk: `mesh.kind` and `mesh.hull` (`enum`) — see
+ * `MANIFEST_ENUMS`, below; `crop` and the other nested shapes, `parts` and
+ * `mesh` (`object`) — the readers that walk them.
+ */
+export const MANIFEST_TYPES = {
+  FaceManifest: {
+    schema: 'string', crop: 'object', base: 'string', state_machine: 'map of string[]', parts: 'object[]',
+    insertion: 'number[]', axis: 'object', stroke: 'object', roi: 'object', anchors: 'map of number[]',
+  },
+  'FaceManifest.crop': { x: 'number', y: 'number', w: 'number', h: 'number', resample: 'string' },
+  'FaceManifest.axis': { deg: 'number', unit: 'number[]' },
+  'FaceManifest.stroke': {
+    amplitude: 'number', extension: 'number', contact_depth: 'number | null', cap_containment_ceiling: 'number | null',
+  },
+  'FaceManifest.roi': { x: 'number', y: 'number', w: 'number', h: 'number' },
+  FaceManifestPart: {
+    slot: 'string', rig_slot: 'string', draw_order: 'number', image: 'string | null', offset: 'number[]', size: 'number[]',
+    state_key: 'string', states: 'map of string | null', polygon: 'number[][]', mesh: 'object',
+  },
+  FaceManifestMesh: {
+    kind: 'enum', hull: 'enum', center: 'number[]', inner: 'number', control_bone: 'string', control_bones: 'string[]',
+    rows: 'number', chain: 'string[]', bias: 'object',
+  },
+  'FaceManifestMesh.bias': { axis_deg: 'number', ramp: 'number[]', note: 'string' },
+} as const satisfies Record<string, SpecTypeRow>;
+
+/** The two mesh generators a manifest part may name (`FaceManifestMesh.kind`); absent means `ring`. */
+export const MANIFEST_MESH_KINDS = ['ring', 'ribbon'] as const satisfies ReadonlyArray<NonNullable<FaceManifestMesh['kind']>>;
+
+/**
+ * Who refuses each `enum` row of `MANIFEST_TYPES` outside its set (issue #900);
+ * `SpecEnumTable` in [`keys.ts`](keys.ts) says what an entry means.
+ *
+ * 🚨 `mesh.kind` was listed as held by "the manifest mesh reader", and it was
+ * not held at all: that reader has three places that ask the kind, and they
+ * disagreed about a value outside the two. The mesh checks read `"foo"` as a
+ * ribbon, while the control-bone reader and the geometry builder read it as a
+ * ring — so a ring part was refused as *a ribbon mesh needs mesh.rows and a
+ * mesh.chain*, and a ribbon part as *a mesh with no control bone deforms
+ * nothing*, both naming a fault the part did not have. `hull` is held: the ring
+ * check refuses anything but `"polygon"` by name, and keeps that sentence.
+ */
+export const MANIFEST_ENUMS = {
+  FaceManifestMesh: {
+    kind: {
+      set: MANIFEST_MESH_KINDS,
+      readAs:
+        'anything else was read as a ribbon by the mesh checks and as a ring by the control-bone reader and the ' +
+        'geometry builder, so the refusal it got named a fault the part did not have',
+    },
+    hull: { owner: 'compileInto' },
+  },
+} as const satisfies SpecEnumTable<typeof MANIFEST_TYPES>;
+
 // ---------------------------------------------------------------------------
 // Motion spec  (spec: "rigc-motion/1")
 // ---------------------------------------------------------------------------