Jpl Moshier Ephemeris Php Laravel Package

Technical Evaluation

Architecture Fit

• Breaking Semantic Change for Extended Bodies: Release 2.0.0 shifts extended-body identifiers into JME's reserved negative range, distinct from core bodies. Applications that persisted numeric extended-body IDs (e.g., in ephemeris_bodies.id, cache keys, or API payloads) must migrate to the new named constants. This is the single largest architectural concern in this release and it is not merely a version bump — it can silently corrupt stored references if not addressed.
• Engine Lifecycle Change: High-level JPL calculations now auto-open the configured kernel and resolve relative kernel names against the configured ephemeris directory. This is a genuine lifecycle simplification (fewer manual open/close calls), but it assumes the kernel path is correctly configured. It moves "kernel not found" failures from lazy runtime discovery to calculation-time exceptions.
• Error-Contract Tightening: Unsupported rise/set options now return explicit errors instead of being silently ignored. This improves observability but is a behavioral break for code that relied on lenient no-ops (e.g., passing an unsupported option and expecting a default result).
• Native Runtime Rebuild (JME 2.0.0 / C17): All bundled runtimes were rebuilt from the JME 2.0.0 C17 source and now ship matching CALCEPH libraries and runtime notices. The major native version bump means the wrapper and native libs must move together — mixed 1.x wrapper + 2.0.0 native (or vice versa) is unsupported and must be prevented.
• Additive Improvements: Consistent extended-body display names, numeric house-system identifiers accepted by house-name lookup, and expanded contract tests are non-breaking quality gains.

Integration Feasibility

• Migration Complexity is Data-Centric, Not Code-Centric: Method names and signatures are unchanged, so the wrapper swap is mechanically simple. The real effort is finding and rewriting persisted numeric extended-body identifiers to named constants across database rows, fixtures, exports, and client contracts.
• Config-Bound Behavior: The configured ephemeris directory is now on the critical path for kernel resolution. Teams must verify relative kernel names resolve correctly under Laravel's runtime working directory (base_path() vs. storage_path() vs. container CWD).
• Native/Runtime Coupling: Because native libs are rebuilt from a major-version source, composer lockstep is mandatory — no partial upgrades.
• CALCEPH Attribution: Bundling CALCEPH libraries introduces license/notice obligations that must be surfaced in deployments and legal review.

Technical Risk

• Silent Data Corruption (Highest): Stored numeric extended-body IDs that remain valid-but-wrong after the range change are the most dangerous failure mode. Require a defensive lookup wrapper that rejects out-of-band IDs.
• Kernel Auto-Open Assumptions: Auto-open + relative-path resolution can break in queued jobs, schedulers, and long-running workers where CWD differs from the web context.
• Rise/Set Error Regressions: Code paths that previously tolerated unsupported options will now throw. Regression test all rise/set call sites.
• Native ABI Drift: The C17 rebuild at a specific commit is reproducible for the vendor but not necessarily for your builders; pin the exact package version and verify checksums.
• Mixed-Version Deployment: Rolling deploys that partially upgrade can leave wrapper/native mismatches. Atomic deploy required.
• Undocumented Edge Cases: The reserved-range migration is documented but boundary transitions (e.g., -1, -2 reserved IDs colliding with legacy stored values) need explicit test coverage.

Key Questions

1. Extended-Body Migration: Where are numeric extended-body IDs persisted (DB columns, JSON, cache keys, API responses), and is there a migration script + backfill planned before the upgrade?
2. Kernel Configuration: Is the ephemeris directory configured consistently across web, queue, and scheduler contexts? How are relative kernel names resolved?
3. Rise/Set Call Sites: Which code passes potentially unsupported rise/set options, and are those call sites regression-tested?
4. CALCEPH Licensing: Has legal reviewed the CALCEPH notices bundled with the runtimes, and are attribution requirements met?
5. Deploy Atomicity: Can the wrapper + native libs be upgraded atomically to prevent 1.x/2.0.0 mixing?
6. Version Pinning: Has composer.json been pinned to 2.0.0 (and native libs checksum-verified) to prevent drift?

Integration Approach

Stack Fit

• PHP 8.3+ remains required (FFI + dynamic loading). Confirm Laravel runtime.
• Ephemeris Config: Formalize a config file (config/ephemeris.php) exposing kernel_dir and kernel_name. Prefer absolute paths derived from storage_path() to survive CWD differences.
• Service Provider Validation: Extend bootstrap validation to check both the native libs/ directory and the configured kernel directory:

  public function boot(): void {
      if (!Ephemeris::isLibraryLoaded()) {
          throw new RuntimeException('Native ephemeris libraries not found. Check libs/.');
      }
      if (!is_dir(config('ephemeris.kernel_dir'))) {
          throw new RuntimeException('Ephemeris kernel directory missing.');
      }
  }
  

• No ORM/Schema Changes to precision columns, but extended-body reference columns may need a type/value migration.

Migration Path

1. Phase 0: Impact Audit
   • Grep for numeric extended-body IDs in code, DB, fixtures, and API contracts.
   • Inventory all rise/set option call sites.
   • Verify kernel directory configuration consistency across contexts.
2. Phase 1: Adopt Named Constants
   • Replace persisted numeric extended-body IDs with named constants.
   • Add a migration to backfill/map legacy values; fail closed on unknown IDs.
3. Phase 2: Harden Kernel Resolution
   • Point kernel_dir to a stable absolute path; test in web, queue, and scheduler.
4. Phase 3: Atomic Native Upgrade
   • Pin 2.0.0; upgrade wrapper + libs/ together; checksum-verify.
5. Phase 4: Regression & Attribution
   • Regression-test rise/set error paths; add CALCEPH notices to deployment docs and legal review.

Compatibility

• Native Matrix: Rebuilt from JME 2.0.0 C17 (commit ab153fd…) with matching CALCEPH libs; Linux x64 reports 2.0.0. 1.x native libs are incompatible with the 2.0.0 wrapper.
• OS/Architecture: Presume the prior support matrix carries forward (Ubuntu 22/24 glibc, macOS arm64, Windows MSVC 2022), but re-validate against the rebuilt runtimes — Alpine/musl remains unsupported.
• Behavioral Contract: Rise/set and kernel-open behavior changes require testing in queue workers and CLI jobs, not just HTTP.

Sequencing

1. Audit persisted numeric IDs and rise/set call sites.
2. Migrate stored values to named constants with a safe backfill.
3. Configure kernel_dir absolutely; validate across runtime contexts.
4. Pin & deploy atomically wrapper + native libs + CALCEPH.
5. Regression test error contracts and kernel resolution.
6. Publish CALCEPH notices and update runbooks.

Operational Impact

Maintenance

• Version Lockstep: Pin package at 2.0.0; never allow wrapper/native divergence. Add a checksum verification step for libs/.
• C17 Build Tracking: The vendor pinned a specific commit; if you ever self-build, record the exact toolchain.
• Dependency Monitoring: Watch for JME 2.x ABI changes and CALCEPH updates; both can invalidate the wrapper contract.
• Config Discipline: Treat ephemeris.kernel_dir as a first-class supported config with docs.

Support

• New Error Surfaces: Unsupported rise/set options and missing kernels now produce explicit errors — support docs and user-facing messages must be updated.
• Extended-Body Lookup Errors: Unknown/legacy IDs now fail closed; prepare a support playbook.
• CALCEPH Notices: Ensure NOTICE/license files ship with deployments.

Scaling

• Negligible overhead from prior dynamic loading remains. Auto-kernel-open may add small per-calculation I/O if kernels aren't cached — verify kernel caching behavior under high-frequency load.

Failure Modes

• Wrong-but-valid extended-body ID (worst): silent misreference — mitigate with lookup guards.
• Kernel not found in workers due to CWD/pathing.
• Rise/set exceptions in code assuming lenient behavior.
• Mixed-version deploy: wrapper/native mismatch crashes at FFI load.
• Missing CALCEPH libs on a target runtime.

Ramp-up

• Moderate: developers must learn the extended-body reserved-range model, the kernel auto-open/config contract, and the stricter error semantics. Plan a short engineering briefing and update onboarding docs with the new contract tests as reference.