spine-rigc 1.5.3 → 1.6.2

package/src/deformreport.ts

@@ -0,0 +1,370 @@
+/**
+ * The `DEFORM` report block `rigc explain` prints (issue #316), as a function of
+ * the deform survey alone (issue #969): moved out of `cli.ts` whole, so that a
+ * control can render it off a survey taken through either poser — spine-core
+ * over the Spine skeleton, rigc's own core over the model document — and hold
+ * the two blocks to each other. `cli.ts`'s `deformReportLines` states why the
+ * block is a report and not an assertion, and what it deliberately leaves out.
+ */
+import type { CompileResult } from './types.ts';
+import type { DeformExtreme, DeformKeyMeasure, DeformSpan, DeformSurvey } from './deformmeasure.ts';
+import { unreachableWhy } from './deformmeasure.ts';
+import { float32Step } from './timelines.ts';
+
+/**
+ * One extreme, as `x0.637306 tri 0`, or an em dash when no triangle on the key
+ * could carry the quantity.
+ *
+ * A dash rather than `x1.000000`: a key over a mesh whose every triangle is a
+ * hair has no ratio and no map, and printing the identity there would report a
+ * measurement that was never taken — this repository's favourite false green.
+ */
+function deformExtreme(extreme: DeformExtreme | null): string {
+  return extreme === null ? '—'.padEnd(9) : `x${extreme.value.toFixed(6)} tri ${extreme.triangle}`;
+}
+
+/** `head/head key 1`, which is how A39's own message names a key. */
+function deformKeyName(key: DeformKeyMeasure): string {
+  return `${key.slot}/${key.attachment} key ${key.key}`;
+}
+
+/**
+ * Does this compiled `transform` report belong to this loaded key?
+ *
+ * ⚠️ The two times are not the same number and cannot be compared with `===`.
+ * The report's is the spec's own `t`; the survey's came back through
+ * `Float32Array`, because that is what `spine-core` reads a timeline's frames
+ * into — a key written `0.62` arrives as `0.6200000047683716`. So the tolerance
+ * is one float32 step at this magnitude (`float32Step`): the compiler emits a
+ * key time as a float's name — the spec's own time when it names one, the float
+ * below it when it does not (issue #716) — so the loaded float is within one
+ * step of the spec's `t` either way, which is narrower than any key spacing the
+ * format can hold.
+ */
+function sameKeyTime(specTime: number, loaded: number): boolean {
+  return Math.abs(specTime - loaded) <= float32Step(loaded);
+}
+
+/** The block, off `survey` — `cli.ts`'s `deformReportLines` says what each line is and why. */
+export function deformReportBlock(survey: DeformSurvey, deformTransforms: CompileResult['deformTransforms'], exempt: ReadonlySet<string>): string[] {
+  if (survey.timelines === 0) return [];
+  const out: string[] = ['', 'deform  (what each key does to the geometry — figures with names, never a bar; issue #316)'];
+  // The legend costs six lines and is worth them exactly once — on a report that
+  // has figures in it. A bounding box or a clipping polygon deformed and nothing
+  // else gets the reason it has no figures and no essay about them.
+  if (survey.keys.length) {
+    out.push(
+      '  ..    every key measured at its OWN time against the same pose with the deform CLEARED, so the',
+      '  ..    denominator is 1.000 by definition and a NEGATIVE area ratio IS a reversed triangle',
+      '  ..    the FRAME is on each key line: on a track, or the slider that applies the animation with the',
+      '  ..    dial value its mapping was inverted to — a slider picks the time, so the key\'s time IS it',
+      '  ..    stretch is the two singular values of the map from the cleared triangle to the deformed one —',
+      '  ..    the worst stretch and the worst squash the drawing takes there; their product is |area ratio|',
+      '  ..    coverage is NOT here: it is rasterised from the uvs, which no deform moves, so the figure on',
+      '  ..    the `meshes` line below is already the deformed one',
+    );
+  }
+  if (survey.notAMesh.length) {
+    out.push(`  ..    ${survey.notAMesh.join(', ')} deform an attachment with no triangles — nothing to measure`);
+  }
+  for (const key of survey.keys) {
+    const model = deformTransforms.find(
+      (g) =>
+        g.animation === key.animation &&
+        g.skin === key.skin &&
+        g.slot === key.slot &&
+        g.attachment === key.placeholder &&
+        sameKeyTime(g.time, key.time),
+    );
+    // A stated model is quoted rather than reduced to its results: `yaw
+    // radius=170 degrees=12` is what a reviewer checks the ratios against, and an
+    // authored table says so instead of saying nothing, because "no model here"
+    // is itself the thing a reader of a wrong ratio needs to know.
+    const states = model === undefined ? 'authored table' : `transform ${model.kind}  ${model.stated}`;
+    out.push(
+      `  DEFORM  ${key.animation}  ${key.skin}/${key.slot}/${key.placeholder}  key ${key.key}  ` +
+        `t=${key.time.toFixed(6)}  ${states}`,
+    );
+    // 🔒 The frame, on every key, because the derivation is shared with A39 and
+    // this block is where a reader finds out which one it was (issue #407). A
+    // track frame says so in three words; a slider frame names the dial value
+    // its own mapping inverts this time to, which is the number an author sets.
+    out.push(
+      `          frame      ${key.reach.label}` +
+        (key.dial === null
+          ? ''
+          : `, dial ${key.dial.value.toFixed(6)}` +
+            // ⚠️ `reach.drive` names the field when it is NOT the one `property`
+            // names, which happens under `local: false` on a rotated parent — a
+            // bare figure there would read as a value of the wrong field (#419).
+            (key.reach.local || key.dial.driven === key.dial.value
+              ? ''
+              : ` (bone local ${key.reach.drive === null ? '' : `${key.reach.drive} `}${key.dial.driven.toFixed(6)})`) +
+            ` -> t=${key.dial.applied.toFixed(6)}`),
+    );
+    // A key at a time no dial selects: the figures below are the frame the
+    // runtime DOES land on, which is some other time's geometry, so the line
+    // that says so comes before them and the gate reads none of them.
+    if (key.dial?.unreachable === true) {
+      out.push(
+        `          unreachable A39 gates nothing here: ${unreachableWhy(key)}. Every figure below is that other ` +
+          "frame's, not this key's",
+      );
+    }
+    // ⚠️ An exemption nobody can see is how a gate comes to look kept while
+    // checking nothing (issue #401). A key the gate passed over because the mesh
+    // draws no pixels there says so on its own line, in the survey's own words,
+    // whether or not it folds.
+    if (key.draw.blank !== null) {
+      out.push(
+        `          skipped    A39 reads no winding off this key: ${key.draw.blank} — a triangle that draws no ` +
+          'pixels cannot draw them backwards',
+      );
+    }
+    // And when the slot shows something else, the figures below would be a
+    // second falsehood rather than a caveat: the runtime applies no deform to a
+    // slot that is not showing the mesh (`DeformTimeline.applyToSlot`), so every
+    // figure would be the identity and `moved 0` would read as "this key is the
+    // setup pose" — which is exactly what the key is NOT.
+    if (!key.draw.showsThisMesh) {
+      out.push(
+        `          ..         the slot shows ${key.draw.shown === null ? 'no attachment' : `"${key.draw.shown}"`} ` +
+          'here, so the runtime applied no deform and there is no posed geometry to measure' +
+          (key.draw.blank === null
+            ? ' — but the mesh IS drawn in another slot this deform reaches (timelineSlots), so nothing here is exempt'
+            : ''),
+      );
+      continue;
+    }
+    // A key that moves nothing gets one line and no figures. `{ "t": 2.2 }` with
+    // no run is the format's own way of writing "back to the setup pose" (§4.11),
+    // and its geometry is bit-identical to the cleared pose it would be measured
+    // against — so `x1.000000` there is the definition and not a measurement, and
+    // four lines of it on every loop's opening and closing key is the noise that
+    // stops the block being read. It is still counted in the rollup below,
+    // because A39 measures it too.
+    if (key.moved === 0) {
+      out.push(
+        `          moved      0 of ${key.vertices} vertices — this key IS the setup pose, so every ` +
+          `figure is the identity (${key.triangles} triangles, all kept)`,
+      );
+      continue;
+    }
+    out.push(
+      `          moved      ${key.moved} of ${key.vertices} vertices, ` +
+        `worst ${key.maxDisplacement.toFixed(4)}px at v${key.maxDisplacementVertex}`,
+    );
+    out.push(
+      `          area       min ${deformExtreme(key.areaRatioMin)}   max ${deformExtreme(key.areaRatioMax)}   ` +
+        `(${key.triangles} triangles, ${key.degenerate} with no area at the cleared pose, band ${key.band.toFixed(6)}px²)`,
+    );
+    out.push(
+      `          stretch    max ${deformExtreme(key.stretchMax)}   min ${deformExtreme(key.stretchMin)}`,
+    );
+    // The marker has to know about the exemption, or it says the false half of
+    // the truth on the one build where it matters: a declared fold IS a fold and
+    // A39 does not refuse it — it SKIPs the slot entirely.
+    const exempted = exempt.has(key.slot);
+    const fold = key.reversed.length
+      ? key.draw.blank !== null
+        ? '  <- a fold, and nothing gates it: this key draws no pixels (see above)'
+        : exempted
+          ? '  <- a fold, and A39 does not gate it — see below'
+          : '  <- a fold: A39 refuses this key by name'
+      : '';
+    out.push(
+      `          winding    ${key.triangles - key.reversed.length} of ${key.triangles} kept, ` +
+        `${key.collapsed} collapsed${fold}`,
+    );
+    if (exempted) {
+      out.push(
+        `          ..         A39 is exempt on "${key.slot}" (invariants.deformMayFold), so nothing here is gated`,
+      );
+    }
+  }
+  // The folds at times no key lands on (issue #403), printed after the keys they
+  // lie between rather than interleaved: they are a different measurement — the
+  // closed form named the time and the runtime was posed there — and a reader
+  // needs to be able to tell the two apart at a glance.
+  for (const span of survey.spans) {
+    if (span.fold === null) continue;
+    const at = span.fold;
+    out.push(
+      `  BETWEEN ${span.animation}${span.reach.kind === 'slider' ? ` via ${span.reach.slider}` : ''}  ` +
+        `${span.skin}/${span.slot}/${span.placeholder}  key ${span.fromKey} -> ` +
+        `${span.toKey}  t=${at.time.toFixed(6)}  ${span.curve}` +
+        (span.curve === 'stepped' ? '  (held, not interpolated)' : `  ${(at.percent * 100).toFixed(1)}% of the way`),
+    );
+    out.push(
+      `          winding    ${at.measure.triangles - at.measure.reversed.length} of ${at.measure.triangles} kept, ` +
+        `${at.measure.collapsed} collapsed  <- a fold at a time no key lands on` +
+        (at.measure.draw.blank !== null
+          ? ', and nothing gates it: nothing is drawn there'
+          : exempt.has(span.slot)
+            ? ', and A39 does not gate it (invariants.deformMayFold)'
+            : `: A39 refuses this span by name, at alpha ${at.measure.draw.alpha.toFixed(4)}`),
+    );
+  }
+  // The rollup, per animation: the worst key by each quantity. A timeline's own
+  // eight keys are eight blocks above, and "which of them is the one to look at"
+  // is the question the sweep in issue #313's landing comment answered by hand.
+  //
+  // ⚠️ Per animation AND per frame (issue #407). Two sliders applying one
+  // animation are two frames and two rollups: merging them would average a fold
+  // one dial reaches into a run of keys another one is clean over, which is the
+  // hiding the two frames exist to prevent.
+  // 🔒 ONE derivation of a rollup's identity, read by every filter below.
+  //
+  // ⚠️ It was spelled three times and one of them drifted. The two key filters
+  // separate animation from slider with a NUL; the span filter used a SPACE, so
+  // its `=== id` never matched on any rig and `spans` was always empty — the
+  // "N span(s) … scanned" line silently stopped printing everywhere, taking with
+  // it the one thing issue #403 added it to say: that the scan RAN and found
+  // nothing, as opposed to never having run. A dead branch is the same silence
+  // this tool exists to convert into a named failure, and it survived because
+  // the identity was a literal at each site rather than a derivation (#440).
+  const rollupId = (animation: string, slider: string | null): string => `${animation}\u0000${slider ?? ''}`;
+  /**
+   * The readings A39 puts on its stats line for the three things this rollup
+   * reports — each spelled ONCE here and nowhere else in this file.
+   *
+   * 🔒 Checked rather than derived, and the difference is forced: `src/validate.ts`
+   * sets these on a `Record<string, number | string>`, so there is no type to take
+   * a name off and no constant to import. So they are spelled here and a control
+   * compiles a rig that triggers each one, then asserts the breadcrumb names a
+   * reading A39 really printed — two independent derivations compared, which is
+   * the shape `CUR07` uses for the same reason.
+   */
+  const A39_COUNTS = {
+    notDrawn: 'deformKeysNotDrawn',
+    unreachable: 'deformKeysUnreachable',
+    dialsDisagreed: 'deformDialsDisagreed',
+    dialDisagreed: 'deformDialDisagreed',
+  } as const;
+  const rollups = new Map<string, { animation: string; label: string }>();
+  for (const key of survey.keys) {
+    rollups.set(rollupId(key.animation, key.reach.slider), {
+      animation: key.animation,
+      label: key.reach.kind === 'slider' ? `${key.animation} via ${key.reach.slider}` : key.animation,
+    });
+  }
+  for (const [id, { animation, label }] of rollups) {
+    // Only the keys the gate ran on, because the line ends by claiming A39 reads
+    // the same two counts and A39 reads none of a key that draws nothing, nor of
+    // one at a time no dial selects. The ones it left out get their own line
+    // rather than a silence (issues #401, #407).
+    const mine = survey.keys.filter((k) => rollupId(k.animation, k.reach.slider) === id);
+    const unreachable = mine.filter((k) => k.dial?.unreachable === true);
+    const keys = mine.filter((k) => k.dial?.unreachable !== true && k.draw.blank === null);
+    const blank = mine.filter((k) => k.dial?.unreachable !== true && k.draw.blank !== null);
+    const worst = (
+      pick: (key: DeformKeyMeasure) => DeformExtreme | null,
+      better: (a: number, b: number) => boolean,
+    ): string => {
+      let best: { key: DeformKeyMeasure; extreme: DeformExtreme } | null = null;
+      for (const key of keys) {
+        const extreme = pick(key);
+        if (extreme === null) continue;
+        if (best === null || better(extreme.value, best.extreme.value)) best = { key, extreme };
+      }
+      return best === null ? '—' : `x${best.extreme.value.toFixed(6)} (${deformKeyName(best.key)} tri ${best.extreme.triangle})`;
+    };
+    const reversed = keys.reduce((n, k) => n + k.reversed.length, 0);
+    const collapsed = keys.reduce((n, k) => n + k.collapsed, 0);
+    const samples = keys.reduce((n, k) => n + k.triangles, 0);
+    if (keys.length) {
+      out.push(
+        `  WORST   ${label}  area ${worst((k) => k.areaRatioMin, (a, b) => a < b)}  ` +
+          `stretch ${worst((k) => k.stretchMax, (a, b) => a > b)}  ` +
+          `squash ${worst((k) => k.stretchMin, (a, b) => a < b)}`,
+      );
+      out.push(
+        `  ..      ${''.padEnd(label.length)}  reversed ${reversed}, collapsed ${collapsed}, over ` +
+          `${keys.length} key(s) and ${samples} triangle sample(s)  <- A39 reads the same two counts`,
+      );
+    }
+    if (blank.length) {
+      out.push(
+        `  ..      ${keys.length ? ''.padEnd(label.length) : label}  ${blank.length} key(s) draw no pixels ` +
+          `at their own time and are read for no winding, carrying ` +
+          `${blank.reduce((n, k) => n + k.reversed.length, 0)} reversed triangle(s) nothing gates  <- A39 counts ` +
+          `them as ${A39_COUNTS.notDrawn}`,
+      );
+    }
+    if (unreachable.length) {
+      out.push(
+        `  ..      ${keys.length || blank.length ? ''.padEnd(label.length) : label}  ${unreachable.length} key(s) ` +
+          'at a time no dial selects, measured in the frame the runtime lands on instead and read for no winding, ' +
+          `carrying ${unreachable.reduce((n, k) => n + k.reversed.length, 0)} reversed triangle(s) nothing gates ` +
+          ` <- A39 counts them as ${A39_COUNTS.unreachable}`,
+      );
+    }
+    // ⚠️ The dial rigc's two halves disagree about (issues #427, #440). It is a
+    // property of the SLIDER and not of any one key, so it is placed by the
+    // rollup's own identity rather than by a key filter — and it is REPORTED,
+    // never gated: A39 refuses nothing for it, because a disagreement can pose
+    // every frame correctly. Both readings are named because they differ by one
+    // letter, and a breadcrumb that named only one of `deformDialsDisagreed` /
+    // `deformDialDisagreed` would send a reader to grep for the other.
+    const disputes = survey.dialDisputes.filter((dispute) => rollupId(animation, dispute.slider) === id);
+    if (disputes.length) {
+      out.push(
+        `  ..      ${keys.length || blank.length || unreachable.length ? ''.padEnd(label.length) : label}  ` +
+          `${disputes.length} dial(s) the skeleton and the probe disagree about: ` +
+          disputes
+            .map(
+              (dispute) =>
+                `the skeleton reads ${dispute.bone}.${dispute.stated} and the probe drives ` +
+                `${dispute.bone}.${dispute.drive}, ` +
+                (dispute.outside.length === 0
+                  ? 'and both answers pose the same frames'
+                  : `${dispute.outside.length} key time(s) outside what the skeleton's own field reaches`),
+            )
+            .join('; ') +
+          `  <- A39 counts them as ${A39_COUNTS.dialsDisagreed} and spells them out as ${A39_COUNTS.dialDisagreed}`,
+      );
+    }
+    // ⚠️ Printed on a clean animation too. "The scan ran and found nothing" and
+    // "the scan never ran" are the two things a gate must never say the same
+    // way, and this line is the only place an author can tell them apart
+    // (issue #403).
+    const spans = survey.spans.filter((s) => rollupId(s.animation, s.reach.slider) === id);
+    if (spans.length) {
+      out.push(
+        `  ..      ${keys.length || blank.length || unreachable.length || disputes.length ? ''.padEnd(label.length) : label}  ` +
+          `${spans.length} span(s) between consecutive keys scanned for a fold no key lands on: ` +
+          `${spanTally(spans)}  <- A39 reads the same scan`,
+      );
+    }
+  }
+  // ⚠️ And the spans that were NOT scanned, once, because a scan that did not
+  // run has to be distinguishable from one that ran and found nothing — the same
+  // rule the line above keeps, on the other side of it (issue #407).
+  if (survey.spansNotScanned) {
+    out.push(
+      `  ..      ${survey.spansNotScanned} span(s) NOT scanned: one of the two keys bounding each is at a time no ` +
+        'dial selects, so the interpolation between them is between two poses of some other time',
+    );
+  }
+  return out;
+}
+
+/** What the between-keys scan found, in one clause (issue #403). */
+function spanTally(spans: readonly DeformSpan[]): string {
+  const folds = spans.filter((s) => s.fold !== null).length;
+  const notDrawn = spans.filter((s) => s.notDrawn > 0).length;
+  const unconfirmed = spans.filter((s) => s.unconfirmed).length;
+  const probes = spans.reduce((n, s) => n + s.probed.length, 0);
+  if (folds === 0 && notDrawn === 0 && unconfirmed === 0) {
+    return `none folds (the closed form flagged nothing, so no span cost a posed measurement)`;
+  }
+  return (
+    [
+      folds ? `${folds} fold(s)` : '',
+      notDrawn ? `${notDrawn} folding only where nothing is drawn` : '',
+      unconfirmed ? `${unconfirmed} predicted a fold no probe reproduced` : '',
+    ]
+      .filter(Boolean)
+      .join(', ') + `, at a cost of ${probes} posed measurement(s)`
+  );
+}

package/src/depth.ts

@@ -370,6 +370,81 @@ export function compareTurnFields(input: {
  */
 const CEILING_AREA_FLOOR = 1e-6;
 
+/**
+ * A measured figure of the fold report on the tree's six-decimal grid — the
+ * rule `src/mesh.ts`'s `r6` states for the generator's measured figures, and
+ * never "-0".
+ *
+ * ⭐ **Why the report is rounded at all (issue #942).** Every other number the
+ * model document spells is on the float32 grid the Spine file is written on,
+ * or on this one; these four were the only full doubles, and the one place a
+ * platform's libm reached the document. `gallery/look`'s document differed
+ * between macOS and the Linux runner by exactly two leaves,
+ * `/meshes/0/depth/ceiling/pitch/negative/{degrees,p1}`, `26.935130523311`
+ * against `26.935130523311003`: macOS's `Math.atan` returned 0.512 ulp below
+ * the exact arctangent and Linux the correctly rounded double above it.
+ * Measured on that rig, the nearest six-decimal boundary is at least 2.33e-8°
+ * from any of its ceiling angles against a one-ulp step of about 3.6e-15°, so
+ * a one-ulp difference no longer reaches a byte. What a grid cannot absorb is
+ * stated rather than hidden: a value within one ulp of a rounding boundary
+ * still moves. Which triangle is the minimum no longer rides on the last ulp
+ * (issue #949): the choice is made on this grid too, by `foldPrecedes`.
+ *
+ * 🔒 Applied to the figures after the minimum is chosen and the percentile
+ * ranked; `TC01` still requires the named triangle, at ±0.01°, to be one `A39`
+ * fires on, and `TB03` that it is the FIRST one A39 names. A share or
+ * a step is a positive number and r6 only returns 0 for one under 5e-7; `TC07`
+ * reads every share it builds as `> 0`.
+ */
+function r6(n: number): number {
+  const v = Math.round(n * 1e6) / 1e6;
+  return v === 0 ? 0 : v;
+}
+
+/**
+ * Whether fold `a` is the tighter of two on one axis and side: its angle is
+ * smaller ON THE SIX-DECIMAL GRID THE REPORT SPELLS IT ON, or equal there and
+ * `a` is the lower triangle ordinal. `degrees` are the full doubles; the grid
+ * is applied here, so a caller cannot compare the doubles by accident.
+ *
+ * ⭐ Why the grid and not the doubles (issue #949). A minimum chosen on full
+ * doubles is chosen by the platform's libm whenever two triangles fold within
+ * a few ulps of each other, and a fold names its triangle with that
+ * triangle's own `ids`, `depthStep` and `stepShare`, so the document moves by
+ * whole fields while the angle it prints does not. Measured on
+ * `gallery/look`, with every libm-backed `Math` result moved one ulp through a
+ * `--preload`: mesh 0's `pitch.negative` minimum is triangles 49 and 50, both
+ * at exactly `26.935130523311` unperturbed (the doubles are EQUAL, and the
+ * first-found rule named 49); `Math.pow` +1 ulp made 50 the smaller by one ulp
+ * (`26.935130523310995`) and −1 ulp made 49 the larger (`26.935130523311003`),
+ * and the document named 50, `ids` `[60,…,80]`, `depthStep` 90.533309 for
+ * 95.668608. `pow` −1 ulp also swapped `yaw.positive`'s triangles 174 and 215
+ * (`19.316350434748518`, both; 7.1e-15° apart once perturbed). 5 and 10 leaves
+ * moved; with this rule, 0 under `atan`, `pow` or all sixteen functions
+ * together, either direction, on all seven gallery rows.
+ *
+ * ⭐ Why the LOWEST ordinal, and not some other tie-break: it is the order
+ * `A39` names triangles in. The gate lists the triangles a key reverses by
+ * ascending ordinal (`deformmeasure.ts`, `reversed`), so turned just past a
+ * tied ceiling every tied triangle reverses and the first one the refusal
+ * names is the lowest — the one this reports. `TB03` holds the two to it on a
+ * planted tie; `TB01` holds the choice unmoved by which of two tied triangles
+ * carries the larger double.
+ *
+ * ⚠️ What a grid cannot absorb, stated rather than hidden: two angles one ulp
+ * apart that straddle a six-decimal rounding boundary are two different
+ * reported values, and a one-ulp change can still pick the other one. That is
+ * the value moving, not the choice, and it is the residual `r6` already names.
+ */
+export function foldPrecedes(
+  a: { readonly degrees: number; readonly triangle: number },
+  b: { readonly degrees: number; readonly triangle: number },
+): boolean {
+  const ra = r6(a.degrees);
+  const rb = r6(b.degrees);
+  return ra < rb || (ra === rb && a.triangle < b.triangle);
+}
+
 /**
  * Where one triangle turns inside out, which triangle that is — and, beside it,
  * what the REST of this axis and side's triangles do.
@@ -393,6 +468,11 @@ const CEILING_AREA_FLOOR = 1e-6;
  * smooths or rejects a sample — the ceiling stays the raw sheet read through
  * the mesh, which is the only thing `A39` will agree with. What to read off the
  * two numbers is stated in `docs/AUTHORING.md` §3.4, not decided here.
+ *
+ * 🔸 `degrees`, `depthStep`, `stepShare` and `p1` are reported on the
+ * six-decimal grid (`r6` above, issue #942), and the choice among triangles is
+ * made on that grid with the lowest ordinal winning a tie (`foldPrecedes`,
+ * issue #949).
  */
 export interface FoldLimit {
   /** Degrees from setup, in (0, 90). */
@@ -572,6 +652,19 @@ export interface TurnCeiling {
  * key is not built from, and would part company with the gate that reads the
  * raw one.
  *
+ * ## Which triangle, when two fold at the same angle (issue #949)
+ *
+ * The minimum is chosen on the six-decimal grid the angle is reported on, and
+ * a tie there goes to the LOWEST triangle ordinal — the triangle `A39` names
+ * first when a key turns just past the ceiling (`foldPrecedes`). Chosen on the
+ * full doubles, it was the platform's libm that broke a tie: on
+ * `gallery/look`, triangles 49 and 50 fold at exactly `26.935130523311` and a
+ * one-ulp `Math.pow` perturbation (through the depth tone, into every `z`)
+ * named 50 instead of 49, moving 5 leaves of the model document in one
+ * direction and 10 in the other while no printed angle moved. With the rule,
+ * a ±1 ulp perturbation of `atan`, `pow`, or sixteen libm functions at once
+ * moves no leaf of any gallery row's document (`TB02` re-runs it in process).
+ *
  * @param points Vertices in the BIND space the deform offsets are authored in.
  *   Areas are translation-invariant, so the origin does not matter; the scale
  *   and the axis directions do. A y flip alone leaves a `yaw` answer alone and
@@ -661,7 +754,10 @@ export function turnCeiling(
       const held = out[axis][side];
       // `count` and `p1` are filled once the whole population is in; a minimum
       // cannot know its own percentile while it is still being found.
-      if (held === null || degrees < held.degrees) {
+      // On the reported grid, lowest ordinal first — `foldPrecedes` above. The
+      // walk is in ordinal order, so the ordinal clause never decides here; it is
+      // stated so the rule does not depend on the walk.
+      if (held === null || foldPrecedes({ degrees, triangle: n }, held)) {
         // `zSpan` cannot be zero here: `aAxis !== 0` needs two of this
         // triangle's vertices at different depths, and the span over the whole
         // mesh is at least that difference. A guard would be an unreachable
@@ -678,7 +774,10 @@ export function turnCeiling(
       const sorted = angles[axis][side].slice().sort((a, b) => a - b);
       const rank = nearestRankIndex(sorted.length, 0.01);
       held.count = sorted.length;
-      held.p1 = rank === 0 ? null : sorted[rank];
+      held.p1 = rank === 0 ? null : r6(sorted[rank]);
+      held.degrees = r6(held.degrees);
+      held.depthStep = r6(held.depthStep);
+      held.stepShare = r6(held.stepShare);
     }
   }
   return out;