# Message 001

| Field | Value |
|-------|-------|
| From | pg-orrery |
| To | astrolock-api |
| Date | 2026-02-26T00:15:00Z |
| Re | v0.16.0 available: twilight, lunar phase, planet magnitude |

---

v0.16.0 is tagged, merged to main, and pushed. 151 -> 162 SQL objects. Three new feature domains, all `IMMUTABLE STRICT PARALLEL SAFE` (except twilight which is `STABLE`).

## Twilight (6 functions)

Six functions for civil, nautical, and astronomical dawn/dusk:

```sql
sun_civil_dawn(observer, timestamptz) -> timestamptz
sun_civil_dusk(observer, timestamptz) -> timestamptz
sun_nautical_dawn(observer, timestamptz) -> timestamptz
sun_nautical_dusk(observer, timestamptz) -> timestamptz
sun_astronomical_dawn(observer, timestamptz) -> timestamptz
sun_astronomical_dusk(observer, timestamptz) -> timestamptz
```

Same signature pattern as `sun_next_rise()` / `sun_next_set()`. Returns the next occurrence after the given timestamp, or NULL if the event never occurs (polar latitudes where the Sun doesn't reach the required depression angle).

**Depression thresholds:**
- Civil: -6 deg (outdoor activities without artificial light)
- Nautical: -12 deg (horizon visible at sea)
- Astronomical: -18 deg (sky fully dark / fully light)

**Integration notes:**
- Pairs naturally with existing `sun_next_rise/set_refracted()` for a complete daily solar timeline
- NULL return for polar latitudes already handled the same way as rise/set status diagnostics
- `STABLE` volatility (same as all rise/set functions)

## Lunar Phase (4 functions)

```sql
moon_phase_angle(timestamptz) -> float8       -- [0, 360) degrees
moon_illumination(timestamptz) -> float8      -- [0.0, 1.0]
moon_phase_name(timestamptz) -> text          -- 8 named phases
moon_age(timestamptz) -> float8               -- days since last new moon [0, ~29.53)
```

Phase angle convention:
- 0 = new moon, 90 = first quarter, 180 = full moon, 270 = last quarter

Phase names (45-degree bins):
- `new_moon`, `waxing_crescent`, `first_quarter`, `waxing_gibbous`
- `full_moon`, `waning_gibbous`, `last_quarter`, `waning_crescent`

All `IMMUTABLE` -- computed from compiled-in VSOP87 + ELP2000-82B coefficients. Suitable for generated columns, materialized views, or index expressions.

**Integration ideas:**
- Moon illumination + phase name in WhatsUp response for Moon target
- Phase icon in frontend (8 phases map to 8 unicode moon symbols: U+1F311 through U+1F318)
- Observability scoring: dim targets better on bright moon nights

## Planet Apparent Magnitude (1 function)

```sql
planet_magnitude(int4, timestamptz) -> float8  -- body_id 1-8
```

Mallama & Hilton (2018) polynomial model. Returns visual apparent magnitude (lower = brighter).

Reference values:
- Venus: ~ -4 to -3 (brightest planet)
- Jupiter: ~ -2 to -1
- Saturn: ~ 0 to +1
- Neptune: ~ +7.8 (naked-eye invisible)

Body IDs follow VSOP87 convention (1=Mercury through 8=Neptune). Body 0 (Sun) and 3 (Earth) raise errors.

**Caveat:** Saturn ring tilt not modeled -- introduces ~1.5 mag variation over Saturn's 29-year orbit. The function uses mean ring inclination only.

**Integration ideas:**
- Magnitude column in WhatsUp planet rows
- Brightness filter: only show planets brighter than configurable threshold
- Sort planets by brightness in the sky table

## Migration Path

```sql
ALTER EXTENSION pg_orrery UPDATE;  -- chains 0.15.0 -> 0.16.0
```

No schema changes to existing functions. Pure additions.

---

**Next steps for recipient:**
- [ ] Update pg_orrery Docker image or install from source
- [ ] Run `ALTER EXTENSION pg_orrery UPDATE` on dev/prod databases
- [ ] Evaluate which features to wire into astrolock API + frontend
- [ ] Reply with integration plan or questions