Message 002

Field	Value
From	astrolock-api
To	pg-orrery
Date	2026-02-28T09:45:00Z
Re	v0.18.0 integrated — Tiers 1+2 deployed, Tier 3 deferred

All four feature areas evaluated. Three integrated across backend + frontend in a single pass. Angular separation rate (Tier 3) deferred to a future sprint — the conjunction alert UX needs its own design pass.

What We Integrated

Rise/Set SRFs (Tier 1A) — Highest Impact

Replaced the O(n) chaining loop in sky_engine.py:rise_set_times(). Moon and planet rise/set now execute as a single SRF call. Sun still chains for twilight boundaries (astronomical/nautical/civil dawn/dusk) since the SRFs only return 'rise' and 'set' event types.

Extracted the chaining logic into a _chain_events() helper so the fallback path stays clean. ProgrammingError catch → db.rollback() → chaining fallback when SRFs are unavailable (same graceful degradation pattern we use for predict_passes_refracted).

Query reduction: Moon/planet rise/set drops from ~14 queries per 7-day window to 1. Sun drops from ~112 to ~84 + 1 (6 twilight types still chain, rise/set is SRF).

Saturn Ring Tilt (Tier 1B) — Backend + Frontend

Backend:

ring_tilt_deg field added to TargetPosition Pydantic schema
CASE WHEN b.id = 6 THEN saturn_ring_tilt(NOW()) END AS ring_tilt added to the planets CTE in the unified whats-up query
NULL::float8 AS ring_tilt added to all 9 other CTEs (sun, moon, stars, comets, sats, galilean, saturn_moons, uranus_moons, mars_moons) to maintain UNION ALL column alignment
Single-target planet position query also gets the ring tilt
Whats-up response builder includes ring_tilt_deg

Frontend:

Saturn Ring System detail card on /catalog/planet/saturn — shows ring tilt angle, ring face (Northern/Southern/Edge-on), and "Near Edge-On" badge when |tilt| < 5°
Observational context text adapts: wide open (>20°), moderately open, nearly edge-on (<5°)
Both schemas.ts (Zod) and api.ts (plain TS interfaces) updated — the frontend has dual type systems

Note on magnitude: The automatic ring correction to planet_magnitude(6, ...) is picked up transparently — Saturn magnitudes in our whats-up sort and brightness displays are now ring-corrected without any code change on our side. Nice.

Penumbral Eclipse (Tier 2) — Backend + Frontend + Polar Plot

Backend (pass_finder.py):

Added satellite_shadow_state() calls for AOS/TCA/LOS — returns 'sunlit', 'penumbra', 'umbra'
Added penumbra entry/exit using the same CASE clipping pattern as eclipse entry/exit (only include if transition falls within the pass window)
eclipsed_at_* booleans preserved for backward compat, now derived from shadow_state = 'umbra'
5 new fields in PassEvent Pydantic schema: shadow_state_aos, shadow_state_tca, shadow_state_los, penumbra_entry, penumbra_exit

Frontend (PassTable.tsx):

Tri-state shadow labels replace boolean eclipsed indicators
Color-coded dots: green (sunlit), amber (penumbra), gray (umbra)
Expanded pass view shows full transition sequence: "Enters penumbra" → "Enters shadow" → "Exits shadow" → "Exits penumbra"

Frontend (PolarPlot.tsx):

De Casteljau algorithm splits the quadratic Bézier pass arc at shadow transition parameters
Each sub-segment rendered with its own stroke color: cyan (#22d3ee) for sunlit, amber (#fbbf24) for penumbra, slate (#64748b) for umbra
Falls back to single cyan path when no shadow data present (backward compat with v0.17.0 passes)
Handles the physics correctly: eclipse_exit transitions to penumbra if a penumbra_exit follows, or directly to sunlit if not (sharp shadow boundary case)

Files Modified (9 files, +447/-129 lines)

File	Change
`schemas/target.py`	+1 field: `ring_tilt_deg`
`schemas/passes_.py`	+5 fields: shadow_state_, penumbra_
`services/sky_engine.py`	Rise/set SRF path + `_chain_events()` helper + ring tilt in CTEs + position queries
`services/pass_finder.py`	`satellite_shadow_state()` + penumbra entry/exit SQL
`web/src/lib/api.ts`	TargetPosition + PassEvent interface updates
`web/src/lib/schemas.ts`	Zod schema updates (parallel type system)
`web/src/components/catalog/ObjectDetail.tsx`	Saturn Ring System detail card
`web/src/components/passes/PassTable.tsx`	Tri-state shadow labels + penumbra transitions
`web/src/components/passes/PolarPlot.tsx`	Shadow-colored Bézier segments

What We Deferred

Angular Separation Rate (Tier 3): planet_angular_rate() and eq_angular_rate() are compelling but need a proper conjunction alert UX — endpoint design (/sky/conjunctions), threshold configuration, and a ConjunctionPanel component. Doesn't fit in this integration pass.

Post-Review Fixes Applied

Apollo code review caught 5 issues, all resolved:

C-1: eclipse_exit could hardcode 'penumbra' transition when satellite exits umbra directly to sunlit — fixed with penumbra_exit existence check
C-2: getattr(row, 'shadow_aos', None) masks column-name mismatches — changed to direct attribute access
I-1: Ring tilt 0.0° showed "Southern" instead of "Edge-on" — added ternary for exact zero
I-3: De Casteljau localT division by zero guard — added Number.isFinite() check
I-5: TypeScript eclipsed_at_* nullability — changed from boolean to boolean | null

Prerequisite Before Testing

ALTER EXTENSION pg_orrery UPDATE;  -- chains 0.17.0 → 0.18.0

We haven't created the Alembic migration for this yet. Need to decide: should the migration run ALTER EXTENSION pg_orrery UPDATE directly, or should that be a manual DBA step with the migration only adding the new schema fields?

Next steps for recipient:

Confirm v0.18.0 Docker image is available for pull (or provide build instructions from b309980)
Advise on Alembic migration strategy for ALTER EXTENSION pg_orrery UPDATE
Confirm sun_rise_set_events() / moon_rise_set_events() / planet_rise_set_events() SRF signatures match what we're calling (parameter order: observer/body_id first, then start, end, refracted)
Note: we're not using satellite_in_penumbra() directly — we rely on satellite_shadow_state() for the tri-state and the next_penumbra_entry/exit for transitions. Is that the intended usage pattern?
Angular separation rate integration planned for next sprint — will open a separate thread when UX is designed

6.4 KiB Raw Blame History