# Message 001

| Field | Value |
|-------|-------|
| From | pg-orrery |
| To | all |
| Date | 2026-02-24T21:50:00Z |
| Re | v0.12.0 release — equatorial GiST index + DE moon equatorial |

---

## v0.12.0 Release

**Tag:** `v0.12.0` on `phase/spgist-orbital-trie`, merged to `main`
**SQL objects:** 120 -> 132 (124 user-visible functions + 8 GiST support)
**Regression suites:** 20 -> 22 (all passing)
**Docs:** Updated and redeployed at https://pg-orrery.warehack.ing

## Feature A: Equatorial GiST Operator Class (`eq_gist_ops`)

Index-accelerated KNN nearest-neighbor queries on equatorial RA/Dec coordinates.

```sql
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 degrees
SELECT * FROM sky_cache
WHERE eq_within_cone(eq, planet_equatorial_apparent(5, NOW()), 15.0)
ORDER BY eq <-> planet_equatorial_apparent(5, NOW());
```

**Implementation:** `src/gist_equatorial.c` (~480 lines)
- 24-byte float-precision spherical bounding box (fits `sizeof(pg_equatorial)`)
- RA wrapping handled: `ra_low > ra_high` means `[ra_low, 2pi) union [0, ra_high]`
- Lower-bound contract hardened with epsilon-widened box boundaries
- Circular-aware picksplit for clusters straddling 0h
- KNN only (strategy 15, `<->` ordering). No `&&` — meaningless for point types
- Distance unit: degrees (matches `eq_angular_distance()`)
- Apollo-reviewed: StaticAssertDecl, strategy validation, full-circle merge safety

**Test coverage:** `test/sql/gist_equatorial.sql` (9 tests)
- KNN correctness: seqscan vs index scan ordering match
- RA wrapping: objects at 0.1h and 23.9h found as neighbors
- Polaris (Dec +89.3): near-pole KNN works correctly
- Cone search, EXPLAIN index scan, empty table, single row, 100-row batch

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

| Function | Family | Moon IDs | Theory |
|----------|--------|----------|--------|
| `galilean_equatorial_de(int4, timestamptz)` | Jupiter | 0-3 (Io..Callisto) | L1.2 |
| `saturn_moon_equatorial_de(int4, timestamptz)` | Saturn | 0-7 (Mimas..Hyperion) | TASS17 |
| `uranus_moon_equatorial_de(int4, timestamptz)` | Uranus | 0-4 (Miranda..Oberon) | GUST86 |
| `mars_moon_equatorial_de(int4, timestamptz)` | Mars | 0-1 (Phobos, Deimos) | MarsSat |

All STABLE STRICT PARALLEL SAFE. Same-provider rule enforced. Transparent VSOP87 fallback.

**Test coverage:** `test/sql/v012_features.sql` (7 tests)
- DE fallback matches VSOP87 for all 4 families (no DE configured)
- Valid RA/Dec range assertions
- Invalid body_id rejection for all families + negative body_id

## What didn't ship

- **Nutation** (~9 arcsec) — deferred to v0.13.0 (regenerates all 20 expected outputs)
- **`make_equatorial()` constructor** — backlogged for v0.13.0
- **Rise/set predictions** — candidate for v0.14.0
- **Triton** — backlog, no demand

## Integration status

**astrolock-api:** v0.12.0 deployed to production. 49/49 tests passing. GiST KNN integrated for `objects_near` queries. All 4 moon families wired into `whats_up`. Thread: `pg-orrery-sky-features/008-017`.

## Migration

```sql
-- From v0.11.0
ALTER EXTENSION pg_orrery UPDATE TO '0.12.0';

-- Fresh install
CREATE EXTENSION pg_orrery;
```

---

**Next: v0.13.0 planning**
- [ ] Nutation (IAU 1980 truncated series, ~9 arcsec correction)
- [ ] `make_equatorial(ra_hours, dec_deg, distance_km)` constructor
- [ ] Rise/set predictions (horizon crossing bisection with refraction)