rig-c 2.29.0 → 2.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-c",
-  "version": "2.29.0",
+  "version": "2.30.0",
   "description": "AI-authored Spine 2D rigging and animation, verified before it is written. rigc compiles a rig spec into Spine 4.3 skeleton data, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Output imports into the Spine editor. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/mesh.ts

@@ -50,9 +50,11 @@ import type { ModelBinding, ModelVertices } from './model.ts';
 // two form an import cycle: safe only because neither reads the other's
 // bindings while it is being evaluated — every use is inside a function.
 // The reduction (`reduceMesh`, stage B2 of #1224) sits in the same cycle, by
-// the same rule.
+// the same rule. So does the skinning residual and its envelope helper
+// (`src/meshskinning.ts`, issue #1294), which the measurement reads.
 export * from './meshquality.ts';
 export * from './meshreduce.ts';
+export * from './meshskinning.ts';
 
 export interface MeshSpecInput {
   /** Polygon in part-local pixels, y down, in manifest order. */

package/src/meshcarriers.ts

@@ -0,0 +1,93 @@
+/**
+ * Where a UV sample lies in a mesh's UV triangulation — §3 and correction 4 of
+ * docs/MESH_REDUCTION.md, the common domain two triangulations of one
+ * attachment are compared on.
+ *
+ * `uvCarriers` was written for the motion comparison (`src/meshcompare.ts`,
+ * issue #1230), which still re-exports it from `rig-c/meshcompare` where it is
+ * promised. It lives here, in a module that links no poser, because the
+ * skinning residual (`src/meshskinning.ts`, issue #1294) reads the same carriers
+ * from `rig-c/mesh`, which is geometry-only (§0, P1): one definition of "the
+ * triangle that carries this UV" for both, so the residual and the motion row
+ * it is compared with can never disagree about which triangle a sample is in.
+ *
+ * Pure: no clock, no randomness, no runtime.
+ */
+import { MeshReductionError } from './mesh.ts';
+import { areaBand, triangleAreas } from './areaband.ts';
+
+/** `pointInTriangle`'s epsilon in `src/mesh.ts`, applied to each barycentric coordinate. */
+const CONTAINS = 1e-9;
+
+function refuse(code: string, message: string): never {
+  throw new MeshReductionError(code, message);
+}
+
+/** A sample's carrier: the UV triangle that contains it, its three vertex indices and the sample's barycentric coordinates there. */
+export interface Carrier {
+  triangle: number;
+  corners: [number, number, number];
+  bary: [number, number, number];
+}
+
+/**
+ * Each sample's carrier in one mesh's UV triangulation — §3 and correction 4.
+ * Throws `COMPARE_UV_CARRIER_NOT_UNIQUE` for a sample two triangles carry
+ * other than across a vertex or edge they share.
+ */
+export function uvCarriers(uvs: readonly number[], triangles: readonly number[], samples: ReadonlyArray<{ uv: [number, number] }>, who: string): Array<Carrier | null> {
+  const areas = triangleAreas(uvs, triangles);
+  const band = areaBand(areas, uvs);
+  const live: number[] = [];
+  const boxes: number[] = [];
+  for (let t = 0; t < areas.length; t++) {
+    if (Math.abs(areas[t]) <= band) continue;
+    live.push(t);
+    const xs = [uvs[triangles[t * 3] * 2], uvs[triangles[t * 3 + 1] * 2], uvs[triangles[t * 3 + 2] * 2]];
+    const ys = [uvs[triangles[t * 3] * 2 + 1], uvs[triangles[t * 3 + 1] * 2 + 1], uvs[triangles[t * 3 + 2] * 2 + 1]];
+    boxes.push(Math.min(...xs), Math.min(...ys), Math.max(...xs), Math.max(...ys));
+  }
+  return samples.map((s) => {
+    const [px, py] = s.uv;
+    const hits: Carrier[] = [];
+    live.forEach((t, k) => {
+      const slack = 1e-9;
+      if (px < boxes[k * 4] - slack || py < boxes[k * 4 + 1] - slack || px > boxes[k * 4 + 2] + slack || py > boxes[k * 4 + 3] + slack) return;
+      const i0 = triangles[t * 3];
+      const i1 = triangles[t * 3 + 1];
+      const i2 = triangles[t * 3 + 2];
+      const ax = uvs[i0 * 2];
+      const ay = uvs[i0 * 2 + 1];
+      const bx = uvs[i1 * 2] - ax;
+      const by = uvs[i1 * 2 + 1] - ay;
+      const cx = uvs[i2 * 2] - ax;
+      const cy = uvs[i2 * 2 + 1] - ay;
+      const qx = px - ax;
+      const qy = py - ay;
+      const det = bx * cy - cx * by;
+      const l1 = (qx * cy - cx * qy) / det;
+      const l2 = (bx * qy - qx * by) / det;
+      const l0 = 1 - l1 - l2;
+      if (l0 < -CONTAINS || l1 < -CONTAINS || l2 < -CONTAINS) return;
+      hits.push({ triangle: t, corners: [i0, i1, i2], bary: [l0, l1, l2] });
+    });
+    if (hits.length === 0) return null;
+    if (hits.length === 1) return hits[0];
+    // Several carriers are one hit only across a vertex or an edge they all share: the sample's support — the corners
+    // it does not sit at zero weight on — is then the same vertex indices in each, and the carried point is theirs.
+    const support = (c: Carrier): string =>
+      c.corners
+        .filter((_v, k) => c.bary[k] > CONTAINS)
+        .sort((a, b) => a - b)
+        .join(',');
+    const first = support(hits[0]);
+    const shared = first.split(',').length <= 2 && hits.every((c) => support(c) === first);
+    if (!shared) {
+      refuse(
+        'COMPARE_UV_CARRIER_NOT_UNIQUE',
+        `${who}: the sample at uv (${px}, ${py}) lies in ${hits.length} UV triangles — ${hits.map((c) => `triangle ${c.triangle} (vertices ${c.corners.join(', ')})`).join(' and ')} — that do not meet there at a shared vertex or edge; required one carrier per sample (correction 4: overlapping or folded UV triangles would carry it by an arbitrary one)`,
+      );
+    }
+    return hits[0];
+  });
+}

package/src/meshcompare.ts

@@ -100,6 +100,7 @@ import {
   type WorstSample,
 } from './meshquality.ts';
 import { areaBand, stretchSingularValues, triangleAreas } from './areaband.ts';
+import { uvCarriers, type Carrier } from './meshcarriers.ts';
 import { CoreInputError, readModel, underNoSkin, underSkin, type CompiledDocument } from './core/index.ts';
 import { poseRawAnimationEach, poseRawSetup, type RawPose } from './core/raw.ts';
 import { sampleTime } from './core/animation.ts';
@@ -178,9 +179,6 @@ export type ComparePlant = 'amplitude-not-carried' | 'null-read-as-left-out' | '
 // fixed tolerances — the tree's own
 // ---------------------------------------------------------------------------
 
-/** `pointInTriangle`'s epsilon in `src/mesh.ts`, applied to each barycentric coordinate. */
-const CONTAINS = 1e-9;
-
 /** §3 *Independent evidence* (a): the rows a reference is refused on — its art fit against its own mask, and only that. */
 const REFERENCE_ART_FIT: readonly string[] = ['MQ_COVERAGE', 'MQ_OVERSHOOT', 'MQ_UNDERCUT'];
 
@@ -585,6 +583,9 @@ function poseBuild(doc: CompiledDocument, refs: readonly AttachmentRef[], frames
 // §3 — the samples and their carriers
 // ---------------------------------------------------------------------------
 
+/** Promised on `rig-c/meshcompare` since issue #1230; defined in `src/meshcarriers.ts` since issue #1294, which the skinning residual shares. */
+export { uvCarriers };
+
 interface Sample {
   uv: [number, number];
   /** Part-local drawing px, y down — where a region's polygon is read. */
@@ -594,12 +595,6 @@ interface Sample {
   vertex: number | null;
 }
 
-interface Carrier {
-  triangle: number;
-  corners: [number, number, number];
-  bary: [number, number, number];
-}
-
 interface MeshOf {
   uvs: number[];
   triangles: number[];
@@ -607,68 +602,6 @@ interface MeshOf {
   weights: SourceMesh['weights'];
 }
 
-/**
- * Each sample's carrier in one mesh's UV triangulation — §3 and correction 4.
- * Throws `COMPARE_UV_CARRIER_NOT_UNIQUE` for a sample two triangles carry
- * other than across a vertex or edge they share.
- */
-export function uvCarriers(uvs: readonly number[], triangles: readonly number[], samples: ReadonlyArray<{ uv: [number, number] }>, who: string): Array<Carrier | null> {
-  const areas = triangleAreas(uvs, triangles);
-  const band = areaBand(areas, uvs);
-  const live: number[] = [];
-  const boxes: number[] = [];
-  for (let t = 0; t < areas.length; t++) {
-    if (Math.abs(areas[t]) <= band) continue;
-    live.push(t);
-    const xs = [uvs[triangles[t * 3] * 2], uvs[triangles[t * 3 + 1] * 2], uvs[triangles[t * 3 + 2] * 2]];
-    const ys = [uvs[triangles[t * 3] * 2 + 1], uvs[triangles[t * 3 + 1] * 2 + 1], uvs[triangles[t * 3 + 2] * 2 + 1]];
-    boxes.push(Math.min(...xs), Math.min(...ys), Math.max(...xs), Math.max(...ys));
-  }
-  return samples.map((s) => {
-    const [px, py] = s.uv;
-    const hits: Carrier[] = [];
-    live.forEach((t, k) => {
-      const slack = 1e-9;
-      if (px < boxes[k * 4] - slack || py < boxes[k * 4 + 1] - slack || px > boxes[k * 4 + 2] + slack || py > boxes[k * 4 + 3] + slack) return;
-      const i0 = triangles[t * 3];
-      const i1 = triangles[t * 3 + 1];
-      const i2 = triangles[t * 3 + 2];
-      const ax = uvs[i0 * 2];
-      const ay = uvs[i0 * 2 + 1];
-      const bx = uvs[i1 * 2] - ax;
-      const by = uvs[i1 * 2 + 1] - ay;
-      const cx = uvs[i2 * 2] - ax;
-      const cy = uvs[i2 * 2 + 1] - ay;
-      const qx = px - ax;
-      const qy = py - ay;
-      const det = bx * cy - cx * by;
-      const l1 = (qx * cy - cx * qy) / det;
-      const l2 = (bx * qy - qx * by) / det;
-      const l0 = 1 - l1 - l2;
-      if (l0 < -CONTAINS || l1 < -CONTAINS || l2 < -CONTAINS) return;
-      hits.push({ triangle: t, corners: [i0, i1, i2], bary: [l0, l1, l2] });
-    });
-    if (hits.length === 0) return null;
-    if (hits.length === 1) return hits[0];
-    // Several carriers are one hit only across a vertex or an edge they all share: the sample's support — the corners
-    // it does not sit at zero weight on — is then the same vertex indices in each, and the carried point is theirs.
-    const support = (c: Carrier): string =>
-      c.corners
-        .filter((_v, k) => c.bary[k] > CONTAINS)
-        .sort((a, b) => a - b)
-        .join(',');
-    const first = support(hits[0]);
-    const shared = first.split(',').length <= 2 && hits.every((c) => support(c) === first);
-    if (!shared) {
-      refuse(
-        'COMPARE_UV_CARRIER_NOT_UNIQUE',
-        `${who}: the sample at uv (${px}, ${py}) lies in ${hits.length} UV triangles — ${hits.map((c) => `triangle ${c.triangle} (vertices ${c.corners.join(', ')})`).join(' and ')} — that do not meet there at a shared vertex or edge; required one carrier per sample (correction 4: overlapping or folded UV triangles would carry it by an arbitrary one)`,
-      );
-    }
-    return hits[0];
-  });
-}
-
 /** The point a carrier puts the sample at over one pose's world vertices. */
 function carried(c: Carrier, world: readonly number[]): [number, number] {
   const [i0, i1, i2] = c.corners;

package/src/meshquality.ts

@@ -71,6 +71,7 @@ import {
 } from './mesh.ts';
 import { areaBand, triangleAreas } from './areaband.ts';
 import { allocationContrast, boundaryNecessityOnce, deformLoad, gradeMax, minAngleP10, type AllocationArt, type AllocationPlant } from './meshallocation.ts';
+import { skinningEchoOf, skinningResidual, validateSkinning, type SkinningDetail, type SkinningEcho, type SkinningPlant, type SkinningResidualInput } from './meshskinning.ts';
 import { artRastersOf, type ArtRasters, type CoverageReading, type OutlineMemo, type RegionEdgeReading, type SilhouetteReading, type StepRasters } from './meshrasters.ts';
 import { cropToSpineY } from './transform.ts';
 
@@ -369,6 +370,16 @@ export interface MeshMeasureInput {
    * `null` art bound is declared absent, #1257). It declares no bound: every allocation row stays `undeclared`.
    */
   motionAmplitude?: MotionAmplitude | null;
+  /**
+   * Issue #1294 (§7, mechanism 1): the skinning-envelope residual of this mesh — the candidate — against the original
+   * source it was made from, under a declared envelope (`SkinningResidualInput`, `src/meshskinning.ts`). Left out, it
+   * is not asked for: no `MQ_SKINNING_RESIDUAL` row and no echo, so the report is the one written without the field,
+   * byte for byte. `null` declares it absent: the row is `not-measurable` saying so, and the echo is `null`. Set, the
+   * row is measured over §3's samples at `art.threshold` and is required when `maxResidual` is a number; a source or an
+   * envelope the measurement cannot read refuses the row by name. Anything that is not a `SkinningResidualInput` in
+   * full is refused `REDUCE_INPUT_MISSING` naming its path, before any work.
+   */
+  skinning?: SkinningResidualInput | null;
 }
 
 /**
@@ -442,6 +453,8 @@ export interface MeasureRow {
   motion?: MotionRowDetail;
   /** The five allocation rows only (issue #1280): what the value is a reading of, and what it was read from. */
   allocation?: AllocationDetail;
+  /** `MQ_SKINNING_RESIDUAL` when measured (issue #1294): the source, the samples, the worst sample's terms and the contract's own figures. */
+  skinning?: SkinningDetail;
 }
 
 /** Issue #1280: an allocation row's own fields. Written on those five rows, measured or not, and on no other. */
@@ -610,6 +623,8 @@ export interface EffectiveSettings {
   retriangulate?: 'delaunay';
   /** A reduction's `removalOrder`, echoed when the input set it (issue #1283); absent otherwise — the order was ascending source index. */
   removalOrder?: 'deformation-load';
+  /** A measurement's `skinning`, echoed when the input set it — `null` included (issue #1294): the source by id and digest. Absent otherwise. */
+  skinning?: SkinningEcho | null;
 }
 
 export interface MeshCounts {
@@ -863,6 +878,7 @@ function validateInput(input: MeshMeasureInput): void {
     refuse('REDUCE_INPUT_MISSING', `${who}: preset is not { name, version }; required that, or null`);
   }
   validateMotionAmplitude(who, input.motionAmplitude);
+  validateSkinning(who, input.skinning);
 }
 
 /**
@@ -1503,6 +1519,15 @@ export function measureMeshQualityPlanted(input: MeshMeasureInput, plant: Alloca
   return measureValidated(input, artRastersOf(input.art), null, plant);
 }
 
+/**
+ * `measureMeshQuality` with a fault planted in the skinning residual or its report (issue #1294, `SkinningPlant` in
+ * `src/meshskinning.ts`) — the `mesh-compare` suite's negative controls. Internal, as `measureMeshQualityWith` is.
+ */
+export function measureMeshQualitySkinningPlanted(input: MeshMeasureInput, plant: SkinningPlant): MeshQualityReport {
+  validateInput(input);
+  return measureValidated(input, artRastersOf(input.art), null, null, plant);
+}
+
 /**
  * `measureMeshQuality` over art rasters the caller already holds
  * (`src/meshrasters.ts`) — what `reduceMesh` calls for every measurement of
@@ -1612,12 +1637,12 @@ function checkArtRasters(input: MeshMeasureInput, rasters: ArtRasters): void {
 }
 
 /** The measurement proper, over an input `validateInput` accepted and rasters taken from its art. */
-function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: StepRasters | null, plant: AllocationPlant | null): MeshQualityReport {
+function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: StepRasters | null, plant: AllocationPlant | null, skinningPlant: SkinningPlant | null = null): MeshQualityReport {
   rasters.tally.uses++;
   const { attachment, art, source, targets } = input;
   const { mask, threshold, frame } = art;
   const scale = frame.pageScale;
-  const effective = effectiveOf(input);
+  const effective = effectiveOf(input, skinningPlant);
   const report = (sourceCounts: MeshCounts | null, candidate: CandidateReport, termination: Termination | null): MeshQualityReport => ({
     spec: MESH_QUALITY_REPORT_SPEC,
     operation: 'measure',
@@ -1654,6 +1679,9 @@ function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: S
   // --- allocation rows (issue #1280): undeclared or not-measurable, never required ------------
   if (plant !== 'omit-rows') rows.push(...allocationRows(input, outline, rasters, steps, plant));
 
+  // --- the skinning residual (issue #1294): only when the input asked for it ------------------
+  if (input.skinning !== undefined || skinningPlant === 'row-when-unset') rows.push(skinningRow(input, rasters, skinningPlant));
+
   // --- raster rows ---------------------------------------------------------
   const w = mask.width;
   const h = mask.height;
@@ -1805,6 +1833,53 @@ function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: S
   return report(counts, { id: input.id, counts, geometry, motion: null, accepted }, null);
 }
 
+/**
+ * `MQ_SKINNING_RESIDUAL` (issue #1294, `src/meshskinning.ts`): a geometry row in drawing px, required when
+ * `skinning.maxResidual` is a number. `null` for the field reads `not-measurable` saying it was declared absent;
+ * a refusal of the source or the envelope is a `refused` row whose reason opens with its code. The samples are §3's:
+ * art pixel centres at `art.threshold` and the source hull's UVs.
+ */
+function skinningRow(input: MeshMeasureInput, rasters: ArtRasters, plant: SkinningPlant | null): Built {
+  const { attachment, art } = input;
+  const spec: RowSpec = { code: 'MQ_SKINNING_RESIDUAL', unit: 'px', region: null, attachment };
+  const skinning = input.skinning;
+  if (skinning === undefined || skinning === null) {
+    const why =
+      skinning === null
+        ? `attachment ${nameOf(attachment)}: skinning is null — the residual is declared absent, so there is no source or envelope to measure against`
+        : `attachment ${nameOf(attachment)}: skinning was not set`;
+    return unmeasuredRow(spec, 'not-measurable', why, false);
+  }
+  const bound = skinning.maxResidual === null ? null : { op: '<=' as const, value: skinning.maxResidual };
+  const reading = skinningResidual(
+    {
+      attachment,
+      frame: art.frame,
+      artBits: rasters.artBits(),
+      maskWidth: art.mask.width,
+      maskHeight: art.mask.height,
+      minArtSamples: input.minArtSamples,
+      threshold: art.threshold,
+      candidate: input.source,
+      skinning,
+    },
+    plant,
+  );
+  const sampling = { domain: `art pixel centres at alpha >= ${art.threshold} and the source's hull UVs, on the region UV square, carried by the source's and this mesh's UV triangles`, count: reading.samples };
+  const artField = { threshold: art.threshold, connectivity: null, samples: reading.art };
+  if (reading.state !== 'measured') {
+    const built = unmeasuredRow(spec, reading.state, reading.reason, bound !== null);
+    built.row.art = artField;
+    built.row.sampling = sampling;
+    return built;
+  }
+  const built = measuredRow(spec, reading.value, bound, reading.worst, true);
+  built.row.art = artField;
+  built.row.sampling = sampling;
+  built.row.skinning = reading.detail;
+  return built;
+}
+
 /** What each allocation row is a reading of — `AllocationDetail.reading`, one fixed sentence per code. */
 const ALLOCATION_READINGS: Record<string, string> = {
   MQ_GRADE:
@@ -2223,7 +2298,7 @@ function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon:
 // the echo, and the document's text
 // ---------------------------------------------------------------------------
 
-function effectiveOf(input: MeshMeasureInput): EffectiveSettings {
+function effectiveOf(input: MeshMeasureInput, skinningPlant: SkinningPlant | null = null): EffectiveSettings {
   const { art } = input;
   return {
     preset: input.preset,
@@ -2251,6 +2326,7 @@ function effectiveOf(input: MeshMeasureInput): EffectiveSettings {
     schedule: null,
     budget: null,
     ...(input.motionAmplitude === undefined ? {} : { motionAmplitude: input.motionAmplitude }),
+    ...(input.skinning === undefined ? (skinningPlant === 'echo-when-unset' ? { skinning: null } : {}) : { skinning: skinningEchoOf(input.skinning) }),
   };
 }
 
@@ -2344,6 +2420,7 @@ function effectiveJson(e: EffectiveSettings): Json {
     ...(e.motionAmplitude === undefined ? {} : { motionAmplitude: amplitudeJson(e.motionAmplitude) }),
     ...(e.retriangulate === undefined ? {} : { retriangulate: e.retriangulate }),
     ...(e.removalOrder === undefined ? {} : { removalOrder: e.removalOrder }),
+    ...(e.skinning === undefined ? {} : { skinning: skinningEchoJson(e.skinning) }),
   };
 }
 
@@ -2388,9 +2465,40 @@ function rowJson(r: MeasureRow): Json {
   if (r.sampling !== undefined) out.sampling = { domain: r.sampling.domain, count: r.sampling.count };
   if (r.motion !== undefined) out.motion = motionDetailJson(r.motion);
   if (r.allocation !== undefined) out.allocation = allocationDetailJson(r.allocation);
+  if (r.skinning !== undefined) out.skinning = skinningDetailJson(r.skinning);
   return out;
 }
 
+function deformJson(t: DeformTimelineInput): Json {
+  return {
+    animation: t.animation,
+    attachment: attachmentJson(t.attachment),
+    keys: t.keys.map((k): Json => (k.kind === 'vertices' ? { time: k.time, kind: k.kind, offset: k.offset, vertices: [...k.vertices] } : { time: k.time, kind: k.kind })),
+  };
+}
+
+function skinningEchoJson(e: SkinningEcho | null): Json {
+  if (e === null) return null;
+  return {
+    source: { id: e.source.id, digest: e.source.digest },
+    envelope: { reference: e.envelope.reference, bones: e.envelope.bones.map((b) => ({ bone: b.bone, linear: b.linear, pivot: pair(b.pivot), translation: b.translation })) },
+    maxResidual: e.maxResidual,
+    deform: e.deform.map(deformJson),
+  };
+}
+
+function skinningDetailJson(d: SkinningDetail): Json {
+  return {
+    reading: d.reading,
+    source: { id: d.source.id, digest: d.source.digest },
+    reference: d.reference,
+    samples: { measured: d.samples.measured, uncarried: { source: d.samples.uncarried.source.map(pair), candidate: d.samples.uncarried.candidate.map(pair) } },
+    worst: d.worst === null ? null : { covariance: d.worst.covariance, lever: d.worst.lever, bones: d.worst.bones.map((b) => ({ bone: b.bone, covariance: b.covariance, lever: b.lever })) },
+    weightField: { l1: d.weightField.l1, lInf: d.weightField.lInf },
+    setup: { vertexGap: d.setup.vertexGap, vertexSlack: pair(d.setup.vertexSlack), sampleGap: d.setup.sampleGap, weightSumGap: d.setup.weightSumGap },
+  };
+}
+
 function allocationDetailJson(a: AllocationDetail): Json {
   const out: { [key: string]: Json } = { reading: a.reading };
   if (a.contrast !== undefined) {

package/src/meshskinning.ts

@@ -0,0 +1,708 @@
+/**
+ * The skinning-envelope residual — `MQ_SKINNING_RESIDUAL` of
+ * `mesh-quality-report/1` (issue #1294, mechanism 1 of #1266):
+ * docs/MESH_REDUCTION.md §7 derives it and *Mechanism 1 — implemented* says
+ * what it is and what it is not. This module computes it for
+ * `measureMeshQuality` (`src/meshquality.ts`), which turns it into a row, and
+ * holds the helper that turns declared rotation and scale ranges into an
+ * envelope entry (`skinningEnvelopeBone`).
+ *
+ * ## The quantity
+ *
+ * A UV sample of the attachment (§3: every art pixel centre, every source hull
+ * vertex's UV) is carried by one triangle of each mesh — the original source
+ * and the candidate — at barycentric β (`uvCarriers`). In each mesh, per bone
+ * k, the carried point has the interpolated share w̄ₖ = Σᵢ βᵢ wᵢₖ, the setup
+ * position p = Σᵢ βᵢ xᵢ and the weighted position moment
+ * sₖ = Σᵢ βᵢ wᵢₖ (xᵢ − p). For any motion under which bone k's deformation
+ * Dₖ (posed ∘ setup⁻¹, in the drawing frame) differs from the reference bone's
+ * D₀ by a linear part of spectral norm at most εₖ and a lever
+ * |(Dₖ − D₀) q| ≤ εₖ |q − cₖ| + τₖ, the candidate draws the sample within
+ *
+ *   Σₖ εₖ |sₖ(candidate) − sₖ(source)| + Σₖ |w̄ₖ(candidate) − w̄ₖ(source)| (εₖ |p − cₖ| + τₖ)
+ *
+ * of where the source draws it, p the source's setup position — provided each
+ * vertex's shares sum to 1 and both meshes place the sample at the same setup
+ * position. Those two are this measurement's contract, checked rather than
+ * assumed: a vertex whose shares miss 1 by more than half a weight-grid step,
+ * or whose point is off its UV carried through the frame by more than two
+ * `r6` half-steps, refuses the row by name. What the contract still lets
+ * through — the setup positions of one UV in the two meshes differing by
+ * rounding — is reported beside the value (`setup.sampleGap`), never folded
+ * into it: its term is ‖A₀ + Σₖ w̄ₖ (Aₖ − A₀)‖ |Δp|, and ‖A₀‖, the reference
+ * bone's own motion, is not something the envelope declares.
+ *
+ * ## What it never does
+ *
+ * - Pose, link the runtime, or read a frame: the envelope is declared, so the
+ *   value is pose-free and frame-free. It bounds positions under the declared
+ *   motion only — no orientation, stretch or squash, nothing outside the
+ *   envelope — and never replaces `compareMeshesInMotion`.
+ * - Fill a gap. A bone a vertex binds that the envelope does not declare, an
+ *   envelope bone the source does not bind, a deform key that moves vertices
+ *   outside skinning, an unweighted mesh beside a weighted one: each refuses
+ *   the row by name. No sample carried by both meshes, or fewer art samples
+ *   than the floor, is `not-measurable` — never a value of 0.
+ * - Compare against anything but the source it is handed. The reference is
+ *   the original supplied mesh, never a previous candidate.
+ *
+ * Pure: no clock, no randomness, no runtime. Every loop runs in index order,
+ * so one input reads one answer (A18's standard).
+ *
+ * ⚠️ This module imports types only from `src/meshquality.ts`, which imports
+ * it; `src/mesh.ts` re-exports both. As with the other mesh modules, nothing
+ * at the top level reads another module's bindings.
+ */
+import { createHash } from 'node:crypto';
+import { MeshReductionError, r6 } from './mesh.ts';
+import { uvCarriers, type Carrier } from './meshcarriers.ts';
+import type { AttachmentRef, DeformTimelineInput, SourceFrame, SourceMesh, WorstSample } from './meshquality.ts';
+
+type Pt = readonly [number, number];
+
+// ---------------------------------------------------------------------------
+// the input
+// ---------------------------------------------------------------------------
+
+/**
+ * The motion a candidate must stay correct under — declared, never posed. Part-local drawing px, y down (§7, Q3–Q5,
+ * rig-parts#126). Nothing in it has a default.
+ */
+export interface SkinningEnvelope {
+  /** D₀: the bone every other bone's deformation is measured against — the slot's bone (Q4). Its own terms are 0. */
+  reference: string;
+  /** Every bone either mesh binds, other than `reference`, once each. */
+  bones: SkinningEnvelopeBone[];
+}
+
+/** One bone of a `SkinningEnvelope`: the bound on how its deformation differs from the reference's. */
+export interface SkinningEnvelopeBone {
+  bone: string;
+  /**
+   * εₖ ≥ ‖Aₖ − A₀‖₂ over the motion, Aₖ and A₀ the linear parts of the two bones' deformations — dimensionless,
+   * finite, 0 or more. A rotation by up to θ relative to the reference is 2 sin(θ / 2); `skinningEnvelopeBone` derives
+   * it from declared rotation and scale ranges.
+   */
+  linear: number;
+  /** cₖ, drawing px: the pivot of the lever bound |(Dₖ − D₀) q| ≤ εₖ |q − cₖ| + τₖ — usually the bone's setup joint. */
+  pivot: [number, number];
+  /** τₖ, drawing px, 0 or more: the lever bound's constant — how far Dₖ and D₀ carry the pivot apart. */
+  translation: number;
+}
+
+/**
+ * `MeshMeasureInput.skinning` (issue #1294): the source the measured mesh is a candidate of, the envelope, and the
+ * bound. The measured mesh (`MeshMeasureInput.source`) is the candidate; this `source` is the comparison reference.
+ */
+export interface SkinningResidualInput {
+  /**
+   * The original supplied mesh — never a previous candidate — and the caller's id for it. Its sha-256 over the mesh's
+   * own fields is reported beside the id (`SkinningEcho.source.digest`), so a report names the bytes it was measured
+   * against.
+   */
+  source: { id: string; mesh: SourceMesh };
+  envelope: SkinningEnvelope;
+  /** Drawing px: the row's bound, inclusive. `null` declares it absent — the row is measured and `undeclared`. */
+  maxResidual: number | null;
+  /**
+   * Every deform timeline keyed on the attachment or one of its linked meshes, as `MeshReductionInput.deform`; empty
+   * when none. A `vertices` or `transform` key moves vertices outside skinning, so any key but `setup` refuses the row
+   * (`SKINNING_DEFORM_UNSUPPORTED`, Q10).
+   */
+  deform: DeformTimelineInput[];
+}
+
+// ---------------------------------------------------------------------------
+// the report's fields
+// ---------------------------------------------------------------------------
+
+/** What `effective.skinning` echoes: the source by id and digest rather than in full, the envelope, the bound and the deform list. */
+export interface SkinningEcho {
+  source: { id: string; digest: string };
+  envelope: SkinningEnvelope;
+  maxResidual: number | null;
+  deform: DeformTimelineInput[];
+}
+
+/** `MeasureRow.skinning`: written on `MQ_SKINNING_RESIDUAL` when it was measured, and on no other row. */
+export interface SkinningDetail {
+  /** One fixed sentence: what the value is a reading of, and what it is not. */
+  reading: string;
+  /** The comparison reference: the caller's id and the sha-256 of its mesh. */
+  source: { id: string; digest: string };
+  /** The envelope's reference bone. */
+  reference: string;
+  /** Samples carried by both meshes — the ones the value is the largest over — and every sample one mesh does not carry, by UV. */
+  samples: { measured: number; uncarried: { source: Array<[number, number]>; candidate: Array<[number, number]> } };
+  /**
+   * At the worst sample: the value's two sums — `covariance`, Σₖ εₖ |Δsₖ|, and `lever`, Σₖ |Δw̄ₖ| (εₖ |p − cₖ| + τₖ) —
+   * and each envelope bone's share of each, in envelope order. Null when the value is 0 (nothing worse than ideal).
+   */
+  worst: { covariance: number; lever: number; bones: Array<{ bone: string; covariance: number; lever: number }> } | null;
+  /**
+   * The weight-field difference alone, over every bone the envelope names and its reference — the largest over
+   * samples of Σ |Δw̄| (`l1`) and of max |Δw̄| (`lInf`). A diagnostic: it reads 0 wherever the two fields agree, as
+   * on a linear ramp, however far the meshes draw apart, so it is never a guard (§7, M2).
+   */
+  weightField: { l1: number; lInf: number };
+  /**
+   * The contract's own figures: `vertexGap`, the largest distance of any vertex of either mesh from its UV carried
+   * through the frame, against `vertexSlack` per axis; `sampleGap`, the largest |p(candidate) − p(source)| over the
+   * measured samples — the term outside the value; `weightSumGap`, the largest |Σ shares − 1| of any vertex.
+   */
+  setup: { vertexGap: number; vertexSlack: [number, number]; sampleGap: number; weightSumGap: number };
+}
+
+/** The fixed sentence of `SkinningDetail.reading`. */
+export const SKINNING_READING =
+  'the largest over the samples carried by both meshes of Σk εk·|Δsk| + Σk |Δw̄k|·(εk·|p − ck| + τk): a bound, under the declared envelope only, on how far the candidate draws a UV from where the source draws it — positions only; it certifies no orientation, stretch or squash, no motion outside the envelope, and replaces no motion comparison (docs/MESH_REDUCTION.md §7)';
+
+// ---------------------------------------------------------------------------
+// plants
+// ---------------------------------------------------------------------------
+
+/**
+ * A fault planted on purpose, for the `mesh-compare` suite's negative controls (MQ116 onward). `measureMeshQuality`
+ * plants none.
+ *
+ * - `drop-covariance`: the first sum left out — the weight-field bound the card proposed first.
+ * - `drop-lever`: the second sum left out.
+ * - `uncarried-read-as-zero`: no sample carried by both meshes read as a value of 0 rather than not measurable.
+ * - `undeclared-bone-ignored`: a bound bone the envelope does not declare read as contributing nothing.
+ * - `unknown-bone-accepted`: an envelope bone the source does not bind accepted.
+ * - `setup-unchecked`: a vertex off its UV accepted.
+ * - `deform-unchecked`: a `vertices` or `transform` deform key accepted.
+ * - `echo-when-unset`, `row-when-unset`: the report writes the echo, or the row, for a call that did not set the field.
+ */
+export type SkinningPlant =
+  | 'drop-covariance'
+  | 'drop-lever'
+  | 'uncarried-read-as-zero'
+  | 'undeclared-bone-ignored'
+  | 'unknown-bone-accepted'
+  | 'setup-unchecked'
+  | 'deform-unchecked'
+  | 'echo-when-unset'
+  | 'row-when-unset';
+
+// ---------------------------------------------------------------------------
+// refusals of the declaration's shape — thrown before any work
+// ---------------------------------------------------------------------------
+
+function refuse(code: string, message: string): never {
+  throw new MeshReductionError(code, message);
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+/** A value as a message names it: JSON, except a non-finite number, which JSON would print as null. */
+function shown(value: unknown): string {
+  return typeof value === 'number' ? String(value) : JSON.stringify(value);
+}
+
+function isPoint(value: unknown): value is [number, number] {
+  return Array.isArray(value) && value.length === 2 && isFiniteNumber(value[0]) && isFiniteNumber(value[1]);
+}
+
+/**
+ * `MeshMeasureInput.skinning`: left out or `null` is accepted as it stands; anything else is a `SkinningResidualInput`
+ * in full, else refused `REDUCE_INPUT_MISSING` naming the path. Internal: on `rig-c/mesh` only through `export *`.
+ */
+export function validateSkinning(who: string, skinning: unknown): void {
+  if (skinning === undefined || skinning === null) return;
+  const shape = '{ source: { id, mesh }, envelope: { reference, bones }, maxResidual, deform }';
+  if (!isObject(skinning)) refuse('REDUCE_INPUT_MISSING', `${who}: skinning is ${shown(skinning)}; required ${shape}, null, or the field left out`);
+  const source = skinning.source;
+  if (!isObject(source)) refuse('REDUCE_INPUT_MISSING', `${who}: skinning.source is ${shown(source)}; required { id, mesh } — the original supplied mesh and the caller's id for it`);
+  if (typeof source.id !== 'string' || source.id === '') refuse('REDUCE_INPUT_MISSING', `${who}: skinning.source.id is ${shown(source.id)}; required a non-empty string naming the source`);
+  const mesh = source.mesh;
+  if (!isObject(mesh) || !Array.isArray(mesh.points) || !Array.isArray(mesh.uvs) || !Array.isArray(mesh.triangles)) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: skinning.source.mesh is not { points, uvs, triangles, hull, weights } with three arrays; required a SourceMesh`);
+  }
+  mesh.points.forEach((p: unknown, i: number) => {
+    if (!isPoint(p)) refuse('REDUCE_INPUT_MISSING', `${who}: skinning.source.mesh.points[${i}] is ${shown(p)}; required a pair of finite numbers`);
+  });
+  if (mesh.uvs.length !== 2 * mesh.points.length || mesh.uvs.some((u: unknown) => !isFiniteNumber(u))) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: skinning.source.mesh.uvs holds ${mesh.uvs.length} numbers for ${mesh.points.length} points; required one finite u, v pair per point (${2 * mesh.points.length})`);
+  }
+  const vertexCount = mesh.points.length;
+  if (mesh.triangles.length % 3 !== 0 || mesh.triangles.some((t: unknown) => !Number.isInteger(t) || (t as number) < 0 || (t as number) >= vertexCount)) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: skinning.source.mesh.triangles is not a list of vertex index triples into ${mesh.points.length} points; required that`);
+  }
+  if (!Number.isInteger(mesh.hull) || (mesh.hull as number) < 3 || (mesh.hull as number) > mesh.points.length) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: skinning.source.mesh.hull is ${shown(mesh.hull)}; required the whole number of hull vertices, 3 to ${mesh.points.length}`);
+  }
+  if (mesh.weights !== null) {
+    if (!Array.isArray(mesh.weights) || mesh.weights.length !== mesh.points.length) {
+      refuse('REDUCE_INPUT_MISSING', `${who}: skinning.source.mesh.weights is not one binding list per point (${mesh.points.length}); required that, or null for an unweighted mesh`);
+    }
+    mesh.weights.forEach((vertex: unknown, i: number) => {
+      if (!Array.isArray(vertex) || vertex.some((b) => !isObject(b) || typeof b.bone !== 'string' || !isFiniteNumber(b.weight) || b.weight < 0)) {
+        refuse('REDUCE_INPUT_MISSING', `${who}: skinning.source.mesh.weights[${i}] is not a list of { bone, weight } with finite shares, 0 or more; required that`);
+      }
+    });
+  }
+  const envelope = skinning.envelope;
+  if (!isObject(envelope) || !Array.isArray(envelope.bones)) refuse('REDUCE_INPUT_MISSING', `${who}: skinning.envelope is ${shown(envelope)}; required { reference, bones: [{ bone, linear, pivot, translation }] }`);
+  if (typeof envelope.reference !== 'string' || envelope.reference === '') refuse('REDUCE_INPUT_MISSING', `${who}: skinning.envelope.reference is ${shown(envelope.reference)}; required a non-empty bone name — the slot's bone (Q4)`);
+  const seen = new Set<string>();
+  envelope.bones.forEach((entry: unknown, i: number) => {
+    const at = `skinning.envelope.bones[${i}]`;
+    if (!isObject(entry) || typeof entry.bone !== 'string' || entry.bone === '') refuse('REDUCE_INPUT_MISSING', `${who}: ${at} is ${shown(entry)}; required { bone: a non-empty name, linear, pivot, translation }`);
+    if (entry.bone === envelope.reference) refuse('REDUCE_INPUT_MISSING', `${who}: ${at}.bone is "${entry.bone}", the envelope's reference; required every bone but the reference — the reference's own terms are 0 by definition`);
+    if (seen.has(entry.bone)) refuse('REDUCE_INPUT_MISSING', `${who}: ${at}.bone "${entry.bone}" is declared twice; required one entry per bone`);
+    seen.add(entry.bone);
+    if (!isFiniteNumber(entry.linear) || entry.linear < 0) refuse('REDUCE_INPUT_MISSING', `${who}: ${at}.linear is ${shown(entry.linear)}; required a finite number, 0 or more (εk ≥ ‖Ak − A0‖, dimensionless)`);
+    if (!isPoint(entry.pivot)) refuse('REDUCE_INPUT_MISSING', `${who}: ${at}.pivot is ${shown(entry.pivot)}; required a pair of finite drawing px`);
+    if (!isFiniteNumber(entry.translation) || entry.translation < 0) refuse('REDUCE_INPUT_MISSING', `${who}: ${at}.translation is ${shown(entry.translation)}; required a finite number of drawing px, 0 or more`);
+  });
+  const bound = skinning.maxResidual;
+  if (bound === undefined) refuse('REDUCE_INPUT_MISSING', `${who}: skinning.maxResidual is missing; required a finite number of drawing px, 0 or more, or null (declared absent: measured, reported undeclared) — no field has a default`);
+  if (bound !== null && (!isFiniteNumber(bound) || bound < 0)) refuse('REDUCE_INPUT_MISSING', `${who}: skinning.maxResidual is ${shown(bound)}; required a finite number of drawing px, 0 or more, or null`);
+  const deform = skinning.deform;
+  if (!Array.isArray(deform)) refuse('REDUCE_INPUT_MISSING', `${who}: skinning.deform is ${shown(deform)}; required the deform timelines keyed on the attachment or its linked meshes (empty when none)`);
+  deform.forEach((t: unknown, i: number) => {
+    if (!isObject(t) || typeof t.animation !== 'string' || !isObject(t.attachment) || !Array.isArray(t.keys) || t.keys.some((k: unknown) => !isObject(k) || typeof k.kind !== 'string')) {
+      refuse('REDUCE_INPUT_MISSING', `${who}: skinning.deform[${i}] is not { animation, attachment, keys: [{ time, kind }] }; required a DeformTimelineInput`);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// the source's identity
+// ---------------------------------------------------------------------------
+
+/** `sha256:<hex>` of the mesh's own fields, written in a fixed key order — the same bytes for the same mesh, whatever order its objects were built in. */
+export function sourceMeshDigest(mesh: SourceMesh): string {
+  const canonical = JSON.stringify({
+    points: mesh.points.map((p) => [p[0], p[1]]),
+    uvs: [...mesh.uvs],
+    triangles: [...mesh.triangles],
+    hull: mesh.hull,
+    weights: mesh.weights === null ? null : mesh.weights.map((v) => v.map((b) => ({ bone: b.bone, weight: b.weight }))),
+  });
+  return `sha256:${createHash('sha256').update(canonical).digest('hex')}`;
+}
+
+/** The echo `effective.skinning` writes. */
+export function skinningEchoOf(skinning: SkinningResidualInput | null): SkinningEcho | null {
+  if (skinning === null) return null;
+  return { source: { id: skinning.source.id, digest: sourceMeshDigest(skinning.source.mesh) }, envelope: skinning.envelope, maxResidual: skinning.maxResidual, deform: skinning.deform };
+}
+
+// ---------------------------------------------------------------------------
+// the samples and their terms
+// ---------------------------------------------------------------------------
+
+/** One §3 sample: its UV, and the art pixel (mask grid) or source hull vertex it is. */
+export interface SkinningSample {
+  uv: [number, number];
+  pixel: [number, number] | null;
+  vertex: number | null;
+}
+
+/** One mesh's terms at one sample: p, and per bone (envelope order, then the reference last) w̄ and s. */
+export interface SampleTerms {
+  p: [number, number];
+  wbar: number[];
+  moment: Array<[number, number]>;
+}
+
+/** §3's sample set over art bits at the threshold: every art pixel centre in row order, then the source hull's UVs. */
+export function skinningSamplesOf(artBits: Uint8Array, width: number, height: number, source: SourceMesh): { samples: SkinningSample[]; art: number } {
+  const samples: SkinningSample[] = [];
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      if (artBits[y * width + x]) samples.push({ uv: [(x + 0.5) / width, (y + 0.5) / height], pixel: [x, y], vertex: null });
+    }
+  }
+  const art = samples.length;
+  for (let v = 0; v < source.hull; v++) samples.push({ uv: [source.uvs[v * 2], source.uvs[v * 2 + 1]], pixel: null, vertex: v });
+  return { samples, art };
+}
+
+/**
+ * A mesh's terms at a carrier — p, and per bone w̄ and the moment s = Σᵢ βᵢ wᵢₖ (xᵢ − p) — over `bones` (index by name).
+ * Shares of a bone `bones` does not name are not read: the coverage check refuses such a mesh before this runs.
+ */
+export function termsAt(mesh: SourceMesh, c: Carrier, bones: ReadonlyMap<string, number>): SampleTerms {
+  const n = bones.size;
+  const wbar = new Array<number>(n).fill(0);
+  const moment: Array<[number, number]> = Array.from({ length: n }, () => [0, 0]);
+  let px = 0;
+  let py = 0;
+  for (let k = 0; k < 3; k++) {
+    const pt = mesh.points[c.corners[k]];
+    px += c.bary[k] * pt[0];
+    py += c.bary[k] * pt[1];
+  }
+  for (let k = 0; k < 3; k++) {
+    const v = c.corners[k];
+    const b = c.bary[k];
+    const pt = mesh.points[v];
+    const dx = pt[0] - px;
+    const dy = pt[1] - py;
+    for (const bind of mesh.weights![v]) {
+      const j = bones.get(bind.bone);
+      if (j === undefined) continue;
+      wbar[j] += b * bind.weight;
+      moment[j][0] += b * bind.weight * dx;
+      moment[j][1] += b * bind.weight * dy;
+    }
+  }
+  return { p: [px, py], wbar, moment };
+}
+
+// ---------------------------------------------------------------------------
+// the measurement
+// ---------------------------------------------------------------------------
+
+/** What `measureMeshQuality` hands the residual: the candidate (the mesh measured), the field, and the art read at the measurement's threshold. */
+export interface SkinningMeasureArgs {
+  attachment: AttachmentRef;
+  frame: SourceFrame;
+  /** Art bits on the mask grid at the measurement's threshold, and the grid's size. */
+  artBits: Uint8Array;
+  maskWidth: number;
+  maskHeight: number;
+  minArtSamples: number;
+  threshold: number;
+  candidate: SourceMesh;
+  skinning: SkinningResidualInput;
+}
+
+/** The residual's reading, which the row is built from. */
+export type SkinningReading =
+  | { state: 'measured'; value: number; worst: WorstSample; detail: SkinningDetail; samples: number; art: number }
+  | { state: 'refused' | 'not-measurable'; reason: string; samples: number; art: number };
+
+/** Half a step of the 6-decimal weight grid the bindings are written on (§6, P19): a vertex's shares further from 1 are not closed. */
+const WEIGHT_SUM_SLACK = 5e-7;
+
+/** One `r6` half-step, of a point or of a UV (its error carried through the frame is that times the frame's size). */
+const R6_HALF_STEP = 5e-7;
+
+function nameOf(ref: AttachmentRef): string {
+  return `${ref.skin ?? '(no skin)'}/${ref.slot}/${ref.attachment}`;
+}
+
+/**
+ * The residual over the §3 sample set, or the reason it is refused or not measurable — the order of the checks is
+ * the order a fix has to happen in: what the motion is, which bones bind, the shares, the setup positions, the
+ * samples. Internal: on `rig-c/mesh` only through `export *`.
+ */
+export function skinningResidual(args: SkinningMeasureArgs, plant: SkinningPlant | null = null): SkinningReading {
+  const { attachment, frame, candidate, skinning } = args;
+  const source = skinning.source.mesh;
+  const envelope = skinning.envelope;
+  const who = `attachment ${nameOf(attachment)}`;
+  const { samples, art } = skinningSamplesOf(args.artBits, args.maskWidth, args.maskHeight, source);
+  const out = (state: 'refused' | 'not-measurable', reason: string): SkinningReading => ({ state, reason, samples: samples.length, art });
+
+  // What moves the vertices: skinning alone, or a deform key besides it.
+  if (plant !== 'deform-unchecked') {
+    for (const t of skinning.deform) {
+      const k = t.keys.findIndex((key) => key.kind !== 'setup');
+      if (k >= 0) {
+        return out(
+          'refused',
+          `SKINNING_DEFORM_UNSUPPORTED: ${who}: skinning.deform names animation "${t.animation}" keyed on ${nameOf(t.attachment)}, whose key ${k} is a "${t.keys[k].kind}" key; required setup keys only — a vertices or transform deform moves vertices outside skinning, which the envelope does not bound (Q10)`,
+        );
+      }
+    }
+  }
+
+  // Which bones bind, and that the envelope declares every one of them.
+  if (source.weights === null || candidate.weights === null) {
+    if (source.weights === null && candidate.weights === null) {
+      return out('not-measurable', `${who}: neither the source "${skinning.source.id}" nor the candidate is weighted, so no vertex has a binding to compare — an unweighted mesh follows its slot's bone, which no envelope entry describes`);
+    }
+    return out('refused', `SKINNING_UNWEIGHTED: ${who}: the ${source.weights === null ? `source "${skinning.source.id}"` : 'candidate'} is unweighted and the ${source.weights === null ? 'candidate' : 'source'} is weighted; required both weighted — the residual compares two bindings of one attachment`);
+  }
+  const declared = new Set(envelope.bones.map((b) => b.bone));
+  const bound = new Set<string>();
+  for (const [label, mesh] of [[`source "${skinning.source.id}"`, source], ['candidate', candidate]] as const) {
+    for (let v = 0; v < mesh.weights!.length; v++) {
+      for (const b of mesh.weights![v]) {
+        if (label !== 'candidate') bound.add(b.bone);
+        if (b.bone === envelope.reference || declared.has(b.bone) || plant === 'undeclared-bone-ignored') continue;
+        return out(
+          'refused',
+          `SKINNING_BONE_NOT_DECLARED: ${who}: ${label} vertex ${v} binds bone "${b.bone}", which skinning.envelope neither declares nor names as its reference "${envelope.reference}"; required an envelope entry for every bone either mesh binds — an undeclared bone's motion is unbounded`,
+        );
+      }
+    }
+  }
+  if (plant !== 'unknown-bone-accepted') {
+    const i = envelope.bones.findIndex((b) => !bound.has(b.bone));
+    if (i >= 0) {
+      return out(
+        'refused',
+        `SKINNING_BONE_UNKNOWN: ${who}: skinning.envelope.bones[${i}] declares bone "${envelope.bones[i].bone}", which no vertex of the source "${skinning.source.id}" binds; required envelope bones the source binds — the source binds ${[...bound].sort().map((b) => `"${b}"`).join(', ')}`,
+      );
+    }
+  }
+
+  // The shares: each vertex's sum is 1 on the weight grid, or the reference bone's motion would enter the difference.
+  let weightSumGap = 0;
+  for (const [label, mesh] of [[`source "${skinning.source.id}"`, source], ['candidate', candidate]] as const) {
+    for (let v = 0; v < mesh.weights!.length; v++) {
+      const sum = mesh.weights![v].reduce((s, b) => s + b.weight, 0);
+      const gap = Math.abs(sum - 1);
+      weightSumGap = Math.max(weightSumGap, gap);
+      if (gap > WEIGHT_SUM_SLACK) {
+        return out(
+          'refused',
+          `SKINNING_WEIGHT_SUM: ${who}: ${label} vertex ${v}'s shares sum to ${sum}; required 1 within ${WEIGHT_SUM_SLACK} (half a step of the 6-decimal weight grid) — a deficit moves the vertex with the reference bone's own motion, which the envelope does not bound`,
+        );
+      }
+    }
+  }
+
+  // The setup positions: every vertex of either mesh at its UV carried through the frame, so one UV is one setup point.
+  const slack: [number, number] = [2 * R6_HALF_STEP * (1 + frame.width), 2 * R6_HALF_STEP * (1 + frame.height)];
+  let vertexGap = 0;
+  for (const [label, mesh] of [[`source "${skinning.source.id}"`, source], ['candidate', candidate]] as const) {
+    for (let v = 0; v < mesh.points.length; v++) {
+      const dx = Math.abs(mesh.points[v][0] - mesh.uvs[v * 2] * frame.width);
+      const dy = Math.abs(mesh.points[v][1] - mesh.uvs[v * 2 + 1] * frame.height);
+      vertexGap = Math.max(vertexGap, Math.hypot(dx, dy));
+      if ((dx > slack[0] || dy > slack[1]) && plant !== 'setup-unchecked') {
+        return out(
+          'refused',
+          `SKINNING_SETUP_MISMATCH: ${who}: ${label} vertex ${v} is at (${mesh.points[v][0]}, ${mesh.points[v][1]}) and its UV (${mesh.uvs[v * 2]}, ${mesh.uvs[v * 2 + 1]}) carried through the ${frame.width}x${frame.height} px frame is at (${r6(mesh.uvs[v * 2] * frame.width)}, ${r6(mesh.uvs[v * 2 + 1] * frame.height)}); required within (${slack[0]}, ${slack[1]}) px per axis (two r6 half-steps, of the point and of the UV) — both meshes have to place one UV at one setup position`,
+        );
+      }
+    }
+  }
+
+  // The samples: under the floor is not a measurement.
+  if (art < args.minArtSamples) {
+    return out('not-measurable', `${who} has ${art} art sample(s) at alpha >= ${args.threshold}; required at least ${args.minArtSamples} (minArtSamples, P9) — the source hull's UVs are samples and do not count towards it`);
+  }
+  let sourceCarriers: Array<Carrier | null>;
+  let candidateCarriers: Array<Carrier | null>;
+  try {
+    sourceCarriers = uvCarriers(source.uvs, source.triangles, samples, `source "${skinning.source.id}", attachment ${nameOf(attachment)}`);
+    candidateCarriers = uvCarriers(candidate.uvs, candidate.triangles, samples, `candidate, attachment ${nameOf(attachment)}`);
+  } catch (err) {
+    if (err instanceof MeshReductionError && err.code === 'COMPARE_UV_CARRIER_NOT_UNIQUE') return out('refused', `SKINNING_UV_CARRIER_NOT_UNIQUE: ${err.message}`);
+    throw err;
+  }
+
+  // The bones in envelope order, the reference last (its εk and τk are 0, so it enters only the weight-field diagnostic).
+  const index = new Map<string, number>();
+  envelope.bones.forEach((b, i) => index.set(b.bone, i));
+  index.set(envelope.reference, envelope.bones.length);
+  const eps = [...envelope.bones.map((b) => b.linear), 0];
+  const tau = [...envelope.bones.map((b) => b.translation), 0];
+  const pivot: Pt[] = [...envelope.bones.map((b) => b.pivot), [0, 0]];
+  const K = eps.length;
+
+  const uncarried = {
+    source: samples.filter((_s, j) => sourceCarriers[j] === null).map((s) => s.uv),
+    candidate: samples.filter((_s, j) => candidateCarriers[j] === null).map((s) => s.uv),
+  };
+  let measured = 0;
+  let worst = -1;
+  let worstAt = -1;
+  let worstCov: number[] = [];
+  let worstLev: number[] = [];
+  let l1Max = 0;
+  let lInfMax = 0;
+  let sampleGap = 0;
+  for (let j = 0; j < samples.length; j++) {
+    const cs = sourceCarriers[j];
+    const cc = candidateCarriers[j];
+    if (cs === null || cc === null) continue;
+    measured++;
+    const r = termsAt(source, cs, index);
+    const c = termsAt(candidate, cc, index);
+    sampleGap = Math.max(sampleGap, Math.hypot(c.p[0] - r.p[0], c.p[1] - r.p[1]));
+    let total = 0;
+    let l1 = 0;
+    let lInf = 0;
+    const cov = new Array<number>(K).fill(0);
+    const lev = new Array<number>(K).fill(0);
+    for (let k = 0; k < K; k++) {
+      const dw = Math.abs(c.wbar[k] - r.wbar[k]);
+      l1 += dw;
+      lInf = Math.max(lInf, dw);
+      if (plant !== 'drop-covariance') cov[k] = eps[k] * Math.hypot(c.moment[k][0] - r.moment[k][0], c.moment[k][1] - r.moment[k][1]);
+      if (plant !== 'drop-lever') lev[k] = dw * (eps[k] * Math.hypot(r.p[0] - pivot[k][0], r.p[1] - pivot[k][1]) + tau[k]);
+      total += cov[k] + lev[k];
+    }
+    l1Max = Math.max(l1Max, l1);
+    lInfMax = Math.max(lInfMax, lInf);
+    if (total > worst) {
+      worst = total;
+      worstAt = j;
+      worstCov = cov;
+      worstLev = lev;
+    }
+  }
+  if (measured === 0 && plant !== 'uncarried-read-as-zero') {
+    return out('not-measurable', `${who}: no sample is carried by both the source "${skinning.source.id}"'s and the candidate's UV triangles, so there is nothing to bound — ${uncarried.source.length} uncarried by the source, ${uncarried.candidate.length} by the candidate`);
+  }
+  const value = measured === 0 ? 0 : r6(worst);
+  const s = worstAt >= 0 ? samples[worstAt] : null;
+  const at: WorstSample['at'] = s === null ? {} : s.pixel !== null ? { pixel: s.pixel, uv: s.uv } : { vertex: s.vertex ?? undefined, uv: s.uv };
+  const sum = (xs: readonly number[]): number => xs.reduce((a, b) => a + b, 0);
+  const detail: SkinningDetail = {
+    reading: SKINNING_READING,
+    source: { id: skinning.source.id, digest: sourceMeshDigest(source) },
+    reference: envelope.reference,
+    samples: { measured, uncarried },
+    worst:
+      value === 0
+        ? null
+        : {
+            covariance: r6(sum(worstCov)),
+            lever: r6(sum(worstLev)),
+            bones: envelope.bones.map((b, k) => ({ bone: b.bone, covariance: r6(worstCov[k]), lever: r6(worstLev[k]) })),
+          },
+    weightField: { l1: r6(l1Max), lInf: r6(lInfMax) },
+    setup: { vertexGap: r6(vertexGap), vertexSlack: slack, sampleGap: r6(sampleGap), weightSumGap },
+  };
+  return { state: 'measured', value, worst: value === 0 ? { at: {} } : { at }, detail, samples: samples.length, art };
+}
+
+// ---------------------------------------------------------------------------
+// the helper: declared ranges → one envelope entry
+// ---------------------------------------------------------------------------
+
+/**
+ * One bone's declared motion, relative to its setup pose, as `skinningEnvelopeBone` reads it. Every field is required.
+ *
+ * Coordinates: `pivot` is the bone's setup joint (world origin) in the attachment's drawing frame, px, y down.
+ * Rotations and scales are the bone's LOCAL values over the motion relative to its setup values — the keys of its
+ * rotate and scale timelines — so a bone that does not move declares `[0, 0]` and `[1, 1]`.
+ */
+export interface BoneMotionRange {
+  bone: string;
+  /** Where the range comes from. Only `'keys'` is certified; any other value — `'physics'` — is refused by name. */
+  source: 'keys';
+  /** The setup joint in drawing px, y down. */
+  pivot: [number, number];
+  /** Local rotation minus setup rotation over the motion, degrees, [min, max]. */
+  rotate: [number, number];
+  /** Local scale over setup scale, per axis, [min, max]. */
+  scaleX: [number, number];
+  scaleY: [number, number];
+  /** The most the bone's local translation moves its joint from setup, drawing px, 0 or more. */
+  translate: number;
+  /** The bone's setup as the rig declares it — checked against the helper's assumptions, never corrected. */
+  setup: { scaleX: number; scaleY: number; shearX: number; shearY: number; inherit: 'normal' };
+}
+
+/**
+ * What `skinningEnvelopeBone` composes: the chain from the skeleton's root to the envelope's reference, and from below
+ * the reference down to the bone the entry is for.
+ */
+export interface EnvelopeBoneRanges {
+  /** Root first, ending at the reference bone: every bone the reference's world transform is composed of. */
+  referenceChain: BoneMotionRange[];
+  /** Parent first, from the reference's child down to the bone the entry is for (its last element). At least one. */
+  chain: BoneMotionRange[];
+}
+
+/** `skinningEnvelopeBone`'s planted faults, for the helper's negative controls (MQ133): scale ranges ignored, the joints' motion ignored. */
+export type EnvelopePlant = 'scale-ignored' | 'translation-ignored';
+
+function rangeOf(who: string, at: string, value: unknown, positive: boolean): [number, number] {
+  if (!Array.isArray(value) || value.length !== 2 || !isFiniteNumber(value[0]) || !isFiniteNumber(value[1]) || value[0] > value[1] || (positive && value[0] <= 0)) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: ${at} is ${shown(value)}; required [min, max], finite, min <= max${positive ? ', min above 0' : ''}`);
+  }
+  return [value[0], value[1]];
+}
+
+/** e = ‖R(θ) diag(σx, σy) − I‖₂ bounded by 2 sin(θ / 2) + max |σ − 1|, and the scale's norm max |σ|, over a declared range. */
+function stepOf(who: string, at: string, r: unknown): { e: number; norm: number; translate: number; pivot: Pt; rotation: number; scale: number } {
+  if (!isObject(r) || typeof r.bone !== 'string' || r.bone === '') refuse('REDUCE_INPUT_MISSING', `${who}: ${at} is ${shown(r)}; required a BoneMotionRange`);
+  const name = `${at} (bone "${r.bone}")`;
+  if (r.source !== 'keys') {
+    refuse(
+      'SKINNING_RANGE_UNSUPPORTED',
+      `${who}: ${name}.source is ${shown(r.source)}; required "keys" — a range not declared by the bone's own keys (a physics swing, a range read off a posed schedule) is not certified by this helper, so it is refused rather than turned into a bound`,
+    );
+  }
+  if (!isPoint(r.pivot)) refuse('REDUCE_INPUT_MISSING', `${who}: ${name}.pivot is ${shown(r.pivot)}; required the setup joint as a pair of finite drawing px`);
+  const rotate = rangeOf(who, `${name}.rotate`, r.rotate, false);
+  const sx = rangeOf(who, `${name}.scaleX`, r.scaleX, true);
+  const sy = rangeOf(who, `${name}.scaleY`, r.scaleY, true);
+  if (!isFiniteNumber(r.translate) || r.translate < 0) refuse('REDUCE_INPUT_MISSING', `${who}: ${name}.translate is ${shown(r.translate)}; required a finite number of drawing px, 0 or more`);
+  const setup = r.setup;
+  if (!isObject(setup) || !isFiniteNumber(setup.scaleX) || !isFiniteNumber(setup.scaleY) || !isFiniteNumber(setup.shearX) || !isFiniteNumber(setup.shearY) || typeof setup.inherit !== 'string') {
+    refuse('REDUCE_INPUT_MISSING', `${who}: ${name}.setup is ${shown(setup)}; required { scaleX, scaleY, shearX, shearY, inherit } as the rig declares them`);
+  }
+  if (Math.abs(setup.scaleX) !== Math.abs(setup.scaleY) || setup.scaleX === 0) {
+    refuse('SKINNING_RANGE_UNSUPPORTED', `${who}: ${name}.setup scale is (${setup.scaleX}, ${setup.scaleY}); required a uniform setup scale — under a nonuniform one the bone's deformation is not a rotation and scale of the drawing, and the bound is not proven`);
+  }
+  if (setup.shearX !== 0 || setup.shearY !== 0) refuse('SKINNING_RANGE_UNSUPPORTED', `${who}: ${name}.setup shear is (${setup.shearX}, ${setup.shearY}); required (0, 0) — a sheared setup is outside the helper's assumptions`);
+  if (setup.inherit !== 'normal') refuse('SKINNING_RANGE_UNSUPPORTED', `${who}: ${name}.setup.inherit is ${shown(setup.inherit)}; required "normal" — another inherit mode composes the chain otherwise than the helper does`);
+  const theta = Math.min(Math.max(Math.abs(rotate[0]), Math.abs(rotate[1])), 180);
+  const rotation = 2 * Math.sin((theta * Math.PI) / 360);
+  const scale = Math.max(Math.abs(sx[0] - 1), Math.abs(sx[1] - 1), Math.abs(sy[0] - 1), Math.abs(sy[1] - 1));
+  const norm = Math.max(sx[1], sy[1]);
+  return { e: rotation + scale, norm, translate: r.translate, pivot: r.pivot, rotation, scale };
+}
+
+/**
+ * One `SkinningEnvelopeBone` from declared ranges (issue #1294; rig-parts#126 Q3: one definition of `linear`, rig-c's).
+ *
+ * The definition. Under the assumptions below, each bone j's local change is, in the drawing frame, an affine map
+ * Fⱼ(q) = cⱼ + Mⱼ (q − cⱼ) + tⱼ with ‖Mⱼ − I‖ ≤ eⱼ = 2 sin(θⱼ / 2) + max |σⱼ − 1| (θⱼ the largest |rotation|, capped
+ * at 180°, σⱼ every scale ratio's endpoint), ‖Mⱼ‖ ≤ max σⱼ, and |tⱼ| ≤ the declared `translate`. The bone's deformation
+ * relative to the reference is G = F₁ ∘ … ∘ Fₘ over `chain`, and the reference's own deformation scales by at most
+ * S = Π max σ over `referenceChain`. Then
+ *
+ * - `linear` ε = S · (Πⱼ (1 + eⱼ) − 1) ≥ ‖Aₖ − A₀‖ — the composition is a product, because a chain's changes multiply;
+ * - `pivot` c = the last bone's setup joint;
+ * - `translation` τ = S · δ₁, where δₘ = translate of the last bone and δⱼ = eⱼ |c − cⱼ| + (1 + eⱼ) δⱼ₊₁ + translateⱼ,
+ *   so that |(Dₖ − D₀) q| ≤ ε |q − c| + τ for every q.
+ *
+ * Every step is a triangle inequality, so the entry is conservative for any motion inside the declared ranges, and
+ * claims nothing outside them. The reference chain's rotations and translations cancel in Dₖ − D₀ and are not read.
+ *
+ * The assumptions, checked where the input can show them and refused by name (`SKINNING_RANGE_UNSUPPORTED`): each
+ * bone's range is declared by its keys (`source: 'keys'`; a physics swing is not certified); every bone of both
+ * chains has a uniform setup scale, no setup shear and inherit `normal`, so every setup world map is a similarity and
+ * conjugating by it keeps each norm. Not checkable here, and assumed: the attachment's drawing frame maps to world by a
+ * similarity (the slot's bone at its setup, as the compile places a part), and the chain listed is the bone's real
+ * ancestry. Malformed input is `REDUCE_INPUT_MISSING` naming the path.
+ */
+export function skinningEnvelopeBone(ranges: EnvelopeBoneRanges): SkinningEnvelopeBone {
+  return envelopeBoneWith(ranges, null);
+}
+
+/** `skinningEnvelopeBone` with a fault planted (`EnvelopePlant`) — the helper's negative controls. Internal: merely exported. */
+export function skinningEnvelopeBonePlanted(ranges: EnvelopeBoneRanges, plant: EnvelopePlant): SkinningEnvelopeBone {
+  return envelopeBoneWith(ranges, plant);
+}
+
+function envelopeBoneWith(ranges: EnvelopeBoneRanges, plant: EnvelopePlant | null): SkinningEnvelopeBone {
+  const who = 'skinningEnvelopeBone';
+  if (!isObject(ranges) || !Array.isArray(ranges.referenceChain) || !Array.isArray(ranges.chain)) refuse('REDUCE_INPUT_MISSING', `${who}: the input is ${shown(ranges)}; required { referenceChain: BoneMotionRange[], chain: BoneMotionRange[] }`);
+  if (ranges.referenceChain.length === 0) refuse('REDUCE_INPUT_MISSING', `${who}: referenceChain is empty; required the bones from the skeleton's root to the reference, at least the reference`);
+  if (ranges.chain.length === 0) refuse('REDUCE_INPUT_MISSING', `${who}: chain is empty; required the bones below the reference down to the bone the entry is for, at least that bone`);
+  const above = ranges.referenceChain.map((r, i) => stepOf(who, `referenceChain[${i}]`, r));
+  const below = ranges.chain.map((r, i) => stepOf(who, `chain[${i}]`, r));
+  const S = above.reduce((s, x) => s * (plant === 'scale-ignored' ? 1 : x.norm), 1);
+  const eOf = (x: { e: number; rotation: number }): number => (plant === 'scale-ignored' ? x.rotation : x.e);
+  const composed = below.reduce((s, x) => s * (1 + eOf(x)), 1) - 1;
+  const last = below[below.length - 1];
+  const c = last.pivot;
+  let delta = plant === 'translation-ignored' ? 0 : last.translate;
+  for (let j = below.length - 2; j >= 0; j--) {
+    if (plant === 'translation-ignored') break;
+    const x = below[j];
+    delta = eOf(x) * Math.hypot(c[0] - x.pivot[0], c[1] - x.pivot[1]) + (1 + eOf(x)) * delta + x.translate;
+  }
+  return { bone: (ranges.chain[ranges.chain.length - 1] as BoneMotionRange).bone, linear: S * composed, pivot: [c[0], c[1]], translation: S * delta };
+}