@essrt/physics 4.9.0 → 6.0.0

package/src/earth/precession-composed.cjs

@@ -0,0 +1,144 @@
+/**
+ * The composed lunisolar precession rate — ONE home (holisticuniverse plan 06,
+ * D6: the physical ψ̇(t) of falsification leg 1).
+ *
+ * Earth's axial precession rate is the two tiers composed: the spin ω(t) from
+ * the tidal chain (LOD history) carries BOTH torques, and the lunar torque
+ * additionally grows with the recession history as (a₀/a_M(t))³:
+ *
+ *   ψ̇(t) = [ω(t)/ω₀] · p₀ · [ f_S + (1 − f_S) · (a₀/a_M(t))³ ]
+ *
+ * with p₀ the J2000 rate and f_S the solar fraction of the J2000 torque,
+ * derived from the shared constants (two-body point-mass torques with the
+ * (1 − e²)^(−3/2) eccentricity factors and the lunar-inclination factor
+ * 1 − 3/2·sin² i_M; ≈ 0.316, the textbook value). At J2000 every factor is 1.
+ *
+ * THE ANCHOR p₀ (plan 06 S5 — one J2000 precession reading): p₀ is the
+ * model's DERIVED J2000 rate, 1,296,000/axial0 with axial0 the certified
+ * year-length laws' beat at 2000 (sid/(sid − trop) = 25,771.4 yr = 50.2883
+ * ″/yr, IAU 50.2879 to 8×10⁻⁶) — the SAME anchor the hybrid obliquity
+ * self-anchors on. It is NOT 1,296,000/(H/13): H₀ = 335,317 was fitted on
+ * the 1246 AD perihelion–solstice alignment (the perihelion-of-date beat),
+ * so H₀/13 = 25,793.6 yr is the fit anchor's reading, 0.086 % slow, and
+ * is not a period of anything the model computes (nor a window mean: the
+ * published period averages 25,598 yr over ±26 kyr). The unit H(t) =
+ * H_era/[torque term] (deltat/deep-time.cjs hAtAge) scales WITH the
+ * composed period — H(t)/T_p(t) = H₀/axial0 = 13.011 at every epoch — but
+ * is not 13 of them; the 13 is a fit-era label that leaves the physics.
+ * The pre-Phase-3 structural clock 13·1,296,000/H_era(t) (pure ω-scaling,
+ * H_era = H₀·LOD/LOD₀) survives only as the FROZEN ERA CLOCK's named phase
+ * convention (eraClockHAtAge) and in docs/retired-record.md, with its
+ * record: it read 70.9 ″/yr against Lantink et al. 2022's 108.6 ± 8.5 at
+ * 2.46 Ga and 65.2 against Meyers & Malinverno 2018's 85.79 ± 2.72 at
+ * 1.4 Ga, where the composed rate reads 104.6 and 86.6.
+ *
+ * Pure factory: the tidal chain is injected (each runtime's own LOD and
+ * moon-distance evaluators), no artifact reads, no globals.
+ */
+
+'use strict';
+
+const D2R = Math.PI / 180;
+
+/**
+ * Solar fraction of the J2000 precession torque from the shared constants.
+ * @param {{
+ *   gmSunKm3S2: number, auKm: number, earthEccentricity: number,
+ *   gmMoonKm3S2: number, moonDistanceKm: number, moonEccentricity: number, moonInclinationDeg: number,
+ * }} c
+ * @returns {number} f_S in [0, 1]
+ */
+function computeSolarTorqueShare(c) {
+  const sol = (c.gmSunKm3S2 / c.auKm ** 3) * Math.pow(1 - c.earthEccentricity * c.earthEccentricity, -1.5);
+  const lun = (c.gmMoonKm3S2 / c.moonDistanceKm ** 3) * Math.pow(1 - c.moonEccentricity * c.moonEccentricity, -1.5)
+    * (1 - 1.5 * Math.sin(c.moonInclinationDeg * D2R) ** 2);
+  return sol / (sol + lun);
+}
+
+/**
+ * @param {{
+ *   p0ArcsecPerYr: number | (() => number),
+ *   solarShare: number,
+ *   lodSecondsAtAge: (tMa: number) => (number | null),
+ *   lodJ2000Seconds: number,
+ *   moonDistanceMetresAtAge: (tMa: number) => (number | null),
+ *   moonDistanceJ2000Metres: number,
+ *   yearToTMa: (year: number) => number,
+ * }} deps - p0 = the model's derived J2000 rate, 1,296,000/axial0 (S5; a
+ *   number or a LAZY getter — the callers' certified year laws read the
+ *   deep-time factory this is built inside, so the anchor is resolved on
+ *   the first RATE use, never at construction; the torque term needs no
+ *   anchor); lodJ2000Seconds the SAME day basis lodSecondsAtAge(0) returns.
+ * @returns {{
+ *   composedRateArcsecPerYrAtAge: (tMa: number) => (number | null),
+ *   composedPeriodYearsAtAge: (tMa: number) => (number | null),
+ *   composedRateArcsecPerYrAtYear: (year: number) => (number | null),
+ *   composedPeriodYearsAtYear: (year: number) => (number | null),
+ *   composedRateRatioAtAge: (tMa: number) => (number | null),
+ *   torqueTermAtAge: (tMa: number) => (number | null),
+ *   lunarTorqueFactorAtAge: (tMa: number) => (number | null),
+ *   solarShare: number,
+ *   p0ArcsecPerYr: number,
+ * }}
+ */
+function createComposedPrecession(deps) {
+  const { solarShare: fS } = deps;
+  /** @type {number|undefined} */
+  let p0Memo;
+  /** The J2000 anchor, resolved once on first use (lazy getter allowed). */
+  const p0 = () => {
+    if (p0Memo === undefined) {
+      const v = typeof deps.p0ArcsecPerYr === 'function' ? deps.p0ArcsecPerYr() : deps.p0ArcsecPerYr;
+      if (!(v > 0)) throw new Error(`createComposedPrecession: p0ArcsecPerYr must resolve to a positive rate, got ${v}`);
+      p0Memo = v;
+    }
+    return p0Memo;
+  };
+  /** @param {number} tMa */
+  const lunarTorqueFactorAtAge = (tMa) => {
+    const a = deps.moonDistanceMetresAtAge(tMa);
+    return a === null || !(a > 0) ? null : Math.pow(deps.moonDistanceJ2000Metres / a, 3);
+  };
+  /** The torque term f_S + (1 − f_S)·(a₀/a_M)³ — the factor the unit H(t)
+   * divides the spin-scaled H_era by (deltat/deep-time.cjs; layer0 spells the
+   * SAME operations, the layer0 gate holds them bit-identical).
+   * @param {number} tMa */
+  const torqueTermAtAge = (tMa) => {
+    const lf = lunarTorqueFactorAtAge(tMa);
+    return lf === null ? null : fS + (1 - fS) * lf;
+  };
+  /** @param {number} tMa */
+  const composedRateArcsecPerYrAtAge = (tMa) => {
+    const lod = deps.lodSecondsAtAge(tMa);
+    const term = torqueTermAtAge(tMa);
+    if (lod === null || !(lod > 0) || term === null) return null;
+    return (deps.lodJ2000Seconds / lod) * p0() * term;
+  };
+  /** @param {number} tMa */
+  const composedPeriodYearsAtAge = (tMa) => {
+    const r = composedRateArcsecPerYrAtAge(tMa);
+    return r === null ? null : 1296000 / r;
+  };
+  /** ψ̇(t)/ψ̇₀ — the factor a consumer scales ITS OWN certified J2000
+   * anchor by (since S5 p₀ and the hybrids' anchor are the same derived
+   * value, 25,771.4 yr; the ratio is what D6 changes). ≡ 1 at J2000; null
+   * out of the tidal chain's domain.
+   * @param {number} tMa */
+  const composedRateRatioAtAge = (tMa) => {
+    const r = composedRateArcsecPerYrAtAge(tMa);
+    return r === null ? null : r / p0();
+  };
+  return {
+    composedRateArcsecPerYrAtAge,
+    composedPeriodYearsAtAge,
+    composedRateArcsecPerYrAtYear: (year) => composedRateArcsecPerYrAtAge(deps.yearToTMa(year)),
+    composedPeriodYearsAtYear: (year) => composedPeriodYearsAtAge(deps.yearToTMa(year)),
+    composedRateRatioAtAge,
+    torqueTermAtAge,
+    lunarTorqueFactorAtAge,
+    solarShare: fS,
+    get p0ArcsecPerYr() { return p0(); },
+  };
+}
+
+module.exports = { computeSolarTorqueShare, createComposedPrecession };

package/src/earth/year-lengths.cjs

@@ -113,4 +113,15 @@ function createYearLengths({ sampleAt, massLossSiderealSecondsAtYearFn, apsidalS
   });
 }
 
-module.exports = { createYearLengths };
+/**
+ * The published of-date window (plan 06 Phase 3 S2): inside |year − 2000| ≤
+ * this span the one-family route is THE published year-length / precession
+ * family (the banked tiers — 100-yr and 1000-yr grids, no unbounded sampler
+ * growth); beyond it the published surfaces return the unit's SECULAR mean
+ * (H(t)/13 for the precession period, the tidal-chain mean year), because the
+ * of-date wobble is unresolved there and the deep sampler grows ~0.1 s per Myr
+ * of span. A displayed rate must name its window — this is the window.
+ */
+const ONE_FAMILY_WINDOW_YEARS = 2000000;
+
+module.exports = { createYearLengths, ONE_FAMILY_WINDOW_YEARS };

package/src/index.js

@@ -138,7 +138,11 @@ export { createDeepOrbitalHistory } from './earth/deep-orbital-history.cjs';
 // D6: the sidereal-year-of-date channel (banked λ̇ ratio × the caller's mass-loss law)
 export { createSiderealYearChannel } from './earth/sidereal-year-channel.cjs';
 // S2: THE ONE of-date year-length family (years + precession beats, SI seconds)
-export { createYearLengths } from './earth/year-lengths.cjs';
+export { createYearLengths, ONE_FAMILY_WINDOW_YEARS } from './earth/year-lengths.cjs';
+// Plan 06 D6: THE ONE home of the composed lunisolar precession rate ψ̇(t)
+// (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';
 // L10 — the composition front door: one law set, N body records. Thin by
 // design; engines keep their direct call sites (see planets/model.cjs).
@@ -148,7 +152,7 @@ export { createDeltaTCycles } from './deltat/cycles.cjs';
 export { createDeepTimeLod } from './deltat/deep-time.cjs';
 export { createMoonRecessionHistory, createSolarChannelBudget } from './deltat/recession-history.cjs';
 export { deltaTEspenakMeeusCanonSeconds } from './deltat/historical.cjs';
-export { evalClimateL1OrbitalPermil } from './climate/l1-orbital.cjs';
+export { evalClimateL1OrbitalPermil, laggedL1Terms, createAlphaGiaChannel } from './climate/l1-orbital.cjs';
 // Phase 8.5 — eclipse geometry (single-copy: the browser had no Node twin).
 export { createEclipseFinders } from './eclipse/finders.cjs';
 // Phase 8.6 — the published reference curves (external comparison formulas
@@ -223,19 +227,22 @@ export const createModel = (constants = GENERATED, opts = {}) => {
     hash,
 
     /**
-     * H-lattice periods — the structural identities, in years.
+     * The fit-era lattice identities H/13, H/3, H/16, in years — DEVICE tier.
      *
-     * PURE ALGEBRA OVER THE CONTEXT. No epoch, no formula, no fit. These are
-     * the divisor relationships H/13, H/3, H/16 that define the lattice, and
-     * they exist here in Phase 5 for one reason: a hash-only counterfactual
-     * test would still pass if `createModel` ignored its argument entirely.
-     * Something has to READ the context and return a number for injection to be
-     * demonstrated end to end.
+     * PURE ALGEBRA OVER THE CONTEXT. No epoch, no formula, no fit. They exist
+     * here for one reason: a hash-only counterfactual test would still pass if
+     * `createModel` ignored its argument entirely. Something has to READ the
+     * context and return a number for injection to be demonstrated end to end.
      *
-     * The motion model is Phase 6. This is not it.
+     * These are NOT the published periods (plan 06 S5): the axial precession
+     * period is `epoch.axialPrecessionYearsAtYear` (25,771.4 yr at J2000, the
+     * of-date year laws' beat); H/13 = 25,793.6 is the fit anchor's reading,
+     * 0.086 % slow — H₀ was fitted on the perihelion-of-date beat. Likewise
+     * H/3 and H/16 against the chain's apsidal and perihelion-of-date periods.
+     * The property names keep their historical form (plan 06 P4).
      *
      * `divisor` and `period` are never interchangeable (CLAUDE.md): 13 is the
-     * divisor, H/13 years is the period. The names say which.
+     * divisor, H/13 years is the identity's value. The names say which.
      *
      * @returns {{axialPrecessionPeriodYears: number, inclinationPrecessionPeriodYears: number, perihelionPrecessionPeriodYears: number}}
      */

package/src/layer0/derive-params.js

@@ -9,12 +9,16 @@
  * If the two ever disagree, one of them changed and the other did not — which
  * is the exact drift mode that produced five diverging implementations.
  *
- * Pure function, imports nothing. Lives in physics so the browser and the Node
- * engine can both build Layer 0 from ONE derivation (deep-time.js keeps its
- * own inline copy only until Phase C rewrites it; until then the test is the
- * enforcement).
+ * Pure function; its only import is the torque-share derivation (plan 06
+ * Phase 3: the unit H(t) = 13·T_p,composed needs the solar fraction of the
+ * J2000 precession torque, derived ONCE here from the shared constants).
+ * Lives in physics so the browser and the Node engine can both build Layer 0
+ * from ONE derivation (deep-time.js keeps its own inline copy only until
+ * Phase C rewrites it; until then the test is the enforcement).
  */
 
+import { computeSolarTorqueShare } from '../earth/precession-composed.cjs';
+
 /**
  * @typedef {Object} RawEpochConstants
  * @property {number} solarLuminosityW          IAU 2015 nominal (W)
@@ -35,6 +39,10 @@
  * @property {number} moonDistanceKm
  * @property {number} moonOrbitalEccentricity
  * @property {number} gmEarthMoonSystemKm3S2
+ * @property {number} gmSunKm3S2                 GM☉ (km³/s²) — the solar precession torque
+ * @property {number} astronomicalUnitKm         1 AU (km)
+ * @property {number} earthOrbitalEccentricityJ2000
+ * @property {number} moonEclipticInclinationJ2000Deg
  */
 
 /**
@@ -64,6 +72,14 @@ export const deriveEpochParams = (raw) => {
     + (moonMassKg * Math.sqrt(gmEarthMoonM3S2 * moonDistanceNowM) * moonEccentricityFactor);
   const moonLockDistanceM = (totalAngularMomentumKgM2S / (moonMassKg * Math.sqrt(gmEarthMoonM3S2) * moonEccentricityFactor)) ** 2;
 
+  // The solar fraction of the J2000 precession torque (plan 06 Phase 3): the
+  // unit H(t) ≡ 13·T_p,composed = H_era(t) / [f_S + (1 − f_S)(a₀/a_M(t))³].
+  const precessionSolarShareJ2000 = computeSolarTorqueShare({
+    gmSunKm3S2: raw.gmSunKm3S2, auKm: raw.astronomicalUnitKm, earthEccentricity: raw.earthOrbitalEccentricityJ2000,
+    gmMoonKm3S2: raw.gmMoonAloneKm3S2, moonDistanceKm: raw.moonDistanceKm, moonEccentricity: raw.moonOrbitalEccentricity,
+    moonInclinationDeg: raw.moonEclipticInclinationJ2000Deg,
+  });
+
   return Object.freeze({
     epochYear: 2000,
     alpha1PerMa: raw.alpha1PerMa,
@@ -81,5 +97,6 @@ export const deriveEpochParams = (raw) => {
     lodNowH13Seconds,
     siderealYearJ2000Seconds: raw.meanSiderealYearSeconds,
     solarMassLossFracPerYear,
+    precessionSolarShareJ2000,
   });
 };

package/src/layer0/index.js

@@ -47,6 +47,7 @@
  * @property {number} lodNowH13Seconds
  * @property {number} siderealYearJ2000Seconds
  * @property {number} solarMassLossFracPerYear
+ * @property {number} precessionSolarShareJ2000  f_S, the solar fraction of the J2000 precession torque
  */
 
 /**
@@ -54,10 +55,12 @@
  * @property {(year: number) => number} tMa
  * @property {(year: number) => number} moonDistanceMetres
  * @property {(year: number) => number|null} lodSeconds
- * @property {(year: number) => number|null} holisticH
+ * @property {(year: number) => number|null} holisticH               the UNIT: 13 × the composed lunisolar precession period
  * @property {(year: number) => number} siderealYearSeconds
  * @property {(year: number) => number} tropicalYearSeconds
  * @property {(year: number) => number|null} anomalisticYearSeconds
+ * @property {(year: number) => number|null} eraClockH               the frozen era clock's phase convention H₀·LOD/LOD₀ (device tier)
+ * @property {(year: number) => number} eraClockTropicalYearSeconds  T_sid·(1 − 13/H_era) — the frozen comb family's base
  */
 
 /**
@@ -98,16 +101,35 @@ export const createEpochPrimitives = ({ params: p, alphaAtAgeMa }) => {
   };
 
   /**
-   * The Earth Fundamental Cycle. H scales with LOD — the lattice is defined by
-   * the rotation rate, so a longer day is a longer H.
+   * The frozen era clock's phase convention: H_era(t) = H₀·LOD(t)/LOD₀ —
+   * pure spin scaling. This is the counter the FROZEN devices (the cardinal
+   * era clock, the year-length comb family) were fitted against; it ships
+   * with their coefficients as a named device constant (plan 06 Phase 3,
+   * D8), never as "H(t)".
    * @param {number} t age in Ma
    * @returns {number|null} years
    */
-  const holisticHCore = (t) => {
+  const eraClockHCore = (t) => {
     const lod = lodSecondsCore(t);
     return lod === null ? null : p.holisticYearJ2000 * lod / p.lodNowH13Seconds;
   };
 
+  /**
+   * The unit H(t) ≡ 13 × the composed lunisolar precession period:
+   * H_era(t) / [f_S + (1 − f_S)·(a₀/a_M(t))³] — the spin scaling AND the
+   * lunar torque growing on the recession history (plan 06 D6/Phase 3; the
+   * formula's home is earth/precession-composed, this is its Layer-0 twin,
+   * held bit-identical to deltat/deep-time.cjs by the layer0 gate).
+   * @param {number} t age in Ma
+   * @returns {number|null} years
+   */
+  const holisticHCore = (t) => {
+    const hEra = eraClockHCore(t);
+    if (hEra === null) return null;
+    const lf = Math.pow(p.moonDistanceNowM / moonDistanceMetresCore(t), 3);
+    return hEra / (p.precessionSolarShareJ2000 + (1 - p.precessionSolarShareJ2000) * lf);
+  };
+
   /**
    * Sidereal year. Driver 2 alone — solar mass loss via Kepler, `dT/T = -2 dM/M`
    * under the adiabatic `a*M = const` coupling. Carries NO alpha and NO LOD,
@@ -127,7 +149,10 @@ export const createEpochPrimitives = ({ params: p, alphaAtAgeMa }) => {
   };
 
   /**
-   * Tropical year — sidereal less one axial-precession turn, H/13.
+   * Tropical year — sidereal less one calendar turn of the unit, 13/H(t): the
+   * unit's CALENDAR convention (plan 06 S5 — a device identity, 0.086 % from
+   * one turn per the published precession period; D2 decided: it stays a
+   * named device, never re-based).
    * Falls back to the J2000 H past the asymptote, matching the shipped chain.
    * @param {number} t age in Ma
    * @returns {number} seconds
@@ -159,6 +184,13 @@ export const createEpochPrimitives = ({ params: p, alphaAtAgeMa }) => {
     return sid * (H - 13) / H * H / (H - 16);
   };
 
+  /** The frozen comb family's tropical base: T_sid·(1 − 13/H_era). @param {number} t */
+  const eraClockTropicalYearSecondsCore = (t) => {
+    const sid = siderealYearSecondsCore(t);
+    const H = eraClockHCore(t);
+    return H === null ? sid * (1 - 13 / p.holisticYearJ2000) : sid * (1 - 13 / H);
+  };
+
   return Object.freeze({
     tMa,
     moonDistanceMetres: (year) => moonDistanceMetresCore(tMa(year)),
@@ -167,5 +199,7 @@ export const createEpochPrimitives = ({ params: p, alphaAtAgeMa }) => {
     siderealYearSeconds: (year) => siderealYearSecondsCore(tMa(year)),
     tropicalYearSeconds: (year) => tropicalYearSecondsCore(tMa(year)),
     anomalisticYearSeconds: (year) => anomalisticYearSecondsCore(tMa(year)),
+    eraClockH: (year) => eraClockHCore(tMa(year)),
+    eraClockTropicalYearSeconds: (year) => eraClockTropicalYearSecondsCore(tMa(year)),
   });
 };