@essrt/physics 1.0.0

package/src/layer0/index.js

@@ -0,0 +1,166 @@
+/**
+ * Layer 0 — epoch primitives. Pure `f(year)` → SI scalar.
+ *
+ * Imports NOTHING: not a sibling layer, not the constants module, not a Node
+ * builtin. Everything arrives through `createEpochPrimitives`. That is §2b and
+ * §2d of IP-unified-architecture.md, and it is what makes a counterfactual
+ * expressible — the one thing DE440 and Laskar cannot offer.
+ *
+ * ── ONE AXIS, BY MEASUREMENT ──────────────────────────────────────────────
+ * The API is `f(year)` (naming rule: the epoch parameter is a year). The
+ * internal cores work in t_Ma, converted once by `tMa()`. A second `t_Ma`
+ * entry axis was built and then REMOVED: the worry was that pre-migration
+ * callers holding a t_Ma would suffer `t → year → t` float wobble (1.9% of the
+ * domain fails that round-trip), but a 200k-point sweep found ZERO output-level
+ * differences — the chain's sensitivity (~20 s/Ma on LOD) times a 1-ULP wobble
+ * in t sits orders below the output ULP everywhere in ±495 Ma. The layer0
+ * identity gate pins that conclusion with harvested non-round-tripping t
+ * values, so a future chain steep enough to break it fails loudly.
+ *
+ * ── α IS INJECTED, AND THAT IS R2 ─────────────────────────────────────────
+ * `alphaAtAgeMa` is a parameter, not an import. The Earth moment-of-inertia
+ * factor rides on the climate L1 series, so hard-wiring it would drag the
+ * climate formula into Layer 0 — but the deeper reason is R2: when BUILDING an
+ * H-lattice table α must be held at its J2000 reference, or the lattice
+ * defines itself in terms of its own output. The browser gets this right today
+ * only by accident (a TDZ throw during table build); Node integrates the live
+ * α(t) and lands 141.6 d away at cycle 0. Making α an argument turns that
+ * accident into a decision the caller states out loud. R2 itself is a Phase C
+ * change — nothing here applies it.
+ */
+
+/**
+ * @typedef {Object} EpochParams
+ * @property {number} epochYear                  year at t_Ma = 0 (2000, NOT startmodelYear)
+ * @property {number} alpha1PerMa                Moon recession, LLR-anchored
+ * @property {number} alpha3PerMa3
+ * @property {number} alpha4PerMa4
+ * @property {number} moonDistanceNowM           a_Moon at J2000, metres
+ * @property {number} moonLockDistanceM          tidal-lock asymptote, metres
+ * @property {number} totalAngularMomentumKgM2S  L_tot of the Earth-Moon system
+ * @property {number} moonMassKg
+ * @property {number} gmEarthMoonM3S2
+ * @property {number} moonEccentricityFactor     sqrt(1 - e^2)
+ * @property {number} earthMassKg
+ * @property {number} earthRadiusM
+ * @property {number} holisticYearJ2000
+ * @property {number} lodNowH13Seconds
+ * @property {number} siderealYearJ2000Seconds
+ * @property {number} solarMassLossFracPerYear
+ */
+
+/**
+ * @typedef {Object} EpochPrimitives
+ * @property {(year: number) => number} tMa
+ * @property {(year: number) => number} moonDistanceMetres
+ * @property {(year: number) => number|null} lodSeconds
+ * @property {(year: number) => number|null} holisticH
+ * @property {(year: number) => number} siderealYearSeconds
+ * @property {(year: number) => number} tropicalYearSeconds
+ * @property {(year: number) => number|null} anomalisticYearSeconds
+ */
+
+/**
+ * @param {{params: EpochParams, alphaAtAgeMa: (tMa: number) => number}} deps
+ * @returns {EpochPrimitives}
+ */
+export const createEpochPrimitives = ({ params: p, alphaAtAgeMa }) => {
+  /**
+   * Years before the epoch, in Ma. The ONE place this conversion lives.
+   * @param {number} year
+   * @returns {number}
+   */
+  const tMa = (year) => (p.epochYear - year) / 1e6;
+
+  /**
+   * Moon semi-major axis. Cubic in t_Ma: alpha1 is LLR-anchored, alpha3/alpha4
+   * are the Farhat 2022 deep-time fit.
+   * @param {number} t age in Ma
+   * @returns {number} metres
+   */
+  const moonDistanceMetresCore = (t) =>
+    p.moonDistanceNowM
+      * (1 + p.alpha1PerMa * t + p.alpha3PerMa3 * t * t * t + p.alpha4PerMa4 * t * t * t * t);
+
+  /**
+   * Length of day from angular-momentum conservation: as the Moon recedes it
+   * takes orbital angular momentum and Earth's spin slows to compensate.
+   * @param {number} t age in Ma
+   * @returns {number|null} seconds; null past the tidal-lock asymptote
+   */
+  const lodSecondsCore = (t) => {
+    const a = moonDistanceMetresCore(t);
+    if (a <= 0 || a >= p.moonLockDistanceM) return null;
+    const iEarth = alphaAtAgeMa(t) * p.earthMassKg * p.earthRadiusM * p.earthRadiusM;
+    return (2 * Math.PI * iEarth)
+      / (p.totalAngularMomentumKgM2S
+         - p.moonMassKg * Math.sqrt(p.gmEarthMoonM3S2 * a) * p.moonEccentricityFactor);
+  };
+
+  /**
+   * The Earth Fundamental Cycle. H scales with LOD — the lattice is defined by
+   * the rotation rate, so a longer day is a longer H.
+   * @param {number} t age in Ma
+   * @returns {number|null} years
+   */
+  const holisticHCore = (t) => {
+    const lod = lodSecondsCore(t);
+    return lod === null ? null : p.holisticYearJ2000 * lod / p.lodNowH13Seconds;
+  };
+
+  /**
+   * Sidereal year. Driver 2 alone — solar mass loss via Kepler, `dT/T = -2 dM/M`
+   * under the adiabatic `a*M = const` coupling. Carries NO alpha and NO LOD,
+   * which is why attempt 1 used it as the clean probe for the mass-loss
+   * amplitude (measured 0.9964, i.e. 1.00).
+   * @param {number} t age in Ma
+   * @returns {number} seconds
+   */
+  const siderealYearSecondsCore = (t) => {
+    if (t === 0) return p.siderealYearJ2000Seconds;
+    return p.siderealYearJ2000Seconds * (1 - 2 * p.solarMassLossFracPerYear * t * 1e6);
+  };
+
+  /**
+   * Tropical year — sidereal less one axial-precession turn, H/13.
+   * Falls back to the J2000 H past the asymptote, matching the shipped chain.
+   * @param {number} t age in Ma
+   * @returns {number} seconds
+   */
+  const tropicalYearSecondsCore = (t) => {
+    const sid = siderealYearSecondsCore(t);
+    const H = holisticHCore(t);
+    return H === null ? sid * (1 - 13 / p.holisticYearJ2000) : sid * (1 - 13 / H);
+  };
+
+  /**
+   * Anomalistic year.
+   *
+   * NOT `T_sid * (1 + 3/H)`. That is the FIRST-ORDER form and the plan quotes
+   * it, but the shipped chain composes the lattice steps exactly: tropical is
+   * `(H-13)/H` of sidereal, then anomalistic is `H/(H-16)` of tropical, giving
+   * `T_sid * (H-13)/(H-16)`. The two differ by `48/H^2 * T_sid` ~ 13.5 ms —
+   * comparable to 6d's own 0.0178 s anomalistic RMSE, so adopting the
+   * first-order form would move a shipped value for no reason. Exact
+   * composition it is; the identity 13 + 3 = 16 still holds to first order.
+   *
+   * @param {number} t age in Ma
+   * @returns {number|null} seconds
+   */
+  const anomalisticYearSecondsCore = (t) => {
+    const H = holisticHCore(t);
+    if (H === null) return null;
+    const sid = siderealYearSecondsCore(t);
+    return sid * (H - 13) / H * H / (H - 16);
+  };
+
+  return Object.freeze({
+    tMa,
+    moonDistanceMetres: (year) => moonDistanceMetresCore(tMa(year)),
+    lodSeconds: (year) => lodSecondsCore(tMa(year)),
+    holisticH: (year) => holisticHCore(tMa(year)),
+    siderealYearSeconds: (year) => siderealYearSecondsCore(tMa(year)),
+    tropicalYearSeconds: (year) => tropicalYearSecondsCore(tMa(year)),
+    anomalisticYearSeconds: (year) => anomalisticYearSecondsCore(tMa(year)),
+  });
+};

package/src/layer1/index.js

@@ -0,0 +1,86 @@
+/**
+ * Layer 1 — derived views. Pure, composed only from Layer 0.
+ *
+ * The point of this layer is that TWO AXES DISAPPEAR (§2c):
+ *
+ *   "Kinematic" is not a code path. It is `f(2000)`.
+ *   "RealLOD"  is not a function variant. It is a division by `lodSeconds(Y)`.
+ *
+ * Everything here is a year length expressed in DAYS, and a day is
+ * `lodSeconds(Y)` — the epoch's own rotation period, not 86400 SI seconds. That
+ * distinction is not cosmetic: the CSV measures JD intervals (SI days) while the
+ * ESSRT chart is in real days, and detrending one against the other injects a
+ * 2590 s ramp. Unit in the name, always.
+ */
+
+/**
+ * @typedef {import('../layer0/index.js').EpochPrimitives} EpochPrimitives
+ */
+
+/**
+ * @typedef {Object} DerivedViews
+ * @property {(year: number) => number|null} tropicalYearDays
+ * @property {(year: number) => number|null} siderealYearDays
+ * @property {(year: number) => number|null} anomalisticYearDays
+ * @property {(year: number) => number|null} siderealYearDaysViaLattice
+ */
+
+/**
+ * @param {{primitives: EpochPrimitives}} deps
+ * @returns {DerivedViews}
+ */
+export const createDerivedViews = ({ primitives: L0 }) => {
+  /**
+   * Days per year at the epoch's own day length. `null` past tidal lock, which
+   * propagates rather than silently becoming Infinity.
+   * @param {(year: number) => number|null} seconds
+   * @returns {(year: number) => number|null}
+   */
+  const perDay = (seconds) => (year) => {
+    const s = seconds(year);
+    const lod = L0.lodSeconds(year);
+    return (s === null || lod === null || lod === 0) ? null : s / lod;
+  };
+
+  const tropicalYearDays = perDay(L0.tropicalYearSeconds);
+  const siderealYearDays = perDay(L0.siderealYearSeconds);
+  const anomalisticYearDays = perDay(L0.anomalisticYearSeconds);
+
+  /**
+   * The sidereal year in days, reached the long way — from the tropical year
+   * through the H/13 lattice identity instead of from sidereal seconds.
+   *
+   * ALGEBRAICALLY THE SAME NUMBER. `T_trop = T_sid·(H−13)/H`, so
+   * `(T_trop/LOD)·H/(H−13)` cancels to `T_sid/LOD` — but the operation ORDER
+   * differs, so it is not bit-identical everywhere. Measured across the fixture
+   * grid: identical at six of seven epochs, 0.7 ULP apart at +0.3 Ma. The
+   * browser shows exactly the same one-epoch split, which is how we know the
+   * port is faithful rather than merely close.
+   *
+   * It exists because `src/script.js` carries BOTH as separate mutable globals
+   * — `meansiderealyearlengthinDays` and `meansiderealyearlengthinDays_kinematic`
+   * — and they hold the same value at every epoch once `recomputeEpochAnchors`
+   * has run. They diverge only at module load, where one is the IAU anchor
+   * (365.256363004) and the other is lattice-derived: the 118 ms of R16.
+   *
+   * So the "kinematic" variant was never a different quantity, only a
+   * different arrival route with a different starting constant. Keeping the
+   * route explicit here lets B.3 retire one global without asserting the
+   * equality on faith.
+   *
+   * @param {number} year
+   * @returns {number|null}
+   */
+  const siderealYearDaysViaLattice = (year) => {
+    const trop = tropicalYearDays(year);
+    const H = L0.holisticH(year);
+    return (trop === null || H === null) ? null : trop * H / (H - 13);
+  };
+
+  return Object.freeze({
+    tropicalYearDays,
+    siderealYearDays,
+    anomalisticYearDays,
+    siderealYearDaysViaLattice,
+  });
+};

package/src/layer2/index.js

@@ -0,0 +1,6 @@
+/**
+ * Composites — cardinal points, earth, planets, moon, climate, deeptime. May use layer0 and layer1, never another layer2 module.
+ *
+ * PHASE 2 SKELETON — empty until the phase noted in IP-technical-design.md §6.
+ */
+export {};

package/src/moon/apparent.cjs

@@ -0,0 +1,153 @@
+/**
+ * Moon apparent position — THE shared implementation (Phase 8.2-7, the
+ * final lunar layer). The D5 derived optics + the post-hoc RA/Dec override:
+ *
+ *  - 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.
+ *
+ * S8 (obliquity source) stays ENGINE-INJECTED per call: the browser passes
+ * its live scene value (o.obliquityEarth, refreshed in updatePositions);
+ * the Node engine recomputes for the scene year. Equal when both describe
+ * the same year — a scene-state convention, not physics.
+ */
+
+'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).
+ */
+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
+   *  @returns {{raRad: number, decRad: number}} */
+  function overrideRaDec({ lonDeg, betRad, meeusT, 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;
+    }
+    return { raRad: newRA, decRad: newDec };
+  }
+
+  return { sunGeoVecEqD5, moonAberrationRaDec, overrideRaDec };
+}
+
+module.exports = { createMoonApparent };