@essrt/physics 1.3.2 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@essrt/physics",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "description": "ESSRT (Expanding Solar System Resonance Theory) physics core \u2014 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": "v11.0",

package/src/constants/coefficients.js

@@ -17,7 +17,7 @@
  */
 
 /** @type {string} */
-export const COEFFICIENTS_HASH = "1f1692da72c0e10a";
+export const COEFFICIENTS_HASH = "bf011174cdd73175";
 
 /** @type {Readonly<Record<string, unknown>>} */
 export const FITTED_COEFFICIENTS = Object.freeze({
@@ -34,6 +34,7 @@ export const FITTED_COEFFICIENTS = Object.freeze({
   DT_STACK: {"bond":{"lattice_n":1830,"period_yr":1465.8666666666666,"cos_coeff_s":145.55092942423886,"sin_coeff_s":329.34746510072887,"raw_at_j2000_s":152.06408184557264,"amplitude_s":360.0761389269436,"phase_deg":66.15757672735135,"source":"Stage D anchored fit (USNO LOD constraint active)","joint_mode":true},"hallstatt":{"lattice_n":1104,"period_yr":2429.8333333333335,"cos_coeff_s":-73.00792820024905,"sin_coeff_s":32.70844569690342,"raw_at_j2000_s":-61.685166343361075,"amplitude_s":80,"phase_deg":155.86703617290817,"target_amp_source":"CAPPED from anchored quad-fit free amp 100.73 s → 80 s prior","joint_mode":true},"jose5":{"lattice_n":2989,"period_yr":897.469387755102,"cos_coeff_s":-34.5239711109052,"sin_coeff_s":36.16760178299611,"raw_at_j2000_s":31.185593588239136,"amplitude_s":50.00000000000001,"phase_deg":133.66807127984734,"target_amp_source":"CAPPED from anchored quad-fit free amp 86.44 s → 50 s prior","joint_mode":true},"jose4":{"lattice_n":3749,"period_yr":715.5337423312883,"cos_coeff_s":38.542513112148065,"sin_coeff_s":-31.850819188835548,"raw_at_j2000_s":41.35969402774114,"amplitude_s":50,"phase_deg":-39.56969682845315,"target_amp_source":"unconstrained: quad-fit free amp 47.06 s (below 50 s prior — no cap applied)","joint_mode":true}},
   ELONGATION_CORRECTION: {"venus":{"cosVwE_sinEl_ra":-0.00013078499578943705,"cosVwE_sinEl_dec":0.00023700025209189867,"sinEl_d_ra":0.0007755608738916972,"sinEl_d_dec":-0.0003797976373342036,"sinVwE_sinEl_ra":-0.0006776328282247138,"sinVwE_sinEl_dec":-0.00043481049672109887,"sin2VwE_sinEl_ra":0.0018944674227536075,"sin2VwE_sinEl_dec":0.007226452365794387,"cos2VwE_sinEl_ra":0.0022333742453015813,"cos2VwE_sinEl_dec":0.00643045263681664,"cos4VwE_sinEl_ra":-0.005168878088645803,"cos4VwE_sinEl_dec":-0.001292412216853322,"sin4VwE_sinEl_ra":0.002473729458674539,"sin4VwE_sinEl_dec":0.000937054827431583,"sinVwE_sinEl_d2_ra":0.0002912977464846237,"sinVwE_sinEl_d2_dec":0.00009508378159137789,"cos3VwE_sinEl_ra":-0.0004372175697726782,"cos3VwE_sinEl_dec":0.002048597993702653,"sin3VwE_sinEl_ra":-0.011369485008173839,"sin3VwE_sinEl_dec":-0.007442688270196107,"sin2syn_ra":-0.0010979280775001478,"sin2syn_dec":-0.00036294328226461474,"cos1syn_ra":0.0006738224187823681,"cos1syn_dec":-0.0006544590346891286,"sin3VwE_sinEl_d2_ra":0.002112353789427301,"sin3VwE_sinEl_d2_dec":0.0024447308843828846,"sin2VwE_sinEl_d2_ra":-0.000381924061656027,"sin2VwE_sinEl_d2_dec":-0.001112791195900534,"cos2VwE_sinEl_d2_ra":-0.0009611408402006777,"cos2VwE_sinEl_d2_dec":-0.0016972655933243698,"cosEl_d_ra":0.00019899967515409905,"cosEl_d_dec":-0.00034331917768957944,"cosVwE_cosEl_d_ra":-0.005960071418246849,"cosVwE_cosEl_d_dec":0.0031678195308038003,"sinVwE_cosEl_d_ra":-0.007190793725682356,"sinVwE_cosEl_d_dec":0.0013596615637549907,"cosEl_d2_ra":-0.00020663256097824926,"cosEl_d2_dec":-0.00004027080936022818,"cosVwE_cosEl_d2_ra":0.0005814547197492051,"cosVwE_cosEl_d2_dec":-0.000935906915634443,"sinVwE_cosEl_d2_ra":0.0007813571841350501,"sinVwE_cosEl_d2_dec":-0.00047223215820587456},"mars":{"cosVwE_sinEl_ra":-0.0011140487798611339,"cosVwE_sinEl_dec":-0.0036743796624175667,"sinEl_d_ra":0.0033627186215710245,"sinEl_d_dec":-0.012701815547956385,"sinVwE_sinEl_ra":-0.006356141564681869,"sinVwE_sinEl_dec":-0.00013369961659808483,"sin2VwE_sinEl_ra":0.00031724439612794344,"sin2VwE_sinEl_dec":0.01739168539941939,"cos2VwE_sinEl_ra":0.004143516153439421,"cos2VwE_sinEl_dec":0.00022778444218044325,"cos4VwE_sinEl_ra":0.005428306044246736,"cos4VwE_sinEl_dec":-0.01080111524328561,"sin4VwE_sinEl_ra":-0.0222174954712206,"sin4VwE_sinEl_dec":0.004286393953615477,"sinVwE_sinEl_d2_ra":0.005283420045811403,"sinVwE_sinEl_d2_dec":-0.0019096834272178508,"cos3VwE_sinEl_ra":-0.01713337342795123,"cos3VwE_sinEl_dec":0.002581862227614283,"sin3VwE_sinEl_ra":0.01566231796548501,"sin3VwE_sinEl_dec":-0.0046477676601650916,"sin2syn_ra":0.00256480149974197,"sin2syn_dec":-0.012209611899495584,"cos1syn_ra":-0.001006874061925775,"cos1syn_dec":0.009872831735740904,"sin3VwE_sinEl_d2_ra":-0.037392015803510585,"sin3VwE_sinEl_d2_dec":0.002473538068428684,"sin2VwE_sinEl_d2_ra":0.0038455948792325678,"sin2VwE_sinEl_d2_dec":-0.014778577154897714,"cos2VwE_sinEl_d2_ra":-0.011807978628793191,"cos2VwE_sinEl_d2_dec":0.0012557544306986937,"cosEl_d_ra":0.000284882868911627,"cosEl_d_dec":-0.0021820884562501544,"cosVwE_cosEl_d_ra":-0.0003505964419227473,"cosVwE_cosEl_d_dec":0.0055104246995418575,"sinVwE_cosEl_d_ra":0.0002518986669389568,"sinVwE_cosEl_d_dec":-0.0020101942296837116,"cosEl_d2_ra":0.00006092485835005758,"cosEl_d2_dec":-0.001141320906493464,"cosVwE_cosEl_d2_ra":0.00023028197939182156,"cosVwE_cosEl_d2_dec":-0.002735862075021542,"sinVwE_cosEl_d2_ra":0.00011442353028413846,"sinVwE_cosEl_d2_dec":-0.0005857378114159205}},
   GRAVITATION_CORRECTION: {"mercury":[{"period":47.426470068243695,"raSin":0.00020636689960606448,"raCos":-0.000463323074166234,"decSin":-0.0012812669809594151,"decCos":-0.000661073144287821},{"period":23.713235034121848,"raSin":0.0024571786204407695,"raCos":-0.00007829078384963884,"decSin":-0.00040252237651284623,"decCos":0.006123565966605076}],"mars":[{"period":2.2353274492027086,"raSin":0.003981258082191666,"raCos":-0.004279949161181997,"decSin":-0.0007025871136428711,"decCos":0.00013803329632746126},{"period":2.742729776153993,"raSin":0.0009224827474374854,"raCos":0.0035243396145755255,"decSin":-0.000041052377051558215,"decCos":0.0003882097655946518}],"jupiter":[{"period":12.782258986772387,"raSin":0.00010028515727242995,"raCos":-0.0013936371417833254,"decSin":0.0018857367234133855,"decCos":-0.0008391359414103676},{"period":19.858868818477937,"raSin":0.022964869787559093,"raCos":-0.005600637142447164,"decSin":-0.0004034780418806047,"decCos":0.00008820719281509448}],"saturn":[{"period":19.858868818477937,"raSin":-0.0053846507635660415,"raCos":-0.005118860493020084,"decSin":0.016664189906193345,"decCos":-0.012277491565905576},{"period":136.08644480519482,"raSin":0.023864298650611435,"raCos":0.003917202339383959,"decSin":-0.0009902470204102892,"decCos":-0.002105843197823579},{"period":71.74090714591357,"raSin":0.005228577374514756,"raCos":-0.02062423940765225,"decSin":0.0010240283184854112,"decCos":0.005623456135787617},{"period":45.36214826839827,"raSin":0.013297492020279023,"raCos":-0.002641113806354099,"decSin":-0.008482436148476174,"decCos":0.00024099809887146969}],"uranus":[{"period":171.42995910020446,"raSin":0.011161170123927776,"raCos":0.006577304787331431,"decSin":0.0003585949163466174,"decCos":0.0006814216700589923},{"period":13.812126704288008,"raSin":-0.0021822974433193016,"raCos":-0.014428543965216015,"decSin":0.000022821047430643845,"decCos":-0.0011047767505970472}],"neptune":[{"period":12.782258986772387,"raSin":-0.00020371209839160938,"raCos":-0.009366315007525577,"decSin":4.249640867513261e-7,"decCos":-0.00027671876932212577},{"period":35.870453572956784,"raSin":0.0013395890197134145,"raCos":-0.0049071499875754645,"decSin":0.00005320422039121083,"decCos":-0.0000805247365884665}]},
+  MEEUS_DISTANCE_TERMS: {"meanKm":385000.56,"terms":[[0,0,1,0,-20905355],[2,0,-1,0,-3699111],[2,0,0,0,-2955968],[0,0,2,0,-569925],[0,1,0,0,48888],[0,0,0,2,-3149],[2,0,-2,0,246158],[2,-1,-1,0,-152138],[2,0,1,0,-170733],[2,-1,0,0,-204586],[0,1,-1,0,-129620],[1,0,0,0,108743],[0,1,1,0,104755],[2,0,0,-2,10321],[0,0,1,2,0],[0,0,1,-2,79661],[4,0,-1,0,-34782],[0,0,3,0,-23210],[4,0,-2,0,-21636],[2,1,-1,0,24208],[2,1,0,0,30824],[1,0,-1,0,-8379],[1,1,0,0,-16675],[2,-1,1,0,-12831],[2,0,2,0,-10445],[4,0,0,0,-11650],[2,0,-3,0,14403],[0,1,-2,0,-7003],[2,0,-1,2,0],[2,-1,-2,0,10056],[1,0,1,0,6322],[2,-2,0,0,-9884],[0,1,2,0,5751],[0,2,0,0,0],[2,-2,-1,0,-4950],[2,0,1,-2,4130],[2,0,0,2,0],[4,-1,-1,0,-3958],[0,0,2,2,0],[3,0,-1,0,3258],[2,1,1,0,2616],[4,-1,-2,0,-1897],[0,2,-1,0,-2117],[2,2,-1,0,2354],[2,1,-2,0,0],[2,-1,0,-2,0],[4,0,1,0,-1423],[0,0,4,0,-1117],[4,-1,0,0,-1571],[1,0,-2,0,-1739],[2,1,0,-2,0],[0,0,2,-2,-4421],[1,1,1,0,0],[3,0,-2,0,0],[4,0,-3,0,0],[2,-1,2,0,0],[0,2,1,0,1165],[1,1,-1,0,0],[2,0,3,0,0],[2,0,-1,-2,8752]]},
   MEEUS_LATITUDE_TERMS: [[0,0,0,1,5128122],[0,0,1,1,280602],[0,0,1,-1,277693],[2,0,0,-1,173237],[2,0,-1,1,55413],[2,0,-1,-1,46271],[2,0,0,1,32573],[0,0,2,1,17198],[2,0,1,-1,9266],[0,0,2,-1,8822],[2,-1,0,-1,8216],[2,0,-2,-1,4324],[2,0,1,1,4200],[2,1,0,-1,-3359],[2,-1,-1,1,2463],[2,-1,0,1,2211],[2,-1,-1,-1,2065],[0,1,-1,-1,-1870],[4,0,-1,-1,1828],[0,1,0,1,-1794],[0,0,0,3,-1749],[0,1,-1,1,-1565],[1,0,0,1,-1491],[0,1,1,1,-1475],[0,1,1,-1,-1410],[0,1,0,-1,-1344],[1,0,0,-1,-1335],[0,0,3,1,1107],[4,0,0,-1,1021],[4,0,-1,1,833],[0,0,1,-3,777],[4,0,-2,1,671],[2,0,0,-3,607],[2,0,2,-1,596],[2,-1,1,-1,491],[2,0,-2,1,-451],[0,0,3,-1,439],[2,0,2,1,422],[2,0,-3,-1,421],[2,1,-1,1,-366],[2,1,0,1,-351],[4,0,0,1,331],[2,-1,1,1,315],[2,-2,0,-1,302],[0,0,1,3,-283],[2,1,1,-1,-229],[1,1,0,-1,223],[1,1,0,1,223],[0,1,-2,-1,-220],[2,1,-1,-1,-220],[1,0,1,1,-185],[2,-1,-2,-1,181],[0,1,2,1,-177],[4,0,-2,-1,176],[4,-1,-1,-1,166],[1,0,1,-1,-164],[4,0,1,-1,132],[1,0,-1,-1,-119],[4,-1,0,-1,115],[2,-2,0,1,107]],
   MEEUS_LONGITUDE_TERMS: [[0,0,1,0,6288774],[2,0,-1,0,1274027],[2,0,0,0,658314],[0,0,2,0,213618],[0,1,0,0,-185116],[0,0,0,2,-114332],[2,0,-2,0,58793],[2,-1,-1,0,57066],[2,0,1,0,53322],[2,-1,0,0,45758],[0,1,-1,0,-40923],[1,0,0,0,-34720],[0,1,1,0,-30383],[2,0,0,-2,15327],[0,0,1,2,-12528],[0,0,1,-2,10980],[4,0,-1,0,10675],[0,0,3,0,10034],[4,0,-2,0,8548],[2,1,-1,0,-7888],[2,1,0,0,-6766],[1,0,-1,0,-5163],[1,1,0,0,4987],[2,-1,1,0,4036],[2,0,2,0,3994],[4,0,0,0,3861],[2,0,-3,0,3665],[0,1,-2,0,-2689],[2,0,-1,2,-2602],[2,-1,-2,0,2390],[1,0,1,0,-2348],[2,-2,0,0,2236],[0,1,2,0,-2120],[0,2,0,0,-2069],[2,-2,-1,0,2048],[2,0,1,-2,-1773],[2,0,0,2,-1595],[4,-1,-1,0,1215],[0,0,2,2,-1110],[3,0,-1,0,-892],[2,1,1,0,-810],[4,-1,-2,0,759],[0,2,-1,0,-713],[2,2,-1,0,-700],[2,1,-2,0,691],[2,-1,0,-2,596],[4,0,1,0,549],[0,0,4,0,537],[4,-1,0,0,520],[1,0,-2,0,-487],[2,1,0,-2,-399],[0,0,2,-2,-381],[1,1,1,0,351],[3,0,-2,0,-340],[4,0,-3,0,330],[2,-1,2,0,327],[0,2,1,0,-323],[1,1,-1,0,299],[2,0,3,0,294]],
   MOON_CORRECTION: {"raSinD":7.184453869061568e-7,"raCosD":0.000007773645658437624,"raSinMp":1.4279023255816577e-7,"raCosMp":-0.000016143853244117095,"raSinMs":0.00004290517368813111,"raCosMs":-0.000028078099681085273,"decSinD":-0.00001414309929430708,"decCosD":0.000007487034647903192,"decSinMp":0.000008568789356865513,"decCosMp":0.000010874252100847628,"decSinMs":-0.00002315228957457375,"decCosMs":0.0000057588397049875064},

package/src/constants/generated.d.ts

@@ -2,14 +2,14 @@
 // Gives the TypeScript website full type safety at the boundary (§2g) while
 // packages/physics stays JavaScript.
 
-export declare const CONSTANTS_HASH: "c27d98c2f75e949b";
+export declare const CONSTANTS_HASH: "fa3230753655d190";
 
 export declare const MODEL_VERSION: string;
 
 export declare const PREPRINT_DOI: string;
 
 export declare const DEFAULT_CONSTANTS: {
-  readonly hash: "c27d98c2f75e949b";
+  readonly hash: "fa3230753655d190";
   readonly additionalBodies: {
     "pluto": {
       "name": string;
@@ -239,6 +239,22 @@ export declare const DEFAULT_CONSTANTS: {
     "MASS_RATIO_EARTH_MOON": number;
     "speedOfLight": number;
     "earthMoiFactorJ2000": number;
+    "earthFlatteningInverseWGS84": number;
+    "aberrationConstantArcsec": number;
+    "gmstMeanSiderealT0Deg": number;
+    "gmstMeanSiderealRateDegPerDay": number;
+    "gmstMeanSiderealT2Deg": number;
+    "nutationLeadingTermsArcsec": {
+      "psiOmega": number;
+      "psi2Ls": number;
+      "psi2Lm": number;
+      "psi2Omega": number;
+      "epsOmega": number;
+      "eps2Ls": number;
+      "eps2Lm": number;
+      "eps2Omega": number;
+      "omegaNodeJ2000Deg": number;
+    };
     "solarLuminosityW": number;
     "solarWindMassLossKgPerS": number;
     "massRatioDE440": {

package/src/constants/generated.js

@@ -32,7 +32,7 @@
  * carry it so a counterfactual is reproducible (§2d).
  * @type {string}
  */
-export const CONSTANTS_HASH = "c27d98c2f75e949b";
+export const CONSTANTS_HASH = "fa3230753655d190";
 
 /** Model version label — single source: public/input/model-version.json (§10 two-axis scheme). */
 export const MODEL_VERSION = "v11.0";
@@ -42,7 +42,7 @@ export const PREPRINT_DOI = "10.21203/rs.3.rs-8758810/v4";
 
 /** @type {Readonly<Record<string, unknown>>} */
 export const DEFAULT_CONSTANTS = Object.freeze({
-  hash: "c27d98c2f75e949b",
+  hash: "fa3230753655d190",
   additionalBodies: {
     "pluto": {
       "name": "Pluto",
@@ -296,6 +296,22 @@ export const DEFAULT_CONSTANTS = Object.freeze({
     "MASS_RATIO_EARTH_MOON": 81.30056816,
     "speedOfLight": 299792.458,
     "earthMoiFactorJ2000": 0.3306947,
+    "earthFlatteningInverseWGS84": 298.257223563,
+    "aberrationConstantArcsec": 20.4955,
+    "gmstMeanSiderealT0Deg": 280.46061837,
+    "gmstMeanSiderealRateDegPerDay": 360.98564736629,
+    "gmstMeanSiderealT2Deg": 0.000387933,
+    "nutationLeadingTermsArcsec": {
+      "psiOmega": -17.2,
+      "psi2Ls": -1.32,
+      "psi2Lm": -0.23,
+      "psi2Omega": 0.21,
+      "epsOmega": 9.2,
+      "eps2Ls": 0.57,
+      "eps2Lm": 0.1,
+      "eps2Omega": -0.09,
+      "omegaNodeJ2000Deg": 125.04452
+    },
     "solarLuminosityW": 3.828e+26,
     "solarWindMassLossKgPerS": 1600000000,
     "massRatioDE440": {

package/src/eclipse/besselian.cjs

@@ -0,0 +1,278 @@
+/**
+ * Solar-eclipse shadow geometry — the location tier (20.3g).
+ *
+ * Instantaneous shadow-axis evaluation on the FULL shared series (no
+ * precomputed polynomial elements): at any JD(UT) the geocentric Sun and
+ * Moon are placed in the equatorial-of-date frame, the umbra axis is
+ * intersected with the ellipsoid, and observer local circumstances follow
+ * from the observer's perpendicular offset to the axis versus the
+ * penumbra/umbra cone radii at the observer's axial plane.
+ *
+ * THE TWO AXIS CONVENTIONS (both measured against the 15 NASA path-table
+ * centerline points, tools/verify/eclipse-audit.js `centerlines`; the raw
+ * finder chain read ~61″ shadow-plane, this chain 6.3″ mean / 9.1″ max —
+ * within every NASA path half-width):
+ *
+ *  1. TT bridge. The framework ΔT curve is ZEROED AT J2000 by construction
+ *     (it integrates LOD excess from the epoch anchor); the model's
+ *     absolute ΔT is deltaTStart + curve — exactly how every other
+ *     consumer reads it (the browser accumulator, Meeus geometry, the ΔT
+ *     charts; deltaTStart is the joint-world trend anchor, deliberately
+ *     ~8 s below the IERS instantaneous 63.6 s — the industrial-era
+ *     acceleration the cyclic model does not capture). The eclipse
+ *     FINDERS deliberately stay on the zeroed convention — their fitted
+ *     anchors (SUN_HARMONICS, canon statistics) were produced through it,
+ *     and eclipse TIMING is elongation-class, where the convention
+ *     cancels against the fitted phases. GROUND LOCATION is absolute: the
+ *     Earth-fixed frame rides true UT rotation, so the bodies are
+ *     evaluated at the model's absolute TT. ttBridgeSeconds = deltaTStart
+ *     (no new constant; measured BETTER on the NASA reference points than
+ *     the observed 63.8/64.2 s — mean 6.3″ vs 7.3″). ~34″ of the raw
+ *     offset.
+ *
+ *  2. Full series, not the truncated finder forms. truncatedLonDeg omits
+ *     the fitted moonMeeusLpCorrection anchor (+33.8″) and truncatedBetaDeg
+ *     omits the −2235·sin(Lp) latitude family (~8″) — both deliberate for
+ *     the certified finder statistics (knife-edge canon events), both
+ *     required here. The injected moonFullAtDaysTT is the series'
+ *     sceneEvalAt — the same evaluation the browser scene ships. Measured:
+ *     ~27″ of the raw offset.
+ *
+ * Annual aberration is deliberately ABSENT: for ground location a
+ * common-mode rotation of both bodies moves the ground point by the raw
+ * angle (~0.6 km), and the elongation content cancels at syzygy (the
+ * round-3 result). Both bodies here are geometric mean-of-date, matching
+ * the MEAN sidereal time used for the Earth-fixed mapping.
+ *
+ * The scene-umbra conventions (THREE scaffold navigation) never enter this
+ * package (§2h) — this is an independent construction on the shared
+ * series, cross-checked against the scene twins through the same NASA
+ * reference points.
+ */
+
+'use strict';
+
+/**
+ * @typedef {Object} BesselianDeps
+ * @property {(dDaysTT: number) => {lonDeg: number, latDeg: number, distKm: number}} moonFullAtDaysTT
+ *   full-series Moon: ecliptic-of-date longitude/latitude (deg) + distance (km), TT axis (days since J2000)
+ * @property {(jdUT: number) => number} sunLonDegAt - geometric mean sun longitude (deg), JD(UT) axis with the finder's internal ΔT
+ * @property {(jd: number) => number} deltaTSecondsAt - framework ΔT (J2000-zeroed convention)
+ * @property {(year: number) => number} obliquityDegAt - framework obliquity (deg) at calendar year
+ * @property {(year: number) => number} eccentricityAt - framework Earth-orbit eccentricity at calendar year
+ * @property {(year: number) => number} perihelionLongitudeDegAt - framework perihelion longitude (deg) at calendar year
+ * @property {(jd: number) => number} yearFromJD - the model's own JD → calendar-year conversion
+ * @property {{ j2000JD: number, julianCenturyDays: number, earthDiameterKm: number,
+ *   moonDiameterKm: number, sunDiameterKm: number, sunDistanceKm: number,
+ *   earthFlatteningInverse: number, ttBridgeSeconds: number,
+ *   gmstMeanSiderealT0Deg: number, gmstMeanSiderealRateDegPerDay: number,
+ *   gmstMeanSiderealT2Deg: number }} constants
+ */
+
+/** @param {BesselianDeps} deps */
+function createBesselian(deps) {
+  const K = deps.constants;
+  const D2R = Math.PI / 180;
+  const R_E_KM = K.earthDiameterKm / 2;
+  const R_SUN_KM = K.sunDiameterKm / 2;
+  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;
+  }
+
+  /** Ecliptic-of-date → equatorial-of-date vector (km).
+   *  @param {number} lonDeg @param {number} betDeg @param {number} distKm
+   *  @param {number} epsRad @returns {[number, number, number]} */
+  function eclToEq(lonDeg, betDeg, distKm, epsRad) {
+    const lam = lonDeg * D2R, bet = betDeg * D2R;
+    const x = Math.cos(bet) * Math.cos(lam);
+    const y = Math.cos(bet) * Math.sin(lam) * Math.cos(epsRad) - Math.sin(bet) * Math.sin(epsRad);
+    const z = Math.cos(bet) * Math.sin(lam) * Math.sin(epsRad) + Math.sin(bet) * Math.cos(epsRad);
+    return [distKm * x, distKm * y, distKm * z];
+  }
+
+  /** Elliptical Sun distance — FRAMEWORK-NATIVE: the model's own
+   *  eccentricity (Law-5-locked base + drift) and perihelion longitude
+   *  (H/16 precession) close the ellipse, with the true anomaly from the
+   *  already-computed sun longitude (v = λ − (ϖ + 180°), geocentric-perigee
+   *  convention). Agrees with the Meeus Ch. 25 polynomial to ±0.001% over a
+   *  year, with no fitted external coefficients, and stays honest at deep
+   *  time (e and ϖ evolve with the model). The distance is LOAD-BEARING for
+   *  the umbral cone radius — a small difference of large terms: the
+   *  mean-AU approximation's ±1.7% seasonal error became tens of percent of
+   *  umbra radius (measured: Carbondale 2017 central duration 95 s vs the
+   *  real 158 s; elliptical gives 157 s).
+   *  @param {number} year @param {number} sunLonDeg @returns {number} km */
+  function sunDistanceKm(year, sunLonDeg) {
+    const e = deps.eccentricityAt(year);
+    const v = (sunLonDeg - (deps.perihelionLongitudeDegAt(year) + 180)) * D2R;
+    return K.sunDistanceKm * (1 - e * e) / (1 + e * Math.cos(v));
+  }
+
+  /** Sun and Moon geocentric equatorial-of-date vectors at true TT.
+   *  @param {number} jdUT @returns {{S: [number,number,number], M: [number,number,number]}} */
+  function bodiesAt(jdUT) {
+    const jb = jdUT + K.ttBridgeSeconds / 86400;          // finder-axis input → its internal ΔT lands on true TT
+    const year = deps.yearFromJD(jb);
+    const eps = deps.obliquityDegAt(year) * D2R;
+    const sunLon = deps.sunLonDegAt(jb);
+    const dTT = (jb - K.j2000JD) + deps.deltaTSecondsAt(jb) / 86400;
+    const moon = deps.moonFullAtDaysTT(dTT);
+    return {
+      S: eclToEq(sunLon, 0, sunDistanceKm(year, sunLon), eps),
+      M: eclToEq(moon.lonDeg, moon.latDeg, moon.distKm, eps),
+    };
+  }
+
+  /** Umbra-axis ground intersection at JD(UT): geodetic latitude, east
+   *  longitude — or null when the axis misses the ellipsoid.
+   *  @param {number} jdUT @returns {{latDeg: number, lonDeg: number} | null} */
+  function umbraGroundAt(jdUT) {
+    const { S, M } = bodiesAt(jdUT);
+    const dv = [M[0] - S[0], M[1] - S[1], M[2] - S[2]];
+    const dl = Math.hypot(dv[0], dv[1], dv[2]);
+    const d = [dv[0] / dl, dv[1] / dl, dv[2] / dl];
+    const MdotD = M[0] * d[0] + M[1] * d[1] + M[2] * d[2];
+    const MdotM = M[0] * M[0] + M[1] * M[1] + M[2] * M[2];
+    const disc = MdotD * MdotD - (MdotM - R_E_KM * R_E_KM);
+    if (disc < 0) return null;
+    const s = -MdotD - Math.sqrt(disc);
+    const hit = [M[0] + s * d[0], M[1] + s * d[1], M[2] + s * d[2]];
+    const r = Math.hypot(hit[0], hit[1], hit[2]);
+    const latGc = Math.asin(Math.max(-1, Math.min(1, hit[2] / r)));
+    const latDeg = Math.atan(Math.tan(latGc) / ((1 - F) * (1 - F))) / D2R;
+    let lonDeg = Math.atan2(hit[1], hit[0]) / D2R - gmstDeg(jdUT);
+    lonDeg = ((lonDeg + 540) % 360) - 180;
+    return { latDeg, lonDeg };
+  }
+
+  /** Observer geocentric position in the equatorial-of-date frame (km).
+   *  Geodetic latitude on the ellipsoid (sea level).
+   *  @param {number} jdUT @param {number} latDeg @param {number} lonDeg
+   *  @returns {[number, number, number]} */
+  function observerVec(jdUT, latDeg, lonDeg) {
+    const u = Math.atan((1 - F) * Math.tan(latDeg * D2R));     // reduced latitude
+    const rho = [Math.cos(u), (1 - F) * Math.sin(u)];          // [equatorial, polar] components / R_E
+    const lst = (gmstDeg(jdUT) + lonDeg) * D2R;                // local mean sidereal angle
+    return [
+      R_E_KM * rho[0] * Math.cos(lst),
+      R_E_KM * rho[0] * Math.sin(lst),
+      R_E_KM * rho[1],
+    ];
+  }
+
+  /**
+   * Instantaneous shadow state at the observer: perpendicular offset from
+   * the axis vs cone radii at the observer's axial plane.
+   * @param {number} jdUT @param {number} latDeg @param {number} lonDeg
+   * @returns {{offsetKm: number, penumbraKm: number, umbraKm: number, magnitude: number}}
+   *   umbraKm is SIGNED: positive = annular (beyond the umbral vertex),
+   *   negative = total; |umbraKm| is the central-zone radius either way.
+   */
+  function shadowStateAt(jdUT, latDeg, lonDeg) {
+    const { S, M } = bodiesAt(jdUT);
+    const O = observerVec(jdUT, latDeg, lonDeg);
+    const dv = [M[0] - S[0], M[1] - S[1], M[2] - S[2]];
+    const dl = Math.hypot(dv[0], dv[1], dv[2]);
+    const d = [dv[0] / dl, dv[1] / dl, dv[2] / dl];            // Sun→Moon (toward Earth)
+    const OM = [O[0] - M[0], O[1] - M[1], O[2] - M[2]];
+    const along = OM[0] * d[0] + OM[1] * d[1] + OM[2] * d[2];  // axial distance Moon→observer plane
+    const w = [OM[0] - along * d[0], OM[1] - along * d[1], OM[2] - along * d[2]];
+    const offsetKm = Math.hypot(w[0], w[1], w[2]);
+    const tanF1 = (R_SUN_KM + R_MOON_KM) / dl;                 // penumbral half-angle
+    const tanF2 = (R_SUN_KM - R_MOON_KM) / dl;                 // umbral half-angle
+    const penumbraKm = R_MOON_KM + along * tanF1;
+    const umbraKm = along * tanF2 - R_MOON_KM;                 // signed: >0 annular, <0 total
+    // Besselian magnitude convention: SIGNED umbral radius in the
+    // denominator — total events read >1 at the centre, annular <1.
+    const magnitude = (penumbraKm - offsetKm) / (penumbraKm + umbraKm);
+    return { offsetKm, penumbraKm, umbraKm, magnitude };
+  }
+
+  /**
+   * Local circumstances for an observer around one solar eclipse.
+   * Scans ±4 h around jdGreatest at 30 s, bisects contacts to ~1 s.
+   * @param {number} jdGreatest - the finder's greatest-eclipse JD(UT)
+   * @param {number} latDeg @param {number} lonDeg
+   * @returns {{kind: 'none'|'partial'|'annular'|'total',
+   *   magnitude: number, maxJd: number,
+   *   contacts: {c1: number|null, c2: number|null, c3: number|null, c4: number|null},
+   *   centralDurationSeconds: number|null}}
+   */
+  function localCircumstances(jdGreatest, latDeg, lonDeg) {
+    const HALF_WIN = 4 / 24, STEP = 30 / 86400;
+    // maximum: minimize offset − nothing fancier than a fine scan + refine
+    let best = { t: jdGreatest, magnitude: -Infinity };
+    for (let t = jdGreatest - HALF_WIN; t <= jdGreatest + HALF_WIN; t += STEP) {
+      const st = shadowStateAt(t, latDeg, lonDeg);
+      if (st.magnitude > best.magnitude) best = { t, magnitude: st.magnitude };
+    }
+    // golden-section-ish refine on magnitude around the best sample
+    let lo = best.t - STEP, hi = best.t + STEP;
+    for (let i = 0; i < 30; i++) {
+      const m1 = lo + (hi - lo) / 3, m2 = hi - (hi - lo) / 3;
+      if (shadowStateAt(m1, latDeg, lonDeg).magnitude
+        < shadowStateAt(m2, latDeg, lonDeg).magnitude) lo = m1; else hi = m2;
+    }
+    const maxJd = (lo + hi) / 2;
+    const atMax = shadowStateAt(maxJd, latDeg, lonDeg);
+
+    /** Bisect a sign change of fn between a (negative) and b (positive).
+     *  @param {(t: number) => number} fn @param {number} a @param {number} b
+     *  @returns {number} */
+    const bisect = (fn, a, b) => {
+      for (let i = 0; i < 40; i++) {
+        const m = (a + b) / 2;
+        if (fn(m) < 0) a = m; else b = m;
+      }
+      return (a + b) / 2;
+    };
+    /** @param {number} t @returns {number} >0 inside the penumbra */
+    const penEdge = (t) => {
+      const st = shadowStateAt(t, latDeg, lonDeg);
+      return st.penumbraKm - st.offsetKm;
+    };
+    /** @param {number} t @returns {number} >0 inside the central zone */
+    const umbEdge = (t) => {
+      const st = shadowStateAt(t, latDeg, lonDeg);
+      return Math.abs(st.umbraKm) - st.offsetKm;
+    };
+
+    /** @type {{c1: number|null, c2: number|null, c3: number|null, c4: number|null}} */
+    const contacts = { c1: null, c2: null, c3: null, c4: null };
+    let kind = /** @type {'none'|'partial'|'annular'|'total'} */ ('none');
+    if (penEdge(maxJd) > 0) {
+      kind = 'partial';
+      // outer contacts: walk out from max until outside, then bisect
+      for (let t = maxJd; t >= maxJd - HALF_WIN; t -= STEP) {
+        if (penEdge(t) < 0) { contacts.c1 = bisect(penEdge, t, t + STEP); break; }
+      }
+      for (let t = maxJd; t <= maxJd + HALF_WIN; t += STEP) {
+        if (penEdge(t) < 0) { contacts.c4 = bisect(/** @param {number} x */ (x) => -penEdge(x), t - STEP, t); break; }
+      }
+      if (umbEdge(maxJd) > 0) {
+        kind = atMax.umbraKm < 0 ? 'total' : 'annular';
+        for (let t = maxJd; t >= maxJd - HALF_WIN; t -= STEP) {
+          if (umbEdge(t) < 0) { contacts.c2 = bisect(umbEdge, t, t + STEP); break; }
+        }
+        for (let t = maxJd; t <= maxJd + HALF_WIN; t += STEP) {
+          if (umbEdge(t) < 0) { contacts.c3 = bisect(/** @param {number} x */ (x) => -umbEdge(x), t - STEP, t); break; }
+        }
+      }
+    }
+    const centralDurationSeconds = (contacts.c2 !== null && contacts.c3 !== null)
+      ? (contacts.c3 - contacts.c2) * 86400 : null;
+    return { kind, magnitude: Math.max(0, atMax.magnitude), maxJd, contacts, centralDurationSeconds };
+  }
+
+  return { umbraGroundAt, shadowStateAt, localCircumstances };
+}
+
+module.exports = { createBesselian };

package/src/model.js

@@ -32,6 +32,7 @@ import { createChainCycleIntegrator } from './chain-cycles/index.cjs';
 import { createMoonArguments, jdToDecimalYear } from './moon/arguments.cjs';
 import { createMoonSeries } from './moon/series.cjs';
 import { createEclipseFinders } from './eclipse/finders.cjs';
+import { createBesselian } from './eclipse/besselian.cjs';
 import { driver2PeriodSecondsAtAge } from './planets/orbit-chain.cjs';
 
 /**
@@ -769,6 +770,9 @@ export function assembleModel(C, F) {
     constants: {
       moonL: F.MEEUS_LONGITUDE_TERMS,
       moonB: F.MEEUS_LATITUDE_TERMS,
+      moonR: F.MEEUS_DISTANCE_TERMS.terms,
+      moonRMeanKm: F.MEEUS_DISTANCE_TERMS.meanKm,
+      moonDistanceJ2000Km: C.moonReference.moonDistance,
       j2000JD,
       julianCenturyDays,
       moonMeeusLpCorrectionDeg: C.moon.moonMeeusLpCorrection,
@@ -813,6 +817,39 @@ export function assembleModel(C, F) {
     },
   });
 
+  // 20.3g — the solar-eclipse LOCATION tier: shadow geometry on the FULL
+  // series (sceneEvalAt — the truncated finder forms omit the fitted Lp
+  // anchor and the −2235·sin(Lp) β family, deliberate for finder
+  // statistics, required here) at the model's ABSOLUTE TT (deltaTStart +
+  // curve, the same convention every other ΔT consumer reads). Both axis
+  // conventions are measured against the NASA path-table centerlines —
+  // see eclipse/besselian.cjs.
+  const besselian = createBesselian({
+    moonFullAtDaysTT: /** @param {number} dDaysTT */ (dDaysTT) => {
+      const ev = moonSeries.sceneEvalAt(dDaysTT);
+      return { lonDeg: ev.lonDeg, latDeg: ev.latDeg, distKm: ev.distKm };
+    },
+    sunLonDegAt: /** @param {number} jdUT */ (jdUT) => eclipseFinders.sunLonDegAt(jdUT),
+    deltaTSecondsAt: /** @param {number} jd */ (jd) => (jdTTFromUT(jd) - jd) * 86400,
+    obliquityDegAt: obliquityDeg,
+    eccentricityAt,
+    perihelionLongitudeDegAt: earthPerihelionDeg,
+    yearFromJD,
+    constants: {
+      j2000JD,
+      julianCenturyDays,
+      earthDiameterKm: C.bodyDiametersKm.earth,
+      moonDiameterKm: C.bodyDiametersKm.moon,
+      sunDiameterKm: C.bodyDiametersKm.sun,
+      sunDistanceKm: currentAUDistance,
+      earthFlatteningInverse: C.physicalConstants.earthFlatteningInverseWGS84,
+      ttBridgeSeconds: C.earthOrbital.deltaTStart,
+      gmstMeanSiderealT0Deg: C.physicalConstants.gmstMeanSiderealT0Deg,
+      gmstMeanSiderealRateDegPerDay: C.physicalConstants.gmstMeanSiderealRateDegPerDay,
+      gmstMeanSiderealT2Deg: C.physicalConstants.gmstMeanSiderealT2Deg,
+    },
+  });
+
   // ── The assembled surface ─────────────────────────────────────────────────
   return Object.freeze({
     time: Object.freeze({
@@ -871,6 +908,9 @@ export function assembleModel(C, F) {
       findLunarInRange: /** @param {number} jdStart @param {number} jdEnd */ (jdStart, jdEnd) => eclipseFinders.findLunarEclipsesInRange(jdStart, jdEnd),
       findSolarInRange: /** @param {number} jdStart @param {number} jdEnd */ (jdStart, jdEnd) => eclipseFinders.findSolarEclipsesInRange(jdStart, jdEnd),
       deltaTSecondsAtJD: frameworkDeltaTSecondsAtJD,
+      // 20.3g location tier (see eclipse/besselian.cjs):
+      umbraGroundAtJD: /** @param {number} jd @returns {{latDeg: number, lonDeg: number} | null} */ (jd) => besselian.umbraGroundAt(jd),
+      solarLocalCircumstances: /** @param {number} jdGreatest @param {number} latDeg @param {number} lonDeg */ (jdGreatest, latDeg, lonDeg) => besselian.localCircumstances(jdGreatest, latDeg, lonDeg),
     }),
     climate: Object.freeze({
       l1OrbitalPermil: evalClimateL1,

package/src/moon/series.cjs

@@ -35,6 +35,9 @@
  *   constants: {
  *     moonL: MeeusTermTable,
  *     moonB: MeeusTermTable,
+ *     moonR: MeeusTermTable,
+ *     moonRMeanKm: number,
+ *     moonDistanceJ2000Km: number,
  *     j2000JD: number,
  *     julianCenturyDays: number,
  *     moonMeeusLpCorrectionDeg: number,
@@ -64,7 +67,7 @@
  */
 function createMoonSeries({ constants, fns }) {
   const {
-    moonL, moonB, j2000JD, julianCenturyDays,
+    moonL, moonB, moonR, moonRMeanKm, moonDistanceJ2000Km, j2000JD, julianCenturyDays,
     moonMeeusLpCorrectionDeg, fwA2RateDegPerCy, fwA3RateDegPerCy,
   } = constants;
   const {
@@ -115,6 +118,40 @@ function createMoonSeries({ constants, fns }) {
     return s;
   }
 
+  /** Σr table pass — COSINE of the argument (Meeus 47.A distance column),
+   *  same E/E² convention. Units 0.001 km.
+   *  @param {MeeusTermTable} table @param {number} Dr @param {number} Mr
+   *  @param {number} Mpr @param {number} Fr @param {number} E
+   *  @param {number} E2 @returns {number} */
+  function sumTableCos(table, Dr, Mr, Mpr, Fr, E, E2) {
+    let s = 0;
+    for (let i = 0; i < table.length; i++) {
+      const r = table[i];
+      if (r[4] === 0) continue;
+      const arg = r[0] * Dr + r[1] * Mr + r[2] * Mpr + r[3] * Fr;
+      let term = r[4] * Math.cos(arg);
+      const absM = r[1] < 0 ? -r[1] : r[1];
+      if (absM === 1) term *= E;
+      else if (absM === 2) term *= E2;
+      s += term;
+    }
+    return s;
+  }
+
+  /** Full Meeus Ch. 47 distance: r = meanKm + Σr·10⁻³ km, scaled by the
+   *  framework's Driver-1 distance ratio (≡ 1 at J2000; the epoch-mutable
+   *  getter over the J2000 constant, preserving the deep-time scaling the
+   *  previous two-term ellipse form carried). ~2 km vs JPL at syzygy where
+   *  the two-term form was ~5,700 km too far (the 2D-family terms all peak
+   *  at eclipses).
+   *  @param {number} Dr @param {number} Mr @param {number} Mpr
+   *  @param {number} Fr @param {number} E @param {number} E2
+   *  @returns {number} km */
+  function fullDistanceKm(Dr, Mr, Mpr, Fr, E, E2) {
+    const Sr = sumTableCos(moonR, Dr, Mr, Mpr, Fr, E, E2);
+    return (moonRMeanKm + Sr * 1e-3) * (getMoonDistanceKm() / moonDistanceJ2000Km);
+  }
+
   /** The PRODUCTION scene evaluation at d days TT from J2000 (the caller
    *  owns the UT→TT conversion — engine timing conventions differ).
    *  Returns everything the scene blocks write:
@@ -155,7 +192,7 @@ function createMoonSeries({ constants, fns }) {
     const fullSl = Sl + (2 * eocHalf / D2R * 1e6) * Math.sin(Mpr)
                      + (1.25 * eocHalf * eocHalf / D2R * 1e6) * Math.sin(2 * Mpr);
     const lonDeg = Lp / D2R + fullSl * 1e-6 + moonMeeusLpCorrectionDeg;
-    const distKm = getMoonDistanceKm() * (1 - getEccentricityBase() * Math.cos(Mpr));
+    const distKm = fullDistanceKm(Dr, Mr, Mpr, Fr, E, E2);
     return { thetaAddRad, lonDeg, latRad, latDeg, distKm, T };
   }
 
@@ -197,12 +234,15 @@ function createMoonSeries({ constants, fns }) {
     return sumTable(moonB, Dr, Mr, Mpr, Fr, E, E2) * 1e-6;
   }
 
-  /** Two-term ellipse distance at JD_UT (shared with the scene form).
+  /** Full Meeus Ch. 47 distance at JD_UT (shared with the scene form).
    *  @param {number} jdUT @returns {number} km */
   function truncatedDistanceKm(jdUT) {
     const jdTT = jdUT + deltaTSeconds(jdUT) / 86400;
-    const Mpr = argsAt(jdTT).Mp * D2R;
-    return getMoonDistanceKm() * (1 - getEccentricityBase() * Math.cos(Mpr));
+    const T = (jdTT - j2000JD) / julianCenturyDays;
+    const args = argsAt(jdTT);
+    const Dr = args.D * D2R, Mr = args.M * D2R, Mpr = args.Mp * D2R, Fr = args.F * D2R;
+    const E = eFactorAtJdTT(jdTT, T, T * T);
+    return fullDistanceKm(Dr, Mr, Mpr, Fr, E, E * E);
   }
 
   return { sceneEvalAt, truncatedLonDeg, truncatedBetaDeg, truncatedDistanceKm, additionalArgs };