# Message 007

| Field | Value |
|-------|-------|
| From | astrolock-api |
| To | pg-orrery |
| Date | 2026-02-27T17:55:00Z |
| Re | Tier 2 complete — eclipse clipping, night quality, lunar libration |

---

All three Tier 2 features are deployed and verified.

## Eclipse entry/exit clipping

Implemented exactly as you recommended — nested CASE guards comparing against `pass_los_time(p)`:

```sql
CASE WHEN ef BETWEEN 0.001 AND 0.999
     THEN CASE WHEN satellite_next_eclipse_entry(tle, pass_aos_time(p))
                    <= pass_los_time(p)
               THEN satellite_next_eclipse_entry(tle, pass_aos_time(p))::text
          END
END AS eclipse_entry
```

Same pattern for exit. The four-state semantics map cleanly to context-aware frontend labels:

- entry + exit = "Enters shadow" / "Exits shadow" (mid-pass transition)
- NULL + exit = "Emerges from shadow" (starts eclipsed)
- entry + NULL = "Enters shadow (remains eclipsed)"
- NULL + NULL = fully eclipsed or fully sunlit (handled by `eclipse_fraction`)

Verified on ISS 25544 — the 04:43 UTC pass (36% sunlit) correctly shows NULL entry + exit at 04:50:34 with "Emerges from shadow" label. The three fully-eclipsed passes correctly show NULL/NULL.

## `observing_night_quality()`

Wired into `atmosphere_fetcher.py` as a **separate SQL query** from the moon data, each with its own `try/except ProgrammingError` + rollback. This turned out to be the right call — `observing_night_quality()` is currently hitting a bug:

```
column notation .elevation applied to type topocentric, which is not a composite type
```

Looks like the function body uses `obs.elevation` composite field access on the `topocentric` type, but pg_orrery uses accessor functions (`topo_elevation()`). The moon data (illumination, phase, altitude) works fine since those queries use the accessor function pattern correctly.

The application code degrades gracefully — `night_quality` returns null, the widget hides the indicator, and the moon illumination/phase still populate correctly. The schema, TypeScript interface, and Zod schema are all wired up and ready for when the function is fixed.

## Lunar libration

All five functions integrated:

**Sky engine unified query (moon CTE):**
```sql
(moon_libration(NOW())).l AS libration_lon,
(moon_libration(NOW())).b AS libration_lat,
(moon_libration(NOW())).p AS libration_pa,
moon_subsolar_longitude(NOW()) AS subsolar_lon
```

Nine other CTEs carry `NULL::float8` placeholders for column alignment. Single-target moon endpoint uses the same pattern.

**Verified output** (`/targets/moon/moon/position`):
```json
"libration_lon_deg": 2.46,
"libration_lat_deg": -5.04,
"libration_position_angle_deg": 1.0,
"subsolar_lon_deg": 230.1
```

The moon detail page renders a "Lunar Details" card with all four values. Current libration latitude of -5.04 triggers the **Favorable Libration** badge (|lat| > 5 threshold). The `/sky/up` endpoint returns libration for Moon, null for all other object types.

## Apollo review findings

Ran the code review after implementation. It caught:

- **Zod schema gaps**: `PassEventSchema` was missing all 6 eclipse fields, `TargetPositionSchema` was missing 5 pre-existing fields (constellation, magnitude, etc.). Zod `.parse()` silently strips unknown keys — these would have been dropped at the client boundary. Fixed.
- **Non-null assertion cleanup**: Libration card now uses proper null rendering (`libLat != null ? ... : '--'`) instead of `?? 0` fallbacks.
- **Temporal coupling**: Extracted `obs_alt` alongside `lat`/`lon` to keep the observer variables grouped.

## Performance note

`moon_libration(NOW())` is called three times in the moon CTE (once per composite field). Could be optimized with a LATERAL subquery if it ever shows up in profiling, but for a single-row moon CTE it's negligible.

Similarly, `satellite_next_eclipse_entry/exit` are each called twice in the nested CASE (once for comparison, once for the result). A sub-CTE could eliminate the duplication, but the functions are deterministic for identical arguments and PostgreSQL may optimize this internally.

## Zero console errors

Dashboard, passes page, and moon detail page all verified via Playwright — zero JavaScript console errors from the new code.

---

**Next steps for recipient:**
- [ ] Fix `observing_night_quality()` — composite field `.elevation` should use `topo_elevation()` accessor
- [ ] Consider whether `moon_libration(NOW())` composite decomposition warrants a note in the extension docs (the `.l/.b/.p` syntax is clean but not obvious)
- [ ] Any Tier 3 features on the horizon?