spine-rigc 2.19.0 → 2.20.0

package/src/meshquality.ts

@@ -299,6 +299,8 @@ export interface MeasureRow {
   raster?: RasterSensitivity;
   /** Sampled rows — correction 2. */
   sampling?: { domain: string; count: number };
+  /** Motion rows only (stage C, `src/meshcompare.ts`): how the row's value was taken over the schedule. */
+  motion?: MotionRowDetail;
 }
 
 /** Correction 2: the spatial grid and the value's own granularity are two fields. */
@@ -353,9 +355,10 @@ export interface MotionSchedule {
 
 /**
  * The schedule a motion section was measured under. The contract names this
- * type without defining it; until stage C does, it is the schedule as given.
+ * type without defining it; stage C (issue #1230) defines it as the schedule as
+ * given plus what was walked from it (`ScheduleWalked`, at the end of this file).
  */
-export type ScheduleUsed = MotionSchedule;
+export type ScheduleUsed = MotionSchedule & ScheduleWalked;
 
 /** One candidate's evidence — correction 1. `reduce` and `measure` carry exactly one. */
 export interface CandidateReport {
@@ -421,8 +424,8 @@ export interface EffectiveSettings {
     frame: SourceFrame;
     maskSize: [number, number];
     minArtSamples: number;
-    /** P9: each region's own floor, in the order the regions were given. */
-    regions: Array<{ name: string; minArtSamples: number }>;
+    /** P9: each region's own floor, in the order the regions were given — and, on a `compare`, its polygon. */
+    regions: Array<{ name: string; minArtSamples: number; polygon?: Array<[number, number]> }>;
   }>;
   sourceBounds: ArtFitBounds | null;
   referenceArtFit: ArtFitBounds | null;
@@ -473,6 +476,20 @@ const HAUSDORFF_TOLERANCE = 1e-9;
 /** The predicate epsilon `segmentsMeet` and `prunePolygon` use (`src/mesh.ts`), for "on the boundary". */
 const ON_BOUNDARY = 1e-9;
 
+/**
+ * How near a region's band's outer boundary, in drawing px, an edge's nearest
+ * point has to come to count as touching it rather than entering the band —
+ * the precision of "a single point on the outer boundary" in
+ * `edgeIsHeldByRegion`, ten units of the `r6` grid. The refinement puts the
+ * vertex it splits an edge at half of this inside the outer boundary and then
+ * on the grid, which moves it by at most √2 × 5e-7 px, so the piece beyond it
+ * lands inside this tolerance from either side.
+ */
+export const BAND_CONTACT_TOLERANCE = 1e-5;
+
+/** Halvings of the parameter interval in the convex searches along an edge (`edgeIsHeldByRegion`): 2^-60 of an edge is below a double's resolution of it. */
+const EDGE_SEARCH_STEPS = 60;
+
 // ---------------------------------------------------------------------------
 // refusals
 // ---------------------------------------------------------------------------
@@ -708,6 +725,110 @@ function segmentToPolygon(a: Pt, b: Pt, poly: readonly Pt[]): number {
   return best;
 }
 
+/**
+ * The parameter in `[0, 1]` along `a`–`b` nearest which `c`–`d` lies — the
+ * minimum of the distance from `a + t(b − a)` to the segment `c`–`d`, which is
+ * convex in `t`, found by golden-section search. A flat minimum (parallel
+ * segments) returns some point of it; the callers never read one there.
+ */
+function nearestParameter(a: Pt, b: Pt, c: Pt, d: Pt): number {
+  const at = (t: number): number => distanceToSegment([a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t], c, d);
+  const g = (Math.sqrt(5) - 1) / 2;
+  let lo = 0;
+  let hi = 1;
+  for (let i = 0; i < EDGE_SEARCH_STEPS; i++) {
+    const p = hi - g * (hi - lo);
+    const q = lo + g * (hi - lo);
+    if (at(p) <= at(q)) hi = q;
+    else lo = p;
+  }
+  return (lo + hi) / 2;
+}
+
+/**
+ * Does `a`–`b` run along the outer boundary of a band of width `transition`
+ * for a positive length — some polygon edge it overlaps in projection by more
+ * than `BAND_CONTACT_TOLERANCE`, at that edge's perpendicular distance
+ * `transition` (within the tolerance) at both ends of the overlap, so at every
+ * point between them? The caller has already found the edge's nearest approach
+ * to the polygon within the tolerance of `transition`.
+ */
+function runsAlongOuterBoundary(a: Pt, b: Pt, poly: readonly Pt[], transition: number): boolean {
+  const length = Math.hypot(b[0] - a[0], b[1] - a[1]);
+  const n = poly.length;
+  for (let i = 0; i < n; i++) {
+    const c = poly[i];
+    const e = poly[(i + 1) % n];
+    const side = Math.hypot(e[0] - c[0], e[1] - c[1]);
+    if (side === 0) continue;
+    const ux = (e[0] - c[0]) / side;
+    const uy = (e[1] - c[1]) / side;
+    const sa = (a[0] - c[0]) * ux + (a[1] - c[1]) * uy;
+    const sb = (b[0] - c[0]) * ux + (b[1] - c[1]) * uy;
+    let t0 = 0;
+    let t1 = 1;
+    if (sa === sb) {
+      if (sa < 0 || sa > side) continue;
+    } else {
+      const p = (0 - sa) / (sb - sa);
+      const q = (side - sa) / (sb - sa);
+      t0 = Math.max(0, Math.min(p, q));
+      t1 = Math.min(1, Math.max(p, q));
+    }
+    if ((t1 - t0) * length <= BAND_CONTACT_TOLERANCE) continue;
+    const off = (t: number): number => Math.abs(ux * (a[1] + (b[1] - a[1]) * t - c[1]) - uy * (a[0] + (b[0] - a[0]) * t - c[0]));
+    if (Math.abs(off(t0) - transition) <= BAND_CONTACT_TOLERANCE && Math.abs(off(t1) - transition) <= BAND_CONTACT_TOLERANCE) return true;
+  }
+  return false;
+}
+
+/**
+ * [agreed, spine-parts#126] Is the edge `a`–`b` held by `region` — does the
+ * region's density bound (`MQ_MAX_EDGE` or `MQ_TRANSITION`) apply to it? The
+ * one definition both `measureMeshQuality` and `reduceMesh`'s refinement read.
+ *
+ * The region's active domain is its closed polygon and, when `transition > 0`,
+ * the band of that width outside it. An edge is held when it meets that domain,
+ * except for one case: its intersection with the domain is a **single point on
+ * the band's outer boundary** and the rest of the edge lies outside — an edge
+ * that only touches the band from outside is exempt.
+ *
+ * - An edge that meets the closed polygon is held, whatever the band.
+ * - With `transition: 0` there is no outer band, and a contact with the
+ *   authored boundary is held under the closed-region rule — never exempt.
+ * - A positive-length intersection is held, including a segment lying along
+ *   the band's outer boundary.
+ * - Two separate touches of the outer boundary are two points, not one, and
+ *   the edge is held.
+ *
+ * "On the outer boundary" is within `BAND_CONTACT_TOLERANCE`. Each region is
+ * read on its own: an exemption from one never removes another's bound.
+ */
+export function edgeIsHeldByRegion(a: readonly [number, number], b: readonly [number, number], region: RefinementRegion): boolean {
+  const poly: readonly Pt[] = region.polygon;
+  if (segmentMeetsPolygon(a, b, poly)) return true;
+  const transition = region.transition;
+  if (!(transition > 0)) return false;
+  const d = segmentToPolygon(a, b, poly);
+  if (d > transition) return false;
+  if (d < transition - BAND_CONTACT_TOLERANCE) return true;
+  if (runsAlongOuterBoundary(a, b, poly, transition)) return true;
+  // Where on the edge each polygon side is touched: one point, or several apart.
+  const length = Math.hypot(b[0] - a[0], b[1] - a[1]);
+  let first = Infinity;
+  let last = -Infinity;
+  const n = poly.length;
+  for (let i = 0; i < n; i++) {
+    const c = poly[i];
+    const e = poly[(i + 1) % n];
+    if (segmentDistance(a, b, c, e) > transition) continue;
+    const t = nearestParameter(a, b, c, e);
+    first = Math.min(first, t);
+    last = Math.max(last, t);
+  }
+  return (last - first) * length > BAND_CONTACT_TOLERANCE;
+}
+
 /** Distance from a point to a closed polyline (the polygon's boundary), and the edge that realises it. */
 function pointToBoundary(p: Pt, poly: readonly Pt[]): { d: number; edge: number } {
   let d = Infinity;
@@ -1201,9 +1322,12 @@ interface Edge {
  * graded band, only where the band has width) and `MQ_FILL_DISTANCE` (`h(R)`,
  * sampled, informational).
  *
- * One bound per edge, the smallest applicable anywhere on it (P16): `L0` of
- * every region whose closed polygon it meets, and `L0 + grade·d` of every band
- * it lies in, `d` its distance from that region. A row's value is the edge whose
+ * Which edges a region holds is `edgeIsHeldByRegion`'s answer and nothing
+ * else's: an edge that only touches the band's outer boundary at one point,
+ * from outside, is not held (spine-parts#126). One bound per edge, the smallest
+ * applicable anywhere on it (P16): `L0` of every region whose closed polygon it
+ * meets, and `L0 + grade·d` of every other region that holds it, `d` its
+ * distance from that region. A row's value is the edge whose
  * length most exceeds its own bound — so the row fails exactly when some edge
  * it covers is over — and the row names that edge and that bound.
  */
@@ -1242,15 +1366,29 @@ function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon:
     else refusals.set(region.name, `${refusal.code}: ${refusal.message}`);
   }
 
-  /** Every bound that applies to an edge, from every measurable region, and the smallest. */
+  /**
+   * Per measurable region, per edge (in `edges` order): the edge's distance
+   * from the closed polygon when the region holds it (`edgeIsHeldByRegion`,
+   * the one definition the refinement reads too), null when it does not.
+   */
+  const holds = new Map<RefinementRegion, Array<number | null>>();
+  for (const region of live) {
+    holds.set(
+      region,
+      edges.map((e) => (edgeIsHeldByRegion(points[e.a], points[e.b], region) ? segmentToPolygon(points[e.a], points[e.b], region.polygon) : null)),
+    );
+  }
+  const edgeIndex = new Map(edges.map((e, i) => [e, i]));
+
+  /** Every bound that applies to an edge, from every measurable region that holds it, and the smallest. */
   const boundOf = (e: Edge): number | null => {
     let bound: number | null = null;
+    const i = edgeIndex.get(e)!;
     for (const region of live) {
-      const d = segmentToPolygon(points[e.a], points[e.b], region.polygon);
-      let here: number | null = null;
-      if (d === 0) here = region.maxEdgeLength;
-      else if (region.transition > 0 && d <= region.transition) here = r6(region.maxEdgeLength + region.grade * d);
-      if (here !== null && (bound === null || here < bound)) bound = here;
+      const d = holds.get(region)![i];
+      if (d === null) continue;
+      const here = d === 0 ? region.maxEdgeLength : r6(region.maxEdgeLength + region.grade * d);
+      if (bound === null || here < bound) bound = here;
     }
     return bound;
   };
@@ -1280,7 +1418,8 @@ function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon:
       continue;
     }
     const poly: Pt[] = region.polygon;
-    const inside = edges.filter((e) => segmentMeetsPolygon(points[e.a], points[e.b], poly));
+    const held = holds.get(region)!;
+    const inside = edges.filter((_, i) => held[i] === 0);
     const maxSpec = spec('MQ_MAX_EDGE', 'px', region.name);
     const inWorst = worstOf(inside);
     if (inWorst === null) {
@@ -1289,10 +1428,7 @@ function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon:
       out.push(measuredRow(maxSpec, r6(inWorst.edge.length), { op: '<=', value: inWorst.bound }, { at: { edge: [inWorst.edge.a, inWorst.edge.b] } }, true));
     }
     if (region.transition > 0) {
-      const banded = edges.filter((e) => {
-        const d = segmentToPolygon(points[e.a], points[e.b], poly);
-        return d > 0 && d <= region.transition;
-      });
+      const banded = edges.filter((_, i) => held[i] !== null && held[i]! > 0);
       const bandWorst = worstOf(banded);
       const transitionSpec = spec('MQ_TRANSITION', 'px', region.name);
       if (bandWorst === null) {
@@ -1443,7 +1579,7 @@ function effectiveJson(e: EffectiveSettings): Json {
       frame: frameJson(a.frame),
       maskSize: pair(a.maskSize),
       minArtSamples: a.minArtSamples,
-      regions: a.regions.map((r) => ({ name: r.name, minArtSamples: r.minArtSamples })),
+      regions: a.regions.map((r): Json => (r.polygon === undefined ? { name: r.name, minArtSamples: r.minArtSamples } : { name: r.name, minArtSamples: r.minArtSamples, polygon: r.polygon.map(pair) })),
     })),
     sourceBounds: fitJson(e.sourceBounds),
     referenceArtFit: fitJson(e.referenceArtFit),
@@ -1498,6 +1634,7 @@ function rowJson(r: MeasureRow): Json {
     };
   }
   if (r.sampling !== undefined) out.sampling = { domain: r.sampling.domain, count: r.sampling.count };
+  if (r.motion !== undefined) out.motion = motionDetailJson(r.motion);
   return out;
 }
 
@@ -1518,7 +1655,7 @@ function candidateJson(c: CandidateReport): Json {
     id: c.id,
     counts: countsJson(c.counts),
     geometry: c.geometry === null ? null : sectionJson(c.geometry),
-    motion: c.motion === null ? null : { ...sectionJson(c.motion), schedule: scheduleJson(c.motion.schedule) },
+    motion: c.motion === null ? null : { ...sectionJson(c.motion), schedule: scheduleUsedJson(c.motion.schedule) },
     accepted: c.accepted,
   };
   if (c.perFrame !== undefined) out.perFrame = c.perFrame.map((p) => ({ code: p.code, frame: p.frame, value: p.value }));
@@ -1569,3 +1706,97 @@ export function writeMeshQualityReport(report: MeshQualityReport): string {
   };
   return `${JSON.stringify(doc, null, 2)}\n`;
 }
+
+// ---------------------------------------------------------------------------
+// stage C — the motion section's own fields (issue #1230, `src/meshcompare.ts`)
+// ---------------------------------------------------------------------------
+//
+// Additive: nothing above reads these, a `measure` and a `reduce` never write
+// them, and every one is written only when present.
+
+/** One group of frames a motion row was also taken over — a phase, or a role (P11). */
+export interface MotionReading {
+  /** The group's worst value; null when no frame of the group drew the attachment. */
+  value: number | null;
+  /** The value against the row's bound, by the row's own rule; `undeclared` with no bound, `not-measurable` with no value. */
+  state: MeasureState;
+  /** The frame the group's worst value was taken at, by `FrameRef.id`. */
+  frame: string | null;
+}
+
+/**
+ * How a motion row's value was taken over the schedule (stage C). The row's own
+ * `value` is the worst over every frame measured; these keep apart what the
+ * contract says must not be folded together.
+ */
+export interface MotionRowDetail {
+  /** Frames at which the attachment was drawn and measured, and the ids of those at which its slot drew something else or nothing. */
+  frames: { measured: number; notDrawn: string[] };
+  /**
+   * §4 *Transition in time*: the row taken per sample phase — `grid` and `irr`
+   * for the frames a rate generated, `null` for the setup frame and for frames
+   * the caller gave as explicit times (no phase applies to those).
+   */
+  byPhase: Array<{ phase: 'grid' | 'irr' | null } & MotionReading>;
+  /** When one phase passes and another fails: the worst frame of each, by id, and a sentence naming both. Null otherwise. */
+  phasesDisagree: { pass: string; fail: string; sentence: string } | null;
+  /** P11: the row per role. `heldOut` is null when no held-out frame was measured — no held-out claim is made. */
+  byRole: { baseline: MotionReading | null; selection: MotionReading | null; heldOut: MotionReading | null };
+  /**
+   * Correction 4, world rows: the declared setup map of the attachment's slot
+   * bone — its world 2×2 at the setup pose, `[a, b, c, d]` as the core poses it
+   * from the bones' declared fields — and its two singular scales. Never a
+   * single world-per-pixel ratio, and never fitted to output vertices.
+   */
+  setupMap?: { bone: string; linear: [number, number, number, number]; singularScales: [number, number] };
+  /** §3: samples no non-degenerate UV triangle carries, listed by UV — in the reference's mesh and in this candidate's. */
+  uncarried?: { reference: Array<[number, number]>; candidate: Array<[number, number]> };
+  /** §3, `MQ_INVERSION` on a slot `invariants.deformMayFold` names: every reversed triangle with its frame — listed, never zeroed. */
+  folds?: Array<{ triangle: number; frame: string }>;
+  /** Triangles that have no area at the setup pose (the A39 band), so no sign and no stretch is read off them. */
+  degenerateAtSetup?: number;
+}
+
+/** What a motion section walked from the schedule it was given (`ScheduleUsed`). */
+export interface ScheduleWalked {
+  /** Every frame the schedule names, in walk order, each with its role (P11). */
+  walked: FrameRef[];
+  /** The roles among those frames — what the section has evidence for. */
+  roles: Array<FrameRef['role']>;
+  /** P11: true only when at least one held-out frame, disjoint from `selection`, was walked. */
+  heldOutClaim: boolean;
+  /** P10: every walk resets physics at time 0 and steps from there, the same steps for the reference and every candidate. */
+  reset: 'physics reset at time 0';
+  /** Each walk: the animation, the phase (null for explicit times), and how many steps reached its last frame. */
+  walks: Array<{ animation: string; phase: 'grid' | 'irr' | null; steps: number }>;
+}
+
+function readingJson(r: MotionReading | null): Json {
+  return r === null ? null : { value: r.value, state: r.state, frame: r.frame };
+}
+
+function motionDetailJson(m: MotionRowDetail): Json {
+  const out: { [key: string]: Json } = {
+    frames: { measured: m.frames.measured, notDrawn: [...m.frames.notDrawn] },
+    byPhase: m.byPhase.map((p) => ({ phase: p.phase, value: p.value, state: p.state, frame: p.frame })),
+    phasesDisagree: m.phasesDisagree === null ? null : { pass: m.phasesDisagree.pass, fail: m.phasesDisagree.fail, sentence: m.phasesDisagree.sentence },
+    byRole: { baseline: readingJson(m.byRole.baseline), selection: readingJson(m.byRole.selection), heldOut: readingJson(m.byRole.heldOut) },
+  };
+  if (m.setupMap !== undefined) out.setupMap = { bone: m.setupMap.bone, linear: [...m.setupMap.linear], singularScales: pair(m.setupMap.singularScales) };
+  if (m.uncarried !== undefined) out.uncarried = { reference: m.uncarried.reference.map(pair), candidate: m.uncarried.candidate.map(pair) };
+  if (m.folds !== undefined) out.folds = m.folds.map((f) => ({ triangle: f.triangle, frame: f.frame }));
+  if (m.degenerateAtSetup !== undefined) out.degenerateAtSetup = m.degenerateAtSetup;
+  return out;
+}
+
+function scheduleUsedJson(s: ScheduleUsed): Json {
+  const given = scheduleJson(s) as { [key: string]: Json };
+  return {
+    ...given,
+    walked: s.walked.map(frameRefJson),
+    roles: [...s.roles],
+    heldOutClaim: s.heldOutClaim,
+    reset: s.reset,
+    walks: s.walks.map((w) => ({ animation: w.animation, phase: w.phase, steps: w.steps })),
+  };
+}

package/src/meshreduce.ts

@@ -42,9 +42,13 @@
  * to meet `L(R)`, and removing one is undoing the refinement.
  *
  * The refinement measures, takes the first failing region row in report order
- * (code, then region name) and splits that row's worst edge: at its midpoint
- * when the midpoint lies in the region or its band, otherwise at the point of
- * the edge inside them nearest the midpoint. A region no edge meets — one
+ * (code, then region name) and splits that row's worst edge. When an end of
+ * the edge lies outside the region and its band, the split is where the edge
+ * leaves the band, so the piece to that end only touches the band's outer
+ * boundary and `edgeIsHeldByRegion` — the one definition the rows read —
+ * exempts it (spine-parts#126). Otherwise the split is at the midpoint when
+ * the midpoint lies in the region or its band, else at the point of the edge
+ * inside them nearest the midpoint. A region no edge meets — one
  * inside a single triangle — gets the first vertex of its polygon inserted into
  * the triangle that holds it. Every inserted position is on the `r6` grid.
  *
@@ -79,6 +83,8 @@ import {
   checkHullOrder,
 } from './mesh.ts';
 import {
+  BAND_CONTACT_TOLERANCE,
+  edgeIsHeldByRegion,
   measureMeshQuality,
   type AttachmentRef,
   type ArtFitBounds,
@@ -159,6 +165,9 @@ const ON_BOUNDARY = 1e-9;
 /** How many halvings toward a point known to lie in a region's band the split search tries before it says none was found. */
 const SPLIT_SEARCH_STEPS = 40;
 
+/** Iterations of the convex searches `offsetExit` runs along an edge: 2^-60 of an edge is below a double's resolution of it. */
+const EXIT_SEARCH_STEPS = 60;
+
 function nameOf(ref: AttachmentRef): string {
   return `${ref.skin ?? '(no skin)'}/${ref.slot}/${ref.attachment}`;
 }
@@ -797,6 +806,64 @@ function splitPoint(a: Pt, b: Pt, region: RefinementRegion): Pt | null {
   return null;
 }
 
+/**
+ * The parameter, from `inner` (0) to `outer` (1), of the point of the edge
+ * nearest `outer` that lies within `level` of `region`'s polygon — where the
+ * edge last leaves that offset of the polygon on its way to `outer` — or null
+ * when no point of it comes that near. `outer` lies further than `level`, so
+ * walking back from it the offset is first met where some polygon side is
+ * exactly `level` away: the largest such parameter over the sides. Each side's
+ * distance is convex along the edge, so its minimum is found by golden section
+ * and the last parameter within `level` by bisection from there towards `outer`.
+ */
+function offsetExit(inner: Pt, outer: Pt, poly: readonly Pt[], level: number): number | null {
+  const at = (t: number): Pt => [inner[0] + (outer[0] - inner[0]) * t, inner[1] + (outer[1] - inner[1]) * t];
+  const g = (Math.sqrt(5) - 1) / 2;
+  let best: number | null = null;
+  for (let i = 0; i < poly.length; i++) {
+    const c = poly[i];
+    const e = poly[(i + 1) % poly.length];
+    const f = (t: number): number => distanceToSegment(at(t), c, e);
+    let lo = 0;
+    let hi = 1;
+    for (let k = 0; k < EXIT_SEARCH_STEPS; k++) {
+      const p = hi - g * (hi - lo);
+      const q = lo + g * (hi - lo);
+      if (f(p) <= f(q)) hi = q;
+      else lo = p;
+    }
+    let inside = (lo + hi) / 2;
+    if (f(inside) > level) continue;
+    let outside = 1;
+    for (let k = 0; k < EXIT_SEARCH_STEPS; k++) {
+      const mid = (inside + outside) / 2;
+      if (f(mid) <= level) inside = mid;
+      else outside = mid;
+    }
+    if (best === null || inside > best) best = inside;
+  }
+  return best;
+}
+
+/**
+ * [agreed, spine-parts#126] A split of `inner`–`outer` where it leaves
+ * `region`'s band, so that the piece to `outer` only touches the band's outer
+ * boundary and is exempt by `edgeIsHeldByRegion` — the one definition the
+ * measurement reads. The split is put half of `BAND_CONTACT_TOLERANCE` inside
+ * the outer boundary, then on the `r6` grid, so it lies inside the band (P16's
+ * checkable form) and within the tolerance of its edge. Null when there is no
+ * band, no point of the edge comes that near the polygon, or the point found
+ * is an end or fails either condition — each re-checked rather than assumed.
+ */
+function outerSplit(inner: Pt, outer: Pt, region: RefinementRegion): Pt | null {
+  if (!(region.transition > 0)) return null;
+  const t = offsetExit(inner, outer, region.polygon, region.transition - BAND_CONTACT_TOLERANCE / 2);
+  if (t === null) return null;
+  const q: Pt = [r6(inner[0] + (outer[0] - inner[0]) * t), r6(inner[1] + (outer[1] - inner[1]) * t)];
+  if ((q[0] === inner[0] && q[1] === inner[1]) || (q[0] === outer[0] && q[1] === outer[1])) return null;
+  return inRegionOrBand(q, region) && !edgeIsHeldByRegion(q, outer, region) ? q : null;
+}
+
 /** Add a vertex at `p` with what interpolation gives it, refusing it under a deform run (P18). */
 function addVertex(run: Run, p: Pt): number {
   const got = interpolate(p, run.input, run.boneRank, run.tally, run.who);
@@ -892,16 +959,35 @@ function refineRegions(run: Run): PhaseEnd {
     const [ra, rb] = target.worst!.at.edge!;
     const a = canon.order[ra];
     const b = canon.order[rb];
-    // An end outside the region and its band further beyond the band than the edge's own bound: every
-    // split keeps an edge from a vertex inside them to that end, so no insertion P16 allows can meet it.
+    // An end outside the region and its band: split where the edge leaves the band, so the piece to that
+    // end only touches the band's outer boundary and is exempt (spine-parts#126) — the same predicate the
+    // measurement reads decides it, so the next measurement agrees.
+    let exited = false;
+    for (const [inner, outer] of [[b, a], [a, b]] as const) {
+      if (inRegionOrBand(run.work.pos[outer], region)) continue;
+      const q = outerSplit(run.work.pos[inner], run.work.pos[outer], region);
+      if (q === null) continue;
+      splitEdge(run, a, b, q);
+      exited = true;
+      break;
+    }
+    if (exited) continue;
+    // An end outside the region and its band further beyond it than the edge's own bound, with no split on
+    // the band's outer boundary that frees the piece to it — always so with transition 0, where a contact
+    // with the authored boundary stays held: every split keeps a held edge from a vertex inside the region
+    // and its band to that end, so no insertion P16 allows can meet it.
     for (const [end, id] of [[ra, a], [rb, b]] as const) {
       const at = run.work.pos[id];
       if (inRegionOrBand(at, region)) continue;
       const beyond = distanceToBoundary(at, region.polygon) - region.transition;
       if (beyond > target.bound!.value) {
+        const why =
+          region.transition > 0
+            ? 'no point of the edge on the band\'s outer boundary leaves the piece to it exempt, so an edge from inside the region and its band to it stays over the bound'
+            : 'with no band, an edge from the region to it touches the authored boundary and stays held (spine-parts#126), so it stays over the bound';
         return {
           kind: 'stuck',
-          constraint: `${rowName(target)} (vertex ${end} of edge ${ra}–${rb} lies ${r6(beyond)} px beyond region "${region.name}"'s ${region.transition} px band, further than the edge's bound ${target.bound!.value}: an edge from inside the region and its band to it stays over the bound, and the refinement inserts only inside them — P16)`,
+          constraint: `${rowName(target)} (vertex ${end} of edge ${ra}–${rb} lies ${r6(beyond)} px beyond region "${region.name}"'s ${region.transition} px band, further than the edge's bound ${target.bound!.value}: ${why}, and the refinement inserts only inside them — P16)`,
         };
       }
     }

package/src/package_meta.ts

@@ -0,0 +1,48 @@
+/**
+ * The package's own metadata — its installed version and repository — read
+ * once from the `package.json` beside the code.
+ *
+ * Moved here unchanged from `src/cli/shared.ts` (issue #1230), which imports
+ * these back and re-exports every name it exported before, so no caller
+ * changed an import. They moved because the motion comparison
+ * (`src/meshcompare.ts`) records the version of the poser that ran
+ * (`MeshQualityReport.poser`, P2 of docs/MESH_REDUCTION.md), and a library
+ * module that read it through `src/cli/shared.ts` would load the whole CLI —
+ * the compiler, `check` and every command body — to read one string. One
+ * reader, in the one place both can reach.
+ *
+ * Imports nothing but `node:fs` and `node:path`: no clock, no runtime.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+interface PackageMeta {
+  version?: string;
+  repository?: string | { url?: string };
+}
+
+let packageMeta: PackageMeta | null | undefined;
+
+/**
+ * The directory `cli.ts` sits in: `package.json`, `skills/` and, in a
+ * checkout, `examples/` and `scripts/` are beside it, in the repository and
+ * once installed. One level above this file (`src/`) — the same directory
+ * `src/cli/shared.ts` reached two levels above itself before the reader moved.
+ */
+export const PACKAGE_ROOT = join(import.meta.dir, '..');
+
+/** `package.json` sits next to `cli.ts` both in the repo and once installed (`PACKAGE_ROOT`). */
+export function readPackageMeta(): PackageMeta | null {
+  if (packageMeta === undefined) {
+    try {
+      packageMeta = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')) as PackageMeta;
+    } catch {
+      packageMeta = null;
+    }
+  }
+  return packageMeta;
+}
+
+export function readVersion(): string {
+  return readPackageMeta()?.version ?? 'unknown';
+}