@knowvah/dot-engine 2.3.0 → 2.3.1

package/src/pathplan/route.ts

@@ -3,6 +3,8 @@
 
 import type { Point, Poly, Edge } from './types.js';
 import { solve3 } from './solvers.js';
+import { fma, fms } from '../common/fma.js';
+import { libmHypot } from '../common/libm-hypot.js';
 
 const EPSILON1 = 1e-3;
 const EPSILON2 = 1e-6;
@@ -18,28 +20,53 @@ class RouteHelper {
   static B1(t: number): number { const u = 1-t; return 3*t*u*u; }
   static B2(t: number): number { const u = 1-t; return 3*t*t*u; }
   static B3(t: number): number { return t*t*t; }
-  static B01(t: number): number { const u = 1-t; return u*u*(u+3*t); }
-  static B23(t: number): number { const u = 1-t; return t*t*(3*u+t); }
+  /** @see lib/pathplan/route.c:B01 */
+  static B01(t: number): number {
+    const u = 1-t;
+    // clang -ffp-contract=on: fmadd at route.c:488 (`tmp + 3*t`)
+    return (u*u) * fma(3, t, u);
+  }
+  /** @see lib/pathplan/route.c:B23 */
+  static B23(t: number): number {
+    const u = 1-t;
+    // clang -ffp-contract=on: fmadd at route.c:494 (`3*tmp + t`)
+    return (t*t) * fma(3, u, t);
+  }
 
+  /** @see lib/pathplan/route.c:normv */
   static normv(v: Point): Point {
-    const d = v.x*v.x + v.y*v.y;
+    // clang -ffp-contract=on: fmadd at route.c:413 (v.x*v.x fused, v.y*v.y rounded)
+    const d = fma(v.x, v.x, v.y*v.y);
     if (d > 1e-6) { const s = Math.sqrt(d); return { x: v.x/s, y: v.y/s }; }
     return v;
   }
   static ptAdd(a: Point, b: Point): Point { return { x: a.x+b.x, y: a.y+b.y }; }
   static ptSub(a: Point, b: Point): Point { return { x: a.x-b.x, y: a.y-b.y }; }
   static ptScale(p: Point, c: number): Point { return { x: p.x*c, y: p.y*c }; }
-  static ptDot(a: Point, b: Point): number { return a.x*b.x + a.y*b.y; }
-  static ptDist(a: Point, b: Point): number { return Math.hypot(a.x-b.x, a.y-b.y); }
+  /** @see lib/pathplan/route.c:dot */
+  static ptDot(a: Point, b: Point): number {
+    // clang -ffp-contract=on: fmadd at route.c:459 (p1.x*p2.x fused, p1.y*p2.y rounded)
+    return fma(a.x, b.x, a.y*b.y);
+  }
+  /** @see lib/pathplan/route.c:dist (libm hypot, no contraction) */
+  static ptDist(a: Point, b: Point): number { return libmHypot(a.x-b.x, a.y-b.y); }
   static distN(pts: Point[]): number {
     let rv = 0;
     for (let i = 1; i < pts.length; i++) rv += RouteHelper.ptDist(pts[i], pts[i-1]);
     return rv;
   }
 
+  /**
+   * The cubic's coefficients come out of catastrophic cancellation when the
+   * spline is tangent to a barrier (tests/2646.dot), so clang's contraction
+   * here decides solve3's root count; mirror it exactly.
+   * @see lib/pathplan/route.c:points2coeff
+   */
   static points2coeff(v0: number, v1: number, v2: number, v3: number, c: number[]): void {
-    c[3] = v3 + 3*v1 - (v0 + 3*v2);
-    c[2] = 3*v0 + 3*v2 - 6*v1;
+    // clang -ffp-contract=on: fmadd x2 at route.c:397 (`v3 + 3*v1`, `v0 + 3*v2`; outer sub rounded)
+    c[3] = fma(3, v1, v3) - fma(3, v2, v0);
+    // clang -ffp-contract=on: fmadd at route.c:398 (`3*v0` fused onto rounded `3*v2`, then `- 6*v1` fused)
+    c[2] = fma(-6, v1, fma(3, v0, 3*v2));
     c[1] = 3*(v1 - v0);
     c[0] = v0;
   }
@@ -79,7 +106,8 @@ class RouteHelper {
       const tv = xr[i];
       if (tv >= 0 && tv <= 1) {
         RouteHelper.points2coeff(sps[0].y, sps[1].y, sps[2].y, sps[3].y, sc);
-        const sv = (sc[0] + tv*(sc[1] + tv*(sc[2] + tv*sc[3])) - lc.yc0) / lc.yc1;
+        // clang -ffp-contract=on: fmadd x3 at route.c:360-361 (Horner `sv`; `(sv - ycoeff[0]) / ycoeff[1]` plain)
+        const sv = (fma(tv, fma(tv, fma(tv, sc[3], sc[2]), sc[1]), sc[0]) - lc.yc0) / lc.yc1;
         if (sv >= 0 && sv <= 1) RouteHelper.addRoot(tv, acc);
       }
     }
@@ -89,23 +117,27 @@ class RouteHelper {
   static silGeneral(sps: Point[], lc: LineCoeff, acc: RootAccum): number {
     const sc = [0,0,0,0], xr = [0,0,0];
     const rat = lc.yc1 / lc.xc1;
+    // clang -ffp-contract=on: fmsub x4 at route.c:371-372 (`sps[k].y - rat*sps[k].x`)
     RouteHelper.points2coeff(
-      sps[0].y - rat*sps[0].x, sps[1].y - rat*sps[1].x,
-      sps[2].y - rat*sps[2].x, sps[3].y - rat*sps[3].x, sc);
-    sc[0] += rat*lc.xc0 - lc.yc0;
+      fms(rat, sps[0].x, sps[0].y), fms(rat, sps[1].x, sps[1].y),
+      fms(rat, sps[2].x, sps[2].y), fms(rat, sps[3].x, sps[3].y), sc);
+    // clang -ffp-contract=on: fnmsub at route.c:374 (`rat*xcoeff[0] - ycoeff[0]`; `+=` rounded)
+    sc[0] += fma(rat, lc.xc0, -lc.yc0);
     const xn = solve3(sc, xr);
     if (xn === 4) return 4;
     for (let i = 0; i < xn; i++) {
       const tv = xr[i];
       if (tv >= 0 && tv <= 1) {
         RouteHelper.points2coeff(sps[0].x, sps[1].x, sps[2].x, sps[3].x, sc);
-        const sv = (sc[0] + tv*(sc[1] + tv*(sc[2] + tv*sc[3])) - lc.xc0) / lc.xc1;
+        // clang -ffp-contract=on: fmadd x3 at route.c:383-384 (Horner `sv`; `(sv - xcoeff[0]) / xcoeff[1]` plain)
+        const sv = (fma(tv, fma(tv, fma(tv, sc[3], sc[2]), sc[1]), sc[0]) - lc.xc0) / lc.xc1;
         if (sv >= 0 && sv <= 1) RouteHelper.addRoot(tv, acc);
       }
     }
     return acc.n;
   }
 
+  /** @see lib/pathplan/route.c:splineintersectsline */
   static splineIntersectsLine(sps: Point[], lps: Point[], roots: number[]): number {
     const lc: LineCoeff = {
       xc0: lps[0].x, xc1: lps[1].x - lps[0].x,
@@ -156,8 +188,13 @@ class RouteHelper {
       x0 += RouteHelper.ptDot(tnas[i].a[0], tmp);
       x1 += RouteHelper.ptDot(tnas[i].a[1], tmp);
     }
-    const det01 = c00*c11 - c01*c01;
-    const detX1 = x0*c11 - x1*c01, det0X = c00*x1 - c01*x0;
+    // C's c[1][0] is a copy of c[0][1] (route.c:174), so c10 == c01 here.
+    // clang -ffp-contract=on: fnmul+fmadd at route.c:181 (c00*c11 fused, c10*c01 rounded)
+    const det01 = fma(c00, c11, -(c01*c01));
+    // clang -ffp-contract=on: fnmul+fmadd at route.c:182 (c00*x1 fused, c01*x0 rounded)
+    const det0X = fma(c00, x1, -(c01*x0));
+    // clang -ffp-contract=on: fnmul+fmadd at route.c:183 (x0*c11 fused, x1*c01 rounded)
+    const detX1 = fma(x0, c11, -(x1*c01));
     if (Math.abs(det01) >= 1e-6) { scale0 = detX1/det01; scale3 = det0X/det01; }
     if (Math.abs(det01) < 1e-6 || scale0 <= 0 || scale3 <= 0) {
       const d = RouteHelper.ptDist(inps[0], inps[n-1]) / 3;
@@ -179,6 +216,27 @@ class RouteHelper {
     return tnas;
   }
 
+  /**
+   * The max-deviation split of `reallyroutespline` (route.c:130-143): the
+   * interior polyline point farthest from the fitted bezier.
+   *
+   * Faithful contract. On a geometrically symmetric channel two interior
+   * deviations tie to within an ulp, so the split point (and the whole
+   * spline) is decided by C's exact arithmetic, which this mirrors bit for
+   * bit against the native arm64 oracle:
+   * - `dist` is libm `hypot` (route.c:448) -> `libmHypot` via `ptDist`;
+   * - the test is C's strict `(d = dist(p, inps[i])) > maxd` (route.c:139),
+   *   so an exact tie keeps the first index;
+   * - clang's default `-ffp-contract=on` fuses the bezier eval at
+   *   route.c:137-138 as `fma(B3,p2, fma(B2,cp2, fma(B0,p1, B1*cp1)))`; the
+   *   B0..B3 weights and cp1/cp2 (route.c:130-131) are not fused. Fusing the
+   *   other product first is NOT equivalent (flips pt-issue-23-w9 and 32).
+   * C is therefore not translation-equivariant on such ties (the winner
+   * depends on absolute-coordinate rounding), and neither is this port.
+   * This supersedes the former tolerant tie-break (accepted divergence A3).
+   * Contraction map: .agent-notes/pathplan-fma-contraction-map.md.
+   * @see lib/pathplan/route.c:reallyroutespline
+   */
   static findMaxDev(inps: Point[], tnas: Tna[], ends: SplineEndpoints): number {
     const { p0, v0, p1, v1 } = ends;
     const cp1 = RouteHelper.ptAdd(p0, RouteHelper.ptScale(v0, 1/3));
@@ -186,27 +244,14 @@ class RouteHelper {
     let maxi = -1, maxd = -1;
     for (let i = 1; i < inps.length - 1; i++) {
       const t = tnas[i].t;
-      const px = RouteHelper.B0(t)*p0.x + RouteHelper.B1(t)*cp1.x + RouteHelper.B2(t)*cp2.x + RouteHelper.B3(t)*p1.x;
-      const py = RouteHelper.B0(t)*p0.y + RouteHelper.B1(t)*cp1.y + RouteHelper.B2(t)*cp2.y + RouteHelper.B3(t)*p1.y;
+      const b0 = RouteHelper.B0(t), b1 = RouteHelper.B1(t);
+      const b2 = RouteHelper.B2(t), b3 = RouteHelper.B3(t);
+      // clang -ffp-contract=on: fmadd at route.c:137 (x3; B1*cp1.x rounded first)
+      const px = fma(b3, p1.x, fma(b2, cp2.x, fma(b0, p0.x, b1*cp1.x)));
+      // clang -ffp-contract=on: fmadd at route.c:138 (x3; B1*cp1.y rounded first)
+      const py = fma(b3, p1.y, fma(b2, cp2.y, fma(b0, p0.y, b1*cp1.y)));
       const d = RouteHelper.ptDist({ x: px, y: py }, inps[i]);
-      // C `reallyroutespline` uses strict `if (d > maxd)`. On a geometrically
-      // SYMMETRIC channel the two interior deviations are an exact tie, and the
-      // winner is then decided by ~1e-14 cancellation noise in the
-      // absolute-coordinate bezier eval above — whose sign depends on absolute
-      // position. So C is NOT consistent: it splits two translation-congruent
-      // arcs toward opposite corners (e.g. 2368 `376->76` mirrors `256->436`),
-      // because Apple's macOS libm `hypot` (which generated the oracle) is a
-      // proprietary ~1-ULP-divergent implementation that no portable hypot
-      // reproduces. We deliberately keep the tolerant tie-break: a true tie
-      // always resolves to the first index, so the port is TRANSLATION-
-      // EQUIVARIANT (same channel anywhere -> same spline). This matches C where
-      // C's noise also keeps-first (#241_0 5:ne->8:nw, and the cnt=3 oracle
-      // case) and consciously diverges where C's noise keeps-second (2368
-      // `376->76`, the lone surviving residual: structural-match, maxΔ ~10pt on
-      // one flat-edge arc). See .agent-notes/2368-residual-flat-label-ranksep.md
-      // and the pow precedent (src/common/arm-pow.ts) for the same Apple-libm
-      // boundary. @see lib/pathplan/route.c:reallyroutespline (max-deviation split)
-      if (d > maxd * (1 + 1e-10) + 1e-10) { maxd = d; maxi = i; }
+      if (d > maxd) { maxd = d; maxi = i; }
     }
     return maxi;
   }

package/src/pathplan/solvers.ts

@@ -1,65 +1,93 @@
 // SPDX-License-Identifier: EPL-2.0
-/** @see lib/pathplan/solvers.c */
+/**
+ * @see lib/pathplan/solvers.c
+ *
+ * The native oracle's libpathplan is compiled by clang with the default
+ * `-ffp-contract=on`, which fuses five multiply-adds in this file into single
+ * fmadd/fmsub/fnmsub instructions (solve2 is inlined into solve3). Those sites
+ * are mirrored with the software `fma`; every other operation is plain IEEE
+ * double, in C's evaluation order. Contraction map:
+ * .agent-notes/pathplan-fma-contraction-map.md.
+ */
 
+import { fma } from '../common/fma.js';
+
+/** @see lib/pathplan/solvers.c:EPS */
 const EPS = 1e-7;
 
-class Solver {
-  static aeq0(x: number): boolean {
-    return x < EPS && x > -EPS;
-  }
+/** @see lib/pathplan/solvers.c:AEQ0 */
+function aeq0(x: number): boolean {
+  return x < EPS && x > -EPS;
+}
 
-  static solve1(c: number[], r: number[]): number {
-    if (Solver.aeq0(c[1])) return Solver.aeq0(c[0]) ? 4 : 0;
-    r[0] = -c[0] / c[1];
-    return 1;
-  }
+/**
+ * Solve cubic coeff[3]*x^3 + coeff[2]*x^2 + coeff[1]*x + coeff[0] = 0.
+ * Returns the root count; 4 means every x satisfies.
+ * @see lib/pathplan/solvers.c:solve3
+ */
+export function solve3(coeff: number[], roots: number[]): number {
+  const a = coeff[3], b = coeff[2], c = coeff[1], d = coeff[0];
+  if (aeq0(a)) return solve2(coeff, roots);
+  const bOver3a = b / (3 * a), cOverA = c / a, dOverA = d / a;
 
-  static solve2(c: number[], r: number[]): number {
-    if (Solver.aeq0(c[2])) return Solver.solve1(c, r);
-    const b2a = c[1] / (2 * c[2]);
-    const disc = b2a * b2a - c[0] / c[2];
-    if (disc < 0) return 0;
-    if (disc > 0) {
-      r[0] = -b2a + Math.sqrt(disc);
-      r[1] = -2 * b2a - r[0];
-      return 2;
-    }
-    r[0] = -b2a;
-    return 1;
-  }
+  let p = bOver3a * bOver3a;
+  // clang -ffp-contract=on: fnmul+fmadd at solvers.c:41 (`2*b_over_3a*p` fused,
+  // `b_over_3a*c_over_a` rounded; `+ d_over_a` is a separate rounded add)
+  const q = dOverA + fma(2 * bOver3a, p, -(bOver3a * cOverA));
+  p = cOverA / 3 - p;
+  // clang -ffp-contract=on: fmadd at solvers.c:43 (q*q fused, 4*p*p*p rounded)
+  const disc = fma(q, q, 4 * p * p * p);
 
-  static solve3neg(disc: number, q: number, b3a: number, r: number[]): number {
-    const rr = 0.5 * Math.sqrt(-disc + q * q);
+  let rootn: number;
+  if (disc < 0) {
+    // clang -ffp-contract=on: fnmsub at solvers.c:46 (`-disc + q*q`)
+    const r = 0.5 * Math.sqrt(fma(q, q, -disc));
     const theta = Math.atan2(Math.sqrt(-disc), -q);
-    const temp = 2 * Math.cbrt(rr);
-    r[0] = temp * Math.cos(theta / 3) - b3a;
-    r[1] = temp * Math.cos((theta + 2 * Math.PI) / 3) - b3a;
-    r[2] = temp * Math.cos((theta - 2 * Math.PI) / 3) - b3a;
-    return 3;
+    const temp = 2 * Math.cbrt(r);
+    roots[0] = temp * Math.cos(theta / 3);
+    roots[1] = temp * Math.cos((theta + Math.PI + Math.PI) / 3);
+    roots[2] = temp * Math.cos((theta - Math.PI - Math.PI) / 3);
+    rootn = 3;
+  } else {
+    const alpha = 0.5 * (Math.sqrt(disc) - q);
+    const beta = -q - alpha;
+    roots[0] = Math.cbrt(alpha) + Math.cbrt(beta);
+    if (disc > 0) rootn = 1;
+    else { roots[1] = roots[2] = -0.5 * roots[0]; rootn = 3; }
   }
 
-  static solve3pos(disc: number, q: number, b3a: number, r: number[]): number {
-    const al = 0.5 * (Math.sqrt(disc) - q);
-    r[0] = Math.cbrt(al) + Math.cbrt(-q - al) - b3a;
-    if (disc > 0) return 1;
-    r[1] = r[2] = -0.5 * (r[0] + b3a) - b3a;
-    return 3;
-  }
+  for (let i = 0; i < rootn; i++) roots[i] -= bOver3a;
+  return rootn;
+}
+
+/** @see lib/pathplan/solvers.c:solve2 */
+function solve2(coeff: number[], roots: number[]): number {
+  const a = coeff[2], b = coeff[1], c = coeff[0];
+  if (aeq0(a)) return solve1(coeff, roots);
+  const bOver2a = b / (2 * a);
+  const cOverA = c / a;
 
-  static solve3(c: number[], r: number[]): number {
-    const a = c[3], b = c[2], cv = c[1], d = c[0];
-    if (Solver.aeq0(a)) return Solver.solve2(c, r);
-    const b3a = b / (3 * a), p0 = b3a * b3a;
-    const q = 2 * b3a * p0 - b3a * cv / a + d / a;
-    const p = cv / (3 * a) - p0;
-    const disc = q * q + 4 * p * p * p;
-    return disc < 0 ? Solver.solve3neg(disc, q, b3a, r)
-                    : Solver.solve3pos(disc, q, b3a, r);
+  // clang -ffp-contract=on: fmadd at solvers.c:80 (`b_over_2a*b_over_2a - c_over_a`)
+  const disc = fma(bOver2a, bOver2a, -cOverA);
+  if (disc < 0) {
+    return 0;
+  } else if (disc > 0) {
+    roots[0] = -bOver2a + Math.sqrt(disc);
+    // clang -ffp-contract=on: fnmsub at solvers.c:85 (`-2*b_over_2a - roots[0]`)
+    roots[1] = fma(-2, bOver2a, -roots[0]);
+    return 2;
   }
+  roots[0] = -bOver2a;
+  return 1;
 }
 
-/** Solve cubic c[3]*x^3 + c[2]*x^2 + c[1]*x + c[0] = 0.
- *  Returns root count; 4 means all x satisfy. @see lib/pathplan/solvers.c:solve3 */
-export function solve3(coeff: number[], roots: number[]): number {
-  return Solver.solve3(coeff, roots);
+/** @see lib/pathplan/solvers.c:solve1 (no contraction) */
+function solve1(coeff: number[], roots: number[]): number {
+  const a = coeff[1], b = coeff[0];
+  if (aeq0(a)) {
+    if (aeq0(b)) return 4;
+    return 0;
+  }
+  roots[0] = -b / a;
+  return 1;
 }