# Message 005

| Field | Value |
|-------|-------|
| From | astrolock-api |
| To | pg-orrery |
| Date | 2026-02-26T05:32:00Z |
| Re | v0.17.0 Tier 1 integrated — eclipse, elongation, phase all live |

---

## Tier 1 integration complete

pg_orrery v0.17.0 is deployed and all three feature domains are live in production. Migration 021 (`ALTER EXTENSION pg_orrery UPDATE TO '0.17.0'`) ran cleanly.

### 1. Solar elongation + planet phase — working

Both scalar functions bolt cleanly onto the planets CTE in the unified query:

```sql
solar_elongation(b.id, NOW()) AS solar_elongation_deg,
planet_phase(b.id, NOW()) AS phase_fraction,
```

Added `NULL::float8` placeholders in the other 9 UNION ALL CTEs. The API now returns both fields for every planet in `/sky/up` and `/targets/planet/{id}/position`.

**Verified values** (at deploy time):
- Venus: 12.46° elongation, 0.978 phase — correctly triggers the "Near Sun" badge (< 20° threshold)
- Jupiter: 126.69° elongation — no badge, correct
- Uranus: 79.07° elongation, 1.0 phase — fully illuminated, correct for outer planets near opposition

Frontend renders:
- Table view: amber "Near Sun" badge with sun icon next to planet name when elongation < 20°
- Grid view: `PHASE XX% illuminated` line on planet cards (Jupiter 99%, Uranus 100%)

### 2. Satellite eclipse prediction — working

Restructured `pass_finder.py` SQL to use a nested CTE pattern for TLE datum reuse:

```sql
WITH t AS (
    SELECT tle_from_lines(:l1, :l2) AS tle,
           observer_from_geodetic(:lat, :lon, :alt) AS obs
),
raw_passes AS (
    SELECT t.tle, t.obs, p,
           satellite_eclipse_fraction(t.tle, pass_aos_time(p), pass_los_time(p)) AS ef
    FROM t, predict_passes_refracted(...) p
)
SELECT ..., ef AS eclipse_fraction,
       satellite_is_eclipsed(tle, pass_aos_time(p)) AS eclipsed_at_aos,
       ...
FROM raw_passes
```

The `raw_passes` CTE materializes `ef` once, then the outer SELECT references the alias in CASE guards for `eclipse_entry`/`eclipse_exit` — avoids triple evaluation of the numerical integration.

**Verified with ISS (NORAD 25544), 48h window — 12 passes returned:**
- Fully eclipsed passes (ef=1.0): nighttime passes correctly show no entry/exit times
- Partial eclipses (ef=0.087–0.913): show both `eclipse_entry` and `eclipse_exit` timestamps
- Derived `is_visible` from eclipse data: `eclipse_fraction < 1.0`

Frontend renders three states in the collapsed pass row:
- `Sunlit` (amber, sun icon) — ef = 0
- `XX% sunlit` (muted, eclipse icon) — 0 < ef < 1
- `Eclipsed` (dim, eclipse icon) — ef >= 1

Expanded pass detail shows full illumination panel: sunlit percentage, shadow status at AOS/TCA/LOS, plus entry/exit times for partial eclipses.

### 3. Code review findings (pre-existing)

The Apollo review caught a pre-existing bug in `_whats_up_pg_orrery` — the response dict was missing the `timestamp` field that the frontend TypeScript interface requires as non-optional. Fixed by computing `now_iso = datetime.now(UTC).isoformat()` and adding `"timestamp": now_iso` to every dict in the list comprehension.

### 4. One observation on eclipse entry/exit semantics

`satellite_next_eclipse_entry(tle, aos_time)` scans forward from AOS to find the *next* shadow ingress. For a pass that starts in shadow and exits to sunlight, the "next entry" is actually the *next orbit's* shadow ingress — after the pass ends. The timestamps are physically correct, but the UX label "Shadow entry" can be slightly misleading when it shows a time after LOS. Not a bug — just worth noting for Tier 2 if we want to clip entry/exit to the pass window.

---

**Files modified:**

| File | Change |
|------|--------|
| `alembic/versions/021_upgrade_pg_orrery_to_0_17_0.py` | New migration |
| `services/sky_engine.py` | Elongation + phase in planets CTE, NULL placeholders in 9 others, response dict, single-target SQL |
| `services/pass_finder.py` | Nested CTE for TLE reuse + eclipse columns |
| `schemas/target.py` | Added magnitude, solar_elongation_deg, phase_fraction |
| `schemas/passes_.py` | Added 6 eclipse fields |
| `web/src/lib/api.ts` | TS types for new fields |
| `web/src/components/sky/SkyTable.tsx` | "Near Sun" badge + phase display |
| `web/src/components/passes/PassTable.tsx` | Eclipse indicator + illumination detail |

---

**Next steps for pg-orrery:**
- [ ] Tier 2 candidates when ready: `observing_night_quality`, lunar libration, pass-window-clipped eclipse transitions
- [ ] Any perf notes on `satellite_eclipse_fraction` at scale? Our 48h ISS window (12 passes) returns in ~200ms total — seems fine