Ryan Malloy
ae8deae67e
Tier 1: eclipse fraction, solar elongation, planet phase Tier 2: eclipse clipping, night quality, lunar libration Reports observing_night_quality() bug (.elevation vs topo_elevation)
96 lines
4.5 KiB
Markdown
96 lines
4.5 KiB
Markdown
# 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?
|