@essrt/physics 4.8.0 → 5.0.0

package/types/planets/fibonacci-laws.d.cts

@@ -0,0 +1,90 @@
+/**
+ * ψ constant from Earth's calibration. @param {{
+ *   earthInvPlaneInclinationAmplitude: number,
+ *   massEarthAlone: number, massSun: number }} c @returns {number} */
+export function computePsiConstant(c: {
+    earthInvPlaneInclinationAmplitude: number;
+    massEarthAlone: number;
+    massSun: number;
+}): number;
+/**
+ * ψ law: invariable-plane inclination amplitude and mean.
+ * @param {{ fibonacciD: number, massFrac: number,
+ *   invPlaneInclinationJ2000: number, longitudePerihelion: number,
+ *   inclinationCycleAnchor: number, antiPhase: boolean }} b
+ * @param {number} psiConstant
+ * @returns {{ amplitude: number, mean: number }} */
+export function computeInclinationLaw(b: {
+    fibonacciD: number;
+    massFrac: number;
+    invPlaneInclinationJ2000: number;
+    longitudePerihelion: number;
+    inclinationCycleAnchor: number;
+    antiPhase: boolean;
+}, psiConstant: number): {
+    amplitude: number;
+    mean: number;
+};
+/**
+ * Wobble period: beat of axial precession and perihelion ICRF precession.
+ * @param {number} periEclYr @param {number} axialYr @param {number} H
+ * @returns {number} years */
+export function computeWobblePeriodYears(periEclYr: number, axialYr: number, H: number): number;
+/**
+ * Obliquity cycle with the Venus/Neptune fallback: the record's cycle if
+ * present, else |ICRF| (tidally damped — the two-component obliquity
+ * formula cancels exactly, constant tilt).
+ * @param {number | null | undefined} obliquityCycleYears
+ * @param {number} periEclYr @param {number} H @returns {number} */
+export function resolveObliquityCycleYears(obliquityCycleYears: number | null | undefined, periEclYr: number, H: number): number;
+/**
+ * Mean obliquity, SNAPSHOT form (the load-time law both engines ship):
+ * mean = tiltJ2000 + amp·cos(ωᵢ·t₂₀₀₀) − amp·cos(ωₒ·t₂₀₀₀).
+ * @param {{ axialTiltJ2000: number, invPlaneInclinationAmplitude: number,
+ *   perihelionEclipticYears: number }} b
+ * @param {number | null | undefined} obliqCycleYears — falsy ⇒ static tilt
+ * @param {{ H: number, t2000: number }} env — t2000 = 2000 − eccentricity
+ *   anchor (balancedYear − systemResetN·H)
+ * @returns {number} degrees */
+export function computeObliquityMeanSnapshot(b: {
+    axialTiltJ2000: number;
+    invPlaneInclinationAmplitude: number;
+    perihelionEclipticYears: number;
+}, obliqCycleYears: number | null | undefined, env: {
+    H: number;
+    t2000: number;
+}): number;
+/**
+ * K constant from Earth's calibration. @param {{
+ *   eccentricityAmplitude: number, massEarthAlone: number, massSun: number,
+ *   earthTiltMeanDeg: number }} c @returns {number} */
+export function computeKConstant(c: {
+    eccentricityAmplitude: number;
+    massEarthAlone: number;
+    massSun: number;
+    earthTiltMeanDeg: number;
+}): number;
+/**
+ * K law: eccentricity amplitude, base and J2000 phase.
+ * @param {{ fibonacciD: number, massFrac: number, solarYearInput: number,
+ *   orbitalEccentricityJ2000: number, antiPhase: boolean }} b
+ * @param {{ kConstant: number, obliquityMeanDeg: number,
+ *   wobblePeriodYears: number, t2000: number, meanSolarYearDays: number }} env
+ * @returns {{ amplitude: number, base: number, phaseJ2000: number }} */
+export function computeEccentricityLaw(b: {
+    fibonacciD: number;
+    massFrac: number;
+    solarYearInput: number;
+    orbitalEccentricityJ2000: number;
+    antiPhase: boolean;
+}, env: {
+    kConstant: number;
+    obliquityMeanDeg: number;
+    wobblePeriodYears: number;
+    t2000: number;
+    meanSolarYearDays: number;
+}): {
+    amplitude: number;
+    base: number;
+    phaseJ2000: number;
+};

package/types/planets/geometry.d.cts

@@ -0,0 +1,60 @@
+export type PlanetGeometryBody = {
+    key: string;
+    type?: string;
+    solarYearInput: number;
+    orbitalEccentricityBase?: number;
+    longitudePerihelion?: number;
+    ascendingNode?: number;
+    rotationPeriodDays?: number;
+    orbitDistanceOverride?: number;
+};
+/**
+ * @typedef {{
+ *   key: string,
+ *   type?: string,
+ *   solarYearInput: number,
+ *   orbitalEccentricityBase?: number,
+ *   longitudePerihelion?: number,
+ *   ascendingNode?: number,
+ *   rotationPeriodDays?: number,
+ *   orbitDistanceOverride?: number,
+ * }} PlanetGeometryBody
+ */
+/**
+ * @param {PlanetGeometryBody} body
+ * @param {{
+ *   holisticYears: number,
+ *   meanSolarYearDays: number,
+ *   currentAUDistanceKm: number,
+ *   earthEccentricityJ2000: number,
+ *   earthPerihelionLongitudeJ2000Deg: number,
+ * }} env — the engine's J2000 values (browser passes its live globals at
+ *   load time, preserving its original initial-derivation semantics; the
+ *   epoch machinery that later mutates the browser's `let` aliases is
+ *   untouched by this layer).
+ * @returns {{
+ *   solarYearCount: number, orbitDistance: number, periodYears: number,
+ *   realOrbitalEccentricity: (number | undefined),
+ *   elipticOrbit: (number | undefined), perihelionDistance: (number | undefined),
+ *   speedKmh: number, rotationPeriodHours: (number | undefined),
+ *   eccentricityPerihelion: (number | undefined), lowestPoint: (number | undefined),
+ * }}
+ */
+export function derivePlanetGeometry(body: PlanetGeometryBody, env: {
+    holisticYears: number;
+    meanSolarYearDays: number;
+    currentAUDistanceKm: number;
+    earthEccentricityJ2000: number;
+    earthPerihelionLongitudeJ2000Deg: number;
+}): {
+    solarYearCount: number;
+    orbitDistance: number;
+    periodYears: number;
+    realOrbitalEccentricity: (number | undefined);
+    elipticOrbit: (number | undefined);
+    perihelionDistance: (number | undefined);
+    speedKmh: number;
+    rotationPeriodHours: (number | undefined);
+    eccentricityPerihelion: (number | undefined);
+    lowestPoint: (number | undefined);
+};

package/types/planets/inv-plane-frame.d.cts

@@ -0,0 +1,36 @@
+export type InvariablePlane = {
+    inclEclipticDeg: number;
+    ascNodeEclipticDeg: number;
+};
+/** @typedef {{ inclEclipticDeg: number, ascNodeEclipticDeg: number }} InvariablePlane */
+/**
+ * The s-frame basis of the banked invariable plane in ecliptic-J2000
+ * coordinates — the SAME construction as the K5c evaluator rotation in
+ * keplerian-chain.cjs (x̂ = ecliptic-X projected into the plane); kept in
+ * lockstep with it (matched-pair rule).
+ * @param {InvariablePlane} invariablePlane  the artifact-banked plane
+ * @returns {{ xf: number[], yf: number[], zf: number[] }} unit basis vectors
+ */
+export function computeSFrameBasis(invariablePlane: InvariablePlane): {
+    xf: number[];
+    yf: number[];
+    zf: number[];
+};
+/**
+ * S-frame longitude of the invariable plane's ascending node on the ICRF
+ * equator — the Souami & Souchay (2012) longitude origin. Subtracting this
+ * from a K5c s-frame node longitude expresses it in the S&S convention.
+ * J2000-fixed (banked plane + J2000 mean obliquity).
+ * @param {InvariablePlane} invariablePlane  the artifact-banked plane
+ * @param {number} obliquityJ2000Deg  J2000 mean obliquity (ecliptic↔ICRF), degrees
+ * @returns {number} s-frame longitude of the origin, degrees in [0, 360)
+ */
+export function computeEquatorNodeOriginSFrameDeg(invariablePlane: InvariablePlane, obliquityJ2000Deg: number): number;
+/**
+ * Convert a K5c s-frame node longitude to the equator-node origin (the
+ * Souami & Souchay 2012 convention).
+ * @param {number} sFrameDeg  node longitude in the engine s-frame, degrees
+ * @param {number} originSFrameDeg  from computeEquatorNodeOriginSFrameDeg, degrees
+ * @returns {number} node longitude in the S&S convention, degrees in [0, 360)
+ */
+export function convertNodeSFrameToEquatorOriginDeg(sFrameDeg: number, originSFrameDeg: number): number;

package/types/planets/keplerian-chain.d.cts

@@ -0,0 +1,173 @@
+export type KcElements = {
+    aAU: number;
+    e: number;
+    inclEclipticDeg: number;
+    ascNodeEclipticDeg: number;
+    lonPeriEclipticDeg: number;
+    meanLonEclipticDeg: number;
+    meanMotionDegPerYr?: number;
+    argPeriDeg?: number;
+    meanAnomalyDeg?: number;
+    inclInvPlaneDeg?: number;
+    ascNodeInvPlaneDeg?: number;
+};
+export type KcInvariablePlane = {
+    inclEclipticDeg: number;
+    ascNodeEclipticDeg: number;
+};
+export type KcCosSinTerm = {
+    omegaRadPerYr: number;
+    cos: number;
+    sin: number;
+};
+export type KcComplexTerm = {
+    omegaRadPerYr: number;
+    re: number;
+    im: number;
+};
+export type KcPoissonCosSinTerm = {
+    comps: Array<{
+        planet: string;
+        sLam?: number;
+        sPom?: number;
+    }>;
+    cos: number;
+    sin: number;
+};
+export type KcPoissonComplexTerm = {
+    comps: Array<{
+        planet: string;
+        sLam?: number;
+        sPom?: number;
+    }>;
+    re: number;
+    im: number;
+};
+export type KcAffine = {
+    off: number;
+    slope?: number;
+};
+export type KcPeriodicTerms = {
+    windowAffine?: {
+        [x: string]: KcAffine;
+    };
+    mlonArcsec?: KcCosSinTerm[];
+    aPpm?: KcCosSinTerm[];
+    z?: KcComplexTerm[];
+    zeta?: KcComplexTerm[];
+    poissonMlonArcsec?: KcPoissonCosSinTerm[];
+    poissonZ?: KcPoissonComplexTerm[];
+};
+export type KcPlanetChain = {
+    anchor: KcElements;
+    periRateArcsecCy: number;
+    meanMotionDegPerYr: (number | null);
+    windowRates?: {
+        meanMotionDegPerYr?: number;
+        nodeRateArcsecCy?: number;
+        eccDotPerCy?: number;
+        inclDotArcsecCy?: number;
+    };
+    secularModes?: ({
+        z: KcComplexTerm[];
+        zeta: KcComplexTerm[];
+    } | null);
+    periodicTerms?: (KcPeriodicTerms | undefined);
+    invariablePlane?: (KcInvariablePlane | undefined);
+};
+export const ANCHOR_EPOCH_YEAR: 2000;
+export const ANCHOR_EPOCH_JD: 2451545;
+/** Full osculating elements from a heliocentric ecliptic-J2000 state vector.
+ *  @param {number[]} rKm  heliocentric position, km
+ *  @param {number[]} vKmS heliocentric velocity, km/s
+ *  @param {number} muKm3S2 GM_Sun + GM_planet
+ *  @param {number} auKm   the model's AU in km (caller's single home)
+ *  @returns {{aAU:number,e:number,inclEclipticDeg:number,ascNodeEclipticDeg:number,
+ *             argPeriDeg:number,lonPeriEclipticDeg:number,meanAnomalyDeg:number,
+ *             meanLonEclipticDeg:number,meanMotionDegPerYr:number}} */
+export function computeOsculatingElements(rKm: number[], vKmS: number[], muKm3S2: number, auKm: number): {
+    aAU: number;
+    e: number;
+    inclEclipticDeg: number;
+    ascNodeEclipticDeg: number;
+    argPeriDeg: number;
+    lonPeriEclipticDeg: number;
+    meanAnomalyDeg: number;
+    meanLonEclipticDeg: number;
+    meanMotionDegPerYr: number;
+};
+/** Solve Kepler's equation E − e·sinE = M (radians), Newton iteration.
+ *  @param {number} meanAnomalyRad @param {number} e @returns {number} */
+export function solveKeplerRad(meanAnomalyRad: number, e: number): number;
+/** Heliocentric ecliptic-J2000 position from elements-of-date.
+ *  @param {{aAU:number,e:number,inclEclipticDeg:number,ascNodeEclipticDeg:number,
+ *           lonPeriEclipticDeg:number,meanLonEclipticDeg:number}} el
+ *  @returns {{xAU:number,yAU:number,zAU:number,rAU:number}} */
+export function computeHeliocentricEclipticFromElements(el: {
+    aAU: number;
+    e: number;
+    inclEclipticDeg: number;
+    ascNodeEclipticDeg: number;
+    lonPeriEclipticDeg: number;
+    meanLonEclipticDeg: number;
+}): {
+    xAU: number;
+    yAU: number;
+    zAU: number;
+    rAU: number;
+};
+/** Poisson argument θ (radians) at `year`: Σ comps of s_lam·λ̄ + s_pom·ϖ over
+ *  the referenced planets — λ̄ from the linear skeleton, ϖ(t) from the
+ *  multi-mode secular sum (d'Alembert-complete arguments; K4.7b — RECORD
+ *  ONLY: the era solve measured Poisson columns negative, no terms are
+ *  exported; the machinery stands as the campaign record).
+ *  @param {number} year @param {Object<string,KcPlanetChain>} allChains
+ *  @param {Array<{planet:string,sLam?:number,sPom?:number}>} comps
+ *  @returns {number} */
+export function computePoissonArgRad(year: number, allChains: {
+    [x: string]: KcPlanetChain;
+}, comps: Array<{
+    planet: string;
+    sLam?: number;
+    sPom?: number;
+}>): number;
+/** Elements-of-date for one planet.
+ *  @param {number} year decimal year (epoch parameter first, per naming rule)
+ *  @param {KcPlanetChain} planetChain
+ *  @param {Object<string,KcPlanetChain>=} allChains  full chain set — required
+ *         only when planetChain.periodicTerms carries Poisson-argument terms
+ *  @returns {KcElements} elements at `year` */
+export function computePlanetElementsAtYear(year: number, planetChain: KcPlanetChain, allChains?: {
+    [x: string]: KcPlanetChain;
+} | undefined): KcElements;
+/**
+ * The SECULAR apsidal tangent of date — dϖ/dt of the chain's smooth
+ * mode-sum, deg per year, J2000-ecliptic frame, ±150-yr central stencil
+ * (the same rate family the panel's Prec. cell displays). The chain
+ * carries no short-period content, so the tangent is stencil-stable
+ * (measured: Earth 11.6160″/yr flat from ±1 to ±500 yr). ONE home: the
+ * year-length factory's anomalistic construction and every panel surface
+ * wire THIS, so the displayed apsidal beats agree by construction.
+ * @param {number} year decimal calendar year (epoch parameter first, per naming rule)
+ * @param {KcPlanetChain} planetChain the planet's chain (buildPlanetChainsFromArtifactData)
+ * @param {Object<string,KcPlanetChain>=} allChains the full chain map
+ * @returns {number} deg/yr, prograde positive
+ */
+export function computeApsidalSecularDegPerYr(year: number, planetChain: KcPlanetChain, allChains?: {
+    [x: string]: KcPlanetChain;
+} | undefined): number;
+/** The chain's canonical constructor from a PARSED governed artifact (K2.1 →
+ *  K4.6c): anchors (the engine-extracted t=0 elements), era-typed window
+ *  rates, the K4.7 secular mode tables, and the K4.5/K4.7b periodic layer.
+ *  @param {*} art  the governed engine-D artifact, parsed (deep JSON —
+ *         shape enforced by the generator's assertions, not retyped here)
+ *  @param {{skeletonOnly?:boolean}=} opts  skeletonOnly omits the periodic
+ *         layer — REQUIRED by the extraction/solve instruments, which
+ *         measure the residual AGAINST the skeleton; a terms-bearing chain
+ *         there would extract its own output.
+ *  @returns {Object<string,KcPlanetChain>} */
+export function buildPlanetChainsFromArtifactData(art: any, opts?: {
+    skeletonOnly?: boolean;
+} | undefined): {
+    [x: string]: KcPlanetChain;
+};

package/types/planets/model.d.cts

@@ -0,0 +1,116 @@
+export type PlanetModelBody = {
+    /**
+     * - geometry type branch ('I' | 'II' | 'III')
+     */
+    type?: string | undefined;
+    solarYearInput: number;
+    fibonacciD?: number | undefined;
+    invPlaneInclinationJ2000?: number | undefined;
+    longitudePerihelion?: number | undefined;
+    inclinationCycleAnchor?: number | undefined;
+    antiPhase?: boolean | undefined;
+    perihelionEclipticYears?: number | undefined;
+    axialPrecessionYears?: number | undefined;
+    obliquityCycle?: number | null | undefined;
+    axialTiltJ2000?: number | undefined;
+    orbitalEccentricityJ2000?: number | undefined;
+    ascendingNode?: number | undefined;
+    rotationPeriodDays?: number | undefined;
+    /**
+     * - minor bodies: JSON input;
+     * carriers: ignored (the K law derives it)
+     */
+    orbitalEccentricityBase?: number | undefined;
+    orbitDistanceOverride?: number | undefined;
+};
+export type PlanetModelEnv = {
+    holisticYears: number;
+    meanSolarYearDays: number;
+    balancedYear: number;
+    systemResetN: number;
+    currentAUDistanceKm: number;
+    earthEccentricityJ2000: number;
+    earthPerihelionLongitudeJ2000Deg: number;
+    calibration: {
+        earthInvPlaneInclinationAmplitude: number;
+        massEarthAlone: number;
+        massSun: number;
+        eccentricityAmplitude: number;
+        earthTiltMeanDeg: number;
+    };
+    massFractions: Record<string, number>;
+};
+export type PlanetModelRecord = {
+    invPlaneInclinationAmplitude?: number | undefined;
+    invPlaneInclinationMean?: number | undefined;
+    wobblePeriodYears?: number | undefined;
+    obliquityMeanDeg?: number | undefined;
+    eccentricityAmplitude?: number | undefined;
+    eccentricityBase?: number | undefined;
+    eccentricityPhaseJ2000Deg?: number | undefined;
+    geometry: ReturnType<typeof derivePlanetGeometry>;
+};
+/**
+ * @typedef {Object} PlanetModelBody
+ * @property {string} [type] - geometry type branch ('I' | 'II' | 'III')
+ * @property {number} solarYearInput
+ * @property {number} [fibonacciD]
+ * @property {number} [invPlaneInclinationJ2000]
+ * @property {number} [longitudePerihelion]
+ * @property {number} [inclinationCycleAnchor]
+ * @property {boolean} [antiPhase]
+ * @property {number} [perihelionEclipticYears]
+ * @property {number} [axialPrecessionYears]
+ * @property {number|null} [obliquityCycle]
+ * @property {number} [axialTiltJ2000]
+ * @property {number} [orbitalEccentricityJ2000]
+ * @property {number} [ascendingNode]
+ * @property {number} [rotationPeriodDays]
+ * @property {number} [orbitalEccentricityBase] - minor bodies: JSON input;
+ *   carriers: ignored (the K law derives it)
+ * @property {number} [orbitDistanceOverride]
+ */
+/**
+ * @typedef {Object} PlanetModelEnv
+ * @property {number} holisticYears
+ * @property {number} meanSolarYearDays
+ * @property {number} balancedYear
+ * @property {number} systemResetN
+ * @property {number} currentAUDistanceKm
+ * @property {number} earthEccentricityJ2000
+ * @property {number} earthPerihelionLongitudeJ2000Deg
+ * @property {{ earthInvPlaneInclinationAmplitude: number,
+ *   massEarthAlone: number, massSun: number,
+ *   eccentricityAmplitude: number, earthTiltMeanDeg: number }} calibration
+ * @property {Record<string, number>} massFractions
+ */
+/**
+ * @typedef {Object} PlanetModelRecord
+ * @property {number} [invPlaneInclinationAmplitude]
+ * @property {number} [invPlaneInclinationMean]
+ * @property {number} [wobblePeriodYears]
+ * @property {number} [obliquityMeanDeg]
+ * @property {number} [eccentricityAmplitude]
+ * @property {number} [eccentricityBase]
+ * @property {number} [eccentricityPhaseJ2000Deg]
+ * @property {ReturnType<typeof derivePlanetGeometry>} geometry
+ */
+/**
+ * Run the full derivation chain over a set of body records.
+ *
+ * @param {PlanetModelEnv} env
+ * @param {Record<string, PlanetModelBody>} bodies - keyed by body name
+ *   (the key selects the body-unique geometry branches: mercury, pluto,
+ *   halleys, ceres)
+ * @returns {{ psiConstant: number, kConstant: number,
+ *   eccentricityAnchor: number, t2000: number,
+ *   bodies: Record<string, PlanetModelRecord> }}
+ */
+export function createPlanetModel(env: PlanetModelEnv, bodies: Record<string, PlanetModelBody>): {
+    psiConstant: number;
+    kConstant: number;
+    eccentricityAnchor: number;
+    t2000: number;
+    bodies: Record<string, PlanetModelRecord>;
+};
+import { derivePlanetGeometry } from "./geometry.cjs";

package/types/planets/orbit-chain.d.cts

@@ -0,0 +1,12 @@
+/**
+ * @param {number} tMa @param {number} valueJ2000
+ * @param {number} massLossFracPerYear @returns {number} */
+export function massLossScaledLinearAtAge(tMa: number, valueJ2000: number, massLossFracPerYear: number): number;
+/**
+ * @param {number} tMa @param {number} periodJ2000Seconds
+ * @param {number} massLossFracPerYear @returns {number} */
+export function driver2PeriodSecondsAtAge(tMa: number, periodJ2000Seconds: number, massLossFracPerYear: number): number;
+/**
+ * @param {number} planetPeriodSeconds @param {number} yearSeconds
+ * @returns {number} */
+export function synodicPeriodSeconds(planetPeriodSeconds: number, yearSeconds: number): number;

package/types/planets/orientation.d.cts

@@ -0,0 +1,67 @@
+/**
+ * Invariable-plane inclination at explicit time (browser form): the ICRF
+ * perihelion-linked oscillation i(t) = mean + s·A·cos(ϖ_ICRF(t) − anchor).
+ * @param {{ key?: string, isEarth?: boolean,
+ *   invPlaneInclinationJ2000: number, invPlaneInclinationMean: number,
+ *   invPlaneInclinationAmplitude: number, inclinationCycleAnchor: number,
+ *   longitudePerihelion: number, perihelionEclipticYears: number,
+ *   antiPhase?: boolean }} body
+ * @param {number} yearsSinceBalanced
+ * @param {{ H: number, yearsFromBalancedToJ2000: number }} env
+ * @returns {number} degrees */
+export function invPlaneInclinationAt(body: {
+    key?: string;
+    isEarth?: boolean;
+    invPlaneInclinationJ2000: number;
+    invPlaneInclinationMean: number;
+    invPlaneInclinationAmplitude: number;
+    inclinationCycleAnchor: number;
+    longitudePerihelion: number;
+    perihelionEclipticYears: number;
+    antiPhase?: boolean;
+}, yearsSinceBalanced: number, env: {
+    H: number;
+    yearsFromBalancedToJ2000: number;
+}): number;
+/**
+ * Ascending node on the invariable plane — the LINEAR year-2000-anchored
+ * convention (node-integrator/dashboard; see the header).
+ * @param {{ ascendingNodeInvPlane?: number, ascendingNodePeriod?: number,
+ *   perihelionEclipticYears: number }} body
+ * @param {number} year @returns {number} degrees 0–360 */
+export function ascendingNodeInvPlaneLinearAt(body: {
+    ascendingNodeInvPlane?: number;
+    ascendingNodePeriod?: number;
+    perihelionEclipticYears: number;
+}, year: number): number;
+/**
+ * Scene ecliptic inclination — normal-vector dot product, balanced-year
+ * anchoring, planet Ω on the −8H/N assignment (canonicalized at S-P4; the
+ * mirror of src/script.js updateDynamicInclinations).
+ * @param {{ perihelionEclipticYears: number, longitudePerihelion: number,
+ *   inclinationCycleAnchor: number, antiPhase?: boolean,
+ *   invPlaneInclinationMean: number, invPlaneInclinationAmplitude: number,
+ *   ascendingNodeInvPlane: number, ascendingNodeCyclesIn8H?: number }} body
+ * @param {{ invPlanePrecessionYears: number, inclinationMean: number,
+ *   inclinationAmplitude: number, ascendingNodeInvPlane: number }} earth
+ * @param {number} yearsSinceBalanced
+ * @param {{ H: number, yearsFromBalancedToJ2000: number }} env
+ * @returns {number} degrees */
+export function eclipticInclinationFromBalanced(body: {
+    perihelionEclipticYears: number;
+    longitudePerihelion: number;
+    inclinationCycleAnchor: number;
+    antiPhase?: boolean;
+    invPlaneInclinationMean: number;
+    invPlaneInclinationAmplitude: number;
+    ascendingNodeInvPlane: number;
+    ascendingNodeCyclesIn8H?: number;
+}, earth: {
+    invPlanePrecessionYears: number;
+    inclinationMean: number;
+    inclinationAmplitude: number;
+    ascendingNodeInvPlane: number;
+}, yearsSinceBalanced: number, env: {
+    H: number;
+    yearsFromBalancedToJ2000: number;
+}): number;

package/types/planets/predict.d.cts

@@ -0,0 +1,88 @@
+export type PredictPlanetFields = {
+    perihelionEclipticYears: number;
+    longitudePerihelion: number;
+    ascendingNodeCyclesIn8H: number | null | undefined;
+    axialPrecessionYears: number;
+    obliquityCycle: number | null | undefined;
+    wobblePeriod: number | null | undefined;
+};
+export type PredictDeps = {
+    /**
+     * - holistic year length (live: setEpoch mutates it)
+     */
+    getHYears: () => number;
+    getBalancedYear: () => number;
+    /**
+     * - live per-call reads
+     */
+    getPlanetFields: (planetKey: string) => PredictPlanetFields;
+    /**
+     * - θ_E, engine-owned form
+     */
+    calcEarthPerihelionDeg: (year: number) => number;
+    /**
+     * - ERD deg/yr, engine-owned form
+     */
+    calcErdRate: (year: number) => number;
+    computeObliquityEarthDeg: (year: number) => number;
+    computeEccentricityEarth: (year: number) => number;
+    /**
+     * - the fitted solstice-obliquity mean
+     */
+    obliquityMeanDeg: number;
+    /**
+     * - Earth's mean eccentricity (the one law's base′)
+     */
+    eccentricityMean: number;
+};
+/**
+ * @typedef {Object} PredictPlanetFields
+ * @property {number} perihelionEclipticYears
+ * @property {number} longitudePerihelion
+ * @property {number|null|undefined} ascendingNodeCyclesIn8H
+ * @property {number} axialPrecessionYears
+ * @property {number|null|undefined} obliquityCycle
+ * @property {number|null|undefined} wobblePeriod
+ */
+/**
+ * @typedef {Object} PredictDeps
+ * @property {() => number} getHYears - holistic year length (live: setEpoch mutates it)
+ * @property {() => number} getBalancedYear
+ * @property {(planetKey: string) => PredictPlanetFields} getPlanetFields - live per-call reads
+ * @property {(year: number) => number} calcEarthPerihelionDeg - θ_E, engine-owned form
+ * @property {(year: number) => number} calcErdRate - ERD deg/yr, engine-owned form
+ * @property {(year: number) => number} computeObliquityEarthDeg
+ * @property {(year: number) => number} computeEccentricityEarth
+ * @property {number} obliquityMeanDeg - the fitted solstice-obliquity mean
+ * @property {number} eccentricityMean - Earth's mean eccentricity (the one law's base′)
+ */
+/**
+ * Build the predictive-precession machinery over one engine's state.
+ * @param {PredictDeps} deps
+ */
+export function createPredictivePrecession(deps: PredictDeps): {
+    buildPredictiveFeatures: (year: number, planetKey: string) => number[];
+    getPlanetFundamentalPeriodsYears: (planetName: string) => Record<string, number | null>;
+    getFeatureTemplate: (planetName: string) => number[];
+    resetTemplateCache: () => void;
+};
+/**
+ * Any planet's perihelion longitude — simple linear precession from J2000.
+ *
+ * @param {number} theta0Deg - perihelion longitude at J2000 (degrees)
+ * @param {number} periodYears - precession period in years
+ * @param {number} year - decimal year
+ * @returns {number} longitude in degrees [0, 360)
+ */
+export function calcPlanetPerihelionLongDeg(theta0Deg: number, periodYears: number, year: number): number;
+/**
+ * Sum/difference beat periods of two cycles, null where degenerate or
+ * beyond MAX_BEAT_YEARS.
+ *
+ * @param {number|null} t1 @param {number|null} t2
+ * @returns {{ sum: number|null, diff: number|null }}
+ */
+export function beatPair(t1: number | null, t2: number | null): {
+    sum: number | null;
+    diff: number | null;
+};