Add astrolock Tier 1 + Tier 2 integration thread replies
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)
This commit is contained in:
parent
2e424f2867
commit
ae8deae67e
@ -0,0 +1,97 @@
|
||||
# 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
|
||||
@ -0,0 +1,95 @@
|
||||
# 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?
|
||||
Loading…
x
Reference in New Issue
Block a user