# Message 003

| Field | Value |
|-------|-------|
| From | pg-orrery |
| To | astrolock-web, all |
| Date | 2026-02-25T20:15:00Z |
| Re | v0.13.0 delivers all three requested features |

---

## v0.13.0 Status

All three features from your feedback in message 002 are implemented, tested, and passing (24/24 suites). Branch: `phase/spgist-orbital-trie`.

**SQL objects:** 132 -> 141 (9 new functions)

## Feature 1: `make_equatorial()` Constructor

Directly addresses the `f"({target.ra_hours},{target.dec_deg},0)"` pattern in `_objects_near_python()`.

```sql
-- Before (fragile text cast):
SELECT * FROM sky_cache
ORDER BY eq <-> '(4.292,20.600,0.000)'::equatorial
LIMIT 10;

-- After (typed bind parameters):
SELECT * FROM sky_cache
ORDER BY eq <-> make_equatorial($1, $2, 0.0)
LIMIT 10;
```

`IMMUTABLE STRICT PARALLEL SAFE`. Same validation as `equatorial_in()`: RA in `[0, 24)`, Dec in `[-90, 90]`, rejects NaN/Inf.

## Feature 2: Rise/Set Predictions (8 functions)

| Function | Threshold | Notes |
|----------|-----------|-------|
| `planet_next_rise(body_id, obs, t)` | 0.0 deg | body_id 1-8, rejects 0 (Sun) and 3 (Earth) |
| `planet_next_set(body_id, obs, t)` | 0.0 deg | |
| `sun_next_rise(obs, t)` | 0.0 deg | |
| `sun_next_set(obs, t)` | 0.0 deg | |
| `moon_next_rise(obs, t)` | 0.0 deg | |
| `moon_next_set(obs, t)` | 0.0 deg | |
| `sun_next_rise_refracted(obs, t)` | -0.833 deg | Refraction + semidiameter |
| `sun_next_set_refracted(obs, t)` | -0.833 deg | |

All `STABLE STRICT PARALLEL SAFE`. Returns `NULL` if no crossing within 7 days (circumpolar / polar night). Bisection to 0.1s precision, adapted from the satellite pass prediction algorithm.

Tested: Eagle, Idaho mid-latitude, refracted vs geometric offset (2-5 min), consecutive-rise ~24h gap, midnight sun (70N June) returns NULL for set, polar night (70N December) returns NULL for rise.

**Integration path for astrolock:** Your `/sky/rise-set` endpoint could call these directly via SkyEngine, eliminating the Skyfield computation. The SQL functions use the same VSOP87/ELP2000-82B pipeline that feeds `sky_cache`.

## Feature 3: Nutation (IAU 2000B)

The existing `get_nutation_angles_iau2000b()` in `precession.c` is now wired into the observation pipeline via `precess_and_nutate_j2000_to_date()`. Four dominant lunisolar terms, ~17.2 arcsec amplitude in longitude, ~9.2 arcsec in obliquity.

**What changed:** All solar system RA/Dec and az/el values shift by up to ~9 arcsec. KNN ordering for the Galilean moon case you flagged is now more accurate at sub-arcminute separations.

**What didn't change:** Satellite pipeline (SGP4/TEME) is completely unaffected. All 8 satellite-only test suites are bit-identical to v0.12.0.

## Migration

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

No reindex needed. The GiST index values shift by arcseconds but the bounding box structure is the same.

---

**Next steps for recipient:**
- [ ] astrolock-web: Replace `f"({target.ra_hours},{target.dec_deg},0)"` with `make_equatorial($1, $2, 0.0)` bind parameters
- [ ] astrolock-api: Wire `sun_next_rise_refracted()` / `sun_next_set_refracted()` into `/sky/rise-set` endpoint
- [ ] astrolock-api: Run `ALTER EXTENSION pg_orrery UPDATE TO '0.13.0'` on production after pg_orrery v0.13.0 is tagged