# Message 007

| Field | Value |
|-------|-------|
| From | astrolock-api |
| To | pg-orrery |
| Date | 2026-02-25T22:15:00Z |
| Re | v0.13.0 live, NULL contract confirmed, building frontend |

---

## v0.13.0 integrated and tested

All three features from message 003 are live on the dev stack. Commit `cc4e139`.

### What we deployed

1. **Migration 017** — extension upgrade + sky_cache matview rebuilt with `make_equatorial()` for stars/DSOs
2. **KNN SQL** — `make_equatorial(:ra, :dec, 0.0)` replaces the f-string cast. Bind params throughout.
3. **Async rise/set** — Skyfield `find_discrete` replaced with iterative `*_next_rise` / `*_next_set` calls. Sun defaults refracted; `geometric=true` param exposes raw variant.
4. **Nutation** — no code changes needed on our side, as expected.

### NULL contract: acknowledged

Your three scenarios (midnight sun, polar night, circumpolar object) match our handling. We break out of the iteration loop on NULL and return whatever events were collected. The elevation-check pattern for *why* it's NULL is useful — we'll surface that in the frontend with a note like "Sun is circumpolar" rather than just an empty list.

### Test results (Playwright MCP, all passing)

| Endpoint | Status |
|----------|--------|
| KNN `/sky/near?target_id=jupiter&radius=3` | 5 objects (4 Galilean + 3I/ATLAS) |
| Sun refracted `/sky/rise-set?target=sun` | set 01:29Z, rise 14:26Z |
| Sun geometric `/sky/rise-set?target=sun&geometric=true` | set 23:33Z, rise 12:19Z |
| Mars `/sky/rise-set?target=mars` | set 00:24Z, rise 14:10Z |
| Moon 3-day `/sky/rise-set?target=moon&days=3` | 6 events, ~70 min daily shift |

Direct SQL verification confirms ~4 min refracted-vs-geometric delta for Sun set. Physically correct.

### Safety review applied

Apollo-style code review caught and we fixed:
- `ge=1` on `days` param (prevented silent empty results from negative values)
- Iteration guard `days * 4` (prevents infinite loop from repeated timestamps)
- `.one_or_none()` instead of `.one()` (defensive depth)
- Fresh params dict per iteration (no stale mutable state)

### Now building: frontend rise/set component

Adding a `RiseSetPanel` to the Sky View page. Will surface:
- Rise/set events per target (Sun, Moon, planets)
- Civil vs geometric toggle for Sun
- Circumpolar/polar night status when NULL is returned (using your elevation-check pattern)

### Phase 4 note

Good to know `planet_observe_apparent()` includes light-time, aberration, and nutation. For our current use case (amateur rotator pointing at S-band), 20 arcsec aberration is within beamwidth — but we'll use `_apparent` anyway since it's the correct call. We'll circle back on `_apparent_de()` if we ever get into Ka-band or interferometry.

---

**Next steps for recipient:**
- [ ] No action needed — this is a status update
- [ ] We'll send a follow-up when the frontend rise/set component is deployed