@essrt/physics 4.8.0 → 5.0.0

package/types/eclipse/finders.d.cts

@@ -0,0 +1,116 @@
+export type FrameworkSunDeps = {
+    /**
+     * - L0 anchor (input anchor, 280.46646)
+     */
+    sunMeanLongitudeJ2000Deg: number;
+    /**
+     * - the framework tropical rate (from the year chain)
+     */
+    tropicalRateDegPerCy: number;
+    /**
+     * - the framework e(t) law
+     */
+    eccentricityAt: (year: number) => number;
+    /**
+     * - the framework ϖ(t) law (heliocentric)
+     */
+    perihelionLongitudeDegAt: (year: number) => number;
+    /**
+     * - optional epoch-dependent
+     * mean longitude L(t) (e.g. L0 + ∫rate·dt from the f(Y) tropical-year chain);
+     * absent = the linear form L0 + rate·T
+     */
+    meanLongitudeDegAt?: ((year: number) => number) | undefined;
+};
+export type EclipseFinderDeps = {
+    /**
+     * - truncated-series ecliptic longitude
+     */
+    moonLonDegAt: (jd: number) => number;
+    /**
+     * - truncated-series ecliptic latitude
+     */
+    moonBetaDegAt: (jd: number) => number;
+    /**
+     * - truncated-series distance
+     */
+    moonDistanceKmAt: (jd: number) => number;
+    /**
+     * - the engine's ΔT convention
+     */
+    deltaTSecondsAt: (jd: number) => number;
+    /**
+     * - live (epoch-mutable)
+     */
+    getSynodicMonthDays: () => number;
+    /**
+     * - live (epoch-mutable)
+     */
+    getSunDistanceKm: () => number;
+    /**
+     * - E4 (the native-Sun landing,
+     * plan §12i item 11): when present, sunLonDegAt uses the FRAMEWORK form —
+     * linear tropical rate + Kepler EoC (to e³) on the framework e(t)/ϖ(t)
+     * laws, TT clock unchanged — instead of the Meeus Ch. 25 polynomials.
+     * Absent = the historical Meeus form (every certified number's current
+     * basis). The swap is a conscious matched-pair event: the D2 completion's
+     * fitted 2lE residue and the certified statistics re-measure with it.
+     */
+    frameworkSun?: FrameworkSunDeps | undefined;
+    constants: {
+        rEarthMetres: number;
+        moonDiameterKm: number;
+        sunDiameterKm: number;
+        j2000JD: number;
+        julianCenturyDays: number;
+    };
+};
+/**
+ * @typedef {Object} FrameworkSunDeps
+ * @property {number} sunMeanLongitudeJ2000Deg - L0 anchor (input anchor, 280.46646)
+ * @property {number} tropicalRateDegPerCy - the framework tropical rate (from the year chain)
+ * @property {(year: number) => number} eccentricityAt - the framework e(t) law
+ * @property {(year: number) => number} perihelionLongitudeDegAt - the framework ϖ(t) law (heliocentric)
+ * @property {(year: number) => number} [meanLongitudeDegAt] - optional epoch-dependent
+ *   mean longitude L(t) (e.g. L0 + ∫rate·dt from the f(Y) tropical-year chain);
+ *   absent = the linear form L0 + rate·T
+ */
+/**
+ * @typedef {Object} EclipseFinderDeps
+ * @property {(jd: number) => number} moonLonDegAt - truncated-series ecliptic longitude
+ * @property {(jd: number) => number} moonBetaDegAt - truncated-series ecliptic latitude
+ * @property {(jd: number) => number} moonDistanceKmAt - truncated-series distance
+ * @property {(jd: number) => number} deltaTSecondsAt - the engine's ΔT convention
+ * @property {() => number} getSynodicMonthDays - live (epoch-mutable)
+ * @property {() => number} getSunDistanceKm - live (epoch-mutable)
+ * @property {FrameworkSunDeps} [frameworkSun] - E4 (the native-Sun landing,
+ *   plan §12i item 11): when present, sunLonDegAt uses the FRAMEWORK form —
+ *   linear tropical rate + Kepler EoC (to e³) on the framework e(t)/ϖ(t)
+ *   laws, TT clock unchanged — instead of the Meeus Ch. 25 polynomials.
+ *   Absent = the historical Meeus form (every certified number's current
+ *   basis). The swap is a conscious matched-pair event: the D2 completion's
+ *   fitted 2lE residue and the certified statistics re-measure with it.
+ * @property {{ rEarthMetres: number, moonDiameterKm: number,
+ *   sunDiameterKm: number, j2000JD: number, julianCenturyDays: number }} constants
+ */
+/** @param {EclipseFinderDeps} deps */
+export function createEclipseFinders(deps: EclipseFinderDeps): {
+    sunLonDegAt: (jd: number) => number;
+    findLunarEclipsesInRange: (jdStart: number, jdEnd: number) => Array<{
+        jd: number;
+        beta: number;
+        moonDistance_km: number;
+        type: string;
+        magnitudeUmbral: number;
+        magnitudePenumbral: number;
+    }>;
+    findSolarEclipsesInRange: (jdStart: number, jdEnd: number) => Array<{
+        jd: number;
+        beta: number;
+        moonDistance_km: number;
+        type: string;
+        moonAppR_topo: number;
+        sunAppR: number;
+        moonSunRatio: number;
+    }>;
+};

package/types/eclipse/sun-planetary-completion.d.cts

@@ -0,0 +1,39 @@
+/**
+ * @param {{ embWobbleArcsec: number,
+ *           carrierRatesDegPerCy: { planets: number[], moonElongation: number } }} opts
+ *   - embWobbleArcsec: the DERIVED Earth-around-EMB wobble amplitude
+ *     a_M·μ/AU in arcsec (μ = 1/(1+M_E/M_M));
+ *   - carrierRatesDegPerCy.planets: the six FRAMEWORK mean-longitude
+ *     rates (deg/Julian-century TT), body order Me,V,E,Ma,J,S — one
+ *     revolution per the model's own tropical period records;
+ *   - carrierRatesDegPerCy.moonElongation: the framework Moon
+ *     mean-elongation rate (deg/cy TT) for the EMB-wobble carrier.
+ *   All computed from live constants by the model wiring so the
+ *   carrier↔table matched pair tracks the constants.
+ * @returns {{ sunPlanetaryCompletionDeg: (T: number) => number }}
+ */
+export function createSunPlanetaryCompletion({ embWobbleArcsec, carrierRatesDegPerCy }: {
+    embWobbleArcsec: number;
+    carrierRatesDegPerCy: {
+        planets: number[];
+        moonElongation: number;
+    };
+}): {
+    sunPlanetaryCompletionDeg: (T: number) => number;
+};
+/** sha256/16 of JSON.stringify(FITTED_COEFFICIENTS.SUN_LONGITUDE_HARMONICS)
+ *  at derivation time — the matched-pair fingerprint asserted by test:model.
+ *  Unchanged from v1/v2: SUN_HARMONICS did not move in the D2 or N3
+ *  landings. */
+export const PAIRED_SUN_HARMONICS_SHA256: "cbc189cea1c20292";
+/** sha256/16 of JSON.stringify([...planets, moonElongation]) — the seven
+ *  full-precision carrier rates (deg/cy TT) the TERMS table was extracted
+ *  under at N3. The model wiring recomputes the rates live from the planet
+ *  records, so a planet-period / year / month input change moves the
+ *  carriers automatically while the table stays frozen — a silent few-
+ *  arcsec stale below the api gate's ≤8″ backstop. test:model recomputes
+ *  this fingerprint from live constants (identical arithmetic to model.js)
+ *  and fails on mismatch: re-run the N3 extraction chain
+ *  (tools/explore/n2-sun-framework-carriers.mjs →
+ *  n3-carrier-swap-preview.mjs), re-embed TERMS, and update this value. */
+export const PAIRED_CARRIER_RATES_SHA256: "893e055ee12343bd";

package/types/index.d.ts

@@ -0,0 +1,78 @@
+export { createEpochPrimitives } from "./layer0/index.js";
+export { deriveEpochParams } from "./layer0/derive-params.js";
+export { createDerivedViews } from "./layer1/index.js";
+export { createPhaseMachinery } from "./phase/index.cjs";
+export { createCardinalModel } from "./cardinal/index.cjs";
+export { createCardinalStructure } from "./cardinal/one-source-structure.cjs";
+export { createMoonEccChannel } from "./moon/ecc-channel.cjs";
+export { createMoonMonthChain } from "./moon/month-chain.cjs";
+export { createChainCycleIntegrator } from "./chain-cycles/index.cjs";
+export { createMoonArguments } from "./moon/arguments.cjs";
+export { createMoonSeries } from "./moon/series.cjs";
+export { createMoonApparent } from "./moon/apparent.cjs";
+export { derivePlanetGeometry } from "./planets/geometry.cjs";
+export * as planetFibonacciLaws from "./planets/fibonacci-laws.cjs";
+export * as planetOrientation from "./planets/orientation.cjs";
+export { integrateAscendingNode } from "./planets/asc-node-integrator.cjs";
+export * as planetOrbitChain from "./planets/orbit-chain.cjs";
+export { createSecularSeriesOverride } from "./planets/secular-series.cjs";
+export { createDeepEccChannel } from "./moon/deep-ecc-channel.cjs";
+export { createDeepOrbitalHistory } from "./earth/deep-orbital-history.cjs";
+export { createSiderealYearChannel } from "./earth/sidereal-year-channel.cjs";
+export { createPlanetModel } from "./planets/model.cjs";
+export { createDeltaTCycles } from "./deltat/cycles.cjs";
+export { createDeepTimeLod } from "./deltat/deep-time.cjs";
+export { deltaTEspenakMeeusCanonSeconds } from "./deltat/historical.cjs";
+export { createEclipseFinders } from "./eclipse/finders.cjs";
+export { createSunLongitudeCorrection } from "./sun/longitude-correction.cjs";
+export function createModel(constants?: Constants, opts?: {
+    laws?: {
+        eccentricityAt?: (year: number) => number;
+        eccentricityRateAt?: (year: number) => number;
+        perihelionLongitudeDegAt?: (year: number) => number;
+    };
+    secularSeriesArtifact?: any;
+}): Model;
+export type Constants = Record<string, unknown> & {
+    hash?: string;
+};
+export type ModelSurfaces = ReturnType<typeof assembleModel>;
+export type ModelIdentity = {
+    modelVersion: string;
+    /**
+     * THIS context's hash — distinct for a counterfactual
+     */
+    constantsHash: string;
+    coefficientsHash: string;
+    counterfactual: boolean;
+    preprintDoi: string;
+};
+export type Model = {
+    constants: Constants;
+    hash: string;
+    computeLatticePeriodsYears: () => {
+        axialPrecessionPeriodYears: number;
+        inclinationPrecessionPeriodYears: number;
+        perihelionPrecessionPeriodYears: number;
+    };
+    eccentricity: (year: number) => number;
+    identity: ModelIdentity;
+} & ModelSurfaces;
+import { DEFAULT_CONSTANTS as GENERATED } from './constants/index.js';
+import { CONSTANTS_HASH } from './constants/index.js';
+import { MODEL_VERSION } from './constants/index.js';
+import { PREPRINT_DOI } from './constants/index.js';
+import { REFERENCE_DATA } from './constants/index.js';
+import { assembleModel } from './model.js';
+export { GENERATED as DEFAULT_CONSTANTS, CONSTANTS_HASH, MODEL_VERSION, PREPRINT_DOI, REFERENCE_DATA };
+export { FITTED_COEFFICIENTS, COEFFICIENTS_HASH } from "./constants/index.js";
+export { eccentricityFromCycles, computeEccentricityIntegrated } from "./planets/ecc-channel.cjs";
+export { buildPlanetChainsFromArtifactData, computePlanetElementsAtYear, computeHeliocentricEclipticFromElements, computePoissonArgRad, computeOsculatingElements, solveKeplerRad, computeApsidalSecularDegPerYr, ANCHOR_EPOCH_YEAR, ANCHOR_EPOCH_JD } from "./planets/keplerian-chain.cjs";
+export { computeEquatorNodeOriginSFrameDeg, convertNodeSFrameToEquatorOriginDeg } from "./planets/inv-plane-frame.cjs";
+export { CHAIN_ARTIFACT, CHAIN_ARTIFACT_HASH } from "./planets/chain-artifact.js";
+export { DEEP_MODES_ARTIFACT, DEEP_MODES_ARTIFACT_HASH } from "./moon/deep-modes-artifact.cjs";
+export { createYearLengths, ONE_FAMILY_WINDOW_YEARS } from "./earth/year-lengths.cjs";
+export { computeSolarTorqueShare, createComposedPrecession } from "./earth/precession-composed.cjs";
+export { createPredictivePrecession, calcPlanetPerihelionLongDeg } from "./planets/predict.cjs";
+export { createMoonRecessionHistory, createSolarChannelBudget } from "./deltat/recession-history.cjs";
+export { evalClimateL1OrbitalPermil, laggedL1Terms, createAlphaGiaChannel } from "./climate/l1-orbital.cjs";

package/types/layer0/derive-params.d.ts

@@ -0,0 +1,46 @@
+export function deriveEpochParams(raw: RawEpochConstants): import("./index.js").EpochParams;
+export type RawEpochConstants = {
+    /**
+     * IAU 2015 nominal (W)
+     */
+    solarLuminosityW: number;
+    /**
+     * Ulysses/ACE/Wind
+     */
+    solarWindKgPerS: number;
+    /**
+     * km/s (fallback 299792458 m/s if falsy)
+     */
+    speedOfLightKmPerS: number;
+    alpha1PerMa: number;
+    alpha3PerMa3: number;
+    alpha4PerMa4: number;
+    /**
+     * H
+     */
+    holisticYearJ2000: number;
+    meanSiderealYearSeconds: number;
+    meanSiderealYearDaysKinematic: number;
+    /**
+     * M_SUN
+     */
+    sunMassKg: number;
+    gmEarthAloneKm3S2: number;
+    gmMoonAloneKm3S2: number;
+    gravitationalConstantKm3KgS2: number;
+    earthMoiFactorJ2000: number;
+    earthDiameterKm: number;
+    moonDistanceKm: number;
+    moonOrbitalEccentricity: number;
+    gmEarthMoonSystemKm3S2: number;
+    /**
+     * GM☉ (km³/s²) — the solar precession torque
+     */
+    gmSunKm3S2: number;
+    /**
+     * 1 AU (km)
+     */
+    astronomicalUnitKm: number;
+    earthOrbitalEccentricityJ2000: number;
+    moonEclipticInclinationJ2000Deg: number;
+};

package/types/layer0/index.d.ts

@@ -0,0 +1,64 @@
+export function createEpochPrimitives({ params: p, alphaAtAgeMa }: {
+    params: EpochParams;
+    alphaAtAgeMa: (tMa: number) => number;
+}): EpochPrimitives;
+export type EpochParams = {
+    /**
+     * year at t_Ma = 0 (2000, NOT startmodelYear)
+     */
+    epochYear: number;
+    /**
+     * Moon recession, LLR-anchored
+     */
+    alpha1PerMa: number;
+    alpha3PerMa3: number;
+    alpha4PerMa4: number;
+    /**
+     * a_Moon at J2000, metres
+     */
+    moonDistanceNowM: number;
+    /**
+     * tidal-lock asymptote, metres
+     */
+    moonLockDistanceM: number;
+    /**
+     * L_tot of the Earth-Moon system
+     */
+    totalAngularMomentumKgM2S: number;
+    moonMassKg: number;
+    gmEarthMoonM3S2: number;
+    /**
+     * sqrt(1 - e^2)
+     */
+    moonEccentricityFactor: number;
+    earthMassKg: number;
+    earthRadiusM: number;
+    holisticYearJ2000: number;
+    lodNowH13Seconds: number;
+    siderealYearJ2000Seconds: number;
+    solarMassLossFracPerYear: number;
+    /**
+     * f_S, the solar fraction of the J2000 precession torque
+     */
+    precessionSolarShareJ2000: number;
+};
+export type EpochPrimitives = {
+    tMa: (year: number) => number;
+    moonDistanceMetres: (year: number) => number;
+    lodSeconds: (year: number) => number | null;
+    /**
+     * the UNIT: 13 × the composed lunisolar precession period
+     */
+    holisticH: (year: number) => number | null;
+    siderealYearSeconds: (year: number) => number;
+    tropicalYearSeconds: (year: number) => number;
+    anomalisticYearSeconds: (year: number) => number | null;
+    /**
+     * the frozen era clock's phase convention H₀·LOD/LOD₀ (device tier)
+     */
+    eraClockH: (year: number) => number | null;
+    /**
+     * T_sid·(1 − 13/H_era) — the frozen comb family's base
+     */
+    eraClockTropicalYearSeconds: (year: number) => number;
+};

package/types/layer1/index.d.ts

@@ -0,0 +1,10 @@
+export function createDerivedViews({ primitives: L0 }: {
+    primitives: EpochPrimitives;
+}): DerivedViews;
+export type EpochPrimitives = import("../layer0/index.js").EpochPrimitives;
+export type DerivedViews = {
+    tropicalYearDays: (year: number) => number | null;
+    siderealYearDays: (year: number) => number | null;
+    anomalisticYearDays: (year: number) => number | null;
+    siderealYearDaysViaLattice: (year: number) => number | null;
+};

package/types/model.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Assemble the model surfaces from a resolved constants context + fitted
+ * coefficients. Internal: `createModel` in index.js composes this with the
+ * §2d context validation and counterfactual hashing — call that, not this.
+ *
+ * @param {Readonly<Record<string, any>>} C  the frozen constants context
+ * @param {Readonly<Record<string, any>>} F  the fitted coefficients
+ * @param {{ eccentricityAt?: (year: number) => number, eccentricityRateAt?: (year: number) => number, perihelionLongitudeDegAt?: (year: number) => number }} [laws]
+ *   RESEARCH OVERRIDES for Earth's orbit laws (doc 109 §7): an alternative e(t),
+ *   de/dt(t) and ϖ_of-date(t) flow through every consumer (the eclipse Sun, the
+ *   Moon's E-factor, the cardinal points) exactly as the shipped laws do. Default
+ *   {} = the shipped laws, bit-identical to before this parameter existed. Not a
+ *   counterfactual in the §2d sense (no hash change) — callers must say when
+ *   they used it; the generators refuse to --write under an override.
+ * @returns the assembled surfaces (epoch, earth, lengths, cardinal, moon) — type inferred so ReturnType stays precise
+ */
+export function assembleModel(C: Readonly<Record<string, any>>, F: Readonly<Record<string, any>>, laws?: {
+    eccentricityAt?: (year: number) => number;
+    eccentricityRateAt?: (year: number) => number;
+    perihelionLongitudeDegAt?: (year: number) => number;
+}, secularSeriesArtifact?: any): Readonly<{
+    time: Readonly<{
+        yearFromJD: (jd: number) => number;
+        jdFromYear: (year: number) => number;
+        siTropicalYearDays: number;
+    }>;
+    epoch: Readonly<{
+        yearToTMa: (year: number) => number;
+        hAtYear: (year: number) => number | null;
+        lodSecondsAtYear: (year: number) => number | null;
+        alphaAtYear: (year: number) => number;
+        moonDistanceKmAtYear: (year: number) => number;
+        siderealYearSecondsAtYear: (year: number) => number;
+        deltaTSecondsAtYear: (year: number) => number;
+        cyclesBetween: (yearA: number, yearB: number, divisorN: number) => number;
+        axialPrecessionYearsAtYear: (year: number) => number;
+        tropicalYearSecondsAtYear: (year: number) => number;
+    }>;
+    lunisolar: Readonly<{
+        /** The mean lunisolar precession period T_p(t), years — the composed torque rate's period. @param {number} year @returns {number} */
+        meanPeriodYearsAtYear: (year: number) => number;
+        /** The composed rate ψ̇(t) = [ω/ω₀]·p₀·[f_S + (1 − f_S)(a₀/a_M)³], ″/yr. @param {number} year @returns {number} */
+        meanRateArcsecPerYrAtYear: (year: number) => number;
+        /** The of-date period — the one-family beat inside ±2 Myr, the mean beyond. @param {number} year @returns {number} */
+        ofDatePeriodYearsAtYear: (year: number) => number;
+        /** f_S, the solar fraction of the J2000 precession torque. */
+        solarShareJ2000: number;
+        /** (a₀/a_M(t))³ — the lunar torque's growth on the recession history. @param {number} year @returns {number} */
+        lunarTorqueFactorAtYear: (year: number) => number;
+        /** f_S + (1 − f_S)(a₀/a_M)³ — the torque term the unit divides H_era by. @param {number} year @returns {number} */
+        torqueTermAtYear: (year: number) => number;
+        /** The hybrid's precession constant α = p₀ / cos ε₀, ″/yr (ε₀ the J2000 obliquity input). */
+        torqueConstantJ2000ArcsecPerYr: number;
+        /** 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: number) => number | 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: number) => number | null;
+        /** 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: number) => number | null;
+        /** 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: number) => number | null;
+        /** The published of-date window, years from 2000. */
+        publishedWindowYears: 2000000;
+    }>;
+    earth: Readonly<{
+        perihelionLongitudeDeg: (year: number) => number;
+        obliquityDeg: (year: number) => number;
+        obliquityCombDeg: (year: number) => number;
+        eccentricity: (year: number) => number;
+        inclinationDeg: (year: number) => number;
+        ascendingNodeDeg: (year: number) => number;
+    }>;
+    lengths: Readonly<{
+        tropicalYearDays: (year: number) => number;
+        tropicalYearDirectDays: (year: number) => number;
+        siderealYearDays: (year: number) => number;
+        anomalisticYearDays: (year: number) => number;
+        dayLengthSeconds: (year: number) => number;
+        siderealDaySeconds: (year: number) => number;
+        stellarDaySeconds: (year: number) => number;
+        measuredSolarDaySeconds: (year: number) => number;
+        raDayOffsetMs: (year: number) => number;
+    }>;
+    cardinal: Readonly<{
+        jd: (year: number, type: string) => number;
+        raDeg: (year: number, type: string) => number;
+        yearLengthDays: (year: number, type: string) => number;
+    }>;
+    cardinalStructure: Readonly<{
+        yearLengthSeconds: (year: number, type: "VE" | "SS" | "AE" | "WS") => number;
+        eocOffsetSeconds: (year: number, type: "VE" | "SS" | "AE" | "WS") => number;
+        spreadSeconds: (year: number) => {
+            VE: number;
+            SS: number;
+            AE: number;
+            WS: number;
+            meanSeconds: number;
+        };
+        anomalisticYearSeconds: (year: number) => number;
+    }>;
+    yearLengths: Readonly<{
+        tropicalYearSecondsAtYear: (year: number) => number;
+        siderealYearSecondsAtYear: (year: number) => number;
+        anomalisticYearSecondsAtYear: (year: number) => number;
+        axialPrecessionYearsAtYear: (y: number) => number;
+        perihelionPrecessionYearsAtYear: (y: number) => number;
+        inclinationPrecessionYearsAtYear: (y: number) => number;
+        cardinal: Readonly<{
+            yearLengthSeconds: (y: number, type: "VE" | "SS" | "AE" | "WS") => number;
+            eocOffsetSeconds: (y: number, type: "VE" | "SS" | "AE" | "WS") => number;
+            spreadSeconds: (y: number) => {
+                VE: number;
+                SS: number;
+                AE: number;
+                WS: number;
+                meanSeconds: number;
+            };
+        }>;
+        planetaryRelAtYear: (year: number) => number;
+    }>;
+    moon: Readonly<{
+        distanceKmAtYear: (year: number) => number;
+        siderealMonthDaysAtYear: (year: number) => number;
+        synodicMonthDays: number;
+        lonDegAtJD: (jd: number) => number;
+        betaDegAtJD: (jd: number) => number;
+        distanceKmAtJD: (jd: number) => number;
+    }>;
+    eclipse: Readonly<{
+        sunLonDegAtJD: (jd: number) => number;
+        sunLonCompletedDegAtJD: (jd: number) => number;
+        findLunarInRange: (jdStart: number, jdEnd: number) => {
+            jd: number;
+            beta: number;
+            moonDistance_km: number;
+            type: string;
+            magnitudeUmbral: number;
+            magnitudePenumbral: number;
+        }[];
+        findSolarInRange: (jdStart: number, jdEnd: number) => {
+            jd: number;
+            beta: number;
+            moonDistance_km: number;
+            type: string;
+            moonAppR_topo: number;
+            sunAppR: number;
+            moonSunRatio: number;
+        }[];
+        deltaTSecondsAtJD: (jd: number) => number;
+        frameworkSunDeps: Readonly<{
+            sunMeanLongitudeJ2000Deg: any;
+            tropicalRateDegPerCy: number;
+            eccentricityAt: (year: number) => number;
+            perihelionLongitudeDegAt: (year: number) => number;
+            meanLongitudeDegAt: (year: number) => number;
+        }>;
+        umbraGroundAtJD: (jd: number) => {
+            latDeg: number;
+            lonDeg: number;
+        } | null;
+        solarLocalCircumstances: (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;
+        };
+    }>;
+    climate: Readonly<{
+        l1OrbitalPermil: (year: number) => number;
+    }>;
+    planets: Readonly<{
+        keys: readonly string[];
+        record: (k: string) => Record<string, any> | undefined;
+        perihelionLongitudeDeg: (k: string, year: number) => number;
+        ascendingNodeInvPlaneDeg: (k: string, year: number) => number;
+        invPlaneInclinationDeg: (k: string, year: number) => number;
+    }>;
+}>;

package/types/moon/apparent.d.cts

@@ -0,0 +1,78 @@
+export type MoonCorrectionTable = {
+    raSinD: number;
+    raCosD: number;
+    raSinMp: number;
+    raCosMp: number;
+    raSinMs: number;
+    raCosMs: number;
+    decSinD: number;
+    decCosD: number;
+    decSinMp: number;
+    decCosMp: number;
+    decSinMs: number;
+    decCosMs: number;
+};
+/**
+ * @typedef {{raSinD: number, raCosD: number, raSinMp: number, raCosMp: number,
+ *            raSinMs: number, raCosMs: number, decSinD: number, decCosD: number,
+ *            decSinMp: number, decCosMp: number, decSinMs: number, decCosMs: number}} MoonCorrectionTable
+ */
+/**
+ * @param {{
+ *   constants: {
+ *     j2000JD: number,
+ *     julianCenturyDays: number,
+ *     sunMeanLongitudeJ2000Deg: number,
+ *     perihelionLongitudeJ2000Deg: number,
+ *     eccentricityJ2000: number,
+ *     eccentricityDotJ2000: number,
+ *     d5RateLDegPerDay: number,
+ *     d5RatePeriDegPerDay: number,
+ *     speedOfLight: number,
+ *   },
+ *   fns: {
+ *     computeObliquityEarth: (year: number) => number,
+ *     getAuDistanceKm: () => number,
+ *     isFrameworkNative: () => boolean,
+ *     getCorrectionResidual: () => (MoonCorrectionTable | null),
+ *     getCorrectionLegacy: () => (MoonCorrectionTable | null),
+ *   },
+ * }} deps — the D5 rates are the engines' J2000-frozen values (the year
+ *   globals are deep-time-mutable, same pattern as FW_A2_RATE); the AU
+ *   distance is a GETTER (browser-mutable under deep time).
+ */
+export function createMoonApparent({ constants, fns }: {
+    constants: {
+        j2000JD: number;
+        julianCenturyDays: number;
+        sunMeanLongitudeJ2000Deg: number;
+        perihelionLongitudeJ2000Deg: number;
+        eccentricityJ2000: number;
+        eccentricityDotJ2000: number;
+        d5RateLDegPerDay: number;
+        d5RatePeriDegPerDay: number;
+        speedOfLight: number;
+    };
+    fns: {
+        computeObliquityEarth: (year: number) => number;
+        getAuDistanceKm: () => number;
+        isFrameworkNative: () => boolean;
+        getCorrectionResidual: () => (MoonCorrectionTable | null);
+        getCorrectionLegacy: () => (MoonCorrectionTable | null);
+    };
+}): {
+    sunGeoVecEqD5: (jd: number) => [number, number, number];
+    moonAberrationRaDec: (jd: number, ra: number, dec: number) => {
+        dRA: number;
+        dDec: number;
+    };
+    overrideRaDec: ({ lonDeg, betRad, meeusT, obliquityDeg }: {
+        lonDeg: number;
+        betRad: number;
+        meeusT: (number | undefined);
+        obliquityDeg: number;
+    }) => {
+        raRad: number;
+        decRad: number;
+    };
+};