@essrt/physics 4.8.0 → 5.0.0

package/types/constants/index.d.ts

@@ -0,0 +1,2 @@
+export { DEFAULT_CONSTANTS, CONSTANTS_HASH, MODEL_VERSION, PREPRINT_DOI, REFERENCE_DATA } from "./generated.js";
+export { FITTED_COEFFICIENTS, COEFFICIENTS_HASH } from "./coefficients.js";

package/types/deltat/cycles.d.cts

@@ -0,0 +1,72 @@
+export type CycleSpec = {
+    latticeN: number;
+    cosCoeffSeconds: number;
+    sinCoeffSeconds: number;
+};
+export type ResonatorKick = {
+    tYear: number;
+    cosSeconds: number;
+    sinSeconds: number;
+};
+export type ResonatorTone = {
+    dn: number;
+    phiLockedRad: number;
+    ampSeconds: number;
+};
+export type DeltaTCyclesDeps = {
+    /**
+     * - 8 × the holistic year (J2000)
+     */
+    eightHYears: number;
+    /**
+     * - full strength within |y−2000| ≤ this
+     */
+    taperFullHalfwidthYears: number;
+    /**
+     * - zero beyond
+     */
+    taperTotalHalfwidthYears: number;
+    /**
+     * - δLOD denominator (variation ≤1e-8 in-window)
+     */
+    tropicalYearSecondsJ2000: number;
+    /**
+     * - keyed bond/hallstatt/jose5/jose4
+     */
+    cycles: Record<string, CycleSpec>;
+    resonator: {
+        t0LatticeN: number;
+        q: number;
+        kicks: ResonatorKick[];
+        tones: ResonatorTone[];
+    };
+};
+/**
+ * @typedef {{ latticeN: number, cosCoeffSeconds: number, sinCoeffSeconds: number }} CycleSpec
+ * @typedef {{ tYear: number, cosSeconds: number, sinSeconds: number }} ResonatorKick
+ * @typedef {{ dn: number, phiLockedRad: number, ampSeconds: number }} ResonatorTone
+ */
+/**
+ * @typedef {Object} DeltaTCyclesDeps
+ * @property {number} eightHYears - 8 × the holistic year (J2000)
+ * @property {number} taperFullHalfwidthYears - full strength within |y−2000| ≤ this
+ * @property {number} taperTotalHalfwidthYears - zero beyond
+ * @property {number} tropicalYearSecondsJ2000 - δLOD denominator (variation ≤1e-8 in-window)
+ * @property {Record<string, CycleSpec>} cycles - keyed bond/hallstatt/jose5/jose4
+ * @property {{ t0LatticeN: number, q: number, kicks: ResonatorKick[],
+ *   tones: ResonatorTone[] }} resonator
+ */
+/**
+ * Build the cycle-correction evaluators over one engine's constant set.
+ * All evaluators are UNGATED — the engines own their enable flags.
+ * @param {DeltaTCyclesDeps} deps
+ */
+export function createDeltaTCycles(deps: DeltaTCyclesDeps): {
+    taperAt: (year: number) => number;
+    taperDerivativeAt: (year: number) => number;
+    cycleDeltaTSecondsAt: (cycleKey: string, year: number) => number;
+    cycleLodSecondsAt: (cycleKey: string, year: number) => number;
+    swingDeltaTSecondsAt: (year: number) => number;
+    swingLodSecondsAt: (year: number) => number;
+    swingLodRateAt: (year: number) => number;
+};

package/types/deltat/deep-time.d.cts

@@ -0,0 +1,135 @@
+export type DeepTimeLodConstants = {
+    /**
+     * - Earth–Moon total angular momentum
+     */
+    lTotalEmKgm2S: number;
+    mMoonAloneKg: number;
+    mEarthAloneKg: number;
+    rEarthMetres: number;
+    /**
+     * - GM of the Earth–Moon system
+     */
+    gmEmM3PerS2: number;
+    /**
+     * - √(1−e²) factor of the lunar orbit
+     */
+    eFactorMoon: number;
+    /**
+     * - tidal-lock distance (LOD denominator → 0)
+     */
+    aLockMetres: number;
+    /**
+     * - Farhat polynomial anchor
+     */
+    aMoonNowMetres: number;
+    alpha1PerMa: number;
+    alpha3PerMa3: number;
+    alpha4PerMa4: number;
+    holisticYearJ2000: number;
+    /**
+     * - the H/13-identity mean LOD at J2000
+     */
+    lodNowH13Seconds: number;
+    meanSiderealYearJ2000Seconds: number;
+    solarMassLossFracPerYear: number;
+    /**
+     * - Actual-LOD numerator
+     */
+    siderealYearDaysKinematicJ2000: number;
+    /**
+     * - f_S, the solar fraction of the J2000
+     * precession torque (derive-params) — the unit H(t) = 13·T_p,composed needs it
+     */
+    precessionSolarShareJ2000: number;
+};
+export type DeepTimeLodDeps = {
+    constants: DeepTimeLodConstants;
+    moonDistanceMetresAtAge: (tMa: number) => number;
+    /**
+     * - GIA α(t)
+     */
+    moiFactorAtAge: (tMa: number) => number;
+    siderealYearDaysFourierAt: (year: number) => number;
+    /**
+     * - gated δLOD sum (incl. swing)
+     */
+    cycleLodSumAt: (year: number) => number;
+    /**
+     * - gated swing δLOD alone
+     */
+    swingLodAt: (year: number) => number;
+    /**
+     * - gated analytic swing rate
+     */
+    swingLodRateAt: (year: number) => number;
+    /**
+     * - 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.
+     */
+    lEmAtAgeKgm2S?: ((tMa: number) => number) | undefined;
+};
+/**
+ * @typedef {Object} DeepTimeLodConstants
+ * @property {number} lTotalEmKgm2S - Earth–Moon total angular momentum
+ * @property {number} mMoonAloneKg
+ * @property {number} mEarthAloneKg
+ * @property {number} rEarthMetres
+ * @property {number} gmEmM3PerS2 - GM of the Earth–Moon system
+ * @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} holisticYearJ2000
+ * @property {number} lodNowH13Seconds - the H/13-identity mean LOD at J2000
+ * @property {number} meanSiderealYearJ2000Seconds
+ * @property {number} solarMassLossFracPerYear
+ * @property {number} siderealYearDaysKinematicJ2000 - Actual-LOD numerator
+ * @property {number} precessionSolarShareJ2000 - f_S, the solar fraction of the J2000
+ *   precession torque (derive-params) — the unit H(t) = 13·T_p,composed needs it
+ */
+/**
+ * @typedef {Object} DeepTimeLodDeps
+ * @property {DeepTimeLodConstants} constants
+ * @property {(tMa: number) => number} moonDistanceMetresAtAge
+ * @property {(tMa: number) => number} moiFactorAtAge - GIA α(t)
+ * @property {(year: number) => number} siderealYearDaysFourierAt
+ * @property {(year: number) => number} cycleLodSumAt - gated δLOD sum (incl. swing)
+ * @property {(year: number) => number} swingLodAt - gated swing δLOD alone
+ * @property {(year: number) => number} swingLodRateAt - gated analytic swing rate
+ * @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.
+ */
+/** @param {DeepTimeLodDeps} deps */
+export function createDeepTimeLod(deps: DeepTimeLodDeps): {
+    lodSecondsAtAge: (t_Ma: number) => number | null;
+    lodSecondsAtAgeWithAlpha: (t_Ma: number, alpha: number) => number | null;
+    lodHoursAtAge: (t_Ma: number) => number | null;
+    hAtAge: (t_Ma: number) => number | null;
+    lunisolarPrecessionRateArcsecPerYrAtAge: (t_Ma: number) => number | null;
+    lunarTorqueFactorAtAge: (tMa: number) => (number | null);
+    precessionTorqueTermAtAge: (tMa: number) => (number | null);
+    siderealYearSecondsAtAge: (t_Ma: number) => number;
+    tropicalYearSecondsAtAge: (t_Ma: number) => number;
+    tropicalYearDaysAtAge: (t_Ma: number) => number | null;
+    yearInDaysAtAge: (t_Ma: number) => number | null;
+    deltaTRawSecondsAtAge: (t_Ma: number) => number;
+    lodSecondsWithCorrectionsAtAge: (t_Ma: number) => number | null;
+    lodSecondsActualAtAge: (t_Ma: number) => number | null;
+    dLodDtDecompositionAtAge: (t_Ma: number) => {
+        tidal: number | null;
+        gia: number | null;
+        stack: number | null;
+        resonator: number | null;
+        net_L2: number | null;
+        net_L3: number | null;
+        net_L4: number | null;
+    };
+    eraClockHAtAge: (t_Ma: number) => number | null;
+    eraClockTropicalYearSecondsAtAge: (t_Ma: number) => number;
+    eraClockYearInDaysAtAge: (t_Ma: number) => number | null;
+};

package/types/deltat/historical.d.cts

@@ -0,0 +1,8 @@
+/**
+ * Espenak/Meeus ΔT in seconds — the FULL published canon: separate
+ * 1986–2005 segment, and the −20 + 32u² parabola (with the −0.5628
+ * correction above 2050) outside the tabulated range instead of NaN.
+ * @param {number} year - calendar year
+ * @returns {number}
+ */
+export function deltaTEspenakMeeusCanonSeconds(year: number): number;

package/types/deltat/recession-history.d.cts

@@ -0,0 +1,80 @@
+export type RecessionRegime = {
+    /**
+     * - regime boundary; quartic below, spline above
+     */
+    jointMa: number;
+    /**
+     * - interior knot ages (ascending)
+     */
+    knotAgesMa: number[];
+    /**
+     * - fitted knot distances
+     */
+    knotDistancesKm: number[];
+    /**
+     * - the Roche-crossing epoch
+     */
+    genesisMa: number;
+    /**
+     * - the rigid Roche endpoint
+     */
+    rocheLimitKm: number;
+};
+/**
+ * @typedef {Object} RecessionRegime
+ * @property {number} jointMa - regime boundary; quartic below, spline above
+ * @property {number[]} knotAgesMa - interior knot ages (ascending)
+ * @property {number[]} knotDistancesKm - fitted knot distances
+ * @property {number} genesisMa - the Roche-crossing epoch
+ * @property {number} rocheLimitKm - the rigid Roche endpoint
+ */
+/**
+ * @param {{
+ *   aMoonNowMetres: number,
+ *   alpha1PerMa: number, alpha3PerMa3: number, alpha4PerMa4: number,
+ *   regime: RecessionRegime,
+ * }} deps
+ * @returns {{ distanceMetresAtAge: (tMa: number) => number }}
+ */
+export function createMoonRecessionHistory(deps: {
+    aMoonNowMetres: number;
+    alpha1PerMa: number;
+    alpha3PerMa3: number;
+    alpha4PerMa4: number;
+    regime: RecessionRegime;
+}): {
+    distanceMetresAtAge: (tMa: number) => number;
+};
+/**
+ * The solar angular-momentum channels: L_EM(t) integrated backward from
+ * J2000 with the ocean leak and the thermal-tide pump, explicit only
+ * beyond jointMa. Absent this module, every consumer's L_EM is the J2000
+ * constant — which remains the exact behaviour for t ≤ jointMa.
+ *
+ * @param {{
+ *   lTotalJ2000KgM2S: number,
+ *   mMoonAloneKg: number, gmEmM3PerS2: number, eFactorMoon: number,
+ *   beta0: number,
+ *   pumpStartMa: number, pumpEndMa: number, pumpFactor: number,
+ *   jointMa: number, genesisMa: number,
+ *   distanceMetresAtAge: (tMa: number) => number,
+ *   stepMa?: number,
+ * }} deps
+ * @returns {{ lEmAtAgeKgm2S: (tMa: number) => number }}
+ */
+export function createSolarChannelBudget(deps: {
+    lTotalJ2000KgM2S: number;
+    mMoonAloneKg: number;
+    gmEmM3PerS2: number;
+    eFactorMoon: number;
+    beta0: number;
+    pumpStartMa: number;
+    pumpEndMa: number;
+    pumpFactor: number;
+    jointMa: number;
+    genesisMa: number;
+    distanceMetresAtAge: (tMa: number) => number;
+    stepMa?: number;
+}): {
+    lEmAtAgeKgm2S: (tMa: number) => number;
+};

package/types/earth/deep-orbital-history.d.cts

@@ -0,0 +1,77 @@
+/**
+ * @param {{
+ *   zModes: ReadonlyArray<{omegaRadPerYr: number, re: number, im: number}>,
+ *   zetaModes: ReadonlyArray<{omegaRadPerYr: number, re: number, im: number}>,
+ *   zetaSeries?: {t0Yr: number, stepYr: number,
+ *                 q: ReadonlyArray<number>, p: ReadonlyArray<number>},
+ *   zSeries?: {t0Yr: number, stepYr: number,
+ *              q: ReadonlyArray<number>, p: ReadonlyArray<number>},
+ *   anchorE: number,
+ *   anchorPeriEclipticDeg: number,
+ *   anchorInclEclipticDeg: number,
+ *   anchorAscNodeEclipticDeg: number,
+ *   axialPrecessionYearsJ2000: number,
+ *   obliquityJ2000Deg: number,
+ *   axialPrecessionYearsAtYearFn?: (year: number) => number,
+ * }} deps — mode tables from the governed deep artifact (choose the ζ tier
+ *   per consumer: era = its own 8-term extraction, deep = the 16-term
+ *   table; NEVER a slice); anchors from the chain artifact's one home; the
+ *   axial-precession years and ε₀ from the injecting engine's certified
+ *   surfaces. zetaSeries (C-2, the ONE-SOURCE evaluator): the BANKED engine
+ *   ζ series (data/nbody-earth-zeta-series.json) — when supplied, n̂(t)
+ *   reads the series itself inside its span (no mode extraction, no tiers;
+ *   measured at the 500-yr artifact cadence: 0.16″/0.18″ rms vs IAU-2006
+ *   over 1900–2100/1600–2400 vs the era tier's 0.31″/0.63″, and 0.0396°
+ *   vs La2004 over −200 kyr vs the deep tier's 0.069° — the C-1 verdict,
+ *   plan 02) and zetaModes serves only as the TAIL beyond the span (the
+ *   seam at the span edge is the extraction residual, far outside every
+ *   certified window).
+ */
+export function createDeepOrbitalHistory({ zModes, zetaModes, zetaSeries, zSeries, anchorE, anchorPeriEclipticDeg, anchorInclEclipticDeg, anchorAscNodeEclipticDeg, axialPrecessionYearsJ2000, obliquityJ2000Deg, axialPrecessionYearsAtYearFn, }: {
+    zModes: ReadonlyArray<{
+        omegaRadPerYr: number;
+        re: number;
+        im: number;
+    }>;
+    zetaModes: ReadonlyArray<{
+        omegaRadPerYr: number;
+        re: number;
+        im: number;
+    }>;
+    zetaSeries?: {
+        t0Yr: number;
+        stepYr: number;
+        q: ReadonlyArray<number>;
+        p: ReadonlyArray<number>;
+    };
+    zSeries?: {
+        t0Yr: number;
+        stepYr: number;
+        q: ReadonlyArray<number>;
+        p: ReadonlyArray<number>;
+    };
+    anchorE: number;
+    anchorPeriEclipticDeg: number;
+    anchorInclEclipticDeg: number;
+    anchorAscNodeEclipticDeg: number;
+    axialPrecessionYearsJ2000: number;
+    obliquityJ2000Deg: number;
+    axialPrecessionYearsAtYearFn?: (year: number) => number;
+}): {
+    build: (t0Yr: number, t1Yr: number, stepYr: number) => {
+        /** @param {number} tYr */
+        at(tYr: number): {
+            epsDeg: number;
+            e: number;
+            periOfDateDeg: number;
+            eSinPeri: number;
+            eCosPeri: number;
+            inclEclDeg: number;
+            equinoxLonJ2000Deg: number;
+            equinoxLonRateDegPerYr: number;
+        };
+    };
+    alphaArcsecPerYr: number;
+    alphaLunisolarArcsecPerYr: number;
+    axialPrecessionYearsLunisolarJ2000: number;
+};

package/types/earth/precession-composed.d.cts

@@ -0,0 +1,59 @@
+/**
+ * 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]
+ */
+export function computeSolarTorqueShare(c: {
+    gmSunKm3S2: number;
+    auKm: number;
+    earthEccentricity: number;
+    gmMoonKm3S2: number;
+    moonDistanceKm: number;
+    moonEccentricity: number;
+    moonInclinationDeg: number;
+}): number;
+/**
+ * @param {{
+ *   p0ArcsecPerYr: number,
+ *   solarShare: number,
+ *   lodSecondsAtAge: (tMa: number) => (number | null),
+ *   lodJ2000Seconds: number,
+ *   moonDistanceMetresAtAge: (tMa: number) => (number | null),
+ *   moonDistanceJ2000Metres: number,
+ *   yearToTMa: (year: number) => number,
+ * }} deps - p0 = 1,296,000/(H/13) (the model's J2000 rate); 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,
+ * }}
+ */
+export function createComposedPrecession(deps: {
+    p0ArcsecPerYr: number;
+    solarShare: number;
+    lodSecondsAtAge: (tMa: number) => (number | null);
+    lodJ2000Seconds: number;
+    moonDistanceMetresAtAge: (tMa: number) => (number | null);
+    moonDistanceJ2000Metres: number;
+    yearToTMa: (year: number) => number;
+}): {
+    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;
+};

package/types/earth/sidereal-channel-artifact.d.cts

@@ -0,0 +1,12 @@
+export const SIDEREAL_CHANNEL_ARTIFACT: Readonly<{
+    t0Yr: -10000000;
+    stepYr: 2000;
+    windowYr: 2000;
+    lamDotRel: number[];
+    meta: {
+        dumpSha256: string;
+        source: string;
+        chaprontGate: number;
+    };
+}>;
+export const SIDEREAL_CHANNEL_ARTIFACT_HASH: "528101ca3410dc9b";

package/types/earth/sidereal-year-channel.d.cts

@@ -0,0 +1,38 @@
+/**
+ * @param {{
+ *   t0Yr?: number,
+ *   stepYr?: number,
+ *   lamDotRel?: number[],
+ *   massLossSiderealSecondsAtYearFn: (year: number) => number,
+ * }} opts
+ *   t0Yr/stepYr/lamDotRel: the banked channel geometry (t in years from
+ *   J2000: t_i = t0Yr + i·stepYr) — default: the embedded
+ *   SIDEREAL_CHANNEL_ARTIFACT (generate.mjs-owned, pinned to the governed
+ *   series artifact), so callers normally pass only the mass-loss law.
+ *   massLossSiderealSecondsAtYearFn: the caller's secular mass-loss
+ *   sidereal-year law, SI seconds (year = calendar year).
+ */
+export function createSiderealYearChannel(opts: {
+    t0Yr?: number;
+    stepYr?: number;
+    lamDotRel?: number[];
+    massLossSiderealSecondsAtYearFn: (year: number) => number;
+}): {
+    /** The planetary λ̇ ratio to J2000 (1 outside the banked span). @param {number} year */
+    planetaryRelAtYear: (year: number) => number;
+    /** The sidereal year of date, SI seconds. @param {number} year */
+    siderealYearSecondsAtYear: (year: number) => number;
+    /**
+     * Apply the λ̇ drift COHERENTLY to any year length (tropical,
+     * anomalistic, …): every year is 360/(λ̇ + X) for some geometric rate
+     * X (equinox p, apsidal −ϖ̇, 0 for sidereal), and the channel scales
+     * λ̇ only — so the correction is on the RATE, not the period:
+     *   1/T' = 1/T + (rel − 1)/T_sid_raw
+     * (for the sidereal year itself this reduces exactly to T/rel).
+     * Correcting periods by division instead would corrupt beat-derived
+     * quantities (P = sid/(sid − trop) amplifies ~20×/s); this form
+     * leaves every beat invariant to second order.
+     * @param {number} year @param {number} yearSeconds
+     */
+    correctedYearSeconds: (year: number, yearSeconds: number) => number;
+};

package/types/earth/year-lengths.d.cts

@@ -0,0 +1,67 @@
+/**
+ * @param {{
+ *   sampleAt: (year: number) => {e: number, periOfDateDeg: number, equinoxLonJ2000Deg: number},
+ *   massLossSiderealSecondsAtYearFn: (year: number) => number,
+ *   apsidalSecularDegPerYrFn?: (year: number) => number,
+ * }} opts
+ *   sampleAt: the one-source movement sampler, calendar-year keyed
+ *   (createDeepOrbitalHistory build().at wrapped by the caller — series
+ *   tier where the artifact is available, mode tail beyond).
+ *   massLossSiderealSecondsAtYearFn: the caller's secular mass-loss
+ *   sidereal-year law, SI seconds, IAU-anchored at J2000.
+ *   apsidalSecularDegPerYrFn: the chain's SECULAR apsidal tangent of date
+ *   (keplerian-chain computeApsidalSecularDegPerYr for Earth — deg/yr,
+ *   J2000-ecliptic frame). When given, the anomalistic year is the
+ *   mean-element construction on this smooth rate; when absent, it falls
+ *   back to the cardinal structure's measured year-over-year interval
+ *   (which carries the banked series' century-scale ϖ̇ wobble).
+ */
+export function createYearLengths({ sampleAt, massLossSiderealSecondsAtYearFn, apsidalSecularDegPerYrFn }: {
+    sampleAt: (year: number) => {
+        e: number;
+        periOfDateDeg: number;
+        equinoxLonJ2000Deg: number;
+    };
+    massLossSiderealSecondsAtYearFn: (year: number) => number;
+    apsidalSecularDegPerYrFn?: (year: number) => number;
+}): Readonly<{
+    /** Mean tropical year of date, SI seconds. @param {number} year */
+    tropicalYearSecondsAtYear: (year: number) => number;
+    /** Sidereal year of date, SI seconds. @param {number} year */
+    siderealYearSecondsAtYear: (year: number) => number;
+    /** Anomalistic year of date, SI seconds. @param {number} year */
+    anomalisticYearSecondsAtYear: (year: number) => number;
+    /** Axial precession period of date (equinox regression beat), years. @param {number} y */
+    axialPrecessionYearsAtYear: (y: number) => number;
+    /** Perihelion (apsidal-vs-equinox) precession period of date, years. @param {number} y */
+    perihelionPrecessionYearsAtYear: (y: number) => number;
+    /** Apsidal precession period of date vs the fixed stars, years (hypersensitive: ±1 s ↔ ≈400 yr; the identifier keeps the historical "inclination" name). @param {number} y */
+    inclinationPrecessionYearsAtYear: (y: number) => number;
+    /** The per-cardinal layer (D6 rules: year lengths λ̇-corrected; offsets/spreads raw — μs-class/second-order there). */
+    cardinal: Readonly<{
+        /** @param {number} y @param {'VE'|'SS'|'AE'|'WS'} type */
+        yearLengthSeconds: (y: number, type: "VE" | "SS" | "AE" | "WS") => number;
+        /** @param {number} y @param {'VE'|'SS'|'AE'|'WS'} type */
+        eocOffsetSeconds: (y: number, type: "VE" | "SS" | "AE" | "WS") => number;
+        /** @param {number} y */
+        spreadSeconds: (y: number) => {
+            VE: number;
+            SS: number;
+            AE: number;
+            WS: number;
+            meanSeconds: number;
+        };
+    }>;
+    /** The planetary λ̇ ratio (diagnostic; ≡1 at J2000). */
+    planetaryRelAtYear: (year: number) => number;
+}>;
+/**
+ * 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.
+ */
+export const ONE_FAMILY_WINDOW_YEARS: 2000000;

package/types/eclipse/besselian.d.cts

@@ -0,0 +1,101 @@
+export type BesselianDeps = {
+    /**
+     *   full-series Moon: ecliptic-of-date longitude/latitude (deg) + distance (km), TT axis (days since J2000)
+     */
+    moonFullAtDaysTT: (dDaysTT: number) => {
+        lonDeg: number;
+        latDeg: number;
+        distKm: number;
+    };
+    /**
+     * - geometric mean sun longitude (deg), JD(UT) axis with the finder's internal ΔT
+     */
+    sunLonDegAt: (jdUT: number) => number;
+    /**
+     * - planetary completion (deg) at T centuries TT, SUBTRACTED from the finder sun (see eclipse/sun-planetary-completion.cjs; the finders deliberately stay without it — their fitted anchors and certified canon statistics were produced on the bare form, and elongation-class timing absorbs the omission into the fitted phases)
+     */
+    sunCompletionDeg: (T: number) => number;
+    /**
+     * - derived series-extension tail (deg) at T centuries TT, ADDED to the full-series Moon longitude/latitude (see moon/series-extension.cjs; same finder-scoping rationale as sunCompletionDeg — the finders stay on the bare series)
+     */
+    moonExtensionAt: (T: number) => {
+        dLonDeg: number;
+        dLatDeg: number;
+    };
+    /**
+     * - framework ΔT (J2000-zeroed convention)
+     */
+    deltaTSecondsAt: (jd: number) => number;
+    /**
+     * - framework obliquity (deg) at calendar year
+     */
+    obliquityDegAt: (year: number) => number;
+    /**
+     * - framework Earth-orbit eccentricity at calendar year
+     */
+    eccentricityAt: (year: number) => number;
+    /**
+     * - framework perihelion longitude (deg) at calendar year
+     */
+    perihelionLongitudeDegAt: (year: number) => number;
+    /**
+     * - the model's own JD → calendar-year conversion
+     */
+    yearFromJD: (jd: number) => number;
+    constants: {
+        j2000JD: number;
+        julianCenturyDays: number;
+        earthDiameterKm: number;
+        moonDiameterKm: number;
+        sunDiameterKm: number;
+        sunDistanceKm: number;
+        earthFlatteningInverse: number;
+        ttBridgeSeconds: number;
+        gmstMeanSiderealT0Deg: number;
+        gmstMeanSiderealRateDegPerDay: number;
+        gmstMeanSiderealT2Deg: number;
+    };
+};
+/**
+ * @typedef {Object} BesselianDeps
+ * @property {(dDaysTT: number) => {lonDeg: number, latDeg: number, distKm: number}} moonFullAtDaysTT
+ *   full-series Moon: ecliptic-of-date longitude/latitude (deg) + distance (km), TT axis (days since J2000)
+ * @property {(jdUT: number) => number} sunLonDegAt - geometric mean sun longitude (deg), JD(UT) axis with the finder's internal ΔT
+ * @property {(T: number) => number} sunCompletionDeg - planetary completion (deg) at T centuries TT, SUBTRACTED from the finder sun (see eclipse/sun-planetary-completion.cjs; the finders deliberately stay without it — their fitted anchors and certified canon statistics were produced on the bare form, and elongation-class timing absorbs the omission into the fitted phases)
+ * @property {(T: number) => {dLonDeg: number, dLatDeg: number}} moonExtensionAt - derived series-extension tail (deg) at T centuries TT, ADDED to the full-series Moon longitude/latitude (see moon/series-extension.cjs; same finder-scoping rationale as sunCompletionDeg — the finders stay on the bare series)
+ * @property {(jd: number) => number} deltaTSecondsAt - framework ΔT (J2000-zeroed convention)
+ * @property {(year: number) => number} obliquityDegAt - framework obliquity (deg) at calendar year
+ * @property {(year: number) => number} eccentricityAt - framework Earth-orbit eccentricity at calendar year
+ * @property {(year: number) => number} perihelionLongitudeDegAt - framework perihelion longitude (deg) at calendar year
+ * @property {(jd: number) => number} yearFromJD - the model's own JD → calendar-year conversion
+ * @property {{ j2000JD: number, julianCenturyDays: number, earthDiameterKm: number,
+ *   moonDiameterKm: number, sunDiameterKm: number, sunDistanceKm: number,
+ *   earthFlatteningInverse: number, ttBridgeSeconds: number,
+ *   gmstMeanSiderealT0Deg: number, gmstMeanSiderealRateDegPerDay: number,
+ *   gmstMeanSiderealT2Deg: number }} constants
+ */
+/** @param {BesselianDeps} deps */
+export function createBesselian(deps: BesselianDeps): {
+    umbraGroundAt: (jdUT: number) => {
+        latDeg: number;
+        lonDeg: number;
+    } | null;
+    shadowStateAt: (jdUT: number, latDeg: number, lonDeg: number) => {
+        offsetKm: number;
+        penumbraKm: number;
+        umbraKm: number;
+        magnitude: number;
+    };
+    localCircumstances: (jdGreatest: number, latDeg: number, lonDeg: number) => {
+        kind: "none" | "partial" | "annular" | "total";
+        magnitude: number;
+        maxJd: number;
+        contacts: {
+            c1: number | null;
+            c2: number | null;
+            c3: number | null;
+            c4: number | null;
+        };
+        centralDurationSeconds: number | null;
+    };
+};