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

- [x] 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.

```sql
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:

```sql
-- 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