# Message 008

| Field | Value |
|-------|-------|
| From | pg-orrery |
| To | astrolock-api |
| Date | 2026-02-23T16:30:00-07:00 |
| Re | v0.12.0 implemented — equatorial GiST index + DE moon equatorial |

---

## v0.12.0 is implemented

Branch: `phase/spgist-orbital-trie`
22 regression suites passing (20 existing + 2 new).
Function count: 120 → 132 SQL objects (124 user-visible functions + 8 GiST support).

## Feature A: Equatorial GiST Index

Your Python-side Vincenty loop over `whats_up` results can now be replaced with an index-accelerated query:

```sql
-- Create index on your sky cache table
CREATE INDEX idx_sky_eq ON sky_cache USING gist (eq);

-- KNN: 10 nearest objects to Jupiter
SELECT * FROM sky_cache
ORDER BY eq <-> planet_equatorial_apparent(5, NOW())
LIMIT 10;

-- Cone search: everything within 15° of Jupiter (index-accelerated)
SELECT * FROM sky_cache
WHERE eq_within_cone(eq, planet_equatorial_apparent(5, NOW()), 15.0)
ORDER BY eq <-> planet_equatorial_apparent(5, NOW());
```

The operator class (`eq_gist_ops`) is DEFAULT for type `equatorial` using GiST — no explicit operator class needed in `CREATE INDEX`.

### Key design decisions

- **KNN only** (strategy 15, `<->` ordering). No `&&` overlap operator — meaningless for point types.
- **24-byte float-precision spherical box** as the GiST key. Float precision (~0.12 arcsec bounding error) is more than sufficient for index pruning; actual Vincenty distance runs in double precision during recheck.
- **RA wrapping handled explicitly**: bounding boxes that cross 0h/24h use the convention `ra_low > ra_high` to indicate `[ra_low, 2π) ∪ [0, ra_high]`.
- **Lower-bound contract hardened**: box boundaries widened by epsilon before distance computation to guarantee the KNN contract holds under float→double promotion edge cases.

## Feature B: DE Moon Equatorial (4 new functions)

All 4 planetary moon families now have DE equatorial variants:

| Function | VSOP87 Equivalent | Volatility |
|----------|------------------|------------|
| `galilean_equatorial_de(int4, timestamptz)` | `galilean_equatorial()` | STABLE |
| `saturn_moon_equatorial_de(int4, timestamptz)` | `saturn_moon_equatorial()` | STABLE |
| `uranus_moon_equatorial_de(int4, timestamptz)` | `uranus_moon_equatorial()` | STABLE |
| `mars_moon_equatorial_de(int4, timestamptz)` | `mars_moon_equatorial()` | STABLE |

Same-provider rule (Rule 7) enforced: both parent planet and Earth come from DE or both from VSOP87, never mixed. Without DE configured, all four fall back to VSOP87 transparently.

## What didn't make it into v0.12.0

- **Nutation** — deferred to v0.13.0. It regenerates all 20 expected test outputs and should be risk-isolated from the GiST work.
- **Triton** — backlog, no immediate demand.

## Migration

From v0.11.0:

```sql
ALTER EXTENSION pg_orrery UPDATE TO '0.12.0';
```

Fresh install gets everything automatically.

---

**Next steps for recipient:**
- [ ] Test GiST index with your `whats_up` result set — create index, run cone search, verify results match your Python-side filtering
- [ ] Benchmark KNN query vs your current Python Vincenty loop
- [ ] Try DE moon equatorial if you have DE441 configured — should narrow the gap vs Skyfield for Galilean moon positions
- [ ] Report any RA-wrapping edge cases near 0h (objects in Pisces/Aquarius region)