rig-c 2.31.2 → 2.32.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-c",
-  "version": "2.31.2",
+  "version": "2.32.1",
   "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/meshcompare.ts

@@ -95,7 +95,11 @@ import {
   type MotionReading,
   type MotionRowDetail,
   type MotionSchedule,
+  type OverBoundReport,
+  type OverBoundRequest,
+  type OverBoundRow,
   type ScheduleUsed,
+  type TriangleMaxima,
   type SourceMesh,
   type WorstSample,
 } from './meshquality.ts';
@@ -165,6 +169,17 @@ export interface MotionComparisonInput {
    * before any build is read, in the measurement's words. Echoed in `effective` when set, `null` included.
    */
   motionAmplitude?: MotionAmplitude | null;
+  /**
+   * Issue #1315: asks each candidate's report for where its motion rows broke — the samples over each declared
+   * `MQ_LOCAL_DEFORMATION` bound (the attachment's row and each measured region's), each with the frame of its worst
+   * value and the candidate's UV triangle that carries it, at most `maxSamples` per row, worst first, with the count
+   * of all of them; and each candidate triangle's worst value of every declared motion row over the selection frames
+   * (`triangles`: the over-bound triangles, or `all` with a reading). Nothing else moves: no row, verdict, acceptance
+   * or byte of a report without it. Left out, not asked; anything that is not an `OverBoundRequest` in full — `null`
+   * included, since asking for nothing is leaving the field out — is refused `COMPARE_INPUT_MISSING` naming the field,
+   * before any build is read. Echoed in `effective` when set.
+   */
+  overBound?: OverBoundRequest;
 }
 
 /**
@@ -173,7 +188,27 @@ export interface MotionComparisonInput {
  * 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';
+export type ComparePlant =
+  | 'amplitude-not-carried'
+  | 'null-read-as-left-out'
+  | 'amplitude-unvalidated'
+  | 'echo-when-unset'
+  | 'amplitude-gates-acceptance'
+  | OverBoundPlant;
+
+/**
+ * Issue #1315's faults in `overBound`, for the `mesh-compare` suite's negative controls: a listed sample's triangle
+ * taken from the reference's carrier rather than the candidate's; the samples listed in domain order rather than worst
+ * first; the total counted off the listed samples; the per-triangle table read over every frame rather than the
+ * selection's; the field echoed when left out; and the field not validated, so `null` and a malformed request pass.
+ */
+export type OverBoundPlant =
+  | 'over-bound-reference-carrier'
+  | 'over-bound-domain-order'
+  | 'over-bound-total-is-listed'
+  | 'over-bound-table-every-frame'
+  | 'over-bound-echo-when-unset'
+  | 'over-bound-unvalidated';
 
 // ---------------------------------------------------------------------------
 // fixed tolerances — the tree's own
@@ -286,6 +321,14 @@ function validateInput(input: MotionComparisonInput, plant: ComparePlant | null)
       throw err;
     }
   }
+  if (plant !== 'over-bound-unvalidated' && input.overBound !== undefined) {
+    // Issue #1315: a request in full, or the field left out. No count is assumed and no table is chosen for the caller.
+    const o: unknown = input.overBound;
+    const shape = "an OverBoundRequest { maxSamples, triangles }, or the field left out — null asks for nothing, which is what leaving it out says";
+    if (!isObject(o)) missing('overBound', o, shape);
+    if (!Number.isInteger(o.maxSamples) || (o.maxSamples as number) < 1) missing('overBound.maxSamples', o.maxSamples, 'a whole number >= 1 — the most over-bound samples listed per row; there is no default');
+    if (o.triangles !== 'over-bound' && o.triangles !== 'all') missing('overBound.triangles', o.triangles, "'over-bound' or 'all' — which triangles the per-triangle table lists; there is no default");
+  }
   const s = input.schedule;
   if (s === null) return;
   if (!isObject(s)) missing('schedule', s, 'a MotionSchedule, or null for no motion');
@@ -915,7 +958,9 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
 
   // --- motion ---------------------------------------------------------------------------------
   const schedule = input.schedule;
-  type Motion = { section: EvidenceSection & { schedule: ScheduleUsed }; perFrame: NonNullable<CandidateReport['perFrame']> } | null;
+  type Motion = { section: EvidenceSection & { schedule: ScheduleUsed }; perFrame: NonNullable<CandidateReport['perFrame']>; overBound: OverBoundReport | null } | null;
+  // Issue #1315: the request as the caller set it; `?? undefined` only matters under the unvalidated plant.
+  const overBound: OverBoundRequest | undefined = input.overBound ?? undefined;
   let motionOf: (b: Build, isReference: boolean) => Motion = () => null;
   if (schedule !== null) {
     const physicsConstraints = reference.doc.constraints.filter((c) => c.kind === 'physics').length;
@@ -958,6 +1003,9 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
       const posed = isReference ? posedRef : poseBuild(b.doc, order.map((i) => refs[i]), frames, walks);
       const built: Built[] = [];
       const perFrame: NonNullable<CandidateReport['perFrame']> = [];
+      // Issue #1315: kept for a candidate only, and only when asked — a call without the field does none of this.
+      const ask = isReference ? undefined : overBound;
+      const located: OverBoundReport | null = ask === undefined ? null : { selectionFrames: frames.filter((f) => f.ref.role === 'selection').length, rows: [], triangles: [] };
       order.forEach((i, k) => {
         const a = input.attachments[i];
         const ref = refs[i];
@@ -996,6 +1044,18 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
         const squash: Reading[] = [];
         const inversion: Reading[] = [];
         const folds: Array<{ triangle: number; frame: string }> = [];
+        // Issue #1315: each sample's worst distance over every frame and the frame of it (first in walk order); each
+        // triangle's worst reading of each row over the selection frames. Bookkeeping over values computed below anyway.
+        const nTri = mesh.triangles.length / 3;
+        const track = located !== null;
+        const sampleWorst = new Float64Array(track ? samples.length : 0).fill(-1);
+        const sampleFrame = new Int32Array(track ? samples.length : 0).fill(-1);
+        const triLocal = new Float64Array(track ? nTri : 0).fill(-1);
+        const triHi = new Float64Array(track ? nTri : 0).fill(-Infinity);
+        const triLo = new Float64Array(track ? nTri : 0).fill(Infinity);
+        const triStretchRead = new Uint8Array(track ? nTri : 0);
+        const triReversed = new Int32Array(track ? nTri : 0);
+        const triInversionRead = new Uint8Array(track ? nTri : 0);
         const setupWorld = posed.setup[k];
         const setupAreas = setupWorld === null ? [] : triangleAreas(setupWorld, mesh.triangles);
         const setupBand = setupWorld === null ? 0 : areaBand(setupAreas, setupWorld);
@@ -1007,6 +1067,7 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
             notDrawn.push(f.ref.id);
             return;
           }
+          const selected = track && (f.ref.role === 'selection' || plant === 'over-bound-table-every-frame');
           // Local deformation: the carried points, sample by sample.
           let worst = -1;
           let worstAt = -1;
@@ -1020,6 +1081,16 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
               worst = d;
               worstAt = j;
             }
+            if (track) {
+              if (d > sampleWorst[j]) {
+                sampleWorst[j] = d;
+                sampleFrame[j] = fi;
+              }
+              if (selected) {
+                const t = candCarrier[j]!.triangle;
+                if (d > triLocal[t]) triLocal[t] = d;
+              }
+            }
             for (let r = 0; r < a.regions.length; r++) {
               if (inRegion[r][j] && d > regionWorst[r].d) regionWorst[r] = { d, j };
             }
@@ -1046,9 +1117,16 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
             if (sv !== null) {
               if (hi === null || sv.max > hi.value) hi = { frame: fi, value: sv.max, at: { triangle: t } };
               if (lo === null || sv.min < lo.value) lo = { frame: fi, value: sv.min, at: { triangle: t } };
+              if (selected) {
+                triStretchRead[t] = 1;
+                if (sv.max > triHi[t]) triHi[t] = sv.max;
+                if (sv.min < triLo[t]) triLo[t] = sv.min;
+              }
             }
+            if (selected) triInversionRead[t] = 1;
             if (Math.abs(after[t]) <= band) continue;
             if (Math.sign(setupAreas[t]) !== Math.sign(after[t])) {
+              if (selected) triReversed[t]++;
               reversed++;
               if (firstReversed === -1) firstReversed = t;
               if (folding.has(ref.slot)) folds.push({ triangle: t, frame: f.ref.id });
@@ -1102,6 +1180,60 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
           // A slot `deformMayFold` names: the row holds no bound (A39 exempts it), keeps its count rather than zeroing it, and lists every fold.
           built.push(motionRow(plans.inversion, inversion, frames, schedule, notDrawn, folding.has(ref.slot) ? { folds, degenerateAtSetup } : { degenerateAtSetup }));
         }
+        if (located !== null && ask !== undefined) {
+          // Issue #1315: the samples over the local-deformation bound, per measured row, and the per-triangle tables.
+          const localBound = { op: '<=' as const, value: input.bounds.maxLocalDeformation };
+          const listed = (region: string | null, inside: readonly boolean[] | null): OverBoundRow => {
+            const over: Array<{ j: number; v: number }> = [];
+            for (let j = 0; j < samples.length; j++) {
+              if (sampleFrame[j] < 0 || (inside !== null && !inside[j])) continue;
+              const v = r6(sampleWorst[j]);
+              if (judged(v, localBound) === 'fail') over.push({ j, v });
+            }
+            if (plant !== 'over-bound-domain-order') over.sort((p, q) => q.v - p.v || p.j - q.j);
+            const kept = over.slice(0, ask.maxSamples);
+            return {
+              code: 'MQ_LOCAL_DEFORMATION',
+              attachment: ref,
+              region,
+              bound: localBound,
+              total: plant === 'over-bound-total-is-listed' ? kept.length : over.length,
+              samples: kept.map(({ j, v }) => {
+                const s = samples[j];
+                const c = plant === 'over-bound-reference-carrier' ? refCarrier[j]! : candCarrier[j]!;
+                return {
+                  at: s.pixel !== null ? { pixel: s.pixel, uv: s.uv } : { vertex: s.vertex ?? -1, uv: s.uv },
+                  frame: frames[sampleFrame[j]].ref,
+                  value: v,
+                  triangle: c.triangle,
+                  corners: [c.corners[0], c.corners[1], c.corners[2]],
+                };
+              }),
+            };
+          };
+          if (art >= a.minArtSamples) located.rows.push(listed(null, null));
+          const measuredRegions = a.regions
+            .map((r, ri) => ({ name: r.name, ri }))
+            .filter(({ ri }) => artIn(inRegion[ri]) >= a.regions[ri].minArtSamples)
+            .sort((p, q) => (p.name < q.name ? -1 : p.name > q.name ? 1 : 0));
+          for (const { name, ri } of measuredRegions) located.rows.push(listed(name, inRegion[ri]));
+          const table = (code: string, bound: { op: '<=' | '>='; value: number }, read: (t: number) => number | null): TriangleMaxima => {
+            const values: Array<{ triangle: number; value: number }> = [];
+            for (let t = 0; t < nTri; t++) {
+              const raw = read(t);
+              if (raw === null) continue;
+              const value = r6(raw);
+              if (ask.triangles === 'all' || judged(value, bound) === 'fail') values.push({ triangle: t, value });
+            }
+            values.sort((p, q) => (bound.op === '<=' ? q.value - p.value : p.value - q.value) || p.triangle - q.triangle);
+            return { code, attachment: ref, bound, values };
+          };
+          // Codes in the rows' order (ROW_ORDER: codes as strings); a row with no declared bound has no table.
+          if (setupWorld !== null && plans.inversion.bound !== null) located.triangles.push(table('MQ_INVERSION', plans.inversion.bound, (t) => (triInversionRead[t] === 1 ? triReversed[t] : null)));
+          if (art >= a.minArtSamples) located.triangles.push(table('MQ_LOCAL_DEFORMATION', localBound, (t) => (triLocal[t] >= 0 ? triLocal[t] : null)));
+          if (setupWorld !== null && plans.squash.bound !== null) located.triangles.push(table('MQ_SQUASH', plans.squash.bound, (t) => (triStretchRead[t] === 1 ? triLo[t] : null)));
+          if (setupWorld !== null && plans.stretch.bound !== null) located.triangles.push(table('MQ_STRETCH', plans.stretch.bound, (t) => (triStretchRead[t] === 1 ? triHi[t] : null)));
+        }
         // P7's opt-in table: each attachment-level row's value at every frame walked, null where none was taken.
         const label = (code: string): string => (order.length > 1 ? `${code}[${nameOf(ref)}]` : code);
         const table: Array<[string, Reading[]]> = [
@@ -1124,17 +1256,18 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
         const ref = refs[order[k]];
         grouped.push(...built.filter((x) => x.row.object.attachment === ref).sort((p, q) => ROW_ORDER(p.row, q.row)));
       }
-      return { section: { ...sectionOf(grouped), schedule: scheduleUsed }, perFrame };
+      return { section: { ...sectionOf(grouped), schedule: scheduleUsed }, perFrame, overBound: located };
     };
   }
   const referenceMotion = motionOf(reference, true);
   const candidateMotions = candidates.map((c) => motionOf(c, false));
-  const reportOf = (b: Build, geometry: { geometry: EvidenceSection | null; counts: MeshCounts | null }, measured: Motion): CandidateReport => {
+  const reportOf = (b: Build, geometry: { geometry: EvidenceSection | null; counts: MeshCounts | null }, measured: Motion, isCandidate: boolean): CandidateReport => {
     const motion = measured === null ? null : measured.section;
     // P6: the geometry verdict pass (every required row measured and passing), and — when motion is required — the motion verdict pass.
     const accepted = geometry.geometry !== null && geometry.geometry.verdict === 'pass' && (!input.motionRequired || (motion !== null && motion.verdict === 'pass'));
     const out: CandidateReport = { id: b.id, counts: geometry.counts, geometry: geometry.geometry, motion, accepted };
     if (input.perFrame && measured !== null) out.perFrame = measured.perFrame;
+    if (isCandidate && overBound !== undefined) out.overBound = measured === null ? null : measured.overBound;
     return out;
   };
   const effective: EffectiveSettings = {
@@ -1163,6 +1296,11 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
     schedule,
     budget: null,
     ...(amplitude === undefined ? (plant === 'echo-when-unset' ? { motionAmplitude: null } : {}) : { motionAmplitude: amplitude }),
+    ...(overBound === undefined
+      ? plant === 'over-bound-echo-when-unset'
+        ? { overBound: { maxSamples: 1, triangles: 'over-bound' as const } }
+        : {}
+      : { overBound: { maxSamples: overBound.maxSamples, triangles: overBound.triangles } }),
   };
   return {
     spec: MESH_QUALITY_REPORT_SPEC,
@@ -1171,8 +1309,8 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
     poser: schedule === null ? null : { kind: 'core', rigcVersion: readVersion() },
     motionRequired: input.motionRequired,
     sourceCounts: refGeometry.counts,
-    reference: reportOf(reference, refGeometry, referenceMotion),
-    candidates: candidates.map((c, i) => reportOf(c, candGeometry[i], candidateMotions[i])),
+    reference: reportOf(reference, refGeometry, referenceMotion, false),
+    candidates: candidates.map((c, i) => reportOf(c, candGeometry[i], candidateMotions[i], true)),
     termination: null,
   };
 }

package/src/meshquality.ts

@@ -547,10 +547,69 @@ export interface CandidateReport {
   accepted: boolean;
   /** Opt-in (P7): every row's value at every frame. Absent unless asked for. */
   perFrame?: Array<{ code: string; frame: string; value: number | null }>;
+  /**
+   * Issue #1315, a comparison's candidate only: present exactly when the input set `overBound` — the samples over each
+   * declared motion bound with the candidate triangle that carries them, and each triangle's worst value of each motion
+   * row over the selection frames. Null when no motion section was measured (no schedule). Absent otherwise.
+   */
+  overBound?: OverBoundReport | null;
   /** A `reduce` whose result exists: what the operation changed. Absent on a `measure` and when no mesh is returned. */
   changes?: ReductionChanges;
 }
 
+/**
+ * Issue #1315: what `MotionComparisonInput.overBound` asks for — how many over-bound samples each row lists at most,
+ * worst first (a whole number, 1 or more; no default), and which triangles the per-triangle table lists: those over
+ * the row's bound, or every triangle that has a reading. Echoed in `effective` when set.
+ */
+export interface OverBoundRequest {
+  maxSamples: number;
+  triangles: 'over-bound' | 'all';
+}
+
+/**
+ * One sample over a motion bound (issue #1315): the sample by §3's id — an art pixel of the mask grid, or a reference
+ * hull vertex — with its UV; the frame its worst value over every frame walked was taken at (the first such frame in
+ * walk order), whose `role` says selection, held out or baseline; that value; and the candidate's UV triangle that
+ * carries the sample, by index and by its three vertex indices.
+ */
+export interface OverBoundSample {
+  at: { pixel?: [number, number]; vertex?: number; uv: [number, number] };
+  frame: FrameRef;
+  value: number;
+  triangle: number;
+  corners: [number, number, number];
+}
+
+/** One sample-taken motion row with a declared bound (issue #1315): every sample over it counted, the worst listed. */
+export interface OverBoundRow {
+  code: string;
+  attachment: AttachmentRef;
+  region: string | null;
+  bound: { op: '<=' | '>='; value: number };
+  /** Samples whose worst value over every frame walked fails the bound — all of them, whether or not they are listed. */
+  total: number;
+  /** At most `maxSamples` of them: worst first, then in §3's domain order (art pixels row by row, then hull vertices). */
+  samples: OverBoundSample[];
+}
+
+/** Each candidate triangle's worst value of one motion row over the selection frames (issue #1315). */
+export interface TriangleMaxima {
+  code: string;
+  attachment: AttachmentRef;
+  bound: { op: '<=' | '>='; value: number };
+  /** Worst first, then triangle index; over-bound triangles only, or every triangle with a reading, as asked. */
+  values: Array<{ triangle: number; value: number }>;
+}
+
+/** Issue #1315's report block on a compared candidate. */
+export interface OverBoundReport {
+  /** How many frames the selection named and the schedule walked — the frames `triangles` reads; 0 leaves every table empty. */
+  selectionFrames: number;
+  rows: OverBoundRow[];
+  triangles: TriangleMaxima[];
+}
+
 /**
  * What a reduction changed, counted rather than described — the figures the
  * contract says are reported (§6, P18 and P19) and that no geometry row carries.
@@ -635,6 +694,8 @@ export interface EffectiveSettings {
   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;
+  /** A comparison's `overBound`, echoed when the input set it (issue #1315); absent otherwise. */
+  overBound?: OverBoundRequest;
 }
 
 export interface MeshCounts {
@@ -2436,6 +2497,7 @@ function effectiveJson(e: EffectiveSettings): Json {
     ...(e.retriangulate === undefined ? {} : { retriangulate: e.retriangulate }),
     ...(e.removalOrder === undefined ? {} : { removalOrder: e.removalOrder }),
     ...(e.skinning === undefined ? {} : { skinning: skinningEchoJson(e.skinning) }),
+    ...(e.overBound === undefined ? {} : { overBound: { maxSamples: e.overBound.maxSamples, triangles: e.overBound.triangles } }),
   };
 }
 
@@ -2557,6 +2619,7 @@ function candidateJson(c: CandidateReport): Json {
     accepted: c.accepted,
   };
   if (c.perFrame !== undefined) out.perFrame = c.perFrame.map((p) => ({ code: p.code, frame: p.frame, value: p.value }));
+  if (c.overBound !== undefined) out.overBound = overBoundJson(c.overBound);
   if (c.changes !== undefined) {
     const k = c.changes;
     out.changes = {
@@ -2585,6 +2648,29 @@ function candidateJson(c: CandidateReport): Json {
   return out;
 }
 
+function overBoundJson(o: OverBoundReport | null): Json {
+  if (o === null) return null;
+  const boundJson = (b: { op: '<=' | '>='; value: number }): Json => ({ op: b.op, value: b.value });
+  return {
+    selectionFrames: o.selectionFrames,
+    rows: o.rows.map((r) => ({
+      code: r.code,
+      attachment: attachmentJson(r.attachment),
+      region: r.region,
+      bound: boundJson(r.bound),
+      total: r.total,
+      samples: r.samples.map((x) => {
+        const at: { [key: string]: Json } = {};
+        if (x.at.pixel !== undefined) at.pixel = pair(x.at.pixel);
+        if (x.at.vertex !== undefined) at.vertex = x.at.vertex;
+        at.uv = pair(x.at.uv);
+        return { at, frame: frameRefJson(x.frame), value: x.value, triangle: x.triangle, corners: [x.corners[0], x.corners[1], x.corners[2]] };
+      }),
+    })),
+    triangles: o.triangles.map((t) => ({ code: t.code, attachment: attachmentJson(t.attachment), bound: boundJson(t.bound), values: t.values.map((v) => ({ triangle: v.triangle, value: v.value })) })),
+  };
+}
+
 const notReachedJson = (s: StopNotReached | undefined): { [key: string]: Json } =>
   s === undefined ? {} : { stopAfterAccepted: { requested: s.requested, acceptedSteps: s.acceptedSteps } };
 

package/src/meshreduce.ts

@@ -160,6 +160,8 @@ import {
   type Termination,
 } from './meshquality.ts';
 import { artRastersOf, stepRastersOf, type ArtRasters, type StepRasters } from './meshrasters.ts';
+import { areaBand, triangleAreas } from './areaband.ts';
+import { cropToSpineY } from './transform.ts';
 import {
   skinningContract,
   SkinningCarry,
@@ -1262,43 +1264,154 @@ function addVertex(run: Run, p: Pt): number {
   return id;
 }
 
+/**
+ * The two triangles a split of the edge a–b at the new vertex `m` makes of `tri`, winding kept, or null when `tri`
+ * does not have that edge — the one rule `splitEdge` writes and `degenerateInsertion` reads (issue #1311).
+ */
+function splitPieces(tri: readonly [number, number, number], a: number, b: number, m: number): [[number, number, number], [number, number, number]] | null {
+  const i = tri.indexOf(a);
+  const j = tri.indexOf(b);
+  if (i === -1 || j === -1) return null;
+  // Rotate so the edge is the triangle's first two corners, in its own winding.
+  const r = (j - i + 3) % 3 === 1 ? i : j;
+  const x = tri[r];
+  const y = tri[(r + 1) % 3];
+  const c = tri[(r + 2) % 3];
+  return [[x, m, c], [m, y, c]];
+}
+
 /** Split the edge between working ids a and b at `p`: each triangle on it becomes two, winding kept. */
 function splitEdge(run: Run, a: number, b: number, p: Pt): void {
   const m = addVertex(run, p);
   const next: Array<[number, number, number]> = [];
   for (const tri of run.work.triangles) {
-    const i = tri.indexOf(a);
-    const j = tri.indexOf(b);
-    if (i === -1 || j === -1) {
-      next.push(tri);
-      continue;
-    }
-    // Rotate so the edge is the triangle's first two corners, in its own winding.
-    const r = (j - i + 3) % 3 === 1 ? i : j;
-    const x = tri[r];
-    const y = tri[(r + 1) % 3];
-    const c = tri[(r + 2) % 3];
-    next.push([x, m, c], [m, y, c]);
+    const pieces = splitPieces(tri, a, b, m);
+    if (pieces === null) next.push(tri);
+    else next.push(...pieces);
   }
   run.work.triangles = next;
 }
 
-/** Insert `p` into the working triangle that holds it: on an edge, that edge is split; inside, the triangle becomes three. */
-function insertPoint(run: Run, p: Pt): boolean {
+/** Where `insertPoint` puts `p`: on an edge of the working triangle that holds it, inside that triangle, or nowhere. */
+type Placement = { kind: 'edge'; a: number; b: number } | { kind: 'inside'; tri: [number, number, number] } | null;
+
+function placementOf(run: Run, p: Pt): Placement {
   const { work } = run;
   for (const tri of work.triangles) {
     const l = barycentric(p, work.pos[tri[0]], work.pos[tri[1]], work.pos[tri[2]]);
     if (l === null || Math.min(...l) < -1e-9) continue;
     const onEdge = l.findIndex((v) => Math.abs(v) <= 1e-9);
-    if (onEdge !== -1) {
-      splitEdge(run, tri[(onEdge + 1) % 3], tri[(onEdge + 2) % 3], p);
-      return true;
-    }
-    const m = addVertex(run, p);
-    work.triangles = work.triangles.flatMap((t): Array<[number, number, number]> => (t === tri ? [[tri[0], tri[1], m], [tri[1], tri[2], m], [tri[2], tri[0], m]] : [t]));
-    return true;
+    if (onEdge !== -1) return { kind: 'edge', a: tri[(onEdge + 1) % 3], b: tri[(onEdge + 2) % 3] };
+    return { kind: 'inside', tri };
   }
-  return false;
+  return null;
+}
+
+/** The three triangles an insertion of the new vertex `m` inside `tri` makes of it — `insertPoint`'s rule. */
+function fanPieces(tri: readonly [number, number, number], m: number): Array<[number, number, number]> {
+  return [[tri[0], tri[1], m], [tri[1], tri[2], m], [tri[2], tri[0], m]];
+}
+
+/** Insert `p` where `placementOf` put it: on an edge, that edge is split; inside, the triangle becomes three. */
+function insertPoint(run: Run, p: Pt, at: Exclude<Placement, null>): void {
+  const { work } = run;
+  if (at.kind === 'edge') {
+    splitEdge(run, at.a, at.b, p);
+    return;
+  }
+  const m = addVertex(run, p);
+  work.triangles = work.triangles.flatMap((t): Array<[number, number, number]> => (t === at.tri ? fanPieces(at.tri, m) : [t]));
+}
+
+/** The vertex id the degenerate check reads for the vertex an insertion would add, before it exists. */
+const NEW_VERTEX = -1;
+
+/** A triangle an insertion would write that `MQ_DEGENERATE` reads as degenerate (issue #1311). */
+interface DegenerateWrite {
+  /** Working ids, `NEW_VERTEX` for the inserted one, in the triangle's own winding. */
+  corners: [number, number, number];
+  /** The smallest magnitude of its area over the three corners it can be read from, px². */
+  area: number;
+  /** `areaBand` of the mesh the insertion would leave, px². */
+  band: number;
+}
+
+/**
+ * Issue #1311: the first triangle an insertion of `p` would write whose area `MQ_DEGENERATE` reads as degenerate, or
+ * null. Read as the row reads it, over the mesh the insertion would leave: every point in the art frame's world (y up,
+ * `cropToSpineY` on the frame's height), every triangle's area by `triangleAreas`, and the band by `areaBand` over all of
+ * them — the larger of 1e-6 of the largest triangle and the float32 noise bound of the coordinates. The row reads a
+ * triangle from its smallest canonical index, which is not known before the mesh is canonicalised, so a fresh triangle
+ * is read from each of its three corners and the smallest magnitude is the one compared: a triangle that any reading
+ * puts within the band is refused. `fresh` uses `NEW_VERTEX` for the inserted vertex; `replaced` are the triangles it
+ * takes the place of.
+ */
+function degenerateInsertion(run: Run, p: Pt, replaced: ReadonlySet<readonly number[]>, fresh: ReadonlyArray<[number, number, number]>): DegenerateWrite | null {
+  const { work } = run;
+  const height = run.input.art.frame.height;
+  const slot = new Map<number, number>();
+  const world: number[] = [];
+  for (let id = 0; id < work.pos.length; id++) {
+    if (!work.alive[id]) continue;
+    slot.set(id, world.length / 2);
+    world.push(work.pos[id][0], cropToSpineY(work.pos[id][1], height));
+  }
+  slot.set(NEW_VERTEX, world.length / 2);
+  world.push(p[0], cropToSpineY(p[1], height));
+  const flat: number[] = [];
+  for (const tri of work.triangles) if (!replaced.has(tri)) for (const id of tri) flat.push(slot.get(id)!);
+  for (const tri of fresh) for (const id of tri) flat.push(slot.get(id)!);
+  const band = areaBand(triangleAreas(world, flat), world) * (run.plant === 'degenerate-band-widened' ? 1000 : 1);
+  for (const tri of fresh) {
+    const [i, j, k] = tri.map((id) => slot.get(id)!);
+    const area = Math.min(...triangleAreas(world, [i, j, k, j, k, i, k, i, j]).map(Math.abs));
+    if (area <= band) return { corners: tri, area, band };
+  }
+  return null;
+}
+
+/**
+ * Issue #1311: the refinement's stop when the insertion its rule chose would write a triangle `MQ_DEGENERATE` refuses —
+ * by name: the target row, the region, the insertion, the triangle's corners with their distance from the region's
+ * polygon, its area and the band required. The refinement writes no triangle the row refuses: a refined source that
+ * failed that row could take no step at all, and the failure would name a triangle rather than the insertion that made
+ * it.
+ */
+function degenerateStop(run: Run, canon: Canonical, target: MeasureRow, region: RefinementRegion, what: string, p: Pt, found: DegenerateWrite): PhaseEnd {
+  const corner = (id: number): string => {
+    const at = id === NEW_VERTEX ? p : run.work.pos[id];
+    const name = id === NEW_VERTEX ? 'the inserted vertex' : `vertex ${canon.indexOf.get(id)!}`;
+    const where = inClosedPolygon(at, region.polygon) ? 'in the polygon' : `${r6(distanceToBoundary(at, region.polygon))} px from the polygon`;
+    return `${name} (${at[0]}, ${at[1]}), ${where}`;
+  };
+  return {
+    kind: 'stuck',
+    constraint:
+      `${rowName(target)} (${what} at (${p[0]}, ${p[1]}) would write the triangle of ${found.corners.map(corner).join('; ')} — ` +
+      `area ${r6(found.area)} px², which MQ_DEGENERATE reads as degenerate: required an area above the row's band ${r6(found.band)} px² ` +
+      `(the larger of the float32 noise bound of the mesh's coordinates and 1e-6 of its largest triangle); ` +
+      `region "${region.name}" has a ${region.transition} px band, and the refinement writes no triangle the row refuses)`,
+  };
+}
+
+/** The triangles a split of a–b replaces, and what it writes in their place with `NEW_VERTEX` inserted. */
+function splitPlan(run: Run, a: number, b: number): { replaced: Set<readonly number[]>; fresh: Array<[number, number, number]> } {
+  const replaced = new Set<readonly number[]>();
+  const fresh: Array<[number, number, number]> = [];
+  for (const tri of run.work.triangles) {
+    const pieces = splitPieces(tri, a, b, NEW_VERTEX);
+    if (pieces === null) continue;
+    replaced.add(tri);
+    fresh.push(...pieces);
+  }
+  return { replaced, fresh };
+}
+
+/** Issue #1311: what a split of a–b at `p` would write that the row refuses, or null — always null under the control's plant. */
+function degenerateSplit(run: Run, a: number, b: number, p: Pt): DegenerateWrite | null {
+  if (run.plant === 'refinement-writes-degenerate') return null;
+  const { replaced, fresh } = splitPlan(run, a, b);
+  return degenerateInsertion(run, p, replaced, fresh);
 }
 
 type PhaseEnd =
@@ -1346,7 +1459,15 @@ export type ReductionPlant =
   | 'floor-half-a-pixel-short'
   | RetriangulationPlant
   | OrderPlant
-  | AmplitudePlant;
+  | AmplitudePlant
+  | RefinementPlant;
+
+/**
+ * Issue #1311's faults in the refinement: the insertion its rule chose written without asking whether it writes a
+ * triangle `MQ_DEGENERATE` refuses — the refinement as it was before the check; and the check reading the row's band
+ * a thousand times as wide, so it refuses insertions the row would pass.
+ */
+export type RefinementPlant = 'refinement-writes-degenerate' | 'degenerate-band-widened';
 
 /**
  * Issue #1283's faults in the triangulation post-pass: the pass run on a call that did not opt in; the pass skipped
@@ -1400,7 +1521,9 @@ export type AttemptObserver = (attempt: AttemptRecord) => void;
  * `MQ_TRANSITION` that the refinement can act on passes. One insertion per
  * measurement: the first failing region row in report order has its worst edge
  * split. A band no edge lies in leaves `MQ_TRANSITION` not-measurable (B1's
- * definition) and is not something an insertion is aimed at.
+ * definition) and is not something an insertion is aimed at. An insertion that
+ * would write a triangle `MQ_DEGENERATE` refuses is not made: the refinement
+ * stops there by name (issue #1311, `degenerateStop`).
  */
 function refineRegions(run: Run): PhaseEnd {
   const regions = new Map(run.input.targets.regions.map((r) => [r.name, r]));
@@ -1416,7 +1539,16 @@ function refineRegions(run: Run): PhaseEnd {
     const region = regions.get(target.object.region!)!;
     if (target.state === 'not-measurable') {
       const p: Pt = [r6(region.polygon[0][0]), r6(region.polygon[0][1])];
-      if (!insertPoint(run, p)) return { kind: 'stuck', constraint: `${rowName(target)} (the refinement found no triangle holding the region's first vertex)` };
+      const at = placementOf(run, p);
+      if (at === null) return { kind: 'stuck', constraint: `${rowName(target)} (the refinement found no triangle holding the region's first vertex)` };
+      const found =
+        run.plant === 'refinement-writes-degenerate'
+          ? null
+          : at.kind === 'edge'
+            ? degenerateSplit(run, at.a, at.b, p)
+            : degenerateInsertion(run, p, new Set([at.tri]), fanPieces(at.tri, NEW_VERTEX));
+      if (found !== null) return degenerateStop(run, canon, target, region, `inserting region "${region.name}"'s first vertex`, p, found);
+      insertPoint(run, p, at);
       followSkinning(run, 'insertion');
       if (accept(run, 'insertion', [])) return { kind: 'replayed' };
       continue;
@@ -1432,6 +1564,8 @@ function refineRegions(run: Run): PhaseEnd {
       if (inRegionOrBand(run.work.pos[outer], region)) continue;
       const q = outerSplit(run.work.pos[inner], run.work.pos[outer], region);
       if (q === null) continue;
+      const found = degenerateSplit(run, a, b, q);
+      if (found !== null) return degenerateStop(run, canon, target, region, `splitting edge ${ra}–${rb} where it leaves region "${region.name}"'s band`, q, found);
       splitEdge(run, a, b, q);
       followSkinning(run, 'insertion');
       exited = true;
@@ -1462,6 +1596,8 @@ function refineRegions(run: Run): PhaseEnd {
     }
     const p = splitPoint(run.work.pos[a], run.work.pos[b], region);
     if (p === null) return { kind: 'stuck', constraint: `${rowName(target)} (the refinement found no point of edge ${ra}–${rb} strictly between its ends inside region "${region.name}" or its band)` };
+    const found = degenerateSplit(run, a, b, p);
+    if (found !== null) return degenerateStop(run, canon, target, region, `splitting edge ${ra}–${rb} inside region "${region.name}" or its band`, p, found);
     splitEdge(run, a, b, p);
     followSkinning(run, 'insertion');
     if (accept(run, 'insertion', [])) return { kind: 'replayed' };