ADR-088 — Downrange DOF + range-control entry guidance (the entry computer flies the flight)

Status · Accepted · 2026-08-31 · Operator-directed (Physics Lab spaceflight program) · builds on ADR-087 (kernel systems layer) + RFC-036 (2-DOF descent) · closes the "computer we teach but don't use" gap for re-entry lift-steering

Gating sentence. The planar descent integrator (descent-physics.ts) gains a downrange degree of freedom and a range-control bank law so a lifting capsule's entry computer solves the constant vertical-lift fraction cos(bank) that lands it at a target downrange — the real Apollo/Orion/Soyuz range-control job. This is what the ADR-087 systems/entry-steering controller steers to: without a downrange state a bank law has no landing point to null, so it was taught in the Lab but flown by nothing. The solve is a bisection over the (measured) monotone range-vs-bank curve; every existing descent profile (no targetDownrangeKm) integrates byte-identically at full lift-up.

Context

The re-entry lift-steering "computer" (systems/entry-steering.ts, ADR-087) was taught in the Lab but exercised by zero flights. Investigation found two stacked reasons:

1. Data: no descent profile authored a lift-to-drag, so every capsule — including the Apollo CM (L/D ≈ 0.3) and Soyuz — flew ballistic (~11 g). Fixed by authoring liftToDragRatio on the crewed Earth-return profiles.
   • ENTRY-ANGLE CALIBRATION (Phase 0a — DONE): the profiles previously used a too-steep flightPathAngleDeg: 4 (~2× the real ~1.5° LEO deorbit), inflating peak-g. Re-authored the 29 orbital Earth capsules to 1.5° (suborbital Mercury-Redstone hops stay 18°). Orbital ballistic capsules (Mercury/Vostok/Voskhod) now read ~7.6–7.7 g — matching the flown ~7.8 g. Earlier drafts wrongly cited lunar-return sources (~6–7 g) as "matching the flown value" for these LEO-return flights — corrected (FAA/NASA reentry data: Apollo 7 LEO peak 3.3 g).
   • DRAG-AREA + L/D SOURCING (Phase 1a — DONE; full sourced table in docs/reference/capsule-entry-aerodynamics.md): the lifting capsules read ~7 g not because of the γ-floor (measured: removing it changes nothing at LEO energy) but because entryCdA was ~3× too small. Corrected entryCdA to real/derived drag areas — Apollo/Skylab BC 313.5 kg/m² (NASA, sourced → Cd·A 17.7), others geometry-derived (published base diameter × Apollo-calibrated Cd 1.47). Also corrected liftToDragRatio to sourced values: Apollo 0.3, Soyuz 0.3 (RU sources), Shenzhou 0.2 (CN sources), Dragon 0.18 (Georgia Tech), Gemini 0.19 (DTIC AD0856691). Result: lifting capsules now read ~4.2–5.6 g (was ~7). Flown guided values: Apollo 3.3 g, Soyuz 3–4 g, Shenzhou ≤4 g, Dragon ~4 g — so the model runs +1 to +2.6 g above flown (Soyuz 5.6 g is the worst) because our range solve flies a single FIXED bank; real vehicles ACTIVELY modulate bank to hold a g-limit. MEASURED NEGATIVE RESULT: wiring the kernel's own decel-hold controller (bankLiftFraction) does NOT close this — it overshoots (Apollo target 3 g → peak ~6 g, WORSE than the fixed bank's 4.2 g), because early in entry, with g below target, it digs in to build g. Gain-independent. Holding a target g needs a predictor-corrector (integrate-ahead) controller — a large build, deferred; the residual stands documented, not faked.
   • Synthetic vs sourced fields (Phase 0b/1a — DONE): entryMassKg + liftToDragRatio (all) + Apollo entryCdA are sourced; the ~1.5° flightPathAngleDeg, targetDownrangeKm, and non-Apollo entryCdA are model estimates, declared per-profile in estimatedFields with a test enforcing that estimates are flagged and sourced fields are not — so an estimate cannot silently wear mission-report provenance.
2. Model: the bank controller's real job is downrange range control (steer to the recovery zone) and the lunar-return skip — but the integrator is planar with no downrange state, so a steering law had nothing to steer. A naive decel-hold bank law, applied without a range DOF, only raised peak-g (it modulates lift down from the peak-limiting full-lift-up attitude). That was the honest finding that redirected the work: don't wire a controller with no job — give the model the dimension the controller acts on.

Decision

Downrange state. integrateDescent integrates downrange += v·cosγ·dt, exposed as DescentState.downrangeKm (the entry ground track) and DescentSummary.landingDownrangeKm.

Bank-scaled lift. The entry γ-integration lift becomes L = (L/D)·D·cos(bank). cos(bank) = +1 is full lift-up (peak-limiting attitude: max range, min g); −1 is lift-down (dig in: short range, high g). DescentOptions.entryBankCos carries it; default 1 preserves the prior full-lift-up behaviour exactly.

Range-control solve. A profile with targetDownrangeKm triggers integrateGuidedDescent: downrange is monotone in cos(bank), so a 28-step bisection finds the bank that lands at the target — no per-case tuning. Out-of-footprint targets clamp to the reachable edge and set guidance.targetReachable = false (honest: the computer reports it cannot reach, it does not fake it). The solved bank + reachability ride on DescentSummary.guidance.

This is the range-error → commanded-bank architecture of real entry guidance. The measured footprint for the Apollo CM (7.82 km/s, γ 4°) is ~1083 km (lift-down, 24.6 g) to ~1928 km (lift-up, 7.1 g); a ~1500 km target solves to a mid bank at ~7.5 g. NOTE these ranges + g are the steep-4° model, not flown values (flown ~3.3 g, longer range) — Phase 0a re-calibration to ~1.5° is pending.

Consequences

• The entry computer now flies a real flight — it steers the app's Earth-capsule descent to a chosen landing point, the same range-target → commanded-bank principle the Lab teaches (NOT the same code: the app's integrateGuidedDescent and the Lab's solveEntryBankForRange are separate solvers — reconcile in Phase 0d). Verified: solves to any reachable target; flags the unreachable.
• No behaviour change for the non-lifting profiles — at ship time the range DOF changed nothing for a profile without targetDownrangeKm (entryBankCos defaults to 1, full lift-up). Since Phase 1a the 16 lifting Earth capsules DO set targetDownrangeKm (they fly the guided solve); the other 59 of the 75 shipped profiles are unaffected. Typecheck clean; descent + HUD suites green.
• A ground-track readout (downrangeKm) is now available to the /fly descent scene/HUD.

Non-goals / honest simplifications

• Crossrange / bank reversals — out of scope. Real guidance banks laterally and reverses to null crossrange; this model is planar, downrange-only.
• Live closed-loop guidance — the solve is an offline bisection for a single held bank, not Apollo's stored-reference-trajectory + linearised-gain closed loop flown continuously. The architecture (range target → bank) is faithful; the mechanism is teaching-grade.
• The lunar-return skip (Apollo 4 double-g-pulse at 11 km/s) — deferred to task #29. It needs the γ-floor removed for the super-circular lifting case plus an exo-atmospheric Keplerian coast to bound Euler energy drift; it belongs with the Apollo round-trip capstone where the 11 km/s entry is the point.
• Mars guided-lifting entries — Curiosity/MSL (first guided Mars entry), Perseverance, Tianwen-1 flew real lifting, bank-steered entries. NOW modelled 2-DOF (ADR-089 Phase 2): real ~15° FPA + L/D 0.24 (MSL sourced MSL Entry Guidance), ~6.5–8.5 g (flown MSL ~12 g — the fixed-bank residual, since we fly lift-up without the active bank-modulation that digs deeper).
• Not re-tuning the Lab entry-corridor lesson — the corridor-widening claim (lift roughly doubles the survivable entry-angle band) stands unchanged.