@essrt/physics 23.6.0 → 24.1.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@essrt/physics",
-  "version": "23.6.0",
+  "version": "24.1.0",
   "description": "ESSRT (Expanding Solar System Resonance Theory) physics core — pure, injectable-constants, no I/O, no globals, no DOM. The complete model incl. fitted coefficients; every published version immutably ships one recorded model identity.",
   "essrt": {
-    "modelVersion": "v26.5",
+    "modelVersion": "v26.7",
     "_note": "The model identity this package version ships (IP-unified-architecture §10: package semver tracks the API axis; the model version + CONSTANTS_HASH/COEFFICIENTS_HASH in src/constants/ carry the scientific identity). The version-pinning gate enforces this pairing against public/input/model-version.json."
   },
   "type": "module",

package/src/cardinal/one-source-structure.cjs

@@ -40,6 +40,8 @@
  * like createDeepOrbitalHistory injects its surfaces.
  */
 
+const { wrap180 } = require('../math/angles.cjs');
+
 const D2R = Math.PI / 180;
 
 /** Cardinal longitudes, equinox of date. @type {Record<string, number>} */
@@ -134,7 +136,7 @@ function createCardinalStructure({ sampleAt, tropicalYearSecondsAtYearFn }) {
   function anomalisticYearSeconds(year) {
     const p0 = sampleAt(year).periOfDateDeg;
     const p1 = sampleAt(year + 1).periOfDateDeg;
-    const dPeriDeg = ((p1 - p0 + 540) % 360) - 180;   // wrapped, prograde +
+    const dPeriDeg = wrap180(p1 - p0);   // wrapped, prograde + (math/angles; a one-year step, far below 180°)
     return tropicalYearSecondsAtYearFn(year + 0.5) * 360 / (360 - dPeriDeg);
   }
 

package/src/chain-cycles/index.cjs

@@ -26,11 +26,18 @@
  *    tableAnchorYear vs driftRefYear pair).
  *
  * NUMERICS ARE LOAD-BEARING: fixed 10-yr grid over ±250 kyr, per-cell
- * 3-point Simpson at build, LINEAR interpolation on read; adaptive Simpson
- * (~1 sample/kyr, n ∈ [32, 1024], even) as the out-of-range fallback. The
- * table replaced the per-call Simpson for in-range spans (the L-4
- * 92 s/century full-canon regression); an "analytically better" integrator
- * here would detach the runtime from the certified numbers.
+ * 3-point Simpson at build, LINEAR interpolation on read; beyond the dense
+ * grid a COARSE cumulative table (1-kyr cells, the same per-cell Simpson,
+ * anchored at the dense edge) grown lazily in 250-kyr chunks in the direction
+ * asked for — the owner's playback at 1,000 yr/s past year 250,000 had fallen
+ * to 190 ms of JS per frame: the former fallback, an adaptive Simpson of up to
+ * 1,024 samples per call cached by exact year pair, re-integrated every one
+ * of the four Moon chains from the grid edge on every frame, each sample a
+ * deep-time LOD/α evaluation. The adaptive Simpson remains only for a chain
+ * undefined somewhere in range (null) or beyond the coarse limit (±600 Myr,
+ * past the model's domain). An "analytically better" integrator here would
+ * detach the runtime from the certified numbers: the in-range path is
+ * byte-identical to before.
  */
 
 'use strict';
@@ -125,6 +132,62 @@ function createChainCycleIntegrator({
     return tab[i] + (idxF - i) * (tab[i + 1] - tab[i]);
   }
 
+  // ── The coarse extension beyond the dense grid ─────────────────────────────
+  // Per chain and per direction, a cumulative table in COARSE_STEP cells that
+  // starts at the dense edge with the edge's own value and grows by COARSE_CHUNK
+  // years whenever a year beyond its reach is asked for. The cells are built
+  // with the same 3-point Simpson as the dense grid; the read is the same
+  // linear interpolation. The period laws vary on Myr scales at deep time, so
+  // 1-kyr cells hold the count to far below a cycle — the old fallback sampled
+  // ~1 per kyr too, but re-did the whole span on every call.
+  const COARSE_STEP = 1000, COARSE_CHUNK = 250000, COARSE_LIMIT_YEARS = 600e6;
+  /** @typedef {{ cum: number[], ok: boolean }} CoarseSide */
+  /** @type {WeakMap<PeriodSecondsAtAge, { fwd: CoarseSide, bwd: CoarseSide }>} */
+  const coarse = new WeakMap();
+  /** @param {PeriodSecondsAtAge} periodFnSeconds @param {number} y @returns {number | null} cycles per tick */
+  const integrandAt = (periodFnSeconds, y) => {
+    const tPeriodS = periodFnSeconds((ageAnchorYear - y) / 1e6);
+    return tPeriodS === null ? null : tropicalYearJ2000Seconds / tPeriodS;
+  };
+  /** Grow one side until it covers `distance` years from the dense edge (or fails on a null chain).
+   *  @param {PeriodSecondsAtAge} periodFnSeconds @param {CoarseSide} side @param {number} edgeYear
+   *  @param {1|-1} dir @param {number} distance */
+  function growCoarse(periodFnSeconds, side, edgeYear, dir, distance) {
+    const need = Math.ceil(distance / COARSE_STEP) + 1;
+    let target = side.cum.length;
+    while (target < need) target += COARSE_CHUNK / COARSE_STEP;
+    for (let i = side.cum.length; i < target && side.ok; i++) {
+      const y0 = edgeYear + dir * (i - 1) * COARSE_STEP, y1 = y0 + dir * COARSE_STEP;
+      const f0 = integrandAt(periodFnSeconds, y0), fm = integrandAt(periodFnSeconds, (y0 + y1) / 2), f1 = integrandAt(periodFnSeconds, y1);
+      if (f0 === null || fm === null || f1 === null) { side.ok = false; break; }
+      side.cum.push(side.cum[i - 1] + dir * (f0 + 4 * fm + f1) * (COARSE_STEP / 6));
+    }
+  }
+  /** C(y) beyond the dense grid, or null when the chain is undefined on the way there.
+   *  @param {PeriodSecondsAtAge} periodFnSeconds @param {Float64Array} tab @param {number} y @returns {number | null} */
+  function coarseAt(periodFnSeconds, tab, y) {
+    let c = coarse.get(periodFnSeconds);
+    if (!c) {
+      c = { fwd: { cum: [tab[tab.length - 1]], ok: true }, bwd: { cum: [tab[0]], ok: true } };
+      coarse.set(periodFnSeconds, c);
+    }
+    const dir = y >= gridMaxYear ? 1 : -1;
+    const side = dir === 1 ? c.fwd : c.bwd;
+    const edgeYear = dir === 1 ? gridMaxYear : gridMinYear;
+    const distance = Math.abs(y - edgeYear);
+    if (distance > COARSE_LIMIT_YEARS) return null;
+    if (side.cum.length < Math.ceil(distance / COARSE_STEP) + 1) growCoarse(periodFnSeconds, side, edgeYear, dir, distance);
+    if (!side.ok || side.cum.length < Math.ceil(distance / COARSE_STEP) + 1) return null;
+    const idxF = distance / COARSE_STEP;
+    const i = Math.floor(idxF);
+    return side.cum[i] + (idxF - i) * (side.cum[i + 1] - side.cum[i]);
+  }
+  /** C(y) anywhere the tables reach: dense inside the grid, coarse beyond.
+   *  @param {PeriodSecondsAtAge} periodFnSeconds @param {Float64Array} tab @param {number} y @returns {number | null} */
+  function cumulativeAt(periodFnSeconds, tab, y) {
+    return (y > gridMinYear && y < gridMaxYear) ? tableAt(tab, y) : coarseAt(periodFnSeconds, tab, y);
+  }
+
   /** Cycles of the chain between two calendar years. Snapshot mode: linear
    *  at the J2000 rate. Deep time: table lookup in ±range, adaptive Simpson
    *  beyond. null past the tidal-lock asymptote.
@@ -147,10 +210,16 @@ function createChainCycleIntegrator({
       return dy * tropicalYearJ2000Seconds / tJ2000;
     }
 
-    // Cumulative-table fast path (deterministic, call-order independent)
-    if (yearA > gridMinYear && yearA < gridMaxYear && yearB > gridMinYear && yearB < gridMaxYear) {
-      const tab = table(periodFnSeconds);
-      if (tab !== null) return tableAt(tab, yearB) - tableAt(tab, yearA);
+    // Cumulative-table fast path (deterministic, call-order independent): the
+    // dense grid inside ±250 kyr — byte-identical to before — and the lazily
+    // grown coarse extension beyond it.
+    const tab = table(periodFnSeconds);
+    if (tab !== null) {
+      if (yearA > gridMinYear && yearA < gridMaxYear && yearB > gridMinYear && yearB < gridMaxYear) {
+        return tableAt(tab, yearB) - tableAt(tab, yearA);
+      }
+      const cA = cumulativeAt(periodFnSeconds, tab, yearA), cB = cumulativeAt(periodFnSeconds, tab, yearB);
+      if (cA !== null && cB !== null) return cB - cA;
     }
 
     let cache = caches.get(periodFnSeconds);
@@ -162,7 +231,8 @@ function createChainCycleIntegrator({
     const hit = cache.get(cacheKey);
     if (hit !== undefined) return hit;
 
-    // Adaptive Simpson: ~1 sample per 1 kyr, capped at 1024 to bound per-call cost.
+    // Adaptive Simpson (a chain undefined in range, or beyond the coarse limit):
+    // ~1 sample per 1 kyr, capped at 1024 to bound per-call cost.
     let n = Math.max(32, Math.ceil(Math.abs(dy) / 1000));
     if (n > 1024) n = 1024;
     if (n % 2 === 1) n++;

package/src/constants/generated.d.ts

@@ -2,17 +2,17 @@
 // Gives the TypeScript website full type safety at the boundary (§2g) while
 // packages/physics stays JavaScript.
 
-export declare const CONSTANTS_HASH: "320c51865d620009";
+export declare const CONSTANTS_HASH: "da713fc2d846767d";
 
 export declare const MODEL_VERSION: string;
 
 export declare const PREPRINT_DOI: string;
 
 export declare const DEFAULT_CONSTANTS: {
-  readonly hash: "320c51865d620009";
+  readonly hash: "da713fc2d846767d";
   readonly additionalBodiesReference: {
     "pluto": {
-      "solarYearInput": number;
+      "orbitalPeriodInputDays": number;
       "orbitalEccentricityJ2000": number;
       "eclipticInclinationJ2000": number;
       "invPlaneInclinationJ2000": number;
@@ -25,7 +25,7 @@ export declare const DEFAULT_CONSTANTS: {
       "ascendingNodeInvPlaneClosedForm": number;
     };
     "halleys": {
-      "solarYearInput": number;
+      "orbitalPeriodInputDays": number;
       "orbitalEccentricityJ2000": number;
       "eclipticInclinationJ2000": number;
       "invPlaneInclinationJ2000": number;
@@ -37,7 +37,7 @@ export declare const DEFAULT_CONSTANTS: {
       "rotationPeriodDays": number;
     };
     "eros": {
-      "solarYearInput": number;
+      "orbitalPeriodInputDays": number;
       "orbitalEccentricityJ2000": number;
       "eclipticInclinationJ2000": number;
       "invPlaneInclinationJ2000": number;
@@ -49,7 +49,7 @@ export declare const DEFAULT_CONSTANTS: {
       "rotationPeriodDays": number;
     };
     "ceres": {
-      "solarYearInput": number;
+      "orbitalPeriodInputDays": number;
       "orbitalEccentricityJ2000": number;
       "eclipticInclinationJ2000": number;
       "invPlaneInclinationJ2000": number;
@@ -200,7 +200,7 @@ export declare const DEFAULT_CONSTANTS: {
   };
   readonly planetOrbitalElements: {
     "mercury": {
-      "solarYearInput": number;
+      "orbitalPeriodInputDays": number;
       "orbitalEccentricityJ2000": number;
       "axialTiltJ2000": number;
       "eclipticInclinationJ2000": number;
@@ -212,7 +212,7 @@ export declare const DEFAULT_CONSTANTS: {
       "ascendingNodeInvPlaneClosedForm": number;
     };
     "venus": {
-      "solarYearInput": number;
+      "orbitalPeriodInputDays": number;
       "orbitalEccentricityJ2000": number;
       "axialTiltJ2000": number;
       "eclipticInclinationJ2000": number;
@@ -225,7 +225,7 @@ export declare const DEFAULT_CONSTANTS: {
       "ascendingNodeInvPlaneClosedForm": number;
     };
     "mars": {
-      "solarYearInput": number;
+      "orbitalPeriodInputDays": number;
       "orbitalEccentricityJ2000": number;
       "axialTiltJ2000": number;
       "eclipticInclinationJ2000": number;
@@ -238,7 +238,7 @@ export declare const DEFAULT_CONSTANTS: {
       "ascendingNodeInvPlaneClosedForm": number;
     };
     "jupiter": {
-      "solarYearInput": number;
+      "orbitalPeriodInputDays": number;
       "orbitalEccentricityJ2000": number;
       "axialTiltJ2000": number;
       "eclipticInclinationJ2000": number;
@@ -251,7 +251,7 @@ export declare const DEFAULT_CONSTANTS: {
       "ascendingNodeInvPlaneClosedForm": number;
     };
     "saturn": {
-      "solarYearInput": number;
+      "orbitalPeriodInputDays": number;
       "orbitalEccentricityJ2000": number;
       "axialTiltJ2000": number;
       "eclipticInclinationJ2000": number;
@@ -264,7 +264,7 @@ export declare const DEFAULT_CONSTANTS: {
       "ascendingNodeInvPlaneClosedForm": number;
     };
     "uranus": {
-      "solarYearInput": number;
+      "orbitalPeriodInputDays": number;
       "orbitalEccentricityJ2000": number;
       "axialTiltJ2000": number;
       "eclipticInclinationJ2000": number;
@@ -277,7 +277,7 @@ export declare const DEFAULT_CONSTANTS: {
       "ascendingNodeInvPlaneClosedForm": number;
     };
     "neptune": {
-      "solarYearInput": number;
+      "orbitalPeriodInputDays": number;
       "orbitalEccentricityJ2000": number;
       "axialTiltJ2000": number;
       "eclipticInclinationJ2000": number;

package/src/constants/generated.js

@@ -36,20 +36,20 @@
  * carry it so a counterfactual is reproducible (§2d).
  * @type {string}
  */
-export const CONSTANTS_HASH = "320c51865d620009";
+export const CONSTANTS_HASH = "da713fc2d846767d";
 
 /** Model version label — single source: public/input/model-version.json (§10 two-axis scheme). */
-export const MODEL_VERSION = "v26.5";
+export const MODEL_VERSION = "v26.7";
 
 /** Canonical preprint DOI — single source: public/input/model-version.json. */
 export const PREPRINT_DOI = "10.21203/rs.3.rs-8758810/v4";
 
 /** @type {Readonly<Record<string, unknown>>} */
 export const DEFAULT_CONSTANTS = Object.freeze({
-  hash: "320c51865d620009",
+  hash: "da713fc2d846767d",
   additionalBodiesReference: {
     "pluto": {
-      "solarYearInput": 90465,
+      "orbitalPeriodInputDays": 90465,
       "orbitalEccentricityJ2000": 0.2488273,
       "eclipticInclinationJ2000": 17.14001,
       "invPlaneInclinationJ2000": 15.5639473,
@@ -62,7 +62,7 @@ export const DEFAULT_CONSTANTS = Object.freeze({
       "ascendingNodeInvPlaneClosedForm": 101.06
     },
     "halleys": {
-      "solarYearInput": 27503,
+      "orbitalPeriodInputDays": 27503,
       "orbitalEccentricityJ2000": 0.96714291,
       "eclipticInclinationJ2000": 162.26269,
       "invPlaneInclinationJ2000": 150,
@@ -74,7 +74,7 @@ export const DEFAULT_CONSTANTS = Object.freeze({
       "rotationPeriodDays": 2.2
     },
     "eros": {
-      "solarYearInput": 642.93,
+      "orbitalPeriodInputDays": 642.93,
       "orbitalEccentricityJ2000": 0.2229512,
       "eclipticInclinationJ2000": 10.8276,
       "invPlaneInclinationJ2000": 9.25,
@@ -86,7 +86,7 @@ export const DEFAULT_CONSTANTS = Object.freeze({
       "rotationPeriodDays": 0.21958333344885
     },
     "ceres": {
-      "solarYearInput": 1680.5,
+      "orbitalPeriodInputDays": 1680.5,
       "orbitalEccentricityJ2000": 0.0755347,
       "eclipticInclinationJ2000": 10.59407,
       "invPlaneInclinationJ2000": 0.4331698,
@@ -237,7 +237,7 @@ export const DEFAULT_CONSTANTS = Object.freeze({
   },
   planetOrbitalElements: {
     "mercury": {
-      "solarYearInput": 87.9683,
+      "orbitalPeriodInputDays": 87.9683,
       "orbitalEccentricityJ2000": 0.20563593,
       "axialTiltJ2000": 0.03,
       "eclipticInclinationJ2000": 7.00497902,
@@ -249,7 +249,7 @@ export const DEFAULT_CONSTANTS = Object.freeze({
       "ascendingNodeInvPlaneClosedForm": 32.83
     },
     "venus": {
-      "solarYearInput": 224.695,
+      "orbitalPeriodInputDays": 224.695,
       "orbitalEccentricityJ2000": 0.00677672,
       "axialTiltJ2000": 2.6392,
       "eclipticInclinationJ2000": 3.39467605,
@@ -262,7 +262,7 @@ export const DEFAULT_CONSTANTS = Object.freeze({
       "ascendingNodeInvPlaneClosedForm": 54.7
     },
     "mars": {
-      "solarYearInput": 686.93,
+      "orbitalPeriodInputDays": 686.93,
       "orbitalEccentricityJ2000": 0.0933941,
       "axialTiltJ2000": 25.19,
       "eclipticInclinationJ2000": 1.84969142,
@@ -275,7 +275,7 @@ export const DEFAULT_CONSTANTS = Object.freeze({
       "ascendingNodeInvPlaneClosedForm": 354.87
     },
     "jupiter": {
-      "solarYearInput": 4330.53,
+      "orbitalPeriodInputDays": 4330.53,
       "orbitalEccentricityJ2000": 0.04838624,
       "axialTiltJ2000": 3.13,
       "eclipticInclinationJ2000": 1.30439695,
@@ -288,7 +288,7 @@ export const DEFAULT_CONSTANTS = Object.freeze({
       "ascendingNodeInvPlaneClosedForm": 312.89
     },
     "saturn": {
-      "solarYearInput": 10747,
+      "orbitalPeriodInputDays": 10747,
       "orbitalEccentricityJ2000": 0.05386179,
       "axialTiltJ2000": 26.73,
       "eclipticInclinationJ2000": 2.48599187,
@@ -301,7 +301,7 @@ export const DEFAULT_CONSTANTS = Object.freeze({
       "ascendingNodeInvPlaneClosedForm": 118.81
     },
     "uranus": {
-      "solarYearInput": 30586,
+      "orbitalPeriodInputDays": 30586,
       "orbitalEccentricityJ2000": 0.04725744,
       "axialTiltJ2000": 82.23,
       "eclipticInclinationJ2000": 0.77263783,
@@ -314,7 +314,7 @@ export const DEFAULT_CONSTANTS = Object.freeze({
       "ascendingNodeInvPlaneClosedForm": 307.8
     },
     "neptune": {
-      "solarYearInput": 59800,
+      "orbitalPeriodInputDays": 59800,
       "orbitalEccentricityJ2000": 0.00859048,
       "axialTiltJ2000": 28.32,
       "eclipticInclinationJ2000": 1.77004347,

package/src/earth/deep-orbital-history.cjs

@@ -30,6 +30,49 @@
 
 'use strict';
 
+/**
+ * The CO-ROTATING anchored mode sum — the z-side evaluator of the history
+ * (the ϖ̇ fix, measured): the plain DC anchor residual is a spurious
+ * zero-frequency mode that preserves the J2000 VALUE but dilutes the local
+ * argument rate by |sum(0)|/|anchor| (z: 11.47 → 7.93″/yr, a 92 s-class
+ * anomalistic-year bias in the mode tier). Here the residual ROTATES at the
+ * raw sum's own local arg-rate g* = Im(ż·z̄)/|z|² (analytic), so at t = 0
+ * both the value AND the rate are exact, and at depth the residual is one
+ * |R|-amplitude term at a physical frequency instead of a DC offset (deep
+ * envelope measured unchanged: [0.0001, 0.0672] → [0.0003, 0.0678] over
+ * 10–50 Myr). Exported: e(t) = hypot(sum(t)) needs no spin integration,
+ * so a fixture can read a deep eccentricity node here (bit-identical at the
+ * grid nodes; the published surface is the grid's linear interpolation and
+ * stays on the history).
+ * @param {ReadonlyArray<{omegaRadPerYr: number, re: number, im: number}>} modes
+ * @param {[number, number]} anchor the J2000 value (q, p) the sum is pinned to
+ * @returns {(t: number) => [number, number]} t in years from J2000
+ */
+function createCoRotatingAnchoredModeSum(modes, anchor) {
+  const sum = (/** @type {number} */ t) => {
+    let re = 0, im = 0;
+    for (const m of modes) {
+      const c = Math.cos(m.omegaRadPerYr * t), s = Math.sin(m.omegaRadPerYr * t);
+      re += m.re * c - m.im * s;
+      im += m.re * s + m.im * c;
+    }
+    return [re, im];
+  };
+  let q0 = 0, p0 = 0, dq0 = 0, dp0 = 0;
+  for (const m of modes) {
+    q0 += m.re; p0 += m.im;
+    dq0 += -m.omegaRadPerYr * m.im;
+    dp0 += m.omegaRadPerYr * m.re;
+  }
+  const gStar = (dp0 * q0 - dq0 * p0) / (q0 * q0 + p0 * p0);
+  const R = [anchor[0] - q0, anchor[1] - p0];
+  return (/** @type {number} */ t) => {
+    const [x, y] = sum(t);
+    const c = Math.cos(gStar * t), s = Math.sin(gStar * t);
+    return [x + R[0] * c - R[1] * s, y + R[0] * s + R[1] * c];
+  };
+}
+
 /**
  * @param {{
  *   zModes: ReadonlyArray<{omegaRadPerYr: number, re: number, im: number}>,
@@ -97,43 +140,14 @@ function createDeepOrbitalHistory({
   // CO-ROTATING anchor (the ϖ̇ fix, measured): the DC residual above is a
   // spurious zero-frequency mode — it preserves the J2000 VALUE but dilutes
   // the local argument rate by |sum(0)|/|anchor| (z: 11.47 → 7.93″/yr, a
-  // 92 s-class anomalistic-year bias in the mode tier). Here the residual
-  // ROTATES at the raw sum's own local arg-rate g* = Im(ż·z̄)/|z|²
-  // (analytic), so at t=0 both the value AND the rate are exact, and at
-  // depth the residual is one |R|-amplitude term at a physical frequency
-  // instead of a DC offset (deep envelope measured unchanged:
-  // [0.0001, 0.0672] → [0.0003, 0.0678] over 10–50 Myr).
+  // 92 s-class anomalistic-year bias in the mode tier). The co-rotating form
+  // is the module-level createCoRotatingAnchoredModeSum (exported — the
+  // plan-06 fixture reads the deep eccentricity from it directly).
   // z ONLY: ζ keeps the DC anchor DELIBERATELY — its anchor is ~0 by
   // definition (Earth's inclination to the J2000 ecliptic at J2000), i.e.
   // the coordinate origin; a rotating residual there would inject a fake
   // wobble into n̂(t).
-  const mkAnchoredCoRot = (
-    /** @type {ReadonlyArray<{omegaRadPerYr: number, re: number, im: number}>} */ modes,
-    /** @type {[number, number]} */ anchor,
-  ) => {
-    const sum = (/** @type {number} */ t) => {
-      let re = 0, im = 0;
-      for (const m of modes) {
-        const c = Math.cos(m.omegaRadPerYr * t), s = Math.sin(m.omegaRadPerYr * t);
-        re += m.re * c - m.im * s;
-        im += m.re * s + m.im * c;
-      }
-      return [re, im];
-    };
-    let q0 = 0, p0 = 0, dq0 = 0, dp0 = 0;
-    for (const m of modes) {
-      q0 += m.re; p0 += m.im;
-      dq0 += -m.omegaRadPerYr * m.im;
-      dp0 += m.omegaRadPerYr * m.re;
-    }
-    const gStar = (dp0 * q0 - dq0 * p0) / (q0 * q0 + p0 * p0);
-    const R = [anchor[0] - q0, anchor[1] - p0];
-    return (/** @type {number} */ t) => {
-      const [x, y] = sum(t);
-      const c = Math.cos(gStar * t), s = Math.sin(gStar * t);
-      return [x + R[0] * c - R[1] * s, y + R[0] * s + R[1] * c];
-    };
-  };
+  const mkAnchoredCoRot = createCoRotatingAnchoredModeSum;
   const s2h = Math.sin(anchorInclEclipticDeg / 2 * D2R);
   const zetaAnchor = /** @type {[number, number]} */ (
     [s2h * Math.cos(anchorAscNodeEclipticDeg * D2R), s2h * Math.sin(anchorAscNodeEclipticDeg * D2R)]);
@@ -676,4 +690,4 @@ function createDeepOrbitalHistory({
   };
 }
 
-module.exports = { createDeepOrbitalHistory };
+module.exports = { createDeepOrbitalHistory, createCoRotatingAnchoredModeSum };

package/src/earth/year-lengths.cjs

@@ -42,6 +42,7 @@
 //   • The frozen era clock stays the certified era device (opt-out /
 //     era-certification record), not a member of this family.
 
+const { wrap180 } = require('../math/angles.cjs');
 const { createCardinalStructure } = require('../cardinal/one-source-structure.cjs');
 const { createSiderealYearChannel } = require('./sidereal-year-channel.cjs');
 
@@ -64,7 +65,7 @@ function createYearLengths({ sampleAt, massLossSiderealSecondsAtYearFn }) {
   if (typeof sampleAt !== 'function' || typeof massLossSiderealSecondsAtYearFn !== 'function') {
     throw new Error('createYearLengths: sampleAt and massLossSiderealSecondsAtYearFn are required');
   }
-  const w180 = (/** @type {number} */ d) => ((d + 540) % 360) - 180;
+  const w180 = wrap180;   // math/angles — bit-identical to the former inline form for the sub-degree differences wrapped here
   const chan = createSiderealYearChannel({ massLossSiderealSecondsAtYearFn });
   /** A year length from a longer year and a retrograde angular rate of the
    *  reference point, RATE form: 1/T = 1/T_long + p/(360°·JY) — exact (the

package/src/eclipse/besselian.cjs

@@ -69,6 +69,8 @@
 
 'use strict';
 
+const { wrap180 } = require('../math/angles.cjs');
+
 /**
  * @typedef {Object} BesselianDeps
  * @property {(dDaysTT: number) => {lonDeg: number, latDeg: number, distKm: number}} moonFullAtDaysTT
@@ -88,6 +90,23 @@
  *   gmstMeanSiderealT2Deg: number, speedOfLightKmS: number }} constants
  */
 
+/** Mean sidereal time at Greenwich, degrees (mean equinox — pairs with the
+ *  mean-of-date body longitudes; coefficients single-sourced from
+ *  astro-reference.json physicalConstants). THE ONE GMST of the model: the
+ *  eclipse location tier, the API's observer tier, the eclipse and lunar
+ *  audits and the browser's diagnostics all read it. Meeus 12.4's
+ *  cubic term (−T³/38,710,000) is deliberately absent: it is 0.9″ in the
+ *  eclipse canon and at most 93″ (6 s of time) at the edge of the observer
+ *  era, and every recorded eclipse and lunar value was measured without it.
+ *  @param {number} jdUT
+ *  @param {{ j2000JD: number, julianCenturyDays: number, gmstMeanSiderealT0Deg: number, gmstMeanSiderealRateDegPerDay: number, gmstMeanSiderealT2Deg: number }} K
+ *  @returns {number} */
+function computeGmstDeg(jdUT, K) {
+  const T = (jdUT - K.j2000JD) / K.julianCenturyDays;
+  return ((K.gmstMeanSiderealT0Deg + K.gmstMeanSiderealRateDegPerDay * (jdUT - K.j2000JD)
+    + K.gmstMeanSiderealT2Deg * T * T) % 360 + 360) % 360;
+}
+
 /** @param {BesselianDeps} deps */
 function createBesselian(deps) {
   const K = deps.constants;
@@ -97,14 +116,8 @@ function createBesselian(deps) {
   const R_MOON_KM = K.moonDiameterKm / 2;
   const F = 1 / K.earthFlatteningInverse;
 
-  /** Mean sidereal time at Greenwich, degrees (mean equinox — pairs with the
-   *  mean-of-date body longitudes; coefficients single-sourced from
-   *  astro-reference.json physicalConstants). @param {number} jdUT @returns {number} */
-  function gmstDeg(jdUT) {
-    const T = (jdUT - K.j2000JD) / K.julianCenturyDays;
-    return ((K.gmstMeanSiderealT0Deg + K.gmstMeanSiderealRateDegPerDay * (jdUT - K.j2000JD)
-      + K.gmstMeanSiderealT2Deg * T * T) % 360 + 360) % 360;
-  }
+  /** @param {number} jdUT @returns {number} */
+  const gmstDeg = (jdUT) => computeGmstDeg(jdUT, K);
 
   /** Ecliptic-of-date → equatorial-of-date vector (km).
    *  @param {number} lonDeg @param {number} betDeg @param {number} distKm
@@ -150,7 +163,7 @@ function createBesselian(deps) {
     const moon = deps.moonFullAtDaysTT(dTT);
     const H_DAYS = 0.02;
     const dLon = deps.moonFullAtDaysTT(dTT + H_DAYS).lonDeg - deps.moonFullAtDaysTT(dTT - H_DAYS).lonDeg;
-    const moonRateDegPerDay = (((dLon + 540) % 360) - 180) / (2 * H_DAYS);
+    const moonRateDegPerDay = wrap180(dLon) / (2 * H_DAYS);
     const tauDays = moon.distKm / K.speedOfLightKmS / 86400;
     return {
       S: eclToEq(sunLon, 0, sunDistanceKm(year, sunLon), eps),
@@ -310,7 +323,7 @@ function createBesselian(deps) {
     return { kind, magnitude: Math.max(0, atMax.magnitude), maxJd, contacts, centralDurationSeconds };
   }
 
-  return { umbraGroundAt, shadowStateAt, localCircumstances };
+  return { umbraGroundAt, shadowStateAt, localCircumstances, gmstDeg };
 }
 
-module.exports = { createBesselian };
+module.exports = { createBesselian, computeGmstDeg };

package/src/index.js

@@ -138,9 +138,9 @@ export * as planetOrbitChain from './planets/orbit-chain.cjs';
 export { computeSecularShape } from './planets/secular-shape.cjs';
 // `computeApsidalTangentDegPerYr` is the chain's ±150-yr central tangent of the perihelion
 // longitude (the panels' "Prec." cell — osculating, NOT the ±1-kyr secular stencil of the
-// "Secular" cell); `computeApsidalSecularDegPerYr` is its former name, kept as a deprecated
-// alias on the API axis.
-export { buildPlanetChainsFromArtifactData, computePlanetElementsAtYear, computeHeliocentricEclipticFromElements, computePoissonArgRad, computeOsculatingElements, solveKeplerRad, computeApsidalSecularDegPerYr, computeApsidalSecularDegPerYr as computeApsidalTangentDegPerYr, ANCHOR_EPOCH_YEAR, ANCHOR_EPOCH_JD } from './planets/keplerian-chain.cjs';
+// "Secular" cell). Its former name `computeApsidalSecularDegPerYr` left the API at 24.0.0
+// (no reader in the simulator, the website or the paper).
+export { buildPlanetChainsFromArtifactData, computePlanetElementsAtYear, computeHeliocentricEclipticFromElements, computePoissonArgRad, computeOsculatingElements, solveKeplerRad, computeApsidalTangentDegPerYr, ANCHOR_EPOCH_YEAR, ANCHOR_EPOCH_JD } from './planets/keplerian-chain.cjs';
 export { computeEquatorNodeOriginSFrameDeg, convertNodeSFrameToEquatorOriginDeg } from './planets/inv-plane-frame.cjs';
 export { createSecularSeriesOverride } from './planets/secular-series.cjs';
 // The planets' spin channel (the precession constant from each planet's own

package/src/model/lunar-theory.js

@@ -61,7 +61,7 @@ export function assembleLunarTheory(ctx) {
   const anomalisticMonthPeriodFn = (tMa) => moonChain.anomalisticMonthSecondsAtAge(tMa);
   /** @param {number} tMa @returns {number|null} */
   const siderealMonthPeriodFn = (tMa) => moonChain.siderealMonthSecondsAtAge(tMa);
-  const jupiterT0Seconds = C.planetOrbitalElements.jupiter.solarYearInput * 86400;
+  const jupiterT0Seconds = C.planetOrbitalElements.jupiter.orbitalPeriodInputDays * 86400;
   /** @param {number} tMa @returns {number} */
   const jupiterPeriodFn = (tMa) => driver2PeriodSecondsAtAge(tMa, jupiterT0Seconds, EPOCH_PARAMS.solarMassLossFracPerYear);
   /** @param {number} a @param {number} b @returns {number|null} */
@@ -164,7 +164,7 @@ export function assembleLunarTheory(ctx) {
   // docs/109 §22 for the derivation)
   const fwA2RateDegPerCy = 2 * ((360 * 36525) / moonTropicalMonthDays)
     - (360 * 36525) / moonAnomalisticMonthDays
-    - 2 * ((360 * 36525) / C.planetOrbitalElements.jupiter.solarYearInput);
+    - 2 * ((360 * 36525) / C.planetOrbitalElements.jupiter.orbitalPeriodInputDays);
   const fwA3RateDegPerCy = (360 * 36525) / moonSiderealMonth;
 
   // Meeus Ch. 47 truncated series (framework-native arguments + E-factor)

package/src/model/planet-records.js

@@ -46,7 +46,7 @@ export function assemblePlanetRecords(ctx) {
     const sArc = chainModes.s[k] && chainModes.s[k].arcsecPerYr;
     PUBLISHED_PLANET_RECORDS[k] = Object.freeze({
       name: PLANET_DISPLAY_NAMES[k],   // presentation — planets/display-names, the deleted JSON's last leaf (plan 11 step 6)
-      solarYearInput: ar.solarYearInput,
+      orbitalPeriodInputDays: ar.orbitalPeriodInputDays,
       longitudePerihelion: ar.longitudePerihelion,
       ascendingNodeInvPlane: ar.ascendingNodeInvPlaneClosedForm,   // the closed-form verified J2000 node — astro-reference since plan 11 step 2
       invPlaneInclinationJ2000: ar.invPlaneInclinationJ2000,

package/src/model/sun-and-eclipses.js

@@ -132,7 +132,7 @@ export function assembleSunAndEclipses(ctx) {
   // FQ-5 N3 — the completion's carriers are FRAMEWORK-derived from the
   // model's own planet period records (the Moon-elongation rate from the
   // sidereal month/year identity). Plan 06 I2 — the carriers are SIDEREAL
-  // (measured): the records' solarYearInput are OF-DATE periods (their
+  // (measured): the records' orbitalPeriodInputDays are OF-DATE periods (their
   // rates sit +1.39..1.62°/cy above the VSOP sidereal mean motions — the
   // framework precession plus input rounding), and a perturbation argument
   // is inertial (D'Alembert: only Σk = 0 arguments are frame-free), so on

package/src/model/surface.js

@@ -312,6 +312,8 @@ export function assembleSurface(ctx) {
       }),
       // 20.3g location tier (see eclipse/besselian.cjs):
       umbraGroundAtJD: /** @param {number} jd @returns {{latDeg: number, lonDeg: number} | null} */ (jd) => besselian.umbraGroundAt(jd),
+      /** THE ONE GMST — mean sidereal time at Greenwich, degrees, at a UT JD (eclipse/besselian.cjs computeGmstDeg; the observer tier's hour angle). @param {number} jdUT @returns {number} */
+      gmstDegAtJD: (jdUT) => besselian.gmstDeg(jdUT),
       solarLocalCircumstances: /** @param {number} jdGreatest @param {number} latDeg @param {number} lonDeg */ (jdGreatest, latDeg, lonDeg) => besselian.localCircumstances(jdGreatest, latDeg, lonDeg),
     }),
     climate: Object.freeze({

package/src/model/year-day-lengths.js

@@ -7,7 +7,7 @@ import { ONE_FAMILY_WINDOW_YEARS } from '../earth/year-lengths.cjs';
 
 /** @param {import('./earth-scalars.js').Ctx} ctx @returns the bindings the later slices read */
 export function assembleYearDayLengths(ctx) {
-  const { C, late, deepLod, meanLengthOfDay, yearToTMa } = ctx;
+  const { chain, late, deepLod, meanLengthOfDay, yearToTMa } = ctx;
   // The year lengths of date in DAYS are the published SI year lengths over
   // the kinematic day of date; the kinematic day of date is the Layer-0 tidal
   // mean LOD, exactly ω₀ (the SI day) at J2000.
@@ -19,7 +19,7 @@ export function assembleYearDayLengths(ctx) {
    * surface all read it (the identifier predates the anchor's move onto the
    * IAU input). @returns {number} */
   function certifiedAxialPrecessionJ2000Years() {
-    return 1296000 / C.earthOrbital.generalPrecessionJ2000_arcsecPerYr;
+    return chain.certifiedAxialPrecessionJ2000Years();   // the ONE home: the deep-time chain's export (1,296,000 / p_A on the same constants)
   }
   /** Kinematic day of date (Layer 0 tidal mean LOD; ω₀ at J2000). Past the
    *  tidal-lock asymptote the chain is null — the J2000 day stands in.