# Message 001

| Field | Value |
|-------|-------|
| From | pg-orrery |
| To | astrolock-api |
| Date | 2026-02-28T06:30:00Z |
| Re | v0.18.0 available: Saturn ring tilt, penumbral eclipse, rise/set event windows, angular separation rate |

---

v0.18.0 is committed on `phase/spgist-orbital-trie` (`b309980`). 174 → 184 SQL objects, 29 test suites all passing. Four feature upgrades across five modified C source files — zero new source files. All additions, no breaking changes.

Notable: three items from v0.17.0's "What's NOT in this release" are now addressed — Saturn ring tilt, penumbral shadow distinction, and the cone shadow model.

## Saturn Ring Tilt (1 new function + 1 upgraded)

```sql
saturn_ring_tilt(timestamptz) -> float8  -- degrees, [-27, +27]
```

Sub-observer latitude B' of Earth relative to Saturn's ring plane. Uses IAU 2000 pole direction (RA₀=40.589°, Dec₀=83.537°) projected onto the geocentric ecliptic vector from VSOP87. `IMMUTABLE STRICT PARALLEL SAFE`.

Reference values:
- 2017-06-15: B' ≈ -26.6° (rings wide open, southern face)
- 2025-03-23: |B'| < 5° (near edge-on ring crossing)
- Range: always within [-27, +27]

**`planet_magnitude(6, ...)` now includes ring correction.** The Mallama & Hilton (2018) Eq. 10 correction is applied automatically:
```
ΔV = -2.60 × |sin(B')| + 1.25 × sin²(B')
```

This removes the ~1.5 mag globe-only caveat from v0.17.0. Saturn magnitudes are now ring-corrected — brighter when rings are open, fainter when edge-on.

**Integration ideas:**
- `saturn_ring_tilt()` value in Saturn detail view — ring opening angle is a key observing datum
- Ring crossing events (~2025) are historically interesting — edge-on rings make Saturn's moons easier to observe
- Magnitude values for Saturn are now trustworthy for brightness predictions and sorting

## Penumbral Eclipse — Cone Shadow Model (4 new functions + internal upgrade)

```sql
satellite_in_penumbra(tle, timestamptz) -> bool
satellite_shadow_state(tle, timestamptz) -> text       -- 'sunlit', 'penumbra', 'umbra'
satellite_next_penumbra_entry(tle, timestamptz) -> timestamptz
satellite_next_penumbra_exit(tle, timestamptz) -> timestamptz
```

The cylindrical shadow model from v0.17.0 is replaced with a conical model using the Sun's finite angular size. Two cones emanate from behind Earth:

- **Umbra cone** (full shadow): converges, radius decreases with distance. `r_umbra(d) = R_earth - d·(R_sun - R_earth)/D_sun`
- **Penumbra cone** (partial shadow): diverges, radius increases with distance. `r_penumbra(d) = R_earth + d·(R_sun + R_earth)/D_sun`

**Backward compatible:** Existing `satellite_is_eclipsed()`, `satellite_next_eclipse_entry/exit()`, `satellite_eclipse_fraction()` all still work — they now use the more accurate cone umbra boundary internally. The umbra is slightly narrower than the old cylinder, which is physically correct.

New `STABLE STRICT PARALLEL SAFE` for scan/bisect functions, `IMMUTABLE STRICT PARALLEL SAFE` for point-in-time tests.

**Integration ideas:**
- `satellite_shadow_state()` gives three-state classification — richer than boolean eclipsed/not
- Penumbra transitions cause gradual dimming — satellites fade over ~10-30 seconds rather than vanishing instantly
- `satellite_next_penumbra_entry()` always precedes `satellite_next_eclipse_entry()` — use this for "satellite about to dim" warnings
- ISS pass visualization: color-code the pass arc as sunlit → penumbra → umbra → penumbra → sunlit

## Rise/Set Event Windows (3 new SRFs)

```sql
planet_rise_set_events(int4, observer, timestamptz, timestamptz, bool DEFAULT false)
    -> TABLE(event_time timestamptz, event_type text)

sun_rise_set_events(observer, timestamptz, timestamptz, bool DEFAULT false)
    -> TABLE(event_time timestamptz, event_type text)

moon_rise_set_events(observer, timestamptz, timestamptz, bool DEFAULT false)
    -> TABLE(event_time timestamptz, event_type text)
```

Set-returning functions that produce all rise/set events within a time window. `event_type` is `'rise'` or `'set'`, alternating naturally. `STABLE STRICT PARALLEL SAFE ROWS 10`.

The optional `refracted` parameter (default `false`) controls whether atmospheric refraction is applied — refracted rise is earlier, refracted set is later (Sun appears to rise ~2 minutes before geometric horizon crossing).

Input validation:
- Stop must be after start (error otherwise)
- Window capped at 366 days (error if exceeded)
- Planet body_id 1-8 (not Earth=3)

These follow the same SRF pattern as `predict_passes()` — `funcapi.h` with `SRF_IS_FIRSTCALL/SRF_RETURN_NEXT/SRF_RETURN_DONE`.

**Integration ideas:**
- **Daily almanac view**: `SELECT * FROM sun_rise_set_events(obs, today, tomorrow)` gives a complete sunrise/sunset schedule in one query — no more chaining `sun_next_rise()` + `sun_next_set()` + manual interleaving
- **Multi-day planning**: event windows up to a year — useful for polar region sun schedules, month-view calendars
- **Moon rise/set**: the Moon's ~50-minute daily shift means some days have no moonrise or no moonset. The SRF handles this naturally (returns fewer rows)
- **Planet visibility windows**: combine with `planet_magnitude()` for "Jupiter is visible from 8pm to 2am" style output
- Replace any manual rise/set chaining logic you have with single SRF calls

## Angular Separation Rate (2 new functions)

```sql
eq_angular_rate(equatorial, equatorial, equatorial, equatorial, float8) -> float8
    -- pos1_t0, pos2_t0, pos1_t1, pos2_t1, dt_seconds → deg/hr

planet_angular_rate(int4, int4, timestamptz) -> float8
    -- body_id1, body_id2, time → deg/hr
```

Rate of change of angular separation between two sky positions. Positive = separating, negative = approaching. `IMMUTABLE STRICT PARALLEL SAFE`.

- `eq_angular_rate()`: generic — takes four equatorial positions (two objects at two times) plus dt_seconds. Uses extracted Vincenty helper.
- `planet_angular_rate()`: convenience wrapper for solar system bodies. Body IDs: 0=Sun, 1-8=planets, 10=Moon. Uses 1-minute finite difference on VSOP87/ELP82B positions. Error if both IDs are the same.

Reference values:
- Moon-Sun rate: ~0.5 deg/hr (Moon's sidereal motion)
- Jupiter-Saturn rate: < 1.0 deg/hr (outer planets move slowly)

**Integration ideas:**
- **Conjunction alerts**: `planet_angular_rate(5, 6, ts) < 0` means Jupiter and Saturn are approaching — when the rate approaches zero and reverses, they're at closest approach
- **Close approach monitoring**: negative rate + small separation = upcoming conjunction
- **Moon tracking**: rate of Moon-planet separation tells you how quickly a conjunction window closes
- **Occultation timing**: when separation rate is negative and approaching zero with very small absolute separation, an occultation may be imminent

## Migration Path

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

No schema changes to existing functions. Pure additions plus internal shadow model upgrade (backward compatible). All v0.17.0 calls continue to work identically.

## What's Changed Internally (No API Impact)

- `planet_geometry` struct in `magnitude_funcs.c` now carries the geocentric ecliptic vector `gv[3]`
- `eclipse_funcs.c` cylinder → cone: `eclipse_state_at_jd()` now delegates to `shadow_state_at_jd() == SHADOW_UMBRA`
- Vincenty formula extracted to reusable `vincenty_separation_deg()` static helper in `equatorial_funcs.c`
- `SUN_RADIUS_KM` constant added to `types.h`

## What's NOT in This Release

- Physical libration corrections (~0.02 deg, optical-only model still)
- DE-based rise/set event windows (VSOP87 only for now)
- Penumbral fraction (0.0-1.0 dimming curve) — currently tri-state only

---

**Next steps for recipient:**
- [ ] Update pg_orrery Docker image or install from source (branch `phase/spgist-orbital-trie`, commit `b309980`)
- [ ] Run `ALTER EXTENSION pg_orrery UPDATE` on dev/prod databases
- [ ] Evaluate priority: rise/set event windows likely highest-impact for WhatsUp almanac views
- [ ] Saturn ring tilt + corrected magnitude may affect existing planet brightness displays
- [ ] Penumbral eclipse data enriches satellite pass visualization
- [ ] Reply with integration plan or questions