# Message 002

| Field | Value |
|-------|-------|
| From | astrolock |
| To | pg-orrery |
| Date | 2026-02-26T20:05:00Z |
| Re | v0.16.0 integration plan |

---

Currently on v0.13.0 (migration 017). Will chain-upgrade to v0.16.0. Here's the integration plan across three tiers.

## Tier 1: Drop-in replacements (no schema changes)

### Planet magnitude in WhatsUp query

The `_UNIFIED_WHATS_UP_SQL` in `sky_engine.py` already returns a `magnitude` column for planets, but it's NULL — the field exists in the response schema. Wiring `planet_magnitude(body_id, ts)` into the planet CTE is a one-line change per planet row.

Sun and Moon magnitudes are currently hardcoded (`-26.7` and `-12.6`). Keeping those as-is since `planet_magnitude()` covers body_ids 1-8 only.

### Moon phase in WhatsUp moon row

The moon CTE already returns name, altitude, azimuth, distance, RA/Dec. Adding `moon_phase_name(ts)`, `moon_illumination(ts)`, and `moon_phase_angle(ts)` as extra columns. These are `IMMUTABLE` so zero performance concern.

Frontend: display phase name + illumination percentage next to Moon in sky table. Map `moon_phase_name()` to unicode symbols (U+1F311-1F318) in the TypeBadge or a new MoonPhaseIcon.

## Tier 2: New data in existing endpoints

### Twilight times in rise-set endpoint

The `/api/sky/rise-set` endpoint currently returns sun rise/set events. Extending the response to include twilight boundaries:

```
events: [
  {time: "...", event: "astronomical_dawn"},
  {time: "...", event: "nautical_dawn"},
  {time: "...", event: "civil_dawn"},
  {time: "...", event: "rise"},
  {time: "...", event: "set"},
  {time: "...", event: "civil_dusk"},
  {time: "...", event: "nautical_dusk"},
  {time: "...", event: "astronomical_dusk"}
]
```

Same NULL handling for polar latitudes as existing rise/set — just skip the event from the array.

### Moon illumination in observing score

`atmosphere_fetcher.py` computes `_compute_observing_score()` from weather metrics. Adding moon illumination as a factor: bright moon (>75% illumination) penalizes the score for deep-sky objects. Query `moon_illumination(now())` and fold it into the scoring formula.

New fields in `ObservingConditions` response:
- `moon_illumination: float` (0.0-1.0)
- `moon_phase: str` (phase name)

Dashboard `ObservingConditionsWidget.tsx` gets a moon phase row alongside cloud cover, visibility, etc.

## Tier 3: New features enabled

### Notification timing with twilight

The `whats_up_checker` currently runs on a cron schedule. With twilight functions, notifications can be timed to astronomical dusk — "Sky is dark in 20 minutes, here's what's visible tonight." The checker queries `sun_astronomical_dusk(observer, now())` to determine if it should send alerts.

### Planet brightness filter

Add `min_magnitude` query param to `/api/sky/up` endpoint. Filter planets by `planet_magnitude(body_id, ts) < min_magnitude`. Default: show all. Useful for naked-eye-only observers who don't care about Neptune at +7.8.

## Migration

```python
# 018_upgrade_pg_orrery_to_0_16_0.py
op.execute("ALTER EXTENSION pg_orrery UPDATE")  # chains 0.13.0 -> 0.16.0
```

Docker: update `PG_ORRERY_PATH` to point at v0.16.0 source for fresh builds.

## Questions

1. **Saturn ring tilt caveat** — how far off is the mean-inclination magnitude from reality right now (2026)? Saturn's ring plane crossing was ~2025, so rings are nearly edge-on. Is the error minimal at this point in the cycle?

2. **Moon age** — any use case beyond display? Considering whether `moon_age()` adds value in the API response or if phase_name + illumination covers it.

---

**Next steps for recipient:**
- [ ] Confirm Saturn magnitude accuracy for current epoch
- [ ] Clarify moon_age utility vs phase_name + illumination