@essrt/physics 7.0.0 → 9.1.0

package/src/earth/frame-of-date.cjs

@@ -0,0 +1,105 @@
+/**
+ * The Earth frame of date — ONE home (holisticuniverse plan 06, R4 "one Earth
+ * frame": the scene's axis, equinox and sun plane placed from the engine).
+ *
+ * The one-source movement's sample carries, at a year, the obliquity ε, the
+ * equinox node's longitude in the J2000 ecliptic frame and the orbit normal's
+ * in-plane components. From those three the full frame follows, all unit
+ * vectors in the J2000 ecliptic frame the chain artifact uses:
+ *
+ *   n̂ — the ecliptic pole of date (the orbit normal; the sun plane's normal)
+ *   ĝ — the equinox of date: the ascending node of the ecliptic of date on the
+ *       equator of date, ĝ ∝ ŝ × n̂; it lies in the ecliptic of date at the
+ *       sample's node longitude
+ *   ŝ — the spin axis (the celestial pole of date): the ecliptic pole tilted by
+ *       ε toward longitude ĝ + 90° — ŝ = cos ε·n̂ + sin ε·(n̂ × ĝ)
+ *
+ * so that ĝ = unit(ŝ × n̂) and ε = ∠(ŝ, n̂) hold by construction. Reconstructing
+ * from ANGLES (not from stored vectors) keeps the grid interpolation exact: the
+ * node longitude is Hermite-interpolated by the sampler, the normal components
+ * and ε are smooth.
+ *
+ * Both scene twins (src/script.js, tools/lib/scene-graph.js) place the axis,
+ * the sun plane and the Sun from this frame every frame — no relative
+ * corrections on a device geometry (the retired tilt/azimuth/apsidal/plane
+ * corrections and the δ Newton read: docs/41). Measured before the change:
+ * the K sun plane and the RA frame's ecliptic parted by 20.5″ at J2000 and 10′
+ * at −3000, the rendered Sun −19″ in declination against Horizons at the
+ * March 2000 equinox (+19″ in September; 0.1–1″ at the solstice).
+ */
+'use strict';
+
+const D2R = Math.PI / 180;
+
+/**
+ * @typedef {{x: number, y: number, z: number}} Vec3
+ */
+
+/** @param {number[]} a @param {number[]} b @returns {number[]} */
+function cross(a, b) {
+  return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+/** @param {number[]} v @returns {number[]} */
+function unit(v) {
+  const n = Math.hypot(v[0], v[1], v[2]);
+  return [v[0] / n, v[1] / n, v[2] / n];
+}
+
+/**
+ * The Earth frame of date from a one-source sample, unit vectors in the J2000
+ * ecliptic frame: `n` the ecliptic pole of date, `g` the equinox of date, `s`
+ * the spin axis of date. Every vector is `[x, y, z]`.
+ * @param {{epsDeg: number, equinoxLonJ2000Deg: number, orbitNormalX: number, orbitNormalY: number}} sample
+ * @returns {{n: number[], g: number[], s: number[]}}
+ */
+function computeEarthFrameOfDate(sample) {
+  const nx = sample.orbitNormalX, ny = sample.orbitNormalY;
+  const nz = Math.sqrt(Math.max(0, 1 - nx * nx - ny * ny));
+  const n = [nx, ny, nz];
+  // the equinox: in the ecliptic of date (⟂ n̂), at the sampled longitude L
+  // measured in the J2000 ecliptic — the unit vector (cos L, sin L, z) with
+  // z fixed by ĝ·n̂ = 0
+  const L = sample.equinoxLonJ2000Deg * D2R;
+  const gx = Math.cos(L), gy = Math.sin(L);
+  const gz = -(nx * gx + ny * gy) / nz;
+  const g = unit([gx, gy, gz]);
+  // the spin axis: the pole tilted by ε from n̂ toward longitude ĝ + 90°
+  const eps = sample.epsDeg * D2R;
+  const w = cross(n, g);   // the in-plane direction at ĝ + 90°
+  const s = unit([
+    Math.cos(eps) * n[0] + Math.sin(eps) * w[0],
+    Math.cos(eps) * n[1] + Math.sin(eps) * w[1],
+    Math.cos(eps) * n[2] + Math.sin(eps) * w[2],
+  ]);
+  return { n, g, s };
+}
+
+/**
+ * The wheel angle θ that puts the Sun at ecliptic longitude λ on the scene's
+ * offset circle: the Sun sits at radius 1 (100 scene units) about a centre
+ * displaced by −e along the perihelion direction ϖ (the one eccentricity law's
+ * single arm), P(θ) = −e·û(ϖ) + û(θ), and the geocentric longitude is the
+ * direction of P. Two Newton steps from θ₀ = λ (the offset-circle Jacobian
+ * dλ/dθ = 1 − e·cos(θ − ϖ) + O(e²)); converged to <1e-12 rad for e < 0.1.
+ * Angles in radians; θ increases with λ (the scene's node angles are
+ * λ-handed).
+ * @param {number} lambdaRad - the target geocentric ecliptic longitude
+ * @param {number} e - the eccentricity (the centre offset in units of the radius)
+ * @param {number} periRad - the perihelion longitude ϖ of date (the offset direction is −û(ϖ))
+ * @returns {number} θ in radians, in (−π, π]
+ */
+function solveWheelAngleForLongitude(lambdaRad, e, periRad) {
+  const cx = -e * Math.cos(periRad), cy = -e * Math.sin(periRad);
+  let th = lambdaRad;
+  for (let k = 0; k < 3; k++) {
+    const px = cx + Math.cos(th), py = cy + Math.sin(th);
+    const lam = Math.atan2(py, px);
+    const r2 = px * px + py * py;
+    const dLamDth = (px * Math.cos(th) + py * Math.sin(th)) / r2;   // d atan2(py, px)/dθ
+    const err = Math.atan2(Math.sin(lambdaRad - lam), Math.cos(lambdaRad - lam));
+    th += err / dLamDth;
+  }
+  return Math.atan2(Math.sin(th), Math.cos(th));
+}
+
+module.exports = { computeEarthFrameOfDate, solveWheelAngleForLongitude };

package/src/eclipse/besselian.cjs

@@ -30,19 +30,36 @@
  *     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.
+ *  2. Full series, not the truncated finder forms. truncatedBetaDeg omits
+ *     the −2235·sin(Lp) latitude family (~8″) and both truncated forms omit
+ *     the derived series-extension tail — deliberate for the certified
+ *     finder statistics (knife-edge canon events), required here. The
+ *     injected moonFullAtDaysTT is the series' sceneEvalAt — the same
+ *     evaluation the browser scene ships (the extension inside it since
+ *     plan 06 R3 item 1: one scene Moon).
  *
- * 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.
+ * APPARENT PLACES (plan 06 R3 item 1 — measured, the cancellation the I2
+ * Sun exposed): both bodies are evaluated mean-of-date (nutation is a common
+ * rotation of Sun and Moon and cancels in the elongation) but with their
+ * PLANETARY ABERRATION: the Sun's derived κ = 2π a/(c T_sid √(1−e²))
+ * (≈20.5″, the light-time of a source at rest in the barycentric frame) and
+ * the Moon's RELATIVE light-time (its geocentric motion during dist/c,
+ * ≈0.7″). For a body co-moving with the observer the stellar aberration
+ * cancels against its barycentric light-time displacement — Horizons'
+ * apparent Moon coincides with the geometric Moon to that 0.7″ (the
+ * truncated series + extension read −1.0″ ± 1.5″ against it over
+ * 1970–2049, flat in elongation) — so "aberrate both bodies, it cancels at
+ * syzygy" (the former round-3 reasoning) was the wrong physics: it held the
+ * Moon 20.5″ from its apparent place, and the fitted moonMeeusLpCorrection
+ * (+32.75″ = κ + the Sun's then-missing long inequality + the trend-ΔT
+ * offset) absorbed it. That anchor is retired (0) with the Sun's κ applied
+ * here. The mean sidereal time of the Earth-fixed mapping pairs with the
+ * mean equinox of the body longitudes as before.
+ *
+ * The remaining centerline residual on NASA's UT instants (2–5″ in
+ * 1999–2026) is the model's TREND ΔT against the observed one (9.5 s below
+ * IERS at 2000, 2.9 s at 2024, × the Moon's 0.55″/s) — a ΔT-convention
+ * floor, never to be fitted here.
  *
  * The scene-umbra conventions (THREE scaffold navigation) never enter this
  * package (§2h) — this is an independent construction on the shared
@@ -58,7 +75,7 @@
  *   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 {(T: number) => number} sunCompletionDeg - planetary completion (deg) at T centuries TT, SUBTRACTED from the finder sun (see eclipse/sun-planetary-completion.cjs; the finders deliberately stay without it — their fitted anchors and certified canon statistics were produced on the bare form, and elongation-class timing absorbs the omission into the fitted phases)
- * @property {(T: number) => {dLonDeg: number, dLatDeg: number}} moonExtensionAt - derived series-extension tail (deg) at T centuries TT, ADDED to the full-series Moon longitude/latitude (see moon/series-extension.cjs; same finder-scoping rationale as sunCompletionDeg — the finders stay on the bare series)
+ * @property {(year: number) => number} sunAberrationDegAt - the Sun's derived planetary aberration κ (deg) at calendar year, SUBTRACTED from the geometric Sun longitude (the apparent Sun; see the header)
  * @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
@@ -68,7 +85,7 @@
  *   moonDiameterKm: number, sunDiameterKm: number, sunDistanceKm: number,
  *   earthFlatteningInverse: number, ttBridgeSeconds: number,
  *   gmstMeanSiderealT0Deg: number, gmstMeanSiderealRateDegPerDay: number,
- *   gmstMeanSiderealT2Deg: number }} constants
+ *   gmstMeanSiderealT2Deg: number, speedOfLightKmS: number }} constants
  */
 
 /** @param {BesselianDeps} deps */
@@ -125,12 +142,19 @@ function createBesselian(deps) {
     const year = deps.yearFromJD(jb);
     const eps = deps.obliquityDegAt(year) * D2R;
     const dTT = (jb - K.j2000JD) + deps.deltaTSecondsAt(jb) / 86400;
-    const sunLon = deps.sunLonDegAt(jb) - deps.sunCompletionDeg(dTT / K.julianCenturyDays);
+    // the APPARENT Sun: geometric completed longitude minus its derived aberration κ
+    const sunLon = deps.sunLonDegAt(jb) - deps.sunCompletionDeg(dTT / K.julianCenturyDays) - deps.sunAberrationDegAt(year);
+    // the APPARENT Moon: the geometric series displaced by its RELATIVE light-time —
+    // the Moon's own geocentric motion (central difference, a point rate at this
+    // instant, never a mean rate × span) during τ = dist/c
     const moon = deps.moonFullAtDaysTT(dTT);
-    const ext = deps.moonExtensionAt(dTT / K.julianCenturyDays);
+    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 tauDays = moon.distKm / K.speedOfLightKmS / 86400;
     return {
       S: eclToEq(sunLon, 0, sunDistanceKm(year, sunLon), eps),
-      M: eclToEq(moon.lonDeg + ext.dLonDeg, moon.latDeg + ext.dLatDeg, moon.distKm, eps),
+      M: eclToEq(moon.lonDeg - moonRateDegPerDay * tauDays, moon.latDeg, moon.distKm, eps),
     };
   }
 

package/src/eclipse/sun-planetary-completion.cjs

@@ -22,9 +22,23 @@
  * THE CARRIERS (FQ-5 N3, the doctrine's final mile for the Sun side):
  * the six planetary mean-longitude RATES are no longer instrument
  * literals — they are INJECTED by the model wiring, computed live from
- * the framework's own planet records (one revolution per the record's
- * tropical period; Earth from the framework mean solar year), as is the
- * Moon-elongation rate for the EMB-wobble carrier. The J2000 phase
+ * the framework's own planet records, as is the Moon-elongation rate for
+ * the EMB-wobble carrier. PLAN 06 I2 — the injected rates are SIDEREAL
+ * (the record's of-date rate minus the model's own J2000 precession;
+ * Earth the framework sidereal year; model.js): a perturbation argument
+ * is inertial (D'Alembert — only Σk = 0 arguments are frame-free), and
+ * on the N3 of-date carriers every Σk ≠ 0 row (3V−4E, E−2J, 2V−3E,
+ * 2E−3J, 2E−3M, 2M−E, 2(2M−E) …) drifted by Σk·ψ(t): 42..52° at −3000,
+ * measured against JPL Horizons over ±3000 yr as the dominant ancient
+ * scatter of the certified Sun (6.4″ → 4.4″ at −3000, 6.0 → 4.6″ at
+ * −2000, 3.6 → 3.0″ at 0 AD on sidereal carriers; 1900–2100 unchanged).
+ * The 70 N3 literals are KEPT: the two carrier sets share the J2000
+ * anchors and part by ≤ 1.4°·|Σk| at the 200-yr window's edges, and the
+ * re-extraction on sidereal carriers (tools/explore/i2-sidereal-carrier-
+ * table.mjs) reproduces the composed function (fidelity 0.612 vs 0.614″,
+ * JPL 1900–2100 all-phase sd identical to 0.01″) while redistributing
+ * the near-degenerate ±M sideband pairs — only the composed function
+ * ships, so the literals stay as extracted. The J2000 phase
  * anchors (ARG_L0, PERI, D0) remain declared epoch constants — the
  * "anchored by design" class; any constant phase offset is absorbed into
  * the fitted cos/sin split exactly. N3 gates measured before the swap:
@@ -80,7 +94,7 @@
  * check`) recomputes it from live constants and fails on mismatch. The
  * carrier↔table pairing is enforced by both living in this one module
  * with the rates injected from the same constants the records read. The
- * api centerline gate (≤8″ shadow-plane) backstops gross staleness
+ * api centerline gate (≤12″ shadow-plane) backstops gross staleness
  * independently.
  *
  * FQ-5 N2 RECORD (the carrier attribution): 8/10 carriers measured
@@ -115,6 +129,26 @@ const ARG_D0 = 297.8501921;
  * composed difference vs the previous table ≤1.5″ at the ancient presets,
  * detrended 0.033 min). Individual coefficients redistribute between the
  * near-degenerate ±M sideband families; only the composed function ships.
+ *
+ * PLAN 06 I2 — the LONG-PERIOD rows (the last two): the Earth–Mars–
+ * Jupiter long inequality 4λ_E − 8λ_Ma + 3λ_J (carrier period 1801 yr;
+ * the classical ~1783-yr term of the solar theory) and the Venus–Earth
+ * term 8λ_V − 13λ_E (238 yr), DERIVED on the model's own Wisdom–Holman
+ * engine (tools/explore/nbody-wh.mjs, the chain artifact's integrator) on
+ * the campaign's ONE Horizons J2000 seed, Sun + eight planets, DE440
+ * masses, 1PN, order 2, dt 2 d, −5100..+1100 yr: the EMB's osculating
+ * mean longitude Ω+ω+M in yearly means, LSQ on [1, T, T²] + cos/sin of
+ * the arguments on THESE carriers (tools/explore/i2-long-inequality.mjs).
+ * Measured: 6.27″ / 1.84″; step-converged (dt 1 d: 6.272 / 1.869); the
+ * integration reproduces DE441's Earth longitude to 0.68″ sd over 6000
+ * yr with 0.03″ left at the 1783-yr argument. Neither could come from the
+ * 200-yr D2 window (the term's in-window ramp went to the projected-out
+ * secular basis; the 240-yr term folded into it). WHY they were missing:
+ * the certified Sun integrates a smooth tropical year for its mean
+ * longitude; against Horizons its residual carried exactly this 6″ ripple
+ * (plan 06 I1 analysis) — with the same phase in the sidereal residual, a
+ * perturbation of Earth's mean motion, not a frame effect. Sub-0.2″
+ * candidates left out (2J−5S 0.17″, 5V−8E 0.17″: window-dependent phase).
  * @type {Array<[number[], number[], number, number]>}
  */
 const TERMS = [
@@ -188,6 +222,9 @@ const TERMS = [
   [[0, 0, 1, -1, 0, 0], [0, 0, 1, 0, 0, 0], 0.0188, 0.0523],
   [[0, 2, -2, 0, 0, 0], [0, 0, 1, 0, 0, 0], -0.0421, -0.0340],
   [[0, 0, 1, -1, 0, 0], [0, 0, -1, 0, 0, 0], -0.0353, -0.0379],
+  // plan 06 I2 — the long-period rows (see the doc comment above)
+  [[0, 0, 4, -8, 3, 0], [0, 0, 0, 0, 0, 0], 6.2314, -0.7168],
+  [[0, 8, -13, 0, 0, 0], [0, 0, 0, 0, 0, 0], 1.8389, 0.1419],
 ];
 
 const D2R = Math.PI / 180;
@@ -247,15 +284,19 @@ function createSunPlanetaryCompletion({ embWobbleArcsec, carrierRatesDegPerCy })
 const PAIRED_SUN_HARMONICS_SHA256 = 'cbc189cea1c20292';   // eccentricity unification: Step-0 refit → N2/N3 re-derived (fidelity 0.616″, 70 terms)
 
 /** sha256/16 of JSON.stringify([...planets, moonElongation]) — the seven
- *  full-precision carrier rates (deg/cy TT) the TERMS table was extracted
- *  under at N3. The model wiring recomputes the rates live from the planet
- *  records, so a planet-period / year / month input change moves the
- *  carriers automatically while the table stays frozen — a silent few-
- *  arcsec stale below the api gate's ≤8″ backstop. test:model recomputes
- *  this fingerprint from live constants (identical arithmetic to model.js)
- *  and fails on mismatch: re-run the N3 extraction chain
- *  (tools/explore/n2-sun-framework-carriers.mjs →
- *  n3-carrier-swap-preview.mjs), re-embed TERMS, and update this value. */
-const PAIRED_CARRIER_RATES_SHA256 = '893e055ee12343bd';
+ *  full-precision carrier rates (deg/cy TT) the TERMS table pairs with:
+ *  the SIDEREAL carriers of plan 06 I2 (record rate − the model's J2000
+ *  precession; Earth the framework sidereal year; the N3 literals kept,
+ *  the two long-period rows derived on these rates). The model wiring
+ *  recomputes the rates live from the planet records, so a planet-period /
+ *  year / month input change moves the carriers automatically while the
+ *  table stays frozen — a silent few-arcsec stale below the api gate's
+ *  ≤12″ backstop. test:model recomputes this fingerprint from live
+ *  constants (identical arithmetic to model.js) and fails on mismatch:
+ *  re-run the extraction chain (tools/explore/n2-sun-framework-carriers.mjs
+ *  → i2-sidereal-carrier-table.mjs for the short-period rows,
+ *  i2-long-inequality.mjs for the long-period rows), re-embed TERMS, and
+ *  update this value. */
+const PAIRED_CARRIER_RATES_SHA256 = '2d066e92bae955e4';
 
 module.exports = { createSunPlanetaryCompletion, PAIRED_SUN_HARMONICS_SHA256, PAIRED_CARRIER_RATES_SHA256 };

package/src/index.js

@@ -114,6 +114,9 @@ export { createChainCycleIntegrator } from './chain-cycles/index.cjs';
 export { createMoonArguments } from './moon/arguments.cjs';
 export { createMoonSeries } from './moon/series.cjs';
 export { createMoonApparent } from './moon/apparent.cjs';
+// R4 — the Earth frame of date (sun plane, equinox, spin axis from the one-source
+// sample) and the offset-circle wheel-angle solver: the scene twins' one placement.
+export { computeEarthFrameOfDate, solveWheelAngleForLongitude } from './earth/frame-of-date.cjs';
 // Phase 8.3 — the planet machinery, extracted by LAW over body records
 // (survey order: geometry → Fibonacci laws → channels → chains).
 export { derivePlanetGeometry } from './planets/geometry.cjs';
@@ -124,9 +127,13 @@ export { integrateAscendingNode } from './planets/asc-node-integrator.cjs';
 export * as planetOrbitChain from './planets/orbit-chain.cjs';
 // P5/K4.6c — the engine-D Keplerian chain (pure evaluator + the embedded
 // governed artifact; the browser flag path consumes exactly these).
+export { computeSecularShape } from './planets/secular-shape.cjs';
 export { buildPlanetChainsFromArtifactData, computePlanetElementsAtYear, computeHeliocentricEclipticFromElements, computePoissonArgRad, computeOsculatingElements, solveKeplerRad, computeApsidalSecularDegPerYr, 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';
+// Plan 06 Phase 7 — the planets' spin channel (the precession constant from
+// each planet's own torques, the spin integrated on its own ζ plane history).
+export { computePlanetPrecessionConstant, createPlanetSpinChannel, createPlanetSpinChannelFromArtifacts, computeObliquityJ2000Deg } from './planets/spin-channel.cjs';
 export { CHAIN_ARTIFACT, CHAIN_ARTIFACT_HASH } from './planets/chain-artifact.js';
 // Engine-switch Stage B, T5d-(d): the deep-time Earth-z channel (the deep
 // lunar-chain modulation rides it; era consumers stay on the H/3 channel).
@@ -143,7 +150,8 @@ export { createYearLengths, ONE_FAMILY_WINDOW_YEARS } from './earth/year-lengths
 // (spin ω(t) × [solar torque + lunar torque on the recession history]) —
 // leg-1's physical rate; the structural H(t)/13 clock is its named diagnostic.
 export { computeSolarTorqueShare, createComposedPrecession } from './earth/precession-composed.cjs';
-export { createPredictivePrecession, calcPlanetPerihelionLongDeg } from './planets/predict.cjs';
+// (planets/predict.cjs — the planet predictive-precession feature basis — was
+// retired at plan 06 R8 with PREDICT_COEFFS_PHYSICAL; docs/retired-record.md.)
 // L10 — the composition front door: one law set, N body records. Thin by
 // design; engines keep their direct call sites (see planets/model.cjs).
 export { createPlanetModel } from './planets/model.cjs';