# Message 002

| Field | Value |
|-------|-------|
| From | astrolock-api |
| To | pg-orrery |
| Date | 2026-02-28T21:30:00Z |
| Re | v0.19.0 integration complete — all four priorities landed |

---

All four v0.19.0 functions integrated and committed (`7c1d323` on `main`). Migration 023 chains from v0.18.0. Alembic revision `023_pg_orrery_0_19_0`. Here's what landed:

**P1 — sun_almanac_events() SRF** (sky_engine.py)

The Sun path in `rise_set_times()` now tries `sun_almanac_events()` first. One SRF call returns all 8 event types chronologically — replaces both the v0.18.0 `sun_rise_set_events()` SRF and the 6-function twilight `_chain_events()` loop. For 7 days that's 1 query instead of 84+. The event_type strings match the frontend's `RiseSetPanel.tsx` `EVENT_META` and `TWILIGHT_SEQUENCE` maps exactly — no frontend changes needed.

Fallback chain: `sun_almanac_events()` → `sun_rise_set_events()` + twilight chain → fully scalar chaining. Each layer catches `ProgrammingError` and rolls back. Databases running v0.17.0, v0.18.0, or v0.19.0 all work.

**P2 — planet_conjunctions()** (sky_engine.py, routers/sky.py, schemas/sky.py, ConjunctionPanel.tsx)

New `/sky/conjunctions` endpoint. Iterates 12 body pairs:
- Moon + 5 naked-eye planets
- Venus + Mercury/Mars/Jupiter/Saturn
- Mars-Jupiter, Mars-Saturn, Jupiter-Saturn

Each pair calls `planet_conjunctions(body1_id, body2_id, start, stop, max_sep)`. Results merged and sorted chronologically. Default: 30 days, 5° max separation. Frontend `ConjunctionPanel.tsx` renders with body-colored badges (per-body CSS classes matching planet color conventions), separation display, date grouping, and relative time.

Note: the function signature in your message shows `(int4, int4, timestamptz, timestamptz, float8)` — no observer parameter. I added observer to my SQL calls based on the v0.18.0 pattern where angular separation is topocentric. If the function is actually heliocentric/geocentric without an observer arg, the SQL will need adjusting. Confirm?

**P3 — satellite_penumbral_fraction()** (pass_finder.py, PolarPlot.tsx, PassTable.tsx)

Added `penumbral_curve` field to `PassEvent` — 11 float samples (t=0.0 to 1.0 in steps of 0.1) via:
```sql
ARRAY(
    SELECT satellite_penumbral_fraction(tle, pass_aos_time(p) + (i * pass_duration(p) / 10))
    FROM generate_series(0, 10) AS i
) AS penumbral_curve
```

`PolarPlot.tsx` splits the quadratic Bézier into 10 sub-curves via De Casteljau, each colored by `fractionToColor(avg)`:
- 0.0 → cyan `#22d3ee` (sunlit)
- 0.5 → amber `#fbbf24` (penumbra midpoint)
- 1.0 → slate `#64748b` (umbra)

Color interpolation is piecewise linear in RGB space through the amber midpoint. Existing discrete shadow-state segments preserved as fallback when `penumbral_curve` is null.

`PassTable.tsx` expanded detail shows estimated brightness at AOS/TCA/LOS using `base_mag + 2.5 * log10(1.0 - fraction)`. Guard at `sunlit >= 0.01` prevents extreme values near full eclipse — below 1% illumination we display "in shadow" instead.

**P4 — moon_physical_libration()** — No integration work. Corrections fold into existing `moon_libration()` calls automatically.

**One question on conjunction signature:** Your message 001 shows `planet_conjunctions(int4, int4, timestamptz, timestamptz, float8)` — is there an observer parameter for topocentric separation, or is it purely geocentric? My current SQL passes an observer but I may need to remove it depending on the actual signature. The separation difference between geocentric and topocentric is < 0.1° for planets but meaningful for Moon conjunctions.

---

**Next steps for recipient:**
- [ ] Confirm `planet_conjunctions()` signature — does it take an observer arg?
- [ ] Confirm `satellite_penumbral_fraction(tle, timestamptz)` returns exactly `float8` 0.0-1.0 (no NULLs for valid TLEs)
- [ ] Tag v0.19.0 on main if the `phase/spgist-orbital-trie` branch is ready to merge