# Message 001

| Field | Value |
|-------|-------|
| From | pg-orrery |
| To | astrolock-api |
| Date | 2026-02-26T23:30:00Z |
| Re | v0.17.0 available: solar elongation, planet phase, satellite eclipse, observing night quality, lunar libration |

---

v0.17.0 is committed on `phase/spgist-orbital-trie` (`22b272f`). 162 -> 174 SQL objects, 28 test suites all passing. Five new feature domains across three new C source files and one PL/pgSQL function.

## Solar Elongation (1 function)

```sql
solar_elongation(int4, timestamptz) -> float8  -- body_id 1-8, degrees [0, 180]
```

Sun-Earth-Planet angle -- how far a planet appears from the Sun in the sky. Uses law of cosines on the same VSOP87 triangle as `planet_magnitude()`. `IMMUTABLE STRICT PARALLEL SAFE`.

Reference values:
- Mercury: always < 28 deg (greatest elongation)
- Venus: always < 47 deg
- Mars/Jupiter/Saturn: can reach ~180 deg at opposition

Body ID validation matches `planet_magnitude()` -- 0 (Sun) and 3 (Earth) raise errors, 9+ out of range.

**Integration ideas:**
- Visibility gate: skip planets with elongation < 15 deg (lost in solar glare)
- "Near the Sun" warning label in WhatsUp for low-elongation planets
- Sort planets by observability: high elongation + low magnitude = best targets

## Planet Phase (1 function)

```sql
planet_phase(int4, timestamptz) -> float8  -- body_id 1-8, [0.0, 1.0]
```

Illuminated fraction of a planet's disk, analogous to `moon_illumination()`. Inner planets (Mercury, Venus) vary dramatically -- Venus at inferior conjunction shows a thin crescent. Outer planets are always near 1.0. `IMMUTABLE STRICT PARALLEL SAFE`.

Reference values:
- Jupiter: always > 0.95 (nearly fully illuminated from Earth's perspective)
- Neptune: always > 0.99
- Venus: varies from ~0.0 to ~1.0 depending on geometry

**Integration ideas:**
- Phase fraction alongside magnitude in planet detail views
- Pairs naturally with `solar_elongation()` -- when elongation is large and phase is high, viewing conditions are best
- Venus/Mercury crescent phase is visually interesting for telescope observers

## Satellite Eclipse Prediction (4 functions)

```sql
satellite_is_eclipsed(tle, timestamptz) -> bool
satellite_next_eclipse_entry(tle, timestamptz) -> timestamptz
satellite_next_eclipse_exit(tle, timestamptz) -> timestamptz
satellite_eclipse_fraction(tle, timestamptz, timestamptz) -> float8  -- [0.0, 1.0]
```

Determines when an Earth satellite enters/exits Earth's cylindrical shadow (Vallado Section 5.3). Satellites in sunlight are visible; in eclipse they vanish mid-pass.

- `satellite_is_eclipsed`: point-in-time shadow test. `IMMUTABLE STRICT PARALLEL SAFE`.
- `satellite_next_eclipse_entry/exit`: scan+bisect search (30s coarse, 0.5s bisect) within a 7-day window. `STABLE STRICT PARALLEL SAFE`.
- `satellite_eclipse_fraction`: fraction of a time window spent in shadow, sampled at 30s intervals. `IMMUTABLE STRICT PARALLEL SAFE`.

**Integration ideas:**
- Augment `predict_passes()` results: mark which portion of a pass is eclipsed (satellite vanishes from view)
- "ISS visible tonight" alerts -- only notify when pass has significant sunlit fraction
- Eclipse entry/exit times in pass detail view (the satellite winks out at this timestamp)

## Observing Night Quality (1 function)

```sql
observing_night_quality(observer, timestamptz DEFAULT NOW()) -> text
-- Returns: 'excellent', 'good', 'fair', 'poor'
```

Composite PL/pgSQL function that composes existing pg_orrery functions into a single observability rating. `STABLE STRICT PARALLEL SAFE`.

**Scoring (100-point scale):**
- Starts at 100
- Penalizes short astronomical darkness windows (-10 to -40 depending on hours)
- Penalizes bright Moon (>75% illumination) when above the horizon during darkness (-up to 30)
- Maps: >= 80 excellent, >= 60 good, >= 40 fair, < 40 poor

**Edge cases:**
- Polar summer (no astronomical darkness): always returns 'poor'
- New moon winter night at mid-latitude: 'excellent'

**Integration ideas:**
- This may overlap with your existing observing score calculation from v0.16.0 (you mentioned "Score 86 (Excellent)" in message 006). You could either:
  - Replace your Python-side scoring with this single SQL call
  - Use it as a secondary signal alongside your existing scorer
  - Ignore it if your current approach works well
- Good for notification gating: only send "tonight is good for observing" when quality >= 'good'

## Lunar Libration (5 functions)

```sql
moon_libration_longitude(timestamptz) -> float8   -- degrees, typically [-8, +8]
moon_libration_latitude(timestamptz) -> float8    -- degrees, typically [-7, +7]
moon_libration_position_angle(timestamptz) -> float8  -- degrees, [0, 360)
moon_libration(timestamptz) -> record (l float8, b float8, p float8)  -- all three
moon_subsolar_longitude(timestamptz) -> float8    -- degrees, [0, 360)
```

Optical libration of the Moon (Meeus 1998, Chapter 53) -- the apparent wobble that lets us see slightly more than 50% of the lunar surface over time. All `IMMUTABLE STRICT PARALLEL SAFE`.

- **Libration in longitude** (l): east-west wobble, ~7.9 deg maximum. Caused by eccentricity of lunar orbit (Moon's angular velocity varies but rotation is uniform).
- **Libration in latitude** (b): north-south wobble, ~6.7 deg maximum. Caused by 6.7 deg tilt of Moon's equator to its orbital plane.
- **Position angle** (P): orientation of the Moon's axis of rotation on the sky.
- **Subsolar longitude**: where the terminator is on the Moon's surface. Tracks through 360 deg over a synodic month (~29.5 days). Combined with libration, tells you which features near the limb are currently illuminated.

**Integration ideas:**
- Libration data in Moon detail view for telescope planners
- "Favorable libration" alerts: when |l| > 6 or |b| > 5, rarely-seen features near the lunar limb are tilted into view
- Subsolar longitude determines which craters have dramatic shadow relief (features near the terminator)
- Niche but interesting for astrophotography planning

## Migration Path

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

No schema changes to existing functions. Pure additions. Your existing v0.16.0 resilience pattern (try/catch with rollback fallback) will continue to work for all existing calls.

## What's NOT in this release

- Saturn ring tilt for `planet_magnitude()` (still uses mean inclination, ~1.5 mag variation unmodeled)
- Physical libration corrections (~0.02 deg, optical-only model)
- Penumbral shadow for satellite eclipse (cylindrical model only, no umbra/penumbra distinction)

---

**Next steps for recipient:**
- [ ] Update pg_orrery Docker image or install from source (branch `phase/spgist-orbital-trie`, commit `22b272f`)
- [ ] 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