@essrt/physics 7.0.0 → 9.1.0

package/types/earth/frame-of-date.d.cts

@@ -0,0 +1,37 @@
+export type Vec3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * The Earth frame of date from a one-source sample, unit vectors in the J2000
+ * ecliptic frame: `n` the ecliptic pole of date, `g` the equinox of date, `s`
+ * the spin axis of date. Every vector is `[x, y, z]`.
+ * @param {{epsDeg: number, equinoxLonJ2000Deg: number, orbitNormalX: number, orbitNormalY: number}} sample
+ * @returns {{n: number[], g: number[], s: number[]}}
+ */
+export function computeEarthFrameOfDate(sample: {
+    epsDeg: number;
+    equinoxLonJ2000Deg: number;
+    orbitNormalX: number;
+    orbitNormalY: number;
+}): {
+    n: number[];
+    g: number[];
+    s: number[];
+};
+/**
+ * The wheel angle θ that puts the Sun at ecliptic longitude λ on the scene's
+ * offset circle: the Sun sits at radius 1 (100 scene units) about a centre
+ * displaced by −e along the perihelion direction ϖ (the one eccentricity law's
+ * single arm), P(θ) = −e·û(ϖ) + û(θ), and the geocentric longitude is the
+ * direction of P. Two Newton steps from θ₀ = λ (the offset-circle Jacobian
+ * dλ/dθ = 1 − e·cos(θ − ϖ) + O(e²)); converged to <1e-12 rad for e < 0.1.
+ * Angles in radians; θ increases with λ (the scene's node angles are
+ * λ-handed).
+ * @param {number} lambdaRad - the target geocentric ecliptic longitude
+ * @param {number} e - the eccentricity (the centre offset in units of the radius)
+ * @param {number} periRad - the perihelion longitude ϖ of date (the offset direction is −û(ϖ))
+ * @returns {number} θ in radians, in (−π, π]
+ */
+export function solveWheelAngleForLongitude(lambdaRad: number, e: number, periRad: number): number;

package/types/eclipse/besselian.d.cts

@@ -16,12 +16,9 @@ export type BesselianDeps = {
      */
     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)
+     * - the Sun's derived planetary aberration κ (deg) at calendar year, SUBTRACTED from the geometric Sun longitude (the apparent Sun; see the header)
      */
-    moonExtensionAt: (T: number) => {
-        dLonDeg: number;
-        dLatDeg: number;
-    };
+    sunAberrationDegAt: (year: number) => number;
     /**
      * - framework ΔT (J2000-zeroed convention)
      */
@@ -54,6 +51,7 @@ export type BesselianDeps = {
         gmstMeanSiderealT0Deg: number;
         gmstMeanSiderealRateDegPerDay: number;
         gmstMeanSiderealT2Deg: number;
+        speedOfLightKmS: number;
     };
 };
 /**
@@ -62,7 +60,7 @@ export type BesselianDeps = {
  *   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 {(year: number) => number} sunAberrationDegAt - the Sun's derived planetary aberration κ (deg) at calendar year, SUBTRACTED from the geometric Sun longitude (the apparent Sun; see the header)
  * @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
@@ -72,7 +70,7 @@ export type BesselianDeps = {
  *   moonDiameterKm: number, sunDiameterKm: number, sunDistanceKm: number,
  *   earthFlatteningInverse: number, ttBridgeSeconds: number,
  *   gmstMeanSiderealT0Deg: number, gmstMeanSiderealRateDegPerDay: number,
- *   gmstMeanSiderealT2Deg: number }} constants
+ *   gmstMeanSiderealT2Deg: number, speedOfLightKmS: number }} constants
  */
 /** @param {BesselianDeps} deps */
 export function createBesselian(deps: BesselianDeps): {

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

@@ -27,13 +27,17 @@ export function createSunPlanetaryCompletion({ embWobbleArcsec, carrierRatesDegP
  *  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";
+ *  full-precision carrier rates (deg/cy TT) the TERMS table pairs with:
+ *  the SIDEREAL carriers of plan 06 I2 (record rate − the model's J2000
+ *  precession; Earth the framework sidereal year; the N3 literals kept,
+ *  the two long-period rows derived on these rates). 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
+ *  ≤12″ backstop. test:model recomputes this fingerprint from live
+ *  constants (identical arithmetic to model.js) and fails on mismatch:
+ *  re-run the extraction chain (tools/explore/n2-sun-framework-carriers.mjs
+ *  → i2-sidereal-carrier-table.mjs for the short-period rows,
+ *  i2-long-inequality.mjs for the long-period rows), re-embed TERMS, and
+ *  update this value. */
+export const PAIRED_CARRIER_RATES_SHA256: "2d066e92bae955e4";

package/types/index.d.ts

@@ -15,6 +15,7 @@ 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 { computeSecularShape } from "./planets/secular-shape.cjs";
 export { createSecularSeriesOverride } from "./planets/secular-series.cjs";
 export { createDeepEccChannel } from "./moon/deep-ecc-channel.cjs";
 export { createDeepOrbitalHistory } from "./earth/deep-orbital-history.cjs";
@@ -66,13 +67,14 @@ 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 { computeEarthFrameOfDate, solveWheelAngleForLongitude } from "./earth/frame-of-date.cjs";
 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 { computePlanetPrecessionConstant, createPlanetSpinChannel, createPlanetSpinChannelFromArtifacts, computeObliquityJ2000Deg } from "./planets/spin-channel.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/model.d.ts

@@ -89,6 +89,7 @@ export function assembleModel(C: Readonly<Record<string, any>>, F: Readonly<Reco
     }>;
     cardinal: Readonly<{
         jd: (year: number, type: string) => number;
+        jdNearUT: (jdUT: number, type: string) => number;
         raDeg: (year: number, type: string) => number;
         yearLengthDays: (year: number, type: string) => number;
     }>;
@@ -135,6 +136,8 @@ export function assembleModel(C: Readonly<Record<string, any>>, F: Readonly<Reco
     eclipse: Readonly<{
         sunLonDegAtJD: (jd: number) => number;
         sunLonCompletedDegAtJD: (jd: number) => number;
+        /** The APPARENT Sun (completed geometric − the derived aberration constant + the leading nutation terms on the model's own arguments) — the quantity Horizons' observer ecliptic longitude is; the cardinal instants are its crossings (plan 06 R1/I1). @param {number} jdUT @returns {number} */
+        sunApparentLonDegAtJD: (jdUT: number) => number;
         findLunarInRange: (jdStart: number, jdEnd: number) => {
             jd: number;
             beta: number;
@@ -186,5 +189,28 @@ export function assembleModel(C: Readonly<Record<string, any>>, F: Readonly<Reco
         perihelionLongitudeDeg: (k: string, year: number) => number;
         ascendingNodeInvPlaneDeg: (k: string, year: number) => number;
         invPlaneInclinationDeg: (k: string, year: number) => number;
+        spin: (k: string) => Readonly<{
+            key: string;
+            cassiniLocked: boolean;
+            momentOfInertiaFactor: number;
+            momentOfInertiaFactorClass: string;
+            alphaArcsecPerYr: number;
+            satelliteQuadrupole: number;
+            satelliteAngularMomentum: number;
+            spinRetrograde: boolean;
+            meanMotionRadPerYr: number;
+            obliquityJ2000Deg: number;
+            spinPrecessionRateArcsecPerYrJ2000: number | null;
+            axialPrecessionPeriodYearsJ2000: number | null;
+            obliquityDegAtYear: (year: number) => number | null;
+            spinPrecessionRateArcsecPerYrAtYear: (year: number) => number | null;
+            obliquityEnvelopeDeg: (year: number, spanYr: number) => {
+                minDeg: number;
+                meanDeg: number;
+                maxDeg: number;
+            } | null;
+            stepYr: number;
+            maxSpanYr: 10000000;
+        }>;
     }>;
 }>;

package/types/moon/apparent.d.cts

@@ -1,75 +1,14 @@
-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).
+ * No dependencies since R3 item 1 (the former D5 optics constants and the
+ * fitted-patch getters are gone); the factory shape is kept for the two
+ * scene twins' call sites.
+ * @param {object} [_deps] ignored
  */
-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 }: {
+export function createMoonApparent(_deps?: object): {
+    overrideRaDec: ({ lonDeg, betRad, obliquityDeg }: {
         lonDeg: number;
         betRad: number;
-        meeusT: (number | undefined);
+        meeusT?: (number | undefined);
         obliquityDeg: number;
     }) => {
         raRad: number;

package/types/moon/deep-ecc-channel.d.cts

@@ -1,12 +1,39 @@
 /**
+ * THE SLOPE ANCHOR (owner-approved model change, after the Moon panels).
+ * The 18-term table reproduces the attractor and the 405-kyr beat, but
+ * nothing constrained its local DERIVATIVE at J2000: measured, its ė read
+ * −5.00e-5/cy against the run's own −4.24e-5 (and the observed −4.20e-5),
+ * a 19 % slope error that the lunar chain multiplied straight into the
+ * perigee and node curvature (−44″/cy² against Meeus's −37″/cy² — the
+ * "18 % split" the Moon precession panels showed). Against the ±10-Myr
+ * series the table compresses, the error is a LINEAR vector drift of
+ * 2.25e-4 per kyr out to ±20 kyr (an unresolved ultra-long mode), then
+ * spectrum-class either way. So the anchored form gains a second,
+ * BOUNDED term of the same class as the constant remainder:
+ *
+ *     z(t) = Σ … + (z_J2000 − Σ(0)) + (ż_J2000 − Σ̇(0))·I(t),
+ *     I(t) = ∫₀ᵗ cos²(π τ / 2T_q) dτ  (the arguments' taper: linear near
+ *            J2000, saturating at ±T_q/2 beyond |t| ≥ T_q)
+ *
+ * — ż_J2000 is the run's own z-rate at J2000 (script-written into the
+ * artifact by generate.mjs from the banked series: "we are the source"),
+ * T_q the H/12 taper the arguments' rate anchors ride. Inside the canon it
+ * restores the run's slope exactly; beyond ±T_q it is a constant vector
+ * offset of ~3e-3, the size of the table's own spectrum-class scatter
+ * there, never a growing polynomial. Absent the two fields (an older
+ * artifact), the channel is the value-anchored form above, unchanged.
+ *
  * @param {{
  *   earthZ: ReadonlyArray<{omegaRadPerYr: number, re: number, im: number}>,
  *   anchorE: number,
  *   anchorPeriEclipticDeg: number,
+ *   anchorZDotPerYr?: ReadonlyArray<number>,
+ *   slopeTaperYears?: number,
  * }} artifact — the embedded deep-modes artifact (earth z-modes + the J2000
- *   anchor pair joined from the chain artifact's one home).
+ *   anchor pair joined from the chain artifact's one home, + the J2000
+ *   z-rate pair and the taper from the series' one home).
  */
-export function createDeepEccChannel({ earthZ, anchorE, anchorPeriEclipticDeg }: {
+export function createDeepEccChannel({ earthZ, anchorE, anchorPeriEclipticDeg, anchorZDotPerYr, slopeTaperYears }: {
     earthZ: ReadonlyArray<{
         omegaRadPerYr: number;
         re: number;
@@ -14,6 +41,8 @@ export function createDeepEccChannel({ earthZ, anchorE, anchorPeriEclipticDeg }:
     }>;
     anchorE: number;
     anchorPeriEclipticDeg: number;
+    anchorZDotPerYr?: ReadonlyArray<number>;
+    slopeTaperYears?: number;
 }): {
     eccAt: (tYr: number) => number;
     eccRateAt: (tYr: number) => number;

package/types/moon/deep-modes-artifact.d.cts

@@ -136,5 +136,7 @@ export const DEEP_MODES_ARTIFACT: Readonly<{
     anchorPeriEclipticDeg: 462.9179213996577;
     anchorInclEclipticDeg: 0.00010345820355474172;
     anchorAscNodeEclipticDeg: 140.29217988414328;
+    anchorZDotPerYr: number[];
+    slopeTaperYears: 27943.083333333332;
 }>;
 export const DEEP_MODES_ARTIFACT_HASH: "77e0baf779e85de5";

package/types/moon/month-chain.d.cts

@@ -14,6 +14,8 @@
  *     nNodalOfDateJ2000: number,
  *     moonApsidalJ2000Seconds: number,
  *     moonNodalJ2000Seconds: number,
+ *     moonApsidalOfDateJ2000Seconds: number,
+ *     moonNodalOfDateJ2000Seconds: number,
  *     moonSiderealMonthJ2000Seconds: number,
  *     sPerigee: number,
  *     sNode: number,
@@ -47,6 +49,8 @@ export function createMoonMonthChain({ constants, fns }: {
         nNodalOfDateJ2000: number;
         moonApsidalJ2000Seconds: number;
         moonNodalJ2000Seconds: number;
+        moonApsidalOfDateJ2000Seconds: number;
+        moonNodalOfDateJ2000Seconds: number;
         moonSiderealMonthJ2000Seconds: number;
         sPerigee: number;
         sNode: number;

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

@@ -25,35 +25,6 @@ export function computeInclinationLaw(b: {
     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,

package/types/planets/model.d.cts

@@ -10,8 +10,14 @@ export type PlanetModelBody = {
     inclinationCycleAnchor?: number | undefined;
     antiPhase?: boolean | undefined;
     perihelionEclipticYears?: number | undefined;
-    axialPrecessionYears?: number | undefined;
-    obliquityCycle?: number | null | undefined;
+    /**
+     * - carriers: the chain's g-mode beat (input since Phase 7 commit 2)
+     */
+    wobblePeriodYears?: number | undefined;
+    /**
+     * - carriers: the derived J2000 obliquity (input since Phase 7 commit 2)
+     */
+    obliquityMeanDeg?: number | undefined;
     axialTiltJ2000?: number | undefined;
     orbitalEccentricityJ2000?: number | undefined;
     ascendingNode?: number | undefined;
@@ -60,8 +66,8 @@ export type PlanetModelRecord = {
  * @property {number} [inclinationCycleAnchor]
  * @property {boolean} [antiPhase]
  * @property {number} [perihelionEclipticYears]
- * @property {number} [axialPrecessionYears]
- * @property {number|null} [obliquityCycle]
+ * @property {number} [wobblePeriodYears] - carriers: the chain's g-mode beat (input since Phase 7 commit 2)
+ * @property {number} [obliquityMeanDeg] - carriers: the derived J2000 obliquity (input since Phase 7 commit 2)
  * @property {number} [axialTiltJ2000]
  * @property {number} [orbitalEccentricityJ2000]
  * @property {number} [ascendingNode]

package/types/planets/secular-shape.d.cts

@@ -0,0 +1,30 @@
+/**
+ * @param {{ secularModes: Record<string, { z: ReadonlyArray<{omegaRadPerYr: number, re: number, im: number}> }> }} artifact
+ * @param {string} key
+ * @returns {{ dom: { arcsecPerYr: number, amp: number }, sub: { arcsecPerYr: number, amp: number },
+ *   rest: { count: number, amp: number }, ampSumAll: number, beatYears: number }}
+ */
+export function computeSecularShape(artifact: {
+    secularModes: Record<string, {
+        z: ReadonlyArray<{
+            omegaRadPerYr: number;
+            re: number;
+            im: number;
+        }>;
+    }>;
+}, key: string): {
+    dom: {
+        arcsecPerYr: number;
+        amp: number;
+    };
+    sub: {
+        arcsecPerYr: number;
+        amp: number;
+    };
+    rest: {
+        count: number;
+        amp: number;
+    };
+    ampSumAll: number;
+    beatYears: number;
+};

package/types/planets/spin-channel.d.cts

@@ -0,0 +1,193 @@
+export type SpinSatellite = {
+    name?: string;
+    gmKm3S2: number;
+    semiMajorAxisKm: number;
+    orbitalPeriodDays: number;
+    retrograde?: boolean;
+};
+export type SpinInputs = {
+    j2: number;
+    j2ReferenceRadiusKm: number;
+    momentOfInertiaFactor: number;
+    momentOfInertiaFactorClass?: string;
+    rotationRateDegPerDay: number;
+    poleRaJ2000Deg: number;
+    poleDecJ2000Deg: number;
+    cassiniLocked?: boolean;
+    satellites: ReadonlyArray<SpinSatellite>;
+};
+/** @typedef {{ name?: string, gmKm3S2: number, semiMajorAxisKm: number, orbitalPeriodDays: number, retrograde?: boolean }} SpinSatellite */
+/** @typedef {{ j2: number, j2ReferenceRadiusKm: number, momentOfInertiaFactor: number,
+ *   momentOfInertiaFactorClass?: string, rotationRateDegPerDay: number,
+ *   poleRaJ2000Deg: number, poleDecJ2000Deg: number, cassiniLocked?: boolean,
+ *   satellites: ReadonlyArray<SpinSatellite> }} SpinInputs */
+/**
+ * The precession constant from the planet's own torques.
+ * @param {{
+ *   j2: number, j2ReferenceRadiusKm: number, momentOfInertiaFactor: number,
+ *   rotationRateDegPerDay: number, satellites: ReadonlyArray<SpinSatellite>,
+ *   gmPlanetSystemKm3S2: number, meanMotionRadPerYr: number, eccentricity: number,
+ * }} p
+ * @returns {{ alphaArcsecPerYr: number, alphaRadPerYr: number, q: number, l: number,
+ *   spinRadPerYr: number, spinRetrograde: boolean, gmPlanetAloneKm3S2: number }}
+ */
+export function computePlanetPrecessionConstant(p: {
+    j2: number;
+    j2ReferenceRadiusKm: number;
+    momentOfInertiaFactor: number;
+    rotationRateDegPerDay: number;
+    satellites: ReadonlyArray<SpinSatellite>;
+    gmPlanetSystemKm3S2: number;
+    meanMotionRadPerYr: number;
+    eccentricity: number;
+}): {
+    alphaArcsecPerYr: number;
+    alphaRadPerYr: number;
+    q: number;
+    l: number;
+    spinRadPerYr: number;
+    spinRetrograde: boolean;
+    gmPlanetAloneKm3S2: number;
+};
+/**
+ * @param {{
+ *   key: string,
+ *   spin: SpinInputs,
+ *   zetaModes: ReadonlyArray<{omegaRadPerYr: number, re: number, im: number}>,
+ *   anchorInclEclipticDeg: number, anchorAscNodeEclipticDeg: number,
+ *   semiMajorAxisAU: number, eccentricity: number, massFractionOfSun: number,
+ *   gmSunKm3S2: number, obliquityJ2000Deg: number, stepYr?: number,
+ * }} deps — spin from the astro-reference planetSpinPhysical block; the ζ
+ *   table and the J2000 anchor elements from the governed artifacts; the
+ *   mass fraction (planet system / Sun) for the two-body mean motion
+ *   n = 2π√((1 + μ)/a³); the J2000 obliquity of the ecliptic for the pole
+ *   conversion.
+ */
+export function createPlanetSpinChannel(deps: {
+    key: string;
+    spin: SpinInputs;
+    zetaModes: ReadonlyArray<{
+        omegaRadPerYr: number;
+        re: number;
+        im: number;
+    }>;
+    anchorInclEclipticDeg: number;
+    anchorAscNodeEclipticDeg: number;
+    semiMajorAxisAU: number;
+    eccentricity: number;
+    massFractionOfSun: number;
+    gmSunKm3S2: number;
+    obliquityJ2000Deg: number;
+    stepYr?: number;
+}): Readonly<{
+    key: string;
+    cassiniLocked: boolean;
+    momentOfInertiaFactor: number;
+    momentOfInertiaFactorClass: string;
+    alphaArcsecPerYr: number;
+    satelliteQuadrupole: number;
+    satelliteAngularMomentum: number;
+    spinRetrograde: boolean;
+    meanMotionRadPerYr: number;
+    obliquityJ2000Deg: number;
+    spinPrecessionRateArcsecPerYrJ2000: number | null;
+    axialPrecessionPeriodYearsJ2000: number | null;
+    obliquityDegAtYear: (year: number) => number | null;
+    spinPrecessionRateArcsecPerYrAtYear: (year: number) => number | null;
+    obliquityEnvelopeDeg: (year: number, spanYr: number) => {
+        minDeg: number;
+        meanDeg: number;
+        maxDeg: number;
+    } | null;
+    stepYr: number;
+    maxSpanYr: 10000000;
+}>;
+/**
+ * The channel from the governed artifacts — the ONE construction every
+ * runtime shares (the package model, the Node scene engine, the browser
+ * through the model): the spin block, the chain's J2000 anchor elements and
+ * the deep ζ table for `key`.
+ * @param {{
+ *   key: string,
+ *   planetSpinPhysical: Record<string, SpinInputs>,
+ *   chainAnchorElements: Record<string, { aAU: number, e: number, inclEclipticDeg: number, ascNodeEclipticDeg: number }>,
+ *   planetZeta: Record<string, ReadonlyArray<{omegaRadPerYr: number, re: number, im: number}>>,
+ *   massFractionOfSun: number, gmSunKm3S2: number, obliquityJ2000Deg: number,
+ * }} deps
+ */
+export function createPlanetSpinChannelFromArtifacts(deps: {
+    key: string;
+    planetSpinPhysical: Record<string, SpinInputs>;
+    chainAnchorElements: Record<string, {
+        aAU: number;
+        e: number;
+        inclEclipticDeg: number;
+        ascNodeEclipticDeg: number;
+    }>;
+    planetZeta: Record<string, ReadonlyArray<{
+        omegaRadPerYr: number;
+        re: number;
+        im: number;
+    }>>;
+    massFractionOfSun: number;
+    gmSunKm3S2: number;
+    obliquityJ2000Deg: number;
+}): Readonly<{
+    key: string;
+    cassiniLocked: boolean;
+    momentOfInertiaFactor: number;
+    momentOfInertiaFactorClass: string;
+    alphaArcsecPerYr: number;
+    satelliteQuadrupole: number;
+    satelliteAngularMomentum: number;
+    spinRetrograde: boolean;
+    meanMotionRadPerYr: number;
+    obliquityJ2000Deg: number;
+    spinPrecessionRateArcsecPerYrJ2000: number | null;
+    axialPrecessionPeriodYearsJ2000: number | null;
+    obliquityDegAtYear: (year: number) => number | null;
+    spinPrecessionRateArcsecPerYrAtYear: (year: number) => number | null;
+    obliquityEnvelopeDeg: (year: number, spanYr: number) => {
+        minDeg: number;
+        meanDeg: number;
+        maxDeg: number;
+    } | null;
+    stepYr: number;
+    maxSpanYr: 10000000;
+}>;
+/**
+ * The DERIVED J2000 obliquity to the planet's own orbit, degrees: the angle
+ * between the J2000 spin axis (angular-momentum sense — Venus ≈ 177°,
+ * Uranus ≈ 98°) and the chain's J2000 orbit plane. Needs no mode table and
+ * no integration — the load-time twins read it for the K device's
+ * "mean obliquity" slot (commit 2 of Phase 7); the acute form is
+ * `min(ε, 180 − ε)`.
+ * @param {{ spin: SpinInputs, anchorInclEclipticDeg: number,
+ *   anchorAscNodeEclipticDeg: number, obliquityJ2000Deg: number }} p
+ * @returns {number}
+ */
+export function computeObliquityJ2000Deg(p: {
+    spin: SpinInputs;
+    anchorInclEclipticDeg: number;
+    anchorAscNodeEclipticDeg: number;
+    obliquityJ2000Deg: number;
+}): number;
+/**
+ * The IAU pole (ICRF equatorial RA/Dec) as an ecliptic-J2000 unit vector.
+ * @param {number} raDeg @param {number} decDeg @param {number} obliquityJ2000Deg
+ * @returns {number[]}
+ */
+export function poleEclipticJ2000(raDeg: number, decDeg: number, obliquityJ2000Deg: number): number[];
+/**
+ * The planet's orbit normal n̂(t) in ecliptic J2000 from its deep ζ table,
+ * DC-anchored at the chain's J2000 plane (the Earth hybrid's ζ convention:
+ * ζ = sin(i/2)·e^{iΩ}; the anchor is the coordinate the modes wander around).
+ * @param {ReadonlyArray<{omegaRadPerYr: number, re: number, im: number}>} zetaModes
+ * @param {number} anchorInclEclipticDeg @param {number} anchorAscNodeEclipticDeg
+ * @returns {(tYr: number) => number[]}
+ */
+export function createOrbitNormalEvaluator(zetaModes: ReadonlyArray<{
+    omegaRadPerYr: number;
+    re: number;
+    im: number;
+}>, anchorInclEclipticDeg: number, anchorAscNodeEclipticDeg: number): (tYr: number) => number[];