@essrt/physics 17.0.0 → 18.0.1

package/README.md

@@ -5,7 +5,8 @@ as implemented by the [ESSRT simulator](https://3d.holisticuniverse.com)
 ([source, AGPL-3.0](https://github.com/dvansonsbeek/3d)). Pure computation:
 no I/O, no globals, no DOM, constants injected. The package ships the
 **complete model**, including the fitted coefficients, so an installed copy
-reproduces the hosted simulator bit-for-bit on the shared golden masters.
+reproduces the simulator's engine on the shared golden masters (bit-exact in
+Node; the browser build is held to a measured cross-runtime tolerance).
 
 ## Versioning — two axes, deliberately
 
@@ -39,10 +40,13 @@ subpath export) generated from the sources' JSDoc — `import` from
 `@essrt/physics` or any subpath is fully typed; no ambient shim needed.
 
 See the `exports` map in `package.json` for the full surface: moon
-(arguments/series/apparent/ecc-channel/month-chain), planets (geometry,
-corrections, predict, model, fibonacci-laws, …), deltat (cycles, deep-time,
-historical), cardinal points, phase, chain-cycles, sun, climate, eclipse
-finders, and the published reference curves.
+(arguments, series, series-extension, apparent, ecc-channel,
+deep-ecc-channel, month-chain), earth (year-lengths, precession-composed,
+frame-of-date, sidereal-year-channel, deep-orbital-history), planets
+(keplerian-chain, orbit-chain, secular-shape, secular-series,
+inv-plane-frame, spin-channel, ecc-channel, geometry, model), deltat
+(cycles, deep-time, recession-history, historical), cardinal points, phase,
+chain-cycles, sun, climate and eclipse finders.
 
 For rendered display values (day/year lengths, precession rates, orbital
 elements as preformatted strings), see
@@ -57,10 +61,11 @@ The canonical assembly, wired once inside the package:
 import { createModel, DEFAULT_CONSTANTS } from '@essrt/physics';
 
 const model = createModel();
-model.identity.modelVersion;          // the shipped model identity (e.g. 'v11.0') + both content hashes
-model.epoch.hAtYear(2000 - 380e6);    // 306189 — Devonian H (the Wells 1963 match)
+model.identity.modelVersion;          // the shipped model identity (e.g. 'v21.0') + both content hashes
+model.lunisolar.meanPeriodYearsAtYear(2000 - 380e6); // 21699 — the Devonian precession period
+model.epoch.lodSecondsAtYear(2000 - 380e6);          // 78895 — the Devonian day (Wells 1963's coral count)
 model.earth.obliquityDeg(2000);       // 23.4393
-model.cardinal.jd(2000, 'SS');        // 2451716.5736 — June solstice 2000, the apparent Sun's crossing (USNO 2451716.575: the 2-min gap is the mean-longitude anchor convention, labelled)
+model.cardinal.jd(2000, 'SS');        // 2451716.5751 — June solstice 2000, the apparent Sun's crossing (USNO 2451716.575)
 model.lengths.tropicalYearDays(2000); // 365.24219
 
 // Counterfactual (§2d): inject different constants, get a different solar
@@ -69,22 +74,27 @@ const cf = createModel({
   ...DEFAULT_CONSTANTS,
   foundational: { ...DEFAULT_CONSTANTS.foundational, holisticyearLength: 400000 },
 });
-cf.epoch.hAtYear(2000);               // 400000
+cf.epoch.hAtYear(2000);               // 400000 — the anchor unit (a fit constant, not a period)
 cf.identity.counterfactual;           // true
 ```
 
 The surface groups: `time` (exact JD ↔ model-year conversion on the SI
 axis the fits were anchored on — callers holding a JD convert here, never
 with their own formula), `identity` (version + hashes + citation DOI), `epoch`
-(H, LOD, α, ΔT, deep-time quantities at any year ±500 Myr), `earth`
+(the internal unit, LOD, α, ΔT, the precession period and the deep-time
+quantities at any year ±500 Myr), `lunisolar` (the mean lunisolar precession
+period and rate at any year, its solar/lunar torque split, the nodal mode
+and the obliquity beat, the apsidal and perihelion-of-date periods and their
+ratios over the published window), `earth`
 (obliquity, eccentricity, inclination, perihelion), `lengths` (year and
 day lengths), `cardinal` (solstice/equinox JD, RA, year length), `moon`
 (distance and months at epoch, plus the apparent-position chain on the
 JD(UT) axis — ecliptic longitude, latitude and distance from the shared
 Meeus series over framework-native arguments), `eclipse` (geocentric
 solar/lunar eclipse search over a JD window, greatest-eclipse convention),
-`climate` (the L1 orbital-forcing formula) and `planets` (the retired integer-law
-records and orientation at epoch). Validation targets are refused as
+`climate` (the L1 orbital-forcing formula) and `planets` (the N-body chain's
+elements of date — perihelion longitude, node and inclination on the
+invariable plane, eccentricity — and spin). Validation targets are refused as
 inputs — a counterfactual cannot move the goalposts it is judged by.
 
 ### The series artifact
@@ -105,7 +115,7 @@ createModel().earth.eccentricity(2000 - 100000);   // 0.03374 — the mode table
 Without the artifact `createModel()` evaluates the embedded 18-term mode
 table at every epoch: exact at J2000, a compact approximation away from it
 (RMS 3.6·10⁻³ in e against La2010a over the last 500 kyr, where the series
-reads 2.5·10⁻⁵). The hosted API, the MCP server and the simulator always
+reads 2.5·10⁻⁵). The API handler, the MCP server and the simulator always
 pass the artifact.
 
 ## Underneath: a parts library

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@essrt/physics",
-  "version": "17.0.0",
+  "version": "18.0.1",
   "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": "v21.0",

package/src/index.js

@@ -126,7 +126,7 @@ export { computeEarthFrameOfDate, solveWheelAngleForLongitude } from './earth/fr
 // (planets/fibonacci-laws), the record-based orientation forms
 // (planets/orientation) and the ascending-node integrator
 // (planets/asc-node-integrator) are DELETED at plan 07 R5/R6: the planets'
-// elements of date have one home, the N-body chain; docs/retired-record.md.
+// elements of date have one home, the N-body chain.
 export { derivePlanetGeometry } from './planets/geometry.cjs';
 export { eccentricityFromCycles, computeEccentricityIntegrated } from './planets/ecc-channel.cjs';
 export * as planetOrbitChain from './planets/orbit-chain.cjs';
@@ -156,7 +156,7 @@ export { createYearLengths, ONE_FAMILY_WINDOW_YEARS } from './earth/year-lengths
 // leg-1's physical rate; the structural H(t)/13 clock is its named diagnostic.
 export { computeSolarTorqueShare, createComposedPrecession } from './earth/precession-composed.cjs';
 // (planets/predict.cjs — the planet predictive-precession feature basis — was
-// retired at plan 06 R8 with PREDICT_COEFFS_PHYSICAL; docs/retired-record.md.)
+// retired at plan 06 R8 with PREDICT_COEFFS_PHYSICAL.)
 // 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';

package/src/model.js

@@ -646,11 +646,30 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
   /** @param {number} year @returns {number} */
   const tropicalYearDirectDays = (year) => evalYearFourier(year, tropicalYearDaysBase(year), F.TROPICAL_YEAR_HARMONICS);
 
-  /** @param {number} year @returns {number} */
-  const solarYearSeconds = (year) => tropicalYearDays(year) * dayLengthSeconds(year);
-  /** @param {number} year @returns {number} */
-  const siderealDaySeconds = (year) => solarYearSeconds(year) / (tropicalYearDays(year) + 1);
-  /** @param {number} year @returns {number} */
+  /** Layer-4 solar day of date in SI seconds — LOD_real, the shipped
+   *  observable (the tweakpane Solar Day row, the registry's lodRealPhysical,
+   *  the Framework Verification panel's day): the kinematic day of date + the
+   *  ecliptic missing-motion term on the nodal period + the calibrated ΔT
+   *  cycle stack incl. the core-mantle swing. Twin of tools/lib
+   *  computeLodRealSecondsAtEpoch and the browser's _vfpSolarDaySecondsOfDate
+   *  (86,400.001780 s at 2000). @param {number} year @returns {number} */
+  const lodRealSeconds = (year) =>
+    dayLengthSeconds(year)
+    + (deepLod.eclipticLodCorrectionSecondsAtAge(yearToTMa(year)) ?? 0)
+    + dtCycleLodCorrectionSum(year);
+  /** Mean sidereal day of date in SI seconds — on LOD_real (plan 08 storyline
+   *  sweep, 2026-10-09: the published day bases are the SI day of exactly
+   *  86,400 s, the IAU constants, and LOD_real; this rode the KINEMATIC day
+   *  before, 1.7 ms below the simulator's readout at J2000). One rotation
+   *  more against the equinox than there are solar days in a year.
+   *  @param {number} year @returns {number} */
+  const siderealDaySeconds = (year) => {
+    const Y = tropicalYearDays(year);
+    return (lodRealSeconds(year) * Y) / (Y + 1);
+  };
+  /** Mean stellar day of date in SI seconds — the sidereal day plus the
+   *  equinox's daily regression projected onto the equator (on LOD_real, like
+   *  the sidereal day). @param {number} year @returns {number} */
   const stellarDaySeconds = (year) => {
     const tMa = yearToTMa(year);
     // S5 (plan 06): one equinox turn per T_p(t) — the composed lunisolar
@@ -658,13 +677,12 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
     // unit's counter H(t)/13 (0.086 % slow; 7 µs on the 8.37 ms offset).
     const TpRaw = deepLod.lunisolarPrecessionPeriodYearsAtAge(tMa);
     const Tp = TpRaw === null ? certifiedAxialPrecessionJ2000Years() : TpRaw;
-    const syS = solarYearSeconds(year);
     const syD = tropicalYearDays(year);
     const sidDay = siderealDaySeconds(year);
     // Layer A (plan 06): the RA projection reads the published ε (the one-source
     // hybrid), not the K comb — the browser's _sceneEpsTargetDeg twin; 1e-8 s.
     const raProjection = Math.cos((oneSourceM.epsAt(year) * Math.PI) / 180);
-    return (syS / (syD + 1) / Tp / (syD + 1)) * raProjection + sidDay;
+    return (sidDay / Tp / (syD + 1)) * raProjection + sidDay;
   };
   /** @param {number} year @returns {number} */
   const measuredSolarDaySeconds = (year) => dayLengthSeconds(year) + raDayOffsetMs(year) / 1000;
@@ -1488,7 +1506,15 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
     epoch: Object.freeze({
       yearToTMa,
       hAtYear: /** @param {number} year @returns {number|null} */ (year) => deepLod.hAtAge(yearToTMa(year)),
+      // The Layer-2 mean day of date — the tidal + GIA base the deep-time law
+      // gives at any age (86,399.9997 s at J2000): the day the paleo anchors
+      // and the ΔT integrand ride. NOT the observable solar day of date —
+      // that is lodRealSecondsAtYear below (plan 08 storyline sweep).
       lodSecondsAtYear: /** @param {number} year @returns {number|null} */ (year) => deepLod.lodSecondsAtAge(yearToTMa(year)),
+      // LOD_real of date — the Layer-4 observable (the simulator's Solar Day,
+      // the registry's lodRealPhysical): the kinematic day + the ecliptic term
+      // + the calibrated ΔT cycle stack. 86,400.001780 s at J2000.
+      lodRealSecondsAtYear: /** @param {number} year @returns {number} */ (year) => lodRealSeconds(year),
       alphaAtYear: /** @param {number} year @returns {number} */ (year) => earthMoiFactorAtAge(yearToTMa(year)),
       moonDistanceKmAtYear: /** @param {number} year @returns {number} */ (year) => moonDistanceMetresAtAge(yearToTMa(year)) / 1000,
       // D6: OF-DATE — mass-loss law / the banked planetary λ̇ ratio
@@ -1600,6 +1626,7 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
       siderealYearDays,
       anomalisticYearDays,
       dayLengthSeconds,
+      lodRealSeconds,
       siderealDaySeconds,
       stellarDaySeconds,
       measuredSolarDaySeconds,

package/src/planets/model.cjs

@@ -14,7 +14,7 @@
  * inclination amplitude/mean; K constant → eccentricity amplitude/base/
  * phase) are DELETED — K at plan 07 R6, ψ at plan 07 R5. A planet's
  * inclination and eccentricity of date have one home, the N-body chain
- * (model.js planetChainElementsAt); docs/retired-record.md is the record.
+ * (model.js planetChainElementsAt).
  *
  * THIN BY DESIGN. This is the composition surface, not a rewiring: both
  * engines keep their existing direct call sites, and the runtime channels

package/types/model.d.ts

@@ -28,6 +28,7 @@ export function assembleModel(C: Readonly<Record<string, any>>, F: Readonly<Reco
         yearToTMa: (year: number) => number;
         hAtYear: (year: number) => number | null;
         lodSecondsAtYear: (year: number) => number | null;
+        lodRealSecondsAtYear: (year: number) => number;
         alphaAtYear: (year: number) => number;
         moonDistanceKmAtYear: (year: number) => number;
         siderealYearSecondsAtYear: (year: number) => number;
@@ -86,6 +87,7 @@ export function assembleModel(C: Readonly<Record<string, any>>, F: Readonly<Reco
         siderealYearDays: (year: number) => number;
         anomalisticYearDays: (year: number) => number;
         dayLengthSeconds: (year: number) => number;
+        lodRealSeconds: (year: number) => number;
         siderealDaySeconds: (year: number) => number;
         stellarDaySeconds: (year: number) => number;
         measuredSolarDaySeconds: (year: number) => number;