rig-c 2.25.0 → 2.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-c",
-  "version": "2.25.0",
+  "version": "2.26.0",
   "description": "AI-authored Spine 2D rigging and animation, verified before it is written. rigc compiles a rig spec into Spine 4.3 skeleton data, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Output imports into the Spine editor. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/meshallocation.ts

@@ -0,0 +1,693 @@
+/**
+ * Where a mesh's vertices sit, read as five `undeclared` rows of
+ * `mesh-quality-report/1` (issue #1280, Stage B of #1271): docs/MESH_REDUCTION.md
+ * §8, *Measured — spatial measurements of allocation*, gives each definition
+ * and the fixtures it separates; this module computes them for
+ * `measureMeshQuality` (`src/meshquality.ts`), which turns them into rows.
+ *
+ * - `MQ_GRADE` — the largest |h_u − h_v| / L over the mesh's edges, h a
+ *   vertex's mean incident edge length: an uncontrolled transition, dense
+ *   beside sparse, whether or not the density is justified.
+ * - `MQ_MIN_ANGLE_P10` — the tenth percentile of the triangles' smallest
+ *   angles: the sliver fans a dense boundary leaves against an emptied interior.
+ * - `MQ_ALLOCATION_CONTRAST` — Δ, the share of the dense vertices removable
+ *   alone by a half-edge collapse judged against declared needs only, minus
+ *   that share among the rest; economy E, the share of all, beside it.
+ * - `MQ_DEFORM_LOAD` — the largest L · Δshare · θ / 4 over the edges: the chord
+ *   error bound of the mesh's own weight field under the declared amplitude.
+ *   A location reading; it is not predicted motion (§8's correction).
+ * - `MQ_BOUNDARY_NECESSARY` — B\*, the fewest vertices of the reference hull a
+ *   closed outline can keep with every skipped run within the declared
+ *   deviation of its chord both ways and no art pixel centre cut off.
+ *
+ * None of them takes a bound: there is no field to declare one in, so every
+ * row is `undeclared` when measured and `not-measurable`, with a reason
+ * naming what is missing, when not. None is required, so none can block a
+ * step, refuse a source or satisfy acceptance.
+ *
+ * Pure, as `src/meshquality.ts` is: no clock, no randomness, no runtime. Every
+ * loop runs in index order and every sort breaks its ties by index, so one
+ * input reads one answer (A18's standard).
+ *
+ * ⚠️ This module and `src/meshquality.ts` import each other. As with
+ * `src/mesh.ts`, it is safe only because neither reads the other's bindings at
+ * the top level: every use is inside a function.
+ */
+import { distanceToSegment, r6, type AlphaMask } from './mesh.ts';
+import { closedPolygonCentres, inClosedPolygon, regionEdgeBound, type MotionAmplitude, type RefinementRegion } from './meshquality.ts';
+
+type Pt = readonly [number, number];
+type Weights = ReadonlyArray<ReadonlyArray<{ bone: string; weight: number }>>;
+
+/**
+ * A fault planted on purpose, for the `mesh-quality` suite's negative controls
+ * (MQ120 onward). `measureMeshQuality` plants none.
+ *
+ * - `omit-rows`: no allocation row at all — the report as it was before #1280,
+ *   the baseline the opt-out identity is held to.
+ * - `grade-undivided`: |h_u − h_v| not divided by L.
+ * - `p10-is-min`: the minimum angle reported as the tenth percentile.
+ * - `contrast-without-amplitude`: Δ measured with no declared amplitude, the
+ *   reading §8 rejected (the deformation need is then absent).
+ * - `load-without-theta`: the load reported as L · Δshare / 4, θ dropped.
+ * - `undeclared-pair-is-rigid`: a pair of bones no track declares read as θ 0.
+ * - `bstar-ignores-art`: B\* without the art test.
+ * - `rows-required`: the rows counted as required.
+ * - `mutates-input`: the measurement sorts the caller's triangle list in place.
+ */
+export type AllocationPlant =
+  | 'omit-rows'
+  | 'grade-undivided'
+  | 'p10-is-min'
+  | 'contrast-without-amplitude'
+  | 'load-without-theta'
+  | 'undeclared-pair-is-rigid'
+  | 'bstar-ignores-art'
+  | 'rows-required'
+  | 'mutates-input';
+
+/** The art as the allocation rows read it: art pixels on the mask's grid, and the scale that grid is at. */
+export interface AllocationArt {
+  mask: AlphaMask;
+  /** 1 where the pixel is art (`alpha >= threshold`). */
+  bits: Uint8Array;
+  /** `pageScale`: texels = drawing px × scale. */
+  scale: number;
+}
+
+/** A measured reading, or the sentence saying why there is none. */
+export type Reading<T> = { measured: true; value: T } | { measured: false; reason: string };
+
+const unmeasured = (reason: string): { measured: false; reason: string } => ({ measured: false, reason });
+
+/** The mesh's unique edges, `[low, high]`, sorted — each encoded as low × n + high and sorted as numbers. */
+function uniqueEdges(triangles: readonly number[]): Array<[number, number]> {
+  let n = 0;
+  for (const v of triangles) n = Math.max(n, v + 1);
+  const seen = new Set<number>();
+  for (let t = 0; t + 2 < triangles.length; t += 3) {
+    for (let k = 0; k < 3; k++) {
+      const a = triangles[t + k];
+      const b = triangles[t + ((k + 1) % 3)];
+      seen.add(Math.min(a, b) * n + Math.max(a, b));
+    }
+  }
+  const keys = Float64Array.from(seen).sort();
+  const out: Array<[number, number]> = [];
+  for (const key of keys) out.push([Math.floor(key / n), key % n]);
+  return out;
+}
+
+const lengthOf = (a: Pt, b: Pt): number => Math.hypot(b[0] - a[0], b[1] - a[1]);
+
+/**
+ * Nearest rank at index round((n − 1) · p) of the values sorted ascending, ties by index — §8's percentile rule —
+ * as the index of the value at that rank: the values sorted as numbers, then, among the indices holding the value
+ * found, the one the rank falls on in ascending index order.
+ */
+function rankOf(values: readonly number[], p: number): number {
+  const sorted = Float64Array.from(values).sort();
+  const rank = Math.round((sorted.length - 1) * p);
+  const value = sorted[rank];
+  let below = 0;
+  while (below < rank && sorted[below] < value) below++;
+  let seen = 0;
+  for (let i = 0; i < values.length; i++) {
+    if (values[i] !== value) continue;
+    if (seen === rank - below) return i;
+    seen++;
+  }
+  return values.indexOf(value);
+}
+
+// ---------------------------------------------------------------------------
+// MQ_GRADE
+// ---------------------------------------------------------------------------
+
+/** The largest |h_u − h_v| / L, and the edge it is taken on (the first in sorted order on a tie). */
+export function gradeMax(points: readonly Pt[], triangles: readonly number[], plant: AllocationPlant | null): Reading<{ value: number; edge: [number, number] }> {
+  const edges = uniqueEdges(triangles);
+  const sum = new Array<number>(points.length).fill(0);
+  const count = new Array<number>(points.length).fill(0);
+  const lengths: number[] = [];
+  for (const [u, v] of edges) {
+    const L = lengthOf(points[u], points[v]);
+    if (!(L > 0)) return unmeasured(`edge [${u}, ${v}] has zero length, so |h_u − h_v| / L has no value on it`);
+    lengths.push(L);
+    sum[u] += L;
+    sum[v] += L;
+    count[u]++;
+    count[v]++;
+  }
+  if (edges.length === 0) return unmeasured('the mesh has no edge');
+  const h = sum.map((s, i) => (count[i] > 0 ? s / count[i] : 0));
+  let best = -1;
+  let at = edges[0];
+  edges.forEach(([u, v], i) => {
+    const g = plant === 'grade-undivided' ? Math.abs(h[u] - h[v]) : Math.abs(h[u] - h[v]) / lengths[i];
+    if (g > best) {
+      best = g;
+      at = [u, v];
+    }
+  });
+  return { measured: true, value: { value: r6(best), edge: at } };
+}
+
+// ---------------------------------------------------------------------------
+// MQ_MIN_ANGLE_P10
+// ---------------------------------------------------------------------------
+
+/** Each triangle's smallest interior angle, degrees — `MQ_MIN_ANGLE`'s own formula. */
+export function smallestAngles(points: readonly Pt[], triangles: readonly number[]): number[] {
+  const out: number[] = [];
+  for (let t = 0; t * 3 + 2 < triangles.length; t++) {
+    const corner = [points[triangles[t * 3]], points[triangles[t * 3 + 1]], points[triangles[t * 3 + 2]]];
+    let smallest = Infinity;
+    for (let k = 0; k < 3; k++) {
+      const o = corner[k];
+      const p = corner[(k + 1) % 3];
+      const q = corner[(k + 2) % 3];
+      const ux = p[0] - o[0];
+      const uy = p[1] - o[1];
+      const vx = q[0] - o[0];
+      const vy = q[1] - o[1];
+      smallest = Math.min(smallest, (Math.atan2(Math.abs(ux * vy - uy * vx), ux * vx + uy * vy) * 180) / Math.PI);
+    }
+    out.push(smallest);
+  }
+  return out;
+}
+
+/** The tenth percentile of the triangles' smallest angles, and the triangle it is read at. */
+export function minAngleP10(points: readonly Pt[], triangles: readonly number[], plant: AllocationPlant | null): Reading<{ value: number; triangle: number }> {
+  const angles = smallestAngles(points, triangles);
+  if (angles.length === 0) return unmeasured('the mesh has no triangle');
+  const t = rankOf(angles, plant === 'p10-is-min' ? 0 : 0.1);
+  return { measured: true, value: { value: r6(angles[t]), triangle: t } };
+}
+
+// ---------------------------------------------------------------------------
+// the declared amplitude, per pair of bones
+// ---------------------------------------------------------------------------
+
+/** Half the L1 distance between two weight vectors: the share of weight that moves across an edge. */
+export function shareJump(a: ReadonlyArray<{ bone: string; weight: number }>, b: ReadonlyArray<{ bone: string; weight: number }>): number {
+  const d = deltaOf(a, b);
+  let s = 0;
+  for (const bone of [...d.keys()].sort()) s += Math.abs(d.get(bone)!);
+  return s / 2;
+}
+
+function deltaOf(a: ReadonlyArray<{ bone: string; weight: number }>, b: ReadonlyArray<{ bone: string; weight: number }>): Map<string, number> {
+  const m = new Map<string, number>();
+  for (const x of a) m.set(x.bone, (m.get(x.bone) ?? 0) + x.weight);
+  for (const x of b) m.set(x.bone, (m.get(x.bone) ?? 0) - x.weight);
+  return m;
+}
+
+const pairKey = (p: string, q: string): string => (p < q ? `${p}\u0000${q}` : `${q}\u0000${p}`);
+
+/**
+ * The declared amplitude read per pair of bones: the largest θ, and the
+ * largest θ / ε, any track declares for the pair. A share moving across an
+ * edge from bones that lose it to bones that gain it is a flow between such
+ * pairs, and |Σ Δw_b R_b| ≤ Σ flow · θ_pair ≤ Δshare · max θ_pair — so the
+ * largest over the pairs an edge moves a share between bounds it.
+ */
+export class PairAmplitudes {
+  private readonly theta = new Map<string, number>();
+  private readonly ratio = new Map<string, number>();
+  /** The first pair a share moved between that no track declares, in the order the measurement met it. */
+  missing: { bones: [string, string]; edge: [number, number] } | null = null;
+
+  constructor(
+    declared: MotionAmplitude,
+    private readonly plant: AllocationPlant | null,
+  ) {
+    for (const track of declared.tracks) {
+      for (const pair of track.pairs) {
+        const key = pairKey(pair.bones[0], pair.bones[1]);
+        this.theta.set(key, Math.max(this.theta.get(key) ?? 0, pair.theta));
+        this.ratio.set(key, Math.max(this.ratio.get(key) ?? 0, pair.theta / track.epsilon));
+      }
+    }
+  }
+
+  /** The largest declared θ and θ / ε over the pairs a share moves between across `a`→`b`; null when a pair is undeclared. */
+  across(a: ReadonlyArray<{ bone: string; weight: number }>, b: ReadonlyArray<{ bone: string; weight: number }>, edge: [number, number]): { theta: number; ratio: number } | null {
+    const d = deltaOf(a, b);
+    const bones = [...d.keys()].sort();
+    const gain = bones.filter((x) => d.get(x)! > 0);
+    const loss = bones.filter((x) => d.get(x)! < 0);
+    let theta = 0;
+    let ratio = 0;
+    for (const g of gain) {
+      for (const l of loss) {
+        const key = pairKey(g, l);
+        const t = this.theta.get(key);
+        if (t === undefined) {
+          if (this.plant === 'undeclared-pair-is-rigid') continue;
+          if (this.missing === null) this.missing = { bones: g < l ? [g, l] : [l, g], edge };
+          return null;
+        }
+        theta = Math.max(theta, t);
+        ratio = Math.max(ratio, this.ratio.get(key)!);
+      }
+    }
+    return { theta, ratio };
+  }
+}
+
+function undeclaredPairReason(missing: NonNullable<PairAmplitudes['missing']>): string {
+  return (
+    `motionAmplitude declares no track moving bones "${missing.bones[0]}" and "${missing.bones[1]}", and a share moves between them across ` +
+    `[${missing.edge[0]}, ${missing.edge[1]}]; required a { bones, theta } entry for every pair of bones a share moves between — no amplitude is assumed`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MQ_DEFORM_LOAD
+// ---------------------------------------------------------------------------
+
+/** The largest L · Δshare · θ / 4 over the edges, px, and the edge; `{ edge: null }` when every edge carries none. */
+export function deformLoad(points: readonly Pt[], triangles: readonly number[], weights: Weights, declared: MotionAmplitude, plant: AllocationPlant | null): Reading<{ value: number; edge: [number, number] | null }> {
+  const pairs = new PairAmplitudes(declared, plant);
+  let best = 0;
+  let at: [number, number] | null = null;
+  for (const [u, v] of uniqueEdges(triangles)) {
+    const amp = pairs.across(weights[u], weights[v], [u, v]);
+    if (amp === null) return unmeasured(undeclaredPairReason(pairs.missing!));
+    const theta = plant === 'load-without-theta' ? 1 : amp.theta;
+    const load = (lengthOf(points[u], points[v]) * shareJump(weights[u], weights[v]) * theta) / 4;
+    if (load > best) {
+      best = load;
+      at = [u, v];
+    }
+  }
+  return { measured: true, value: { value: r6(best), edge: at } };
+}
+
+// ---------------------------------------------------------------------------
+// MQ_BOUNDARY_NECESSARY — B*
+// ---------------------------------------------------------------------------
+
+/** How close the search along a chord brings a piece before it stops, px: `HAUSDORFF_TOLERANCE`'s figure. */
+const CHORD_TOLERANCE = 1e-9;
+/** On the chord within this, px, a pixel centre is not cut off by it — `ON_BOUNDARY`'s figure. */
+const ON_CHORD = 1e-9;
+
+/**
+ * Is the furthest point of the chord `a`–`b` from the open polyline `run`
+ * more than `delta`? Exact up to `CHORD_TOLERANCE`, by the branch and bound
+ * `directedHausdorff` (`src/meshquality.ts`) uses: the distance to one segment
+ * is convex along the chord, so on a piece it is at most the larger of its end
+ * values, and the distance to the run is the minimum over its segments.
+ */
+function chordLeavesRun(a: Pt, b: Pt, run: readonly Pt[], delta: number): boolean {
+  const m = run.length - 1;
+  const toEach = (p: Pt): Float64Array => {
+    const out = new Float64Array(m);
+    for (let j = 0; j < m; j++) out[j] = distanceToSegment(p, run[j], run[j + 1]);
+    return out;
+  };
+  const minOf = (g: Float64Array): number => {
+    let v = Infinity;
+    for (let j = 0; j < m; j++) v = Math.min(v, g[j]);
+    return v;
+  };
+  const at = (t: number): Pt => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
+  const g0 = toEach(a);
+  const g1 = toEach(b);
+  if (minOf(g0) > delta || minOf(g1) > delta) return true;
+  const stack: Array<{ t0: number; t1: number; g0: Float64Array; g1: Float64Array; depth: number }> = [{ t0: 0, t1: 1, g0, g1, depth: 0 }];
+  while (stack.length > 0) {
+    const piece = stack.pop()!;
+    let upper = Infinity;
+    for (let j = 0; j < m; j++) upper = Math.min(upper, Math.max(piece.g0[j], piece.g1[j]));
+    if (upper <= delta + CHORD_TOLERANCE || piece.depth >= 64) continue;
+    const tm = (piece.t0 + piece.t1) / 2;
+    const gm = toEach(at(tm));
+    if (minOf(gm) > delta) return true;
+    stack.push({ t0: piece.t0, t1: tm, g0: piece.g0, g1: gm, depth: piece.depth + 1 });
+    stack.push({ t0: tm, t1: piece.t1, g0: gm, g1: piece.g1, depth: piece.depth + 1 });
+  }
+  return false;
+}
+
+/**
+ * Whether the outline `hull` may skip forward from `hull[i]` to `hull[j]`:
+ * every skipped vertex within `delta` of the chord, the chord within `delta`
+ * of the skipped run (both exact), and — unless planted out — no art pixel
+ * centre inside the hull and strictly inside the sliver the chord cuts off
+ * (even-odd over the run closed by the chord; a centre on the chord is kept).
+ */
+export function shortcutTest(hull: readonly Pt[], delta: number, art: AllocationArt, plant: AllocationPlant | null): { valid: (i: number, j: number) => boolean; tests: () => number } {
+  const n = hull.length;
+  const { mask, bits, scale } = art;
+  const w = mask.width;
+  const h = mask.height;
+  let inside: Uint8Array | null = null;
+  let tests = 0;
+  const valid = (i: number, j: number): boolean => {
+    const k = (j - i + n) % n;
+    if (k < 2) return true;
+    tests++;
+    const run: Pt[] = [];
+    for (let s = 0; s <= k; s++) run.push(hull[(i + s) % n]);
+    const a = hull[i];
+    const b = hull[j];
+    for (let s = 1; s < k; s++) if (distanceToSegment(run[s], a, b) > delta) return false;
+    if (chordLeavesRun(a, b, run, delta)) return false;
+    if (plant === 'bstar-ignores-art') return true;
+    if (inside === null) inside = closedPolygonCentres(hull, w, h, scale);
+    let x0 = Infinity;
+    let y0 = Infinity;
+    let x1 = -Infinity;
+    let y1 = -Infinity;
+    for (const p of run) {
+      x0 = Math.min(x0, p[0]);
+      y0 = Math.min(y0, p[1]);
+      x1 = Math.max(x1, p[0]);
+      y1 = Math.max(y1, p[1]);
+    }
+    const gy0 = Math.max(0, Math.floor(y0 * scale) - 1);
+    const gy1 = Math.min(h - 1, Math.ceil(y1 * scale));
+    const gx0 = Math.max(0, Math.floor(x0 * scale) - 1);
+    const gx1 = Math.min(w - 1, Math.ceil(x1 * scale));
+    for (let y = gy0; y <= gy1; y++) {
+      for (let x = gx0; x <= gx1; x++) {
+        const cell = y * w + x;
+        if (!inside[cell] || !bits[cell]) continue;
+        const c: Pt = [(x + 0.5) / scale, (y + 0.5) / scale];
+        if (distanceToSegment(c, a, b) <= ON_CHORD) continue;
+        let odd = false;
+        for (let p = 0, q = run.length - 1; p < run.length; q = p++) {
+          const [xp, yp] = run[p];
+          const [xq, yq] = run[q];
+          if (yp > c[1] !== yq > c[1] && c[0] < ((xq - xp) * (c[1] - yp)) / (yq - yp) + xp) odd = !odd;
+        }
+        if (odd) return false;
+      }
+    }
+    return true;
+  };
+  return { valid, tests: () => tests };
+}
+
+/** B\*, its outline (indices into the hull, in walk order) and the work the search took. */
+export interface BoundaryNecessity {
+  count: number;
+  path: number[];
+  /** Shortcuts tested; at most n × (n − 2) for n hull vertices — every forward skip of 2 or more from every vertex, once. */
+  tests: number;
+  /** n × (n − 2): the bound `tests` is held to. */
+  bound: number;
+}
+
+/**
+ * B\*: the fewest vertices of `hull` a closed outline of at least three of
+ * them can keep, in order, when each skip is a valid shortcut. Every forward
+ * shortcut from every vertex is tested once (n × (n − 2) tests at most), then
+ * a breadth-first walk round the loop from every start, its hop count capped
+ * at 3 so a two-vertex "outline" is never the answer. Ties: the lowest start,
+ * then the first path found in ascending offsets.
+ */
+export function boundaryNecessity(hull: readonly Pt[], delta: number, art: AllocationArt, plant: AllocationPlant | null): BoundaryNecessity {
+  const n = hull.length;
+  const shortcut = shortcutTest(hull, delta, art, plant);
+  const adj: number[][] = [];
+  for (let i = 0; i < n; i++) {
+    const out: number[] = [];
+    for (let k = 1; k < n; k++) if (shortcut.valid(i, (i + k) % n)) out.push(k);
+    adj.push(out);
+  }
+  let best = n;
+  let bestPath = hull.map((_, i) => i);
+  // States: (offset, hops capped at 3). dist[off * 4 + c].
+  for (let s = 0; s < n; s++) {
+    const dist = new Array<number>((n + 1) * 4).fill(Infinity);
+    const prev = new Array<number>((n + 1) * 4).fill(-1);
+    dist[0] = 0;
+    for (let off = 0; off < n; off++) {
+      for (let c = 0; c < 4; c++) {
+        const here = dist[off * 4 + c];
+        if (here === Infinity) continue;
+        for (const k of adj[(s + off) % n]) {
+          if (off + k > n) continue;
+          const nc = Math.min(c + 1, 3);
+          const to = (off + k) * 4 + nc;
+          if (here + 1 < dist[to]) {
+            dist[to] = here + 1;
+            prev[to] = off * 4 + c;
+          }
+        }
+      }
+    }
+    const end = n * 4 + 3;
+    if (dist[end] < best) {
+      best = dist[end];
+      const path: number[] = [];
+      for (let st = prev[end]; st > 0; st = prev[st]) path.push((s + Math.floor(st / 4)) % n);
+      path.push(s);
+      bestPath = path.reverse();
+    }
+  }
+  return { count: best, path: bestPath, tests: shortcut.tests(), bound: n * (n - 2) };
+}
+
+/**
+ * B\* for one hull, delta and art, once per art rasters object: `reduceMesh`
+ * measures every step against the same source hull, so its B\* is a function
+ * of the call and is computed once for it. Keyed by the hull's coordinates and
+ * the deviation; the plant is part of the key.
+ */
+const necessityMemo = new WeakMap<object, Map<string, BoundaryNecessity>>();
+
+export function boundaryNecessityOnce(owner: object, hull: readonly Pt[], delta: number, art: AllocationArt, plant: AllocationPlant | null): BoundaryNecessity {
+  let memo = necessityMemo.get(owner);
+  if (memo === undefined) {
+    memo = new Map();
+    necessityMemo.set(owner, memo);
+  }
+  const key = `${plant ?? ''}|${delta}|${hull.map((p) => `${p[0]},${p[1]}`).join(';')}`;
+  let found = memo.get(key);
+  if (found === undefined) {
+    found = boundaryNecessity(hull, delta, art, plant);
+    memo.set(key, found);
+  }
+  return found;
+}
+
+// ---------------------------------------------------------------------------
+// MQ_ALLOCATION_CONTRAST — Δ and E
+// ---------------------------------------------------------------------------
+
+export interface AllocationContrast {
+  /** Δ: removable-alone share among the dense vertices minus that share among the rest. */
+  contrast: number;
+  /** E: the removable-alone share over every vertex. */
+  economy: number;
+  dense: { vertices: number; removableAlone: number };
+  rest: { vertices: number; removableAlone: number };
+  /** The dense vertex with the lowest ν (ties: the lowest index). */
+  worstVertex: number;
+}
+
+/** h\*: the largest local size every primary need allows at a point, each relaxed at gradation G away from its source. */
+interface Need {
+  at(p: Pt): number;
+}
+
+function needField(points: readonly Pt[], triangles: readonly number[], weights: Weights, silhouette: number[] | null, regions: readonly RefinementRegion[], pairs: PairAmplitudes, gradation: number): Need | null {
+  const sources: Array<{ a: Pt; b: Pt; h: number }> = [];
+  if (silhouette !== null && silhouette.length >= 3) {
+    for (let i = 0; i < silhouette.length; i++) {
+      const a = points[silhouette[i]];
+      const b = points[silhouette[(i + 1) % silhouette.length]];
+      sources.push({ a, b, h: lengthOf(a, b) });
+    }
+  }
+  const bones = [...new Set(weights.flatMap((v) => v.map((x) => x.bone)))].sort();
+  for (let t = 0; t + 2 < triangles.length; t += 3) {
+    const [i, j, k] = [triangles[t], triangles[t + 1], triangles[t + 2]];
+    const [A, B, C] = [points[i], points[j], points[k]];
+    const det = (B[0] - A[0]) * (C[1] - A[1]) - (C[0] - A[0]) * (B[1] - A[1]);
+    if (Math.abs(det) < 1e-12) continue;
+    let tv = 0;
+    for (const bone of bones) {
+      const wt = (v: number): number => weights[v].find((x) => x.bone === bone)?.weight ?? 0;
+      const [wa, wb, wc] = [wt(i), wt(j), wt(k)];
+      const gx = ((wb - wa) * (C[1] - A[1]) - (wc - wa) * (B[1] - A[1])) / det;
+      const gy = ((wc - wa) * (B[0] - A[0]) - (wb - wa) * (C[0] - A[0])) / det;
+      tv += Math.hypot(gx, gy);
+    }
+    tv /= 2;
+    if (tv <= 0) continue;
+    let ratio = 0;
+    for (const [u, v] of [
+      [i, j],
+      [j, k],
+      [k, i],
+    ] as const) {
+      const amp = pairs.across(weights[u], weights[v], [Math.min(u, v), Math.max(u, v)]);
+      if (amp === null) return null;
+      ratio = Math.max(ratio, amp.ratio);
+    }
+    if (ratio <= 0) continue;
+    const c: Pt = [(A[0] + B[0] + C[0]) / 3, (A[1] + B[1] + C[1]) / 3];
+    sources.push({ a: c, b: c, h: Math.sqrt(4 / (ratio * tv)) });
+  }
+  return {
+    at(p: Pt): number {
+      let need = Infinity;
+      for (const s of sources) need = Math.min(need, s.h + gradation * distanceToSegment(p, s.a, s.b));
+      for (const r of regions) {
+        const poly = r.polygon;
+        let d = 0;
+        if (!inClosedPolygon(p, poly)) {
+          d = Infinity;
+          for (let q = 0; q < poly.length; q++) d = Math.min(d, distanceToSegment(p, poly[q], poly[(q + 1) % poly.length]));
+        }
+        const here = d === 0 ? r.maxEdgeLength : r.transition > 0 && d <= r.transition ? r.maxEdgeLength + r.grade * d : Infinity;
+        need = Math.min(need, here);
+      }
+      return need;
+    },
+  };
+}
+
+const twiceSigned = (a: Pt, b: Pt, c: Pt): number => (b[0] - a[0]) * (c[1] - a[1]) - (c[0] - a[0]) * (b[1] - a[1]);
+
+/**
+ * Δ and E (§8; the stage-A record for #1271, M7). For each vertex the
+ * cheapest half-edge collapse into a neighbour — a hull vertex only along the
+ * hull — that turns no triangle over; ν is the largest, over what that
+ * collapse changes, of: the silhouette (the moved outline's chord distance
+ * over δ, and the skip must pass the art test), the deformation (each new
+ * edge's L · Δshare · θ / (4ε)), the region (each new edge over the bound its
+ * region holds it to, `regionEdgeBound`) and the need (each new edge over h\*
+ * at its midpoint). A ratio already over 1 on the edge it replaces counts only
+ * by how much it worsens it. ν < 1 is removable alone. Dense vertices are
+ * those whose mean neighbour distance (on the `r6` grid, so the class is not
+ * a summation order's) is below the area-weighted median of it.
+ */
+export function allocationContrast(
+  points: readonly Pt[],
+  triangles: readonly number[],
+  hull: number,
+  weights: Weights,
+  delta: number,
+  art: AllocationArt,
+  regions: readonly RefinementRegion[],
+  declared: MotionAmplitude,
+  silhouette: number[],
+  plant: AllocationPlant | null,
+): Reading<AllocationContrast> {
+  const n = points.length;
+  const pairs = new PairAmplitudes(declared, plant);
+  const amplitudeRead = plant !== 'contrast-without-amplitude';
+  const need = needField(points, triangles, weights, silhouette, regions, amplitudeRead ? pairs : new PairAmplitudes({ tracks: [], gradation: declared.gradation }, 'undeclared-pair-is-rigid'), declared.gradation);
+  if (need === null) return unmeasured(undeclaredPairReason(pairs.missing!));
+  const nb: Array<Set<number>> = Array.from({ length: n }, () => new Set<number>());
+  const triOf: number[][] = Array.from({ length: n }, () => []);
+  for (let t = 0; t + 2 < triangles.length; t += 3) {
+    for (let k = 0; k < 3; k++) {
+      const a = triangles[t + k];
+      nb[a].add(triangles[t + ((k + 1) % 3)]);
+      nb[a].add(triangles[t + ((k + 2) % 3)]);
+      triOf[a].push(t);
+    }
+  }
+  const neighbours = nb.map((s) => [...s].sort((p, q) => p - q));
+  const hullPoints = points.slice(0, hull);
+  const shortcut = shortcutTest(hullPoints, delta, art, null);
+  const adjacentOnHull = (v: number, w: number): boolean => w < hull && (Math.abs(w - v) === 1 || Math.abs(w - v) === hull - 1);
+  const term = (now: number, before: number): number => (now <= 1 ? now : now / Math.max(1, before));
+  const nu = new Array<number>(n).fill(Infinity);
+  for (let v = 0; v < n; v++) {
+    const isHull = v < hull;
+    for (const w of neighbours[v]) {
+      if (isHull && !adjacentOnHull(v, w)) continue;
+      let folds = false;
+      for (const t of triOf[v]) {
+        const tri = [triangles[t], triangles[t + 1], triangles[t + 2]];
+        if (tri.includes(w)) continue;
+        const before = twiceSigned(points[tri[0]], points[tri[1]], points[tri[2]]);
+        const moved = tri.map((i) => (i === v ? points[w] : points[i]));
+        const after = twiceSigned(moved[0], moved[1], moved[2]);
+        if (Math.sign(after) !== Math.sign(before) || Math.abs(after) < 1e-9) {
+          folds = true;
+          break;
+        }
+      }
+      if (folds) continue;
+      let worst = 0;
+      if (isHull) {
+        const other = v === (w + 1) % hull ? (v + 1) % hull : (v - 1 + hull) % hull;
+        worst = Math.max(worst, distanceToSegment(points[v], points[w], points[other]) / delta);
+        const [from, to] = other === (v + 1) % hull ? [w, other] : [other, w];
+        if (!shortcut.valid(from, to)) worst = Math.max(worst, 1);
+      }
+      for (const u of neighbours[v]) {
+        if (u === w) continue;
+        const a = points[w];
+        const b = points[u];
+        const L = lengthOf(a, b);
+        const L0 = lengthOf(points[v], b);
+        if (amplitudeRead) {
+          const now = pairs.across(weights[w], weights[u], [Math.min(w, u), Math.max(w, u)]);
+          const was = pairs.across(weights[v], weights[u], [Math.min(v, u), Math.max(v, u)]);
+          if (now === null || was === null) return unmeasured(undeclaredPairReason(pairs.missing!));
+          worst = Math.max(worst, term((L * shareJump(weights[w], weights[u]) * now.ratio) / 4, (L0 * shareJump(weights[v], weights[u]) * was.ratio) / 4));
+        }
+        const rb = regionEdgeBound(a, b, regions);
+        if (rb !== null) {
+          const rb0 = regionEdgeBound(points[v], b, regions);
+          worst = Math.max(worst, term(L / rb, rb0 === null ? 0 : L0 / rb0));
+        }
+        const q = need.at([(a[0] + b[0]) / 2, (a[1] + b[1]) / 2]);
+        if (Number.isFinite(q)) {
+          const q0 = need.at([(points[v][0] + b[0]) / 2, (points[v][1] + b[1]) / 2]);
+          worst = Math.max(worst, term(L / q, Number.isFinite(q0) ? L0 / q0 : 0));
+        }
+      }
+      nu[v] = Math.min(nu[v], worst);
+    }
+  }
+  const area = new Array<number>(n).fill(0);
+  for (let t = 0; t + 2 < triangles.length; t += 3) {
+    const third = Math.abs(twiceSigned(points[triangles[t]], points[triangles[t + 1]], points[triangles[t + 2]])) / 6;
+    for (let k = 0; k < 3; k++) area[triangles[t + k]] += third;
+  }
+  const local = neighbours.map((s, x) => (s.length === 0 ? 0 : r6(s.reduce((sum, y) => sum + lengthOf(points[x], points[y]), 0) / s.length)));
+  const order = local.map((_, i) => i).sort((i, j) => local[i] - local[j] || i - j);
+  const total = area.reduce((s, x) => s + x, 0);
+  let median = local[order[order.length - 1]];
+  let acc = 0;
+  for (const i of order) {
+    acc += area[i];
+    if (acc >= 0.5 * total) {
+      median = local[i];
+      break;
+    }
+  }
+  const removable = (i: number): boolean => nu[i] < 1;
+  const dense = local.map((_, i) => i).filter((i) => local[i] < median);
+  const rest = local.map((_, i) => i).filter((i) => local[i] >= median);
+  if (dense.length === 0) return unmeasured(`no vertex's local size is below the area-weighted median ${r6(median)} px, so there is no dense part to contrast`);
+  if (rest.length === 0) return unmeasured('every vertex is below the area-weighted median local size, so there is no rest to contrast the dense part with');
+  const denseRemovable = dense.filter(removable).length;
+  const restRemovable = rest.filter(removable).length;
+  let worstVertex = dense[0];
+  for (const i of dense) if (nu[i] < nu[worstVertex]) worstVertex = i;
+  return {
+    measured: true,
+    value: {
+      contrast: r6(denseRemovable / dense.length - restRemovable / rest.length),
+      economy: r6(nu.filter((x) => x < 1).length / n),
+      dense: { vertices: dense.length, removableAlone: denseRemovable },
+      rest: { vertices: rest.length, removableAlone: restRemovable },
+      worstVertex,
+    },
+  };
+}

package/src/meshquality.ts

@@ -70,6 +70,7 @@ import {
   type MeshOutline,
 } from './mesh.ts';
 import { areaBand, triangleAreas } from './areaband.ts';
+import { allocationContrast, boundaryNecessityOnce, deformLoad, gradeMax, minAngleP10, type AllocationArt, type AllocationPlant } from './meshallocation.ts';
 import { artRastersOf, type ArtRasters, type CoverageReading, type OutlineMemo, type RegionEdgeReading, type SilhouetteReading, type StepRasters } from './meshrasters.ts';
 import { cropToSpineY } from './transform.ts';
 
@@ -311,6 +312,41 @@ export interface MeshMeasureInput {
   influences: InfluenceLimits | null;
   boneOrder: string[] | null;
   preset: { name: string; version: string } | null;
+  /**
+   * Issue #1280 (§8, [agreed, rig-parts#126] Q2): the motion amplitude the two weight-aware allocation rows read —
+   * `MQ_ALLOCATION_CONTRAST` and `MQ_DEFORM_LOAD`. Left out, it is not declared and those two rows are
+   * `not-measurable`, naming this field; `null` declares it absent, with the same result and a reason saying so (as a
+   * `null` art bound is declared absent, #1257). It declares no bound: every allocation row stays `undeclared`.
+   */
+  motionAmplitude?: MotionAmplitude | null;
+}
+
+/**
+ * Issue #1280: the amplitude a caller's motion moves a mesh's weight field by, per track, as the allocation rows read
+ * it. Nothing in it has a default; nothing in it gates anything.
+ */
+export interface MotionAmplitude {
+  /** One entry per track the caller declares (an animation, a parameter axis — its name is echoed, never read). */
+  tracks: TrackAmplitude[];
+  /**
+   * G, px per px: how fast a declared need relaxes away from its source — the size a need allows at distance d is its
+   * own plus G × d (the form of a region's `grade`). Read by `MQ_ALLOCATION_CONTRAST` only. Finite, 0 or more.
+   */
+  gradation: number;
+}
+
+/** One track's amplitude: the pairs of bones a share moves between in it, each with θ, and the track's ε. */
+export interface TrackAmplitude {
+  /** The caller's name for the track; echoed, never read. */
+  track: string;
+  /**
+   * Each pair of bones whose relative transform the track moves, and θ: the largest ‖M − I‖ of the relative linear
+   * part M over the track — 2 sin(α / 2) for a rotation by α (≈ α in radians for a small one), |s − 1| for a uniform
+   * scale by s. Dimensionless, finite, 0 or more. A pair is unordered; declared twice, the larger θ is read.
+   */
+  pairs: Array<{ bones: [string, string]; theta: number }>;
+  /** ε, drawing px: the chord error the track tolerates — what a deformation need is sized against. Finite, above 0. */
+  epsilon: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -344,6 +380,18 @@ export interface MeasureRow {
   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;
+  /** The five allocation rows only (issue #1280): what the value is a reading of, and what it was read from. */
+  allocation?: AllocationDetail;
+}
+
+/** Issue #1280: an allocation row's own fields. Written on those five rows, measured or not, and on no other. */
+export interface AllocationDetail {
+  /** One sentence: what the value is a reading of — and, for `MQ_DEFORM_LOAD`, that it is not predicted motion. */
+  reading: string;
+  /** `MQ_ALLOCATION_CONTRAST` when measured: economy E, and the counts Δ and E are taken from. */
+  contrast?: { economy: number; dense: { vertices: number; removableAlone: number }; rest: { vertices: number; removableAlone: number } };
+  /** `MQ_BOUNDARY_NECESSARY` when measured: the shortcuts the search tested, and the bound n × (n − 2) it is held to. */
+  search?: { shortcutsTested: number; bound: number };
 }
 
 /** Correction 2: the spatial grid and the value's own granularity are two fields. */
@@ -494,6 +542,8 @@ export interface EffectiveSettings {
   stopAfterAccepted?: number;
   /** A reduction's `boundaryRuns`, echoed when the input set it (issue #1279); absent otherwise. */
   boundaryRuns?: BoundaryRuns;
+  /** A measurement's `motionAmplitude`, echoed when the input set it — `null` included (issue #1280); absent otherwise. */
+  motionAmplitude?: MotionAmplitude | null;
 }
 
 export interface MeshCounts {
@@ -746,6 +796,33 @@ function validateInput(input: MeshMeasureInput): void {
   if (input.preset !== null && (!isObject(input.preset) || typeof input.preset.name !== 'string' || typeof input.preset.version !== 'string')) {
     refuse('REDUCE_INPUT_MISSING', `${who}: preset is not { name, version }; required that, or null`);
   }
+  validateAmplitude(who, input.motionAmplitude);
+}
+
+/** Issue #1280: `motionAmplitude` left out or `null` is accepted as it stands; anything else is a `MotionAmplitude` in full. */
+function validateAmplitude(who: string, amplitude: unknown): void {
+  if (amplitude === undefined || amplitude === null) return;
+  const shape = '{ tracks: [{ track, pairs: [{ bones: [a, b], theta }], epsilon }], gradation }';
+  if (!isObject(amplitude) || !Array.isArray(amplitude.tracks)) refuse('REDUCE_INPUT_MISSING', `${who}: motionAmplitude is ${JSON.stringify(amplitude)}; required ${shape}, null, or the field left out`);
+  if (!isFiniteNumber(amplitude.gradation) || amplitude.gradation < 0) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: motionAmplitude.gradation is ${JSON.stringify(amplitude.gradation)}; required a finite number of px per px, 0 or more — no gradation is assumed`);
+  }
+  amplitude.tracks.forEach((track: unknown, i: number) => {
+    const at = `motionAmplitude.tracks[${i}]`;
+    if (!isObject(track) || typeof track.track !== 'string' || track.track === '' || !Array.isArray(track.pairs)) {
+      refuse('REDUCE_INPUT_MISSING', `${who}: ${at} is ${JSON.stringify(track)}; required { track: a non-empty name, pairs: a list, epsilon }`);
+    }
+    if (!isFiniteNumber(track.epsilon) || track.epsilon <= 0) refuse('REDUCE_INPUT_MISSING', `${who}: ${at}.epsilon is ${JSON.stringify(track.epsilon)}; required a finite number of px above 0`);
+    track.pairs.forEach((pair: unknown, j: number) => {
+      const here = `${at}.pairs[${j}]`;
+      const bones = isObject(pair) ? pair.bones : undefined;
+      if (!Array.isArray(bones) || bones.length !== 2 || bones.some((b) => typeof b !== 'string' || b === '') || bones[0] === bones[1]) {
+        refuse('REDUCE_INPUT_MISSING', `${who}: ${here}.bones is ${JSON.stringify(bones)}; required two different bone names`);
+      }
+      const theta = (pair as Record<string, unknown>).theta;
+      if (!isFiniteNumber(theta) || theta < 0) refuse('REDUCE_INPUT_MISSING', `${who}: ${here}.theta is ${JSON.stringify(theta)}; required a finite number, 0 or more (‖M − I‖ of the pair's relative linear part)`);
+    });
+  });
 }
 
 // ---------------------------------------------------------------------------
@@ -1013,6 +1090,24 @@ export function edgeIsHeldByRegion(a: readonly [number, number], b: readonly [nu
   return (last - first) * length > BAND_CONTACT_TOLERANCE;
 }
 
+/**
+ * The density bound the regions hold the segment `a`–`b` to, as `regionRows` reads it for a mesh edge — the
+ * smallest over every region that holds it (`edgeIsHeldByRegion`): `L0` where it meets the closed polygon, else
+ * `L0 + grade·d` on the `r6` grid — or null when no region holds it. Read by `MQ_ALLOCATION_CONTRAST` (issue #1280)
+ * for the edges a collapse would create. The regions are taken as given: the caller has refused any that
+ * `regionRefusal` refuses. Internal, as `measureMeshQualityWith` is: on `rig-c/mesh` only through `export *`.
+ */
+export function regionEdgeBound(a: readonly [number, number], b: readonly [number, number], regions: readonly RefinementRegion[]): number | null {
+  let bound: number | null = null;
+  for (const region of regions) {
+    if (!edgeIsHeldByRegion(a, b, region)) continue;
+    const d = segmentToPolygon(a, b, region.polygon);
+    const here = d === 0 ? region.maxEdgeLength : r6(region.maxEdgeLength + region.grade * d);
+    if (bound === null || here < bound) bound = here;
+  }
+  return bound;
+}
+
 /** 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;
@@ -1321,7 +1416,17 @@ function compareRows(a: MeasureRow, b: MeasureRow): number {
  */
 export function measureMeshQuality(input: MeshMeasureInput): MeshQualityReport {
   validateInput(input);
-  return measureValidated(input, artRastersOf(input.art), null);
+  return measureValidated(input, artRastersOf(input.art), null, null);
+}
+
+/**
+ * `measureMeshQuality` with a fault planted in its allocation rows (issue #1280, `AllocationPlant` in
+ * `src/meshallocation.ts`) — the `mesh-quality` suite's negative controls, and with `omit-rows` the report without
+ * those rows that the opt-out identity is held to. Internal, as `measureMeshQualityWith` is.
+ */
+export function measureMeshQualityPlanted(input: MeshMeasureInput, plant: AllocationPlant): MeshQualityReport {
+  validateInput(input);
+  return measureValidated(input, artRastersOf(input.art), null, plant);
 }
 
 /**
@@ -1340,7 +1445,7 @@ export function measureMeshQuality(input: MeshMeasureInput): MeshQualityReport {
 export function measureMeshQualityWith(input: MeshMeasureInput, rasters: ArtRasters): MeshQualityReport {
   validateInput(input);
   checkArtRasters(input, rasters);
-  return measureValidated(input, rasters, null);
+  return measureValidated(input, rasters, null, null);
 }
 
 /**
@@ -1357,7 +1462,7 @@ export function measureMeshQualityWith(input: MeshMeasureInput, rasters: ArtRast
 export function measureMeshQualityStep(input: MeshMeasureInput, steps: StepRasters): MeshQualityReport {
   validateInput(input);
   checkArtRasters(input, steps.rasters);
-  return measureValidated(input, steps.rasters, steps);
+  return measureValidated(input, steps.rasters, steps, null);
 }
 
 /**
@@ -1433,7 +1538,7 @@ function checkArtRasters(input: MeshMeasureInput, rasters: ArtRasters): void {
 }
 
 /** The measurement proper, over an input `validateInput` accepted and rasters taken from its art. */
-function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: StepRasters | null): MeshQualityReport {
+function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: StepRasters | null, plant: AllocationPlant | null): MeshQualityReport {
   rasters.tally.uses++;
   const { attachment, art, source, targets } = input;
   const { mask, threshold, frame } = art;
@@ -1472,6 +1577,9 @@ function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: S
   const points: Pt[] = source.points;
   const hullPolygon: Pt[] = outline.walk.map((v) => points[v]);
 
+  // --- allocation rows (issue #1280): undeclared or not-measurable, never required ------------
+  if (plant !== 'omit-rows') rows.push(...allocationRows(input, outline, rasters, steps, plant));
+
   // --- raster rows ---------------------------------------------------------
   const w = mask.width;
   const h = mask.height;
@@ -1623,6 +1731,131 @@ function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: S
   return report(counts, { id: input.id, counts, geometry, motion: null, accepted }, null);
 }
 
+/** What each allocation row is a reading of — `AllocationDetail.reading`, one fixed sentence per code. */
+const ALLOCATION_READINGS: Record<string, string> = {
+  MQ_GRADE:
+    'the largest |h_u − h_v| / L over the edges, h a vertex\'s mean incident edge length: how abruptly the local size changes, whether or not the density is justified',
+  MQ_MIN_ANGLE_P10: 'the tenth percentile, nearest rank, of the triangles\' smallest angles: sliver fans, where MQ_MIN_ANGLE reads the single worst triangle',
+  MQ_ALLOCATION_CONTRAST:
+    'Δ: the share of the dense vertices removable alone against the declared needs (silhouette, deformation under motionAmplitude, regions) minus that share among the rest; economy E is the share of all',
+  MQ_DEFORM_LOAD:
+    'the largest L · Δshare · θ / 4 over the edges, Δshare the share of weight that moves across the edge: a bound on the chord error of the mesh\'s own weight field under motionAmplitude, read to locate the edge; it is not predicted motion and no difference to any reference (docs/MESH_REDUCTION.md §8)',
+  MQ_BOUNDARY_NECESSARY:
+    'B*: the fewest vertices of the reference hull a closed outline can keep with every skipped run within maxBoundaryDeviation of its chord both ways and no art pixel centre cut off (overshoot is not tested); worst is the first hull vertex of this mesh not on that outline',
+};
+
+/**
+ * The five allocation rows (issue #1280; docs/MESH_REDUCTION.md §8): each `undeclared` with its value and worst
+ * sample, or `not-measurable` with the sentence naming what is missing — never required, so none can block a step,
+ * refuse a source, or count towards acceptance. `MQ_BOUNDARY_NECESSARY` is read against the reference hull once per
+ * art rasters object (`boundaryNecessityOnce`), so a reduction computes it once per call.
+ */
+function allocationRows(input: MeshMeasureInput, outline: MeshOutline, rasters: ArtRasters, steps: StepRasters | null, plant: AllocationPlant | null): Built[] {
+  const { attachment, source, targets, art } = input;
+  const who = `attachment ${nameOf(attachment)}`;
+  if (plant === 'mutates-input') {
+    const tris = source.triangles;
+    for (let t = 0; t + 2 < tris.length; t += 3) [tris[t + 1], tris[t + 2]] = [tris[t + 2], tris[t + 1]];
+  }
+  const points: Pt[] = source.points;
+  const out: Built[] = [];
+  const row = (code: string, unit: MeasureRow['unit'], built: Built, detail: Omit<AllocationDetail, 'reading'> = {}): void => {
+    built.row.allocation = { reading: ALLOCATION_READINGS[code], ...detail };
+    if (plant === 'rows-required') built.required = true;
+    out.push(built);
+  };
+  const spec = (code: string, unit: MeasureRow['unit']): RowSpec => ({ code, unit, region: null, attachment });
+  const measured = (code: string, unit: MeasureRow['unit'], value: number, worst: WorstSample): Built => measuredRow(spec(code, unit), value, null, worst, false);
+  const missing = (code: string, unit: MeasureRow['unit'], reason: string): Built => unmeasuredRow(spec(code, unit), 'not-measurable', reason, false);
+
+  // Geometry alone.
+  const grade = gradeMax(points, source.triangles, plant);
+  row('MQ_GRADE', 'ratio', grade.measured ? measured('MQ_GRADE', 'ratio', grade.value.value, { at: { edge: grade.value.edge } }) : missing('MQ_GRADE', 'ratio', `${who}: ${grade.reason}`));
+  const p10 = minAngleP10(points, source.triangles, plant);
+  row(
+    'MQ_MIN_ANGLE_P10',
+    'degrees',
+    p10.measured ? measured('MQ_MIN_ANGLE_P10', 'degrees', p10.value.value, { at: { triangle: p10.value.triangle } }) : missing('MQ_MIN_ANGLE_P10', 'degrees', `${who}: ${p10.reason}`),
+  );
+
+  // What the weight-aware and art-reading rows need.
+  const amplitude = input.motionAmplitude;
+  const amplitudeMissing =
+    amplitude === undefined
+      ? `${who}: motionAmplitude is not declared (the field is left out), so no motion amplitude sizes a deformation need; required { tracks, gradation } — no amplitude is assumed, and without one no reading of justification separates anything (§8)`
+      : amplitude === null
+        ? `${who}: motionAmplitude is declared absent (null), so no motion amplitude sizes a deformation need; required { tracks, gradation } for this row — no amplitude is assumed`
+        : null;
+  const unweighted = source.weights === null ? `${who}: source.weights is null — an unweighted mesh has no weight field for a motion to move` : null;
+  const delta = targets.maxBoundaryDeviation;
+  const noDelta = delta === null ? `${who}: targets.maxBoundaryDeviation is null, so no skip of the outline has a deviation to be held to` : null;
+  const artCount = rasters.artCount();
+  const fewArt =
+    artCount < input.minArtSamples
+      ? `${who} has ${artCount} art sample(s) at alpha >= ${art.threshold}; required at least ${input.minArtSamples} (minArtSamples, P9) — a row over fewer is not a measurement`
+      : null;
+  const allocationArt: AllocationArt = { mask: art.mask, bits: rasters.artBits(), scale: art.frame.pageScale };
+
+  // MQ_DEFORM_LOAD.
+  const loadWhy = amplitudeMissing ?? unweighted;
+  if (loadWhy !== null || amplitude === undefined || amplitude === null || source.weights === null) {
+    row('MQ_DEFORM_LOAD', 'px', missing('MQ_DEFORM_LOAD', 'px', loadWhy ?? ''));
+  } else {
+    const load = deformLoad(points, source.triangles, source.weights, amplitude, plant);
+    row(
+      'MQ_DEFORM_LOAD',
+      'px',
+      load.measured
+        ? measured('MQ_DEFORM_LOAD', 'px', load.value.value, load.value.edge === null ? NOTHING_WORSE : { at: { edge: load.value.edge } })
+        : missing('MQ_DEFORM_LOAD', 'px', `${who}: ${load.reason}`),
+    );
+  }
+
+  // MQ_ALLOCATION_CONTRAST.
+  const planted = plant === 'contrast-without-amplitude' && (amplitude === undefined || amplitude === null) ? { tracks: [], gradation: 0 } : null;
+  const declared = planted ?? amplitude;
+  let regionWhy: string | null = null;
+  for (const region of targets.regions) {
+    const refusal = regionRefusal(region, art.frame.pageScale, who, steps);
+    if (refusal !== null) {
+      regionWhy = `${who}: region "${region.name}" is refused (${refusal.code}), so its density cannot be read as a declared need`;
+      break;
+    }
+  }
+  const contrastWhy = (planted === null ? amplitudeMissing : null) ?? unweighted ?? noDelta ?? fewArt ?? regionWhy;
+  if (contrastWhy !== null || declared === undefined || declared === null || source.weights === null || delta === null) {
+    row('MQ_ALLOCATION_CONTRAST', 'fraction', missing('MQ_ALLOCATION_CONTRAST', 'fraction', contrastWhy ?? ''));
+  } else {
+    const ownHull = points.slice(0, outline.hull);
+    const silhouette = boundaryNecessityOnce(rasters, ownHull, delta, allocationArt, null).path;
+    const contrast = allocationContrast(points, source.triangles, outline.hull, source.weights, delta, allocationArt, targets.regions, declared, silhouette, plant);
+    if (contrast.measured) {
+      const c = contrast.value;
+      row('MQ_ALLOCATION_CONTRAST', 'fraction', measured('MQ_ALLOCATION_CONTRAST', 'fraction', c.contrast, { at: { vertex: c.worstVertex } }), {
+        contrast: { economy: c.economy, dense: c.dense, rest: c.rest },
+      });
+    } else {
+      row('MQ_ALLOCATION_CONTRAST', 'fraction', missing('MQ_ALLOCATION_CONTRAST', 'fraction', `${who}: ${contrast.reason}`));
+    }
+  }
+
+  // MQ_BOUNDARY_NECESSARY.
+  const reference = input.referenceHull;
+  const noReference = reference === null ? `${who}: no referenceHull was given, so there is no source hull to find the necessary outline of` : null;
+  const necessaryWhy = noReference ?? noDelta ?? fewArt;
+  if (necessaryWhy !== null || reference === null || delta === null) {
+    row('MQ_BOUNDARY_NECESSARY', 'count', missing('MQ_BOUNDARY_NECESSARY', 'count', necessaryWhy ?? ''));
+  } else {
+    const found = boundaryNecessityOnce(rasters, reference, delta, allocationArt, plant);
+    const kept = new Set(found.path.map((i) => pointKey(reference[i])));
+    const beyond = outline.walk.find((v) => !kept.has(pointKey(points[v])));
+    row('MQ_BOUNDARY_NECESSARY', 'count', measured('MQ_BOUNDARY_NECESSARY', 'count', found.count, beyond === undefined ? NOTHING_WORSE : { at: { vertex: beyond } }), {
+      search: { shortcutsTested: found.tests, bound: found.bound },
+    });
+  }
+  return out;
+}
+
 /** What one source states about itself: hull and interior from the outline, bindings from the weights. */
 function countsOf(source: SourceMesh, outline: MeshOutline): MeshCounts {
   const bindings = source.weights === null ? 0 : source.weights.reduce((s, v) => s + v.length, 0);
@@ -1934,6 +2167,7 @@ function effectiveOf(input: MeshMeasureInput): EffectiveSettings {
     boneOrder: input.boneOrder,
     schedule: null,
     budget: null,
+    ...(input.motionAmplitude === undefined ? {} : { motionAmplitude: input.motionAmplitude }),
   };
 }
 
@@ -2024,6 +2258,7 @@ function effectiveJson(e: EffectiveSettings): Json {
     budget: e.budget === null ? null : { maxCandidates: e.budget.maxCandidates },
     ...(e.stopAfterAccepted === undefined ? {} : { stopAfterAccepted: e.stopAfterAccepted }),
     ...(e.boundaryRuns === undefined ? {} : { boundaryRuns: { maxVertices: e.boundaryRuns.maxVertices } }),
+    ...(e.motionAmplitude === undefined ? {} : { motionAmplitude: amplitudeJson(e.motionAmplitude) }),
   };
 }
 
@@ -2067,9 +2302,32 @@ 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);
+  if (r.allocation !== undefined) out.allocation = allocationDetailJson(r.allocation);
   return out;
 }
 
+function allocationDetailJson(a: AllocationDetail): Json {
+  const out: { [key: string]: Json } = { reading: a.reading };
+  if (a.contrast !== undefined) {
+    const c = a.contrast;
+    out.contrast = {
+      economy: c.economy,
+      dense: { vertices: c.dense.vertices, removableAlone: c.dense.removableAlone },
+      rest: { vertices: c.rest.vertices, removableAlone: c.rest.removableAlone },
+    };
+  }
+  if (a.search !== undefined) out.search = { shortcutsTested: a.search.shortcutsTested, bound: a.search.bound };
+  return out;
+}
+
+function amplitudeJson(a: MotionAmplitude | null): Json {
+  if (a === null) return null;
+  return {
+    tracks: a.tracks.map((t) => ({ track: t.track, pairs: t.pairs.map((p) => ({ bones: [p.bones[0], p.bones[1]], theta: p.theta })), epsilon: t.epsilon })),
+    gradation: a.gradation,
+  };
+}
+
 function sectionJson(s: EvidenceSection): { [key: string]: Json } {
   const m = s.summary;
   return {