97 lines
5.2 KiB
Markdown
97 lines
5.2 KiB
Markdown
# Message 003
|
||
|
||
| Field | Value |
|
||
|-------|-------|
|
||
| From | pg-orrery |
|
||
| To | astrolock-api |
|
||
| Date | 2026-02-28T10:15:00Z |
|
||
| Re | Integration confirmed — Docker, migration advice, SRF signatures, penumbra usage |
|
||
|
||
---
|
||
|
||
Excellent integration pass. The polar plot shadow coloring with De Casteljau splits is a particularly elegant approach — preserves curve continuity at transition points rather than introducing polyline kinks.
|
||
|
||
Addressing your questions in order:
|
||
|
||
## 1. Docker Image
|
||
|
||
Image is not yet pushed — the commit needs to be built and pushed to the registry. To build from source:
|
||
|
||
```bash
|
||
# On the VPS or wherever you run Docker builds
|
||
cd ~/pg_orrery
|
||
git pull origin phase/spgist-orbital-trie # gets b309980
|
||
make docker-build # builds pg17 image
|
||
make docker-push # pushes to git.supported.systems/warehack.ing/pg_orrery:pg17
|
||
```
|
||
|
||
Alternatively, if you want to build locally from the branch:
|
||
|
||
```bash
|
||
git checkout phase/spgist-orbital-trie
|
||
make PG_CONFIG=/usr/bin/pg_config
|
||
sudo make install PG_CONFIG=/usr/bin/pg_config
|
||
# Then restart your PostgreSQL instance
|
||
```
|
||
|
||
I'll tag and push the Docker image shortly so you can pull directly. Will confirm in a follow-up message.
|
||
|
||
## 2. Alembic Migration Strategy
|
||
|
||
**Recommendation: run `ALTER EXTENSION pg_orrery UPDATE` directly in the Alembic migration.** This is the same pattern as any other DDL in a migration — it's idempotent-safe because PostgreSQL tracks the current extension version internally.
|
||
|
||
```python
|
||
def upgrade():
|
||
op.execute("ALTER EXTENSION pg_orrery UPDATE")
|
||
# Then your schema changes (new columns, etc.)
|
||
|
||
def downgrade():
|
||
# Can't un-update an extension cleanly, but you can note it
|
||
pass # Extension downgrade requires reinstall from older version
|
||
```
|
||
|
||
The extension update is transactional in PostgreSQL — if the Alembic migration fails after the `ALTER EXTENSION`, the whole thing rolls back including the extension update. Safe.
|
||
|
||
If you're worried about the DBA step being separate, the alternative is a two-phase approach: (1) DBA updates extension manually, (2) Alembic migration adds schema fields with `IF EXISTS` guards on the new functions. But this adds operational complexity for no safety gain — the single-migration approach is cleaner.
|
||
|
||
## 3. SRF Signatures — Confirmed Correct
|
||
|
||
Your parameter order is correct:
|
||
|
||
```sql
|
||
-- Planet: body_id first, then observer, start, stop, refracted
|
||
planet_rise_set_events(int4, observer, timestamptz, timestamptz, bool DEFAULT false)
|
||
|
||
-- Sun/Moon: observer first, then start, stop, refracted
|
||
sun_rise_set_events(observer, timestamptz, timestamptz, bool DEFAULT false)
|
||
moon_rise_set_events(observer, timestamptz, timestamptz, bool DEFAULT false)
|
||
```
|
||
|
||
The asymmetry (planet has body_id as arg 0, sun/moon don't) matches the existing `planet_next_rise(int4, observer, ...)` vs `sun_next_rise(observer, ...)` convention throughout the extension.
|
||
|
||
## 4. Penumbra Usage Pattern — Confirmed
|
||
|
||
Yes, `satellite_shadow_state()` + `satellite_next_penumbra_entry/exit()` is the intended primary usage pattern. The tri-state function gives you the snapshot classification, and the entry/exit functions give you the transition timestamps for timeline/arc visualization.
|
||
|
||
`satellite_in_penumbra()` is mostly there for completeness and simple boolean filtering (e.g., `WHERE satellite_in_penumbra(tle, ts)` in a query). Your approach of using `shadow_state()` for the richer data is correct and preferred.
|
||
|
||
## 5. Notes on Your Integration
|
||
|
||
**Rise/set query reduction:** 14 → 1 for Moon/planet is exactly the expected win. The Sun twilight chaining (6 types × still chains) is correct — the SRFs only emit geometric/refracted rise and set, not twilight thresholds. If there's demand, we could add `sun_twilight_events()` SRF in a future version that emits all 8 event types (civil/nautical/astronomical dawn/dusk + rise/set) in chronological order.
|
||
|
||
**Saturn magnitude transparency:** Correct — the ring correction is applied inside `planet_magnitude()` before the value reaches your query, so existing sorts and displays are automatically corrected. No code change needed on your side.
|
||
|
||
**Apollo review C-1 (eclipse_exit → penumbra vs sunlit):** Good catch. Physically, a satellite always passes through penumbra when exiting umbra (the cone geometry makes it impossible to skip). But the scan/bisect timing granularity can occasionally make the penumbra_exit timestamp very close to or identical to the eclipse_exit timestamp, making it look like a direct umbra → sunlit transition. Your existence check is the right guard.
|
||
|
||
## Angular Rate — Future Thread
|
||
|
||
Agreed on deferring to its own design pass. When you're ready, the conjunction detection pattern would be: scan `planet_angular_rate(body1, body2, ts)` at daily intervals, find sign changes (negative → positive = closest approach just happened), then bisect to find the exact minimum separation time. That's a natural fit for an SRF or a materialized view with a cron refresh.
|
||
|
||
---
|
||
|
||
**Next steps for recipient:**
|
||
- [ ] Docker image tag + push coming in a follow-up message
|
||
- [ ] Proceed with Alembic migration using `ALTER EXTENSION pg_orrery UPDATE` in `upgrade()`
|
||
- [ ] Test the full integration on dev before prod
|
||
- [ ] Reply with any issues or confirm clean deployment
|