@essrt/physics 4.8.0 → 5.0.0

package/src/model.js

@@ -22,14 +22,14 @@ import * as FL from './planets/fibonacci-laws.cjs';
 import * as planetOrientation from './planets/orientation.cjs';
 import { createPhaseMachinery } from './phase/index.cjs';
 import { createCardinalModel } from './cardinal/index.cjs';
-import { createYearLengths } from './earth/year-lengths.cjs';
+import { createYearLengths, ONE_FAMILY_WINDOW_YEARS } from './earth/year-lengths.cjs';
 import { createDeepOrbitalHistory } from './earth/deep-orbital-history.cjs';
 import { CHAIN_ARTIFACT } from './planets/chain-artifact.js';
 import { buildPlanetChainsFromArtifactData, computeApsidalSecularDegPerYr } from './planets/keplerian-chain.cjs';
 import { createDeltaTCycles } from './deltat/cycles.cjs';
 import { createDeepTimeLod } from './deltat/deep-time.cjs';
 import { createMoonRecessionHistory, createSolarChannelBudget } from './deltat/recession-history.cjs';
-import { evalClimateL1OrbitalPermil } from './climate/l1-orbital.cjs';
+import { evalClimateL1OrbitalPermil, createAlphaGiaChannel } from './climate/l1-orbital.cjs';
 import { createMoonEccChannel } from './moon/ecc-channel.cjs';
 import { createDeepEccChannel } from './moon/deep-ecc-channel.cjs';
 import { DEEP_MODES_ARTIFACT } from './moon/deep-modes-artifact.cjs';
@@ -132,27 +132,42 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
   const GM_SUN = GM_SUN_PLUS_EARTH - GM_EARTH_ALONE;
   const M_SUN = GM_SUN / G_CONSTANT;
 
-  // ── α(t): climate-driven GIA channel with the R2 lattice pin ──────────────
+  // ── α(t): the GIA channel — the LAGGED response to the L1 ice history, with the R2 lattice pin ──
   const CLIMATE = F.CLIMATE_FORMULA_COEFFS;
   const CLIMATE_REGIME = CLIMATE.regimes['lr04-post-mpt'];
-  const alphaClimateScale = C.deepTime.alphaClimateScalePerMille;
 
-  /** @param {number} year @returns {number} */
+  /** The climate formula's L1 (unlagged) — the orbital δ¹⁸O layer itself. @param {number} year @returns {number} */
   const evalClimateL1 = (year) => evalClimateL1OrbitalPermil(year, {
     l1Terms: CLIMATE_REGIME.L1,
     yStdDenormalization: CLIMATE_REGIME.denormalization.y_std,
-    eightHKyr: CLIMATE.config.eight_H_kyr,
+  });
+  // ONE home (climate/l1-orbital.cjs): k derived from the Cox–Chao rate, τ the
+  // record-measured relaxation time (plan 06 D7). Same construction in
+  // src/script.js, tools/lib/deep-time.js and the website's essrt.ts.
+  const alphaGia = createAlphaGiaChannel({
+    l1Terms: CLIMATE_REGIME.L1,
+    yStdDenormalization: CLIMATE_REGIME.denormalization.y_std,
+    relaxationKyr: C.deepTime.alphaGiaRelaxationKyr,
+    alphaGiaRateJ2000PerYr: C.deepTime.alphaGiaRateJ2000PerYr,
+    alphaJ2000: earthMoiFactorJ2000,
   });
 
   let latticeAlphaPin = false;
-  /** @type {number|null} */
-  let alphaL1J2000 = null;
+  // Exact-argument memo (mirrors src/script.js + tools/lib/deep-time.js —
+  // the round-5 perf campaign): same tMa → bit-identical value; the pin
+  // branch bypasses the memo; bounded by wholesale clear.
+  /** @type {Map<number, number>} */
+  const alphaMemo = new Map();
   /** @param {number} tMa @returns {number} */
   const earthMoiFactorAtAge = (tMa) => {
     if (latticeAlphaPin) return earthMoiFactorJ2000;
-    if (alphaL1J2000 === null) alphaL1J2000 = evalClimateL1(2000);
-    const L1at = evalClimateL1(2000 - tMa * 1e6);
-    return earthMoiFactorJ2000 - alphaClimateScale * (L1at - alphaL1J2000);
+    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;
   };
 
   // ── Layer 0 + deep-time core ──────────────────────────────────────────────
@@ -175,6 +190,11 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
     moonDistanceKm,
     moonOrbitalEccentricity: C.moonReference.moonOrbitalEccentricityBase,
     gmEarthMoonSystemKm3S2: GM_EARTH_MOON_SYSTEM,
+    // the solar precession torque's inputs (plan 06 Phase 3: the unit H(t) = 13·T_p,composed)
+    gmSunKm3S2: GM_SUN,
+    astronomicalUnitKm: currentAUDistance,
+    earthOrbitalEccentricityJ2000: C.earthOrbital.earthEccentricityJ2000,
+    moonEclipticInclinationJ2000Deg: C.moonReference.moonEclipticInclinationJ2000,
   });
 
   // ── Driver 1½: regime-aware recession history + the solar channels ────────
@@ -261,6 +281,7 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
       meanSiderealYearJ2000Seconds: meanSiderealYearSeconds,
       solarMassLossFracPerYear: EPOCH_PARAMS.solarMassLossFracPerYear,
       siderealYearDaysKinematicJ2000: meanSiderealYearDaysKinematic,
+      precessionSolarShareJ2000: EPOCH_PARAMS.precessionSolarShareJ2000,
     },
     moonDistanceMetresAtAge,
     moiFactorAtAge: earthMoiFactorAtAge,
@@ -272,8 +293,12 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
   });
 
   // ── Integrated ∫1/H(t)dt phase (R2 α-pin honoured while building) ─────────
+  // The phase counter every FROZEN comb reads rides the frozen era clock's
+  // own convention H_era = H₀·LOD/LOD₀ (plan 06 D8: two named counters — the
+  // coefficients were fitted against this counter and ship with it), NOT the
+  // unit H(t) = 13·T_p,composed that the physics publishes.
   const phaseM = createPhaseMachinery({
-    holisticHAtAgeMa: (tMa) => deepLod.hAtAge(tMa),
+    holisticHAtAgeMa: (tMa) => deepLod.eraClockHAtAge(tMa),
     tableAnchorYear: startmodelYear,
     driftRefYear: startModelYearWithCorrection,
     hJ2000: H,
@@ -402,16 +427,19 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
     if (lod === null) return meanSiderealYearDays;
     return deepLod.siderealYearSecondsAtAge(tMa) / lod;
   };
+  // The comb family's bases are the FROZEN era clock's forms (H_era; plan 06
+  // D8) — the combs were fitted on them. The physical year lengths ride the
+  // unit through yearLengths (family B) and the tidal-chain mean.
   /** @param {number} year @returns {number} */
   const tropicalYearDaysBase = (year) => {
-    const days = deepLod.yearInDaysAtAge(yearToTMa(year));
+    const days = deepLod.eraClockYearInDaysAtAge(yearToTMa(year));
     return days === null ? meanSolarYearDays : days;
   };
   /** @param {number} year @returns {number} */
   const anomalisticYearDaysBase = (year) => {
     const tMa = yearToTMa(year);
-    const Ht = deepLod.hAtAge(tMa);
-    const tropD = deepLod.yearInDaysAtAge(tMa);
+    const Ht = deepLod.eraClockHAtAge(tMa);
+    const tropD = deepLod.eraClockYearInDaysAtAge(tMa);
     if (Ht === null || tropD === null) return meanAnomalisticYearDays;
     return (tropD * (Ht / 16)) / (Ht / 16 - 1);
   };
@@ -445,14 +473,16 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
     },
     fns: {
       cyclesBetween: (a, b, n) => phase().cyclesBetween(a, b, n),
+      // The frozen era clock's deps ride ITS convention H_era (plan 06 D8):
+      // drift integrand, dc/dY and the real-LOD convention were fitted on it.
       analyticTropicalDays: (year) => {
         const tMa = (startmodelYear - year) / 1e6;
-        const Ht = deepLod.hAtAge(tMa);
+        const Ht = deepLod.eraClockHAtAge(tMa);
         if (Ht === null) return null;
         return (deepLod.siderealYearSecondsAtAge(tMa) / 86400) * (1 - 13 / Ht);
       },
-      meanHAtAgeMa: (tMa) => deepLod.hAtAge(tMa),
-      meanYearRealLodDays: (tMa) => deepLod.yearInDaysAtAge(tMa),
+      meanHAtAgeMa: (tMa) => deepLod.eraClockHAtAge(tMa),
+      meanYearRealLodDays: (tMa) => deepLod.eraClockYearInDaysAtAge(tMa),
       eccentricityAt,
       eccentricityRateAt,
     },
@@ -463,9 +493,10 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
   // package's embedded deep-modes artifact; the banked-series tier is the
   // repo-data-bound instrument). Absolute dates deliberately absent — see
   // cardinal/one-source-structure.cjs. The mean year is SI SECONDS: the
-  // sidereal year of date reduced by the SECULAR α(H(t)) equinox precession
-  // (axial0·H(t)/H0 — the movement's leg-1 convention, NOT the H/13
-  // kinematic identity; the two are a recorded 0.09% relation tension).
+  // sidereal year of date reduced by the SECULAR equinox precession
+  // (axial0·H(t)/H₀ with H(t) the UNIT = 13·T_p,composed — plan 06 D6/Phase
+  // 3, the movement's leg-1 convention, NOT the H/13 kinematic identity at
+  // J2000; the two are a recorded 0.09% relation tension there).
   // THE ONE of-date year-length family (owner: "move to 1 implementation")
   // — createYearLengths owns tropical (equinox-rate mean, wobble included),
   // sidereal (the D6 λ̇ channel), anomalistic (the cardinal structure on
@@ -478,7 +509,13 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
   // path; the npm package alone has no 8 MB series), the movement runs the
   // SERIES tier exactly like the browser — killing the mode-vs-series
   // value split (measured: 6 s on the anomalistic year at J2000).
-  const yearLengthsM = (() => {
+  // The engine-D planet chains (ONE build; the one-family route's apsidal
+  // tangent and the lunisolar surface's n_aps read the same instance).
+  const kcChainsM = buildPlanetChainsFromArtifactData(CHAIN_ARTIFACT);
+  // The ONE-SOURCE movement: the hybrid's ε(t) (plan 06 Phase 3 S3b — THE
+  // published obliquity) and the one-family year lengths, on the same
+  // per-tier sampler.
+  const oneSourceM = (() => {
     const AEarth = /** @type {any} */ (CHAIN_ARTIFACT).j2000AnchorElements.earth;
     // The ψ̇ anchor: the CERTIFIED of-date laws at 2000 — identical to the
     // engine/browser (computeSiderealYearDaysDirect / computeSolarYearDays
@@ -490,6 +527,12 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
     const sidLaw2000 = evalYearFourier(2000, siderealYearDaysBase(2000), F.SIDEREAL_YEAR_HARMONICS);
     const solLaw2000 = evalYearFourier(2000, tropicalYearDaysBase(2000), F.TROPICAL_YEAR_HARMONICS);
     const axial0 = sidLaw2000 / (sidLaw2000 - solLaw2000);
+    // D6 → Phase 3 (plan 06): the deep-time ψ̇(t) the hybrid precesses on is
+    // the COMPOSED lunisolar rate, and since Phase 3 the unit H(t) IS
+    // 13 × that period (deltat/deep-time.cjs hAtAge), so the injection is
+    // the plain period₀·H(t)/H₀ again — on the unit, not on the frozen
+    // era clock's H_era (which misses the lunar 1/a³ growth: 70.9 vs
+    // Lantink 2022's 108.6 ± 8.5 ″/yr at 2.46 Ga; the unit reads 104.5).
     const H0 = /** @type {number} */ (deepLod.hAtAge(0));
     const seriesArt = /** @type {any} */ (secularSeriesArtifact);
     const sb = seriesArt && seriesArt.bodies && seriesArt.bodies.earth;
@@ -505,7 +548,13 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
       anchorInclEclipticDeg: AEarth.inclEclipticDeg,
       anchorAscNodeEclipticDeg: AEarth.ascNodeEclipticDeg,
       axialPrecessionYearsJ2000: axial0,
-      obliquityJ2000Deg: obliquityDeg(2000),
+      // Phase 3 S3b: the hybrid's initial condition is the OBSERVED J2000
+      // mean obliquity — the IAU 2006 input constant (84381.406″), the same
+      // anchor the browser's _deepHistSeries and the Node one-source movement
+      // use. It was the K comb's own J2000 value, 0.233″ above IAU: a
+      // rendering-device residual imported as the initial condition of the
+      // physics (found when the package began publishing the hybrid).
+      obliquityJ2000Deg: C.earthOrbital.obliquityJ2000_deg,
       axialPrecessionYearsAtYearFn: (yr) => {
         const h = deepLod.hAtAge((startmodelYear - yr) / 1e6);
         return axial0 * (h === null ? 1 : h / H0);
@@ -534,13 +583,19 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
     };
     // The anomalistic rides the chain's SECULAR apsidal tangent (the same
     // rate family the panel's Prec. cell shows) — ONE helper, keplerian-chain.
-    const kcChains = buildPlanetChainsFromArtifactData(CHAIN_ARTIFACT);
-    return createYearLengths({
+    const kcChains = kcChainsM;
+    const yearLengths = createYearLengths({
       sampleAt,
       massLossSiderealSecondsAtYearFn: (year) => deepLod.siderealYearSecondsAtAge(yearToTMa(year)),
       apsidalSecularDegPerYrFn: (year) => computeApsidalSecularDegPerYr(year, kcChains.earth, kcChains),
     });
+    return {
+      yearLengths,
+      /** The hybrid's obliquity at a decimal year, degrees — the banked series inside its span, the α(t)-coupled ζ-tail integration beyond (the deep sampler grows ~0.1 s/Myr). @param {number} year @returns {number} */
+      epsAt: (year) => sampleAt(year).epsDeg,
+    };
   })();
+  const yearLengthsM = oneSourceM.yearLengths;
 
   /** Tropical year: mean of the four cardinal intervals. @param {number} year @returns {number} */
   const tropicalYearDays = (year) => cardinalM.computeTropicalYearLength(year);
@@ -1159,6 +1214,22 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
   });
 
   // ── The assembled surface ─────────────────────────────────────────────────
+  // Plan 06 Phase 3 S2 — THE published of-date precession period and mean
+  // tropical year: the one-family route (B) inside the banked tiers
+  // (|Δyear| ≤ ONE_FAMILY_WINDOW_YEARS), the unit's secular mean beyond
+  // (H(t)/13; the tidal-chain year). Shared by `epoch` and `lunisolar`.
+  /** @param {number} year @returns {number} */
+  const publishedAxialPrecessionYearsAtYear = (year) => {
+    if (Math.abs(year - 2000) <= ONE_FAMILY_WINDOW_YEARS) return yearLengthsM.axialPrecessionYearsAtYear(year);
+    const h = deepLod.hAtAge(yearToTMa(year));
+    return (h === null ? H : h) / 13;
+  };
+  /** @param {number} year @returns {number} */
+  const publishedTropicalYearSecondsAtYear = (year) => {
+    if (Math.abs(year - 2000) <= ONE_FAMILY_WINDOW_YEARS) return yearLengthsM.tropicalYearSecondsAtYear(year);
+    return deepLod.tropicalYearSecondsAtAge(yearToTMa(year));
+  };
+
   return Object.freeze({
     time: Object.freeze({
       yearFromJD,
@@ -1176,22 +1247,94 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
       siderealYearSecondsAtYear: /** @param {number} year @returns {number} */ (year) => yearLengthsM.siderealYearSecondsAtYear(year),
       deltaTSecondsAtYear: deltaTSeconds,
       cyclesBetween,
-      // The DYNAMICAL axial precession period (the tweakpane identity):
-      // day-form beat of the sidereal and solar year evaluators — real at
-      // J2000 (~25,771 yr ≈ IAU), epoch-valid at any age. The same value
-      // the (d′) of-date rate completion integrates.
-      axialPrecessionYearsAtYear: /** @param {number} year @returns {number} */ (year) => {
-        const sid = siderealYearDays(year);
-        return sid / (sid - tropicalYearDirectDays(year));
+      // Plan 06 Phase 3 S2 — THE published of-date precession period is the
+      // one-family route (B): the hybrid's own equinox regression against
+      // the λ̇-corrected sidereal year (~25,771 yr at J2000 ≈ IAU), inside
+      // the banked tiers (|Δyear| ≤ ONE_FAMILY_WINDOW_YEARS); beyond, the
+      // unit's SECULAR mean H(t)/13 = the composed lunisolar period (the
+      // of-date wobble is unresolved there). The comb family's beat
+      // sid/(sid − tropicalYearDirectDays) — the frozen era clock's
+      // kinematic-day device — is no longer published here; it still
+      // anchors the lunar chain's (d′) rate completion (pDynDegPerYearAt,
+      // a MATCHED TRIPLE with the eclipse gates: M0(a) measured a 3–15 min
+      // lunar-timing shift if it moved).
+      axialPrecessionYearsAtYear: publishedAxialPrecessionYearsAtYear,
+      // The same publication rule for the mean tropical year of date (SI s):
+      // one-family inside the window, the tidal-chain mean beyond.
+      tropicalYearSecondsAtYear: publishedTropicalYearSecondsAtYear,
+    }),
+    // Plan 06 Phase 3 S3 — the lunisolar precession clock as a first-class
+    // surface: Earth's spin clock, ONE home for its published faces, spoken
+    // in PERIODS and their RATIOS — no unit, no integer. T_p(t) is the
+    // composed lunisolar period (calculation map 2.1 step 6; the internal
+    // identifier H is 13·T_p by definition and is not a face here); the
+    // composition's terms; the of-date beat (the published family, seamed
+    // at ±2 Myr); the apsidal period from the engine-D chain's secular
+    // tangent and the two ratios the owner found wandering by hand —
+    // T_aps/T_p (4.33 at J2000, 0.84 … 9.5 across ±26 kyr) and T_peri/T_p
+    // with T_peri = 1/(1/T_p + 1/T_aps) the perihelion-of-date period
+    // (0.812 at J2000). That these read close to 13/3 and 13/16 today is
+    // the J2000 reading, stated nowhere as structure.
+    lunisolar: Object.freeze({
+      /** The mean lunisolar precession period T_p(t), years — the composed torque rate's period. @param {number} year @returns {number} */
+      meanPeriodYearsAtYear: (year) => { const h = deepLod.hAtAge(yearToTMa(year)); return (h === null ? H : h) / 13; },
+      /** The composed rate ψ̇(t) = [ω/ω₀]·p₀·[f_S + (1 − f_S)(a₀/a_M)³], ″/yr. @param {number} year @returns {number} */
+      meanRateArcsecPerYrAtYear: (year) => { const r = deepLod.lunisolarPrecessionRateArcsecPerYrAtAge(yearToTMa(year)); return r === null ? 1296000 / (H / 13) : r; },
+      /** The of-date period — the one-family beat inside ±2 Myr, the mean beyond. @param {number} year @returns {number} */
+      ofDatePeriodYearsAtYear: publishedAxialPrecessionYearsAtYear,
+      /** f_S, the solar fraction of the J2000 precession torque. */
+      solarShareJ2000: EPOCH_PARAMS.precessionSolarShareJ2000,
+      /** (a₀/a_M(t))³ — the lunar torque's growth on the recession history. @param {number} year @returns {number} */
+      lunarTorqueFactorAtYear: (year) => { const f = deepLod.lunarTorqueFactorAtAge(yearToTMa(year)); return f === null ? 1 : f; },
+      /** f_S + (1 − f_S)(a₀/a_M)³ — the torque term the unit divides H_era by. @param {number} year @returns {number} */
+      torqueTermAtYear: (year) => { const t = deepLod.precessionTorqueTermAtAge(yearToTMa(year)); return t === null ? 1 : t; },
+      /** The hybrid's precession constant α = p₀ / cos ε₀, ″/yr (ε₀ the J2000 obliquity input). */
+      torqueConstantJ2000ArcsecPerYr: (1296000 / (H / 13)) / Math.cos((C.earthOrbital.obliquityJ2000_deg * Math.PI) / 180),
+      /** The apsidal (perihelion vs the stars) period from the engine-D chain's secular tangent, years — inside the published window only (the tangent is an extrapolation beyond the banked series: it turns negative at −5 Myr); null beyond. @param {number} year @returns {number|null} */
+      apsidalPeriodYearsAtYear: (year) => (Math.abs(year - 2000) <= ONE_FAMILY_WINDOW_YEARS ? 360 / computeApsidalSecularDegPerYr(year, kcChainsM.earth, kcChainsM) : null),
+      /** T_aps(t) / T_p(t) — the apsidal period in mean precession periods (4.33 at J2000, a fitted reading; 0.84 … 9.5 across ±26 kyr, measured); null beyond the published window. @param {number} year @returns {number|null} */
+      apsidalPerPrecessionAtYear: (year) => {
+        if (Math.abs(year - 2000) > ONE_FAMILY_WINDOW_YEARS) return null;
+        const h = deepLod.hAtAge(yearToTMa(year));
+        return (360 / computeApsidalSecularDegPerYr(year, kcChainsM.earth, kcChainsM)) / ((h === null ? H : h) / 13);
+      },
+      /** T_peri(t) = 1/(1/T_p + 1/T_aps) — the perihelion-of-date period (equinox precession + inertial perihelion motion, frame arithmetic at every epoch), years; null beyond the published window. @param {number} year @returns {number|null} */
+      periOfDatePeriodYearsAtYear: (year) => {
+        if (Math.abs(year - 2000) > ONE_FAMILY_WINDOW_YEARS) return null;
+        const h = deepLod.hAtAge(yearToTMa(year));
+        const tp = (h === null ? H : h) / 13, taps = 360 / computeApsidalSecularDegPerYr(year, kcChainsM.earth, kcChainsM);
+        return 1 / (1 / tp + 1 / taps);
+      },
+      /** T_peri(t) / T_p(t) (0.812 at J2000 — the J2000 reading); null beyond the published window. @param {number} year @returns {number|null} */
+      periOfDatePerPrecessionAtYear: (year) => {
+        if (Math.abs(year - 2000) > ONE_FAMILY_WINDOW_YEARS) return null;
+        const h = deepLod.hAtAge(yearToTMa(year));
+        const tp = (h === null ? H : h) / 13, taps = 360 / computeApsidalSecularDegPerYr(year, kcChainsM.earth, kcChainsM);
+        return (1 / (1 / tp + 1 / taps)) / tp;
       },
+      /** The published of-date window, years from 2000. */
+      publishedWindowYears: ONE_FAMILY_WINDOW_YEARS,
     }),
     earth: Object.freeze({
       perihelionLongitudeDeg: earthPerihelionDeg,
-      obliquityDeg,
+      // Plan 06 Phase 3 S3b: THE published obliquity is the hybrid — one
+      // torque law integrated on the dynamical orbit plane of the N-body
+      // chain, zero fitted constants (≡ La2004 to ≤ 4″ over ±50 kyr). The
+      // fitted 16-harmonic K comb, a device fitted to the scene's own
+      // wheel geometry (0.005″ to it, 1.27° off La2004 at −20 kyr), keeps
+      // its name below as the frozen era clock's device: it anchors the
+      // hybrid at J2000, the kinematic-day stack and the lunar arguments.
+      obliquityDeg: /** @param {number} year @returns {number} */ (year) => oneSourceM.epsAt(year),
+      obliquityCombDeg: obliquityDeg,
       eccentricity: eccentricityAt,
       inclinationDeg,
       ascendingNodeDeg,
     }),
+    // The DEVICE family (plan 06 Phase 3 S2): the frozen era clock's comb
+    // year lengths (A), its cardinal 4-mean (A′) and the kinematic-day stack
+    // built on them (the ΔT stack's Layer 3/4 basis, USNO-anchored). NOT the
+    // published year lengths — those are `yearLengths` (the one-family
+    // route) and the seamed `epoch.*AtYear` surfaces above.
     lengths: Object.freeze({
       tropicalYearDays,
       tropicalYearDirectDays,