rig-c 2.27.0 → 2.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-c",
-  "version": "2.27.0",
+  "version": "2.29.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/meshallocation.ts

@@ -54,6 +54,10 @@ type Weights = ReadonlyArray<ReadonlyArray<{ bone: string; weight: number }>>;
  * - `bstar-ignores-art`: B\* without the art test.
  * - `rows-required`: the rows counted as required.
  * - `mutates-input`: the measurement sorts the caller's triangle list in place.
+ * - `gradation-defaulted`: an amplitude whose `gradation` is left out or `null` read at 0.75, §8's fixtures' value —
+ *   the default issue #1291 measured and refused to choose.
+ * - `load-needs-gradation`: `MQ_DEFORM_LOAD` left unread for want of a `gradation` it does not read.
+ * - `gradation-ignored`: the need relaxed at 0.75 whatever `gradation` declares, so Δ no longer reads the field.
  */
 export type AllocationPlant =
   | 'omit-rows'
@@ -64,7 +68,10 @@ export type AllocationPlant =
   | 'undeclared-pair-is-rigid'
   | 'bstar-ignores-art'
   | 'rows-required'
-  | 'mutates-input';
+  | 'mutates-input'
+  | 'gradation-defaulted'
+  | 'load-needs-gradation'
+  | 'gradation-ignored';
 
 /** The art as the allocation rows read it: art pixels on the mask's grid, and the scale that grid is at. */
 export interface AllocationArt {
@@ -493,7 +500,11 @@ export interface AllocationContrast {
   worstVertex: number;
 }
 
-/** h\*: the largest local size every primary need allows at a point, each relaxed at gradation G away from its source. */
+/**
+ * h\*: the largest local size every primary need allows at a point, each relaxed at gradation G away from its source —
+ * G the caller's `motionAmplitude.gradation`, never a constant of this module: §8 measured that it derives from nothing
+ * a rig declares and that Δ moves with it (issue #1291). A region relaxes at its own declared `grade` over its band.
+ */
 interface Need {
   at(p: Pt): number;
 }
@@ -559,7 +570,8 @@ function needField(points: readonly Pt[], triangles: readonly number[], weights:
 const twiceSigned = (a: Pt, b: Pt, c: Pt): number => (b[0] - a[0]) * (c[1] - a[1]) - (c[0] - a[0]) * (b[1] - a[1]);
 
 /**
- * Δ and E (§8; the stage-A record for #1271, M7). For each vertex the
+ * Δ and E (§8; the stage-A record for #1271, M7), with the need relaxing at `gradation` — the caller's declared G,
+ * which `measureMeshQuality` hands over only when it is set. For each vertex the
  * cheapest half-edge collapse into a neighbour — a hull vertex only along the
  * hull — that turns no triangle over; ν is the largest, over what that
  * collapse changes, of: the silhouette (the moved outline's chord distance
@@ -580,13 +592,15 @@ export function allocationContrast(
   art: AllocationArt,
   regions: readonly RefinementRegion[],
   declared: MotionAmplitude,
+  gradation: number,
   silhouette: number[],
   plant: AllocationPlant | null,
 ): Reading<AllocationContrast> {
   const n = points.length;
   const pairs = new PairAmplitudes(declared, plant);
   const amplitudeRead = plant !== 'contrast-without-amplitude';
-  const need = needField(points, triangles, weights, silhouette, regions, amplitudeRead ? pairs : new PairAmplitudes({ tracks: [], gradation: declared.gradation }, 'undeclared-pair-is-rigid'), declared.gradation);
+  const G = plant === 'gradation-ignored' ? 0.75 : gradation;
+  const need = needField(points, triangles, weights, silhouette, regions, amplitudeRead ? pairs : new PairAmplitudes({ tracks: [] }, 'undeclared-pair-is-rigid'), G);
   if (need === null) return unmeasured(undeclaredPairReason(pairs.missing!));
   const nb: Array<Set<number>> = Array.from({ length: n }, () => new Set<number>());
   const triOf: number[][] = Array.from({ length: n }, () => []);

package/src/meshcompare.ts

@@ -79,6 +79,7 @@ import { artOf, MeshReductionError, r6 } from './mesh.ts';
 import {
   measureMeshQuality,
   MESH_QUALITY_REPORT_SPEC,
+  validateMotionAmplitude,
   type ArtFitBounds,
   type ArtInput,
   type AttachmentRef,
@@ -89,6 +90,7 @@ import {
   type MeasureRow,
   type MeshCounts,
   type MeshQualityReport,
+  type MotionAmplitude,
   type MotionBounds,
   type MotionReading,
   type MotionRowDetail,
@@ -151,8 +153,27 @@ export interface MotionComparisonInput {
   bounds: MotionBounds;
   motionRequired: boolean;
   perFrame: boolean;
+  /**
+   * Issue #1291: the motion amplitude the setup art fit's measurement reads — `MeshMeasureInput.motionAmplitude`, the
+   * same shape and the same handling, handed to that measurement of every build and to nothing else (no frame, no
+   * motion row and no acceptance reads it). Left out, it is not declared and the setup sections' `MQ_DEFORM_LOAD`
+   * and `MQ_ALLOCATION_CONTRAST` are `not-measurable` naming it, as before the field existed; `null` declares it
+   * absent; set, `MQ_DEFORM_LOAD` is measured on each build's setup section. `MQ_ALLOCATION_CONTRAST` stays
+   * `not-measurable` there either way, naming `targets.maxBoundaryDeviation`: the comparison declares no deviation
+   * bound and no reference hull. Anything that is not a `MotionAmplitude` in full is refused `COMPARE_INPUT_MISSING`
+   * before any build is read, in the measurement's words. Echoed in `effective` when set, `null` included.
+   */
+  motionAmplitude?: MotionAmplitude | null;
 }
 
+/**
+ * Issue #1291's faults in carrying `motionAmplitude` into the setup measurement, for the `mesh-compare` suite's
+ * negative controls: the amplitude not handed over; `null` handed over as the field left out; the field not validated
+ * before the builds are read; `null` echoed for a field left out; and the load counted as a required row, so the
+ * amplitude moves a verdict. `compareMeshesInMotion` plants none.
+ */
+export type ComparePlant = 'amplitude-not-carried' | 'null-read-as-left-out' | 'amplitude-unvalidated' | 'echo-when-unset' | 'amplitude-gates-acceptance';
+
 // ---------------------------------------------------------------------------
 // fixed tolerances — the tree's own
 // ---------------------------------------------------------------------------
@@ -204,7 +225,7 @@ function validateFit(field: string, f: unknown): void {
  * art itself (mask, threshold, frame) is `measureMeshQuality`'s to refuse, by
  * its own codes, when the setup art fit is taken.
  */
-function validateInput(input: MotionComparisonInput): void {
+function validateInput(input: MotionComparisonInput, plant: ComparePlant | null): void {
   if (!isObject(input)) missing('the input', input, 'a MotionComparisonInput object');
   const builds = [input.reference, ...(Array.isArray(input.candidates) ? input.candidates : [])];
   if (!Array.isArray(input.candidates) || input.candidates.length === 0) missing('candidates', input.candidates, 'a non-empty list of builds');
@@ -257,6 +278,16 @@ function validateInput(input: MotionComparisonInput): void {
   if (b.minStretch !== undefined && (!isFiniteNumber(b.minStretch) || b.minStretch < 0)) missing('bounds.minStretch', b.minStretch, 'a finite ratio >= 0, or the field left out');
   if (typeof input.motionRequired !== 'boolean') missing('motionRequired', input.motionRequired, 'true or false (P6)');
   if (typeof input.perFrame !== 'boolean') missing('perFrame', input.perFrame, 'true or false (P7)');
+  if (plant !== 'amplitude-unvalidated') {
+    // Issue #1291: the measurement's own validator, so a comparison and a measurement refuse one value in the same
+    // words — under the comparison's code, and here, before any build is read.
+    try {
+      validateMotionAmplitude('the comparison', input.motionAmplitude);
+    } catch (err) {
+      if (err instanceof MeshReductionError) refuse('COMPARE_INPUT_MISSING', err.message.slice(err.code.length + 2));
+      throw err;
+    }
+  }
   const s = input.schedule;
   if (s === null) return;
   if (!isObject(s)) missing('schedule', s, 'a MotionSchedule, or null for no motion');
@@ -852,7 +883,24 @@ function foldingSlots(raw: unknown, who: string): Set<string> {
  * undercut at the setup pose fails `referenceArtFit`, and `measureMeshQuality`'s own codes for the art).
  */
 export function compareMeshesInMotion(input: MotionComparisonInput): MeshQualityReport {
-  validateInput(input);
+  return compareMeshesInMotionWith(input, null);
+}
+
+/**
+ * `compareMeshesInMotion` with a fault planted in how it carries `motionAmplitude` (`ComparePlant`) — the
+ * `mesh-compare` suite's negative controls. Internal: merely exported, so not promised (RELEASING.md *The import
+ * surface*).
+ */
+export function compareMeshesInMotionPlanted(input: MotionComparisonInput, plant: ComparePlant): MeshQualityReport {
+  return compareMeshesInMotionWith(input, plant);
+}
+
+function compareMeshesInMotionWith(input: MotionComparisonInput, plant: ComparePlant | null): MeshQualityReport {
+  validateInput(input, plant);
+  const amplitude = input.motionAmplitude;
+  // What the setup measurement is handed: the field as the caller set it — left out as left out, `null` as `null`.
+  const handed: { motionAmplitude?: MotionAmplitude | null } =
+    plant === 'amplitude-not-carried' || amplitude === undefined || (plant === 'null-read-as-left-out' && amplitude === null) ? {} : { motionAmplitude: amplitude };
   const refs = input.attachments.map((a) => a.attachment);
   const reference = readBuild(input.reference, 'reference', refs);
   const candidates = input.candidates.map((c, i) => readBuild(c, `candidates[${i}]`, refs));
@@ -895,9 +943,14 @@ export function compareMeshesInMotion(input: MotionComparisonInput): MeshQuality
         influences: null,
         boneOrder: null,
         preset: null,
+        ...handed,
       });
       const c = measured.candidates[0];
       if (c.geometry === null || c.counts === null) return { geometry: null, counts: null };
+      if (plant === 'amplitude-gates-acceptance') {
+        const load = c.geometry.rows.find((r) => r.code === 'MQ_DEFORM_LOAD');
+        if (load !== undefined && load.state === 'undeclared') c.geometry.verdict = 'fail';
+      }
       sections.push(c.geometry);
       counts.push(c.counts);
     }
@@ -1176,6 +1229,7 @@ export function compareMeshesInMotion(input: MotionComparisonInput): MeshQuality
     boneOrder: null,
     schedule,
     budget: null,
+    ...(amplitude === undefined ? (plant === 'echo-when-unset' ? { motionAmplitude: null } : {}) : { motionAmplitude: amplitude }),
   };
   return {
     spec: MESH_QUALITY_REPORT_SPEC,

package/src/meshquality.ts

@@ -273,6 +273,16 @@ export interface MeshReductionInput {
    * refused.
    */
   removalOrder?: 'deformation-load';
+  /**
+   * The motion amplitude the two weight-aware allocation rows read (issue #1287) — `MeshMeasureInput.motionAmplitude`,
+   * the same shape and the same handling: left out, it is not declared; `null` declares it absent; anything else that
+   * is not a `MotionAmplitude` in full is refused `REDUCE_INPUT_MISSING` naming its path, before any work. Set, the
+   * result's measurement reads it, so `MQ_ALLOCATION_CONTRAST` and `MQ_DEFORM_LOAD` are measured on the report rather
+   * than `not-measurable`; it is echoed in `effective` (`null` included). It declares no bound — both rows stay
+   * `undeclared` — and no step reads it: the admission, every step and the post-pass are measured without it, so the
+   * mesh, `acceptedAt`, the termination and every other row are the call's without it (docs/MESH_REDUCTION.md §8).
+   */
+  motionAmplitude?: MotionAmplitude | null;
 }
 
 /**
@@ -369,10 +379,20 @@ export interface MotionAmplitude {
   /** One entry per track the caller declares (an animation, a parameter axis — its name is echoed, never read). */
   tracks: TrackAmplitude[];
   /**
-   * G, px per px: how fast a declared need relaxes away from its source — the size a need allows at distance d is its
-   * own plus G × d (the form of a region's `grade`). Read by `MQ_ALLOCATION_CONTRAST` only. Finite, 0 or more.
+   * G, px per px — an author's number, read by `MQ_ALLOCATION_CONTRAST` only (issue #1291). Δ asks of each vertex
+   * whether the mesh still meets every declared need without it; a need — a silhouette edge of the B\* outline, a
+   * deforming triangle sized by θ and ε, a region — allows edges of its own size h at its source and h + G × d at
+   * distance d from it, the form of a region's `grade`. So G is the fastest rate at which the author allows the mesh to
+   * coarsen away from what needs density: a larger G lets the need relax sooner, so more dense vertices read as
+   * removable and Δ and economy E rise (graded layers read as slack); a smaller G keeps more of them needed, and at 0
+   * every point needs the smallest size any source declares, so nothing reads as removable. The value an author
+   * declares on a region's `grade` for the same mesh is the same quantity; §8's fixtures used 0.75 because it is the
+   * one `grade` any of them declares. Nothing a rig or a reduction declares fixes G — docs/MESH_REDUCTION.md §8
+   * measured every candidate derivation, and Δ moves with G on every input there — so none is assumed: left out, it is
+   * not declared, and `null` declares it absent; either leaves `MQ_ALLOCATION_CONTRAST` `not-measurable` naming this
+   * field, and `MQ_DEFORM_LOAD`, which does not read G, measured. Set, finite and 0 or more.
    */
-  gradation: number;
+  gradation?: number | null;
 }
 
 /** One track's amplitude: the pairs of bones a share moves between in it, each with θ, and the track's ε. */
@@ -584,7 +604,7 @@ export interface EffectiveSettings {
   stopAfterAccepted?: number;
   /** A reduction's `boundaryRuns`, echoed when the input set it (issue #1279); absent otherwise. */
   boundaryRuns?: BoundaryRuns;
-  /** A measurement's `motionAmplitude`, echoed when the input set it — `null` included (issue #1280); absent otherwise. */
+  /** A measurement's or a reduction's `motionAmplitude`, echoed when the input set it — `null` included (issues #1280, #1287); absent otherwise. */
   motionAmplitude?: MotionAmplitude | null;
   /** A reduction's `retriangulate`, echoed when the input set it (issue #1283); absent otherwise. */
   retriangulate?: 'delaunay';
@@ -842,16 +862,24 @@ function validateInput(input: MeshMeasureInput): void {
   if (input.preset !== null && (!isObject(input.preset) || typeof input.preset.name !== 'string' || typeof input.preset.version !== 'string')) {
     refuse('REDUCE_INPUT_MISSING', `${who}: preset is not { name, version }; required that, or null`);
   }
-  validateAmplitude(who, input.motionAmplitude);
+  validateMotionAmplitude(who, input.motionAmplitude);
 }
 
-/** Issue #1280: `motionAmplitude` left out or `null` is accepted as it stands; anything else is a `MotionAmplitude` in full. */
-function validateAmplitude(who: string, amplitude: unknown): void {
+/**
+ * Issue #1280: `motionAmplitude` left out or `null` is accepted as it stands; anything else is a `MotionAmplitude` in
+ * full, else refused `REDUCE_INPUT_MISSING` naming the path. `reduceMesh` refuses its own field with it before any work
+ * (issue #1287), so a reduction and a measurement refuse one value in the same words. Internal, as
+ * `measureMeshQualityWith` is: on `rig-c/mesh` only through `export *`.
+ */
+export function validateMotionAmplitude(who: string, amplitude: unknown): void {
   if (amplitude === undefined || amplitude === null) return;
   const shape = '{ tracks: [{ track, pairs: [{ bones: [a, b], theta }], epsilon }], gradation }';
   if (!isObject(amplitude) || !Array.isArray(amplitude.tracks)) refuse('REDUCE_INPUT_MISSING', `${who}: motionAmplitude is ${JSON.stringify(amplitude)}; required ${shape}, null, or the field left out`);
-  if (!isFiniteNumber(amplitude.gradation) || amplitude.gradation < 0) {
-    refuse('REDUCE_INPUT_MISSING', `${who}: motionAmplitude.gradation is ${JSON.stringify(amplitude.gradation)}; required a finite number of px per px, 0 or more — no gradation is assumed`);
+  // Issue #1291: `gradation` left out or `null` is accepted — MQ_ALLOCATION_CONTRAST then reads not-measurable naming it.
+  if (amplitude.gradation !== undefined && amplitude.gradation !== null && (!isFiniteNumber(amplitude.gradation) || amplitude.gradation < 0)) {
+    // A non-finite number is named as itself: JSON would print NaN as null, which this field now accepts.
+    const found = typeof amplitude.gradation === 'number' ? String(amplitude.gradation) : JSON.stringify(amplitude.gradation);
+    refuse('REDUCE_INPUT_MISSING', `${who}: motionAmplitude.gradation is ${found}; required a finite number of px per px, 0 or more, null, or the field left out — no gradation is assumed`);
   }
   amplitude.tracks.forEach((track: unknown, i: number) => {
     const at = `motionAmplitude.tracks[${i}]`;
@@ -1843,7 +1871,7 @@ function allocationRows(input: MeshMeasureInput, outline: MeshOutline, rasters:
   const allocationArt: AllocationArt = { mask: art.mask, bits: rasters.artBits(), scale: art.frame.pageScale };
 
   // MQ_DEFORM_LOAD.
-  const loadWhy = amplitudeMissing ?? unweighted;
+  const loadWhy = amplitudeMissing ?? unweighted ?? (plant === 'load-needs-gradation' && (amplitude?.gradation === undefined || amplitude.gradation === null) ? `${who}: planted — the load refused for want of a gradation it does not read` : null);
   if (loadWhy !== null || amplitude === undefined || amplitude === null || source.weights === null) {
     row('MQ_DEFORM_LOAD', 'px', missing('MQ_DEFORM_LOAD', 'px', loadWhy ?? ''));
   } else {
@@ -1860,6 +1888,15 @@ function allocationRows(input: MeshMeasureInput, outline: MeshOutline, rasters:
   // MQ_ALLOCATION_CONTRAST.
   const planted = plant === 'contrast-without-amplitude' && (amplitude === undefined || amplitude === null) ? { tracks: [], gradation: 0 } : null;
   const declared = planted ?? amplitude;
+  // Issue #1291: G is the author's; an amplitude without it measures the load and leaves Δ unread, naming the field.
+  const declaredGradation = declared === undefined || declared === null ? undefined : declared.gradation;
+  const gradation = plant === 'gradation-defaulted' && (declaredGradation === undefined || declaredGradation === null) ? 0.75 : declaredGradation;
+  const gradationMissing =
+    declared === undefined || declared === null || (gradation !== undefined && gradation !== null)
+      ? null
+      : gradation === undefined
+        ? `${who}: motionAmplitude.gradation is not declared (the field is left out), so no rate says how fast a declared need relaxes away from its source; required G, px per px, 0 or more — none is assumed, because Δ moves with G and nothing a rig declares fixes it (docs/MESH_REDUCTION.md §8)`
+        : `${who}: motionAmplitude.gradation is declared absent (null), so no rate says how fast a declared need relaxes away from its source; required G, px per px, 0 or more, for this row — none is assumed`;
   let regionWhy: string | null = null;
   for (const region of targets.regions) {
     const refusal = regionRefusal(region, art.frame.pageScale, who, steps);
@@ -1868,13 +1905,13 @@ function allocationRows(input: MeshMeasureInput, outline: MeshOutline, rasters:
       break;
     }
   }
-  const contrastWhy = (planted === null ? amplitudeMissing : null) ?? unweighted ?? noDelta ?? fewArt ?? regionWhy;
-  if (contrastWhy !== null || declared === undefined || declared === null || source.weights === null || delta === null) {
+  const contrastWhy = (planted === null ? amplitudeMissing : null) ?? gradationMissing ?? unweighted ?? noDelta ?? fewArt ?? regionWhy;
+  if (contrastWhy !== null || declared === undefined || declared === null || gradation === undefined || gradation === null || source.weights === null || delta === null) {
     row('MQ_ALLOCATION_CONTRAST', 'fraction', missing('MQ_ALLOCATION_CONTRAST', 'fraction', contrastWhy ?? ''));
   } else {
     const ownHull = points.slice(0, outline.hull);
     const silhouette = boundaryNecessityOnce(rasters, ownHull, delta, allocationArt, null).path;
-    const contrast = allocationContrast(points, source.triangles, outline.hull, source.weights, delta, allocationArt, targets.regions, declared, silhouette, plant);
+    const contrast = allocationContrast(points, source.triangles, outline.hull, source.weights, delta, allocationArt, targets.regions, declared, gradation, silhouette, plant);
     if (contrast.measured) {
       const c = contrast.value;
       row('MQ_ALLOCATION_CONTRAST', 'fraction', measured('MQ_ALLOCATION_CONTRAST', 'fraction', c.contrast, { at: { vertex: c.worstVertex } }), {
@@ -2372,7 +2409,7 @@ function amplitudeJson(a: MotionAmplitude | null): Json {
   if (a === null) return null;
   return {
     tracks: a.tracks.map((t) => ({ track: t.track, pairs: t.pairs.map((p) => ({ bones: [p.bones[0], p.bones[1]], theta: p.theta })), epsilon: t.epsilon })),
-    gradation: a.gradation,
+    ...(a.gradation === undefined ? {} : { gradation: a.gradation }),
   };
 }
 

package/src/meshreduce.ts

@@ -70,6 +70,15 @@
  * is not a step: no candidate, no `acceptedAt` entry, so a replay and the
  * budget cut at the same step end on the same state and the same pass.
  *
+ * ## The amplitude (issue #1287, opt-in)
+ *
+ * With `motionAmplitude`, the result's own measurement reads it, so the
+ * report's `MQ_ALLOCATION_CONTRAST` and `MQ_DEFORM_LOAD` are measured rather
+ * than `not-measurable`. No other measurement of the call is handed it — no
+ * step is decided by either row, and no report carries the other
+ * measurements' rows (`amplitudeOf`) — so the mesh and every step are the
+ * call's without it.
+ *
  * A removal whose deviation floor — the furthest removed source-hull vertex
  * from the candidate's outline, which `MQ_BOUNDARY_DEVIATION` can only exceed —
  * is over the bound is refused without the measurement; its name, when read,
@@ -119,6 +128,7 @@ import {
   edgeIsHeldByRegion,
   measureMeshQualityStep,
   measureMeshQualityWith,
+  validateMotionAmplitude,
   type AcceptedOperation,
   type AttachmentRef,
   type ArtFitBounds,
@@ -130,6 +140,7 @@ import {
   type MeshMeasureInput,
   type MeshQualityReport,
   type MeshReductionInput,
+  type MotionAmplitude,
   type RefinementRegion,
   type ReductionChanges,
   type Retriangulation,
@@ -274,7 +285,7 @@ function artBoundAbsent(fit: ArtFitBounds, row: MeasureRow): boolean {
  * by `measureMeshQuality`'s own validation when the source is first measured,
  * with the same codes.
  */
-function validateReduction(input: MeshReductionInput): void {
+function validateReduction(input: MeshReductionInput, plant: ReductionPlant | null = null): void {
   if (!isObject(input)) refuse('REDUCE_INPUT_MISSING', `the input is ${JSON.stringify(input)}; required a MeshReductionInput object`);
   if (!isRef(input.attachment)) refuse('REDUCE_INPUT_MISSING', `attachment is ${JSON.stringify(input.attachment)}; required { skin: string | null, slot: string, attachment: string }`);
   const who = `attachment ${nameOf(input.attachment)}`;
@@ -305,6 +316,9 @@ function validateReduction(input: MeshReductionInput): void {
   if ('removalOrder' in input && input.removalOrder !== undefined && input.removalOrder !== 'deformation-load') {
     refuse('REDUCE_INPUT_MISSING', `${who}: removalOrder is ${JSON.stringify(input.removalOrder)}; required "deformation-load" — single removals in ascending predicted deformation load, ties by source index — or the field left out (issue #1283: ascending source index)`);
   }
+  // Issue #1287: refused here, before the admission measurement and any step, in the measurement's own words — the
+  // admission does not carry the field, and a call whose source is refused never reaches the one measurement that does.
+  if (plant !== 'amplitude-unvalidated') validateMotionAmplitude(who, input.motionAmplitude);
   const src = input.source;
   if (!isObject(src) || !Array.isArray(src.points)) refuse('REDUCE_INPUT_MISSING', `${who}: source is not { points, uvs, triangles, hull, weights }`);
   const n = src.points.length;
@@ -791,8 +805,11 @@ interface Run {
   stepRasters: StepRasters | null;
 }
 
-/** A measurement of a canonical mesh against the result's full contract. */
-function measureAgainstTargets(run: Run, mesh: SourceMesh, id: string): MeshQualityReport {
+/**
+ * A measurement of a canonical mesh against the result's full contract. `final` marks the result's own measurement —
+ * the one whose rows the report carries, and the only one handed the input's `motionAmplitude` (`amplitudeOf`).
+ */
+function measureAgainstTargets(run: Run, mesh: SourceMesh, id: string, final = false): MeshQualityReport {
   const { input } = run;
   const targets = input.targets;
   const measureInput: MeshMeasureInput = {
@@ -808,10 +825,33 @@ function measureAgainstTargets(run: Run, mesh: SourceMesh, id: string): MeshQual
     influences: input.influences,
     boneOrder: input.boneOrder,
     preset: input.preset,
+    ...amplitudeOf(run.input, run.plant, final),
   };
   return run.stepRasters === null ? measureMeshQualityWith(measureInput, run.rasters) : measureMeshQualityStep(measureInput, run.stepRasters);
 }
 
+/**
+ * Issue #1287: what one measurement of a reduction is handed as `motionAmplitude` — the input's, on the result's own
+ * measurement (`final`) only. The admission, every refinement and removal step and the post-pass are measured without
+ * it: no row it adds is read by a step (both are `undeclared`, so `firstBlockingRow` never names one) and no report
+ * carries those measurements' rows, so carrying it there would buy nothing and cost Δ's own silhouette search at every
+ * step (docs/MESH_REDUCTION.md §8, *Stage B — the amplitude on a reduction*, measured). A field left out is passed as
+ * left out and `null` as `null`, so the rows' reasons say which.
+ */
+function amplitudeOf(input: MeshReductionInput, plant: ReductionPlant | null, final: boolean): { motionAmplitude?: MotionAmplitude | null } {
+  const amplitude = input.motionAmplitude;
+  if (!final && plant !== 'amplitude-every-measurement' && plant !== 'amplitude-gates-steps') return {};
+  if (plant === 'amplitude-not-carried') return {};
+  if (plant === 'amplitude-invented' && (amplitude === undefined || amplitude === null)) {
+    const bones = [...new Set((input.source.weights ?? []).flatMap((v) => v.map((b) => b.bone)))].sort();
+    const pairs: Array<{ bones: [string, string]; theta: number }> = [];
+    for (let i = 0; i < bones.length; i++) for (let j = i + 1; j < bones.length; j++) pairs.push({ bones: [bones[i], bones[j]], theta: 1 });
+    return { motionAmplitude: { tracks: [{ track: 'invented', pairs, epsilon: 1 }], gradation: 0 } };
+  }
+  if (plant === 'null-read-as-left-out' && amplitude === null) return {};
+  return amplitude === undefined ? {} : { motionAmplitude: amplitude };
+}
+
 /** The order constraints are named in when several fail on one step: structure, then shape, then art, then density. */
 const BLOCKING_ORDER = ['MQ_ORIENTATION', 'MQ_DEGENERATE', 'MQ_BOUNDARY_DEVIATION', 'MQ_COVERAGE', 'MQ_OVERSHOOT', 'MQ_UNDERCUT', 'MQ_MIN_ANGLE', 'MQ_MAX_EDGE', 'MQ_TRANSITION'];
 
@@ -1051,7 +1091,8 @@ export type ReductionPlant =
   | 'measure-every-candidate'
   | 'floor-half-a-pixel-short'
   | RetriangulationPlant
-  | OrderPlant;
+  | OrderPlant
+  | AmplitudePlant;
 
 /**
  * Issue #1283's faults in the triangulation post-pass: the pass run on a call that did not opt in; the pass skipped
@@ -1064,6 +1105,24 @@ export type RetriangulationPlant = 'flips-without-opt-in' | 'flips-not-on-replay
 /** Issue #1283's faults in the removal order: the load order used by a call that did not opt in, and the loads ranked descending. */
 export type OrderPlant = 'order-without-opt-in' | 'order-descending';
 
+/**
+ * Issue #1287's faults in carrying `motionAmplitude`: the amplitude not handed to the result's measurement; an
+ * amplitude invented (every pair of the source's bones at θ 1, ε 1, gradation 0) when the field is left out or
+ * `null`; `null` passed to the measurement as the field left out; the field not validated by the reduction; a
+ * measured allocation row read as blocking a step; and `effective` echoing `null` for a field left out. And one path
+ * that is not a fault, held equal to the call: the amplitude handed to every measurement of the call — the admission,
+ * each step, the post-pass — which is what the decision to carry it on the result's measurement only is measured
+ * against.
+ */
+export type AmplitudePlant =
+  | 'amplitude-not-carried'
+  | 'amplitude-invented'
+  | 'null-read-as-left-out'
+  | 'amplitude-unvalidated'
+  | 'amplitude-gates-steps'
+  | 'echo-when-unset'
+  | 'amplitude-every-measurement';
+
 /** One removal-phase attempt as a control reads it (issue #1279): what was tried, and what refused it or null when taken. */
 export interface AttemptRecord {
   step: number;
@@ -1484,7 +1543,10 @@ function tryOperation(run: Run, vertices: readonly number[], full: boolean): Ref
       };
     }
   }
-  const blocking = firstBlockingRow(measureAgainstTargets(run, canon.mesh, 'candidate'), run.input.targets.artFit);
+  const measured = measureAgainstTargets(run, canon.mesh, 'candidate');
+  const blocking =
+    firstBlockingRow(measured, run.input.targets.artFit) ??
+    (run.plant === 'amplitude-gates-steps' ? ((measured.candidates[0]?.geometry?.rows ?? []).find((r) => (r.code === 'MQ_DEFORM_LOAD' || r.code === 'MQ_ALLOCATION_CONTRAST') && r.state === 'undeclared') ?? null) : null);
   if (blocking !== null) {
     undo();
     return rowName(blocking);
@@ -1722,7 +1784,7 @@ export function reduceMeshWith(
   plant: ReductionPlant | null = null,
   observe: AttemptObserver | null = null,
 ): MeshReductionResult {
-  validateReduction(input);
+  validateReduction(input, plant);
   if (steps !== null && steps.rasters !== rasters) {
     refuse('REDUCE_ART_RASTERS_MISMATCH', `attachment ${nameOf(input.attachment)}: the step rasters were made over another rasters object; required step rasters made over the rasters passed beside them (stepRastersOf(rasters))`);
   }
@@ -1754,9 +1816,10 @@ function reduceValidated(input: MeshReductionInput, rasters: ArtRasters, steps:
     influences: input.influences,
     boneOrder: input.boneOrder,
     preset: input.preset,
+    ...amplitudeOf(input, plant, false),
   };
   const admit = steps === null ? measureMeshQualityWith(admitInput, rasters) : measureMeshQualityStep(admitInput, steps);
-  const effective = effectiveOf(input, admit.effective, sourceHull);
+  const effective = effectiveOf(input, admit.effective, sourceHull, plant);
   const sourceCounts = admit.sourceCounts;
   const noMesh = (termination: Termination): MeshReductionResult => ({
     mesh: null,
@@ -1911,7 +1974,7 @@ function finish(run: Run, effective: EffectiveSettings, sourceCounts: MeshCounts
     }
     throw err;
   }
-  const measured = measureAgainstTargets(run, canon.mesh, 'result');
+  const measured = measureAgainstTargets(run, canon.mesh, 'result', true);
   const candidate = measured.candidates[0];
   const changes: ReductionChanges = {
     removedVertices: indexMap.filter((r) => r === null).length,
@@ -1952,7 +2015,8 @@ function reportOf(effective: EffectiveSettings, sourceCounts: MeshCounts | null,
 }
 
 /** Correction 1: the reduction's inputs echoed with their structure — the measurement's echo, with what a reduction adds. */
-function effectiveOf(input: MeshReductionInput, measured: EffectiveSettings, sourceHull: Array<[number, number]>): EffectiveSettings {
+function effectiveOf(input: MeshReductionInput, measured: EffectiveSettings, sourceHull: Array<[number, number]>, plant: ReductionPlant | null): EffectiveSettings {
+  const amplitude = plant === 'echo-when-unset' && input.motionAmplitude === undefined ? null : input.motionAmplitude;
   const fit = (f: ArtFitBounds): ArtFitBounds => ({ minCoverage: f.minCoverage, maxOvershoot: f.maxOvershoot, maxUndercut: f.maxUndercut });
   return {
     ...measured,
@@ -1962,6 +2026,7 @@ function effectiveOf(input: MeshReductionInput, measured: EffectiveSettings, sou
     budget: { maxCandidates: input.budget.maxCandidates },
     ...(input.stopAfterAccepted === undefined ? {} : { stopAfterAccepted: input.stopAfterAccepted }),
     ...(input.boundaryRuns === undefined ? {} : { boundaryRuns: { maxVertices: input.boundaryRuns.maxVertices } }),
+    ...(amplitude === undefined ? {} : { motionAmplitude: amplitude }),
     ...(input.retriangulate === undefined ? {} : { retriangulate: input.retriangulate }),
     ...(input.removalOrder === undefined ? {} : { removalOrder: input.removalOrder }),
   };