rig-c 2.30.0 → 2.31.1

package/src/meshreduce.ts

@@ -79,6 +79,17 @@
  * measurements' rows (`amplitudeOf`) — so the mesh and every step are the
  * call's without it.
  *
+ * ## The skinning residual (issue #1295, opt-in)
+ *
+ * With `targets.skinning` and a number for its `maxResidual`, every removal,
+ * boundary run and post-pass whose required rows all pass is also held to
+ * `MQ_SKINNING_RESIDUAL` against the call's own source — the original, never a
+ * previous step — and refused by name when it is over; the refinement's outcome
+ * is held to it before any removal. The value is carried per sample
+ * (`SkinningCarry`, `src/meshskinning.ts`), so a step recomputes only the samples
+ * of the triangles it changed; the result's own measurement reads the row in
+ * full. Left out, nothing here reads it and the call is the one it was.
+ *
  * 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,
@@ -149,6 +160,18 @@ import {
   type Termination,
 } from './meshquality.ts';
 import { artRastersOf, stepRastersOf, type ArtRasters, type StepRasters } from './meshrasters.ts';
+import {
+  skinningContract,
+  SkinningCarry,
+  validateReductionSkinning,
+  skinningResidual,
+  type CarryCheck,
+  type CarryPlant,
+  type CarryReading,
+  type CarryTally,
+  type SkinningMeasureArgs,
+  type SkinningResidualInput,
+} from './meshskinning.ts';
 
 // ---------------------------------------------------------------------------
 // the result
@@ -319,6 +342,8 @@ function validateReduction(input: MeshReductionInput, plant: ReductionPlant | nu
   // 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);
+  // Issue #1295: refused before any work in the measurement's own words, under `targets.skinning`.
+  validateReductionSkinning(who, t.skinning);
   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;
@@ -405,6 +430,98 @@ function edgeKey(a: number, b: number): string {
   return a < b ? `${a},${b}` : `${b},${a}`;
 }
 
+/**
+ * Issue #1307: an undirected edge as one number, `min * n + max`, for ids below `n` — the key every edge set on the
+ * removal and boundary-run paths is held in, where `edgeKey` built a string per edge. Exact below 2^53, so for any
+ * `n` up to 94,906,265.
+ */
+function pairKey(a: number, b: number, n: number): number {
+  return a < b ? a * n + b : b * n + a;
+}
+
+/**
+ * Issue #1307: the edges `fresh`'s triangles hold that no triangle of `old` holds, each once, in the order `fresh`
+ * holds them (triangle by triangle, corner k to k + 1) — the order condition (b) reads them in and names the first
+ * over `weightJump`. Keyed by number over ids below `n`, and only the keys `fresh` holds are looked for in `old`.
+ * `addedEdgesByString` is the construction it replaced, kept as the one it is held equal to.
+ */
+function addedEdges(old: ReadonlyArray<readonly number[]>, fresh: ReadonlyArray<readonly number[]>, n: number): Array<[number, number]> {
+  const wanted = new Set<number>();
+  for (const t of fresh) for (let k = 0; k < 3; k++) wanted.add(pairKey(t[k], t[(k + 1) % 3], n));
+  const held = new Set<number>();
+  for (const t of old) {
+    for (let k = 0; k < 3; k++) {
+      const key = pairKey(t[k], t[(k + 1) % 3], n);
+      if (wanted.has(key)) held.add(key);
+    }
+  }
+  const added: Array<[number, number]> = [];
+  const seen = new Set<number>();
+  for (const t of fresh) {
+    for (let k = 0; k < 3; k++) {
+      const key = pairKey(t[k], t[(k + 1) % 3], n);
+      if (held.has(key) || seen.has(key)) continue;
+      seen.add(key);
+      added.push([t[k], t[(k + 1) % 3]]);
+    }
+  }
+  return added;
+}
+
+/** The string-keyed construction `addedEdges` replaced (issue #1307), run only by the edge-set audit. */
+function addedEdgesByString(old: ReadonlyArray<readonly number[]>, fresh: ReadonlyArray<readonly number[]>): Array<[number, number]> {
+  const had = new Set<string>();
+  for (const t of old) for (let k = 0; k < 3; k++) had.add(edgeKey(t[k], t[(k + 1) % 3]));
+  const added: Array<[number, number]> = [];
+  const seen = new Set<string>();
+  for (const t of fresh) {
+    for (let k = 0; k < 3; k++) {
+      const key = edgeKey(t[k], t[(k + 1) % 3]);
+      if (had.has(key) || seen.has(key)) continue;
+      seen.add(key);
+      added.push([t[k], t[(k + 1) % 3]]);
+    }
+  }
+  return added;
+}
+
+/**
+ * Issue #1307's audit, for the `mesh-compare` suite's control: every edge set the removal and boundary-run paths
+ * build is built a second time the string-keyed way it was before the issue and compared — the added edges as a list
+ * (membership and order, the order condition (b) reads), the triangulation's edge set the protected edges are looked
+ * up in as a set (its order is never read). A difference is recorded, not thrown, so the control reads every one.
+ * `plant` is the fault applied to the numeric construction before the comparison: one edge dropped from each list
+ * and each set, or each added list of two or more reversed. With the audit and no plant, the call's result is the
+ * call's without it.
+ */
+export interface EdgeSetAudit {
+  plant?: 'drop-one' | 'reorder';
+  /** Added-edge lists compared, and the edges in them. */
+  addedLists: number;
+  addedEdges: number;
+  /** Lists among them whose order a difference could move — two edges or more. */
+  orderedLists: number;
+  /** Triangulation edge sets compared (one per operation reaching the protected-edge check), and the edges in them. */
+  edgeSets: number;
+  edgeSetEdges: number;
+  /** Each difference found, named; the first few in full. */
+  differences: string[];
+}
+
+/** One added-edge list read, through the audit when there is one: the plant applied, then the string construction compared. */
+function auditedAdded(audit: EdgeSetAudit | null, where: string, added: Array<[number, number]>, byString: () => Array<[number, number]>): Array<[number, number]> {
+  if (audit === null) return added;
+  let read = added;
+  if (audit.plant === 'drop-one' && read.length > 0) read = read.slice(0, -1);
+  if (audit.plant === 'reorder' && read.length > 1) read = [...read].reverse();
+  const want = byString();
+  audit.addedLists++;
+  audit.addedEdges += want.length;
+  if (want.length > 1) audit.orderedLists++;
+  if (JSON.stringify(read) !== JSON.stringify(want)) audit.differences.push(`${where}: added edges ${JSON.stringify(read)} against the string construction's ${JSON.stringify(want)}`);
+  return read;
+}
+
 // ---------------------------------------------------------------------------
 // the working mesh — vertices by stable id: source index, then insertion order
 // ---------------------------------------------------------------------------
@@ -798,11 +915,61 @@ interface Run {
   keyed: Map<number, { animation: string; ref: AttachmentRef; key: number; time: number }>;
   protectedVertices: Set<number>;
   protectedEdges: Array<[number, number]>;
-  sourceEdges: Set<string>;
+  /** The source's edges, `pairKey` over `work.nSource` (issue #1307). */
+  sourceEdges: Set<number>;
+  /** Issue #1307's audit of the edge sets, or null. */
+  edgeAudit: EdgeSetAudit | null;
   /** The art's rasters, taken once for the call and read by every measurement in it (issue #1240). */
   rasters: ArtRasters;
   /** The step state each removal and insertion is measured through, carried from the last measurement (issue #1246); null measures every step in full. */
   stepRasters: StepRasters | null;
+  /** Issue #1295: the residual every step is held to, or null when the call did not declare a bound for it. */
+  skinning: SkinningRun | null;
+  /** Issue #1295: the controls' faults and inspector, or null. */
+  hooks: SkinningHooks | null;
+}
+
+/**
+ * Issue #1295: the residual a reduction's steps are vetoed by — the bound, the measurement input the result's own row
+ * is read with, and either the carried state (`SkinningCarry`), a reading the admission could not measure (every step
+ * is then blocked by it), or neither, under the full-recompute control, which measures each candidate whole.
+ */
+interface SkinningRun {
+  bound: number;
+  input: SkinningResidualInput;
+  carry: SkinningCarry | null;
+  unmeasured: CarryReading | null;
+  args: Omit<SkinningMeasureArgs, 'candidate'>;
+}
+
+/**
+ * Issue #1295's faults, for the `mesh-compare` suite's controls: the carried state's own (`CarryPlant`); the residual
+ * measured whole on every trial — not a fault, the path the carried state is held equal to and the cost is measured
+ * against; the post-pass taken without the residual's recheck; `effective` echoing `targets.skinning: null` for a
+ * call that left it out; and a residual refusal read as the end of the search rather than one refusal among others.
+ */
+export type SkinningVetoPlant = CarryPlant | 'full-recompute' | 'post-pass-unchecked' | 'echo-when-unset' | 'veto-ends-search';
+
+/** One decision the residual took part in, as a control reads it (issue #1295). */
+export interface SkinningInspection {
+  phase: 'insertion' | 'removal' | 'boundary-run' | 'delaunay';
+  /** `candidatesTried` when it was decided. */
+  step: number;
+  /** Whether the working mesh now holds the trial (an insertion always does). */
+  accepted: boolean;
+  /** The residual's reading of the trial. */
+  reading: CarryReading;
+  /** The carried state's work so far; null under the full-recompute control. */
+  tally: CarryTally | null;
+  memoryBytes: () => number;
+  /** The carried state as it now stands held to the full recompute over the working mesh as it now stands; null under the full-recompute control. */
+  check: () => CarryCheck | null;
+}
+
+/** What a control hands `reduceMeshWith` for issue #1295: a fault, and a callback after every decision the residual took part in. */
+export interface SkinningHooks {
+  plant?: SkinningVetoPlant;
+  inspect?: (inspection: SkinningInspection) => void;
 }
 
 /**
@@ -826,10 +993,76 @@ function measureAgainstTargets(run: Run, mesh: SourceMesh, id: string, final = f
     boneOrder: input.boneOrder,
     preset: input.preset,
     ...amplitudeOf(run.input, run.plant, final),
+    ...(final ? skinningOfResult(run) : {}),
   };
   return run.stepRasters === null ? measureMeshQualityWith(measureInput, run.rasters) : measureMeshQualityStep(measureInput, run.stepRasters);
 }
 
+/**
+ * Issue #1295: what the result's own measurement is handed as `skinning` — the input's envelope and bound against the
+ * call's own source, so the report's row is the measurement's, written as `measureMeshQuality` writes it; `null` as
+ * `null`; nothing when the field was left out. No other measurement of the call carries it: the steps read the
+ * carried state.
+ */
+function skinningOfResult(run: Run): { skinning?: SkinningResidualInput | null } {
+  const declared = run.input.targets.skinning;
+  if (declared === undefined) return {};
+  if (declared === null) return { skinning: null };
+  return { skinning: skinningInputOf(run.input) };
+}
+
+function skinningInputOf(input: MeshReductionInput): SkinningResidualInput {
+  const declared = input.targets.skinning!;
+  return { source: { id: 'source', mesh: input.source }, envelope: declared.envelope, maxResidual: declared.maxResidual, deform: input.deform };
+}
+
+/**
+ * Issue #1295: the residual of the working mesh as it now stands — a carried trial, left pending until `settleSkinning`;
+ * under the full-recompute control, the measurement over the canonical candidate; or the admission's reading when it
+ * could not measure.
+ */
+function skinningTrial(run: Run, canonical: () => SourceMesh): CarryReading {
+  const sk = run.skinning!;
+  if (sk.unmeasured !== null) return sk.unmeasured;
+  if (sk.carry === null) {
+    const reading = skinningResidual({ ...sk.args, candidate: canonical() });
+    return reading.state === 'measured' ? { state: 'measured', value: reading.value } : { state: reading.state, reason: reading.reason };
+  }
+  return sk.carry.trial(run.work.triangles);
+}
+
+/** Issue #1295: the residual's reading as the name a refusal carries — `rowName`'s form — or null when it is within the bound. */
+function skinningVeto(sk: SkinningRun, reading: CarryReading): string | null {
+  if (reading.state === 'measured') return reading.value <= sk.bound ? null : `MQ_SKINNING_RESIDUAL: ${reading.value} against <= ${sk.bound}`;
+  return `MQ_SKINNING_RESIDUAL: ${reading.state} — ${reading.reason}`;
+}
+
+/** Issue #1295: keep or undo a pending trial, then let a control read the decision. The working mesh is already the one decided on. */
+function settleSkinning(run: Run, keep: boolean, phase: SkinningInspection['phase'], reading: CarryReading): void {
+  const carry = run.skinning?.carry ?? null;
+  if (carry !== null && run.skinning!.unmeasured === null) {
+    if (keep) carry.commit();
+    else carry.rollback();
+  }
+  const inspect = run.hooks?.inspect;
+  if (inspect === undefined) return;
+  inspect({
+    phase,
+    step: run.steps,
+    accepted: keep,
+    reading,
+    tally: carry === null ? null : { ...carry.tally },
+    memoryBytes: () => (carry === null ? 0 : carry.memoryBytes()),
+    check: () => (carry === null ? null : carry.compareWithFull(canonicalise(run.work, run.sourceTurn, run.boneRank).mesh)),
+  });
+}
+
+/** Issue #1295: an operation the residual does not decide — a refinement insertion, or a step a plant takes unmeasured — carried so the state follows the working mesh. */
+function followSkinning(run: Run, phase: SkinningInspection['phase']): void {
+  if (run.skinning === null || run.skinning.carry === null || run.skinning.unmeasured !== null) return;
+  settleSkinning(run, true, phase, run.skinning.carry.trial(run.work.triangles));
+}
+
 /**
  * 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
@@ -1163,6 +1396,7 @@ function refineRegions(run: Run): PhaseEnd {
     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)` };
+      followSkinning(run, 'insertion');
       if (accept(run, 'insertion', [])) return { kind: 'replayed' };
       continue;
     }
@@ -1178,6 +1412,7 @@ function refineRegions(run: Run): PhaseEnd {
       const q = outerSplit(run.work.pos[inner], run.work.pos[outer], region);
       if (q === null) continue;
       splitEdge(run, a, b, q);
+      followSkinning(run, 'insertion');
       exited = true;
       break;
     }
@@ -1207,6 +1442,7 @@ 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)` };
     splitEdge(run, a, b, p);
+    followSkinning(run, 'insertion');
     if (accept(run, 'insertion', [])) return { kind: 'replayed' };
   }
 }
@@ -1215,8 +1451,17 @@ function refineRegions(run: Run): PhaseEnd {
 // reduction (§1, §6)
 // ---------------------------------------------------------------------------
 
-/** One removal tried: the working triangles after it and the edges it added, or the structural reason it cannot be made. */
-function removalOf(work: Work, v: number): { triangles: Array<[number, number, number]>; added: Array<[number, number]> } | { blocked: string } {
+/**
+ * One removal tried: the working triangles after it and the edges it added — read through `added()`, built only when
+ * read (issue #1307) — or the structural reason it cannot be made.
+ */
+type Removal = { triangles: Array<[number, number, number]>; added: () => Array<[number, number]> } | { blocked: string };
+
+/**
+ * One removal made on `work`'s triangles: the triangles after it — every triangle not touching `v` as it was, the
+ * same tuple, then the hole's new ones, `fresh` — or the structural reason it cannot be made.
+ */
+function removalStep(work: Work, v: number): { triangles: Array<[number, number, number]>; fresh: Array<[number, number, number]> } | { blocked: string } {
   const star = work.triangles.filter((t) => t.includes(v));
   const next = new Map<number, number>();
   const incoming = new Set<number>();
@@ -1257,19 +1502,16 @@ function removalOf(work: Work, v: number): { triangles: Array<[number, number, n
   } else if (!boundary) {
     return { blocked: `retriangulation: vertex ${v} has fewer than three neighbours` };
   }
-  const old = new Set<string>();
-  for (const t of work.triangles) for (let k = 0; k < 3; k++) old.add(edgeKey(t[k], t[(k + 1) % 3]));
-  const added: Array<[number, number]> = [];
-  const seen = new Set<string>();
-  for (const t of fresh) {
-    for (let k = 0; k < 3; k++) {
-      const key = edgeKey(t[k], t[(k + 1) % 3]);
-      if (old.has(key) || seen.has(key)) continue;
-      seen.add(key);
-      added.push([t[k], t[(k + 1) % 3]]);
-    }
-  }
-  return { triangles: [...rest, ...fresh], added };
+  return { triangles: [...rest, ...fresh], fresh };
+}
+
+/** `removalStep` with the edges it adds: those of the hole's new triangles no triangle before it holds, in their order. */
+function removalOf(work: Work, v: number, audit: EdgeSetAudit | null = null): Removal {
+  const step = removalStep(work, v);
+  if ('blocked' in step) return step;
+  const old = work.triangles;
+  const n = work.alive.length;
+  return { triangles: step.triangles, added: () => auditedAdded(audit, `removing ${v}`, addedEdges(old, step.fresh, n), () => addedEdgesByString(old, step.fresh)) };
 }
 
 /** L1 difference of two weight vectors over the bones they name. */
@@ -1306,10 +1548,10 @@ function loadOrder(run: Run): { order: number[]; load: Map<number, number> } {
   const order: number[] = [];
   for (let v = 0; v < work.nSource; v++) {
     if (!work.alive[v] || run.protectedVertices.has(v)) continue;
-    const step = removalOf(work, v);
+    const step = removalOf(work, v, run.edgeAudit);
     let most = 0;
     if ('blocked' in step) most = Infinity;
-    else for (const [a, b] of step.added) most = Math.max(most, edgeLoad(work, a, b));
+    else for (const [a, b] of step.added()) most = Math.max(most, edgeLoad(work, a, b));
     load.set(v, most);
     order.push(v);
   }
@@ -1329,32 +1571,27 @@ function loadOrder(run: Run): { order: number[]; load: Map<number, number> } {
  * structural reason one of the removals cannot be made. The outline loses the run and gains the chord from the
  * vertex before it to the vertex after it; nothing is measured in between.
  */
-function runRemovalOf(work: Work, vertices: readonly number[]): { triangles: Array<[number, number, number]>; added: Array<[number, number]> } | { blocked: string } {
+function runRemovalOf(work: Work, vertices: readonly number[], audit: EdgeSetAudit | null = null): Removal {
   const was = work.triangles;
+  // Issue #1307: each removal's own added edges are never read here, so none is built; what the run adds is read off
+  // the triangles its removals made. A triangle of `after` that no removal made is the same tuple as one of `was`
+  // (`removalStep` keeps every untouched triangle as it was), so every edge it holds is old and it adds nothing.
+  const made = new Set<readonly number[]>();
   let after: Array<[number, number, number]>;
   try {
     for (const v of vertices) {
-      const step = removalOf(work, v);
+      const step = removalStep(work, v);
       if ('blocked' in step) return step;
+      for (const t of step.fresh) made.add(t);
       work.triangles = step.triangles;
     }
     after = work.triangles;
   } finally {
     work.triangles = was;
   }
-  const old = new Set<string>();
-  for (const t of was) for (let k = 0; k < 3; k++) old.add(edgeKey(t[k], t[(k + 1) % 3]));
-  const added: Array<[number, number]> = [];
-  const seen = new Set<string>();
-  for (const t of after) {
-    for (let k = 0; k < 3; k++) {
-      const key = edgeKey(t[k], t[(k + 1) % 3]);
-      if (old.has(key) || seen.has(key)) continue;
-      seen.add(key);
-      added.push([t[k], t[(k + 1) % 3]]);
-    }
-  }
-  return { triangles: after, added };
+  const n = work.alive.length;
+  const label = `removing ${vertices.join(', ')} as one boundary run`;
+  return { triangles: after, added: () => auditedAdded(audit, label, addedEdges(was, after.filter((t) => made.has(t)), n), () => addedEdgesByString(was, after)) };
 }
 
 /**
@@ -1448,7 +1685,10 @@ function removeVertices(run: Run): PhaseEnd {
       if (block === null) {
         taken++;
         if (accept(run, 'removal', [v])) return { kind: 'replayed' };
-      } else lastBlock = { refusal: block, what: `removing source vertex ${v}` };
+      } else {
+        lastBlock = { refusal: block, what: `removing source vertex ${v}` };
+        if (run.hooks?.plant === 'veto-ends-search' && typeof block === 'string' && block.startsWith('MQ_SKINNING_RESIDUAL')) return { kind: 'stuck', constraint: lastName() };
+      }
     }
     if (taken === 0) {
       // A pass that took nothing left the working mesh as it found it, so a refusal the floor decided is measured
@@ -1485,6 +1725,28 @@ function deviationFloor(run: Run, mesh: SourceMesh, vertices: readonly number[])
  */
 const FLOOR_MARGIN = 1e-5;
 
+/**
+ * Issue #1307's audit of the triangulation's edge set (`EdgeSetAudit`): the plant applied to `edges` in place — so
+ * the decision reads the planted set — then the set held to the string-keyed one, member for member.
+ */
+function auditEdgeSet(audit: EdgeSetAudit, edges: Set<number>, triangles: ReadonlyArray<readonly number[]>, n: number, vertices: readonly number[]): void {
+  if (audit.plant === 'drop-one') {
+    const first = edges.values().next();
+    if (first.done !== true) edges.delete(first.value);
+  }
+  const want = new Set<string>();
+  for (const t of triangles) for (let k = 0; k < 3; k++) want.add(edgeKey(t[k], t[(k + 1) % 3]));
+  audit.edgeSets++;
+  audit.edgeSetEdges += want.size;
+  const missing = [...want].filter((key) => {
+    const [a, b] = key.split(',').map(Number);
+    return !edges.has(pairKey(a, b, n));
+  });
+  if (missing.length > 0 || edges.size !== want.size) {
+    audit.differences.push(`removing ${vertices.join(', ')}: the triangulation's edge set holds ${edges.size} edge(s) against the string construction's ${want.size}${missing.length > 0 ? `, missing ${missing.slice(0, 3).join(' ')}` : ''}`);
+  }
+}
+
 /**
  * One operation — a single removal, or a boundary run of two or more — tried: null when it was taken (the working
  * mesh then holds it), else what refused it (the working mesh as it was). `full` measures every candidate that
@@ -1493,12 +1755,12 @@ const FLOOR_MARGIN = 1e-5;
  */
 function tryOperation(run: Run, vertices: readonly number[], full: boolean): Refusal | null {
   const { work, input } = run;
-  const step = vertices.length === 1 ? removalOf(work, vertices[0]) : runRemovalOf(work, vertices);
+  const step = vertices.length === 1 ? removalOf(work, vertices[0], run.edgeAudit) : runRemovalOf(work, vertices, run.edgeAudit);
   if ('blocked' in step) return step.blocked;
   const jump = input.protect.weightJump;
   if (jump !== null) {
-    for (const [a, b] of step.added) {
-      if (a < work.nSource && b < work.nSource && run.sourceEdges.has(edgeKey(a, b))) continue;
+    for (const [a, b] of step.added()) {
+      if (a < work.nSource && b < work.nSource && run.sourceEdges.has(pairKey(a, b, work.nSource))) continue;
       const d = weightJump(work, a, b);
       if (d > jump) return `weightJump (b): the new edge ${a}–${b} joins weight vectors ${r6(d)} apart, over ${jump}`;
     }
@@ -1510,12 +1772,17 @@ function tryOperation(run: Run, vertices: readonly number[], full: boolean): Ref
     work.triangles = was.triangles;
     for (const v of vertices) work.alive[v] = true;
   };
-  const edges = new Set<string>();
-  for (const t of work.triangles) for (let k = 0; k < 3; k++) edges.add(edgeKey(t[k], t[(k + 1) % 3]));
-  for (const [a, b] of run.protectedEdges) {
-    if (!edges.has(edgeKey(a, b))) {
-      undo();
-      return `protect (a): the protected source edge ${a}–${b} is no longer an edge`;
+  // Issue #1307: the triangulation's edge set is built only when a protected edge is looked up in it, keyed by number.
+  if (run.protectedEdges.length > 0) {
+    const n = work.alive.length;
+    const edges = new Set<number>();
+    for (const t of work.triangles) for (let k = 0; k < 3; k++) edges.add(pairKey(t[k], t[(k + 1) % 3], n));
+    if (run.edgeAudit !== null) auditEdgeSet(run.edgeAudit, edges, work.triangles, n, vertices);
+    for (const [a, b] of run.protectedEdges) {
+      if (!edges.has(pairKey(a, b, n))) {
+        undo();
+        return `protect (a): the protected source edge ${a}–${b} is no longer an edge`;
+      }
     }
   }
   let canon: Canonical;
@@ -1526,7 +1793,11 @@ function tryOperation(run: Run, vertices: readonly number[], full: boolean): Ref
     undo();
     return `outline: ${err.message}`;
   }
-  if (vertices.length > 1 && run.plant === 'run-skips-rows') return null;
+  const phase: SkinningInspection['phase'] = vertices.length > 1 ? 'boundary-run' : 'removal';
+  if (vertices.length > 1 && run.plant === 'run-skips-rows') {
+    followSkinning(run, phase);
+    return null;
+  }
   if (!full && run.plant !== 'measure-every-candidate') {
     const margin = run.plant === 'floor-half-a-pixel-short' ? -0.5 : FLOOR_MARGIN;
     if (deviationFloor(run, canon.mesh, vertices) > input.targets.maxBoundaryDeviation + margin) {
@@ -1551,6 +1822,18 @@ function tryOperation(run: Run, vertices: readonly number[], full: boolean): Ref
     undo();
     return rowName(blocking);
   }
+  // Issue #1295: every required row passes, so the candidate has no reversed or degenerate triangle; now the residual
+  // against the original source. A veto is a refusal like any other: the mesh and the carried state as they were.
+  if (run.skinning !== null) {
+    const reading = skinningTrial(run, () => canon.mesh);
+    const veto = skinningVeto(run.skinning, reading);
+    if (veto !== null) {
+      undo();
+      settleSkinning(run, false, phase, reading);
+      return veto;
+    }
+    settleSkinning(run, true, phase, reading);
+  }
   return null;
 }
 
@@ -1681,7 +1964,7 @@ function delaunayFlips(run: Run, plant: ReductionPlant | null): FlipResult {
       const sine = oppositeAngleSine(P[a], P[b], P[c], P[d]);
       if (against ? !(sine > FLIP_MARGIN) : !(sine < -FLIP_MARGIN)) continue;
       if (held(a, b) || held(c, d)) continue;
-      if (jump !== null && !(c < work.nSource && d < work.nSource && run.sourceEdges.has(edgeKey(c, d))) && weightJump(work, c, d) > jump) continue;
+      if (jump !== null && !(c < work.nSource && d < work.nSource && run.sourceEdges.has(pairKey(c, d, work.nSource))) && weightJump(work, c, d) > jump) continue;
       if (flips >= maxFlips) return { bound: `the flip bound n(n - 1)/2 = ${maxFlips} over ${alive} vertices was reached`, flips, sweeps };
       tris[i] = [a, d, c];
       tris[j] = [d, b, c];
@@ -1718,12 +2001,29 @@ function retriangulateResult(run: Run, termination: Termination): Retriangulatio
   if (result.flips === 0) return out(true, null);
   const was = run.work.triangles;
   run.work.triangles = result.triangles;
-  if (plant === 'flips-against-delaunay-unmeasured') return out(true, null);
+  if (plant === 'flips-against-delaunay-unmeasured') {
+    followSkinning(run, 'delaunay');
+    return out(true, null);
+  }
   const canon = canonicalise(run.work, run.sourceTurn, run.boneRank);
   const blocking = firstBlockingRow(measureAgainstTargets(run, canon.mesh, 'retriangulated'), run.input.targets.artFit);
-  if (blocking === null) return out(true, null);
-  run.work.triangles = was;
-  return out(false, rowName(blocking));
+  if (blocking !== null) {
+    run.work.triangles = was;
+    return out(false, rowName(blocking));
+  }
+  // Issue #1295: the returned triangulation is held to the residual as every step was — it is not in acceptedAt, and
+  // that is no reason for it to escape the bound. Refused whole, naming the row.
+  if (run.skinning !== null) {
+    const reading = skinningTrial(run, () => canon.mesh);
+    const veto = run.hooks?.plant === 'post-pass-unchecked' ? null : skinningVeto(run.skinning, reading);
+    if (veto !== null) {
+      run.work.triangles = was;
+      settleSkinning(run, false, 'delaunay', reading);
+      return out(false, veto);
+    }
+    settleSkinning(run, true, 'delaunay', reading);
+  }
+  return out(true, null);
 }
 
 // ---------------------------------------------------------------------------
@@ -1783,19 +2083,29 @@ export function reduceMeshWith(
   steps: StepRasters | null = stepRastersOf(rasters),
   plant: ReductionPlant | null = null,
   observe: AttemptObserver | null = null,
+  skinning: SkinningHooks | null = null,
+  edgeAudit: EdgeSetAudit | null = null,
 ): MeshReductionResult {
   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))`);
   }
-  return reduceValidated(input, rasters, steps, plant, observe);
+  return reduceValidated(input, rasters, steps, plant, observe, skinning, edgeAudit);
 }
 
 /**
  * The operation, over an input `validateReduction` accepted; the art's rasters are computed at most once, in
  * `rasters`, and every refinement and removal step is measured through `steps` when it is given (issue #1246).
  */
-function reduceValidated(input: MeshReductionInput, rasters: ArtRasters, steps: StepRasters | null, plant: ReductionPlant | null = null, observe: AttemptObserver | null = null): MeshReductionResult {
+function reduceValidated(
+  input: MeshReductionInput,
+  rasters: ArtRasters,
+  steps: StepRasters | null,
+  plant: ReductionPlant | null = null,
+  observe: AttemptObserver | null = null,
+  hooks: SkinningHooks | null = null,
+  edgeAudit: EdgeSetAudit | null = null,
+): MeshReductionResult {
   const who = `attachment ${nameOf(input.attachment)}`;
   const src = input.source;
   const sourceHull: Array<[number, number]> = src.points.slice(0, Math.max(0, src.hull)).map(([x, y]): [number, number] => [x, y]);
@@ -1819,7 +2129,7 @@ function reduceValidated(input: MeshReductionInput, rasters: ArtRasters, steps:
     ...amplitudeOf(input, plant, false),
   };
   const admit = steps === null ? measureMeshQualityWith(admitInput, rasters) : measureMeshQualityStep(admitInput, steps);
-  const effective = effectiveOf(input, admit.effective, sourceHull, plant);
+  const effective = effectiveOf(input, admit.effective, sourceHull, plant, hooks);
   const sourceCounts = admit.sourceCounts;
   const noMesh = (termination: Termination): MeshReductionResult => ({
     mesh: null,
@@ -1849,6 +2159,7 @@ function reduceValidated(input: MeshReductionInput, rasters: ArtRasters, steps:
     }
     checkIslands(input, who, rasters);
     checkDeformBeforeWork(input);
+    const skinningAdmitted = admitSkinning(input, rasters);
 
     const boneRank = new Map((input.boneOrder ?? []).map((b, i) => [b, i]));
     const work: Work = {
@@ -1861,8 +2172,12 @@ function reduceValidated(input: MeshReductionInput, rasters: ArtRasters, steps:
       sourceTriangle: new Map(),
     };
     for (let i = 0; i + 2 < src.triangles.length; i += 3) work.triangles.push([src.triangles[i], src.triangles[i + 1], src.triangles[i + 2]]);
-    const sourceEdges = new Set<string>();
-    for (const t of work.triangles) for (let k = 0; k < 3; k++) sourceEdges.add(edgeKey(t[k], t[(k + 1) % 3]));
+    // The string-keyed set is read once, by `protectionOf`, whose weightJump edges follow its sorted keys; every step
+    // reads the numeric one (issue #1307).
+    const sourceEdgeNames = new Set<string>();
+    for (const t of work.triangles) for (let k = 0; k < 3; k++) sourceEdgeNames.add(edgeKey(t[k], t[(k + 1) % 3]));
+    const sourceEdges = new Set<number>();
+    for (const t of work.triangles) for (let k = 0; k < 3; k++) sourceEdges.add(pairKey(t[k], t[(k + 1) % 3], work.nSource));
     const run: Run = {
       input,
       who,
@@ -1876,11 +2191,15 @@ function reduceValidated(input: MeshReductionInput, rasters: ArtRasters, steps:
       observe,
       tally: { sharesDroppedOnGrid: 0, sharesPruned: 0 },
       keyed: keyedSourceVertices(input),
-      ...protectionOf(input, work, sourceEdges),
+      ...protectionOf(input, work, sourceEdgeNames),
       sourceEdges,
+      edgeAudit,
       rasters,
       stepRasters: steps,
+      skinning: null,
+      hooks,
     };
+    run.skinning = skinningRunOf(run, skinningAdmitted);
 
     // Issue #1268: a replay ends in its own termination, never as an exhausted budget; a stop the run never reaches
     // leaves the run's own termination, which then carries `stopAfterAccepted` saying so.
@@ -1892,10 +2211,13 @@ function reduceValidated(input: MeshReductionInput, rasters: ArtRasters, steps:
     if (refined.kind === 'replayed') return finish(run, effective, sourceCounts, replayed());
     if (refined.kind === 'budget') return noMesh({ reason: 'budget-exhausted', candidatesTried: run.steps, budget: input.budget.maxCandidates, result: 'none-met-the-targets', ...notReached() });
     const startCanon = canonicalise(work, run.sourceTurn, boneRank);
-    const startBlock = firstBlockingRow(measureAgainstTargets(run, startCanon.mesh, 'start'), input.targets.artFit);
+    const startRow = firstBlockingRow(measureAgainstTargets(run, startCanon.mesh, 'start'), input.targets.artFit);
+    // Issue #1295: the refined source — the refinement's outcome — held to the residual before any removal; with no
+    // region it is the source, which reads 0 against itself.
+    const startBlock = startRow !== null ? rowName(startRow) : run.skinning === null ? null : skinningStart(run, () => startCanon.mesh);
     let termination: Termination;
     if (startBlock !== null) {
-      const constraint = refined.kind === 'stuck' ? refined.constraint : rowName(startBlock);
+      const constraint = refined.kind === 'stuck' ? refined.constraint : startBlock;
       termination = { reason: 'no-further-valid-reduction', candidatesTried: run.steps, blockingConstraint: `${constraint} — before any removal: the refined source does not meet its targets, so no step from it can`, ...notReached() };
     } else {
       const reduced = removeVertices(run);
@@ -1912,6 +2234,87 @@ function reduceValidated(input: MeshReductionInput, rasters: ArtRasters, steps:
   }
 }
 
+/**
+ * Issue #1295: the residual's admission — what the source itself reads under the declared envelope, before any step.
+ * Null when no step reads a residual (the field left out, `null`, or a bound declared absent). A source the
+ * measurement refuses — a deform key that moves vertices outside skinning, a bone the envelope does not declare, an
+ * envelope bone the source does not bind, shares that do not close, a vertex off its UV, one mesh weighted and not the
+ * other — is refused here, `invalid-input` with the measurement's code and words; what it cannot measure (both meshes
+ * unweighted, fewer art samples than the floor) is kept as the reading every step is then blocked by.
+ */
+function admitSkinning(input: MeshReductionInput, rasters: ArtRasters): { input: SkinningResidualInput; args: Omit<SkinningMeasureArgs, 'candidate'>; unmeasured: CarryReading | null } | null {
+  const declared = input.targets.skinning;
+  if (declared === undefined || declared === null || declared.maxResidual === null) return null;
+  const skinning = skinningInputOf(input);
+  const args: Omit<SkinningMeasureArgs, 'candidate'> = {
+    attachment: input.attachment,
+    frame: input.art.frame,
+    artBits: rasters.artBits(),
+    maskWidth: input.art.mask.width,
+    maskHeight: input.art.mask.height,
+    minArtSamples: input.minArtSamples,
+    threshold: input.art.threshold,
+    skinning,
+  };
+  const contract = skinningContract({ ...args, candidate: input.source });
+  if (!('state' in contract) || contract.state === 'measured') return { input: skinning, args, unmeasured: null };
+  if (contract.state === 'refused') {
+    const code = contract.reason.slice(0, contract.reason.indexOf(':'));
+    throw new Stop('invalid-input', code, contract.reason.slice(code.length + 2));
+  }
+  return { input: skinning, args, unmeasured: { state: 'not-measurable', reason: contract.reason } };
+}
+
+/** Issue #1295: the run's residual — the carried state over the working mesh as the reduction starts, or what stands in for it. */
+function skinningRunOf(run: Run, admitted: ReturnType<typeof admitSkinning>): SkinningRun | null {
+  if (admitted === null) return null;
+  const bound = admitted.input.maxResidual!;
+  const base = { bound, input: admitted.input, args: admitted.args };
+  if (admitted.unmeasured !== null) return { ...base, carry: null, unmeasured: admitted.unmeasured };
+  const plant = run.hooks?.plant;
+  if (plant === 'full-recompute') {
+    const reading = skinningResidual({ ...admitted.args, candidate: run.input.source });
+    if (reading.state === 'refused') {
+      const code = reading.reason.slice(0, reading.reason.indexOf(':'));
+      throw new Stop('invalid-input', code, reading.reason.slice(code.length + 2));
+    }
+    return { ...base, carry: null, unmeasured: null };
+  }
+  const carryPlant: CarryPlant | null = plant === 'stale-carrier' || plant === 'lost-maximum' || plant === 'no-rollback' || plant === 'previous-candidate' ? plant : null;
+  try {
+    const carry = new SkinningCarry(
+      run.who,
+      { pos: run.work.pos, uv: run.work.uv, weights: run.work.weights! },
+      run.work.nSource,
+      run.work.triangles,
+      run.input.source,
+      admitted.input.envelope,
+      admitted.args.artBits,
+      admitted.args.maskWidth,
+      admitted.args.maskHeight,
+      run.input.art.frame,
+      carryPlant,
+    );
+    return { ...base, carry, unmeasured: null };
+  } catch (err) {
+    if (err instanceof MeshReductionError && err.code === 'COMPARE_UV_CARRIER_NOT_UNIQUE') throw new Stop('invalid-input', 'SKINNING_UV_CARRIER_NOT_UNIQUE', err.message);
+    throw err;
+  }
+}
+
+/** Issue #1295: the residual's verdict on the mesh the removals start from — the refinement's outcome — as a refusal name, or null. */
+function skinningStart(run: Run, canonical: () => SourceMesh): string | null {
+  const sk = run.skinning!;
+  let reading: CarryReading;
+  if (sk.unmeasured !== null) reading = sk.unmeasured;
+  else if (sk.carry !== null) reading = sk.carry.reading();
+  else {
+    const r = skinningResidual({ ...sk.args, candidate: canonical() });
+    reading = r.state === 'measured' ? { state: 'measured', value: r.value } : { state: r.state, reason: r.reason };
+  }
+  return skinningVeto(sk, reading);
+}
+
 /** §4: full coverage asked of a source that touches no pixel of some art island is refused, never met by deleting art. */
 function checkIslands(input: MeshReductionInput, who: string, rasters: ArtRasters): void {
   if (input.targets.artFit.minCoverage !== 1) return;
@@ -2015,13 +2418,13 @@ 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]>, plant: ReductionPlant | null): EffectiveSettings {
+function effectiveOf(input: MeshReductionInput, measured: EffectiveSettings, sourceHull: Array<[number, number]>, plant: ReductionPlant | null, hooks: SkinningHooks | null = 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,
     sourceBounds: fit(input.sourceBounds),
-    targets: input.targets,
+    targets: hooks?.plant === 'echo-when-unset' && input.targets.skinning === undefined ? { ...input.targets, skinning: null } : input.targets,
     referenceHull: sourceHull,
     budget: { maxCandidates: input.budget.maxCandidates },
     ...(input.stopAfterAccepted === undefined ? {} : { stopAfterAccepted: input.stopAfterAccepted }),