pg_orrery/docs/TODO-v0.10.0.md

pg_orrery — Post-v0.10.0 Roadmap

Current State

Version: v0.10.0 (tagged 2026-02-22) Branch: phase/spgist-orbital-trie merged to main Functions: 114 SQL functions, 9 custom types, 19 test suites, 1 new operator Docs: https://pg-orrery.warehack.ing

What v0.10.0 shipped

• Annual stellar aberration in all _apparent() functions (~20 arcsec)
• 6 new _apparent_de() variants with VSOP87 fallback
• eq_angular_distance() + eq_within_cone() + <-> operator on equatorial
• Stellar annual parallax in star_observe_pm() / star_equatorial_pm()

Astrolock integration status

Thread: docs/agent-threads/v090-astrolock-upgrade/

• v0.9.0 fully deployed to both local and production servers
• v0.10.0 upgrade path communicated (message 003)
• Pending their upgrade — aberration improvement is automatic

Remaining Housekeeping

• Merge phase/spgist-orbital-trie to main
• Clean up bench/ — gitignore the untracked TLE catalog files (alpha5, celestrak, satnogs, spacetrack, supgp, tle_api, merged, mega)
• Update "From Skyfield" workflow page for v0.9.0/v0.10.0 RA/Dec + aberration parity
• Add timing numbers for equatorial, refraction, aberration functions to benchmarks page
• Update CLAUDE.md function count: 106 -> 114, test suites: 18 -> 19
• Update docs llms.txt and llms-full.txt for v0.10.0 functions

Feature Candidates — Next Version

Tier 1 — High value, low effort

A. make_orbital_elements() constructor

Requested by: astrolock-api (message 002, question 1)

SQL constructor from 9 floats. Lets users compose orbital_elements from individual table columns without format()/cast workaround.

make_orbital_elements(epoch_jd, q_au, e, inc_rad, omega_rad, node_rad, tp_jd, h_mag, g_slope)
    -> orbital_elements

Complexity: ~30 lines in orbital_elements_type.c. One new function.

B. galilean_equatorial() and moon family equatorial functions

Requested by: astrolock-api (message 002, question 2)

Geocentric RA/Dec for planetary moons. Follows planet_equatorial() pattern — convert geocentric ecliptic position to equatorial J2000, precess to date.

New functions (~4):

• galilean_equatorial(int4, timestamptz) -> equatorial
• saturn_moon_equatorial(int4, timestamptz) -> equatorial
• uranus_moon_equatorial(int4, timestamptz) -> equatorial
• mars_moon_equatorial(int4, timestamptz) -> equatorial

Plus DE variants (~4 more).

Complexity: ~100 lines. Follows established pattern.

C. GiST/SP-GiST index on equatorial type

The <-> operator and eq_within_cone() exist but have no index support. For cone-search queries over large catalogs, an index would enable:

-- Indexed: "what's within 10 deg of Jupiter?"
SELECT * FROM star_catalog
WHERE position <-> planet_equatorial(5, NOW()) < 10.0;

Approach: GiST with bounding-box approximation in RA/Dec space, or SP-GiST with HEALPix-style recursive decomposition.

Complexity: Medium (~300-500 lines). The SP-GiST infrastructure from TLE index is reusable.

Tier 2 — Medium value, medium risk

D. Nutation correction (~9 arcsec)

IAU 1980 nutation (106 terms) or simplified IAU 2000B.

Currently: TEME uses 4 of 106 terms. Equatorial output uses IAU 1976 precession only (no nutation).

Value: ~9 arcsec correction in equatorial coordinates. Matters for sub-arcminute accuracy — telescope GoTo mounts and catalog cross-matching.

Scope: New nutation.c + modify precess_j2000_to_date() to include nutation matrix. Risk: Touches the precession pipeline used by every equatorial function.

E. Delta T (TDB - UTC)

The "affects everything" change. Currently all time is treated as UTC with no TT/TDB distinction.

Requires IERS lookup table or polynomial approximation (Espenak & Meeus 2006).

Scope: Touch sidereal_time.h, propagation pipelines, all observation functions. Risk: High — affects every time conversion. Needs careful regression testing. Value: Improves accuracy for historical epochs (pre-2000) and future predictions (post-2030).

Already noted as deferred at sidereal_time.h:22-26.

F. Rise/set prediction for solar system objects

Like predict_passes() but for planets, Sun, and Moon. Binary search for horizon crossings.

Use cases: sunrise/sunset, moonrise/moonset, planet visibility windows. Complexity: Medium. The pass prediction binary search machinery exists but needs adaptation for much slower angular rates.

Tier 3 — Future / deferred

• Perturbed asteroid propagation — secular perturbation terms for orbital_elements (currently two-body Keplerian)
• Eclipse prediction — Moon shadow cone intersection with observer
• Satellite sunlit visibility — extend pass_visible() with Earth shadow geometry
• Constellation identification — equatorial position to IAU constellation boundary lookup
• Coordinate frame transforms — ICRS/FK5/galactic/ecliptic conversion functions

Suggested Next Phase

Housekeeping (bench cleanup, docs, CLAUDE.md)
    |
    v
Feature A: make_orbital_elements() — 30 lines, unblocks Craft comets
Feature B: moon family equatorial — 100 lines, unblocks Craft Galilean moons
    |
    v
Feature C: equatorial GiST index — enables indexed cone search
Feature D: nutation — closes largest remaining accuracy gap (~9 arcsec)
    |
    v
Feature E: Delta T — high risk, needs its own careful phase
Feature F: rise/set — new domain, independent

A + B could ship as v0.11.0. C + D as v0.12.0.

Verification

• All 19 existing regression suites must continue to pass
• New test suites for each feature
• PG 14-18 matrix (make test-matrix)
• Cross-check against JPL Horizons for nutation accuracy
• Astrolock integration smoke test after each db upgrade