ephemerides-spectral 0.24.3

High-precision HDC reference instrument for the Sol Star System based on JPL DE441. Native C backend; 52-body roster (Lagrange trojans + retrograde irregulars); per-body Geodetic, Electromagnetic, Magnetic-Multipole, Fluid catalogs; eleven cross-channel coupling surfaces; trajectory + sensing layer (ballistic propagator, 3-regime ICBM, look-angle geometry, BC-differential discrimination); resonance-graph ITN-chain search; spectral body-architecture; SPICE-free runtime.

ephemerides-spectral

High-precision HDC reference instrument for the Sol Star System.

Status: v0.24.3 — production-ready. Two-stage architecture: three interchangeable integer-ALU phase-residue encoders (bip Python / c native / complex128 Python reference) feeding an FPU complex64 HD pipeline (syzygy / observer-bind / eclipse-probability); 52-body roster (v0.16.0 Tier-1 expansion: +4 Saturnian Lagrange trojans (Telesto/Calypso at Tethys L4/L5; Helene/Polydeuces at Dione L4/L5 — first L4/L5 entries in BODIES, multiplicity-2 Laplacian degeneracy at host frequency) + 3 Jovian irregulars (Himalia/Pasiphae/Sinope) + Proteus/Nereid (Neptune sub-graph completion); resonance-graph multi-leg find_itn_chains (v0.17.0 — Dijkstra-style graph search over the (body, epoch) state space generalising the v0.8.1 closed-form Hohmann anchor to multi-leg pathways with small-integer (p, q) gear-ratio resonance signatures per leg; pure-Python addition built on top of find_itn_pathways, no ABI bump); bridge.body_architecture (v0.18.0 — first spectral-architecture surface, classifying heliocentric bodies into the canonical inner-8 / outer-5 partition via the resonance-weighted gateway-graph Laplacian Fiedler vector; the cyclic-group encoder discovers the asteroid-belt boundary without being told it exists; Pluto and Neptune share the deepest outer entry via their 2:3 mean-motion lock; pure-Python addition, no ABI bump; research origin notebook §13.8); bridge.predict_itn_accessibility (v0.18.1 → v0.18.2 — closed-form spectral Δv estimate from the §13.9 hybrid Fiedler-distance regression; v0.18.2 upgraded to a 2-D (f₂, f₃) embedding with R² 0.51 → 0.64 and LOOCV MAE 4.24 → 3.12 km/s; useful for fast first-pass triage at microseconds-per-query vs ~1.5 s for the full Dijkstra; not for trajectory design; research origin notebook §13.9 / §13.10 / §14); Sol Electromagnetic Instrument (v0.19.0 — state-at-epoch query surface for the EM sector with bridge.get_em_state(jd_tdb) / list_em_couplings() / em_architecture(target=None); 16-body roster (1 star + 7 magnetised + 4 induced + 4 unmagnetised) + 7 pairwise EM couplings (Jupiter–Io flux tube headliner at ~10¹² W; Saturn–Enceladus, Saturn–Titan, Sun–Earth IMF, Jupiter–Europa, Jupiter–Ganymede, Sun–asteroid radiation pressure); not a BIP encoder — EM clocks don't form a low-order rational lattice with orbital periods so the cyclic-group discipline doesn't transplant; research origin notebook §16); full Sol Symphony Times; Sol Terra-Luna Time (STLT) with Meton's 432 BCE solstice as the default epoch; Sol Proper Time (SPrT) with --proper; Sol Kinematics (v0.12.0) with --state and kinematics query; Sol Dynamics (v0.13.0) with --dynamics and dynamics query — system energy / per-body energy budgets / pair-wise gravitational forces, validated against the textbook 3.54×10²² N Earth-Sun figure to 0.01 % and the virial theorem to 0.5 %; adaptive ("breathing") couplings under their mainstream-literature name (Gross & Blasius 2008); JPL Power-of-Ten audit baseline (v0.11.2) with all ten rules satisfied (v0.13.4 + v0.13.5 + v0.13.6 + v0.13.7 + v0.13.9 — Rules 1, 3, 4, 5 source-side ratchet-pinned; Rule 10 enforced via cross-platform pedantic-build CI matrix; Rules 6+7 manual audits clean); pre-merge docs+parity hygiene check (v0.13.3) as a soft-warning GitHub Actions workflow. See the Status section below for the version-by-version landing record.

Overview

ephemerides-spectral is a hyperdimensional-computing instrument that encodes the barycentric state of our star system using high-precision ephemeris data (NASA JPL DE441 / DE442) as resonant phases over a graph Laplacian.

Two-stage architecture: integer-ALU phase residues, then FPU HD lift

The package separates the phase-residue computation (integer ALU, no FPU on the hot path) from the HD operations (syzygy projection, observer-bind, eclipse-probability — necessarily FPU because channel bases are unit-magnitude complex). The phase-residue stage has three interchangeable encoders; the HD stage runs complex64 natively or complex128 as the reference.

Phase-residue encoders (integer ALU)

• bip (default) — bit-serialised integer ALU in pure Python. Phase composition lives in the cyclic group Z_{2^32}; binding is (φ_1 + φ_2) mod 2^32, which is implicit uint32 overflow — no FPU in the hot path. 305× faster than the FPU reference; 256 KB state at D=65536. Always available.
• c (v0.3.1+) — native C library (libephemerides_spectral.{so,dll,dylib}) bundled in the platform wheel under _native/, loaded via ctypes. Byte-for-byte identical phase residues to bip; ~1000× speedup on the chunk loop (encode at +20 yr: 46 ms Python → 0.04 ms C). Falls back transparently to bip if the binary isn't loadable (sdist installs without a C toolchain, Pyodide / WASM, the pure-Python fallback wheel).

All three phase-residue encoders implement the same algebraic substrate (cyclic-group representation of celestial phase-space, graph-Laplacian eigenbasis) and produce identical uint32[38] residues at any JD; they trade precision for speed (the integer-ALU encoders are exact in Z_{2^32}; the complex128 reference is float-ULP-quantised).

HD pipeline (FPU, complex64 production / complex128 regression)

Once the integer phase residues are computed, the HD operations (syzygy operator, observer-bind, eclipse-probability) lift them to a D-dimensional hypervector. This stage is necessarily FPU because the channel bases are (cos(φ), sin(φ)) complex pairs.

• backend="auto" (default for get_local_view / get_eclipse_probability) — selects c if the native binary is loaded (Tier 2b ABI v6), else falls back to bip integer phases lifted via the Python complex64 shim.
• backend="c" — Tier 2b in C (es_encode_state_hd / es_bind_observer / es_get_eclipse_probability); complex64 storage (single-precision); ABI v6 since v0.7.0; parity smoke pins both paths to within float-ULP.
• backend="fpu-ref" — Python complex128 reference encoder with unit-norm complex Gaussian bases. Regression baseline only; used to validate the c and bip paths against double-precision ground truth, not as the production HD path. Kept for the same reason scientific software keeps reference implementations alongside production ones.

TL;DR on "pure ALU": phase residues are integer ALU end-to-end (BIP encoder hot path is uint64/int64/uint32, no floats); HD operations (syzygy / observer-bind / eclipse) lift those residues to complex64 and run on FPU. The package is not pure-ALU end-to-end — the HD pipeline can't be, because complex-magnitude bases require trigonometric channels. The integer-ALU discipline applies to the encoder hot path and is enforced by the JPL Power-of-Ten audit (Rule 10 pedantic-build matrix).

Companion Project

ephemerides-spectral lives in the same docs/antikythera-maths/ folder as antikythera-spectral because the two share the spectral / cyclic-group framing and the Pyodide bridge contract. They are not consolidated: antikythera-spectral encodes a specific bronze-age mechanism (940-tooth Callippic gear DAG) while ephemerides-spectral encodes the live JPL DE441 ephemeris with phase-dependent (breathing) gravitational couplings. The chess-spectral notebook §20.13–§20.17 calls out the cross-pollination — chess uses Z_{640} (paying an explicit % 640 per op); ephemerides uses Z_{2^32} (free uint32 overflow).

Key Capabilities

• Graph Laplacian Propagator: Diagonal content = Newtonian mean motions + Mercury 43"/century post-Newtonian correction. Off-diagonal = gravitational fiber couplings (planet-sun, moon-planet, mean-motion resonances, asteroid-Jupiter).
• Phase 9 Adaptive Couplings (a.k.a. "breathing") (v0.9.2 CLI rename): Off-diagonal weights modulate with the resonant phase difference cos(n_a·φ_a − n_b·φ_b). Formally a state-dependent (non-autonomous) graph Laplacian / adaptive Kuramoto-family network with phase-difference-dependent coupling (Gross & Blasius 2008, "Adaptive coevolutionary networks") — see the research notebook §1.4 for the full positioning across spectral-graph-theory / dynamical-systems / DNLS-on-a-graph vocabularies. CLI: ephemerides-spectral adaptive --jd ... (canonical) or ephemerides-spectral breathing --jd ... (visual-metaphor synonym; same handler, identical output). Implemented end-to-end without FPU using a 1024-entry int32 cosine LUT (Q1.14 amplitude, 4 KB).
• Sol Star System Roster (v0.5.0+): 38 bodies — Sun, 9 planets (incl. Pluto), 24 moons, 4 main-belt asteroids. The moon set covers Earth's Moon, Mars's Phobos / Deimos, all 4 Galileans (Io, Europa, Ganymede, Callisto) plus the 4 inner regulars (Metis, Adrastea, Amalthea, Thebe), the canonical 9 Saturnians (Mimas, Enceladus, Tethys, Dione, Rhea, Titan, Hyperion, Iapetus, Phoebe) plus the Janus / Epimetheus co-orbitals, Uranus's Titania, and Neptune's Triton.
• Mean-motion resonances (v0.5.0+): 7 entries in RESONANCES — Jupiter–Saturn 5:2, Neptune–Pluto 3:2, Io–Europa 2:1, Europa–Ganymede 2:1, Mimas–Tethys 4:2 (Cassini Division), Enceladus–Dione 2:1 (powers Enceladus tidal heating), Titan–Hyperion 4:3 (Hyperion's chaotic rotation). Natural-resonance gear group: Z_60 = Z_4 × Z_3 × Z_5.
• Runtime kernel patching (v0.4.0+): Diagnosed-fiber overlay — patches sit beside the published kernel as DATA, not code edits, and contribute per-body residue deltas at encode time. Inspired by Linux ksplice / kpatch; the kernel's published bytes never change. Bridge surface: apply_patch(name) / apply_custom_patch(...) / clear_patches(). Three patches in the bundled CATALOG authored from the v0.3.1 FFT residual analysis. v0.5.1 patch-shrinks-residual benchmark measured the catalog and showed partial vindication: J–S coupled patch shrinks both bodies' residuals by ~77% with phase-recovered authoring (research-side; stays out of the v0.5.x catalog until ≥80% on every body); Mars stays stuck at 3% due to FFT bin leakage. v0.5.2 adds windowed FFT + multi-bin patches for full predictive power.
• SPICE-free runtime (v0.5.0+): pip install works out of the box — both backends use codegen-baked initial phases shipped in _data/initial_phases.json. No SPICE kernel staging required for basic encoding. Skyfield + jplephem stay as optional [ephemeris] extras for callers who want runtime recalibration against custom kernels.
• Observer-Agnostic Views: Unitary binding to generate topocentric "Local View" hypervectors at any (lat, lon) on any body.
• Spectral Syzygy Window Search (v0.3.1+): find-syzygies --from-jd ... --to-jd ... enumerates candidate syzygies in closed form via the natural cyclic-group decomposition (synodic + draconic month), then confirms each by spectral projection. ~1000× faster than the v0.3.0 point-evaluation eclipse --jd pattern for window queries.
• ITN Pathway / Lagrange-Tube Query (v0.8.1+): find-tubes --from-jd ... --to-jd ... --departure terra --target mars enumerates Hohmann transfer windows via the same closed-form find-syzygies discipline. "Surfing the perturbations" — the natural cyclic structure tells you when launch windows open without integrating any trajectories. First-cut Hohmann math; future versions layer low-energy / heteroclinic-tube candidates under the same surface (transfer_kind field reserves room). References: Koon-Lo-Marsden-Ross 2011; Lo's Genesis trajectory work.
• Sol Symphony Times (v0.3.0 + v0.5.4 + v0.8.0 + v0.9.1): every body in the Sol Star System has a "Sol Time" exposing its rotational + orbital cycles anchored to a conventional epoch — Mars Sol Date / Mars Coordinated Time (Allison & McEwen 2000), Sol Lunar Time (Luna's synodic + sidereal phase observed from Terra), Sol Uranian Time (USD/SUT, anchored at the 2007 northern equinox), Sol Venus / Sol Mercury / Sol Pluto / Sol Terra / Sol Luna (rocky bodies + Sun + Luna in direct Latin proper-noun form), Sol Sol (the Sun, Carrington rotation system), Sol Jovian / Sol Saturnian / Sol Neptunian (gas/ice giants in established adjective form). The Solar System is a natural symphony of overlapping clocks; Sol Time is just the package telling you what time it is on each body so you can correlate that body's local clock with JD. Naming hierarchy for future moon ports: Sol <Parent>-<Body> Time (e.g., Sol Pluto-Charon Time).

Naming convention (v0.9.x)

The body-identity strings use Latin proper nouns: terra, luna. The generic English words earth (= soil, ground) and moon (= any natural satellite) return to their generic meanings.

"Returning to the giants whose shoulders we stand on. We've always had a lunar orbit and a lunar eclipse. We've all had terrain and terrestrial animals. We're just putting the books back in their dewey decimal spot. We no longer kow tow for the sake of leaning forward."

The adjective forms lunar, terran, terrestrial always derived from Luna and Terra — the language already carried the convention. v0.9.0 made the body-identity strings reflect what the language always implied. v0.9.1 extends this to the Sol Time series itself: rocky bodies + Sun + Luna use direct Latin proper nouns; gas/ice giants keep the established astronomical adjective forms (Jovian, Saturnian, Uranian, Neptunian).

Body	Sol Time	Abbrev	CLI
Mercury	Sol Mercury Time	SMeT	time-mercury
Venus	Sol Venus Time	SVT	time-venus
Terra	Sol Terra Time	STT	time-terra
Mars	Sol Mars Time (= MSD/MTC)	SMaT	time-mars
Luna	Sol Terra-Luna Time	STLT	time-terra-luna
Jupiter	Sol Jovian Time	SJT	time-jupiter
Saturn	Sol Saturnian Time	SST	time-saturn
Uranus	Sol Uranian Time	SUT	time-uranus
Neptune	Sol Neptunian Time	SNT	time-neptune
Pluto	Sol Pluto Time	SPT	time-pluto
Sol	Sol Sol Time	SSoT	time-sol

Moons follow the Sol <Parent>-<Body> Time convention — Luna's primary Sol Time is Sol Terra-Luna Time (STLT) because Luna is gravitationally bound to Terra; the Parent-Body name keeps the moon-stuck-to-parent relationship visible in the time hierarchy. STLT counts synodic months from a historically-significant epoch (default: Meton's 432 BCE summer solstice). The future Pluto-Charon, Jupiter-Io, Saturn-Titan, etc. moon Sol Times will follow the same Sol <Parent>-<Body> Time pattern — see task #86.

A separate, lower-level Sol Luna Time (SLT) also exists — Luna's tidally-locked surface clock (sidereal=orbital=27.32 d, solar=synodic=29.53 d) anchored at J2000. SLT is queryable via time-luna and bridge.jd_to_sol_luna_time; it's the right surface for "what time is it on Luna's prime meridian" rather than "how many synodic months since a Greek-historical event." The two are complementary, not redundant: STLT is anchored Lunar time (count); SLT is Luna's clock (rate).

Resolution Scaling

Temporal resolution of a residue shift scales inversely with hypervector dimension D:

D	Earth resolution	Use case
2^16	~8 minutes	default; long-term mapping
2^19	~1 minute	medium-cadence events
2^25	~1 second	high-cadence local readout

Installation

pip install ephemerides-spectral

For full ephemeris support (skyfield + JPL DE-kernels):

pip install "ephemerides-spectral[ephemeris]"

CLI Usage

The package ships a rich ephemerides-spectral console script. Use --help on the top-level or any sub-command:

ephemerides-spectral --help
ephemerides-spectral encode --help
ephemerides-spectral adaptive --help

Sub-command Cheat-Sheet

# Package version + frozen-data manifest
ephemerides-spectral version

# All 38 bodies in the Sol Star System Laplacian
ephemerides-spectral bodies

# Earth temporal resolution at the default D=65536
ephemerides-spectral resolution --body terra

# Encode J2000 with the integer ALU backend (default)
ephemerides-spectral encode --jd 2451545.0

# Same JD with the FPU complex128 reference encoder
ephemerides-spectral encode --jd 2451545.0 --backend complex128

# Topocentric view from London at J2000
ephemerides-spectral local-view --jd 2451545.0 --body terra --lat 51.5 --lon -0.1

# Syzygy alignment probability AT a JD (point evaluation; encode-then-check).
# For window queries, see `find-syzygies` below (closed-form spectral search,
# ~1000× faster than encode-then-check across long windows).
ephemerides-spectral eclipse --jd 2451545.0

# Off-diagonal couplings (Laplacian fiber bundle)
ephemerides-spectral couplings

# Phase 9 adaptive (a.k.a. "breathing") coupling modulation
# (Jupiter-Saturn 5:2 by default). Both `adaptive` and `breathing`
# work — `adaptive` is the canonical name (matches the adaptive-
# networks / adaptive-Kuramoto literature, Gross & Blasius 2008);
# `breathing` is the visual-metaphor synonym, kept for users who
# learned the couplings as inhaling/exhaling with the resonant phase.
ephemerides-spectral adaptive --jd 2458850.0

# Override resonance: 3:2 Neptune-Pluto
ephemerides-spectral adaptive --jd 2451545.0 \
    --pair-a neptune --pair-b pluto --n-a 3 --n-b 2

# Synonym (same handler, identical output):
ephemerides-spectral breathing --jd 2458850.0

# Mars Sol Date / Mars Coordinated Time at a JD (v0.3.0)
ephemerides-spectral time-mars --jd 2451549.5     # → MSD ≈ 44795.99
ephemerides-spectral time-mars --msd 50000        # invert: MSD → JD_UTC

# Mean lunar synodic + sidereal age/phase at a JD (v0.3.0)
ephemerides-spectral time-lunar --jd 2451545.0

# Sol Uranian Time (v0.5.4) — third planetary time system alongside Mars + Lunar
# USD (sidereal-day count since 2007 northern equinox), SUT (Uranian time-of-day),
# orbital phase + season, retrograde flag.
ephemerides-spectral time-uranus --jd 2454451.0   # → USD = 0.0 at SUT epoch
ephemerides-spectral time-uranus --usd 4046       # invert: USD → JD_TDB

# Sol Symphony Times (v0.8.0) — Venus, Mercury, Pluto, Sol (the Sun!),
# Jupiter, Saturn, Neptune each have their own "Sol Time" exposing rotational + orbital phase.
# Each handles its body's quirks: Mercury's 3:2 spin-orbit resonance, Venus's
# retrograde rotation (sidereal day > year!), Sol's differential rotation
# (Carrington system), Jupiter System III, Saturn Cassini-revised System III.
ephemerides-spectral time-venus --jd 2451545.0
ephemerides-spectral time-mercury --jd 2451545.0  # 3:2 resonance: solar day = 2 × year
ephemerides-spectral time-pluto --jd 2457217.0    # New Horizons closest approach
ephemerides-spectral time-sol --jd 2451545.0      # Sun's own Carrington Rotation Number
ephemerides-spectral time-jupiter --jd 2444000.5
ephemerides-spectral time-saturn --jd 2451545.0
ephemerides-spectral time-neptune --jd 2451545.0

# Sol Terra Time (v0.9.1) — Terra's surface clock
# Sidereal day 23h 56m 4s (rotation rel. stars), solar day 24h (rel. Sun)
ephemerides-spectral time-terra --jd 2451545.0    # J2000 anchor

# Sol Luna Time (v0.9.1) — Luna's surface clock
# Tidally locked: sidereal=orbital=27.32d, solar=synodic=29.53d
# DISTINCT from Sol Lunar Time (time-lunar) which gives Luna's phase observed from Terra
ephemerides-spectral time-luna --jd 2451545.0     # J2000 anchor

# ITN pathway / Lagrange-tube query (v0.8.1) — Hohmann transfer windows
# "surfing the perturbations" via closed-form synodic enumeration
ephemerides-spectral find-tubes --from-jd 2451545.0 --to-jd 2470000.0 \
    --departure terra --target mars
# Output: 23 Terra->Mars windows over ~50 years, each with transfer time
# (~258.9 days) + total Δv (~5.59 km/s)

# Lunar-time kernel metadata (LTE440 + LTC status; v0.3.0)
ephemerides-spectral lunar-kernels

# Resonance-derived natural cyclic group (v0.3.0; expanded to Z_60 in v0.5.0)
ephemerides-spectral natural-group     # → Z_60 = Z_4 × Z_3 × Z_5

# Spectral-native syzygy window search (v0.3.1+)
# Replaces the v0.3.0 point-evaluation `eclipse --jd` for window queries.
# ~1000× faster than encode-then-check; uses the closed-form Saros /
# Metonic / synodic / draconic-month enumeration.
ephemerides-spectral find-syzygies --from-jd 2460311 --to-jd 2460676

# Diagnosed-fiber runtime kernel patching (v0.4.0+)
# Patches sit beside the published kernel as DATA, not code edits, and
# contribute per-body residue deltas at encode time. The kernel's
# published bytes never change. Bundled catalog (11 patches as of v0.5.5):
#   v0.4.0 originals (3): mars-7.96yr-diagonal, mercury-10.69yr-diagonal,
#                         jupiter-saturn-9.56yr-coupled
#   v0.5.2 LS-fit recovered (3, planets ≥96% shrinkage): same names with -v2 suffix
#   v0.5.5 LS-fit moons (5, ≥93% shrinkage): dione/tethys/enceladus/titan/iapetus -v2
ephemerides-spectral patches catalog
ephemerides-spectral patches apply --name jupiter-saturn-9.56yr-coupled-v2
ephemerides-spectral patches active
ephemerides-spectral patches clear

All sub-commands emit JSON to stdout; pass --no-pretty (top-level flag, before the sub-command) for compact single-line output suitable for piping into jq or downstream tooling. Every response carries an ok field; ok: false returns exit code 1 with an error message.

Python API

from ephemerides_spectral import default_encode, bridge

# One-liner: encode a JD as a system state under the default backend.
state = default_encode(jd=2451545.0)            # uint32[52] residues (BIP)
state = default_encode(jd=2451545.0, backend="complex128")  # complex128[D]

# JSON-friendly bridge surface (Pyodide / web frontend)
bridge.get_version()                             # version + manifest
bridge.list_bodies()                             # 52-body roster (v0.16.0+)
bridge.get_resolution(body="mars", D=65536)      # sec/residue
bridge.get_system_state(jd_tdb=2451545.0)        # encode + per-body residues
bridge.get_local_view(jd_tdb=2451545.0, body="terra", lat=51.5, lon=-0.1)
bridge.get_eclipse_probability(jd_tdb=2451545.0)
bridge.list_couplings()                          # Laplacian fibers
bridge.find_itn_pathways(2451545.0, 2470000.0,
                         departure="terra", target="mars")  # v0.8.1 single-leg Hohmann
bridge.find_itn_chains(2451545.0, 2470000.0,
                       departure="terra", target="jupiter",
                       intermediates=["venus", "mars"])     # v0.17.0 multi-leg ITN
bridge.body_architecture(target="terra")          # v0.18.0 inner/outer Fiedler partition
bridge.predict_itn_accessibility(departure="terra",
                                 target="jupiter") # v0.18.1 spectral Δv estimate
bridge.get_breathing_modulation(jd_tdb=2451545.0)  # Phase 9 LUT inspector

# v0.3.0 surface
bridge.jd_to_mars_time(jd_utc=2451549.5)         # MSD + MTC (Allison & McEwen 2000)
bridge.mars_time_to_jd(msd=50000)                # MSD → JD_UTC inverse
bridge.get_lunar_phase(jd_tdb=2451545.0)         # mean synodic + sidereal phase
bridge.list_lunar_kernels()                      # LTE440 metadata + LTC status
bridge.get_natural_resonance_group()             # Z_60 = Z_4 × Z_3 × Z_5 (v0.5.0+)

# v0.4.0 surface — runtime kernel patching (overlay on the spectral kernel)
# Catalog grows over time; v0.6.1 ships 11 entries:
#   v0.4.0 originals (3): mars/mercury/jupiter-saturn at FFT-magnitude amplitudes
#   v0.5.2 LS-fit recovered (3, planets at ≥96% shrinkage): -v2 suffix
#   v0.5.5 LS-fit moons (5, ≥93% shrinkage): dione/tethys/enceladus/titan/iapetus -v2
bridge.list_catalog_patches()                    # bundled CATALOG (11 patches)
bridge.apply_patch("jupiter-saturn-9.56yr-coupled-v2")  # vindicated v0.5.2 entry
bridge.apply_custom_patch(name="my-patch", kind="sinusoid",
                          body="terra", amplitude_deg=0.93,
                          period_days=1940.2)    # FFT-diagnosed custom patch
bridge.list_active_patches()                     # what's currently overlaid
bridge.clear_patches()                           # wipe back to byte-exact baseline

# v0.5.4 surface — Sol Uranian Time
bridge.jd_to_sol_uranian_time(jd_tdb=2454451.0)  # USD + SUT + season + retrograde
bridge.sol_uranian_time_to_jd(usd=4046.0)        # USD → JD_TDB inverse

# v0.6.0 Tier 1 parity surface — both methods accept backend={"auto","bip","c"}
bridge.find_syzygies(jd_lo=2451545.0, jd_hi=2451545.0+365.25, backend="c")
bridge.get_breathing_modulation(jd_tdb=2451545.0, pair=("jupiter","saturn"),
                                n_lobes=(5, 2), backend="c")

Every bridge method returns a Pyodide-JSON-serialisable dict with ok: True/False. Caller-side errors return {ok: False, error: "..."} rather than raising — designed for crossing the Python/JS boundary cleanly.

Performance & Footprint

ephemerides-spectral is designed for high-performance galactic mapping on edge devices where large SPICE kernels (the 3.3 GB DE441) are prohibitive.

Memory Footprint

Component	Format	RAM / Flash	Description
State (BIP)	uint32[D]	256 KB	At D=65536; pure cyclic-group residues.
State (complex128)	complex128	1.0 MB	At D=65536; FPU reference encoder.
Channel Bases	mixed	~52 MB	Full 52-body roster (v0.16.0+); pageable from Flash.
Laplacian (L)	complex128	< 45 KB	52 × 52 interaction matrix.
Cosine LUT (Phase 9)	int32[1024]	4 KB	Off-diagonal adaptive ("breathing") modulation.
DE441 Truth	BSP	3,300 MB	Original JPL source (calibration only).

Compression vs DE441: > 100:1. Once calibrated, the HDC instrument functions as standalone algebraic truth — no kernel needed for propagation, local-view extraction, or syzygy detection.

Microcontroller Compatibility

The BIP backend is the natural production target for embedded use:

• ESP32-S3 / ESP32-C6 (8 MB+ PSRAM): full 52-body BIP state in PSRAM, microsecond-latency phase updates via uint32 adds.
• ARM Cortex-M7 (Teensy 4.1, etc.): integer multiply-accumulate suits the omega * delta_t step path natively; cosine LUT fits in tightly-coupled memory.
• RISC-V / Edge AI accelerators: (φ_1 + φ_2) mod 2^32 is a single uint32 add — directly mappable to vector-extension lanes.

Instead of searching 3.3 GB of Chebyshev coefficients, these devices evolve the entire Sol Star System phase-space using integer additions and a 4 KB cosine table.

Honest accuracy: DE441 full-epoch sweep (v0.3.0)

research/de441_sweep.py runs the BIP integer-ALU encoder at 15 sample points spanning J2000 ± 14,000 yr (just inside DE441's ~30,000-yr coverage window) and compares per-body ecliptic-longitude residues against DE441 ground truth. Results — sorted by max error, descending:

Body	n	median (rad)	p95 (rad)	max (rad)	max (deg)
jupiter	15	1.357	2.937	3.070	175.92
saturn	15	1.415	2.990	3.062	175.46
neptune	15	0.691	2.748	2.778	159.18
pluto	15	0.791	2.524	2.721	155.92
moon	15	1.084	2.559	2.670	153.00
mercury	15	0.356	1.444	1.461	83.74
mars	15	0.117	0.250	0.253	14.52
uranus	15	0.047	0.120	0.141	8.06
venus	15	0.024	0.114	0.124	7.11
earth	15	0.011	0.104	0.115	6.59

Earth phase error scales roughly linearly with horizon:

Δt (yr)	Earth err (deg)
0	0.000
±1	0.001–0.004
±10	0.006–0.008
±100	0.065–0.069
±1000	0.65–0.68
±5000	2.93–3.31
±10000	4.70–5.71
±14000	5.48–6.59

Three regimes, honestly named

• Sub-10° at multi-millennium horizons (Earth, Venus, Uranus): bodies whose mean motion + small eccentricity + the static gravitational fiber couplings approximate the actual orbit well. Earth benefits from being the calibration body for Mercury's PN diagonal.
• Tens of degrees (Mars 14.5°, Mercury 83.7°): dynamics include eccentricity + long-period perturbations the Phase-9 model captures only partially. Mars has no resonance entry; Mercury's PN diagonal is linear whereas its actual perihelion precession at multi-millennium scales has higher-order terms.
• Phase-scrambled (Jupiter, Saturn, Neptune, Pluto, Moon all hit >150°): bodies whose secular drift is dominated by resonant perturbations the Phase-9 model approximates phenomenologically. The α = 0.1 modulation depth is the right order of magnitude but wrong-in-detail; over ±14,000 yr that wrong-detail accumulates to a ~3 rad phase deficit.

This measures how much of multi-millennium ephemeris our v0.3.0 model captures, not how accurate the BIP encoder is at its design horizon. v0.3.0 is calibrated for the ±20-yr horizon (0.0002 rad ≈ 0.012° Earth phase floor); the multi-millennium errors are the cost of running a model trained for short-horizon dynamics far past its design point. The v0.4+ first-principles per-resonance α derivation is the planned fix — see ROADMAP.

Encoding timings (BIP integer-ALU path, default D = 65536)

Δt (yr)	encode wall time
0	0.2 ms
±1	0.7–1.3 ms
±10	4.2–6.8 ms
±100	44.7–45.8 ms
±1000	447–483 ms
±5000	2.38–2.44 s
±10000	4.34–4.44 s
±14000	6.18–6.37 s

Linear in |Δt| — one 30-day chunk per integration step. At the v0.1.0 design horizon (±20 yr, ~243 chunks) the encode is ~1.85 ms; at ±14,000 yr (~170k chunks) it's ~6.4 s. Median across the sweep: 447 ms; max: 6.4 s.

v0.4.1+ C native path drops these by ~1000× (encode at +20 yr: 46 ms BIP → 0.04 ms C). The full DE441 FFT-residual sweep (1024 samples) takes ~14 seconds on the C native path versus ~5 minutes on Python BIP — the truth-lookup against skyfield is the new bottleneck.

Patch-shrinks-residual benchmark — VINDICATED on planets (v0.5.2)

Earn the right to predict the missing data. — measured.

The v0.4.0 catalog patches claimed to predict missing physics; v0.5.1 audited them and surfaced two authoring bugs (amplitude off by 2×, phase=0 assumption wrong); v0.5.2 fixed both with least-squares fitting at the exact target period. Result: VINDICATED on every targeted planet body.

Patch	v0.4.0 (mag-only)	v0.5.1 (phase-recovered)	v0.5.2 (LS-fit)
Mars 7.96 yr	+2.5%	+2.7%	+99.2%
Mercury 10.69 yr	−49.9% (peak GREW)	+39.6%	+99.9%
Jupiter 9.56 yr	+30.9%	+77.1%	+97.6%
Saturn 9.56 yr	−0.4%	+76.4%	+96.0%

The vindicated patches ship as CATALOG_V2 alongside the original v0.4.0 CATALOG. Use the -v2 suffix:

bridge.apply_patch("mars-7.96yr-diagonal-v2")              # 99.2% shrinkage
bridge.apply_patch("mercury-10.69yr-diagonal-v2")          # 99.9%
bridge.apply_patch("jupiter-saturn-9.56yr-coupled-v2")     # 97.6% J / 96.0% S

Empirical findings worth noting:

• J–S correlation = +1 (in-phase), not −1 as v0.4.0 assumed. Anti-correlated-libration intuition was empirically wrong.
• LS-fit amplitudes are 25–55% larger than FFT-bin extraction — the energy that was leaking into adjacent bins.
• Mars's true residual amplitude is 10.69° (LS) vs 3.45° (FFT-bin rank-1) — a 3× underestimate, the worst leakage case in the catalog.

See the v0.5.2 patch-shrinks-residual analysis on the project docs for the full math derivation, methodology, and moon-residual open question.

Status

See the project CHANGELOG and package CHANGELOG for the authoritative version-by-version detail. Headline summary:

• v0.24.3 (current) — Sun Dynamical Spectrum (helioseismology) — fourth per-body dynamical-spectrum surface in v0.24.x; first stellar entry + methodology extension from rigid-body action-angle (Mercury / Luna / Mars) to stellar-oscillation continuum normal-mode spectrum. Where v0.24.0–v0.24.2 decomposed each body's dynamical state into ~10 angle/action modes, v0.24.3 ships the helioseismic asymptotic relation as a closure invariant analogous to Luna's Saros commensurability. Headlines: Δν = 135.1 μHz (large frequency separation between consecutive radial orders n at fixed l; sound-travel-time inverse; ∝ √(M/R³); the asteroseismic-anchor pair with ν_max), δν = 9.0 μHz (small separation between l=0 and l=2 modes; sensitive to the deep-interior sound-speed gradient + helium-core composition), ν_max = 3090 ± 30 μHz (peak amplitude frequency; predicted by Brown 1991 to scale as g/√T_eff and validated extensively across asteroseismic targets). 20-mode sample p-mode catalog (n=18-25 at l=0-2; the high-SNR comb near ν_max). THE HEADLINE PAYLOAD is the Tassoul 1980 asymptotic-relation closure invariant: the relation ν_{n,l} ≈ Δν · (n + l/2 + ε) - δν · l(l+1) / (n + l/2 + ε) predicts the entire continuum mode spectrum from just three constants (Δν, δν, ε ≈ 1.46). Catalog ships asymptotic-consistent reference values (residuals < 0.5 μHz from float roundoff); real BiSON / SOI-MDI / SDO-HMI data has ~0.1-1 μHz residuals from interior-structure "glitches" (helium-ionization zone + base of convection zone — Vorontsov 2002), which are themselves diagnostic of internal structure via the Christensen-Dalsgaard 2002 inversion methodology. The closure invariant is pinned by test_asymptotic_relation_closure_invariant. Cross-channel parallel: this is the stellar-oscillation analogue of v0.24.1's Saros integer-commensurability — three constants → entire mode spectrum, just like 223:239:242 integer triple → entire eclipse-recurrence cycle. The Sun is the only star where individual modes are resolvable to high SNR via spatially-resolved Doppler imaging (BiSON sub-mHz; GOLF/SoHO global modes; SDO-HMI mid-degree). Three new bridge surfaces: bridge.get_sun_dynamical_spectrum() / bridge.get_helioseismic_asymptotic_relation() / bridge.list_sun_dynamical_spectrum(). Three new CLI subcommands: sun-dynamical-spectrum, helioseismic-asymptotic-relation, sun-dynamical-spectrum-full. 8-entry SOURCES citation dict (Davies 2014 BiSON, Schou 1998 SOI/MDI, Christensen-Dalsgaard 2002 review, Tassoul 1980 asymptotic theory, Brown 1991 ν_max scaling, Aerts/Christensen-Dalsgaard/Kurtz 2010 textbook, IAU 2015 Resolution B3 nominal solar constants, Libbrecht-Woodard 1990 solar-cycle frequency modulation). Cross-references v0.20.1 (Sol synoptic magnetic field), v0.21.5 (Earth-Sun IMF coupling). Pure-Python additive; no ABI bump (twenty-sixth consecutive ship since v0.13.x; ES_ABI_VERSION = 8 unchanged). New tests/test_sun_dynamical_spectrum.py (30 tests).
• v0.24.2 — Mars Dynamical Spectrum (chaotic obliquity) — third per-body dynamical-spectrum surface in v0.24.x; the contrast case to Mercury (clean Le Verrier closure) and Luna (clean Saros commensurability). Mars exhibits secular chaos: where Mercury and Luna admit closed-form spectral fingerprints, Mars's dynamical spectrum is the canonical observable signature in our Solar System of KAM-theory small-denominator failure — the regime where the action-angle quasi-periodic torus structure breaks down. 8-mode action-angle catalog (5 angles + 3 actions): orbital mean motion (sidereal year 686.97 d); spin frequency (sol 24.6229 h — NOT in spin-orbit resonance, unlike Mercury / Luna / Galileans / Titan / Pluto-Charon); spin-axis precession ~171 kyr (Ward 1973); apsidal precession g₄ ~71.6 kyr; nodal precession s₄ ~70 kyr; eccentricity 0.0934 (varies 0.005-0.119 over secular cycle); inclination 1.85°; obliquity 25.19° present-day, with Gyr excursion 0°-60° (Laskar et al. 2004) — mean ~37.6°. C/MR² = 0.3645 ± 0.0005 (Le Maistre 2023 InSight RISE measurement). THE HEADLINE PAYLOAD is the secular-resonance overlap chaos invariant: Mars's spin-axis precession frequency (~7.58 arcsec/yr) overlaps with the inner-Solar-System secular orbital fundamentals s₃ (~−18.86 arcsec/yr; Earth-related) and s₄ (~−17.74 arcsec/yr; Mars-related) — the proximity of these frequencies drives the action-angle torus structure to break down on Gyr timescales, producing chaos. Where Mercury's v0.24.0 closure was a successful sum (Newtonian + GR + J₂ ≈ observed within ±1 arcsec/century) and Luna's v0.24.1 closure was a successful integer commensurability (223:239:242 within < 1 day), Mars's v0.24.2 "closure" is a failure mode: the secular frequencies overlap so tightly that quasi-periodic dynamics break down. The chaos invariant is pinned by test_chaos_active_via_min_proximity (min frequency proximity < 12 arcsec/yr threshold per Laskar 1993). Cross-channel observation: without Earth's stabilising Moon (v0.24.1 LLR-constrained), Earth's obliquity would be subject to similar chaos. The Moon's tidal-stabilisation role is therefore load-bearing for long-term Earth climate predictability — a direct cross-strand observation linking v0.24.1 (Luna) and v0.24.2 (Mars) into a coherent argument about why Earth has stable seasons. Three new bridge surfaces: bridge.get_mars_dynamical_spectrum() / bridge.get_mars_secular_resonance_overlap() / bridge.list_mars_dynamical_spectrum(). Three new CLI subcommands: mars-dynamical-spectrum, mars-secular-resonance-overlap, mars-dynamical-spectrum-full. 7-entry SOURCES citation dict (JPL DE441, Le Maistre 2023, Ward 1973, Laskar-Robutel 1993, Laskar 2004, Laskar 2008, Touma-Wisdom 1993). Cross-references v0.20.0 (Mars geodetic), v0.21.4 (Le Maistre 2023 chain — same paper), v0.20.2 (Mars climate-orbit coupling). Pure-Python additive; no ABI bump (twenty-fifth consecutive ship since v0.13.x; ES_ABI_VERSION = 8 unchanged). New tests/test_mars_dynamical_spectrum.py (33 tests).
• v0.24.1 — Luna Dynamical Spectrum — second per-body dynamical-spectrum surface in the v0.24.x sequence, mirroring v0.24.0 Mercury structure with body-appropriate cross-channel headline. Luna chosen as the natural complement to Mercury: same simple-target pattern (no atmosphere, no ocean) but the canonical Earth-tidal case (Mercury was canonical Sol-perturbation). Lunar Laser Ranging is the ground-truth source — 50+ years of millimetre-precision ranging from McDonald (1969), Apache Point (2006), OCA Grasse, and Matera observatories — providing the cleanest observational constraint on a planetary body's full dynamical spectrum. 11-mode action-angle catalog (8 angles + 3 actions): four distinct "months" (sidereal 27.32166 d / synodic 29.53059 d / anomalistic 27.55455 d / draconitic 27.21222 d — they differ because perigee precesses prograde 8.85 yr and nodes regress retrograde 18.61 yr); spin frequency locked 1:1 with sidereal motion (cross-references v0.23.0); forced libration in longitude 7.9 arcsec amplitude (Williams 2014 LLR — most precise libration measurement in Solar System; constrains C/MR² = 0.3932 ± 0.0002); apsidal + nodal precession; eccentricity 0.0549 (varies 0.026-0.077 over decades); inclination 5.145°; obliquity to orbit 6.687° in Cassini state 2 (substantially larger than Mercury's Cassini-state-1 0.034° — different equilibrium branch). THE HEADLINE CLOSURE INVARIANT: the Saros cycle integer commensurability. Luna's three distinct months admit an exact small-integer commensurability: 223 × synodic = 6585.32 d ≈ 239 × anomalistic = 6585.54 d ≈ 242 × draconitic = 6585.36 d ≈ 19 × eclipse-year = 6585.78 d — all four products agree within ~0.5 day at the famous 18.03-yr Saros eclipse-recurrence cycle. This is a textbook small-denominator phenomenon and exactly the structure the project's BIP encoder is built to detect: three irrational-looking frequency ratios sharing a near-rational commensurability. The Saros closure is pinned by test_saros_closure_invariant (max spread < 1 day). Cross-strand observation: the Antikythera mechanism's Saros dial is literally a hardware implementation of this commensurability — making this v0.24.1 bridge surface a direct cross-link between ephemerides-spectral and antikythera-spectral. Same integer triple, different evidentiary layers (one in 21st-century LLR; one in ca. 150 BCE bronze gearing). Three new bridge surfaces: bridge.get_luna_dynamical_spectrum() / bridge.get_luna_saros_commensurability() / bridge.list_luna_dynamical_spectrum(). Three new CLI subcommands: luna-dynamical-spectrum, luna-saros-commensurability, luna-dynamical-spectrum-full. 6-entry SOURCES citation dict (Allen's Astrophysical Quantities, JPL DE441, Williams 2014, Murray-Dermott 1999, Cassini 1693 / Colombo 1966 / Peale 1969, Meeus 1991); ratchet tests pin both directions. Bundled with RTD doc-maintenance fix: the addressing-maths-as-separate-repo paragraph on the RTD landing page (docs/index.md) and the corresponding mkdocs.yml site_description were stale — addressing-maths content was subsumed into the chess-spectral and antikythera-spectral notebooks; both files updated to reflect that. Pure-Python additive; no ABI bump (twenty-fourth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). New tests/test_luna_dynamical_spectrum.py (37 tests).
• v0.24.0 — Mercury Dynamical Spectrum — the first per-body dynamical-spectrum surface in the project; opens the v0.24.x discipline pivot from cross-channel-coupling (v0.21.x decomposing between two channels) to action-angle decomposition of a single body's full dynamical state. Mercury chosen as cleanest first target: no moon, no atmosphere, no ocean, smallest in the planetary roster, in the historically richest dynamical-test position (Le Verrier 1859 → Newcomb 1882 → Einstein 1915 → Clemence 1947 → Margot 2007 → Park 2017 lineage). Action-angle decomposition factors Mercury's dynamical state on a T^n × R^m phase space: 5 angle modes (live on tori — orbital mean motion 415.20 cycles/century, spin frequency 622.80 cycles/century locked at exactly 3:2, forced libration at orbital frequency with 35.8 arcsec amplitude, perihelion-longitude precession at 574.10 arcsec/century, ascending-node precession at -446.30 arcsec/century retrograde) plus 3 action modes (live on real intervals — eccentricity 0.2056, inclination 7.005°, obliquity 2.04 arcmin). THE headline payload is the perihelion-precession contribution-by-perturber decomposition — the famous Le Verrier / Einstein test of GR. Total observed 574.10 ± 0.65 arcsec/century (Clemence 1947) decomposes as Newtonian planetary perturbations (Venus 277.42 + Jupiter 153.58 + Earth 90.04 + Saturn 7.30 + Mars/other 3.29 = 531.63) + general-relativistic Schwarzschild correction (42.98 — Einstein 1915 prediction; Park 2017 MESSENGER measurement confirms to 1 part in 10^4) + solar quadrupole J₂ (0.025 — Park 2017 from MESSENGER orbit fit). Sum closes to 574.6 — within Clemence's ±0.65 uncertainty. This Le Verrier/Einstein closure invariant is pinned by test_le_verrier_einstein_closure_invariant. Cross-channel observation: every contribution is from a neighbouring field (a planetary perturbation, a spacetime-geometry term, or a solar-shape term) — the decomposition is the spectral fingerprint of how Mercury's orbit responds to the rest of the Solar System's fields. Cross-references v0.20.0 + v0.21.4 + v0.23.0 (Mercury 3:2 spin-orbit lock + 35.8 arcsec libration → C/MR² = 0.346 ± 0.014 → molten core; Margot 2007). Three new bridge surfaces: bridge.get_mercury_dynamical_spectrum() (8-mode action-angle catalog) / bridge.get_mercury_precession_decomposition() (8-row Le Verrier/Einstein decomposition with closure-invariant residual) / bridge.list_mercury_dynamical_spectrum() (full enumeration). Three new CLI subcommands: mercury-dynamical-spectrum, mercury-precession-decomposition, mercury-dynamical-spectrum-full. 8-entry SOURCES citation dict (JPL DE441, Margot 2007, Clemence 1947, Einstein 1915, Verma 2014, Park 2017, Murray-Dermott 1999, Laskar 1989); ratchet tests pin both directions. Pure-Python additive; no ABI bump (twenty-third consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). New tests/test_mercury_dynamical_spectrum.py (31 tests). 1372 tests pass, 42 skipped (was 1338 + 42 in v0.23.x; +34 net new — 31 in test_mercury_dynamical_spectrum.py + 2 README-freshness tests that flipped GREEN + 1 reconciliation).
• v0.23.1 — Packaging fix: pyproject.toml description trimmed from 593 → 473 chars to stay under PyPI's hard 512-character Summary metadata limit. Both v0.22.0 and v0.23.0 PyPI publishes had silently failed at the upload step because of this (the upload endpoint rejects oversize metadata with a "could not comply" error that doesn't bubble useful detail into pypa/gh-action-pypi-publish's logs; twine check --strict does NOT catch it). Stripped non-ASCII arrows for portability. Added a Verify description ≤ 512 chars CI guard to the publish workflow that hard-fails at the limit + soft-warns at 480 chars + soft-warns on non-ASCII — so future descriptions can't silently exceed the limit. PyPI migration: pip install -U ephemerides-spectral jumps from 0.21.10 directly to 0.23.1, picking up all v0.22.0 trajectory + sensing surfaces and all v0.23.0 spin-orbit-resonance surfaces. Pure-additive metadata + workflow fix; no ABI bump (twenty-second consecutive ship since v0.13.x); 1338 tests pass, 42 skipped (unchanged from v0.23.0).
• v0.23.0 — Spin-orbit resonance ↔ rotation lock — the eleventh cross-channel coupling surface, resumed after the v0.22.0 trajectory + sensing discipline pivot. Closes the tidal-physics triple with v0.21.4 (rotational Q-factor / dissipation efficiency) + v0.21.6 (orbital migration / secular drift). The end-state of long-term tidal evolution is the spin-orbit resonance lock the body settles into; v0.21.4 measures the dissipation rate, v0.21.6 measures the secular drift, and v0.23.0 measures the resulting equilibrium. 8-body roster: mercury (Margot 2007 — THE 3:2 spin-orbit resonance, the only non-1:1 case in the Solar System; discovered by Pettengill & Dyce 1965 Arecibo radar; explained by Colombo 1965 + Goldreich-Peale 1966 as a stable equilibrium driven by Mercury's high orbital eccentricity e=0.206; ~36 arcsec libration amplitude); luna (Williams & Boggs 2014 LLR — 1:1 with ~7.9 arcsec physical libration, the most precisely-measured libration in the Solar System; cross-references v0.21.4 Mathews 2002 FCN + v0.21.6 Williams 2014 +3.83 cm/yr outward); io / europa / ganymede (Lainey 2009/2020, Van Hoolst 2008 — Galilean Laplace 1:2:4 resonance members, all 1:1 tidal-locked; Europa libration is itself a constraint on subsurface ocean depth — the ice-shell decoupling from interior amplifies forced libration); titan (Iess 2012 / Stiles 2008 / Meriggiola 2016 — 1:1 with anomalously large ~52 arcsec libration, attributed to icy outer shell decoupled from interior by subsurface H₂O ocean — the libration itself diagnoses the ocean; cross-references v0.21.6 Lainey 2020 +11 cm/yr); triton (Jacobson 2009 — 1:1 retrograde tidal lock from KBO-capture origin; cross-references v0.21.6 -0.5 cm/yr Roche-deadline); charon (McKinnon 2017 — Pluto-Charon DUAL-SYNCHRONOUS, the unique solar-system case where both bodies are tidally locked to each other; mass ratio 0.12 puts barycentre outside Pluto, making it a true binary planet; cross-references v0.21.6 zero-migration tidal end-state). Period-consistency invariant pinned: for every entry, T_rot/T_orb ≈ q/p (rotations per orbit) within ±1%. Mercury-only-non-1:1 invariant pinned. Two new bridge surfaces: bridge.get_spin_orbit_resonance(body=None) / bridge.list_spin_orbit_resonances(). Two new CLI subcommands: spin-orbit-resonance, spin-orbit-resonances. 8-entry SOURCES citation dict (Margot 2007, Williams 2014, Lainey 2009, Van Hoolst 2008, Lainey 2020, Iess 2012, Jacobson 2009, McKinnon 2017); ratchet tests pin both directions. Pure-Python additive; no ABI bump (twenty-first consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). New tests/test_spin_orbit_resonance.py (30 tests). 1338 tests pass, 42 skipped (was 1306 + 42 in v0.22.0; +32 net new — 30 in test_spin_orbit_resonance.py + 2 README-freshness tests that flipped GREEN).
• v0.22.0 — Trajectory + Sensing Layer — a discipline pivot out of the v0.21.x cross-channel-coupling sequence into applied-physics propagators. Four new bridge surfaces in a clean four-layer stack: Layer A (bridge.compute_ballistic_trajectory / get_ballistic_atmosphere / list_ballistic_atmospheres) — per-body short-range ballistic propagator with optional exponential-atmosphere drag (BC = m/(C_d·A) parameterization); 7-body roster (terra, mars, venus, titan, luna, mercury, jupiter); vacuum case is the textbook closed form (Vallado §8.6.2 — range = v²·sin(2θ)/g, apex = v²·sin²(θ)/(2g), T = 2v·sin(θ)/g) and matches to numerical precision. Layer B (bridge.compute_icbm_trajectory / get_icbm_reference_profile / list_icbm_reference_profiles) — Earth 3-regime ICBM trajectory with boost as a boundary condition (user supplies burnout state v, γ, h), midcourse Kepler-ellipse propagation (Bate-Mueller-White Ch. 6), and Allen-Eggers closed-form re-entry (NACA Report 1381, 1958); 3 reference profiles (SRBM 300 km, MRBM 1500 km, ICBM 10000 km) from Wilkening 2000 + Sessler/UCS 2000. Boost is intentionally not modelled — vehicle-specific Isp/thrust/gravity-turn cross into operationally-sensitive territory; publishable Layer B starts from burnout state. Layer C(a) (bridge.compute_visibility_geometry / compute_sgp4_state / get_orbital_reference / list_orbital_references) — sensor-access geometry: WGS-84 geodetic-to-ECEF + ECEF-to-ENU + slant-range/elevation/azimuth + Earth-limb occlusion (Vallado Ch. 11); SGP4 propagation via Brandon Rhodes' sgp4 package (transitive optional dep through [ephemeris]); 8 reference TLEs spanning canonical orbit classes (ISS, Sentinel-1A, NOAA-20/JPSS-1, IRIDIUM-NEXT, GOES-16, Molniya, Tundra, Landsat-9 — textbook reference TLEs only; fetch fresh from CelesTrak / Space-Track for operational use); IR transmission windows (VIS / NIR / MWIR 3-5 µm / LWIR 8-12 µm). Layer C(b) (bridge.compute_bc_differential / compute_discrimination_altitude / get_bc_reference_class / list_bc_reference_classes) — the only physics-based midcourse-surviving discriminator: ballistic-coefficient differential velocity separation in the upper atmospheric drag tail (60-100 km), reference Sessler/UCS Countermeasures 2000. Heavy compact RV (BC ~10000 kg/m²) decelerates slowly while light decoys (BC ~50 kg/m²) decelerate rapidly; 4 reference BC classes (heavy_rv, light_rv, replica_decoy, chaff_decoy). The trauma-informed framing: this is defensive-preparedness physics, not a targeting tool. The publishability line: textbook physics + public TLEs + textbook geometry → catalog ✓; specific RV signatures, sensor NEΔT, kill-vehicle parameters, threat-library specifics → out of scope. 14 new bridge surfaces; 14 new CLI subcommands (ballistic-trajectory, ballistic-atmosphere, ballistic-atmospheres, icbm-trajectory, icbm-reference-profile, icbm-reference-profiles, visibility-geometry, sgp4-state, orbital-reference, orbital-references, bc-differential, discrimination-altitude, bc-reference-class, bc-reference-classes); 8 research modules; 23 citations spanning Vallado, Bate-Mueller-White, Curtis, Tewari, Allen-Eggers, Regan-Anandakrishnan, Sessler/UCS, Wilkening, Postol, US Standard Atmosphere 1976, VIRA, Cassini-Huygens HASI, Galileo Probe, NASA Planetary Fact Sheet, CelesTrak, ESA Sentinel, NOAA JPSS / GOES, USGS Landsat, HITRAN, WGS-84. Pure-Python additive; no ABI bump (twentieth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). New tests/test_ballistic_trajectory.py (29 tests), test_icbm_trajectory.py (24 tests), test_sensor_access.py (24 tests), test_decoy_discrimination.py (26 tests). 1306 tests pass, 42 skipped (was 1190 + 41 in v0.21.10; +103 net new + 14 new parity-smoke entries — one tier2_skip via optional sgp4 dep).
• v0.21.10 — Heliocentric flux ↔ surface temperature — the tenth cross-channel coupling surface, seventh in the post-trio sequence. The Stefan-Boltzmann radiative-equilibrium temperature T_eq = ((1 - A) * S / (4σ))^(1/4) (with S the solar flux at the body and A the Bond albedo from v0.20.2) decomposes the observed surface temperature (v0.20.2) into greenhouse + tidal + internal-heat contributions. Cross-channel reach: connects v0.20.2 climatology (T_obs, Bond albedo) + v0.21.8 heat flow + v0.21.9 outgassing into a unified energy-budget picture; the decomposition is independently verified by the heat-flow budget. 6-body roster: terra (Kiehl 1997 — T_eq=254.6 K, T_obs=288.15 K, +33.5 K greenhouse from H₂O+CO₂; the canonical textbook decomposition); mars (Haberle 2013 — T_eq=210 K, T_obs=210 K; only ~5 K greenhouse because 636-Pa CO₂ atmosphere is too thin; the famous "naked planet" case); venus (Bullock 2001 — T_eq=231.8 K, T_obs=737 K, +505 K runaway greenhouse; surface hotter than Mercury despite being further from Sun; the headline case in the catalog); mercury (Hapke 1981 — T_eq=437 K dayside, T_obs=440 K, no atmosphere → pure Stefan-Boltzmann radiative balance with all three offsets exactly zero; Bond albedo only 0.088 because Mercury surface is dark); titan (Strobel 2009 — T_eq=83 K, T_obs=94 K, +11 K split between +9 K CH₄/N₂ greenhouse + 2 K Saturnian tidal heating; cross-references v0.21.8 Titan 2 TW internal heat); jupiter (Hubbard 1999 — T_eq=110 K, T_obs=165 K @ 1-bar reference, +45 K internal-heat-dominated because Jupiter radiates 1.7× more heat than it absorbs from Sun; primordial cooling + helium-rain drainage; cross-references v0.21.8 Jupiter heat flow + v0.20.2 1-bar atmosphere convention). Decomposition consistency invariant: for every body, T_obs - T_eq ≈ greenhouse_offset + tidal_offset + internal_heat_offset (within ~5 K rounding tolerance); pinned by test_observed_minus_equilibrium_consistent. Two new bridge surfaces: bridge.get_thermal_balance(body=None) / bridge.list_thermal_balances(). Two new CLI subcommands: thermal-balance, thermal-balances. 6-entry SOURCES citation dict (Kiehl 1997, Haberle 2013, Bullock 2001, Hapke 1981, Strobel 2009, Hubbard 1999); ratchet tests pin both directions. Pure-Python additive; no ABI bump (nineteenth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). New tests/test_thermal_balance.py (28 tests). 1190 tests pass, 41 skipped (was 1163 + 41 in v0.21.9; +27 net new — 27 in test_thermal_balance.py).
• v0.21.9 — Volcanic outgassing ↔ atmospheric composition — the ninth cross-channel coupling surface, sixth in the post-trio sequence. Forms the supply-side of the atmospheric mass-balance equation, with v0.21.7 atmospheric escape as the demand-side. v0.21.8 heat flow provides the energy budget that drives outgassing in the first place. Steady-state mass balance: outgassing rate (SOURCE) = escape rate (SINK from v0.21.7) + sequestration rate (frost / weathering / ocean dissolution); inventory stable iff source ≈ sink. 6-body roster: terra (Burton 2013 / Plank 2019 — ~3 kg/s subaerial+submarine CO₂; balanced by carbonate-silicate weathering on geological timescales NOT atmospheric escape; the famous long-term carbon cycle); mars (Halevy 2014 — modern Mars effectively dormant ~0.001 kg/s upper limit; early Mars was active ~10⁻³ Earth's rate but stopped ~3 Gyr ago; the famous "dead planet" story made quantitative — atmosphere shrinks because v0.21.7's 2 kg/s pickup-ion escape is decoupled from ~0 outgassing source); venus (Bullock 2001 / Marcq 2018 — ~0.5 kg/s SO₂ from active mantle hotspots; matches v0.21.7's 0.4 kg/s escape closely → atmospheric inventory stable on Gyr timescales because no carbonate weathering sink); io (Lellouch 2007 / Spencer 2007 — THE HEADLINE: 1 ton/s SO₂ outgassing from tidal-driven volcanism; cross-references v0.21.8 100 TW heating that powers the volcanism; SO₂ has three fates: frost condensation on cold-side hemisphere + photo-dissociation in atmosphere + injection into Jupiter Io plasma torus as S+/O+; the Io→Jupiter mass-transfer pipeline is now fully closed across five ships: v0.19.0 flux tube + v0.20.1 JRM33 + v0.21.5 Io aurora footprint + v0.21.7 1000 kg/s Jupiter pickup-ion escape + v0.21.8 100 TW heating + v0.21.9 1 ton/s outgassing — six independent observational handles converging on the same physics); enceladus (Hansen 2011 Cassini INMS — ~200 kg/s H₂O via south-polar tiger-stripe plume vents; supplies Saturn's E-ring directly which would otherwise sublimate in <100 yr; cross-references v0.21.8 10 GW SP heat flow that drives venting); jupiter (Bagenal 2007 — ~1000 kg/s S+/O+ Io plasma torus injection; the upstream side of v0.21.7's 1000 kg/s Jupiter pickup-ion escape; same number because torus is in steady state). 5 of 6 bodies actively outgassing; only Mars is dormant. The 6-mechanism enumerated vocabulary (subaerial_volcanism / submarine_volcanism / tidal_volcanism / plume_venting / magnetospheric_injection / dormant) makes physical-regime queries trivial. Two new bridge surfaces: bridge.get_volcanic_outgassing(body=None) / bridge.list_volcanic_outgassings(). Two new CLI subcommands: volcanic-outgassing, volcanic-outgassings. 6-entry SOURCES citation dict (Burton 2013, Halevy 2014, Bullock 2001, Lellouch 2007, Hansen 2011, Bagenal 2007); ratchet tests pin both directions. Pure-Python additive; no ABI bump (eighteenth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). New tests/test_volcanic_outgassing.py (24 tests). 1163 tests pass, 41 skipped (was 1136 + 41 in v0.21.8; +27 net new — 24 in test_volcanic_outgassing.py + 2 README-freshness + 1 reconciliation).
• v0.21.8 — Heat flow ↔ tidal heating — the eighth cross-channel coupling surface, fifth in the post-trio sequence. For a body with measured total surface heat flow + measured tidal-Q (v0.21.4), the heat flow constrains the energy-budget decomposition into tidal / radiogenic / primordial-cooling contributions. Cross-channel reach: v0.21.4 + v0.21.6 + v0.21.8 close the tidal-energy-budget loop. For Io, the v0.21.4 Q ≈ 80 + v0.21.6 +3.6 cm/yr outward migration imply tidal dissipation power that matches the v0.21.8 observed surface heat flow ~100 TW — three independent observational handles converging on the same physics. 6-body roster: terra (Davies 2010 / Lay 2008 — 47 TW total; ~66% radiogenic + ~34% primordial cooling; tidal contribution negligible because Earth's tidal Q ≈ 280 dissipates almost entirely in oceans not solid mantle); mars (Khan 2023 InSight basal heat-flow inversion from RISE + seismometer — ~0.1 TW total, ~25-30 mW/m² globally averaged; radiogenic-dominated; cooled faster than Earth because smaller body); io (Veeder 2012 Galileo PPR + ground-based IR — THE HEADLINE OF THE CATALOG: ~100 TW total = 99% tidal, the most volcanically active body in the solar system; 2× Earth's heat flow despite Io being 4× smaller in radius; almost entirely tidal heating from Jupiter; cross-references v0.21.4 Q ≈ 80 + v0.21.6 +3.6 cm/yr outward migration — the three ships close the Io tidal-energy-budget loop); europa (Vance 2018 icy-shell + ocean energy budget model — ~0.5 TW; tidal-dominated; maintains the subsurface saline ocean against freezing; cross-references v0.21.5 Saur 2015 ocean-conductivity diagnostic via auroral rocking); enceladus (Howett 2011 Cassini CIRS south-polar tiger-stripe terrain thermal imaging — ~10 GW = 0.01 TW concentrated in SPT region; tidal-dominated; drives the iconic plume geyser system venting H₂O/CO₂/CH₄/N₂/H₂; cross-references v0.20.2 Enceladus column-not-pressure convention); titan (Tobie 2008 internal-structure model — ~2 TW with substantial tidal heating in icy outer mantle from Saturn's gravitational pull; cross-references v0.21.6 Lainey 2020 +11 cm/yr Saturn-Titan migration — Saturn loses angular momentum → Titan gains orbital energy → some fraction dissipates as Titan tidal heat; PRECISION_LOW because of weak observational constraint). The 3-fraction decomposition (tidal / radiogenic / primordial) is pinned to sum to ~1 by an explicit invariant test (test_fractions_sum_to_unity); each fraction is in [0, 1]. Two new bridge surfaces: bridge.get_heat_flow(body=None) / bridge.list_heat_flows(). Two new CLI subcommands: heat-flow, heat-flows. Every entry carries a source_key pointing into a 6-entry SOURCES citation dict (Davies 2010, Khan 2023, Veeder 2012, Vance 2018, Howett 2011, Tobie 2008); ratchet tests pin both directions. Pure-Python additive; no ABI bump (seventeenth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). New tests/test_heat_flow.py (27 tests). 1136 tests pass, 41 skipped (was 1107 + 41 in v0.21.7; +29 net new — 27 in test_heat_flow.py + 2 README-freshness tests that flipped GREEN).
• v0.21.7 — Atmospheric escape ↔ magnetic-field shielding — the seventh cross-channel coupling surface, fourth in the post-trio sequence. Atmospheric escape rates depend critically on magnetic-field shielding: Earth + Jupiter (intrinsic dipole) deflect solar wind at the magnetopause, retaining atmospheres; Mars + Venus (no intrinsic dipole) are exposed to direct solar-wind pickup-ion erosion that preferentially removes heavy species over Gyr timescales. The cross-channel observation: the v0.20.2 atmospheric inventory diverges by Gyr from the v0.20.1 magnetic-multipole inventory — Mars + Venus diverge from terrestrial inventory because they cannot retain atmosphere against solar-wind erosion. 6-body roster: terra (Lammer 2018 — 3 kg/s thermal Jeans escape of H/He; IGRF-shielded; integrated 4-Gyr loss negligible at ~4×10¹⁴ kg); mars (Jakosky 2018 MAVEN — THE HEADLINE: 2 kg/s present-day pickup-ion escape; integrated 4-Gyr loss ~10¹⁸ kg = ~50% of primordial CO₂ atmosphere; the famous "Mars lost atmosphere because it lost dynamo" story; cross-references v0.20.1 (no Mars magnetic-multipole entry) + v0.20.2 (thin Mars atmosphere)); venus (Persson 2020 / Lundin 2008 ASPERA-4 — 0.4 kg/s pickup-ion despite NO intrinsic dipole; thick CO₂ atmosphere retained because Venus's stronger gravity holds heavier ions + induced magnetosphere from solar-wind/ionosphere interaction; HIGH precision); mercury (Killen 2007 / MESSENGER — 0.01 kg/s sputtering exosphere; weak field provides partial deflection; surface-bound Na/K/H/He replenished by impact + sputtering at rate matched to escape; Na tail observable from Earth via D-line emission); titan (Strobel 2008 hydrodynamic-blowoff — 30 kg/s, the highest absolute rate among classic atmospheric bodies despite Titan's small size; Saturn's magnetosphere provides partial shielding; cross-references v0.20.2 Titan thick atmosphere); jupiter (Bagenal 2007 — 1000 kg/s dominated by Io plasma torus injection of S+/O+ from Io volcanism routed through magnetosphere, NOT direct Jupiter atmospheric escape per se; cross-references v0.19.0 Jupiter-Io flux tube ~10¹² W + v0.20.1 JRM33 magnetosphere + v0.21.5 Io footprint aurora). Two new bridge surfaces: bridge.get_atmospheric_escape(body=None) / bridge.list_atmospheric_escapes(). Two new CLI subcommands: atmospheric-escape, atmospheric-escapes. The 5-mechanism enumerated vocabulary (thermal_jeans / hydrodynamic / pickup_ion / photochemical / sputtering) makes physical-regime queries trivial. Every entry carries a source_key pointing into a 6-entry SOURCES citation dict (Lammer 2018, Jakosky 2018, Persson 2020, Killen 2007, Strobel 2008, Bagenal 2007); ratchet tests pin both directions. Pure-Python additive; no ABI bump (sixteenth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). New tests/test_atmospheric_escape.py (23 tests). 1107 tests pass, 41 skipped (was 1082 + 41 in v0.21.6; +25 net new — 23 in test_atmospheric_escape.py + 2 README-freshness tests that flipped GREEN).
• v0.21.6 — Tidal-resonance ↔ orbital migration — the sixth cross-channel coupling surface, third in the post-trio sequence (after v0.21.4 interior↔rotation and v0.21.5 magnetic↔atmosphere via aurorae). A satellite's tidal interaction with its parent body dissipates mechanical energy (via the v0.21.4 Q-factor mechanism) and transfers angular momentum; the secular semi-major-axis drift is the observable signature. Direction follows from the spin-orbit relation: satellite faster than parent rotation → inward; slower → outward; tidal-locked → no migration. 6-pair roster: terra-luna (Williams 2014/2025 LLR — 3.83 cm/yr outward, the most precisely measured tidal-migration rate in the solar system, drives Earth's spin-down + day lengthening); mars-phobos (Lainey 2007 — −1.9 cm/yr inward, Phobos orbits faster than Mars rotates → tidal bulge lags satellite → tidal-disruption / Roche-limit deadline ~50 Myr); jupiter-io (Lainey 2009 — 3.6 cm/yr outward; Galilean Laplace 1:2:4 resonance is currently EXPANDING, not contracting as classical theory assumed; cross-references the v0.21.4 Io Q ≈ 80 finding); saturn-titan (Lainey 2020 — the headline of the catalog: 11 cm/yr outward, 100× older equilibrium-tide predictions; implies Saturn-interior resonance locking with Titan's orbit, providing much stronger angular-momentum transfer than steady-state tidal dissipation; cross-references the v0.21.4 Mankovich-Fuller 2021 ring-seismology result; the two ships together form a coherent picture of Saturn's deep-interior dynamics); neptune-triton (Jacobson 2009 — −0.5 cm/yr inward; retrograde captured Kuiper Belt object; eventual Roche-limit disruption ~3.6 Gyr from now becomes ring system); pluto-charon (McKinnon 2017 — 0 cm/yr LOCKED; the unique solar-system case of dual-synchronous tidal lock, both bodies tidally locked to each other; mass ratio 0.12 puts barycentre outside Pluto, end-state of tidal evolution). Two new bridge surfaces: bridge.get_tidal_migration(pair=None) / bridge.list_tidal_migrations() (note: pair-name keyed not body-name, because each entry is a 2-body relation). Two new CLI subcommands: tidal-migration, tidal-migrations. Direction-sign invariants pinned in tests (outward → positive, inward → negative, locked → zero). Every entry carries a source_key pointing into a 6-entry SOURCES citation dict (Williams 2014, Lainey 2007, Lainey 2009, Lainey 2020, Jacobson 2009, McKinnon 2017); ratchet tests pin both directions. Pure-Python additive; no ABI bump (fifteenth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). New tests/test_tidal_migration.py (24 tests). 1082 tests pass, 41 skipped (was 1056 + 41 in v0.21.5; +26 net new — 24 in test_tidal_migration.py + 2 README-freshness tests that flipped GREEN).
• v0.21.5 — Magnetic ↔ atmosphere coupling via aurorae — the fifth cross-channel coupling surface, second in the post-trio sequence after v0.21.4 interior↔rotation. Aurorae are the visible signature of magnetic-field-line topology mapping into the upper atmosphere; oval morphology directly traces internal-field geometry. 6-body roster: terra (Bonfond 2017 review) — circular oval, solar-wind-reconnection driven, total auroral power ~10¹¹ W; jupiter (Connerney 2017 Juno UVS) — the headline of the catalog: circular oval traces JRM33 dipole + quadrupole + Great Blue Spot; Io flux-tube footprint always visible inside oval; Europa + Ganymede footprints intermittent; internally driven by corotation enforcement, NOT solar wind; total auroral power ~10¹⁴ W = 1000× Earth's; saturn (Hunt 2014 Cassini UVIS / Stallard 2008 NIR H₃⁺) — annular oval directly traces Cao 2020 axisymmetry (dipole tilt < 0.007°); cross-references the v0.20.1 axisymmetry result; solar-wind-driven; uranus (Lamy 2017 HST 2011) — partial oval (not full) due to extreme 58.6° dipole tilt + offset in AH5 model; complex phase relation between magnetic + spin axes; neptune (Pryor 2007 Voyager 2 + HST) — patchy time-variable; weakest aurora in catalog (~10⁸ W); ganymede (Saur 2015 HST) — only intrinsic-moon-dynamo aurora in solar system; auroral-position rocking between 2010 + 2011 HST observations diagnoses subsurface saline ocean's induction response to Jupiter's varying ambient field — a true cross-channel observation: the aurora itself diagnoses an interior property (ocean conductivity), tying together v0.20.1 magnetic + v0.20.0 interior catalogs through observational coupling. Three families of acceleration mechanisms span the catalog: solar-wind reconnection (terra, saturn), corotation enforcement (jupiter, ganymede), tilted-dipole variability (uranus, neptune). Two new bridge surfaces: bridge.get_auroral_coupling(body=None) / bridge.list_auroral_couplings(). Two new CLI subcommands: auroral-coupling, auroral-couplings. Every entry carries a source_key pointing into a 6-entry SOURCES citation dict (Bonfond 2017, Connerney 2017, Hunt 2014, Lamy 2017, Pryor 2007, Saur 2015); ratchet tests pin both directions. Pure-Python additive; no ABI bump (fourteenth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). New tests/test_auroral_coupling.py (24 tests). 1056 tests pass, 41 skipped (was 1029 + 41 in v0.21.4; +27 net new — 24 in test_auroral_coupling.py + 2 README-freshness tests that flipped GREEN + 1 reconciliation).
• v0.21.4 — Interior-derived rotational constraints — the fourth cross-channel coupling surface, opening the post-trio sequence (after v0.21.1-v0.21.3 shipped the trio explicitly named in §17.4.2). For a body with a published interior model (v0.20.0 INTERIOR_MODELS), the constraint connects interior structure (moment-of-inertia, core size, tidal viscosity) to observed rotational behaviour through five distinct physics regimes. 7-body roster: terra (Mathews 2002 IERS) — free-core-nutation period 430.21 days constraining liquid outer-core / mantle boundary friction; mars (Le Maistre 2023 InSight RISE) — direct nutation measurement giving core radius 1830 ± 40 km, revising pre-InSight estimates downward; jupiter (Kaspi 2018 from Juno J6/J8/J10) — zonal-wind base at ~3000 km depth (~4 % of radius) before bottoming out in metallic-H layer; saturn (Mankovich & Fuller 2021 ring seismology) — the headline: revises Saturn's rotation period from Voyager 10h 39min 22s → ring-seismology 10h 33min 38s = 0.43539 days; ring-mode forcing only matches deep-interior rotation, not cloud-deck rotation, resolving decades-long debate; io (Lainey 2009 117-year astrometric fit) — tidal Q ~ 35-100, vigorous dissipation consistent with volcanic activity; europa + ganymede (Lainey 2020 Cassini-era refinement; shared citation = 6 sources for 7 bodies) — Q ~ 250-1000 / 200-500 respectively; subsurface-ocean / dynamo-energy-budget contributions. Two new bridge surfaces: bridge.get_rotational_constraint(body=None) / bridge.list_rotational_constraints(). Two new CLI subcommands: rotational-constraint, rotational-constraints. Every constraint value carries a source_key pointing into a 6-entry SOURCES citation dict (Mathews 2002, Le Maistre 2023, Kaspi 2018, Mankovich-Fuller 2021, Lainey 2009, Lainey 2020); ratchet tests pin both directions. Pure-Python additive; no ABI bump (thirteenth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). New tests/test_rotational_constraint.py (26 tests). 1029 tests pass, 41 skipped (was 1001 + 41 in v0.21.3; +28 net new — 26 in test_rotational_constraint.py + 2 README-freshness tests that flipped GREEN after the Status banner update).
• v0.21.3 — Orographic forcing of atmospheric standing waves — the third cross-channel coupling surface in the §17.4.2 v0.21.x sequence (after v0.21.1 topography ↔ gravity admittance and v0.21.2 magnetic-multipole-derived dynamo-region constraints), completing the trio of cross-channel surfaces explicitly named in §17.4.2's forward sequence. For a body with both a topography model (v0.20.0) and an atmosphere (v0.20.2), surface topography acts as a lower-boundary forcing on the global circulation; the forcing generates downstream stationary Rossby waves with zero phase speed in the body-rotating frame, appearing as fixed structure in the time-mean atmosphere. The dominant zonal wavenumber is set by the Rossby radius of deformation L_R = N·H/f. Not a re-derivation — values shipped are the published GCM-derived stationary-wave decompositions from cited papers. 4-body roster: terra (Held 2002 / Hoskins & Karoly 1981 — Tibetan Plateau ~4.5 km, ~2500 km wide; wavenumber-2 stationary mode at 300-500 mbar mid-troposphere; the canonical Northern-Hemisphere winter pattern); mars (Hollingsworth 1997 / MGS Mars Climate Database — Tharsis Bulge ~10 km, ~10000 km wide; wavenumber-2 stationary mode survives all the way to ~50 km altitude (mesopause) — the headline planetary case in the catalog, with the most dramatic orographic forcing on any body); venus (Lebonnois 2010 GCM — Maxwell Montes ~11 km but very localised; super-rotation regime suppresses classic stationary-wave physics; LOW precision flag, is_stationary_wave_observed=False); titan (Charnay & Lebonnois 2012 GCM — Xanadu uplift + equatorial dune fields modest ~0.5 km; super-rotation regime analogous to Venus; LOW precision, observed=False). The terra + mars entries have observationally-confirmed standing waves; venus + titan are GCM-only because their super-rotation suppresses the Hoskins-Karoly classic-stationary-wave physics regime. Two new bridge surfaces: bridge.get_orographic_forcing(body=None) / bridge.list_orographic_forcings(). Two new CLI subcommands: orographic-forcing, orographic-forcings. Every numeric value carries a source_key pointing into a 4-entry SOURCES citation dict (Held 2002, Hollingsworth 1997, Lebonnois 2010, Charnay & Lebonnois 2012); ratchet tests pin both directions. Pure-Python additive; no ABI bump (twelfth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). With v0.21.3 the trio of cross-channel coupling surfaces explicitly named in §17.4.2 is complete (topography ↔ gravity, magnetic ↔ dynamo, topography ↔ atmosphere); future v0.21.x minors will ship coupling surfaces from §17.1/§17.2/§17.3 follow-up findings. New tests/test_orographic_forcing.py (24 tests). 1001 tests pass, 41 skipped (was 977 + 41 in v0.21.2; +24 net new — 24 in test_orographic_forcing.py; 2 parity-smoke entries are fixture entries, not separate test cases).
• v0.21.2 — Magnetic-multipole-derived dynamo-region constraints — the second cross-channel coupling surface in the §17.4.2 v0.21.x sequence (per §17.4.2: topography ↔ gravity admittance [v0.21.1], magnetic-multipole-derived dynamo constraints [v0.21.2 — this ship], orographic forcing of atmospheric standing waves [v0.21.3]). For a body with a published spherical-harmonic magnetic-field expansion (v0.20.1 MAGNETIC_MULTIPOLE_MODELS), the Lowes-Mauersberger spectrum R(n) ∝ (R_dynamo / R_surface)^(2n+4) inverts directly for the dynamo radius — log-slope of R(n) vs n gives R_dynamo/R_body. Not a re-derivation; values shipped are the published inversions from cited papers. 5-body roster: terra (Lowes 1974 — canonical CMB depth at 3486 km / 0.547 R_E in molten Fe-Ni alloy; matches seismology to better than 1%, the validation case for the technique); mercury (Christensen 2006 — weak-field anomaly with stable-stratified upper-core layer that filters high degrees; standard Lowes-Mauersberger fails, depth from Christensen weak-field model at 0.83 R_Me); jupiter (Connerney 2022 from JRM33 deg-18 — dynamo at 0.85 R_J in metallic H, just above the metallic-H phase boundary); saturn (Cao 2020 / Stevenson 2010 — dynamo at 0.55 R_S in metallic H; the famous axisymmetry < 0.007° is itself a constraint via the Stevenson 1980 stable-stratified-layer mechanism that filters non-axisymmetric modes); ganymede (Schubert 1996 / Kivelson 2002 — only intrinsic-moon dynamo in the solar system; small Fe-FeS core at 0.27 R_G; max_degree=1 dipole-only published, so depth comes from thermal-evolution models). Two new bridge surfaces: bridge.get_dynamo_region(body=None) / bridge.list_dynamo_regions(). Two new CLI subcommands: dynamo-region, dynamo-regions. Every dynamo-radius value carries a source_key pointing into a 5-entry SOURCES citation dict (Lowes 1974, Christensen 2006, Connerney 2022, Cao 2020, Schubert 1996); ratchet tests pin both directions. Pure-Python additive; no ABI bump (eleventh consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). New tests/test_dynamo_catalog.py (24 tests). 975 tests pass, 41 skipped (was 949 + 41 in v0.21.1; +26 net new — 24 in test_dynamo_catalog.py + 2 parity-smoke entries).
• v0.21.1 — Topography ↔ gravity admittance — the first cross-channel coupling surface in the §17.4.2 v0.21.x sequence (per §17.4.2: "v0.21.1+ Cross-channel coupling surfaces, one per minor version: topography ↔ gravity admittance, magnetic-multipole-derived dynamo constraints, orographic forcing of atmospheric standing waves"). For a body with both a published gravity multipole expansion (v0.20.0 GRAVITY_MODELS) and a topography model (v0.20.0 TOPOGRAPHY_MODELS), the spectral admittance Z(n) = ⟨SH_gravity[n,m]·conj(SH_topography[n,m])⟩ / ⟨|SH_topography[n,m]|²⟩ at each spherical-harmonic degree n constrains crustal density and crustal thickness via isostatic compensation theory. Low Z(n) at long wavelengths is a signature of Airy isostatic compensation; high Z(n) at short wavelengths is uncompensated topographic loading. Not a re-derivation — values shipped are the integrated Z summary published in the cited papers; per-degree Z(n) tables remain in the cited paper's supplementary materials. 5-body roster with peer-reviewed admittance studies: terra (Wieczorek 2007 / Watts 2001 — continental-mean Z ~50 mGal/km, crustal density 2670 kg/m³, Airy compensation depth ~35 km); luna (Wieczorek 2013 GRAIL+LOLA — the famous lunar crustal density 2550 kg/m³, revised down from prior ~2900; Z ~95 mGal/km at degrees 50-200; the headline GRAIL geodesy result); mars (Genova 2016 + Konopliv 2016 + InSight — Z ~110 mGal/km, mean crustal thickness ~50 km but strongly bimodal between 30 km northern lowlands and 70 km southern highlands; Tharsis dominates n<10); mercury (James 2015 MESSENGER reanalysis — Z ~85 mGal/km, crustal density ~3200 kg/m³ consistent with Mercury's high planetary density); venus (Anderson 2002 Magellan-only — Z ~200 mGal/km, the highest in the catalog because Venus has weak Airy compensation under Magellan-resolved conditions; lithospheric-flexure / mantle-plume support model dominates instead). Two new bridge surfaces: bridge.get_topography_gravity_admittance(body=None) / bridge.list_admittance_spectra(). Two new CLI subcommands: admittance, admittance-spectra. Every Z(n) value carries a source_key pointing into a 5-entry SOURCES citation dict (Wieczorek 2007, Wieczorek 2013, Genova 2016, James 2015, Anderson 2002); ratchet tests pin both directions. Pure-Python additive; no ABI bump (tenth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). New tests/test_admittance_catalog.py (25 tests). 949 tests pass, 41 skipped (was 922 + 41 in v0.21.0; +27 net new — 25 in test_admittance_catalog.py + 2 parity-smoke entries).
• v0.21.0 — Sol Spherical Harmonic Catalog — unification refactor across the v0.20.0 gravity sector (4π-normalised Stokes coefficients) and the v0.20.1 magnetic sector (Schmidt-quasi-normalised g_n^m / h_n^m). Promotes notebook §17.4.2 to a stable ship surface. This is a unification refactor, not a new data store — the underlying records still live in geodetic_catalog_data (gravity) and magnetic_multipole_catalog_data (magnetic); the v0.20.0 / v0.20.1 surfaces (bridge.get_geodetic_state, bridge.get_magnetic_multipoles) continue to work unchanged. The unification is a NEW query surface that lets consumers ask "what spherical-harmonic representations does the catalog have for body X, across all channels?" with one call instead of two. Each returned record carries an explicit normalisation_convention field — "4pi-Stokes" (geodesy) or "Schmidt-quasi-norm" (geomagnetic) — so consumers know which conversion factors to apply when crossing channels. Two new query surfaces + one math helper: bridge.get_spherical_harmonics(body, channel="both") (single-body query across {"gravity", "magnetic", "both"}; bodies absent from a requested channel return that channel as None); bridge.list_spherical_harmonic_models() (full enumeration: 56 gravity models + 7 magnetic models + the 7 both-channels intersection bodies = terra / mercury / jupiter / saturn / uranus / neptune / ganymede + the merged 76-entry SOURCES citation dict spanning both sectors); bridge.convert_spherical_harmonic_normalisation(coefficient_value, n, m, from_convention, to_convention) (Winch et al. 2005 closed-form: C̄_nm = g_n^m / sqrt((2 - δ_0m) * (2n + 1)); round-trip identity to float-machine precision). Three new CLI subcommands: spherical-harmonics, spherical-harmonic-models, convert-normalisation. No regression on v0.20.0 / v0.20.1 surfaces — back-compat tests pin both surfaces continue to return their original shapes. Pure-Python additive; no ABI bump (ninth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). Research origin notebook §17.4.2. New tests/test_spherical_harmonic_catalog.py (30 tests pinning the unification logic + back-compat invariants + Winch et al. 2005 conversion math + bridge surfaces + CLI surfaces). 922 tests pass, 41 skipped (was 889 + 41 in v0.20.2; +33 net new — 30 in test_spherical_harmonic_catalog.py + 3 parity-smoke entries).
• v0.20.2 — Sol Fluid Instrument — climatology + archive index + state-at-epoch query surface for the solar-system fluid envelope (atmospheres, oceans, cryospheres, exospheres). Promotes the v0.20.x research output (notebook §17.3 + §17.4.2) to a stable ship surface, mirroring the v0.19.0 EM Instrument / v0.20.0 Sol Geodetic Catalog / v0.20.1 Sol Magnetic Multipole Catalog patterns. Ships all three Option-D layers together per the §17.4.2 full-coverage commitment — no MVP subset, no deferred layer. Layer 1 — climatological summary scalars per body (mean surface temperature K, mean surface pressure Pa, dominant gas top-3 mole fractions, obliquity deg, orbital eccentricity, Bond albedo) for 17 atmospheric bodies + 4 airless small bodies = 21 entries (terra / mars / venus / titan / triton / pluto / io / europa / ganymede / enceladus / mercury / luna / sun / jupiter / saturn / uranus / neptune + ceres / vesta / bennu / ryugu). Headline numerics include the surprising results: Titan 94 K + 1.45 bar (denser atmosphere than Earth's despite the cold; only moon with a thick atmosphere); Triton 38 K + 1.4 Pa (one of the coldest known surfaces in the solar system); Venus 737 K + 92 bar; Uranus 97.77° obliquity (extreme axial tilt → 42-yr seasonal cycles). Gas giants ship at the 1-bar reference level by convention. Layer 2 — archive-pointer index (10 entries) per atmospheric body with file format + access protocol + temporal coverage + endpoint URL: ERA5 (terra, ECMWF Copernicus 1940-present), MCD v6.1 (mars, LMD MY 24-present), VIRA + Akatsuki (venus), Cassini PDS-PPI (titan + saturn), Juno PDS (jupiter), MAVEN PDS (mars-upper-atmosphere), Voyager 2 PDS (uranus + neptune flyby snapshots), New Horizons PDS (pluto). Layer 3 — state-at-epoch coverage flags (21 entries) — only terra (ERA5 reanalysis, JD ≈ 2429630.5 onward = 1940-01-01) and mars (MCD v6.1, MY 24-start ≈ JD 2450545.5 onward = 1997-04-07 vernal equinox) have the True flag; all 19 other bodies fall back to the climatological summary with explicit out-of-coverage-fallback-to-climatology query_type. Three new bridge surfaces: bridge.get_fluid_state(body=None, jd_tdb=None, lat=None, lon=None) (with coverage_status triage when jd_tdb given: in_coverage / before_archive / future / no_state_at_epoch), bridge.list_fluid_archives(), bridge.fluid_architecture(target=None). Three new CLI subcommands: fluid-state, fluid-archives, fluid-architecture. No outbound network calls — the package ships pointers + the climatological-summary fallback in a self-contained dict; consumers fetch the actual reanalysis field via the archive's own API (CDS-API for ERA5; Python wrapper for MCD). HIGH/MEDIUM/LOW/NONE data-quality partition is the fluid-channel sibling of the v0.20.0/v0.20.1 partitions — a fourth orthogonal data-quality classification axis: {HIGH: 13, MEDIUM: 8, LOW: 0, NONE: 1} (HIGH = current-best published climatology with multi-mission coverage; MEDIUM = single-mission limited or transient observations; LOW reserved for Voyager-only flyby snapshots in the archives layer; NONE = mars-upper-atmosphere appears as an archive-only body string). Every numeric value carries a source_key pointing into a 24-entry SOURCES citation dict; ratchet tests pin both directions (every key resolves; no unused entries). Pure-Python additive; no ABI bump (eighth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). Research origin notebook §17.3. New tests/test_fluid_instrument.py (50 tests). 889 tests pass, 41 skipped (was 834 + 41 in v0.20.1; +55 net new — 50 in test_fluid_instrument.py + 3 parity-smoke entries + 2 README-freshness tests that flipped GREEN after the Status banner update).
• v0.20.1 — Sol Magnetic Multipole Catalog — state-lookup query surface for the published-internal-field roster across the solar system. Promotes the v0.20.x research output (notebook §17.2 + §17.4.2) to a stable ship surface, mirroring the v0.19.0 EM Instrument and v0.20.0 Sol Geodetic Catalog patterns. Not a BIP encoder — per §17.4.1 the rhythm-mismatch finding generalises across magnetic multipoles alongside solid-body geodesy and fluid-envelope channels: internal-field Schmidt-quasi-normalised g_n^m / h_n^m coefficients are static at their epoch (IGRF main field updates every 5 years on a published schedule; JRM33 is a Juno-prime-mission snapshot; Voyager-derived AH5/O8 are single-flyby fits), so the cyclic-group encoder discipline does not transplant. 7-body main-field roster — every body in the published refereed literature with a multipole expansion: Earth IGRF-13 (deg 13, Alken 2021); Jupiter JRM33 (deg 18, Connerney 2022; Great Blue Spot resolved); Saturn Cao 2020 (deg 14, Cassini Grand Finale; the famous dipole tilt < 0.007° axisymmetric result as first-class structural_flag); Mercury Thébault 2018 (deg 5, MESSENGER reanalysis; ~484 km northward offset dipole); Uranus Holme & Bloxham AH5 (deg 3, Voyager-only; tilt 58.6° + offset); Neptune Holme & Bloxham O8 (deg 3, Voyager-only; tilt 47°); Ganymede Kivelson 2002 (dipole-only — the only solar-system moon with a confirmed intrinsic dipole; "higher-degree pending JUICE 2034" flag). Plus 1 crustal field model — Earth EMM2017 (deg 720, ~30 MB lazy-load via crustal=True flag) — and 1 solar synoptic reference — Stanford HMI synoptic-magnetograms (Carrington-rotation cadence, coverage 2010-present) accessible via bridge.get_solar_synoptic_state(jd_tdb); the Sun's time-varying field lives behind a different surface than the static catalog. Five new bridge surfaces: get_magnetic_multipoles(body=None, crustal=False), evaluate_magnetic_field(body, r_km, lat_deg, lon_deg, jd_tdb=None) (closed-form Schmidt-quasi-normalised dipole synthesis), get_solar_synoptic_state(jd_tdb=None), list_magnetic_multipoles(), magnetic_architecture(target=None). Five new CLI subcommands: magnetic-multipoles, magnetic-field, solar-synoptic, magnetic-models, magnetic-architecture. HIGH/MEDIUM/LOW/NONE data-quality partition (per §17.1.6 ship-readiness convention) is the magnetic-channel sibling of v0.20.0's geodetic partition: HIGH = current-best (Earth/Jupiter/Saturn); MEDIUM = single-mission limited (Mercury/Ganymede); LOW = Voyager-only single flyby (Uranus/Neptune); NONE = synoptic-only (Sun, no static record). Every numeric value carries a source_key pointing into a 9-entry SOURCES citation dict; ratchet tests pin resolution at CI time. Also refreshes the package pyproject.toml description (was advertising the obsolete v0.5-era 38-body roster + omitting all the v0.16-v0.20.x catalog work) — now lists 52-body roster + per-body Sol Geodetic / Electromagnetic / Magnetic-Multipole catalogs + resonance-graph ITN-chain search + spectral body-architecture surfaces. Pure-Python additive; no ABI bump (seventh consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). Research origin notebook §17.2. New tests/test_magnetic_multipole_catalog.py (59 tests). 834 tests pass, 41 skipped (was 769 + 41 in v0.20.0; +65 net new — 59 in test_magnetic_multipole_catalog.py + 5 parity-smoke entries + 1 reconciliation).
• v0.20.0 — Sol Geodetic Catalog — state-lookup query surface for the solar-system solid-body geodetic stack (gravity multipoles + topography / shape models + interior structure). Promotes the v0.20.x research output (notebook §17.1 + §17.4.2) to a stable ship surface, mirroring the v0.19.0 Sol Electromagnetic Instrument pattern. Not a BIP encoder running on geodetic rhythms — per §17.4.1 the rhythm-mismatch finding generalises across solid-body geodesy alongside magnetic multipoles and fluid-envelope channels: solid-body geodetic observables (Stokes coefficients, DEM spectra, layered density profiles) are static parameters with no native rhythm, so the cyclic-group encoder discipline does not transplant. The Sol Geodetic Catalog is therefore a state-lookup surface (no JD-advance mechanic) holding three internal channels per body: gravity — published spherical-harmonic multipole expansions (full Stokes coefficients for terrestrial bodies + the Moon; zonal-only J_n series for the gas + ice giants; point-mass GM for Lagrange trojans + Jovian irregulars); topography — DEM / shape-model metadata (full-coverage DEMs for the inner solar system + the Moon; Cassini SARTopo for Titan; polyhedral shape models for the small-body roster); interior — radial density profiles + layered models + moment-of-inertia constraints (PREM / GRAIL+Apollo / InSight / Mankovich-Fuller ring-seismology / Voyager-derived for the ice giants). 56 gravity + 32 topography + 26 interior entries across the catalog with 22 fully-characterised triple-channel bodies (terra / luna / mars / mercury / venus / io / europa / ganymede / callisto / mimas / enceladus / dione / rhea / iapetus / titan / triton / pluto / charon / ceres / vesta / bennu / ryugu) — full-coverage per the §17.4.2 commitment, no "minimum-viable" subset deferred. Three new bridge surfaces: get_geodetic_state(body=None), list_geodetic_models(), geodetic_architecture(target=None). Three new CLI subcommands: geodetic-state, geodetic-models, geodetic-architecture. HIGH/MEDIUM/LOW/NONE data-quality partition (median of per-channel precision_flag per the §17.1.6 ship-readiness convention) is a third orthogonal classification axis alongside v0.18.0's inner/outer Fiedler partition (orbital position) and v0.19.0's magnetised/induced/unmagnetised split (intrinsic-field presence) — this one is by published-data quality, not physical body class. Every numeric value carries a source_key pointing into a 67-entry SOURCES citation dict (DOIs / mission archives / journal refs); ratchet tests pin the resolution at CI. Forward sequence committed in §17.4.2: v0.20.1 MagneticMultipoleCatalog (full published high-degree internal-field roster); v0.20.2 SolFluidInstrument (climatological summary + archive index + Earth/Mars state-at-epoch); v0.21.0 SphericalHarmonicCatalog unification refactor across gravity + magnetic + fluid sectors; v0.21.1+ cross-channel coupling surfaces (one per minor version). Pure-Python additive; no ABI bump (sixth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). Research origin notebook §17. New tests/test_geodetic_catalog.py (35 tests). 769 tests pass, 41 skipped (was 730 + 41 in v0.19.0; +39 net new — 35 in test_geodetic_catalog.py + 3 parity-smoke entries + 1 reconciliation).
• v0.19.0 — Sol Electromagnetic Instrument — state-at-epoch query surface for the solar-system EM sector. Promotes the v0.19.x research output (notebook §16.9) to a stable ship surface. Not a BIP encoder — the §16.3 / §16.9.1 rhythm-mismatch finding established that EM clocks (rotational, Carrington, solar cycle, plume duty cycles) don't form a low-order rational lattice with each other or with orbital periods, so the cyclic-group encoder discipline doesn't transplant. The Sol EM Instrument is therefore a state-at-epoch lookup surface holding per-body EM observables (intrinsic dipole moment, rotation phase advanced from J2000, synchrotron power, plasma source rate, photoelectric potential) plus a static catalog of pairwise EM couplings. 16-body roster (strict subset of the v0.16.0 52-body celestial roster): 1 star (sun) + 7 magnetised (mercury / terra / jupiter / ganymede / saturn / uranus / neptune) + 4 induced (venus / europa / callisto / titan) + 4 unmagnetised (luna / mars / io / enceladus). 7 pairwise EM couplings: Jupiter↔Io flux tube (~10¹² W, dominant; Saur 2007 / Hess et al. 2010); Saturn↔Enceladus plasma mass loading (~5×10⁹ W; Pontius & Hill 2006); Saturn↔Titan induced magnetosphere (~10⁹ W); Sun↔Terra IMF reconnection (~5×10⁹ W; Lockwood 2022); Jupiter↔Europa induced magnetosphere (~10¹⁰ W; Khurana 1998); Jupiter↔Ganymede intrinsic-field-to-intrinsic-field (~10¹⁰ W — the unique mini-magnetosphere case); Sun↔asteroid-belt-bulk radiation pressure (~10¹⁵ W — Yarkovsky/YORP scoping anchor; Bottke 2006). Saturn rotation-period uncertainty (~1% between Voyager and Cassini SKR) flagged explicitly per §16.3 disclaimer. Three new bridge surfaces: get_em_state(jd_tdb), list_em_couplings(), em_architecture(target=None). Three new CLI subcommands: em-state, em-couplings, em-architecture. Magnetised/induced/unmagnetised partition is a different classification axis than v0.18.0's body_architecture inner/outer Fiedler partition (orbital position) — this one is by intrinsic-field presence (lookup, not eigendecomposition). Every numeric value carries a source_key pointing into a 19-entry SOURCES citation dict for verifiable provenance. Pure-Python additive; no ABI bump (fifth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged). Research origin notebook §16; user course-correction widened scope from "magnetic-only" to "electromagnetic" (the Io flux tube is a current loop, not magnetic-dipole-dipole; solar wind is plasma-mediated; radiation pressure is photon momentum). New tests/test_em_instrument.py (46 tests). 730 tests pass, 41 skipped (was 685 + 41 in v0.18.2; +45 net new on top of the v0.18.2 baseline).
• v0.18.2 — 2-D (f₂, f₃) Fiedler-embedding upgrade for bridge.predict_itn_accessibility. Replaces the v0.18.1 1-D |f₂[i] − f₂[j]| distance with a 2-D Euclidean distance on the (f₂, f₃) embedding of the same hybrid Laplacian. Spearman ρ unchanged (1-D: +0.857 / 2-D: +0.849 — rank ordering already strong) but R² lifts 0.51 → 0.64 and in-sample MAE drops 4.11 → 3.00 km/s (−27 %) + LOOCV MAE drops 4.24 → 3.12 km/s (−26 %) + LOOCV median absolute error drops to 2.20 km/s. The second eigenvector f₃ adds an axis that distinguishes within-cluster pairs (e.g., Earth/Venus + main-belt asteroids cluster on f₃ > 0; outer planets on f₃ < 0; mercury isolated on f₃ ≈ −0.28) that the 1-D Fiedler vector collapsed. Bridge response shape unchanged (predicted_dv_kms, calibration provenance) but adds new embedding_distance_2d and calibration.lambda_3 + calibration.embedding_dim + calibration.loocv_median_abs_error_kms fields. The 1-D Fiedler distance is preserved as the fiedler_distance field for back-compat with v0.18.1 callers. Calibration constants change (intercept 8.68 → 4.90, slope 15.62 → 17.32) — the v0.18.1 1-D constants are exposed under *_1D_HISTORICAL names for traceability. New research/two_eigenvector_fiedler_embedding.py (the calibration-comparison script) lives alongside the existing calibrate_predict_itn_accessibility.py. Notebook §13.10 documents the 2-D embedding result. Pure-Python additive improvement; no ABI bump (fourth consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged from v0.17.0/v0.18.0/v0.18.1). New 5 tests (calibration-pin update + 1-D-historical-preservation + 2-D-distance-presence + embedding-dim metadata). 685 tests pass, 41 skipped (was 681 + 41 in v0.18.1; +4 net new).
• v0.18.1 — bridge.predict_itn_accessibility: closed-form spectral Δv estimate from the §13.9 hybrid Fiedler-distance regression. Promotes the v0.17.x research output (notebook §13.9) — the multiplicative inv_dv × resonance gateway-graph Laplacian's Fiedler distance as a continuous predictor of multi-leg ITN-chain Δv — to a stable ship surface. Calibrated by OLS regression against ground truth from a 50-yr find_itn_chains sweep at J2000 (max_legs=3, dv_budget=30 km/s, threshold=0.1) on the v0.16.0 13-body heliocentric Tier-1 roster: slope ≈ 15.62 km/s per Fiedler-distance unit, intercept ≈ 8.68 km/s, Spearman ρ = +0.857, in-sample R² ≈ 0.51, LOOCV MAE ≈ 4.24 km/s. Use case: fast first-pass triage (microseconds vs ~1.5 s for the full Dijkstra) — not trajectory design (the absolute MAE is ~4 km/s on a 2–28 km/s domain, useful for ranking pairs but too coarse for mission-budget purposes). New bridge.predict_itn_accessibility(departure, target) Python entry + new predict-itn-accessibility CLI subcommand. Calibration provenance returned in every response (Spearman ρ, R², MAE, LOOCV MAE, n_finite, n_inf, window) so callers can decide whether the prediction is precise enough for their use case. New offline calibration script research/calibrate_predict_itn_accessibility.py (re-fits the regression against a re-sampled ground truth — useful for non-default search windows). Pure-Python addition; no ABI bump (third consecutive ship since v0.13.x with no ABI movement; ES_ABI_VERSION = 8 unchanged from v0.17.0/v0.18.0). Notebook §14 (the holographic-principle-at-macro-scale section, also added in v0.18.1) re-reads the §13.9 / v0.18.1 result as the bulk-boundary correspondence's "real" empirical payload — the spectral boundary (13-D Fiedler vector) anticipates the trajectory bulk (78-pair × 3-leg Dijkstra) at calibrated Spearman 0.857. New tests/test_predict_itn_accessibility.py (22 tests). 681 tests pass, 41 skipped (was 658 + 41 in v0.18.0; +23 new — 22 predict_itn_accessibility + 1 parity-smoke entry).
• v0.18.0 — Body Architecture: inner/outer system classification of heliocentric bodies via the resonance-weighted gateway-graph Laplacian Fiedler partition. First spectral-architecture surface in the bridge — the v0.17.x research output (notebook §13.8) promoted to a stable ship API. The cyclic-group encoder discovers the canonical asteroid-belt boundary without being told it exists: outer 5 (jupiter / saturn / uranus / neptune / pluto) all negative; inner 8 (mercury / venus / terra / mars / vesta / ceres / pallas / hygiea) all positive. Pluto and Neptune share the deepest negative Fiedler entry (≈ −0.585) via their well-known 2:3 mean-motion lock dragging both deep into the outer cluster. New bridge.body_architecture(target=None) Python entry + new body-architecture CLI subcommand (full partition by default; --target terra etc. for single-body class lookup). The Fiedler-vector sign is anchored to the shortest-period body (mercury) being positive — class labels are reproducible across platforms regardless of LAPACK pivoting. Pure-Python addition; no ABI bump (second consecutive ship since v0.13.x with no ABI movement — v0.17.0 added find_itn_chains, v0.18.0 adds body_architecture, both leave ES_ABI_VERSION = 8 unchanged). Notebook §13.9 also lands the hybrid inv_dv × resonance Laplacian research follow-up: Spearman ρ = +0.857 (clears the §13.7 0.85 ship bar) but Matthews φ = +0.298 (below the 0.6 partition bar) — vindicates the multiplicative-hybrid hypothesis for a continuous Fiedler-distance Δv predictor while leaving the partition-only ship surface to the resonance-only weighting. A bridge.predict_itn_accessibility continuous-Δv predictor is queued for v0.18.x or v0.19.0 (gated on Fiedler-distance → Δv regression calibration). New tests/test_body_architecture.py (34 tests). 658 tests pass, 41 skipped (was 622 + 41 in v0.17.0; +36 new — 34 body_architecture + 2 parity-smoke entries).
• v0.17.0 — Resonance-graph multi-leg find_itn_chains (advanced Lagrange-highway search). Generalises the v0.8.1 closed-form Hohmann-window enumeration (find_itn_pathways) to multi-leg pathways via Dijkstra-style graph search over the (body, epoch) state space. Each leg is a closed-form Hohmann window from find_itn_pathways; legs stitch end-to-end at intermediate bodies; cumulative Δv and time-of-flight are budget-bounded. Each leg carries a small-integer (p, q) gear-ratio resonance signature (period_dep / period_tgt reduced to lowest terms via _best_rational_approx) — the natural cross-pollination point between the closed-form transfer-window machinery and the BIP cyclic-group encoder. The Dijkstra invariant on cumulative Δv guarantees the first chain emitted is the optimal-Δv path; subsequent chains are emitted in monotonically non-decreasing total-Δv order. Canonical witnesses verified in tests: Earth/Mars 8:15 synodic-resonance anchor (the well-known 8-Earth-yr / 15-Mars-orbit tile), Earth/Jupiter 1:12 Jupiter-orbit anchor, Jupiter/Saturn 2:5 great-inequality. New bridge.find_itn_chains Python entry + new find-chains CLI subcommand (intermediates / max-legs / Δv budget / TOF budget / threshold / max-chains flags). Pure-Python addition built on top of find_itn_pathways: no ABI bump (the C wire-format is unchanged; this is the first ephemerides ship since v0.13.x to leave the ABI alone — v0.14.0/v0.14.1/v0.14.2 added bodies, v0.15.0 + v0.16.0 expanded BODIES, all of which moved the ABI). Sets up the v0.17.x research thesis on Gateway-graph Laplacian + Fiedler-partition empirical-low-Δv-accessibility correspondence (notebook §12). New test_find_itn_chains.py (21 tests: rational-approximation invariants + direct-chain consistency with v0.8.1 + Dijkstra optimal-first invariant + Δv/TOF/max-legs budget enforcement + bridge surface + CLI surface). 622 tests pass, 41 skipped (was 601 + 41 in v0.16.0; +21 new).
• v0.16.0 — BODIES Tier-1 expansion (43 → 52): Lagrange trojans + retrograde irregulars + Neptune sub-graph completion. Themed per the post-v0.15.0 audit (notebook §11). Adds 9 bodies: 4 Saturnian Lagrange trojans (Telesto + Calypso at Tethys L4/L5 with SSaTeT2 / SSaCaT; Helene + Polydeuces at Dione L4/L5 with SSaHeT / SSaPoT — first L4/L5 entries in BODIES, the body-graph Laplacian acquires a multiplicity-2 eigenvalue at the host moon's frequency); 3 Jovian irregulars (Himalia SJuHiT largest prograde, Pasiphae SJuPaT and Sinope SJuSiT retrograde — second retrograde marker beyond Triton); Neptune sub-graph completion (Proteus SNePrT Neptune's second-largest moon at 1.122 d period, fills the gap between Triton at 5.88 d and the deferred inner-Neptunian close-packed cluster; Nereid SNeNeT most eccentric major-moon orbit in the solar system at e=0.749, 360.13 d period extends the low-frequency tail dramatically). First invocation of the v0.14.1-reserved suffix-disambiguation policy: Telesto's SSaTeT2 distinguishes from Tethys's SSaTeT (both share moon-prefix Te under the same parent). C-side wire-format change: ES_N_BODIES 43 → 52; ABI v7 → v8; native binary rebuilt + parity-smoke ratchet ratcheted. The Saturnian trojans are the spectral headliner — their period equals their host moon's, giving the Laplacian eigenbasis a degeneracy that's the natural intersection point with v0.16.x's resonance-graph multi-leg find_itn_chains work. Pure-additive on the Python bridge; Native callers need ABI 8 (the rebuilt native ships in the v0.16.0 wheel). New test modules test_saturnian_trojan_sol_moon_times.py (4 trojans, 12 tests) + test_jovian_irregular_sol_moon_times.py (3 irregulars, near-resonance pin) + extended test_neptunian_sol_moon_times.py (Triton + Proteus + Nereid). 601 tests pass, 41 skipped (was 514 + 41 in v0.15.0; +87 new — parametrize amplification across 4 trojans + 3 irregulars + 3 Neptunians).
• v0.15.0 — Sol Moon Times: classical-roster completion (Pluto-Charon + remaining major Uranian moons) — 38-body roster expanded to 43. Closes task `#86` for the IAU-major moon roster: every classical moon discovered between 1787 and 1948 now has a Sol Time wrapper. Adds 5 new bodies + 5 forward + 5 inverse bridge wrappers + 5 CLI subcommands: Miranda SUrMiT, Ariel SUrArT, Umbriel SUrUmT, Oberon SUrObT (the four classical Uranian moons not in v0.14.2), and Charon SPlChT (Pluto's largest moon — mutually tidally locked, the only such 1:1:1 spin-orbit lock in the solar system; mass ratio Charon:Pluto ≈ 0.12 → Pluto-Charon barycentre lies outside Pluto, making the pair more like a binary planet than a planet-with-moon). SUrMiT vs SSaMiT is the v0.15.0 second-instance disambiguation case — same shared-moon-prefix pattern as the v0.14.2 SUrTiT/SSaTiT pair, exactly the disambiguation the v0.14.1 6-letter policy was designed to provide. C-side wire-format change: ES_N_BODIES 38 → 43; ABI v6 → v7; native binary rebuilt + parity smoke ratchet ratcheted. New test module test_plutonian_sol_moon_times.py for the binary-planet edge case (mutual tidal lock means sidereal == synodic == spin period; no separate synodic correction needed). 512 tests pass, 41 skipped (was 497 + 4; +56 new — 5 Plutonian + 4 expanded Uranian + 10 parity-smoke entries + parity-smoke tier shape variations). With v0.15.0 the Sol Moon Times series covers all 5 classical Uranian moons + every IAU-named moon in the 43-body roster except those that don't yet have BODIES entries (Pluto's smaller satellites Nix, Hydra, Kerberos, Styx are queued; the small Saturnian and Jovian satellites past the v0.14.x ships likewise queued).
• v0.14.2 — Sol Moon Times: remaining 8 moons across 4 parent families (Mars, Jovian inner regulars, Uranus, Neptune). Closes task `#86` for the current 38-body roster. Adds 8 Sol Moon Times: Phobos SMaPhT + Deimos SMaDeT (Mars); Metis SJuMeT + Adrastea SJuAdT + Amalthea SJuAmT + Thebe SJuThT (Jupiter inner regulars — ring-shepherd + Voyager-discovery moons); Titania SUrTiT (Uranus — only Uranian moon currently in BODIES); Triton SNeTrT (Neptune — captured Kuiper Belt object, only large retrograde moon in the solar system). All 8 follow the v0.14.1 6-letter S<Planet2><Moon2>T convention; SUrTiT vs SSaTiT (Uranus's Titania vs Saturn's Titan) is exactly the disambiguation the policy was designed to provide. Encoder convention documented for Triton: period_days is positive (we encode omega = +2π/P for ALL bodies regardless of prograde/retrograde direction; retrograde-ness is metadata, not a sign flip — same convention as v0.5.4 Sol Uranian Time). Generic _add_moon_subparser CLI helper supersedes the v0.14.0/v0.14.1 family-specific helpers. Built via 4 parallel subagent worktrees (one per family) integrated by the parent agent into a single bridge.py / cli.py / parity-smoke ship — first multi-agent ship in this repo. Pure-additive; no API / encoder / ABI / encoder-test changes. 497 tests pass, 4 skipped (was 399 + 4; +98 new — 2 Martian + 4 Jovian-inner + 1 Uranian + 1 Neptunian moon-test modules + parity-smoke entries).
• v0.14.1 — Sol Moon Times: Saturnians (11 moons) + abbreviation policy switch (4-letter → 6-letter). Second slice of `#86`. The contingency policy from v0.14.0's ROADMAP fired exactly as predicted: Saturnians introduced two collisions under the v0.14.0 4-letter S<Planet><Moon>T pattern (Tethys + Titan both 'T' → both SSTT; Enceladus + Epimetheus both 'E' → both SSET). Per the policy, the switch applies uniformly across all Sol Moon Times — Galileans retroactively renamed (SJIT → SJuIoT, SJET → SJuEuT, SJGT → SJuGaT, SJCT → SJuCaT); 11 Saturnians ship with 6-letter abbreviations (Mimas SSaMiT, Enceladus SSaEnT, Tethys SSaTeT, Dione SSaDiT, Rhea SSaRhT, Titan SSaTiT, Hyperion SSaHyT, Iapetus SSaIaT, Phoebe SSaPhT, Janus SSaJaT, Epimetheus SSaEpT). Python function names + CLI subcommand names + return-shape unchanged; only the epoch.abbreviation string changes. Resonance witnesses verified in tests: Mimas-Tethys 4:2 (Cassini Division), Enceladus-Dione 2:1 (tidal heating), Titan-Hyperion 4:3 (chaotic rotation), Janus-Epimetheus co-orbital. Hyperion footnote: chaotic rotation means sidereal_period_days references the orbital period; rotation-phase coupling decoupled (open research). 399 tests pass, 4 skipped (was 294 + 4; +105 new).
• v0.14.0 — Sol Moon Times: Galileans (Io / Europa / Ganymede / Callisto). First slice of task `#86` — extends the Sol Time hierarchy to non-Luna moons under the moons-stuck-to-parent Sol <Parent>-<Body> Time naming convention from v0.9.1. New generic MoonTime primitive in _research/time_scales.py (body-agnostic; caller-supplied parent + sidereal period) + four per-Galilean bridge wrappers (jd_to_sol_jupiter_io_time, ..._europa, ..._ganymede, ..._callisto) with abbreviations SJIT, SJET, SJGT, SJCT + four CLI subcommands (time-jupiter-io, time-jupiter-europa, time-jupiter-ganymede, time-jupiter-callisto) sharing a _add_galilean_subparser helper for consistency. Default epoch is J2000.0 — STLT's Greek-historical anchors don't generalise to non-Luna moons; Galileo's 1610 telescopic discovery is a candidate non-default for a future ship. Galilean Laplace-resonance witness (canonical form n_Io − 3·n_Europa + 2·n_Ganymede ≈ 0) verified in the test module; Callisto correctly identified as the only Galilean NOT in the resonance. Naming convention contingencies added to ROADMAP: if moon-letter collisions arise in future ships (Saturnians, etc.), the fallback policy switches uniformly across all Sol Moon Times to a 6-letter S<Planet2><Moon2>T pattern (e.g., SJuGaT). Pure-additive; no API / encoder / ABI / encoder-test changes. 294 tests pass, 4 skipped (was 251 + 4; +43 new — 35 Galilean tests + 8 parity-smoke entries).
• v0.13.10 — Drop edited from docs-check workflow trigger types — fixes post-merge double-fire. User-flagged on PR `#214` (v0.13.9 ship): the docs-check workflow was double-firing at every merge time. Two pull_request events fired at the same second ~3 seconds before merge committed; concurrency-cancel caught it (one CANCELLED, one SUCCESS) but the wasted CI churn + confusing run-history was observable. Root cause: GitHub web UI's "Squash and merge" fires pull_request: edited (merge-commit dialog populates title/body) near-simultaneously with pull_request: synchronize (GitHub recomputes the refs/pull/N/merge preview ref). Fix: drop edited from the trigger types — now [opened, synchronize, reopened, labeled], matching the narrower trigger list used by ephemerides-spectral-ci.yml (which never had this issue). Trade-off: [skip-docs-check] opt-out added retroactively (by editing the PR body post-open) no longer triggers a re-run; user pushes a synchronizing commit or accepts the stale advisory. Acceptable — opt-out should be set up-front. CI-only change; no code / API / encoder / ABI / test changes. 251 tests pass, 4 skipped.
• v0.13.9 — JPL Power-of-Ten Rules 6 + 7 manual audits — final patch in the v0.13.4-v0.13.9 rule-fix sequence; ALL TEN RULES NOW SATISFIED. Audit-only release; no code changes; 0 violations found for both Rule 6 (smallest possible scope for data) and Rule 7 (check return values, validate parameters). The v0.11.2 spot-check estimates of "5-10 violations across es_encode.c + es_parity.c" (Rule 6) and "5-15 sites where rc is assigned but not checked" (Rule 7) didn't survive the incremental tightening in v0.13.4-v0.13.6: long-function splits relocated state into helper-scope; assertion work added const-near-use patterns throughout; cleanup-on-error refactor unified the rc-check pattern (es_status_t rc = ...; if (rc != ES_OK) return rc;). Audit walked every variable declaration (loop iterators block-scoped; const declarations near use; remaining function-scope declarations are intentional accumulators / sqrt caches / output buffers / result variables) and every es_status_t assignment (8 sites, each checked on the next line). All ten JPL Power-of-Ten rules now satisfied (Rules 1, 3, 4, 5 pinned in test_jpl_audit.py; Rule 10 enforced by pedantic-build 3-cell CI matrix; Rules 6+7 manual audits clean; Rules 2, 8, 9 already-passing at v0.11.2 baseline). 251 tests pass, 4 skipped (unchanged).
• v0.13.8 — README accuracy patch — two-stage architecture clarification. User-flagged misunderstanding about "pure ALU": the previous README listed three backends as if they were full alternatives, with complex128 annotated as "used for syzygy operator, observer binding" — but since v0.7.0 (Tier 2b) the production HD path is C-side complex64, with complex128 retained as backend="fpu-ref" for regression. The README now splits the architecture into two stages: (1) integer-ALU phase-residue encoders (bip / c / complex128 reference) producing uint32[38] residues, and (2) FPU HD pipeline (complex64 production / complex128 regression baseline) for syzygy / observer-bind / eclipse-probability — which is necessarily FPU because channel bases are unit-magnitude complex. Adds a "TL;DR on pure ALU" callout: phase residues are integer ALU end-to-end; HD operations can't be (complex bases require trigonometric channels). Docs-only release; no API / encoder / ABI / test changes. 251 tests pass, 4 skipped.
• v0.13.7 — JPL Power-of-Ten Rule 10 fixes — cross-platform pedantic-build CI matrix. Fourth code-quality patch in the v0.13.4-v0.13.8 rule-fix sequence. New ES_PEDANTIC=ON CMake option elevates the existing -Wall -Wextra -Wpedantic (gcc/clang) and /W4 (MSVC) flags to errors via -Werror / /WX. Default OFF (casual local builds stay friendly); the new pedantic-build job in .github/workflows/ephemerides-spectral-ci.yml turns it ON across a 3-cell matrix (Linux gcc, macOS clang, Windows MSVC) so any new compiler warning fails CI. Always-on (not gated by the wheel-check label) — Rule 10 is a permanent invariant, not a per-PR opt-in. Per Holzmann: "All code must compile, from the first day of development, with all compiler warnings enabled at the compiler's most pedantic setting. All code must compile with these settings without any warnings." Local MSVC /W4 /WX build verified clean. All five mechanically-enforceable JPL rules now satisfied (Rules 1, 3, 4, 5, 10). Remaining JPL roadmap: Rules 6+7 (manual scope + return-value audits, v0.13.8). No public API change, no ABI change (still v6); CI-only addition. 251 tests pass, 4 skipped.
• v0.13.6 — JPL Power-of-Ten Rule 5 fixes — assertion density at 2/function average. Third code-quality patch in the v0.13.4-v0.13.8 rule-fix sequence. 88 assertions added across 42 functions = 2.10/function average (target ≥2.0). Assertions are gated behind standard <assert.h> NDEBUG semantics — production builds (compiled with -DNDEBUG) strip them entirely; assertions are a development-time documentation tool, not a runtime cost. Coverage: pre-conditions on parameters (assert non-NULL after runtime ptr-check; assert index in range), post-conditions on results (assert output finite/bounded where applicable), invariants (assert D > 0, assert n_patches <= ES_MAX_PATCHES, assert loop-iteration bounds). The test_rule_5_density_meets_2_per_function ratchet test flips from SKIP to PASS. PIN_RULE_5_ASSERTIONS ratcheted UP 0 → 88. Total mechanically-detectable violations: 102 → 0 — every Rule 1-5 violation in the v0.11.2 audit baseline now cleared in three ships. Remaining JPL roadmap: Rule 10 (pedantic-build matrix, v0.13.7), Rules 6+7 (manual scope + return-value audits, v0.13.8). No public API change, no ABI change (still v6); pure additive instrumentation. Encoder math byte-identical — parity smoke green. 250 tests pass, 4 skipped (was 5; Rule 5 density test no longer skips).
• v0.13.5 — JPL Power-of-Ten Rule 4 fixes — long-function splits. Second code-quality patch in the v0.13.4-v0.13.8 rule-fix sequence. The 4 functions over 60 lines from the v0.11.2 audit (es_encode_state 109; es_find_syzygies 99; es_bind_observer 78 post-v0.13.4; es_get_eclipse_probability 65 post-v0.13.4) split into JPL-compliant factors via 10 new static internal helpers along natural algorithm seams: apply_one_chunk + apply_subchunk_remainder (encoder), select_syzygy_targets + score_syzygy_event + validate_syzygy_args + emit_syzygy_event (parity), observer_coord_shift + apply_observer_bind + build_syzygy_operator + complex64_vdot_magnitude (HD pipeline). Rule 4 count drops 4 → 0. No public API change, no ABI change (still v6); pure refactor. Encoder math byte-identical — parity smoke pins both backends to within float-ULP and stays green. Total mechanically-detectable violations: 102 → 64 (37% of audit baseline cleared across v0.13.4 + v0.13.5). Remaining: Rule 5 (assertion density, v0.13.6), Rule 10 (pedantic-build matrix, v0.13.7), Rules 6+7 (manual scope + return-value audits, v0.13.8). 250 tests pass, 5 skipped.
• v0.13.4 — JPL Power-of-Ten Rule 1 + Rule 3 fixes — first code-quality patch in the v0.13.4-v0.13.8 rule-fix sequence. Caller-supplied-scratch refactor of c/src/es_hd_state.c eliminates both classes of violation in a single pass: goto count drops 5 → 0 (Rule 1 cleared) and malloc/free count drops 29 → 0 (Rule 3 cleared). The C library no longer calls dynamic allocators after init; <stdlib.h> is no longer included. The HD pipeline's three entry points (es_encode_state_hd, es_bind_observer, es_get_eclipse_probability) gain caller-supplied scratch-buffer parameters; the Python ctypes shim allocates them alongside the existing out_state buffer (no observable heap-pressure change — Python was already heap-allocating the output). ABI v5 → v6 (mechanical wire-format change; encoder math byte-identical to v0.13.3 — parity smoke pins both backends to within float-ULP). Total mechanically-detectable violations: 102 → 68 (33% of audit baseline cleared in one ship). Remaining: Rule 4 long functions (v0.13.5), Rule 5 assertion density (v0.13.6), Rule 10 pedantic-build matrix (v0.13.7), Rules 6+7 manual audits (v0.13.8). User-facing Python bridge surface unchanged. 250 tests pass, 5 skipped.
• v0.13.3 — Pre-merge docs+parity hygiene check (soft-warning GitHub Actions workflow). Closes task `#98` (consolidated; absorbs `#87` + `#88`). New .github/workflows/ephemerides-spectral-docs-check.yml runs on every PR touching the package; classifies code-side changes (version bumps, bridge.py, cli.py, _research/*.py, c/src/*.c / c/include/*.h) against the five PyPI-facing docs files (python/README.md, python/CHANGELOG.md, CHANGELOG.md, ROADMAP.md, ephemerides_spectral_research_notebook.md); posts (or updates in place) a single PR comment summarising the gap. Soft-warning, never fails the build — the existing pytest freshness ratchet (test_native_version_string_matches, test_parity_smoke::PARITY_TARGETS, test_readme_freshness, test_jpl_audit) hard-fails on the highest-value drift modes; this workflow surfaces the next tier — prose-and-narrative drift that humans should review but a regex can't authoritatively adjudicate. Opt-out: [skip-docs-check] in the PR body silences on cosmetic / typo / formatting-only diffs. Comment idempotence: peter-evans/find-comment + peter-evans/create-or-update-comment update one advisory in place rather than spamming the PR. Concurrency: cancel-in-progress: true keyed by workflow + ref absorbs the opened+labeled double-fire pattern documented in ephemerides-spectral-ci.yml. CI-only addition; 250 tests pass, 5 skipped.
• v0.13.2 — Add _native/ to repo .gitignore; renumber JPL rule-fix roadmap to v0.13.4-v0.13.8. Quick-win patch addressing task `#85` (_native/ directory holds compiled DLL/SO files that rebuild on every cmake --build; never belongs in source control). One line added to .gitignore. Also patches c/JPL_AUDIT.md's roadmap section: the original v0.11.3-v0.11.7 numbering is obsolete since the project moved past v0.11.x; the rule-fix patches are renumbered to v0.13.4 (Rule 1+3), v0.13.5 (Rule 4), v0.13.6 (Rule 5), v0.13.7 (Rule 10), v0.13.8 (Rules 6+7). v0.13.3 reserved for `#98` (consolidated docs+parity hygiene check; absorbs `#87` + `#88`). 248 tests pass, 5 skipped.
• v0.13.1 — SPICE feature-gap audit + STLT-naming hygiene. Docs-only release; no API / encoder / ABI changes. New figures/spice_feature_audit.md answers "what does SPICE do that we don't, and is a compat bridge worth shipping?" — three-column comparison + recommendation (skip the compat-bridge; document the gap). Spawns a v0.14.x backlog: light-time + stellar-aberration corrections, frame transformations, full Kepler elements, per-body pole orientation. STLT naming hygiene: the abbreviation table promotes Luna's primary Sol Time from SLT (surface clock) to STLT (anchored Lunar synodic count) per the moons-stuck-to-parent Sol <Parent>-<Body> Time convention; SLT is preserved as a secondary alternative for the surface-clock case. Drops "system clock for the Terra-Luna pair" framing throughout active code (CHANGELOG history entries preserved as artefacts of how v0.10.0 was framed at the time). Tests unchanged at 248 + 5 skipped.
• v0.13.0 — Sol Dynamics — system energy budget, per-body energies, pair-wise gravitational forces. Augmented onto every time-* subcommand via --dynamics. Counterpart to v0.12.0's Kinematics; mirrors chess-spectral's qm_*_dynamics.py dynamics layer (Hamiltonian + evolution + force/energy queries). New bridge.get_dynamics() (system aggregate), bridge.get_force_between(a, b) (Newtonian pair force, validated against the textbook 3.54×10²² N Earth-Sun figure to 0.01 %), bridge.get_body_energies(body) (per-body KE + PE + total), and bridge.apply_dynamics_correction() (CLI post-processor). New standalone dynamics CLI subcommand with three modes: system aggregate (default), per-body (--body X), pair-force (--body X --from Y). Total system energy −1.98×10³⁵ J (gravitationally bound; virial theorem holds to 0.5 %). All three augmenting flags --proper + --state + --dynamics compose without conflict. 248 tests pass (was 212 + 34 new dynamics tests + 2 freshness drift catches).
• v0.12.0 — Sol Kinematics — per-body orbital state, transparently augmented onto every time-* subcommand via --state. Mirrors chess-spectral's qm_*.py kinematics layer (static observables, no time-evolution; the dynamics counterpart ships as v0.13.0). New bridge.get_kinematic_state(body, ...) + bridge.get_full_system_state(...) primitives + standalone kinematics --body X / kinematics --all CLI subcommand. Validated against NASA fact-sheet orbital velocities: Mercury 47.87 vs. 47.36 (1.1 %), Earth 29.785 vs. 29.78 (0.02 %), Mars 24.13 vs. 24.07 (0.25 %), Jupiter 13.06 vs. 13.07 (0.08 %), Pluto 4.741 vs. 4.74 (0.02 %). System totals reproduce the famous "Jupiter holds 61 % of total angular momentum" and "outer planets hold 99.84 % of planetary L" facts to within 0.02-2.5 %. Phase A research script + markdown report (figures/kinematics_dynamics_audit.md) committed first; Phase B canonical primitive ships with two independent implementations agreeing on the 9 published values. New _research/kinematics.py codegened into the package alongside proper_time.py. 212 tests pass (was 182 + 30 new kinematics tests).
• v0.11.2 — JPL Power-of-Ten audit baseline for the C library (audit-only; no code changes yet). Documents 102 mechanically-detectable violations rule-by-rule in c/JPL_AUDIT.md: 5 goto (Rule 1), 29 malloc/free (Rule 3), 4 functions over 60 lines (Rule 4), 64-assertion shortfall (Rule 5). Pins the counts in tests/test_jpl_audit.py as a one-way ratchet — counts can only go DOWN; PRs that increase them fail loudly. Same modular discipline as test_native_version_string_matches_package_version, test_parity_smoke.py::PARITY_TARGETS, and test_readme_freshness.py. Rules 2 (fixed loop bounds), 8 (limited preprocessor), 9 (no function pointers) already pass clean. Rule-by-rule fixes ship in v0.11.3+ as separate code-quality minors. Reference: Holzmann 2006, IEEE Computer. 182 tests pass.
• v0.11.1 — Research notebook hygiene: backfill §7.4 (STLT) and §7.5 (SPrT) sections + refresh Status banner. v0.10.0 STLT and v0.11.0 SPrT shipped without their notebook subsections; this is the doc-only catch-up. Triggered by user noticing the gap. Task #98 captures the broader follow-on (a soft "docs probably need updating" warning on PRs that touch code without touching docs — would have caught this gap automatically). 171 active tests pass; identical to v0.11.0.
• v0.11.0 — Sol Proper Time (SPrT) — --proper flag on every time-* subcommand applies gravitational + orbital-kinematic time dilation transparently. New bridge.get_proper_time_rate(body, ...) and bridge.compare_proper_times(a, b, ...) primitives; new time-proper standalone subcommand for the rate-only query. Same physics as Mercury's existing 43″/century PN diagonal correction, applied per-body to all 38 bodies in the roster — the user's framing was "gravitational time dilation fiber so users don't even need to know anything extra had to happen in the back end." Six published values (Earth GR, Sun GR, Mars GR, Pluto GR, Earth orbital kinematic, Mars-vs-Earth GR difference) reproduced to within 0.30%; the 0.0175 s/Earth-year Curiosity-rover Mars-Terra clock-rate figure verified inline. New surface_radius_km per body in bodies.py. 32+ new tests in test_sprt.py pin every component + the CLI surfaces. Phase A research: research/proper_time_rates.py + figures/proper_time_rates.md.
• v0.10.0 — Sol Terra-Luna Time (STLT) — anchored Lunar time using the synodic month, with Meton's 432 BCE summer solstice as the default epoch. First Sol Time member with a non-J2000 default anchor; primary lunar-time entry per the moons-stuck-to-parent Sol <Parent>-<Body> Time naming convention. New bridge.jd_to_sol_terra_luna_time(jd_tdb, *, epoch="meton") + sol_terra_luna_time_to_jd(...); new CLI time-terra-luna with --epoch {meton, antikythera, hipparchus, mardokempad, j2000}. Synodic month is the natural unit; Saros (18.03 yr) and Metonic (19.00 yr) cycle counts come along for free. Anchor choice is empirically validated: the Hipparchus-Babylonian eclipse-archive midpoint (Mardokempad 721 BCE + Hipparchus 141 BCE) lands within +240 days of Meton's solstice — same year, eight months later — confirming Meton sits at the center of mass of Greek astronomical tradition (the "combo" candidate test from research/lunar_epoch_candidates.py). Also fixes the find_syzygies(backend="auto") latent bug class (same as v0.9.2's get_breathing_modulation fix). House-epoch design choice; not a claim to be NASA's eventual LCT.
• v0.9.3 — PyPI-facing README staleness sweep + CI freshness check. Status section refreshed (8 versions of accumulated drift); Roadmap section pruned of items that have already shipped (Tier 2b, Sol Venusian/Mercurian Time, ITN pathway / find-tubes); leftover earth-body CLI examples corrected to terra; "Phase 9 'Breathing' Couplings" heading inverted to "Phase 9 Adaptive Couplings (a.k.a. 'breathing')" matching the v0.9.2 CLI rename. New tests/test_readme_freshness.py enforces three drift-prevention invariants: every CHANGELOG version must appear in this Status section; the banner under the H1 must equal __version__; every CLI body-name flag in an example must reference a name in SUPPORTED_BODIES. Same discipline as test_native_version_string_matches_package_version and test_parity_smoke.py::PARITY_TARGETS — enumerate the truth, fail on drift.
• v0.9.2 — CLI: adaptive is the primary subcommand for state-dependent coupling modulation; breathing retained as a hidden synonym (help=argparse.SUPPRESS). Matches the adaptive-networks vocabulary (Gross & Blasius 2008; adaptive Kuramoto family). Both names work; new users discover adaptive via --help, visual-metaphor users keep typing breathing. Latent bug fixed in passing: bridge.get_breathing_modulation(backend="auto") was rejected by _validate_backend (sentinel not in SUPPORTED_BACKENDS); resolved before validation now, matching the docstring contract. The breathing CLI subcommand has been broken since v0.8.0 — now fixed.
• v0.9.1 — Sol Time naming convention overhaul + Sol Terra Time + Sol Luna Time. Direct Latin proper noun (Mercury, Venus, Pluto, Terra, Luna, Sol) for rocky bodies + Sun + Luna; established adjective form (Jovian, Saturnian, Uranian, Neptunian) for gas/ice giants. Renames (BREAKING): jd_to_sol_mercurian_time → jd_to_sol_mercury_time; same for venusian → venus, plutonian → pluto. New (additive): Sol Terra Time (STT, Terra's surface clock) + Sol Luna Time (SLT, Luna's tidally-locked surface clock; distinct from Sol Lunar Time which gives Luna's phase observed from Terra).
• v0.9.0 — Body identity rename: moon → luna, earth → terra. BREAKING. Latin proper nouns for body identity strings; generic English moon (= any natural satellite) and earth (= soil/ground) return to their generic meanings. BODIES["luna"] / BODIES["terra"] replace the old keys. _data/initial_phases.json re-keyed (encoded phase residues unchanged at any JD). C-side es_bodies table re-emitted via codegen. JPL/skyfield kernel boundary handled via EphemerisBundle.lookup() translation map. Encoder hot path byte-identical to v0.8.1.
• v0.8.1 — ITN pathway / Lagrange-tube query — find-tubes first cut. "Surfing the perturbations": closed-form Hohmann transfer-window enumeration mirroring v0.3.1's find-syzygies discipline. Earth → Mars sanity: 23 windows over J2000 + 50 yr at threshold 0.02; 258.87-d transfer time and 5.594 km/s Δv match textbook Hohmann to 0.01% / 0.1%.
• v0.8.0 — Sol Symphony Times: 7 new planetary/stellar time systems. Venus, Mercury, Pluto, Sol (the Sun!), Jupiter, Saturn, Neptune join Mars / Lunar / Uranian. Special quirks honored: Mercury 3:2 spin-orbit resonance (solar day = 2 Mercury-years exactly); Venus retrograde with sidereal day longer than year; Sol differential rotation (Carrington Rotation Number); Saturn Cassini-revised rotation (Mankovich 2019).
• v0.7.0 — C/Python parity Tier 2b — full HD pipeline in C (ABI v5). Three new C entry points: es_encode_state_hd, es_bind_observer, es_get_eclipse_probability. Bridge dispatches get_local_view and get_eclipse_probability on backend={"auto","bip","c","fpu-ref"}. Every encoder-touching bridge method now has a paired C path; the v0.6.0 parity discipline is fully realised.
• v0.6.1 — Tier 2a foundation: portable channel-basis PRNG (ABI v4). Splitmix64 PRNG bit-identical between Python + C; es_channel_basis(seed, out, D) produces byte-identical complex64 hypervectors on both sides. Foundation for v0.7.0's HD encode pipeline.
• v0.6.0 — C/Python parity Tier 1 + always-on parity smoke test (ABI v3). find_syzygies and get_breathing_modulation now have C twins; bridge dispatches on backend={"auto","bip","c"}. New tests/test_parity_smoke.py enumerates every encoder-touching bridge.* method in a PARITY_TARGETS table — adding a new bridge method without a parity classification fails CI.
• v0.5.5 — Moon catalog patches (Phase C). Five LS-fit-vindicated moon entries join CATALOG_V2: dione (98.2%), tethys (93.8%), enceladus (98.9%), titan (95.5%), iapetus (98.6%). Methodology vindicated twice on independent body sets: planets at 96-99%, moons at 93-99%.
• v0.5.4 — Sol Uranian Time (SUT) — third planetary time system alongside Mars / Lunar. CLI --help audit across all subcommands.
• v0.5.3 — Moon residuals: 13 of 17 fixed. Period-truncation root cause confirmed via per-orbital-period diagnostic. Fix: 9+-decimal sidereal periods from JPL HORIZONS / NASA fact sheets. Galileans drop from 100°→<1° RMS.
• v0.5.2 — Patch-shrinks-residual benchmark VINDICATED on planets via LS-fit catalog (Mars 99.2%, Mercury 99.9%, J–S 97.6/96.0%). CATALOG_V2 ships alongside v0.4.0. Moon-kernel infrastructure added.
• v0.5.1 — Patch-shrinks-residual benchmark: PARTIAL vindication (J–S 77%, Mercury 40%, Mars stuck on FFT leakage); two v0.4.0 authoring bugs surfaced.
• v0.5.0 — All major Jovian + Saturnian moons join the encoder (26 → 38 bodies). Three new resonances (Cassini Division, Enceladus tidal heating, Hyperion chaos). SPICE-free runtime via codegen-baked initial phases.
• v0.4.1 — C-side runtime kernel patching (ABI v2). 237× speedup on patched encodes vs BIP.
• v0.4.0 — Diagnosed-fiber runtime overlay (Python side). Patches as data, ksplice/kpatch-style.
• v0.3.1 — C-in-wheel + spectral syzygy window search + DE441 error-spectrum FFT.
• v0.3.0 — Mars Sol Date / Mars Coordinated Time, mean lunar primitives, LTE440 awareness, DE441 full-epoch sweep, natural-resonance gear group.
• v0.2.0 — Phase 9 coverage extension to four resonance pairs (J–S 5:2, N–P 3:2, Io–Europa 2:1, Europa–Ganymede 2:1).
• v0.1.0 — first PyPI release. 26-body Sol Star System Laplacian + Phase 9 adaptive ("breathing") couplings + ALU-native BIP encoder.

Roadmap

Items genuinely still ahead (everything previously listed under "in progress" v0.7.0, "Sol Venusian/Mercurian Time," "ITN pathway / Lagrange-tube query (first cut)," and "Sol Moon Times completion (IAU-major roster)" has shipped — see Status above for landing versions):

• v0.16.0 — Tier-1 BODIES expansion (43 → 52) — Themed as "Lagrange-trojan + retrograde-irregular + Neptune sub-graph completion." Adds: 4 Saturnian Lagrange trojans (Helene at Dione L4, Polydeuces at Dione L5, Telesto at Tethys L4, Calypso at Tethys L5 — the roster's first L4/L5 entries), 2 Jovian retrograde irregulars (Pasiphae, Sinope — second retrograde marker beyond Triton), Jupiter's Himalia (largest prograde irregular), and Neptune's Proteus + Nereid (sub-graph completion). The Lagrange trojans are the spectral headliner: their period is identical to their parent moon's, giving the Laplacian a multiplicity-2 degeneracy at the L4/L5 frequency — the natural place where the Lagrange-highway research thread (below) intersects BODIES directly. Mirrors the v0.14.x ship pattern (BODIES additions + bridge wrappers + CLI subcommands + test modules + native rebuild + ABI v7 → v8). See ephemerides_spectral_research_notebook.md §11 for the full audit.
• v0.16.x — Resonance-graph multi-leg find_itn_chains — the natural extension of the v0.8.1 Hohmann anchor. Searches the (body, epoch, heliocentric-energy-bucket) graph using Dijkstra/A* with Hohmann Δv as edge cost; each leg carries a per-leg integer (p, q) gear-ratio resonance signature. Stays in the integer-ALU + FPU pipeline discipline (no CR3BP integrator). API sketch: find_itn_chains(jd_lo, jd_hi, *, departure, target, dv_budget_kms=30.0, max_legs=4) -> List[ITNChainCandidate] with per-leg resonance_signature: Tuple[Tuple[int, int], ...]. Same minor adds L1/L2 gateway designation + Jacobi constant (closed-form Newton on the collinear quintic) + Richardson 1980 third-order halo-orbit amplitudes as supplementary fields on the existing ITNCandidate. See research notebook §12 for the full survey.
• v0.17.x — Gateway-graph Laplacian + heteroclinic search — largely unexplored in published literature. Build a graph whose nodes are (body, L_i, halo-family-index) tuples and whose edges are heteroclinic Δv-cost weighted connections, then ask whether its Fiedler partition agrees with empirical low-Δv accessibility classes. If yes, the spectral lens has earned its keep on ITN. Anderson & Lo 2009 and Topputo et al. treat the manifold network as a graph but do not analyse it spectrally. Likely a short paper's worth of work.
• First-principles per-resonance α — replaces phenomenological α = 0.1 with values derived from a Hamilton/Delaunay-variable Lagrangian (Lie-series perturbation theory around each resonance). The DE441 sweep is the empirical motivation: bodies inside the resonance set phase-scramble at multi-millennium horizons because their α values are wrong-in-detail. The v0.5.5 LS-fit catalog patches are the empirical analog — Fourier-correction overlays that first-principles α should ultimately make redundant for bodies inside the resonance set.
• Hyperion follow-up — multi-component patch or coupled titan-hyperion-4to3-coupled-v2. The single-sinusoid Hyperion patch hits 75% (chaos ceiling); a coupled / multi-component patch should clear the 80% gate.
• Remaining 4 broken moons (metis / thebe / rhea / phoebe). Phoebe needs sign-aware retrograde encoder; Metis needs an authoritative period; Thebe + Rhea look perturbation-driven.
• Tier-2 / Tier-3 thematic ships (deferred from the v0.16.0 audit): resonance-chain shepherd-cluster ship (4 Plutonian small moons in the Charon 3:4:5:6 chain; 5 Saturnian shepherds Pan/Daphnis/Atlas/Prometheus/Pandora); inner-Uranian + inner-Neptunian close-packed ring-system entry; outer-system dwarf-planet ship (Eris, Makemake, Haumea, Sedna, Quaoar with their moons); mission-visited asteroid ship (Eros, Itokawa, Bennu, Ryugu).
• DE441 vs DE442 spectral error signature (experiment) — build two BIP instruments, one calibrated only from DE441, one only from DE442; encode the same JD on both; project the per-body residue deltas onto the encoder's eigenbasis. If the deltas have a coherent spectral signature, DE442's corrections to DE441 live in a specific eigenmode subspace — which means we could predict where ephemeris error correction is structurally needed without needing the corrected kernel.
• LTC (Lunar Coordinated Time) — pending NASA + international space-agency standardisation (target ~2026–2028 per April 2024 White House directive). LTE440 (Lin et al. 2025) ships the underlying SPICE-format conversion ephemeris with 0.15 ns accuracy through 2050; the bridge gains an LTC namespace mirroring MarsTime once the LTC epoch + day-length convention are formalised.
• Phase 10 resonance coverage — Jupiter–Uranus 7:1, Saturn–Uranus 3:1, Saros / Metonic / Terra–Luna precession entries. Each adds a row to the RESONANCES table; the integer-LUT machinery is shared.
• Multi-millennium DE441 sweep with the v0.5+ resonance-corrected encoder. Re-derive Metonic and Saros anchors against the full 3.3 GB DE441 with adaptive ("breathing") couplings active.
• Doxygen for ephemerides-spectral C public API — every entry point in c/include/ephemerides_spectral.h documented in the standard Doxygen style for downstream embedded / WASM consumers.
• Bit-serial hardware port (Verilog/SystemC) — the cosine LUT becomes block RAM, the omega * step becomes a fixed-precision multiplier.

License

GPL-3.0-or-later.