spine-rigc 2.17.0 → 2.18.0

package/src/meshquality.ts

@@ -0,0 +1,1507 @@
+/**
+ * Mesh quality, measured without posing anything — the geometry half of the
+ * contract in docs/MESH_REDUCTION.md (issue #1221, stage B1: issue #1224).
+ *
+ * One operation lives here today, `measureMeshQuality`: a mesh, the art one
+ * attachment draws, and the bounds the caller declared, measured into one
+ * `mesh-quality-report/1` document (`writeMeshQualityReport` writes its text).
+ * Every type the contract declares is declared here too, including the ones
+ * only the reduction (`reduceMesh`, stage B2) and the motion comparison
+ * (stage C) will fill, so that those stages build on one set of types rather
+ * than restating them.
+ *
+ * ## What it is for
+ *
+ * An agent that cannot see a mesh cannot tell a mesh that drops art from one
+ * that does not, a spanned hole from overshoot, or a sliver from a fold. Each of
+ * those is a row here with its value, where the worst value was taken, the bound
+ * the caller declared, and a state that keeps "measured and failed" apart from
+ * "nothing was declared" and from "could not be measured". The five states are
+ * §2's; nothing folds one into another, and an informational row never counts
+ * towards a pass.
+ *
+ * ## What it never does
+ *
+ * - **Invent a bound.** A row whose bound the caller did not declare is
+ *   `undeclared`: measured, reported, and out of the pass count. The two rows
+ *   with a bound of their own — `MQ_ORIENTATION` and `MQ_DEGENERATE`, both 0 —
+ *   take it from the input's own definition (`SourceMesh.triangles` is
+ *   counter-clockwise in Spine world, and a triangle whose sign the A39 band
+ *   cannot read cannot be shown to be), not from a guess.
+ * - **Exchange thresholds.** Every raster row records the threshold it was
+ *   taken at (`MeasureRow.art.threshold`); a measurement claims nothing at any
+ *   other.
+ * - **Change the legacy fit.** `measureAuthoredMeshFit` (`src/mesh.ts`) keeps
+ *   its 4-connected fill for every existing caller. The rows here fill with the
+ *   tracer's 8-connected background flood over all art (P12), and where the two
+ *   fills differ — a diagonal pinch — both labelled results are rows.
+ * - **Pose, or link the runtime.** Pure: no clock, no randomness, no network,
+ *   no spine-core, nothing from the compiler.
+ *
+ * ## Coordinates
+ *
+ * Every caller distance is in the drawing's part-local pixels, y down (P3). The
+ * mask is read on its own grid — the plate's pixels, or a `scale:` page's
+ * texels — so a point is carried to the grid as `px × pageScale`, and a raster
+ * distance comes back as `texels / pageScale`. A pixel named in a `worst` is a
+ * cell of the mask's grid, `[x, y]`, y down. Orientation is read in Spine world,
+ * through `cropToSpineY` (`src/transform.ts`), the one place that conversion
+ * lives.
+ *
+ * ⚠️ `src/mesh.ts` re-exports this module and this module imports helpers from
+ * it, which is an import cycle. It is safe only because nothing at the top
+ * level of either reads the other's bindings: every use is inside a function.
+ * `MeshReductionError` is defined in `src/mesh.ts` for exactly that reason.
+ */
+import {
+  artOf,
+  checkHullOrder,
+  distanceToSegment,
+  fillEnclosed,
+  findSelfIntersection,
+  labelIslands,
+  MeshError,
+  MeshReductionError,
+  meshEdges,
+  prunePolygon,
+  r6,
+  rasteriseTriangles,
+  segmentsMeet,
+  squaredDistanceToSet,
+  traceAlphaOutline,
+  traceOutline,
+  type AlphaMask,
+  type MeshOutline,
+} from './mesh.ts';
+import { areaBand, triangleAreas } from './areaband.ts';
+import { cropToSpineY } from './transform.ts';
+
+// ---------------------------------------------------------------------------
+// §1 — inputs
+// ---------------------------------------------------------------------------
+
+/** The art one attachment is measured against. Correction 1: one per attachment, never shared. */
+export interface ArtInput {
+  /** The art, on the grid it is read off: the plate's pixels, or a `scale:` page's texels. */
+  mask: AlphaMask;
+  /** Art is `alpha >= threshold`. Required, a whole number in 1..255. Never exchanged. */
+  threshold: number;
+  /** The frame the caller's distances are in — P3. Echoed in the report, never inferred. */
+  frame: SourceFrame;
+}
+
+/** P3: the caller authors in drawing pixels, part-local, y down. */
+export interface SourceFrame {
+  space: 'part-local-drawing-px-y-down';
+  /** The part window in drawing pixels. */
+  width: number;
+  height: number;
+  /** The `scale:` the page states (1 when none) — the meaning of `ContourSpecInput.pageScale`. */
+  pageScale: number;
+  /** The conversion applied, stated rather than implied: texels = drawing px × pageScale. */
+  conversion: 'texels = px * pageScale';
+}
+
+export interface AttachmentRef {
+  skin: string | null;
+  slot: string;
+  attachment: string;
+}
+
+export interface SourceMesh {
+  /** Part-local pixels of the drawing, y down. */
+  points: Array<[number, number]>;
+  /** Region UVs, 0..1, `v` from the top — one pair per point. */
+  uvs: number[];
+  /** Counter-clockwise in Spine world; hull first, as `checkHullOrder` requires. */
+  triangles: number[];
+  hull: number;
+  /** Per vertex, by bone NAME (`ModelBinding` without the bind coordinates), or null for an unweighted mesh. */
+  weights: Array<Array<{ bone: string; weight: number }>> | null;
+}
+
+/** All distances in the drawing's pixels; converted to texels by `pageScale`. */
+export interface ArtFitBounds {
+  /** Share of art pixel centres the triangles cover, 0..1. */
+  minCoverage: number;
+  /** Furthest a covered pixel may sit outside the filled silhouette, px. */
+  maxOvershoot: number;
+  /** Furthest an uncovered art pixel may sit from the covered set, px. */
+  maxUndercut: number;
+}
+
+/** What a reduction's RESULT must satisfy (correction 3). Read by `reduceMesh`, stage B2. */
+export interface ReductionTargets {
+  artFit: ArtFitBounds;
+  /** P13: largest Hausdorff distance between the reduced and the source hull polygons, px. */
+  maxBoundaryDeviation: number;
+  /** Optional: smallest interior angle any triangle may have, degrees. Undeclared = reported, not gated. */
+  minAngle?: number;
+  /** Local density requirements — §5. */
+  regions: RefinementRegion[];
+}
+
+/** P16/P17: a local density requirement over a closed polygon. */
+export interface RefinementRegion {
+  /** Caller's name, echoed in the report; rigc reads nothing into it. */
+  name: string;
+  /** Closed polygon, part-local drawing pixels, y down — resolved by the caller (P17). */
+  polygon: Array<[number, number]>;
+  /** L0: every edge that intersects the closed polygon is at most this long, px. */
+  maxEdgeLength: number;
+  /** Width of the band outside the polygon over which the bound relaxes, px. Finite, >= 0; 0 is a hard edge. */
+  transition: number;
+  /** In the band, L(d) = L0 + grade × d, d the distance from the polygon, px per px. Finite, >= 0. */
+  grade: number;
+  /** P17: when the caller approximated another shape by this polygon, how — echoed, never read. */
+  approximation: { from: string; policy: string; maxError: number } | null;
+}
+
+/** §6, with P19/P20 folded in. Echoed by `measureMeshQuality`; read by `reduceMesh`, stage B2. */
+export interface ProtectedFeatures {
+  /** P20: keep every source hull vertex. Required — no default inside the operation. */
+  hull: boolean;
+  /** Source vertex indices that must survive. */
+  vertices: number[];
+  /** P20: source edges (pairs of source indices) that must survive as edges. */
+  edges: Array<[number, number]>;
+  /** Region polygons whose boundary vertices must survive. */
+  regionBoundaries: string[];
+  /** L1 weight-vector difference above which an edge is protected (correction 3). Null = no such protection, reported. */
+  weightJump: number | null;
+  /** Bones whose binding may not be pruned from any vertex that carries it (P19). */
+  influences: string[];
+}
+
+/** P19: stated on every weighted call, never inherited. */
+export interface InfluenceLimits {
+  /** The cap on bindings per vertex. */
+  maxInfluences: number;
+  /** Shares under this are dropped; 0 drops only shares that are zero on the weight grid. */
+  minWeight: number;
+}
+
+/** Everything a reduction reads (stage B2). No field has a default inside the operation. */
+export interface MeshReductionInput {
+  attachment: AttachmentRef;
+  art: ArtInput;
+  /** P8: the unreduced, independently gated source. */
+  source: SourceMesh;
+  /** Correction 3: what the SOURCE must already satisfy to be admissible. */
+  sourceBounds: ArtFitBounds;
+  /** Correction 3: what the RESULT must satisfy. */
+  targets: ReductionTargets;
+  protect: ProtectedFeatures;
+  /** Required when `source.weights` is non-null — §6, P19. */
+  influences: InfluenceLimits | null;
+  /** Correction 1: the skeleton's bone order, used for every weight tie-break. Required when weighted. */
+  boneOrder: string[] | null;
+  /** P5: the preset the caller expanded, if any, echoed and never read. */
+  preset: { name: string; version: string } | null;
+  /** Work bound — *Termination reasons*. */
+  budget: { maxCandidates: number };
+}
+
+/**
+ * What a measurement is held to. `ReductionTargets` with every bound allowed to
+ * be undeclared: a measurement is also asked of meshes nobody has set a target
+ * for, and a null bound is a row reported `undeclared`, never one given a value.
+ */
+export interface MeasureTargets {
+  artFit: ArtFitBounds | null;
+  maxBoundaryDeviation: number | null;
+  minAngle?: number;
+  regions: RefinementRegion[];
+}
+
+/**
+ * What `measureMeshQuality` reads: the part of `MeshReductionInput` a
+ * measurement needs, plus the three things only a measurement is handed — the
+ * caller's id for the mesh, the hull polygon `MQ_BOUNDARY_DEVIATION` is taken
+ * against, and the art sample floors (P9). Every field is required; a field the
+ * caller has nothing for is `null` (or an empty list), never left out.
+ */
+export interface MeshMeasureInput {
+  /** The caller's id for the mesh measured, echoed as the candidate's id. */
+  id: string;
+  attachment: AttachmentRef;
+  art: ArtInput;
+  /** The mesh measured. */
+  source: SourceMesh;
+  targets: MeasureTargets;
+  /** The hull polygon to measure boundary deviation against, drawing px; null makes that row `not-measurable`. */
+  referenceHull: Array<[number, number]> | null;
+  /** P9: the fewest art samples the attachment's raster rows are taken over. A whole number >= 1. */
+  minArtSamples: number;
+  /** P9: one floor per region, by region name — every region named once. */
+  regionArtSamples: Array<{ region: string; minArtSamples: number }>;
+  protect: ProtectedFeatures | null;
+  influences: InfluenceLimits | null;
+  boneOrder: string[] | null;
+  preset: { name: string; version: string } | null;
+}
+
+// ---------------------------------------------------------------------------
+// §2 — the report
+// ---------------------------------------------------------------------------
+
+export const MESH_QUALITY_REPORT_SPEC = 'mesh-quality-report/1';
+
+export type MeasureState = 'pass' | 'fail' | 'undeclared' | 'refused' | 'not-measurable';
+
+export interface MeasureRow {
+  /** Stable code, e.g. `MQ_COVERAGE`. */
+  code: string;
+  /** The object measured: attachment always; region when the row is a region's. */
+  object: { attachment: AttachmentRef; region: string | null };
+  state: MeasureState;
+  /** The measured value: present on pass, fail and undeclared; null otherwise. */
+  value: number | null;
+  /** The declared bound, inclusive: present on pass and fail; null on undeclared, refused, not-measurable. */
+  bound: { op: '<=' | '>='; value: number } | null;
+  unit: 'px' | 'world' | 'fraction' | 'degrees' | 'ratio' | 'count';
+  /** Where the worst value was taken: present whenever `value` is. `{ at: {} }` when nothing is worse than ideal. */
+  worst: WorstSample | null;
+  /** Required on refused and not-measurable: a sentence naming what was missing. */
+  reason: string | null;
+  /** Raster and sampled rows: the art the row was taken against — never read across thresholds. */
+  art?: { threshold: number; connectivity: 4 | 8 | null; samples: number };
+  /** Raster rows only — correction 2. */
+  raster?: RasterSensitivity;
+  /** Sampled rows — correction 2. */
+  sampling?: { domain: string; count: number };
+}
+
+/** Correction 2: the spatial grid and the value's own granularity are two fields. */
+export interface RasterSensitivity {
+  grid: { width: number; height: number; pageScale: number };
+  /** One texel, in the drawing's pixels: 1 / pageScale. */
+  spatialQuantum: number;
+  /** The smallest step the VALUE can take, in the row's own unit. */
+  valueIncrement: number;
+  /** A diagnostic: it changes no verdict and bounds no error. */
+  nearBound: 'at-bound' | 'within-increment' | 'clear';
+}
+
+export interface WorstSample {
+  at: { pixel?: [number, number]; triangle?: number; edge?: [number, number]; vertex?: number; uv?: [number, number] };
+  /** Motion rows only — P7, P11. */
+  frame?: FrameRef;
+}
+
+/** P7/P11: a frame named by a stable id carrying animation, phase and time. Stage C. */
+export interface FrameRef {
+  id: string;
+  animation: string | null;
+  phase: 'grid' | 'irr' | null;
+  time: number | null;
+  index: number | null;
+  role: 'selection' | 'held-out' | 'baseline';
+}
+
+export interface EvidenceSection {
+  rows: MeasureRow[];
+  /** Counts per state. `measured` = pass + fail. Never summed across sections. */
+  summary: { pass: number; fail: number; undeclared: number; refused: number; notMeasurable: number; measured: number };
+  /** pass only when every REQUIRED row is pass AND at least one row is pass. */
+  verdict: 'pass' | 'fail' | 'not-measured';
+}
+
+/** §3's motion bounds. Stage C. */
+export interface MotionBounds {
+  maxLocalDeformation: number;
+  maxStretch?: number;
+  minStretch?: number;
+}
+
+/** §3's schedule. Stage C. */
+export interface MotionSchedule {
+  frames: Array<'setup' | { animation: string; times: number[] } | { animation: string; fps: number }>;
+  phases: Array<'grid' | 'irr'>;
+  physics: { mode: 'none' } | { mode: 'step'; dt: number; warmupSteps: 0 };
+  selection: string[];
+}
+
+/**
+ * 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.
+ */
+export type ScheduleUsed = MotionSchedule;
+
+/** One candidate's evidence — correction 1. `reduce` and `measure` carry exactly one. */
+export interface CandidateReport {
+  /** The caller's id for the candidate, or `result` for a `reduce`. */
+  id: string;
+  counts: MeshCounts | null;
+  /** Null when no mesh exists to measure (correction 3). */
+  geometry: EvidenceSection | null;
+  /** Null when no motion was asked for — never an empty PASS (P6). */
+  motion: (EvidenceSection & { schedule: ScheduleUsed }) | null;
+  /** P6 — declared-contract acceptance. */
+  accepted: boolean;
+  /** Opt-in (P7): every row's value at every frame. Absent unless asked for. */
+  perFrame?: Array<{ code: string; frame: string; value: number | null }>;
+}
+
+export interface MeshQualityReport {
+  spec: typeof MESH_QUALITY_REPORT_SPEC;
+  operation: 'reduce' | 'measure' | 'compare';
+  /** Correction 1: the inputs echoed with their structure. */
+  effective: EffectiveSettings;
+  /** P2: which poser ran and its version. Null on geometry-only operations. */
+  poser: { kind: 'core'; rigcVersion: string } | null;
+  /** Whether the caller required motion evidence (P6). */
+  motionRequired: boolean;
+  /** Null when the source could not be read as a mesh (correction 3: counts are never invented). */
+  sourceCounts: MeshCounts | null;
+  reference: CandidateReport | null;
+  candidates: CandidateReport[];
+  termination: Termination | null;
+}
+
+/** Correction 1: every input the text requires, echoed field for field. */
+export interface EffectiveSettings {
+  preset: { name: string; version: string } | null;
+  attachments: Array<{
+    attachment: AttachmentRef;
+    threshold: number;
+    finalThreshold: number;
+    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 }>;
+  }>;
+  sourceBounds: ArtFitBounds | null;
+  referenceArtFit: ArtFitBounds | null;
+  candidateArtFit: ArtFitBounds | null;
+  targets: ReductionTargets | MeasureTargets | null;
+  /** The hull polygon `MQ_BOUNDARY_DEVIATION` was taken against on a `measure`; null when none was given. */
+  referenceHull: Array<[number, number]> | null;
+  motionBounds: MotionBounds | null;
+  protect: ProtectedFeatures | null;
+  influences: InfluenceLimits | null;
+  boneOrder: string[] | null;
+  schedule: MotionSchedule | null;
+  budget: { maxCandidates: number } | null;
+}
+
+export interface MeshCounts {
+  boundaryVertices: number;
+  interiorVertices: number;
+  triangles: number;
+  /** Total `{ bone, weight }` entries over all vertices; 0 on an unweighted mesh. */
+  bindings: number;
+  /** The most entries any one vertex carries; 0 on an unweighted mesh. */
+  maxInfluences: number;
+}
+
+/** *Termination reasons*. Every `reduce` report carries exactly one; a `measure` carries one only when it could not read the mesh. */
+export type Termination =
+  | { reason: 'no-further-valid-reduction'; candidatesTried: number; blockingConstraint: string }
+  | { reason: 'budget-exhausted'; candidatesTried: number; budget: number; result: 'best-meeting-every-bound' | 'none-met-the-targets' }
+  | { reason: 'invalid-input'; code: string; detail: string }
+  | { reason: 'unsupported-topology'; code: string; detail: string };
+
+// ---------------------------------------------------------------------------
+// fixed tolerances
+// ---------------------------------------------------------------------------
+
+/** A22's slack on a region UV (`src/assertions/bodies/a22.ts`): outside 0..1 by more than this is refused. */
+const UV_RANGE_SLACK = 1e-6;
+
+/**
+ * How close the two-sided Hausdorff search brings its lower and upper bounds
+ * before it stops, in drawing px. The value reported is then put on the `r6`
+ * grid, six decimals, so the search is exact to three orders below what is
+ * printed.
+ */
+const HAUSDORFF_TOLERANCE = 1e-9;
+
+/** The predicate epsilon `segmentsMeet` and `prunePolygon` use (`src/mesh.ts`), for "on the boundary". */
+const ON_BOUNDARY = 1e-9;
+
+// ---------------------------------------------------------------------------
+// refusals
+// ---------------------------------------------------------------------------
+
+/** `skin/slot/attachment`, the way every message names the attachment. */
+function nameOf(ref: AttachmentRef): string {
+  return `${ref.skin ?? '(no skin)'}/${ref.slot}/${ref.attachment}`;
+}
+
+function refuse(code: string, message: string): never {
+  throw new MeshReductionError(code, message);
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function isPoint(value: unknown): value is [number, number] {
+  return Array.isArray(value) && value.length === 2 && isFiniteNumber(value[0]) && isFiniteNumber(value[1]);
+}
+
+/** A field that has to be present: `undefined` is a refusal naming it. */
+function present(owner: string, field: string, value: unknown, required: string): void {
+  if (value === undefined) refuse('REDUCE_INPUT_MISSING', `${owner}: ${field} is missing; required ${required} — no field has a default`);
+}
+
+/**
+ * Everything §1 refuses before a pixel is read, by code. The order is the order
+ * a fix has to happen in: the attachment's identity, then the art, then the
+ * mesh, then the bounds.
+ */
+function validateInput(input: MeshMeasureInput): void {
+  if (!isObject(input)) refuse('REDUCE_INPUT_MISSING', `the input is ${JSON.stringify(input)}; required a MeshMeasureInput object`);
+  const ref = input.attachment;
+  if (!isObject(ref) || typeof ref.slot !== 'string' || ref.slot === '' || typeof ref.attachment !== 'string' || ref.attachment === '' || !(ref.skin === null || typeof ref.skin === 'string')) {
+    refuse('REDUCE_INPUT_MISSING', `attachment is ${JSON.stringify(ref)}; required { skin: string | null, slot: string, attachment: string } with a slot and an attachment name`);
+  }
+  const who = `attachment ${nameOf(ref)}`;
+  if (typeof input.id !== 'string' || input.id === '') refuse('REDUCE_INPUT_MISSING', `${who}: id is ${JSON.stringify(input.id)}; required a non-empty string naming the mesh measured`);
+
+  // The art.
+  const art = input.art;
+  present(who, 'art', art, '{ mask, threshold, frame }');
+  if (!isObject(art)) refuse('REDUCE_INPUT_MISSING', `${who}: art is ${JSON.stringify(art)}; required { mask, threshold, frame }`);
+  present(who, 'art.threshold', art.threshold, 'a whole number in 1..255');
+  if (!Number.isInteger(art.threshold) || art.threshold < 1 || art.threshold > 255) {
+    refuse('REDUCE_THRESHOLD_RANGE', `${who}: art.threshold is ${JSON.stringify(art.threshold)}; required a whole number in 1..255 (art is alpha >= threshold)`);
+  }
+  const frame = art.frame;
+  present(who, 'art.frame', frame, '{ space, width, height, pageScale, conversion }');
+  if (!isObject(frame)) refuse('REDUCE_INPUT_MISSING', `${who}: art.frame is ${JSON.stringify(frame)}; required { space, width, height, pageScale, conversion }`);
+  if (frame.space !== 'part-local-drawing-px-y-down') refuse('REDUCE_INPUT_MISSING', `${who}: art.frame.space is ${JSON.stringify(frame.space)}; required "part-local-drawing-px-y-down"`);
+  if (frame.conversion !== 'texels = px * pageScale') refuse('REDUCE_INPUT_MISSING', `${who}: art.frame.conversion is ${JSON.stringify(frame.conversion)}; required "texels = px * pageScale"`);
+  for (const field of ['width', 'height', 'pageScale'] as const) {
+    const v = frame[field];
+    if (!isFiniteNumber(v) || v <= 0) refuse('REDUCE_INPUT_MISSING', `${who}: art.frame.${field} is ${JSON.stringify(v)}; required a finite number above 0`);
+  }
+  const mask = art.mask;
+  present(who, 'art.mask', mask, '{ width, height, alpha }');
+  if (!isObject(mask) || !(mask.alpha instanceof Uint8Array)) refuse('REDUCE_INPUT_MISSING', `${who}: art.mask is not { width, height, alpha: Uint8Array }; required an AlphaMask`);
+  if (!Number.isInteger(mask.width) || !Number.isInteger(mask.height) || mask.width < 1 || mask.height < 1) {
+    refuse('REDUCE_MASK_SIZE', `${who}: the mask is ${mask.width}x${mask.height}; required whole dimensions of at least 1x1`);
+  }
+  if (mask.alpha.length !== mask.width * mask.height) {
+    refuse('REDUCE_MASK_SIZE', `${who}: the mask holds ${mask.alpha.length} bytes for ${mask.width}x${mask.height}; required width × height = ${mask.width * mask.height}`);
+  }
+  // Correction 1: the mask has to be THIS attachment's — its grid is the frame's, by the stated scale.
+  const wantW = r6(frame.width * frame.pageScale);
+  const wantH = r6(frame.height * frame.pageScale);
+  if (mask.width !== wantW || mask.height !== wantH) {
+    refuse(
+      'REDUCE_MASK_SIZE',
+      `${who}: the mask is ${mask.width}x${mask.height} and the frame is ${frame.width}x${frame.height} px at pageScale ${frame.pageScale}; ` +
+        `required a ${wantW}x${wantH} mask (frame × pageScale) — a mask is one attachment's and is never shared with another of a different size`,
+    );
+  }
+
+  // The mesh.
+  const src = input.source;
+  present(who, 'source', src, '{ points, uvs, triangles, hull, weights }');
+  if (!isObject(src) || !Array.isArray(src.points) || !Array.isArray(src.uvs) || !Array.isArray(src.triangles)) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: source is not { points, uvs, triangles, hull, weights } with three arrays`);
+  }
+  src.points.forEach((p, i) => {
+    if (!isPoint(p)) refuse('REDUCE_INPUT_MISSING', `${who}: source.points[${i}] is ${JSON.stringify(p)}; required a pair of finite numbers`);
+  });
+  if (src.uvs.length !== 2 * src.points.length) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: source.uvs holds ${src.uvs.length} numbers for ${src.points.length} points; required one u, v pair per point (${2 * src.points.length})`);
+  }
+  src.uvs.forEach((u, i) => {
+    if (!isFiniteNumber(u) || u < -UV_RANGE_SLACK || u > 1 + UV_RANGE_SLACK) {
+      refuse('REDUCE_UV_RANGE', `${who}: source.uvs[${i}] (vertex ${Math.floor(i / 2)}, ${i % 2 === 0 ? 'u' : 'v'}) is ${u}; required 0..1 within ${UV_RANGE_SLACK} (A22)`);
+    }
+  });
+  if (!Number.isInteger(src.hull)) refuse('REDUCE_INPUT_MISSING', `${who}: source.hull is ${JSON.stringify(src.hull)}; required the whole number of hull vertices`);
+  if (src.weights !== null) {
+    if (!Array.isArray(src.weights) || src.weights.length !== src.points.length) {
+      refuse('REDUCE_INPUT_MISSING', `${who}: source.weights is not one binding list per point (${src.points.length}); required that, or null for an unweighted mesh`);
+    }
+    src.weights.forEach((vertex, i) => {
+      if (!Array.isArray(vertex) || vertex.some((b) => !isObject(b) || typeof b.bone !== 'string' || !isFiniteNumber(b.weight))) {
+        refuse('REDUCE_INPUT_MISSING', `${who}: source.weights[${i}] is not a list of { bone, weight }; required that`);
+      }
+    });
+  }
+
+  // The bounds.
+  const targets = input.targets;
+  present(who, 'targets', targets, '{ artFit, maxBoundaryDeviation, regions }');
+  if (!isObject(targets)) refuse('REDUCE_INPUT_MISSING', `${who}: targets is ${JSON.stringify(targets)}; required { artFit, maxBoundaryDeviation, regions }`);
+  present(who, 'targets.artFit', targets.artFit, 'an ArtFitBounds or null');
+  if (targets.artFit !== null) {
+    const fit = targets.artFit;
+    const coverage = fit.minCoverage;
+    if (!isFiniteNumber(coverage) || coverage < 0 || coverage > 1) refuse('REDUCE_INPUT_MISSING', `${who}: targets.artFit.minCoverage is ${JSON.stringify(coverage)}; required a fraction in 0..1`);
+    for (const field of ['maxOvershoot', 'maxUndercut'] as const) {
+      const v = fit[field];
+      if (!isFiniteNumber(v) || v < 0) refuse('REDUCE_INPUT_MISSING', `${who}: targets.artFit.${field} is ${JSON.stringify(v)}; required a finite number of px, 0 or more`);
+    }
+  }
+  present(who, 'targets.maxBoundaryDeviation', targets.maxBoundaryDeviation, 'a number of px or null');
+  if (targets.maxBoundaryDeviation !== null && (!isFiniteNumber(targets.maxBoundaryDeviation) || targets.maxBoundaryDeviation < 0)) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: targets.maxBoundaryDeviation is ${JSON.stringify(targets.maxBoundaryDeviation)}; required a finite number of px, 0 or more, or null`);
+  }
+  if (targets.minAngle !== undefined && (!isFiniteNumber(targets.minAngle) || targets.minAngle < 0)) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: targets.minAngle is ${JSON.stringify(targets.minAngle)}; required a finite number of degrees, 0 or more, or the field left out`);
+  }
+  present(who, 'targets.regions', targets.regions, 'a list of regions (empty when none)');
+  if (!Array.isArray(targets.regions)) refuse('REDUCE_INPUT_MISSING', `${who}: targets.regions is ${JSON.stringify(targets.regions)}; required a list (empty when none)`);
+  present(who, 'referenceHull', input.referenceHull, 'a polygon or null');
+  if (input.referenceHull !== null) {
+    if (!Array.isArray(input.referenceHull) || input.referenceHull.length < 3 || !input.referenceHull.every(isPoint)) {
+      refuse('REDUCE_INPUT_MISSING', `${who}: referenceHull is not a polygon of at least 3 finite points; required that, or null`);
+    }
+  }
+
+  // P9: the sample floors.
+  present(who, 'minArtSamples', input.minArtSamples, 'a whole number >= 1');
+  if (!Number.isInteger(input.minArtSamples) || input.minArtSamples < 1) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: minArtSamples is ${JSON.stringify(input.minArtSamples)}; required a whole number >= 1 (P9, no hidden constant)`);
+  }
+  present(who, 'regionArtSamples', input.regionArtSamples, 'one { region, minArtSamples } per region');
+  if (!Array.isArray(input.regionArtSamples)) refuse('REDUCE_INPUT_MISSING', `${who}: regionArtSamples is not a list; required one { region, minArtSamples } per region`);
+  const names = new Set<string>();
+  targets.regions.forEach((region, i) => {
+    if (!isObject(region) || typeof region.name !== 'string' || region.name === '') {
+      refuse('REDUCE_INPUT_MISSING', `${who}: targets.regions[${i}] has no name; required a non-empty name, which every row of the region is keyed by`);
+    }
+    if (names.has(region.name)) refuse('REDUCE_INPUT_MISSING', `${who}: region "${region.name}" is named twice; required one name per region, which its rows and its sample floor are keyed by`);
+    names.add(region.name);
+    if (!Array.isArray(region.polygon) || region.polygon.length < 3) {
+      refuse('REDUCE_INPUT_MISSING', `${who}: region "${region.name}" has a polygon of ${Array.isArray(region.polygon) ? region.polygon.length : 'no'} vertices; required at least 3`);
+    }
+    for (const field of ['maxEdgeLength', 'transition', 'grade'] as const) present(`${who}, region "${region.name}"`, field, region[field], 'a finite number');
+    present(`${who}, region "${region.name}"`, 'approximation', region.approximation, 'an approximation or null');
+    const floors = input.regionArtSamples.filter((f) => isObject(f) && f.region === region.name);
+    if (floors.length !== 1 || !Number.isInteger(floors[0].minArtSamples) || floors[0].minArtSamples < 1) {
+      refuse('REDUCE_INPUT_MISSING', `${who}: region "${region.name}" has ${floors.length} sample floor(s) in regionArtSamples; required exactly one, a whole number >= 1 (P9)`);
+    }
+  });
+  input.regionArtSamples.forEach((f, i) => {
+    if (!isObject(f) || !names.has(f.region)) refuse('REDUCE_INPUT_MISSING', `${who}: regionArtSamples[${i}] names ${JSON.stringify(isObject(f) ? f.region : f)}, which no region is; required a floor for a declared region`);
+  });
+
+  // Echoed, never read — but present, since nothing has a default.
+  for (const field of ['protect', 'influences', 'boneOrder', 'preset'] as const) present(who, field, input[field], 'a value or null');
+  if (input.protect !== null) {
+    const p = input.protect;
+    const ok =
+      isObject(p) &&
+      typeof p.hull === 'boolean' &&
+      Array.isArray(p.vertices) &&
+      Array.isArray(p.edges) &&
+      Array.isArray(p.regionBoundaries) &&
+      (p.weightJump === null || isFiniteNumber(p.weightJump)) &&
+      Array.isArray(p.influences);
+    if (!ok) refuse('REDUCE_INPUT_MISSING', `${who}: protect is not a ProtectedFeatures with every field; required { hull, vertices, edges, regionBoundaries, weightJump, influences }, or null`);
+  }
+  if (input.influences !== null && (!isObject(input.influences) || !isFiniteNumber(input.influences.maxInfluences) || !isFiniteNumber(input.influences.minWeight))) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: influences is not { maxInfluences, minWeight }; required that, or null`);
+  }
+  if (input.boneOrder !== null && (!Array.isArray(input.boneOrder) || input.boneOrder.some((b) => typeof b !== 'string'))) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: boneOrder is not a list of bone names; required that, or null`);
+  }
+  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`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// plane geometry
+// ---------------------------------------------------------------------------
+
+type Pt = readonly [number, number];
+
+/** Is `p` inside or on the closed polygon? On the boundary within `ON_BOUNDARY` counts as inside. */
+function inClosedPolygon(p: Pt, poly: readonly Pt[]): boolean {
+  const n = poly.length;
+  for (let i = 0; i < n; i++) if (distanceToSegment(p, poly[i], poly[(i + 1) % n]) <= ON_BOUNDARY) return true;
+  let inside = false;
+  for (let i = 0, j = n - 1; i < n; j = i++) {
+    const [xi, yi] = poly[i];
+    const [xj, yj] = poly[j];
+    if (yi > p[1] !== yj > p[1] && p[0] < ((xj - xi) * (p[1] - yi)) / (yj - yi) + xi) inside = !inside;
+  }
+  return inside;
+}
+
+/** Does the segment `a`–`b` meet the closed polygon — an endpoint inside or on it, or any crossing or touch? */
+function segmentMeetsPolygon(a: Pt, b: Pt, poly: readonly Pt[]): boolean {
+  if (inClosedPolygon(a, poly) || inClosedPolygon(b, poly)) return true;
+  const n = poly.length;
+  for (let i = 0; i < n; i++) if (segmentsMeet(a, b, poly[i], poly[(i + 1) % n])) return true;
+  return false;
+}
+
+/** Distance between two segments that do not meet: the nearest of the four endpoint-to-segment distances. */
+function segmentDistance(a: Pt, b: Pt, c: Pt, d: Pt): number {
+  if (segmentsMeet(a, b, c, d)) return 0;
+  return Math.min(distanceToSegment(a, c, d), distanceToSegment(b, c, d), distanceToSegment(c, a, b), distanceToSegment(d, a, b));
+}
+
+/** Distance from a segment to a closed polygon's region: 0 when they meet, else to its nearest edge. */
+function segmentToPolygon(a: Pt, b: Pt, poly: readonly Pt[]): number {
+  if (segmentMeetsPolygon(a, b, poly)) return 0;
+  let best = Infinity;
+  const n = poly.length;
+  for (let i = 0; i < n; i++) best = Math.min(best, segmentDistance(a, b, poly[i], poly[(i + 1) % n]));
+  return best;
+}
+
+/** 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;
+  let edge = 0;
+  const n = poly.length;
+  for (let i = 0; i < n; i++) {
+    const v = distanceToSegment(p, poly[i], poly[(i + 1) % n]);
+    if (v < d) {
+      d = v;
+      edge = i;
+    }
+  }
+  return { d, edge };
+}
+
+/**
+ * The directed Hausdorff distance from the boundary of `a` to the boundary of
+ * `b` — the furthest any point of `a`'s outline sits from `b`'s — and where.
+ *
+ * Exact up to `HAUSDORFF_TOLERANCE`, by branch and bound along each edge of
+ * `a`. The distance to one edge of `b` is convex along a segment, so on any
+ * piece of an edge of `a` it is at most the larger of its two end values; the
+ * distance to the whole of `b` is the minimum over `b`'s edges, so the smallest
+ * of those maxima bounds it from above. A piece whose bound cannot beat the best
+ * value already found is dropped; the rest are halved. No sampling density is
+ * chosen, so nothing here can miss a maximum between two samples.
+ */
+function directedHausdorff(a: readonly Pt[], b: readonly Pt[]): { d: number; edge: number; at: Pt } {
+  const m = b.length;
+  const toEach = (p: Pt): Float64Array => {
+    const out = new Float64Array(m);
+    for (let j = 0; j < m; j++) out[j] = distanceToSegment(p, b[j], b[(j + 1) % m]);
+    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;
+  };
+  let best = -1;
+  let bestEdge = 0;
+  let bestAt: Pt = a[0];
+  const n = a.length;
+  for (let i = 0; i < n; i++) {
+    const p0 = a[i];
+    const p1 = a[(i + 1) % n];
+    const at = (t: number): Pt => [p0[0] + (p1[0] - p0[0]) * t, p0[1] + (p1[1] - p0[1]) * t];
+    const consider = (f: number, t: number): void => {
+      if (f > best) {
+        best = f;
+        bestEdge = i;
+        bestAt = at(t);
+      }
+    };
+    const g0 = toEach(p0);
+    const g1 = toEach(p1);
+    consider(minOf(g0), 0);
+    consider(minOf(g1), 1);
+    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 <= best + HAUSDORFF_TOLERANCE || piece.depth >= 64) continue;
+      const tm = (piece.t0 + piece.t1) / 2;
+      const gm = toEach(at(tm));
+      consider(minOf(gm), tm);
+      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 { d: Math.max(best, 0), edge: bestEdge, at: bestAt };
+}
+
+/**
+ * The symmetric Hausdorff distance between two closed polygons' boundaries,
+ * with the candidate hull edge the worst value belongs to: the edge it was
+ * taken on when the worst point is the candidate's, else the candidate edge
+ * nearest the reference's worst point.
+ */
+function hausdorff(candidate: readonly Pt[], reference: readonly Pt[]): { d: number; candidateEdge: number } {
+  const forward = directedHausdorff(candidate, reference);
+  const backward = directedHausdorff(reference, candidate);
+  if (forward.d >= backward.d) return { d: forward.d, candidateEdge: forward.edge };
+  return { d: backward.d, candidateEdge: pointToBoundary(backward.at, candidate).edge };
+}
+
+// ---------------------------------------------------------------------------
+// rows
+// ---------------------------------------------------------------------------
+
+/** A row as it is being built: the report's row, and whether the caller's declared contract requires it (P6). */
+interface Built {
+  row: MeasureRow;
+  required: boolean;
+}
+
+function nearBoundOf(value: number | null, bound: MeasureRow['bound'], increment: number): RasterSensitivity['nearBound'] {
+  if (value === null || bound === null) return 'clear';
+  const gap = Math.abs(value - bound.value);
+  if (gap === 0) return 'at-bound';
+  return gap <= increment ? 'within-increment' : 'clear';
+}
+
+/** Pass or fail against an inclusive bound — equality passes. */
+function judged(value: number, bound: { op: '<=' | '>='; value: number }): 'pass' | 'fail' {
+  return (bound.op === '<=' ? value <= bound.value : value >= bound.value) ? 'pass' : 'fail';
+}
+
+const NOTHING_WORSE: WorstSample = { at: {} };
+
+interface RowSpec {
+  code: string;
+  region: string | null;
+  unit: MeasureRow['unit'];
+  attachment: AttachmentRef;
+}
+
+function measuredRow(spec: RowSpec, value: number, bound: MeasureRow['bound'], worst: WorstSample, required: boolean): Built {
+  return {
+    row: {
+      code: spec.code,
+      object: { attachment: spec.attachment, region: spec.region },
+      state: bound === null ? 'undeclared' : judged(value, bound),
+      value,
+      bound,
+      unit: spec.unit,
+      worst,
+      reason: null,
+    },
+    required: required && bound !== null,
+  };
+}
+
+function unmeasuredRow(spec: RowSpec, state: 'refused' | 'not-measurable', reason: string, required: boolean): Built {
+  return {
+    row: { code: spec.code, object: { attachment: spec.attachment, region: spec.region }, state, value: null, bound: null, unit: spec.unit, worst: null, reason },
+    required,
+  };
+}
+
+/** The raster fields of a row: its art, and the grid and increment its value is quantised on (correction 2). */
+function withRaster(built: Built, art: NonNullable<MeasureRow['art']>, grid: RasterSensitivity['grid'], increment: number): Built {
+  const row = built.row;
+  row.art = art;
+  row.raster = {
+    grid,
+    spatialQuantum: 1 / grid.pageScale,
+    valueIncrement: increment,
+    nearBound: nearBoundOf(row.value, row.bound, increment),
+  };
+  return built;
+}
+
+/** Row order (§2): code, then region (the attachment's own row first), then the gated fill before the labelled legacy one. */
+function compareRows(a: MeasureRow, b: MeasureRow): number {
+  if (a.code !== b.code) return a.code < b.code ? -1 : 1;
+  const ra = a.object.region;
+  const rb = b.object.region;
+  if (ra !== rb) {
+    if (ra === null) return -1;
+    if (rb === null) return 1;
+    return ra < rb ? -1 : 1;
+  }
+  const ca = a.art?.connectivity ?? 0;
+  const cb = b.art?.connectivity ?? 0;
+  return cb - ca;
+}
+
+// ---------------------------------------------------------------------------
+// the operation
+// ---------------------------------------------------------------------------
+
+/**
+ * Measure one mesh against the art its attachment draws and the bounds the
+ * caller declared — §4's geometry rows, no motion. Throws a
+ * `MeshReductionError` for an input §1 refuses; reports a source whose
+ * triangles are not one closed loop rather than throwing, with `sourceCounts`
+ * null and an `unsupported-topology` termination saying why (correction 3: a
+ * count is never invented).
+ */
+export function measureMeshQuality(input: MeshMeasureInput): MeshQualityReport {
+  validateInput(input);
+  const { attachment, art, source, targets } = input;
+  const { mask, threshold, frame } = art;
+  const scale = frame.pageScale;
+  const effective = effectiveOf(input);
+  const report = (sourceCounts: MeshCounts | null, candidate: CandidateReport, termination: Termination | null): MeshQualityReport => ({
+    spec: MESH_QUALITY_REPORT_SPEC,
+    operation: 'measure',
+    effective,
+    poser: null,
+    motionRequired: false,
+    sourceCounts,
+    reference: null,
+    candidates: [candidate],
+    termination,
+  });
+
+  // The outline the triangles state — or the reason there is none.
+  const n = source.points.length;
+  let outline: MeshOutline;
+  try {
+    outline = traceOutline(n, source.triangles);
+    if (outline.hull !== source.hull) {
+      throw new MeshError(`source.hull says ${source.hull} and the triangles' outline has ${outline.hull} vertices`);
+    }
+    checkHullOrder(outline, n);
+  } catch (err) {
+    if (!(err instanceof MeshError)) throw err;
+    const detail = `attachment ${nameOf(attachment)}: ${err.message}; required one closed outline listed first, in order (traceOutline, checkHullOrder)`;
+    return report(null, { id: input.id, counts: null, geometry: null, motion: null, accepted: false }, { reason: 'unsupported-topology', code: 'REDUCE_SOURCE_NOT_ONE_LOOP', detail });
+  }
+
+  const counts = countsOf(source, outline);
+  const rows: Built[] = [];
+  const spec = (code: string, unit: MeasureRow['unit'], region: string | null = null): RowSpec => ({ code, unit, region, attachment });
+  const points: Pt[] = source.points;
+  const hullPolygon: Pt[] = outline.walk.map((v) => points[v]);
+
+  // --- raster rows ---------------------------------------------------------
+  const w = mask.width;
+  const h = mask.height;
+  const grid = { width: w, height: h, pageScale: scale };
+  const artBits = artOf(mask, threshold);
+  let artCount = 0;
+  for (const bit of artBits) artCount += bit;
+  const onGrid: Array<[number, number]> = source.points.map(([x, y]) => [x * scale, y * scale]);
+  const covered = rasteriseTriangles(onGrid, source.triangles, w, h);
+  const fit = targets.artFit;
+  const pxIncrement = 1 / scale;
+  const rasterArt = (connectivity: 4 | 8 | null): NonNullable<MeasureRow['art']> => ({ threshold, connectivity, samples: artCount });
+  const pixelOf = (i: number): [number, number] => [i % w, Math.floor(i / w)];
+  if (artCount < input.minArtSamples) {
+    const why = `attachment ${nameOf(attachment)} has ${artCount} art sample(s) at alpha >= ${threshold}; required at least ${input.minArtSamples} (minArtSamples, P9) — a row over fewer is not a measurement`;
+    rows.push(withRaster(unmeasuredRow(spec('MQ_COVERAGE', 'fraction'), 'not-measurable', why, fit !== null), rasterArt(null), grid, artCount === 0 ? 1 : 1 / artCount));
+    rows.push(withRaster(unmeasuredRow(spec('MQ_OVERSHOOT', 'px'), 'not-measurable', why, fit !== null), rasterArt(8), grid, pxIncrement));
+    rows.push(withRaster(unmeasuredRow(spec('MQ_UNDERCUT', 'px'), 'not-measurable', why, fit !== null), rasterArt(null), grid, pxIncrement));
+    rows.push(withRaster(unmeasuredRow(spec('MQ_HOLES', 'count'), 'not-measurable', why, false), rasterArt(8), grid, 1));
+    rows.push(withRaster(unmeasuredRow(spec('MQ_ISLANDS', 'count'), 'not-measurable', why, false), rasterArt(4), grid, 1));
+  } else {
+    // Coverage — `measureAuthoredMeshFit`'s, unchanged: art pixel centres a triangle covers.
+    let coveredArt = 0;
+    for (let i = 0; i < artBits.length; i++) if (artBits[i] && covered[i]) coveredArt++;
+    const toCovered = squaredDistanceToSet(covered, w, h);
+    const anyCovered = covered.some((c) => c === 1);
+    // Undercut: the furthest uncovered art pixel from the covered set. Its pixel is coverage's worst too.
+    let undercutAt = -1;
+    let undercutSq = 0;
+    for (let i = 0; i < artBits.length; i++) {
+      if (!artBits[i] || covered[i]) continue;
+      if (undercutAt === -1 || toCovered[i] > undercutSq) {
+        undercutAt = i;
+        undercutSq = toCovered[i];
+      }
+    }
+    const missingWorst: WorstSample = undercutAt === -1 ? NOTHING_WORSE : { at: { pixel: pixelOf(undercutAt) } };
+    rows.push(
+      withRaster(
+        measuredRow(spec('MQ_COVERAGE', 'fraction'), coveredArt / artCount, fit === null ? null : { op: '>=', value: fit.minCoverage }, missingWorst, true),
+        rasterArt(null),
+        grid,
+        1 / artCount,
+      ),
+    );
+    const undercutSpec = spec('MQ_UNDERCUT', 'px');
+    rows.push(
+      withRaster(
+        !anyCovered
+          ? unmeasuredRow(undercutSpec, 'not-measurable', `attachment ${nameOf(attachment)}: the triangles cover no pixel centre of the ${w}x${h} grid, so no art pixel has a distance to a covered one`, fit !== null)
+          : measuredRow(undercutSpec, r6(Math.sqrt(undercutSq) / scale), fit === null ? null : { op: '<=', value: fit.maxUndercut }, missingWorst, true),
+        rasterArt(null),
+        grid,
+        pxIncrement,
+      ),
+    );
+
+    // Overshoot and holes against the filled silhouette: 8-connected background over ALL art (P12) — and,
+    // where the legacy 4-connected fill differs (a diagonal pinch), the labelled 4-connected reading beside it.
+    const fill8 = fillEnclosed(artBits, w, h, 8).filled;
+    const fill4 = fillEnclosed(artBits, w, h, 4).filled;
+    let fillsDiffer = false;
+    for (let i = 0; i < fill8.length; i++) {
+      if (fill8[i] !== fill4[i]) {
+        fillsDiffer = true;
+        break;
+      }
+    }
+    const silhouetteRows = (filled: Uint8Array, connectivity: 4 | 8, gated: boolean): void => {
+      const toFilled = squaredDistanceToSet(filled, w, h);
+      let overAt = -1;
+      let overSq = 0;
+      let holes = 0;
+      let holeAt = -1;
+      for (let i = 0; i < covered.length; i++) {
+        if (!covered[i]) continue;
+        if (!filled[i]) {
+          if (overAt === -1 || toFilled[i] > overSq) {
+            overAt = i;
+            overSq = toFilled[i];
+          }
+        } else if (!artBits[i]) {
+          holes++;
+          if (holeAt === -1) holeAt = i;
+        }
+      }
+      const bound = gated && fit !== null ? { op: '<=' as const, value: fit.maxOvershoot } : null;
+      rows.push(
+        withRaster(
+          measuredRow(spec('MQ_OVERSHOOT', 'px'), r6(Math.sqrt(overSq) / scale), bound, overAt === -1 ? NOTHING_WORSE : { at: { pixel: pixelOf(overAt) } }, gated),
+          rasterArt(connectivity),
+          grid,
+          pxIncrement,
+        ),
+      );
+      rows.push(withRaster(measuredRow(spec('MQ_HOLES', 'count'), holes, null, holeAt === -1 ? NOTHING_WORSE : { at: { pixel: pixelOf(holeAt) } }, false), rasterArt(connectivity), grid, 1));
+    };
+    silhouetteRows(fill8, 8, true);
+    if (fillsDiffer) silhouetteRows(fill4, 4, false);
+
+    // Islands: the 4-connected art islands (the tracer's, `labelIslands`) the triangles cover a pixel of.
+    const { label } = labelIslands(artBits, w, h);
+    const touched = new Set<number>();
+    for (let i = 0; i < label.length; i++) if (label[i] && covered[i]) touched.add(label[i]);
+    let joinedAt = -1;
+    if (touched.size >= 2) {
+      const second = [...touched].sort((p, q) => p - q)[1];
+      joinedAt = label.indexOf(second);
+    }
+    rows.push(
+      withRaster(
+        measuredRow(spec('MQ_ISLANDS', 'count'), touched.size, null, joinedAt === -1 ? NOTHING_WORSE : { at: { pixel: pixelOf(joinedAt) } }, false),
+        { threshold, connectivity: 4, samples: artCount },
+        grid,
+        1,
+      ),
+    );
+  }
+
+  // --- the outline against a reference, and against the traced art -------------------------
+  const boundarySpec = spec('MQ_BOUNDARY_DEVIATION', 'px');
+  const edgeOfHull = (i: number): [number, number] => [outline.walk[i], outline.walk[(i + 1) % outline.walk.length]];
+  if (input.referenceHull === null) {
+    rows.push(unmeasuredRow(boundarySpec, 'not-measurable', `attachment ${nameOf(attachment)}: no referenceHull was given, so there is no polygon to measure the hull's deviation from`, targets.maxBoundaryDeviation !== null));
+  } else {
+    const hd = hausdorff(hullPolygon, input.referenceHull);
+    const bound = targets.maxBoundaryDeviation === null ? null : { op: '<=' as const, value: targets.maxBoundaryDeviation };
+    rows.push(measuredRow(boundarySpec, r6(hd.d), bound, hd.d === 0 ? NOTHING_WORSE : { at: { edge: edgeOfHull(hd.candidateEdge) } }, true));
+  }
+  const traceSpec = spec('MQ_TRACE_DEVIATION', 'px');
+  try {
+    const traced = traceAlphaOutline(mask, threshold);
+    const outlinePx = prunePolygon(traced.outline.map(([x, y]): [number, number] => [x / scale, y / scale]));
+    const hd = hausdorff(hullPolygon, outlinePx);
+    rows.push(measuredRow(traceSpec, r6(hd.d), null, hd.d === 0 ? NOTHING_WORSE : { at: { edge: edgeOfHull(hd.candidateEdge) } }, false));
+  } catch (err) {
+    if (!(err instanceof MeshError)) throw err;
+    rows.push(unmeasuredRow(traceSpec, 'not-measurable', `attachment ${nameOf(attachment)}: the tracer refused the art at alpha >= ${threshold}: ${err.message}`, false));
+  }
+
+  // --- triangles: sign, degeneracy, angle --------------------------------------------------
+  const world: number[] = [];
+  for (const [x, y] of points) world.push(x, cropToSpineY(y, frame.height));
+  const areas = triangleAreas(world, source.triangles);
+  const band = areaBand(areas, world);
+  let flipped = 0;
+  let flippedWorst = -1;
+  let degenerate = 0;
+  let degenerateWorst = -1;
+  areas.forEach((a, t) => {
+    if (Math.abs(a) <= band) {
+      degenerate++;
+      if (degenerateWorst === -1 || Math.abs(a) < Math.abs(areas[degenerateWorst])) degenerateWorst = t;
+    } else if (a < 0) {
+      flipped++;
+      if (flippedWorst === -1 || a < areas[flippedWorst]) flippedWorst = t;
+    }
+  });
+  rows.push(measuredRow(spec('MQ_ORIENTATION', 'count'), flipped, { op: '<=', value: 0 }, flippedWorst === -1 ? NOTHING_WORSE : { at: { triangle: flippedWorst } }, true));
+  rows.push(measuredRow(spec('MQ_DEGENERATE', 'count'), degenerate, { op: '<=', value: 0 }, degenerateWorst === -1 ? NOTHING_WORSE : { at: { triangle: degenerateWorst } }, true));
+  let smallest = Infinity;
+  let smallestAt = 0;
+  for (let t = 0; t * 3 + 2 < source.triangles.length; t++) {
+    const corner = [points[source.triangles[t * 3]], points[source.triangles[t * 3 + 1]], points[source.triangles[t * 3 + 2]]];
+    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];
+      const angle = (Math.atan2(Math.abs(ux * vy - uy * vx), ux * vx + uy * vy) * 180) / Math.PI;
+      if (angle < smallest) {
+        smallest = angle;
+        smallestAt = t;
+      }
+    }
+  }
+  rows.push(
+    measuredRow(spec('MQ_MIN_ANGLE', 'degrees'), r6(smallest), targets.minAngle === undefined ? null : { op: '>=', value: targets.minAngle }, { at: { triangle: smallestAt } }, true),
+  );
+
+  // --- regions (§5) ------------------------------------------------------------------------
+  rows.push(...regionRows(input, outline, hullPolygon));
+
+  const ordered = rows.slice().sort((a, b) => compareRows(a.row, b.row));
+  const geometry = sectionOf(ordered);
+  const accepted = geometry.verdict === 'pass';
+  return report(counts, { id: input.id, counts, geometry, motion: null, accepted }, null);
+}
+
+/** 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);
+  const maxInfluences = source.weights === null ? 0 : source.weights.reduce((m, v) => Math.max(m, v.length), 0);
+  return {
+    boundaryVertices: outline.hull,
+    interiorVertices: source.points.length - outline.hull,
+    triangles: source.triangles.length / 3,
+    bindings,
+    maxInfluences,
+  };
+}
+
+/**
+ * The section's figures and verdict (§2, P6): `measured` is pass + fail; the
+ * verdict is `fail` when a required row failed, `pass` only when every required
+ * row passed and at least one row did, and `not-measured` otherwise — which is
+ * what a required row that could not be measured, or was refused, leaves.
+ */
+function sectionOf(built: readonly Built[]): EvidenceSection {
+  const summary = { pass: 0, fail: 0, undeclared: 0, refused: 0, notMeasurable: 0, measured: 0 };
+  for (const { row } of built) {
+    if (row.state === 'pass') summary.pass++;
+    else if (row.state === 'fail') summary.fail++;
+    else if (row.state === 'undeclared') summary.undeclared++;
+    else if (row.state === 'refused') summary.refused++;
+    else summary.notMeasurable++;
+  }
+  summary.measured = summary.pass + summary.fail;
+  const required = built.filter((b) => b.required);
+  let verdict: EvidenceSection['verdict'];
+  if (required.some((b) => b.row.state === 'fail')) verdict = 'fail';
+  else if (required.every((b) => b.row.state === 'pass') && summary.pass > 0) verdict = 'pass';
+  else verdict = 'not-measured';
+  return { rows: built.map((b) => b.row), summary, verdict };
+}
+
+// ---------------------------------------------------------------------------
+// §5 — regions
+// ---------------------------------------------------------------------------
+
+/** A region's own refusal (§2's `refused`: this measurement's input is invalid), or null when it is measurable. */
+function regionRefusal(region: RefinementRegion, pageScale: number, who: string): { code: string; message: string } | null {
+  const numbers: Array<[string, unknown]> = [
+    ['maxEdgeLength', region.maxEdgeLength],
+    ['transition', region.transition],
+    ['grade', region.grade],
+    ...region.polygon.flatMap((p, i): Array<[string, unknown]> => (Array.isArray(p) ? [[`polygon[${i}][0]`, p[0]], [`polygon[${i}][1]`, p[1]]] : [[`polygon[${i}]`, p]])),
+  ];
+  for (const [field, value] of numbers) {
+    if (!isFiniteNumber(value)) return { code: 'REGION_NOT_FINITE', message: `${who}, region "${region.name}": ${field} is ${String(value)}; required a finite number` };
+  }
+  if (region.transition < 0) return { code: 'REGION_TRANSITION_NEGATIVE', message: `${who}, region "${region.name}": transition is ${region.transition} px; required 0 or more (0 is a hard edge)` };
+  if (region.grade < 0) return { code: 'REGION_GRADE_NEGATIVE', message: `${who}, region "${region.name}": grade is ${region.grade} px per px; required 0 or more` };
+  if (region.maxEdgeLength < 1 / pageScale) {
+    return {
+      code: 'REGION_BOUND_BELOW_GRID',
+      message: `${who}, region "${region.name}": maxEdgeLength is ${region.maxEdgeLength} px; required at least one texel, ${r6(1 / pageScale)} px at pageScale ${pageScale}`,
+    };
+  }
+  const crossing = findSelfIntersection(region.polygon);
+  if (crossing !== null) {
+    return {
+      code: 'REGION_SELF_INTERSECTS',
+      message: `${who}, region "${region.name}": polygon edges ${crossing[0]} and ${crossing[1]} meet; required a strictly simple polygon (findSelfIntersection)`,
+    };
+  }
+  return null;
+}
+
+interface Edge {
+  a: number;
+  b: number;
+  length: number;
+}
+
+/**
+ * The rows of every region: `MQ_MAX_EDGE` (§5's `L(R)`), `MQ_TRANSITION` (its
+ * 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
+ * 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.
+ */
+function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon: readonly Pt[]): Built[] {
+  const { attachment, source, art } = input;
+  const who = `attachment ${nameOf(attachment)}`;
+  const scale = art.frame.pageScale;
+  const points: Pt[] = source.points;
+  const out: Built[] = [];
+  const spec = (code: string, unit: MeasureRow['unit'], region: string): RowSpec => ({ code, unit, region, attachment });
+  const encoded = meshEdges(points.length, source.triangles, outline.hull);
+  const edges: Edge[] = [];
+  for (let i = 0; i < encoded.length; i += 2) {
+    const a = encoded[i] / 2;
+    const b = encoded[i + 1] / 2;
+    edges.push({ a: Math.min(a, b), b: Math.max(a, b), length: Math.hypot(points[b][0] - points[a][0], points[b][1] - points[a][1]) });
+  }
+  edges.sort((p, q) => p.a - q.a || p.b - q.b);
+
+  // Which regions are measurable, and the one refusal of each that is not.
+  const live: RefinementRegion[] = [];
+  const refusals = new Map<string, string>();
+  for (const region of input.targets.regions) {
+    let refusal = regionRefusal(region, scale, who);
+    if (refusal === null) {
+      const poly: Pt[] = region.polygon;
+      const meets = edges.some((e) => segmentMeetsPolygon(points[e.a], points[e.b], poly)) || poly.some((p) => inClosedPolygon(p, hullPolygon));
+      if (!meets) {
+        refusal = {
+          code: 'REGION_OUTSIDE_ART',
+          message: `${who}, region "${region.name}": the polygon does not meet the mesh's hull anywhere, so clipped to it the region is empty; required a region that meets the hull`,
+        };
+      }
+    }
+    if (refusal === null) live.push(region);
+    else refusals.set(region.name, `${refusal.code}: ${refusal.message}`);
+  }
+
+  /** Every bound that applies to an edge, from every measurable region, and the smallest. */
+  const boundOf = (e: Edge): number | null => {
+    let bound: number | null = null;
+    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;
+    }
+    return bound;
+  };
+
+  /** The worst edge of a set: the largest length over its own bound, ties to the smaller (a, b). */
+  const worstOf = (set: readonly Edge[]): { edge: Edge; bound: number } | null => {
+    let best: { edge: Edge; bound: number; excess: number } | null = null;
+    for (const e of set) {
+      const bound = boundOf(e);
+      if (bound === null) continue;
+      const excess = r6(e.length) - bound;
+      if (best === null || excess > best.excess) best = { edge: e, bound, excess };
+    }
+    return best === null ? null : { edge: best.edge, bound: best.bound };
+  };
+
+  const floorOf = (name: string): number => input.regionArtSamples.find((f) => f.region === name)!.minArtSamples;
+  const { mask, threshold } = art;
+  const artBits = artOf(mask, threshold);
+
+  for (const region of input.targets.regions) {
+    const refused = refusals.get(region.name);
+    if (refused !== undefined) {
+      out.push(unmeasuredRow(spec('MQ_MAX_EDGE', 'px', region.name), 'refused', refused, true));
+      out.push(unmeasuredRow(spec('MQ_TRANSITION', 'px', region.name), 'refused', refused, true));
+      out.push(unmeasuredRow(spec('MQ_FILL_DISTANCE', 'px', region.name), 'refused', refused, false));
+      continue;
+    }
+    const poly: Pt[] = region.polygon;
+    const inside = edges.filter((e) => segmentMeetsPolygon(points[e.a], points[e.b], poly));
+    const maxSpec = spec('MQ_MAX_EDGE', 'px', region.name);
+    const inWorst = worstOf(inside);
+    if (inWorst === null) {
+      out.push(unmeasuredRow(maxSpec, 'not-measurable', `${who}, region "${region.name}": no triangle edge meets the closed polygon — it lies inside one triangle — so L(R) is a maximum over no edge`, true));
+    } else {
+      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 bandWorst = worstOf(banded);
+      const transitionSpec = spec('MQ_TRANSITION', 'px', region.name);
+      if (bandWorst === null) {
+        out.push(unmeasuredRow(transitionSpec, 'not-measurable', `${who}, region "${region.name}": no triangle edge lies in the ${region.transition} px band outside the polygon`, true));
+      } else {
+        out.push(measuredRow(transitionSpec, r6(bandWorst.edge.length), { op: '<=', value: bandWorst.bound }, { at: { edge: [bandWorst.edge.a, bandWorst.edge.b] } }, true));
+      }
+    }
+
+    // h(R): art pixel centres inside the region clipped to the hull, each to its nearest mesh vertex.
+    let count = 0;
+    let worst = -1;
+    let worstAt = -1;
+    for (let i = 0; i < artBits.length; i++) {
+      if (!artBits[i]) continue;
+      const x = i % mask.width;
+      const y = Math.floor(i / mask.width);
+      const centre: Pt = [(x + 0.5) / scale, (y + 0.5) / scale];
+      if (!inClosedPolygon(centre, poly) || !inClosedPolygon(centre, hullPolygon)) continue;
+      count++;
+      let nearest = Infinity;
+      for (const p of points) nearest = Math.min(nearest, Math.hypot(p[0] - centre[0], p[1] - centre[1]));
+      if (nearest > worst) {
+        worst = nearest;
+        worstAt = i;
+      }
+    }
+    const fillSpec = spec('MQ_FILL_DISTANCE', 'px', region.name);
+    const floor = floorOf(region.name);
+    const sampled = { threshold, connectivity: null, samples: count };
+    const sampling = { domain: 'art pixel centres inside the region and the hull', count };
+    let fill: Built;
+    if (count < floor) {
+      fill = unmeasuredRow(fillSpec, 'not-measurable', `${who}, region "${region.name}" holds ${count} art sample(s) inside the hull at alpha >= ${threshold}; required at least ${floor} (P9)`, false);
+    } else {
+      fill = measuredRow(fillSpec, r6(worst), null, { at: { pixel: [worstAt % mask.width, Math.floor(worstAt / mask.width)] } }, false);
+    }
+    fill.row.art = sampled;
+    fill.row.sampling = sampling;
+    out.push(fill);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// the echo, and the document's text
+// ---------------------------------------------------------------------------
+
+function effectiveOf(input: MeshMeasureInput): EffectiveSettings {
+  const { art } = input;
+  return {
+    preset: input.preset,
+    attachments: [
+      {
+        attachment: input.attachment,
+        threshold: art.threshold,
+        // A measurement states the threshold it was taken at and claims nothing at any other (Thresholds).
+        finalThreshold: art.threshold,
+        frame: art.frame,
+        maskSize: [art.mask.width, art.mask.height],
+        minArtSamples: input.minArtSamples,
+        regions: input.targets.regions.map((r) => ({ name: r.name, minArtSamples: input.regionArtSamples.find((f) => f.region === r.name)!.minArtSamples })),
+      },
+    ],
+    sourceBounds: null,
+    referenceArtFit: null,
+    candidateArtFit: null,
+    targets: input.targets,
+    referenceHull: input.referenceHull,
+    motionBounds: null,
+    protect: input.protect,
+    influences: input.influences,
+    boneOrder: input.boneOrder,
+    schedule: null,
+    budget: null,
+  };
+}
+
+// Every object of the document is rebuilt below in the order its type states
+// its keys, so the bytes depend on the values alone — never on the key order
+// an input object happened to be built in (A18's standard; `build-report/1`'s
+// precedent in `src/assertions/report.ts`). An optional key is written only
+// when it is present.
+
+type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+
+const pair = (p: readonly [number, number]): Json => [p[0], p[1]];
+const attachmentJson = (a: AttachmentRef): Json => ({ skin: a.skin, slot: a.slot, attachment: a.attachment });
+const fitJson = (f: ArtFitBounds | null): Json => (f === null ? null : { minCoverage: f.minCoverage, maxOvershoot: f.maxOvershoot, maxUndercut: f.maxUndercut });
+const frameJson = (f: SourceFrame): Json => ({ space: f.space, width: f.width, height: f.height, pageScale: f.pageScale, conversion: f.conversion });
+
+function regionJson(r: RefinementRegion): Json {
+  return {
+    name: r.name,
+    polygon: r.polygon.map(pair),
+    maxEdgeLength: r.maxEdgeLength,
+    transition: r.transition,
+    grade: r.grade,
+    approximation: r.approximation === null ? null : { from: r.approximation.from, policy: r.approximation.policy, maxError: r.approximation.maxError },
+  };
+}
+
+function targetsJson(t: ReductionTargets | MeasureTargets | null): Json {
+  if (t === null) return null;
+  const out: { [key: string]: Json } = { artFit: fitJson(t.artFit), maxBoundaryDeviation: t.maxBoundaryDeviation };
+  if (t.minAngle !== undefined) out.minAngle = t.minAngle;
+  out.regions = t.regions.map(regionJson);
+  return out;
+}
+
+function protectJson(p: ProtectedFeatures | null): Json {
+  if (p === null) return null;
+  return {
+    hull: p.hull,
+    vertices: [...p.vertices],
+    edges: p.edges.map(pair),
+    regionBoundaries: [...p.regionBoundaries],
+    weightJump: p.weightJump,
+    influences: [...p.influences],
+  };
+}
+
+function motionBoundsJson(b: MotionBounds | null): Json {
+  if (b === null) return null;
+  const out: { [key: string]: Json } = { maxLocalDeformation: b.maxLocalDeformation };
+  if (b.maxStretch !== undefined) out.maxStretch = b.maxStretch;
+  if (b.minStretch !== undefined) out.minStretch = b.minStretch;
+  return out;
+}
+
+function scheduleJson(s: MotionSchedule | null): Json {
+  if (s === null) return null;
+  return {
+    frames: s.frames.map((f): Json => (f === 'setup' ? 'setup' : 'times' in f ? { animation: f.animation, times: [...f.times] } : { animation: f.animation, fps: f.fps })),
+    phases: [...s.phases],
+    physics: s.physics.mode === 'none' ? { mode: 'none' } : { mode: 'step', dt: s.physics.dt, warmupSteps: s.physics.warmupSteps },
+    selection: [...s.selection],
+  };
+}
+
+function effectiveJson(e: EffectiveSettings): Json {
+  return {
+    preset: e.preset === null ? null : { name: e.preset.name, version: e.preset.version },
+    attachments: e.attachments.map((a) => ({
+      attachment: attachmentJson(a.attachment),
+      threshold: a.threshold,
+      finalThreshold: a.finalThreshold,
+      frame: frameJson(a.frame),
+      maskSize: pair(a.maskSize),
+      minArtSamples: a.minArtSamples,
+      regions: a.regions.map((r) => ({ name: r.name, minArtSamples: r.minArtSamples })),
+    })),
+    sourceBounds: fitJson(e.sourceBounds),
+    referenceArtFit: fitJson(e.referenceArtFit),
+    candidateArtFit: fitJson(e.candidateArtFit),
+    targets: targetsJson(e.targets),
+    referenceHull: e.referenceHull === null ? null : e.referenceHull.map(pair),
+    motionBounds: motionBoundsJson(e.motionBounds),
+    protect: protectJson(e.protect),
+    influences: e.influences === null ? null : { maxInfluences: e.influences.maxInfluences, minWeight: e.influences.minWeight },
+    boneOrder: e.boneOrder === null ? null : [...e.boneOrder],
+    schedule: scheduleJson(e.schedule),
+    budget: e.budget === null ? null : { maxCandidates: e.budget.maxCandidates },
+  };
+}
+
+function frameRefJson(f: FrameRef): Json {
+  return { id: f.id, animation: f.animation, phase: f.phase, time: f.time, index: f.index, role: f.role };
+}
+
+function worstJson(w: WorstSample | null): Json {
+  if (w === null) return null;
+  const at: { [key: string]: Json } = {};
+  if (w.at.pixel !== undefined) at.pixel = pair(w.at.pixel);
+  if (w.at.triangle !== undefined) at.triangle = w.at.triangle;
+  if (w.at.edge !== undefined) at.edge = pair(w.at.edge);
+  if (w.at.vertex !== undefined) at.vertex = w.at.vertex;
+  if (w.at.uv !== undefined) at.uv = pair(w.at.uv);
+  const out: { [key: string]: Json } = { at };
+  if (w.frame !== undefined) out.frame = frameRefJson(w.frame);
+  return out;
+}
+
+function rowJson(r: MeasureRow): Json {
+  const out: { [key: string]: Json } = {
+    code: r.code,
+    object: { attachment: attachmentJson(r.object.attachment), region: r.object.region },
+    state: r.state,
+    value: r.value,
+    bound: r.bound === null ? null : { op: r.bound.op, value: r.bound.value },
+    unit: r.unit,
+    worst: worstJson(r.worst),
+    reason: r.reason,
+  };
+  if (r.art !== undefined) out.art = { threshold: r.art.threshold, connectivity: r.art.connectivity, samples: r.art.samples };
+  if (r.raster !== undefined) {
+    const g = r.raster.grid;
+    out.raster = {
+      grid: { width: g.width, height: g.height, pageScale: g.pageScale },
+      spatialQuantum: r.raster.spatialQuantum,
+      valueIncrement: r.raster.valueIncrement,
+      nearBound: r.raster.nearBound,
+    };
+  }
+  if (r.sampling !== undefined) out.sampling = { domain: r.sampling.domain, count: r.sampling.count };
+  return out;
+}
+
+function sectionJson(s: EvidenceSection): { [key: string]: Json } {
+  const m = s.summary;
+  return {
+    rows: s.rows.map(rowJson),
+    summary: { pass: m.pass, fail: m.fail, undeclared: m.undeclared, refused: m.refused, notMeasurable: m.notMeasurable, measured: m.measured },
+    verdict: s.verdict,
+  };
+}
+
+const countsJson = (c: MeshCounts | null): Json =>
+  c === null ? null : { boundaryVertices: c.boundaryVertices, interiorVertices: c.interiorVertices, triangles: c.triangles, bindings: c.bindings, maxInfluences: c.maxInfluences };
+
+function candidateJson(c: CandidateReport): Json {
+  const out: { [key: string]: 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) },
+    accepted: c.accepted,
+  };
+  if (c.perFrame !== undefined) out.perFrame = c.perFrame.map((p) => ({ code: p.code, frame: p.frame, value: p.value }));
+  return out;
+}
+
+function terminationJson(t: Termination | null): Json {
+  if (t === null) return null;
+  switch (t.reason) {
+    case 'no-further-valid-reduction':
+      return { reason: t.reason, candidatesTried: t.candidatesTried, blockingConstraint: t.blockingConstraint };
+    case 'budget-exhausted':
+      return { reason: t.reason, candidatesTried: t.candidatesTried, budget: t.budget, result: t.result };
+    case 'invalid-input':
+    case 'unsupported-topology':
+      return { reason: t.reason, code: t.code, detail: t.detail };
+  }
+}
+
+/**
+ * The document's text: two-space JSON and a final newline, every key in the
+ * order its type states it, so two reports of one input are byte-identical —
+ * nothing in it is a time, a path or a machine's.
+ */
+export function writeMeshQualityReport(report: MeshQualityReport): string {
+  const doc: Json = {
+    spec: report.spec,
+    operation: report.operation,
+    effective: effectiveJson(report.effective),
+    poser: report.poser === null ? null : { kind: report.poser.kind, rigcVersion: report.poser.rigcVersion },
+    motionRequired: report.motionRequired,
+    sourceCounts: countsJson(report.sourceCounts),
+    reference: report.reference === null ? null : candidateJson(report.reference),
+    candidates: report.candidates.map(candidateJson),
+    termination: terminationJson(report.termination),
+  };
+  return `${JSON.stringify(doc, null, 2)}\n`;
+}