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

# 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

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?
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

3.7 KiB Raw Blame History