@essrt/physics 22.1.0 → 23.2.0

package/src/deltat/deep-time-chain.js

@@ -0,0 +1,457 @@
+/**
+ * THE DEEP-TIME CHAIN — ONE assembly (holisticuniverse plan 13 B2).
+ *
+ * Before B2 three runtimes assembled the same chain by hand from the same
+ * factories — `packages/physics/src/model.js`, `tools/lib/deep-time.js`
+ * ("copy, keep in sync") and the `src/script.js` block — each deriving the
+ * GIA α channel, the Layer-0 parameter bundle, the cited Moon-distance
+ * history, the ΔT cycle stack, |s₃|, the LOD/ΔT core and the lunar month
+ * chain, and each carrying its own `mean*AtAge` wrappers. This module is
+ * that assembly, once, from the generated constants and fitted
+ * coefficients; the runtimes destructure it and keep only what is genuinely
+ * theirs (the browser's research toggles and snapshot mode, the Node
+ * engine's env gates and scene grid, the model's one-source movement).
+ *
+ * Bit-identity rule (plan 13 §2.6): every operation here is the twins'
+ * operation in the twins' order — floating point is not associative, and
+ * the goldens pin the values.
+ *
+ * Twin differences that are CONVENTIONS, kept as parameters:
+ *  - `ageAnchorYear`: the year the twins' `h5Correction`/`frameworkDeltaT`
+ *    convert to t_Ma from (the scene epoch 2000.5 in both twins; the model's
+ *    own surfaces use 2000 — `yearToTMa` here is always 2000-anchored, the
+ *    Layer-0 rule, and the scene-anchored readers take `ageAnchorYear`).
+ *  - `flagsAt()`: the ΔT stack's five post-integration terms, each
+ *    switchable (the browser's research toggles; the Node engine maps its
+ *    two env gates onto them; the model runs all ON).
+ *  - the stellar day: the Node twin projects the precession offset onto the
+ *    equator (`stellarDayRaProjection`), the browser does not — two named
+ *    functions, `meanStellarDayAtAge` (unprojected) and
+ *    `meanStellarDayProjectedAtAge`.
+ */
+
+import { deriveEpochParams } from '../layer0/derive-params.js';
+import { createEpochPrimitives } from '../layer0/index.js';
+import { computeMeanTropicalYearJ2000Days } from '../earth/year-lengths.cjs';
+import { createAlphaGiaChannel } from '../climate/l1-orbital.cjs';
+import { createMoonDistanceHistory } from './moon-distance-history.cjs';
+import { createMeanObliquityHistory } from '../earth/mean-obliquity-history.cjs';
+import { createDeltaTCycles } from './cycles.cjs';
+import { createDeepTimeLod } from './deep-time.cjs';
+import { createDeepEccChannel } from '../moon/deep-ecc-channel.cjs';
+import { createMoonMonthChain } from '../moon/month-chain.cjs';
+import { massLossScaledLinearAtAge, driver2PeriodSecondsAtAge, synodicPeriodSeconds } from '../planets/orbit-chain.cjs';
+import { computeMassChainJ2000, computeMoonPeriodsJ2000 } from '../earth/mass-chain.cjs';
+
+/**
+ * Moon-channel eccentricity sensitivities (perigee/node), the [g/g₀]^s
+ * exponents of the factored deep-time law — Meeus-effective (S_N moved
+ * 1.0 → 1.018 with the v4 frame-attribution batch). ONE home since B2 (they
+ * were literals in model.js, tools/lib/deep-time.js and script.js `_FW_MOON`).
+ */
+export const MOON_ECC_SENSITIVITY_PERIGEE = 2.407;
+export const MOON_ECC_SENSITIVITY_NODE = 1.018;
+
+/**
+ * The ΔT stack's switches. `resonator` gates the swing's δLOD terms; the
+ * swing's ΔT term is gated by `resonatorDeltaT` when given (the Node twin
+ * gates it on BOTH env vars, DT_CORRECTIONS and DT_RESONATOR), else by
+ * `resonator`. The four cycles' δLOD terms follow their flags only when
+ * `cycleLodFollowsFlags` is true (the browser's research toggles switch a
+ * cycle's ΔT and δLOD together); the Node twin sums them unconditionally.
+ * Their ΔT terms always follow their flags. Identical with every flag ON.
+ * @typedef {{bond: boolean, hallstatt: boolean, jose5: boolean, jose4: boolean, resonator: boolean, resonatorDeltaT?: boolean, cycleLodFollowsFlags?: boolean}} DeltaTFlags
+ */
+
+/**
+ * @param {{
+ *   constants: any,
+ *   fitted: any,
+ *   deepModes: any,
+ *   moonDistanceArtifact: any,
+ *   ageAnchorYear?: number,
+ *   flagsAt?: () => DeltaTFlags,
+ *   planetAuRatios?: Record<string, number>,
+ *   stellarDayRaProjection?: number,
+ * }} deps — `constants` the generated DEFAULT_CONSTANTS, `fitted` the
+ *   generated FITTED_COEFFICIENTS, `deepModes` the DEEP_MODES_ARTIFACT,
+ *   `moonDistanceArtifact` the MOON_DISTANCE_ARTIFACT — the cited distance
+ *   AND mean-obliquity columns, plan 12 option A / §8 (a) (injected so a
+ *   counterfactual context can replace any of them); `ageAnchorYear` the
+ *   scene epoch (default constants.timeReference.sceneEpochYear);
+ *   `flagsAt` the ΔT stack's switches (default all ON); `planetAuRatios`
+ *   the planets' J2000 semi-major axes in AU (for the per-planet family);
+ *   `stellarDayRaProjection` cos ε₀-class factor for the projected stellar day.
+ */
+export function createDeepTimeChain(deps) {
+  const C = deps.constants, F = deps.fitted;
+  /** @type {() => DeltaTFlags} */
+  const flagsAt = deps.flagsAt ?? (() => ({ bond: true, hallstatt: true, jose5: true, jose4: true, resonator: true }));
+  const ageAnchorYear = deps.ageAnchorYear ?? C.timeReference.sceneEpochYear;
+
+  // ── Derived constants (constants.js §9 order — the twins' operations) ─────
+  const meanSolarYearDays = computeMeanTropicalYearJ2000Days(C.yearLengthRef.siderealYear, C.earthOrbital.generalPrecessionJ2000_arcsecPerYr);
+  const meanSiderealYearDays = C.yearLengthRef.siderealYear;
+  const meanSiderealYearSeconds = meanSiderealYearDays * 86400;
+  const meanLengthOfDay = C.yearLengthRef.solarDay;
+  const meanTropicalYearJ2000Seconds = meanSolarYearDays * meanLengthOfDay;
+  const siTropicalYearDays = meanTropicalYearJ2000Seconds / 86400;
+  const axialPrecessionJ2000Years = 1296000 / C.earthOrbital.generalPrecessionJ2000_arcsecPerYr;
+  const axialPrecessionJ2000Days = axialPrecessionJ2000Years * 365.25;
+
+  const G_CONSTANT = C.physicalConstants.G_CONSTANT;
+  const MASS_RATIO_EARTH_MOON = C.physicalConstants.MASS_RATIO_EARTH_MOON;
+  const currentAUDistance = C.physicalConstants.currentAUDistance;
+  const earthMoiFactorJ2000 = C.physicalConstants.earthMoiFactorJ2000;
+  const moonDistanceKm = C.moonReference.moonDistance;
+  const moonSiderealMonthInput = C.moonReference.moonSiderealMonthInput;
+  const moonSiderealMonth = moonSiderealMonthInput;
+
+  // The mass chain (Moon Kepler → GM_EM → the Earth/Moon split → the Sun) — ONE home (B3)
+  const mass = computeMassChainJ2000({
+    moonDistanceKm, moonSiderealMonthDays: moonSiderealMonth, meanSiderealYearDays,
+    meanLengthOfDaySeconds: meanLengthOfDay, massRatioEarthMoon: MASS_RATIO_EARTH_MOON,
+    currentAUDistanceKm: currentAUDistance, gravitationalConstantKm3KgS2: G_CONSTANT,
+  });
+  const moonOrbitalShift = mass.moonOrbitalShiftKm;
+  const moonDistanceCorrected = mass.moonDistanceCorrectedKm;
+  const GM_EARTH_MOON_SYSTEM = mass.gmEarthMoonSystemKm3S2;
+  const GM_EARTH_ALONE = mass.gmEarthAloneKm3S2;
+  const GM_MOON_ALONE = mass.gmMoonAloneKm3S2;
+  const GM_SUN_PLUS_EARTH = mass.gmSunPlusEarthKm3S2;
+  const GM_SUN = mass.gmSunKm3S2;
+  const M_SUN = mass.sunMassKg;
+
+  /** THE J2000 precession anchor p₀ as a period (plan 09: the IAU 2006 general precession). @returns {number} */
+  const certifiedAxialPrecessionJ2000Years = () => axialPrecessionJ2000Years;
+  /** p₀, ″/yr. @returns {number} */
+  const precessionRateJ2000ArcsecPerYr = () => 1296000 / certifiedAxialPrecessionJ2000Years();
+
+  // ── α(t): the GIA channel (lagged L1 response), the memo and the lattice pin ──
+  const CLIMATE_REGIME = F.CLIMATE_FORMULA_COEFFS.regimes['lr04-post-mpt'];
+  const alphaGia = createAlphaGiaChannel({
+    l1Terms: CLIMATE_REGIME.L1,
+    yStdDenormalization: CLIMATE_REGIME.denormalization.y_std,
+    relaxationKyr: C.deepTime.alphaGiaRelaxationKyr,
+    alphaGiaRateJ2000PerYr: C.deepTime.alphaGiaRateJ2000PerYr,
+    alphaJ2000: earthMoiFactorJ2000,
+    j2RateJ2000PerYr: C.deepTime.j2RateJ2000PerYr,
+    j2J2000: C.physicalConstants.earthJ2,
+  });
+  // R2 — the α lattice reference: while a lattice table is being BUILT α is
+  // held at its J2000 reference, or the lattice defines itself in terms of
+  // its own output. Save/restore under try/finally.
+  let latticeAlphaRef = false;
+  /** @param {() => void} build */
+  const withLatticeAlpha = (build) => { const prev = latticeAlphaRef; latticeAlphaRef = true; try { build(); } finally { latticeAlphaRef = prev; } };
+  /** @type {Map<number, number>} */
+  const alphaMemo = new Map();
+  /** Exact-argument memo (pure dedupe, not a grid); the pin bypasses it. @param {number} tMa @returns {number} */
+  const earthMoiFactorAtAge = (tMa) => {
+    if (latticeAlphaRef) return earthMoiFactorJ2000;
+    let v = alphaMemo.get(tMa);
+    if (v === undefined) {
+      v = alphaGia.alphaAt(2000 - tMa * 1e6);
+      if (alphaMemo.size >= 8192) alphaMemo.clear();
+      alphaMemo.set(tMa, v);
+    }
+    return v;
+  };
+  /** J₂(t)/J₂₀ of the GIA channel at a calendar year — PURE in year. @param {number} year @returns {number} */
+  const j2RatioAtYear = (year) => alphaGia.j2RatioAt(year);
+
+  // ── Layer 0 bundle ────────────────────────────────────────────────────────
+  const EPOCH_PARAMS = deriveEpochParams({
+    solarLuminosityW: C.physicalConstants.solarLuminosityW,
+    solarWindKgPerS: C.physicalConstants.solarWindMassLossKgPerS,
+    speedOfLightKmPerS: C.physicalConstants.speedOfLight,
+    alpha1PerMa: C.deepTime.alpha1PerMa,
+    meanSiderealYearSeconds,
+    lodJ2000Seconds: meanLengthOfDay,
+    sunMassKg: M_SUN,
+    gmEarthAloneKm3S2: GM_EARTH_ALONE,
+    gmMoonAloneKm3S2: GM_MOON_ALONE,
+    gravitationalConstantKm3KgS2: G_CONSTANT,
+    earthMoiFactorJ2000,
+    earthDiameterKm: C.bodyDiametersKm.earth,
+    moonDistanceKm,
+    moonOrbitalEccentricity: C.moonReference.moonOrbitalEccentricityBase,
+    gmEarthMoonSystemKm3S2: GM_EARTH_MOON_SYSTEM,
+    gmSunKm3S2: GM_SUN,
+    astronomicalUnitKm: currentAUDistance,
+    earthOrbitalEccentricityJ2000: C.earthOrbital.earthEccentricityJ2000,
+    moonEclipticInclinationJ2000Deg: C.moonReference.moonEclipticInclinationJ2000,
+    axialPrecessionJ2000Years: certifiedAxialPrecessionJ2000Years(),
+  });
+  /** @param {number} tMa @returns {number} */
+  const iEarthAtAge = (tMa) => earthMoiFactorAtAge(tMa) * EPOCH_PARAMS.earthMassKg * EPOCH_PARAMS.earthRadiusM * EPOCH_PARAMS.earthRadiusM;
+
+  // ── The Earth–Moon distance history — the CITED INPUT (plan 12 option A) ──
+  const recession = createMoonDistanceHistory({
+    table: deps.moonDistanceArtifact,
+    aMoonNowMetres: EPOCH_PARAMS.moonDistanceNowM,
+    alpha1PerMa: EPOCH_PARAMS.alpha1PerMa,
+  });
+  // The cited mean obliquity ε̄(t) — the second column of the same history
+  // (plan 12 §8 option (a)): the precession RATE of date is the constant's
+  // scaling × cos ε̄(t)/cos ε̄(0); the hybrid keeps integrating on the constant.
+  const meanObliquity = createMeanObliquityHistory({ table: deps.moonDistanceArtifact });
+
+  // ── The ΔT cycle stack (the fitted terms, periods stated in years) ────────
+  const DT = F.DT_STACK, RES = F.DT_RESONATOR;
+  const dtCycles = createDeltaTCycles({
+    taperFullHalfwidthYears: C.deepTime.dtStackTaperFullHalfwidthYr,
+    taperTotalHalfwidthYears: C.deepTime.dtStackTaperTotalHalfwidthYr,
+    tropicalYearSecondsJ2000: meanTropicalYearJ2000Seconds,
+    cycles: {
+      bond: { periodYears: DT.bond.period_yr, cosCoeffSeconds: DT.bond.cos_coeff_s, sinCoeffSeconds: DT.bond.sin_coeff_s },
+      hallstatt: { periodYears: DT.hallstatt.period_yr, cosCoeffSeconds: DT.hallstatt.cos_coeff_s, sinCoeffSeconds: DT.hallstatt.sin_coeff_s },
+      jose5: { periodYears: DT.jose5.period_yr, cosCoeffSeconds: DT.jose5.cos_coeff_s, sinCoeffSeconds: DT.jose5.sin_coeff_s },
+      jose4: { periodYears: DT.jose4.period_yr, cosCoeffSeconds: DT.jose4.cos_coeff_s, sinCoeffSeconds: DT.jose4.sin_coeff_s },
+    },
+    resonator: {
+      t0Years: RES.T0_yr,
+      q: RES.Q,
+      kicks: RES.kick_epochs_year.map(/** @param {number} t @param {number} i */ (t, i) => ({ tYear: t, cosSeconds: RES.kick_coefficients_s[i].cos, sinSeconds: RES.kick_coefficients_s[i].sin })),
+      tones: RES.drive_tones.map(/** @param {{period_yr: number, phi_locked_rad: number, amp_s: number}} t */ (t) => ({ periodYears: t.period_yr, phiLockedRad: t.phi_locked_rad, ampSeconds: t.amp_s })),
+    },
+  });
+  /** @param {string} name @param {number} year @returns {number} */
+  const cycleDeltaT = (name, year) => dtCycles.cycleDeltaTSecondsAt(name, year);
+  /** @param {string} name @param {number} year @returns {number} */
+  const cycleLod = (name, year) => dtCycles.cycleLodSecondsAt(name, year);
+  /** The resonator episode's ΔT term, 0 when its flag is off. @param {number} year @returns {number} */
+  const resonatorSwingDeltaTCorrection = (year) => (flagsAt().resonator ? dtCycles.swingDeltaTSecondsAt(year) : 0);
+  /** @param {number} year @returns {number} */
+  const resonatorSwingLodCorrection = (year) => (flagsAt().resonator ? dtCycles.swingLodSecondsAt(year) : 0);
+  /** @param {number} year @returns {number} */
+  const resonatorSwingLodRate = (year) => (flagsAt().resonator ? dtCycles.swingLodRateAt(year) : 0);
+  /** Sum of the cyclic δLOD contributions at a calendar year (s): the four flags plus the swing when ON. @param {number} year @returns {number} */
+  const dtCycleLodCorrectionSum = (year) => {
+    const f = flagsAt();
+    const g = f.cycleLodFollowsFlags === true;
+    return (g && !f.bond ? 0 : cycleLod('bond', year))
+      + (g && !f.hallstatt ? 0 : cycleLod('hallstatt', year))
+      + (g && !f.jose5 ? 0 : cycleLod('jose5', year))
+      + (g && !f.jose4 ? 0 : cycleLod('jose4', year))
+      + resonatorSwingLodCorrection(year);
+  };
+
+  // ── |s₃| — the dominant nodal mode of Earth's orbit ──────────────────────
+  const s3ArcsecPerYr = (() => {
+    const z = deps.deepModes.earthZeta
+      .filter(/** @param {{omegaRadPerYr: number}} m */ (m) => Math.abs(m.omegaRadPerYr) > 1e-9)
+      .sort(/** @param {{re: number, im: number}} a @param {{re: number, im: number}} b */ (a, b) => Math.hypot(b.re, b.im) - Math.hypot(a.re, a.im))[0];
+    return Math.abs((z.omegaRadPerYr * 180) / Math.PI) * 3600;
+  })();
+
+  // ── The LOD/ΔT core ───────────────────────────────────────────────────────
+  const deepLod = createDeepTimeLod({
+    constants: {
+      lTotalEmKgm2S: EPOCH_PARAMS.totalAngularMomentumKgM2S,
+      mMoonAloneKg: EPOCH_PARAMS.moonMassKg,
+      mEarthAloneKg: EPOCH_PARAMS.earthMassKg,
+      rEarthMetres: EPOCH_PARAMS.earthRadiusM,
+      gmEmM3PerS2: EPOCH_PARAMS.gmEarthMoonM3S2,
+      eFactorMoon: EPOCH_PARAMS.moonEccentricityFactor,
+      aLockMetres: EPOCH_PARAMS.moonLockDistanceM,
+      aMoonNowMetres: EPOCH_PARAMS.moonDistanceNowM,
+      alpha1PerMa: EPOCH_PARAMS.alpha1PerMa,
+      lodNowH13Seconds: EPOCH_PARAMS.lodNowH13Seconds,
+      meanSiderealYearJ2000Seconds: meanSiderealYearSeconds,
+      solarMassLossFracPerYear: EPOCH_PARAMS.solarMassLossFracPerYear,
+      precessionSolarShareJ2000: EPOCH_PARAMS.precessionSolarShareJ2000,
+    },
+    moonDistanceMetresAtAge: recession.distanceMetresAtAge,
+    meanObliquityCosRatioAtAge: meanObliquity.cosRatioAtAge,
+    moiFactorAtAge: earthMoiFactorAtAge,
+    precessionPeriodJ2000YearsFn: certifiedAxialPrecessionJ2000Years,
+    nodalPeriodYearsFn: () => 1296000 / s3ArcsecPerYr,
+    cycleLodSumAt: dtCycleLodCorrectionSum,
+    swingLodAt: resonatorSwingLodCorrection,
+    swingLodRateAt: resonatorSwingLodRate,
+    moonDistanceSlopeMetresPerMaAtAge: recession.slopeMetresPerMaAtAge,
+  });
+
+  // ── Layer 0 primitives ────────────────────────────────────────────────────
+  const l0 = createEpochPrimitives({ params: EPOCH_PARAMS, alphaAtAgeMa: earthMoiFactorAtAge, moonDistanceMetresAtAge: recession.distanceMetresAtAge, meanObliquityCosRatioAtAge: meanObliquity.cosRatioAtAge });
+
+  // ── The ONE deep e and the lunar month chain ──────────────────────────────
+  const deepEcc = createDeepEccChannel(deps.deepModes);
+  /** [g(t)/g₀]^s — the e_E-channel modulation; ≡ 1 at J2000. @param {number} tMa @param {number} s @returns {number} */
+  const eCompModulation = (tMa, s) => deepEcc.modulation(tMa, s);
+
+  // The Moon's J2000 periods on the IAU inputs — ONE home (B3): the star-referenced
+  // apsidal/nodal anchors the month chain rides, and the days forms the twins publish.
+  const moonPeriods = computeMoonPeriodsJ2000({
+    moonSiderealMonthDays: moonSiderealMonth,
+    moonApsidalPrecessionDaysInput: C.moonReference.moonApsidalPrecessionDaysInputICRF,
+    moonNodalPrecessionDaysInput: C.moonReference.moonNodalPrecessionDaysInputICRF,
+    axialPrecessionJ2000Days, meanSiderealYearDays, meanSolarYearDays,
+  });
+  const { moonApsidalJ2000Seconds, moonNodalJ2000Seconds, moonSiderealMonthJ2000Seconds } = moonPeriods;
+
+  /** @param {number} tMa @returns {number|null} */
+  const meanLodSecondsAtAge = (tMa) => deepLod.lodSecondsAtAge(tMa);
+  /** @param {number} tMa @returns {number} */
+  const meanSiderealYearSecondsAtAge = (tMa) => deepLod.siderealYearSecondsAtAge(tMa);
+  /** @param {number} tMa @returns {number|null} */
+  const meanLunisolarPrecessionPeriodYearsAtAge = (tMa) => deepLod.lunisolarPrecessionPeriodYearsAtAge(tMa);
+
+  const moonChain = createMoonMonthChain({
+    constants: {
+      aMoonNowMetres: EPOCH_PARAMS.moonDistanceNowM,
+      gmEarthMoonM3PerS2: EPOCH_PARAMS.gmEarthMoonM3S2,
+      massRatioEarthMoon: MASS_RATIO_EARTH_MOON,
+      moonSiderealMonthInputDays: moonSiderealMonthInput,
+      meanSiderealYearJ2000Seconds: meanSiderealYearSeconds,
+      moonApsidalJ2000Seconds,
+      moonNodalJ2000Seconds,
+      moonSiderealMonthJ2000Seconds,
+      sPerigee: MOON_ECC_SENSITIVITY_PERIGEE, sNode: MOON_ECC_SENSITIVITY_NODE,
+    },
+    fns: {
+      meanLodSecondsAtAge,
+      meanSiderealYearSecondsAtAge,
+      precessionPeriodYearsAtAge: meanLunisolarPrecessionPeriodYearsAtAge,
+      modulation: eCompModulation,
+      distanceMetresAtAge: recession.distanceMetresAtAge,
+    },
+  });
+
+  // ── The ΔT integrator with the flag-keyed cache and the SEQUENTIAL adds ───
+  /** @type {Map<string, number>} */
+  const deltaTCache = new Map();
+  /** ΔT in SI seconds at age tMa, RELATIVE TO J2000 (0 at tMa = 0); the raw Simpson
+   *  integral plus the post-integration terms the flags switch, added one by one in
+   *  the twins' order (pre-summing would change the FP association). @param {number} tMa @returns {number} */
+  const meanDeltaTSecondsAtAge = (tMa) => {
+    if (tMa === 0) return 0;
+    const f = flagsAt();
+    const resonatorDeltaT = f.resonatorDeltaT ?? f.resonator;
+    const cacheKey = `${f.bond ? 'B' : '_'}${f.hallstatt ? 'H' : '_'}${f.jose5 ? 'J' : '_'}${f.jose4 ? 'W' : '_'}${resonatorDeltaT ? 'R' : '_'}:${tMa}`;
+    const hit = deltaTCache.get(cacheKey);
+    if (hit !== undefined) return hit;
+    let result = deepLod.deltaTRawSecondsAtAge(tMa);
+    const yearY = 2000 - tMa * 1e6;
+    if (f.bond) result += cycleDeltaT('bond', yearY);
+    if (f.hallstatt) result += cycleDeltaT('hallstatt', yearY);
+    if (f.jose5) result += cycleDeltaT('jose5', yearY);
+    if (f.jose4) result += cycleDeltaT('jose4', yearY);
+    if (resonatorDeltaT) result += dtCycles.swingDeltaTSecondsAt(yearY);
+    if (deltaTCache.size >= 512) deltaTCache.delete(/** @type {string} */ (deltaTCache.keys().next().value));
+    deltaTCache.set(cacheKey, result);
+    return result;
+  };
+
+  // ── The scene-anchored readers (t_Ma from the scene epoch) ───────────────
+  /** @param {number} year @returns {number} */
+  const ageFromSceneYear = (year) => (ageAnchorYear - year) / 1e6;
+  /** The solar day's ecliptic missing-motion term on the nodal period (the identifier is historical). @param {number} year @returns {number} */
+  const h5Correction = (year) => deepLod.eclipticLodCorrectionSecondsAtAge(ageFromSceneYear(year)) ?? 0;
+  /** The kinematic day of date: the Layer-0 tidal mean LOD, the J2000 day past tidal lock. @param {number} year @returns {number} */
+  const computeLodKinematicSecondsAtEpoch = (year) => l0.lodSeconds(year) ?? meanLengthOfDay;
+  /** The Layer-4 solar day: kinematic + ecliptic term + the cycle stack. @param {number} year @returns {number} */
+  const computeLodRealSecondsAtEpoch = (year) => computeLodKinematicSecondsAtEpoch(year) + h5Correction(year) + dtCycleLodCorrectionSum(year);
+
+  // ── Driver 2 and the per-planet family ────────────────────────────────────
+  /** @param {number} tMa @returns {number} */
+  const meanAuAtAge = (tMa) => massLossScaledLinearAtAge(tMa, currentAUDistance, EPOCH_PARAMS.solarMassLossFracPerYear);
+  const planetAuRatios = deps.planetAuRatios ?? {};
+  /** @param {string} planetName @param {number} tMa @returns {number|null} */
+  const meanPlanetSemiMajorAxisAtAge = (planetName, tMa) => {
+    if (planetName === 'earth') return meanAuAtAge(tMa);
+    const ratio = planetAuRatios[planetName];
+    if (ratio === undefined) return null;
+    return massLossScaledLinearAtAge(tMa, ratio * currentAUDistance, EPOCH_PARAMS.solarMassLossFracPerYear);
+  };
+
+  // ── The stellar and sidereal days ─────────────────────────────────────────
+  /** @param {number} tMa @returns {number|null} */
+  const meanSiderealDayAtAge = (tMa) => {
+    const T_sid_s = meanSiderealYearSecondsAtAge(tMa);
+    const LOD_s = meanLodSecondsAtAge(tMa);
+    if (LOD_s === null) return null;
+    const Tp = meanLunisolarPrecessionPeriodYearsAtAge(tMa) ?? certifiedAxialPrecessionJ2000Years();
+    return T_sid_s / (T_sid_s / LOD_s + 1 + 1 / Tp);
+  };
+  /** The browser's form: no projection of the precession offset. @param {number} tMa @returns {number|null} */
+  const meanStellarDayAtAge = (tMa) => {
+    const T_sid_s = meanSiderealYearSecondsAtAge(tMa);
+    const LOD_s = meanLodSecondsAtAge(tMa);
+    if (LOD_s === null) return null;
+    return T_sid_s / (T_sid_s / LOD_s + 1);
+  };
+  /** The Node twin's form: the precession offset projected onto the equator. @param {number} tMa @returns {number|null} */
+  const meanStellarDayProjectedAtAge = (tMa) => {
+    const T_sid_s = meanSiderealYearSecondsAtAge(tMa);
+    const LOD_s = meanLodSecondsAtAge(tMa);
+    if (LOD_s === null) return null;
+    const sid = meanSiderealDayAtAge(tMa);
+    const Tp = meanLunisolarPrecessionPeriodYearsAtAge(tMa) ?? certifiedAxialPrecessionJ2000Years();
+    const unproj = T_sid_s / (T_sid_s / LOD_s + 1);
+    const sidTp = T_sid_s / (T_sid_s / LOD_s + 1 + 1 / Tp);
+    return /** @type {number} */ (sid) + (unproj - sidTp) * (deps.stellarDayRaProjection ?? 1);
+  };
+
+  return Object.freeze({
+    // the derived scalars
+    meanSolarYearDays, meanSiderealYearDays, meanSiderealYearSeconds, meanLengthOfDay,
+    meanTropicalYearJ2000Seconds, siTropicalYearDays, axialPrecessionJ2000Years, axialPrecessionJ2000Days,
+    G_CONSTANT, MASS_RATIO_EARTH_MOON, currentAUDistance, earthMoiFactorJ2000, moonDistanceKm, moonSiderealMonthInput,
+    moonOrbitalShift, moonDistanceCorrected, GM_EARTH_MOON_SYSTEM, GM_EARTH_ALONE, GM_MOON_ALONE, GM_SUN_PLUS_EARTH, GM_SUN, M_SUN,
+    moonApsidalJ2000Seconds, moonNodalJ2000Seconds, moonSiderealMonthJ2000Seconds, moonPeriods,
+    certifiedAxialPrecessionJ2000Years, precessionRateJ2000ArcsecPerYr,
+    EPOCH_PARAMS, ageAnchorYear,
+    // the pieces
+    alphaGia, earthMoiFactorAtAge, withLatticeAlpha, j2RatioAtYear, iEarthAtAge,
+    recession, meanObliquity, dtCycles, s3ArcsecPerYr, deepLod, l0, deepEcc, eCompModulation, moonChain,
+    // the family
+    meanMoonDistanceMetresAtAge: recession.distanceMetresAtAge,
+    meanMoonDistanceAtAge: moonChain.distanceKmAtAge,
+    meanLodSecondsAtAge,
+    meanLodHoursAtAge: deepLod.lodHoursAtAge,
+    meanLunisolarPrecessionRateArcsecPerYrAtAge: deepLod.lunisolarPrecessionRateArcsecPerYrAtAge,
+    meanLunisolarPrecessionPeriodYearsAtAge,
+    // the constant's scaling alone (the hybrid's integrand), the rate's obliquity factor and the cited mean (plan 12 §8)
+    meanLunisolarTorqueRateArcsecPerYrAtAge: deepLod.lunisolarTorqueRateArcsecPerYrAtAge,
+    meanLunisolarTorquePeriodYearsAtAge: deepLod.lunisolarTorquePeriodYearsAtAge,
+    precessionObliquityFactorAtAge: deepLod.precessionObliquityFactorAtAge,
+    meanObliquityCitedDegAtAge: meanObliquity.meanObliquityDegAtAge,
+    meanAuAtAge, meanSiderealYearSecondsAtAge,
+    meanTropicalYearSecondsAtAge: deepLod.tropicalYearSecondsAtAge,
+    meanTropicalYearDaysAtAge: deepLod.tropicalYearDaysAtAge,
+    meanYearInDaysAtAge: deepLod.yearInDaysAtAge,
+    meanDeltaTSecondsAtAge,
+    bondCycleDeltaTCorrection: (/** @type {number} */ year) => cycleDeltaT('bond', year),
+    hallstattCycleDeltaTCorrection: (/** @type {number} */ year) => cycleDeltaT('hallstatt', year),
+    jose5CycleDeltaTCorrection: (/** @type {number} */ year) => cycleDeltaT('jose5', year),
+    jose4CycleDeltaTCorrection: (/** @type {number} */ year) => cycleDeltaT('jose4', year),
+    bondCycleLodCorrection: (/** @type {number} */ year) => cycleLod('bond', year),
+    hallstattCycleLodCorrection: (/** @type {number} */ year) => cycleLod('hallstatt', year),
+    jose5CycleLodCorrection: (/** @type {number} */ year) => cycleLod('jose5', year),
+    jose4CycleLodCorrection: (/** @type {number} */ year) => cycleLod('jose4', year),
+    dtCycleLodCorrectionSum,
+    resonatorSwingDeltaTCorrection, resonatorSwingLodCorrection, resonatorSwingLodRate,
+    meanLodSecondsWithCorrectionsAtAge: deepLod.lodSecondsWithCorrectionsAtAge,
+    dLodDtDecompositionAtAge: deepLod.dLodDtDecompositionAtAge,
+    h5Correction, computeLodKinematicSecondsAtEpoch, computeLodRealSecondsAtEpoch,
+    meanSolarDeltaAAtAge: moonChain.solarDeltaAKmAtAge,
+    meanMoonDistanceCorrectedAtAge: moonChain.distanceCorrectedKmAtAge,
+    meanMoonSiderealMonthAtAge: moonChain.siderealMonthSecondsAtAge,
+    meanSynodicMonthAtAge: moonChain.synodicMonthSecondsAtAge,
+    meanTropicalMonthAtAge: moonChain.tropicalMonthSecondsAtAge,
+    meanLunarPerigeePrecessionAtAge: moonChain.perigeePrecessionSecondsAtAge,
+    meanLunarNodePrecessionAtAge: moonChain.nodePrecessionSecondsAtAge,
+    meanAnomalisticMonthAtAge: moonChain.anomalisticMonthSecondsAtAge,
+    meanNodalMonthAtAge: moonChain.nodalMonthSecondsAtAge,
+    meanApsidalMeetsNodalAtAge: moonChain.apsidalMeetsNodalSecondsAtAge,
+    meanLunarLevelingCycleAtAge: moonChain.lunarLevelingSecondsAtAge,
+    meanStellarDayAtAge, meanStellarDayProjectedAtAge, meanSiderealDayAtAge,
+    meanPlanetSemiMajorAxisAtAge,
+    /** @param {number} tMa @param {number} periodJ2000Seconds @returns {number} */
+    meanPlanetOrbitalPeriodAtAge: (tMa, periodJ2000Seconds) => driver2PeriodSecondsAtAge(tMa, periodJ2000Seconds, EPOCH_PARAMS.solarMassLossFracPerYear),
+    /** @param {number} tMa @param {number} periodJ2000Seconds @returns {number} */
+    meanEarthPlanetSynodicPeriodAtAge: (tMa, periodJ2000Seconds) => synodicPeriodSeconds(driver2PeriodSecondsAtAge(tMa, periodJ2000Seconds, EPOCH_PARAMS.solarMassLossFracPerYear), meanSiderealYearSecondsAtAge(tMa)),
+  });
+}

package/src/deltat/deep-time.cjs

@@ -43,8 +43,7 @@ const { createComposedPrecession } = require('../earth/precession-composed.cjs')
  * @property {number} eFactorMoon - √(1−e²) factor of the lunar orbit
  * @property {number} aLockMetres - tidal-lock distance (LOD denominator → 0)
  * @property {number} aMoonNowMetres - Farhat polynomial anchor
- * @property {number} alpha1PerMa @property {number} alpha3PerMa3
- * @property {number} alpha4PerMa4
+ * @property {number} alpha1PerMa - the LLR recession rate (the J2000 slope of the cited history)
  * @property {number} lodNowH13Seconds - ω₀, the J2000 day length (the SI day since plan 09; identifier kept)
  * @property {number} meanSiderealYearJ2000Seconds
  * @property {number} solarMassLossFracPerYear
@@ -55,7 +54,7 @@ const { createComposedPrecession } = require('../earth/precession-composed.cjs')
 /**
  * @typedef {Object} DeepTimeLodDeps
  * @property {DeepTimeLodConstants} constants
- * @property {(tMa: number) => number} moonDistanceMetresAtAge
+ * @property {(tMa: number) => number|null} moonDistanceMetresAtAge - null beyond the cited history's span
  * @property {(tMa: number) => number} moiFactorAtAge - GIA α(t)
  * @property {(year: number) => number} cycleLodSumAt - gated δLOD sum (incl. swing)
  * @property {(year: number) => number} swingLodAt - gated swing δLOD alone
@@ -74,9 +73,18 @@ const { createComposedPrecession } = require('../earth/precession-composed.cjs')
  *   formerly the spin unit's H/5, 67,063 yr, 2.5 % off and scaling with the
  *   spin at deep time). Lazy, like the precession anchor.
  * @property {(tMa: number) => number} [lEmAtAgeKgm2S] - OPTIONAL time-dependent
- *   Earth-Moon angular momentum (the Driver-1½ solar channels,
- *   recession-history.cjs). Absent → the J2000 constant, which the budget
- *   module equals exactly for t ≤ jointMa — the pure-twin convention.
+ *   Earth-Moon angular momentum. Absent → the J2000 constant: conservation
+ *   (plan 12 option A — the Driver-1½ solar-channel budget is deleted;
+ *   measured: conservation on the cited history reproduces Farhat's own LOD
+ *   to 0.01 h at 100 Ma, 0.14 h at 2.46 Ga).
+ * @property {(tMa: number) => number|null} [moonDistanceSlopeMetresPerMaAtAge] -
+ *   OPTIONAL analytic slope of the distance history (metres per Ma, positive
+ *   into the past means a growing a... sign as da/dt_Ma); absent → a central
+ *   difference on moonDistanceMetresAtAge (the LOD-rate decomposition's tidal term).
+ * @property {(tMa: number) => number|null} [meanObliquityCosRatioAtAge] -
+ *   OPTIONAL cos ε̄(t)/cos ε̄(0) of the cited mean obliquity (earth/mean-
+ *   obliquity-history) — the factor the precession RATE of date carries on the
+ *   constant (plan 12 §8 option (a)); absent → 1, the constant alone, bit-identical.
  */
 
 /** @param {DeepTimeLodDeps} deps */
@@ -88,7 +96,7 @@ function createDeepTimeLod(deps) {
    * @param {number} t_Ma @returns {number|null} seconds, null past tidal lock */
   function lodSecondsAtAge(t_Ma) {
     const a = deps.moonDistanceMetresAtAge(t_Ma);
-    if (a <= 0 || a >= K.aLockMetres) return null;
+    if (a === null || a <= 0 || a >= K.aLockMetres) return null;
     return (2 * Math.PI * (deps.moiFactorAtAge(t_Ma) * K.mEarthAloneKg * K.rEarthMetres * K.rEarthMetres)) /
            (lEmAt(t_Ma) - K.mMoonAloneKg * Math.sqrt(K.gmEmM3PerS2 * a) * K.eFactorMoon);
   }
@@ -97,7 +105,7 @@ function createDeepTimeLod(deps) {
    * @param {number} t_Ma @param {number} alpha @returns {number|null} */
   function lodSecondsAtAgeWithAlpha(t_Ma, alpha) {
     const a = deps.moonDistanceMetresAtAge(t_Ma);
-    if (a <= 0 || a >= K.aLockMetres) return null;
+    if (a === null || a <= 0 || a >= K.aLockMetres) return null;
     const iEarth = alpha * K.mEarthAloneKg * K.rEarthMetres * K.rEarthMetres;
     return (2 * Math.PI * iEarth) /
            (lEmAt(t_Ma) - K.mMoonAloneKg * Math.sqrt(K.gmEmM3PerS2 * a) * K.eFactorMoon);
@@ -122,13 +130,13 @@ function createDeepTimeLod(deps) {
   // year with the model's ΔT memo). Same operations, same inputs — every
   // value bit-identical (11,958-value sweep, 0 differences).
 
-  // The composed lunisolar precession rate (plan 06 D6 → Phase 3 → S5):
-  // ψ̇(t) = [ω(t)/ω₀]·p₀·[f_S + (1 − f_S)(a₀/a_M(t))³], p₀ the model's
-  // DERIVED J2000 rate 1,296,000/axial0 (the certified year-length laws'
-  // beat at 2000 ≈ 25,771.4 yr — NOT 1,296,000/(H₀/13) = 50.245 ″/yr, the
-  // fit anchor's reading, 0.086 % slow; S5). ONE formula home:
-  // earth/precession-composed, built here on this factory's own LOD and
-  // recession history; the anchor resolves lazily on the first rate use.
+  // The composed lunisolar precession (plan 06 D6 → Phase 3 → S5; plan 12 §8):
+  // the CONSTANT's scaling [ω(t)/ω₀]·p₀·[f_S + (1 − f_S)(a₀/a_M(t))³] and the
+  // RATE of date, that × cos ε̄(t)/cos ε̄(0) on the cited mean obliquity; p₀ the
+  // model's J2000 rate 1,296,000/axial0 (the IAU 2006 general precession since
+  // plan 09). ONE formula home: earth/precession-composed, built here on this
+  // factory's own LOD, recession and obliquity histories; the anchor resolves
+  // lazily on the first rate use.
   const composed = createComposedPrecession({
     p0ArcsecPerYr: () => 1296000 / deps.precessionPeriodJ2000YearsFn(),
     solarShare: K.precessionSolarShareJ2000,
@@ -137,23 +145,44 @@ function createDeepTimeLod(deps) {
     moonDistanceMetresAtAge: deps.moonDistanceMetresAtAge,
     moonDistanceJ2000Metres: K.aMoonNowMetres,
     yearToTMa: /** @param {number} year */ (year) => (2000 - year) / 1e6,
+    meanObliquityCosRatioAtAge: deps.meanObliquityCosRatioAtAge,
   });
 
 
-  /** The composed lunisolar precession rate, ″/yr — p₀·[ω/ω₀]·[f_S + (1 − f_S)
-   * (a₀/a_M)³] on the derived J2000 anchor (S5). ≡ 1,296,000·(H₀/axial0)/H(t).
+  /** THE PRECESSION RATE OF DATE ψ̇(t), ″/yr — the constant's scaling
+   * p₀·[ω/ω₀]·[f_S + (1 − f_S)(a₀/a_M)³] × cos ε̄(t)/cos ε̄(0), ε̄ the cited mean
+   * obliquity (plan 12 §8 option (a); the chain held cos ε̄ at J2000 before —
+   * 2.5 % of rate at 2.46 Ga, 2e-7 at 10 kyr). p₀ the J2000 anchor (S5).
    * @param {number} t_Ma @returns {number|null} */
   function lunisolarPrecessionRateArcsecPerYrAtAge(t_Ma) {
     return composed.composedRateArcsecPerYrAtAge(t_Ma);
   }
 
-  /** The mean lunisolar precession period T_p(t), years — 1,296,000/ψ̇(t);
-   * 25,771.4 at J2000 (the model's one J2000 precession reading, S5).
+  /** The mean lunisolar precession period T_p(t), years — 1,296,000/ψ̇(t) on
+   * the rate of date; 25,771.6 at J2000 (the model's one J2000 precession
+   * reading, S5). THE published deep-time clock.
    * @param {number} t_Ma @returns {number|null} */
   function lunisolarPrecessionPeriodYearsAtAge(t_Ma) {
     return composed.composedPeriodYearsAtAge(t_Ma);
   }
 
+  /** THE PRECESSION CONSTANT OF DATE as a rate on the J2000 obliquity, ″/yr —
+   * the spin and torque scaling alone, α(t)·cos ε̄₀. The hybrid obliquity
+   * integration takes this one: its own ŝ·n̂ carries the cosine.
+   * @param {number} t_Ma @returns {number|null} */
+  function lunisolarTorqueRateArcsecPerYrAtAge(t_Ma) {
+    return composed.torqueRateArcsecPerYrAtAge(t_Ma);
+  }
+  /** 1,296,000/the torque rate, years. @param {number} t_Ma @returns {number|null} */
+  function lunisolarTorquePeriodYearsAtAge(t_Ma) {
+    return composed.torquePeriodYearsAtAge(t_Ma);
+  }
+  /** cos ε̄(t)/cos ε̄(0) — the rate's obliquity factor (1 at J2000; 1 when no
+   * history is injected). @param {number} t_Ma @returns {number|null} */
+  function precessionObliquityFactorAtAge(t_Ma) {
+    return composed.obliquityFactorAtAge(t_Ma);
+  }
+
   /** Sidereal year seconds (Kepler under linear mass loss, dT/T = −2 dM/M).
    * @param {number} t_Ma @returns {number} */
   function siderealYearSecondsAtAge(t_Ma) {
@@ -172,7 +201,8 @@ function createDeepTimeLod(deps) {
 
   /** Tropical year of date, seconds — the sidereal year less the equinox's
    * own motion over one year: one turn per the composed lunisolar precession
-   * period T_p(t), 1/T_trop = 1/T_sid + ψ̇(t)/(1,296,000″ · Julian-year s).
+   * period T_p(t), 1/T_trop = 1/T_sid + ψ̇(t)/(1,296,000″ · Julian-year s),
+   * ψ̇(t) the RATE of date (with the cited mean obliquity's cosine, plan 12 §8).
    * Plan 09 step 5d: it was the unit's calendar convention sid·(1 − 13/H(t))
    * — plan 06 D2 had kept it as a named device — 0.086 % slow on the equinox
    * term (1.0 s of year at J2000), and the deep JD↔year calendar integrates
@@ -187,7 +217,8 @@ function createDeepTimeLod(deps) {
     const sidSec = siderealYearSecondsAtAge(t_Ma);
     const term = composed.torqueTermAtAge(t_Ma);
     const p0 = composed.p0ArcsecPerYr;
-    const rate = (LOD_s === null || !(LOD_s > 0) || term === null) ? p0 : (K.lodNowH13Seconds / LOD_s) * p0 * term;
+    const f = composed.obliquityFactorAtAge(t_Ma);
+    const rate = (LOD_s === null || !(LOD_s > 0) || term === null || f === null) ? p0 : (K.lodNowH13Seconds / LOD_s) * p0 * term * f;
     return 1 / (1 / sidSec + rate / (1296000 * 365.25 * 86400));
   }
 
@@ -300,10 +331,20 @@ function createDeepTimeLod(deps) {
     const I_E = alpha * K.mEarthAloneKg * K.rEarthMetres * K.rEarthMetres;
     const year = 2000 - t_Ma * 1e6;
 
-    // Farhat polynomial derivative: da/dyear = −A_now·(α₁ + 3α₃t² + 4α₄t³)/1e6
-    // (t_Ma > 0 = past; forward-time sign flip). At J2000: +3.82 cm/yr (LLR) ✓
-    const da_dt_yr = -K.aMoonNowMetres * (K.alpha1PerMa + 3 * K.alpha3PerMa3 * t_Ma * t_Ma
-                   + 4 * K.alpha4PerMa4 * t_Ma * t_Ma * t_Ma) / 1e6;
+    // The cited history's slope (plan 12 option A): the engine's
+    // moonDistanceSlopeMetresPerMaAtAge when it provides one (the Hermite's
+    // analytic derivative — C1, smooth), else a ±1-kyr central difference on
+    // the distance itself. t_Ma > 0 = past; forward-time sign flip. At J2000
+    // the slope IS the LLR observation (the history's boundary condition):
+    // +3.82 cm/yr ✓
+    let slopePerMa = deps.moonDistanceSlopeMetresPerMaAtAge ? deps.moonDistanceSlopeMetresPerMaAtAge(t_Ma) : null;
+    if (slopePerMa === null || slopePerMa === undefined) {
+      const H_MA = 1e-3;
+      const aPlus = deps.moonDistanceMetresAtAge(t_Ma + H_MA), aMinus = deps.moonDistanceMetresAtAge(t_Ma - H_MA);
+      if (aPlus === null || aMinus === null) return nullResult;
+      slopePerMa = (aPlus - aMinus) / (2 * H_MA);
+    }
+    const da_dt_yr = -slopePerMa / 1e6;
     const SEC_PER_YR = 365.25 * 86400;
     const da_dt_s = da_dt_yr / SEC_PER_YR;
 
@@ -346,6 +387,8 @@ function createDeepTimeLod(deps) {
   return {
     lodSecondsAtAge, lodSecondsAtAgeWithAlpha, lodHoursAtAge,
     lunisolarPrecessionRateArcsecPerYrAtAge, lunisolarPrecessionPeriodYearsAtAge,
+    // the constant's scaling alone (the hybrid's integrand) and the rate's obliquity factor (plan 12 §8)
+    lunisolarTorqueRateArcsecPerYrAtAge, lunisolarTorquePeriodYearsAtAge, precessionObliquityFactorAtAge,
     // the composition's terms (plan 06 Phase 3 S3, the lunisolar surface): (a₀/a_M)³ and f_S + (1 − f_S)(a₀/a_M)³
     lunarTorqueFactorAtAge: composed.lunarTorqueFactorAtAge,
     precessionTorqueTermAtAge: composed.torqueTermAtAge,