rig-c 2.28.0 → 2.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-c",
-  "version": "2.28.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

@@ -379,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 ε. */
@@ -865,8 +875,11 @@ 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}]`;
@@ -1858,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 {
@@ -1875,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);
@@ -1883,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 } }), {
@@ -2387,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 }),
   };
 }