Theory Manual - Merkabah Application Mission-Planning Core

Scope: the physics and numerics behind every certified verdict the application emits. Written for review by a flight-dynamics-literate reader. Section references name the implementing class and its SPRINTS story; every constant and convention stated here is asserted by the pinned test suite (143 tests at issue; each pin python-twin-verified before implementation - see Section 12).

1. Frames, time, ephemerides

Heliocentric ecliptic-J2000 Cartesian throughout (km, km/s, kg, s). Planetary and spacecraft states from NASA/JPL Horizons caches (CachedEphemerisProvider): per-body time series with cubic Hermite interpolation on position using sampled velocities as endpoint derivatives, velocity as the analytic derivative of the same cubic (Story 25.1). Mission caches are barycentric (500@0) - a documented survey approximation; VALIDATION caches (data/ephemeris/validation) are Sun-centered (500@10), where the heliocentric equations of motion are exact. Time tags are treated uniformly (TDB~UTC conflation is self-consistent on both sides of every comparison).

2. Two-body foundations

Kepler propagation, vis-viva, universal conic relations; Lambert boundary solver with full MULTI-REVOLUTION branch enumeration (SolveAll: N-rev low/high branches by z-bracketing, Story 28.4) used by the transfer scorers and as arc-family seeds.

3. Sphere-of-influence patching (Story 23.6)

r_soi = a (m/M)^(2/5); hyperbolic escape/capture legs in periapsis form; one documented Lambert re-solve between SOI crossing points. The center-to-center vs patched honesty delta is printed per plan (~0.27 km/s Earth->Mars class).

4. Powered flybys and the Oberth ledger (Stories 23.4, 28.2)

Periapsis-form energy bookkeeping: v_p = sqrt(vinf^2 + 2mu/rp); capture/escape dv as differences of periapsis speeds. The Jovian chain (JovianChainPlanner) threads capture ellipse, resonant loiter, and Oberth exit with conservation identities test-enforced.

5. The hybrid chemical+ion optimizer (HybridArrivalOptimizer, Stories 27.x)

Per flip-fraction aim-point Lambert shooting with a sequential four-phase ledger: chemical TMI from the staging basis (Earth/Moon/Mars/small-body Oberth treatment as appropriate), outbound deficit-chase ion, flip, arrival-relative retrograde ion deceleration, chemical capture. Variable-Isp ion grid at constant jet power (F = 2 eta P / Ve, mdot = F/Ve; per-phase Ve selection); chemical-TMI cap auto-optimization (equal-margins sweep); return-aware verdicts (the Closes inequality includes the return requirement). Verdict = CLOSES with per-tank margins.

6. Low-thrust trajectories (Stories 28.5b/d/e)

Solar-electric power P(r) = P_1AU (1 AU / r)^2 evaluated at step start; forward RK4 with zero-order-hold control. V1 steering (survey family: tangential spiral / coast / target-relative proportional-navigation chase) answers existence within its family; V2 (SepFreightV2Planner) is the certification path: QLaw2 equinoctial feedback (per-orbit max-rate normalization, anticipatory mean-longitude phasing bias, effectivity coast, glideslope endgame; race winding searched) warm-starting a damped Levenberg-Marquardt shooting polish on an N-arc RTN thrust table at a fixed arrival gate under weight continuation. Twin-proven doctrine: the feedback law alone does not close rendezvous gates; the polish is required.

7. Magnetoplasma sail model v2 (NonGravitationalForces, Story 28.7)

Ram drag from the solar-wind dynamic pressure (rho = n m_p, (AU/r)^2 density scaling, radial 450 km/s wind); tilted-dipole lift = (L/D <= 0.6) x drag, wind-perpendicular along a commanded hint; pumped-magnetosphere augmentation capped at F = 2 eta P / v_rel (control authority, not thrust). Conservation audited in code comments and tests. RetrogradeLiftHint is the inbound tacking primitive (lift sheds angular momentum; gravity is the keel). Leg pricing in SailLegPricer (Story 28.8) with per-step re-issued hints; twin-measured doctrine: inbound tacking arrives hotter at a circular ring - the sail buys reachability, fall control (to full stall), and propellant-free shaping.

8. Certification-grade numerics (AdaptiveRkf78, Story 29.1)

Fehlberg RK7(8), 13 stages (NASA TR R-287 tableau), local extrapolation; WRMS controller scale_i = atol_i + rtol max(|y_i|,|y_new,i|) with atol 1e-3 km / 1e-9 km/s, accept at ratio <= 1, step factor clamp [0.1, 4] with exponent 1/8, h in [1 s, 40 d]. Observed order 8.31-8.41 on Kepler test orbits; truncation below double-precision roundoff at daily steps on year-scale orbits. Stage-time force evaluation (t + c_i h) makes moving third bodies exact inside every stage.

9. High-fidelity force model (HighFidelityForceModel, Story 29.1)

Central Sun + point-mass third bodies in Battin form a_j = mu_j ((r_j - r)/|r_j - r|^3 - r_j/|r_j|^3) with ephemeris-bound resolvers and published GM values (overridable data); cannonball SRP a = Cr (G_sc/c)(AU/r)^2 (A/m) outward (G_sc 1361 W/m^2); optional first-order Schwarzschild term. The --hifi-propagate mode prints the HONESTY DELTA (full model minus two-body) for any coast arc - the certification correction survey-grade planning ignores (worked case: 200-day coast from 1.8 AU ignores Jupiter at ~14,000-16,000 km).

10. Finite burns (FiniteBurnAnalyzer, Story 29.2)

Constant-thrust flowing-mass burns centered on the reference epoch via time-reversal back-coast; prograde (stage-re-evaluated) or inertial steering; gravity loss = rocket- equation budget minus the equivalent reference-state impulse producing the achieved energy. Twin-pinned doctrine: canon Raptor-bank perijove burns are impulsive-equivalent to millimeters per second; minutes-long departure burns pay metres per second and steering law matters ~13x. Integrator honesty note: thrust windows must be INCLUSIVE at the burnout boundary (the embedded 7/8 estimator is blind to the c = 1 stages).

11. Dispersions and margins (DispersionAnalyzer, Story 29.3)

Monte Carlo over departure-state, burn-magnitude, and pointing errors on an impulsive- burn-plus-coast leg; deterministic SplitMix64 + Box-Muller RNG (fully specified; runs reproduce from seeds); nearest-rank percentiles; linear time-to-go MCC pricing dv = miss / window, convertible to propellant at stated Isp and mass - the statistical margin line over the deterministic tank margins.

12. Verification methodology

Every story lands with an independent python twin that reproduces existing pinned values EXACTLY before any new pin is created; new C# behavior is pinned against twin values with stated tolerances; derived behaviors (convergence order, orderings) are recomputed in tests rather than pinned (Agent Rule 10: nothing mission-shaping hardcoded - ships, epochs, masses, grids, sigmas, and seeds are data). Cross-method checks are preferred wherever two independent formulations exist (Kepler vs RK4; analytic conics vs propagated crossings; closed-form capture vs both twins). Validation against FLOWN trajectories is the subject of docs/validation-report.md.

13. Known model boundaries

No planetary oblateness or natural-satellite dynamics (jovicentric encounter internals are out of scope); no Earth-Moon barycenter split; impulsive burns in the survey planners (finite-burn deltas priced separately by Section 10 and shown to be mm/s-class for the canon bank burns); barycentric mission caches (Sun-centered for validation); no light-time, parallax, or relativistic time transformations beyond the optional Schwarzschild acceleration term.