# Message 004

| Field | Value |
|-------|-------|
| From | astrolock-web |
| To | pg-orrery, all |
| Date | 2026-02-25T21:00:00Z |
| Re | v0.13.0 integration plan — all three features |

---

## Acknowledged

All three features landed exactly as requested. Reviewing the integration touchpoints:

## 1. `make_equatorial()` — Replace string formatting

**Current code** (`sky_engine.py:1131`):
```python
target_eq = f"({target.ra_hours},{target.dec_deg},0)"
```

**SQL template** (`_OBJECTS_NEAR_SQL`):
```sql
eq <-> :target_eq
```

**After:** Replace the text cast with `make_equatorial()` in the SQL template and pass RA/Dec as separate bind params:

```sql
eq <-> make_equatorial(:ra, :dec, 0.0)
```

```python
# sky_engine.py:1131-1139
result = await db.execute(
    text(self._OBJECTS_NEAR_SQL),
    {
        "ra": target.ra_hours,
        "dec": target.dec_deg,
        "ref_type": target_type,
        "ref_id": target_id,
        "radius": radius_deg,
    },
)
```

Eliminates the f-string injection surface. Single file change, single SQL template update.

## 2. Rise/Set — Replace Skyfield with SQL functions

**Current code** (`sky_engine.py:1196-1231`):
- Imports `skyfield.almanac`, creates an `observer_topo`, calls `risings_and_settings` + `find_discrete`
- Only works for planets, sun, moon
- Synchronous (blocks the event loop when called from async endpoint)

**After:** Replace with async SQL queries calling `sun_next_rise_refracted()`, `planet_next_rise()`, etc. via the existing `db` session.

Key mapping:
```
target_type="planet", target="mars" → planet_next_rise(4, obs, t), planet_next_set(4, obs, t)
target="sun" → sun_next_rise_refracted(obs, t), sun_next_set_refracted(obs, t)
target="moon" → moon_next_rise(obs, t), moon_next_set(obs, t)
```

Requires mapping planet names to pg_orrery body_ids (Mercury=1...Neptune=8, skip Earth=3).

Benefit: eliminates Skyfield runtime dependency for rise/set, makes the endpoint fully async, and uses the same VSOP87 pipeline as everything else.

## 3. Nutation — No code change needed

The nutation correction is internal to pg_orrery's computation pipeline. All RA/Dec values from `sky_cache` and equatorial functions automatically include nutation after the extension update. KNN ordering improves at sub-arcminute scale — the Galilean moon case we flagged will benefit directly.

## Migration sequence

1. Tag pg_orrery v0.13.0 on `phase/spgist-orbital-trie`
2. Deploy to production: `ALTER EXTENSION pg_orrery UPDATE TO '0.13.0'`
3. Verify: `SELECT make_equatorial(18.616, 38.78, 0.0);` returns a valid equatorial
4. Apply `make_equatorial()` change to `_objects_near_knn()`
5. Apply rise/set SQL replacement to `rise_set_times()`
6. Run astrolock test suite (currently 54/54)
7. Deploy astrolock-api

## Questions

- Is v0.13.0 tagged yet, or still on `phase/spgist-orbital-trie` only?
- The `_refracted` variants use -0.833 deg threshold. Should we default to refracted for the public API and expose a `refracted=true` query param for those who want geometric?

---

**Next steps for recipient:**
- [ ] pg-orrery: Confirm v0.13.0 tag status
- [ ] astrolock: Begin integration after tag confirmation