@essrt/physics 7.0.0 → 8.0.0

package/src/moon/apparent.cjs

@@ -1,27 +1,37 @@
 /**
- * Moon apparent position — THE shared implementation (Phase 8.2-7, the
- * final lunar layer). The D5 derived optics + the post-hoc RA/Dec override:
+ * Moon scene position — the ecliptic → equatorial conversion of the series
+ * output, THE shared implementation (Phase 8.2-7). Since plan 06 R3 item 1 it
+ * is ONLY that conversion: the rendered Moon is the GEOMETRIC series Moon
+ * (moon/series.cjs sceneEvalAt, the derived extension inside), on the same
+ * convention as the rendered Sun and planets.
  *
- *  - sunGeoVecEqD5: framework-native geocentric Sun vector (equatorial km).
- *    e(T) from the anchored observed eccentricity + drift; EoC coefficients
- *    DERIVED from e via the Kepler series (2e − e³/4, (5/4)e², (13/12)e³ —
- *    the identity the D1 laboratory proved at 2 ppm); mean-longitude rate =
- *    framework tropical year; mean-anomaly rate = that minus the H/16
- *    perihelion rate; R from the AU distance; ε from the framework
- *    obliquity. One J2000 anchor: sunMeanLongitudeJ2000_deg.
- *  - moonAberrationRaDec: central-difference v_E/c annual aberration,
- *    SUBTRACTED (delta TO the aberration-removed direction u − v/c).
- *  - overrideRaDec: ecl→eq (Meeus eq. 13.3/13.4) on the series output,
- *    then framework-native analytic aberration + the small fitted residual
- *    (MOON_CORRECTION_RESIDUAL), or the legacy 3-argument fitted
- *    MOON_CORRECTION in pure-Meeus A/B mode.
- *
- * LOAD-BEARING: the correction patch's hard-coded linear arguments
- * (297.850 + 12.19074912·dJD, 134.963 + 13.06499295·dJD,
- * 357.529 + 0.98560028·dJD) are DELIBERATELY independent of the argument
- * skeleton — the fitted coefficients were produced against THIS form
- * (coefficients and runtime form are a matched pair). Do not "unify" them
- * with the args dispatcher.
+ * WHAT LEFT, and the measurement that retired it (record; the values stay in
+ * git history and docs/retired-record.md):
+ *  - the "D5 derived optics" — the annual aberration v_E/c applied to the
+ *    Moon's direction ("moonAberrationRaDec"). That operation turns the
+ *    geometric Moon into its ASTROMETRIC place (the body at emission time,
+ *    the observer's aberration not applied — Horizons quantity 1, a
+ *    star-chart convention 20″·cos D from both the geometric and the
+ *    apparent Moon). D5 had validated against exactly that reference and
+ *    so applied the REFERENCE'S convention to the RENDERED Moon. The scene
+ *    is an orrery of where the bodies are — geometric: Earth's shadow is
+ *    cast by the geometric Sun and the Moon enters it at its geometric
+ *    place — so the conversion belongs to the comparison instrument (the
+ *    pipeline verifier bridges it, tools/lib/optimizer.js), not to the
+ *    scene. Measured over 1970–2049: the bare series + extension against
+ *    Horizons' APPARENT Moon (≡ geometric − 0.7″ for a co-moving body)
+ *    −1.0″ ± 1.5″ flat in elongation; the D5-shifted rendered Moon +32.5″ +
+ *    20″·cos D against the same. (Plan 06 R3 scene conventions — the
+ *    earlier wording "wrong physics" over-reached: astrometric is a valid
+ *    convention, applied on the wrong side of the boundary.)
+ *  - the fitted RA/Dec patches MOON_CORRECTION (pure-Meeus A/B) and
+ *    MOON_CORRECTION_RESIDUAL (the post-D5 remainder, dominated by a −5.1″
+ *    raCosMp term): fitted around the layer above at syzygies; the series +
+ *    extension carry a ~1.3″ cos M′ structure against Horizons and no fitted
+ *    value replaces it.
+ *  - the fitted mean-longitude anchor moonMeeusLpCorrection (+32.75″, now 0,
+ *    model-parameters.json): the eclipse tier's mean Sun compensated (κ +
+ *    the I2 long inequality + the trend-ΔT offset), see eclipse/besselian.cjs.
  *
  * S8 (obliquity source) stays ENGINE-INJECTED per call: the browser passes
  * its live scene value (o.obliquityEarth, refreshed in updatePositions);
@@ -32,122 +42,31 @@
 'use strict';
 
 /**
- * @typedef {{raSinD: number, raCosD: number, raSinMp: number, raCosMp: number,
- *            raSinMs: number, raCosMs: number, decSinD: number, decCosD: number,
- *            decSinMp: number, decCosMp: number, decSinMs: number, decCosMs: number}} MoonCorrectionTable
- */
-
-/**
- * @param {{
- *   constants: {
- *     j2000JD: number,
- *     julianCenturyDays: number,
- *     sunMeanLongitudeJ2000Deg: number,
- *     perihelionLongitudeJ2000Deg: number,
- *     eccentricityJ2000: number,
- *     eccentricityDotJ2000: number,
- *     d5RateLDegPerDay: number,
- *     d5RatePeriDegPerDay: number,
- *     speedOfLight: number,
- *   },
- *   fns: {
- *     computeObliquityEarth: (year: number) => number,
- *     getAuDistanceKm: () => number,
- *     isFrameworkNative: () => boolean,
- *     getCorrectionResidual: () => (MoonCorrectionTable | null),
- *     getCorrectionLegacy: () => (MoonCorrectionTable | null),
- *   },
- * }} deps — the D5 rates are the engines' J2000-frozen values (the year
- *   globals are deep-time-mutable, same pattern as FW_A2_RATE); the AU
- *   distance is a GETTER (browser-mutable under deep time).
+ * No dependencies since R3 item 1 (the former D5 optics constants and the
+ * fitted-patch getters are gone); the factory shape is kept for the two
+ * scene twins' call sites.
+ * @param {object} [_deps] ignored
  */
-function createMoonApparent({ constants, fns }) {
-  const {
-    j2000JD, julianCenturyDays, sunMeanLongitudeJ2000Deg,
-    perihelionLongitudeJ2000Deg, eccentricityJ2000, eccentricityDotJ2000,
-    d5RateLDegPerDay, d5RatePeriDegPerDay, speedOfLight,
-  } = constants;
-  const {
-    computeObliquityEarth, getAuDistanceKm, isFrameworkNative,
-    getCorrectionResidual, getCorrectionLegacy,
-  } = fns;
-
-  /** Framework-native geocentric Sun vector, equatorial km.
-   *  @param {number} jd @returns {[number, number, number]} */
-  function sunGeoVecEqD5(jd) {
-    const T = (jd - j2000JD) / julianCenturyDays;
-    const d = jd - j2000JD;
-    const L0 = sunMeanLongitudeJ2000Deg + d5RateLDegPerDay * d;
-    const M = ((L0 - (perihelionLongitudeJ2000Deg + d5RatePeriDegPerDay * d)) + 180) * Math.PI / 180;  // geocentric-perigee convention (Sun perigee = Earth perihelion + 180°)
-    const e = eccentricityJ2000 + eccentricityDotJ2000 * T;
-    const Ceq = ((2 * e - Math.pow(e, 3) / 4) * Math.sin(M)
-              + 1.25 * e * e * Math.sin(2 * M)
-              + (13 / 12) * Math.pow(e, 3) * Math.sin(3 * M)) * 180 / Math.PI;    // deg (Kepler EoC series)
-    const lam = (L0 + Ceq) * Math.PI / 180;
-    const v = M + Ceq * Math.PI / 180;
-    const R = (1 - e * e) / (1 + e * Math.cos(v)) * getAuDistanceKm();
-    const eps = computeObliquityEarth(2000 + d / 365.2425) * Math.PI / 180;
-    return [R * Math.cos(lam), R * Math.sin(lam) * Math.cos(eps), R * Math.sin(lam) * Math.sin(eps)];
-  }
-
-  /** Annual-aberration delta (central difference, v_E/c SUBTRACTED).
-   *  @param {number} jd @param {number} ra @param {number} dec
-   *  @returns {{dRA: number, dDec: number}} */
-  function moonAberrationRaDec(jd, ra, dec) {
-    const h = 0.02;                                        // days (central difference)
-    const a = sunGeoVecEqD5(jd - h), b = sunGeoVecEqD5(jd + h);
-    const s = 1 / (2 * h * 86400 * speedOfLight);
-    const kx = -(b[0] - a[0]) * s, ky = -(b[1] - a[1]) * s, kz = -(b[2] - a[2]) * s;   // v_E/c
-    const cd = Math.cos(dec);
-    const ux = cd * Math.cos(ra), uy = cd * Math.sin(ra), uz = Math.sin(dec);
-    const wx = ux - kx, wy = uy - ky, wz = uz - kz;        // SUBTRACT the aberration content
-    const wr = Math.sqrt(wx * wx + wy * wy + wz * wz);
-    let dRA = Math.atan2(wy, wx) - ra;
-    dRA = Math.atan2(Math.sin(dRA), Math.cos(dRA));
-    return { dRA, dDec: Math.asin(Math.max(-1, Math.min(1, wz / wr))) - dec };
-  }
-
-  /** The post-hoc RA/Dec override on the series output. Returns EQUATORIAL
-   *  radians — the engines own their scene storage conventions (the browser
-   *  stores dec as π/2 − dec, phi form).
-   *  @param {{lonDeg: number, betRad: number, meeusT: (number | undefined), obliquityDeg: number}} p
+function createMoonApparent(_deps) {
+  /** The RA/Dec of the series output — ecliptic → equatorial (Meeus eq. 13.3,
+   *  13.4) on the injected obliquity. Returns EQUATORIAL radians — the engines
+   *  own their scene storage conventions (the browser stores dec as π/2 − dec,
+   *  phi form). `meeusT` is accepted for call-site stability and unused.
+   *  @param {{lonDeg: number, betRad: number, meeusT?: (number | undefined), obliquityDeg: number}} p
    *  @returns {{raRad: number, decRad: number}} */
-  function overrideRaDec({ lonDeg, betRad, meeusT, obliquityDeg }) {
+  function overrideRaDec({ lonDeg, betRad, obliquityDeg }) {
     const eps = obliquityDeg * (Math.PI / 180);
     const cosE = Math.cos(eps), sinE = Math.sin(eps);
     const lamR = lonDeg * (Math.PI / 180);
     const sinLam = Math.sin(lamR), cosLam = Math.cos(lamR);
     const sinBet = Math.sin(betRad), cosBet = Math.cos(betRad);
-
-    // Ecliptic → equatorial (Meeus eq. 13.3, 13.4)
     let newRA = Math.atan2(sinLam * cosE - Math.tan(betRad) * sinE, cosLam);
     if (newRA < 0) newRA += 2 * Math.PI;
-    let newDec = Math.asin(sinBet * cosE + cosBet * sinE * sinLam);
-
-    if (isFrameworkNative()) {
-      const ab = moonAberrationRaDec(j2000JD + (meeusT || 0) * julianCenturyDays, newRA, newDec);
-      newRA += ab.dRA;
-      newDec += ab.dDec;
-    }
-    const mc = isFrameworkNative() ? getCorrectionResidual() : getCorrectionLegacy();
-    if (mc) {
-      const d2r = Math.PI / 180;
-      const dJD = (meeusT || 0) * julianCenturyDays;
-      // MATCHED-PAIR arguments — fitted against these exact linear forms.
-      const Dc = (297.850 + 12.19074912 * dJD) * d2r;
-      const Mpc = (134.963 + 13.06499295 * dJD) * d2r;
-      const Msc = (357.529 + 0.98560028 * dJD) * d2r;
-      newRA -= (mc.raSinD * Math.sin(Dc) + mc.raCosD * Math.cos(Dc)
-              + mc.raSinMp * Math.sin(Mpc) + mc.raCosMp * Math.cos(Mpc)
-              + mc.raSinMs * Math.sin(Msc) + mc.raCosMs * Math.cos(Msc)) * d2r;
-      newDec -= (mc.decSinD * Math.sin(Dc) + mc.decCosD * Math.cos(Dc)
-              + mc.decSinMp * Math.sin(Mpc) + mc.decCosMp * Math.cos(Mpc)
-              + mc.decSinMs * Math.sin(Msc) + mc.decCosMs * Math.cos(Msc)) * d2r;
-    }
+    const newDec = Math.asin(sinBet * cosE + cosBet * sinE * sinLam);
     return { raRad: newRA, decRad: newDec };
   }
 
-  return { sunGeoVecEqD5, moonAberrationRaDec, overrideRaDec };
+  return { overrideRaDec };
 }
 
 module.exports = { createMoonApparent };

package/src/moon/series-extension.cjs

@@ -52,7 +52,8 @@
  * A1-class correlated-subsample effect (the tracked events sit −1.6″
  * below the +1.4″ fleet mean and sample the near-annual arguments at
  * correlated phases; the era-split refutes anchor double-counting and
- * the modern era improves most, 3.57 → 3.34). The ≤8″ api gate holds
+ * the modern era improves most, 3.57 → 3.34). The api gate (8″ then; 12″
+ * since plan 06 R3 item 1 — the physical ΔT-convention floor) holds
  * (max 6.2″). Coefficients are stored with the run→real argument
  * mapping already applied (the extraction's heliocentric-planet vs
  * geocentric-sun π-offset is folded into the signs).

package/src/moon/series.cjs

@@ -26,6 +26,13 @@
 
 'use strict';
 
+// Plan 06 R3 item 1: the DERIVED series-extension tail (the D2 planetary and
+// node terms, moon/series-extension.cjs) is part of the ONE scene Moon —
+// formerly added by the besselian tier alone, so the rendered Moon and the
+// eclipse-location Moon were two different Moons. The truncated finder forms
+// below stay bare by certified design.
+const { moonSeriesExtensionDeg } = require('./series-extension.cjs');
+
 /**
  * @typedef {Array<[number, number, number, number, number]>} MeeusTermTable
  */
@@ -164,10 +171,17 @@ function createMoonSeries({ constants, fns }) {
    *  owns the UT→TT conversion — engine timing conventions differ).
    *  Returns everything the scene blocks write:
    *  thetaAddRad — the hierarchy θ increment (EoC-half-subtracted Σl);
-   *  lonDeg — full ecliptic longitude incl. moonMeeusLpCorrection;
-   *  latRad/latDeg — Σb with all six corrections (BOTH computed from Σb
-   *  directly: the browser stores radians, the Node engine degrees, and
-   *  (x·D2R)/D2R is not bit-exactly x); distKm — two-term ellipse; T.
+   *  lonDeg — full ecliptic longitude (GEOMETRIC, mean equinox of date)
+   *  incl. the derived series-extension tail and moonMeeusLpCorrection
+   *  (retired to 0 at plan 06 R3 item 1: measured against Horizons' apparent
+   *  Moon over 1970–2049 the series needs no anchor, −1.0″ ± 1.5″ flat in
+   *  elongation; the former +32.75″ was the eclipse tier's mean Sun
+   *  compensated — its aberration κ, the I2 long inequality and the trend-ΔT
+   *  offset — not a property of the Moon);
+   *  latRad/latDeg — Σb with all six corrections plus the extension (BOTH
+   *  computed from Σb directly: the browser stores radians, the Node engine
+   *  degrees, and (x·D2R)/D2R is not bit-exactly x); distKm — two-term
+   *  ellipse; T.
    *  @param {number} dDaysTT
    *  @returns {{thetaAddRad: number, lonDeg: number, latRad: number, latDeg: number, distKm: number, T: number}} */
   function sceneEvalAt(dDaysTT) {
@@ -180,9 +194,11 @@ function createMoonSeries({ constants, fns }) {
     const E = eFactorForD(d, T, T2);
     const E2 = E * E;
     const { A1, A2, A3 } = additionalArgs(T, d);
+    const ext = moonSeriesExtensionDeg(T);   // derived tail, degrees → the tables' 1e-6° units
 
     let Sl = sumTable(moonL, Dr, Mr, Mpr, Fr, E, E2);
     Sl += 3958 * Math.sin(A1) + 1962 * Math.sin(Lp - Fr) + 318 * Math.sin(A2);
+    Sl += ext.dLonDeg * 1e6;
     // Subtract the EoC portion the off-centre orbit geometry already provides.
     const eocHalf = getEccentricityBase() / 2;
     Sl -= (2 * eocHalf / D2R * 1e6) * Math.sin(Mpr);
@@ -193,6 +209,7 @@ function createMoonSeries({ constants, fns }) {
     Sb += -2235 * Math.sin(Lp) + 382 * Math.sin(A3);
     Sb += 175 * Math.sin(A1 - Fr) + 175 * Math.sin(A1 + Fr);
     Sb += 127 * Math.sin(Lp - Mpr) - 115 * Math.sin(Lp + Mpr);
+    Sb += ext.dLatDeg * 1e6;
     const latRad = Sb * 1e-6 * D2R;
     const latDeg = Sb * 1e-6;