astrox-python 1.1.0__tar.gz → 1.2.1__tar.gz

{astrox_python-1.1.0 → astrox_python-1.2.1}/.gitignore

@@ -11,6 +11,9 @@ wheels/
 # Virtual environments
 .venv
 
+# Local-only server runtime for validation triage (never commit)
+.local-runtime/
+
 # Internal & intermediate docs
 *.md
 !README.md

{astrox_python-1.1.0 → astrox_python-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: astrox-python
-Version: 1.1.0
+Version: 1.2.1
 Summary: Python SDK for the ASTROX Web API.
 Project-URL: Homepage, https://github.com/Mtrya/astrox-python
 Project-URL: Repository, https://github.com/Mtrya/astrox-python.git

{astrox_python-1.1.0 → astrox_python-1.2.1}/astrox/celestial.py

@@ -75,8 +75,8 @@ class MpcOrbitalElements:
     argument_of_periapsis_deg: float | None = None
     mean_anomaly_deg: float | None = None
     reference_frame: str | None = None
-    """Heliocentric mean-ecliptic variant: ``MeanEclpJ2000`` (JPL) or
-    ``EclpJ2000ICRF`` (MPC, server default)."""
+    """Heliocentric mean-ecliptic variant: ``MeanEclpJ2000`` (server default)
+    or ``EclpJ2000ICRF``."""
 
     def __post_init__(self) -> None:
         for field_name in (
@@ -369,13 +369,15 @@ def mpc_ephemeris(
     observer_frame: str | None = None,
     start: str | None = None,
     stop: str | None = None,
+    step_s: float | None = None,
     target_elements: MpcOrbitalElements | None = None,
 ) -> dict[str, Any]:
-    """Return ASTROX minor-planet ephemeris output from its MPC-backed route.
+    """Return ASTROX minor-planet ephemeris output from its MPC data route.
 
     When ``target_elements`` is supplied, the server integrates those MPC
-    orbital elements directly instead of resolving ``target_name`` through the
-    MPC network query.
+    orbital elements directly instead of resolving ``target_name`` through its
+    local NEA catalog. ``step_s`` controls the output sampling cadence; zero
+    requests the server's internal integration grid.
     """
     payload: dict[str, Any] = {
         "TargetName": _string(target_name, parameter="target_name"),
@@ -395,6 +397,11 @@ def mpc_ephemeris(
         "Stop",
         _optional_string(stop, parameter="stop"),
     )
+    _include_if_supplied(
+        payload,
+        "Step",
+        _optional_number(step_s, parameter="step_s"),
+    )
     _include_if_supplied(
         payload,
         "TargetElements",

{astrox_python-1.1.0 → astrox_python-1.2.1}/docs/how_to/compute_lambert_transfer.md

@@ -48,9 +48,9 @@ python compute_lambert_transfer.py
 
 ## 需要做的几个决定
 
-1. **选出发与到达天体**：`departure_body`/`arrival_body` 接受服务端支持的天体名称（如 `Earth`、`Mars`、`Ceres`）以及 MPC 编号或名称（如 `2015 XF261`）。小行星省略对应的 `*_elements` 参数时，服务端通过网络查询 MPC 根数。
+1. **选出发与到达天体**：`departure_body`/`arrival_body` 接受服务端支持的天体名称（如 `Earth`、`Mars`、`Ceres`）以及 MPC 编号或名称（如 `2015 XF261`）。近地小行星省略对应的 `*_elements` 参数时，服务端从每日更新的本地 NEA 目录读取根数；其他小行星需显式提供根数。
 2. **定两个时间窗口**：`departure_start`/`departure_stop` 与 `arrival_start`/`arrival_stop` 各定义一个 UTC 时间窗口，SDK 分别组合为 `DepartureInterval`/`ArrivalInterval` 的 `"开始/结束"` 字符串。`departure_step_days` 与 `arrival_step_days`（单位 d）控制窗口内的采样步长，结果个数约等于两个窗口采样点数的乘积；示例中的 2 个出发日 × 3 个到达日产生 6 条结果。`min_time_of_flight_days`（单位 d，整数）过滤掉转移时间太短的组合，服务端缺省 10。
-3. **选输出参考系**：`sun_frame` 服务端缺省 `MeanEclpJ2000`；`ICRF` 分支的转移速度已与独立零圈顺行 Lambert 解一致，端点位置方向也已识别为 ICRF 轴方向，而 `MeanEclpJ2000` 与 ICRF 的精确关系尚未独立确认，需要参考系明确的数值时建议显式传 `sun_frame="ICRF"`。
+3. **选输出参考系**：`sun_frame` 服务端缺省 `EclpJ2000ICRF`；`ICRF` 分支的转移速度已与独立零圈顺行 Lambert 解一致，端点位置方向也已识别为 ICRF 轴方向，而 `MeanEclpJ2000` 与 ICRF 的精确关系尚未独立确认，需要参考系明确的数值时建议显式传 `sun_frame="ICRF"`。
 4. **按需调整过滤上限**：2026-08-20 起服务端按 `max_departure_delta_v_m_s`/`max_arrival_delta_v_m_s`（缺省各 10000 m/s，分别对应出发/到达双曲超速大小）与 `max_time_of_flight_days`（缺省 500 d）过滤算例，全部超界时返回空列表；扫描大 ΔV 或超长转移窗口时需显式放宽，示例中的 Earth→Mars 窗口就属于这种情况。
 
 ## 读懂结果
@@ -65,7 +65,7 @@ python compute_lambert_transfer.py
 
 ## 小行星与显式 MPC 根数
 
-要跳过服务端的 MPC 网络查询，可以显式传入轨道根数：
+要跳过服务端的本地 NEA 目录查询，或使用非 NEA 小行星，可以显式传入轨道根数：
 
 ```python
 elements = celestial.mpc_orbital_elements(

{astrox_python-1.1.0 → astrox_python-1.2.1}/docs/i18n/en/how_to/compute_lambert_transfer.md

@@ -49,9 +49,9 @@ python compute_lambert_transfer.py
 
 ## Decisions to make
 
-1. **Choose the departure and arrival bodies**: `departure_body`/`arrival_body` accept server-supported body names (e.g. `Earth`, `Mars`, `Ceres`) and MPC numbers or names (e.g. `2015 XF261`). When the matching `*_elements` argument is omitted for an asteroid, the server queries the MPC elements over the network.
+1. **Choose the departure and arrival bodies**: `departure_body`/`arrival_body` accept server-supported body names (e.g. `Earth`, `Mars`, `Ceres`) and MPC numbers or names (e.g. `2015 XF261`). When the matching `*_elements` argument is omitted for a near-Earth asteroid, the server reads the elements from its daily-refreshed local NEA catalog; other asteroids require explicit elements.
 2. **Set the two time windows**: `departure_start`/`departure_stop` and `arrival_start`/`arrival_stop` each define a UTC time window, which the SDK combines into the `"start/stop"` string of `DepartureInterval`/`ArrivalInterval` respectively. `departure_step_days` and `arrival_step_days` (unit d) control the sample step within each window; the number of results is roughly the product of the two windows' sample counts — the 2 departure days × 3 arrival days in the example produce 6 results. `min_time_of_flight_days` (unit d, integer) filters out combinations whose transfer time is too short; the server default is 10.
-3. **Choose the output reference frame**: the server default for `sun_frame` is `MeanEclpJ2000`; the transfer velocities of the `ICRF` branch agree with an independent zero-revolution prograde Lambert solution, and the endpoint position directions have also been identified as ICRF axes, while the exact relationship between `MeanEclpJ2000` and ICRF is not yet independently confirmed, so pass `sun_frame="ICRF"` explicitly when you need numbers with an identified frame.
+3. **Choose the output reference frame**: the server default for `sun_frame` is `EclpJ2000ICRF`; the transfer velocities of the `ICRF` branch agree with an independent zero-revolution prograde Lambert solution, and the endpoint position directions have also been identified as ICRF axes, while the exact relationship between `MeanEclpJ2000` and ICRF is not yet independently confirmed, so pass `sun_frame="ICRF"` explicitly when you need numbers with an identified frame.
 4. **Adjust the filter bounds as needed**: since 2026-08-20 the server filters cases by `max_departure_delta_v_m_s`/`max_arrival_delta_v_m_s` (defaults 10000 m/s each, the departure/arrival hyperbolic excess speed magnitudes) and `max_time_of_flight_days` (default 500 d), returning an empty list when everything is out of bounds; widen the bounds explicitly when scanning large-ΔV or very long transfer windows — the Earth→Mars window in the example is such a case.
 
 ## Reading the results
@@ -66,7 +66,7 @@ Each result object contains:
 
 ## Asteroids and explicit MPC elements
 
-To skip the server's MPC network query, you can pass orbital elements explicitly:
+To bypass the server's local NEA catalog lookup, or to use a non-NEA asteroid, pass orbital elements explicitly:
 
 ```python
 elements = celestial.mpc_orbital_elements(

{astrox_python-1.1.0 → astrox_python-1.2.1}/docs/i18n/en/manual/celestial/README.md

@@ -32,7 +32,7 @@ Computes an ephemeris for a target body over a time window and returns a raw JSO
 | `start` | `Start` | Analysis start time (UTC, `yyyy-MM-ddTHH:mm:ssZ`). Optional; the server default is January 1 of the current year |
 | `stop` | `Stop` | Analysis stop time (UTC). Optional; the server default is December 31 of the current year |
 | `observer_name` | `ObserverName` | Observer name, e.g. `Earth`; the server default is `Sun` |
-| `observer_frame` | `ObserverFrame` | Observer frame, server options `FIXED`, `INERTIAL`, `MeanEclpJ2000`, `J2000`, default `MeanEclpJ2000` |
+| `observer_frame` | `ObserverFrame` | Observer frame; the server currently accepts `FIXED`, `INERTIAL`, `MeanEclpJ2000`, `EclpJ2000ICRF`, `J2000`, and `ICRF`; default `MeanEclpJ2000` |
 | `step_s` | `Step` | Sample step, in s, server default 86400 s |
 
 `target_name` is the only required request field of this function; `start` and `stop` are optional — when omitted they are not sent to ASTROX and the server selects January 1 to December 31 of the current year as the window. Other optional fields that are not supplied are likewise not sent to ASTROX, and the server retains its default values.
@@ -43,7 +43,7 @@ from astrox import celestial
 start = "2026-01-01T00:00:00.000Z"
 stop = "2026-01-02T00:00:00.000Z"
 
-for frame in ("J2000", "MeanEclpJ2000"):
+for frame in ("J2000", "MeanEclpJ2000", "EclpJ2000ICRF"):
     ephemeris = celestial.ephemeris(
         target_name="Moon",
         start=start,
@@ -81,11 +81,11 @@ Computes the rotation from the coordinate axes of the source central body to tho
 | `from_central_body` | `FromCbName` | Source central body name, e.g. `Earth` |
 | `to_central_body` | `ToCbName` | Target central body name, e.g. `Moon` |
 | `epoch` | `Epoch` | Epoch time (UTC) |
-| `from_frame` | `FromCbFrame` | Source frame, server options `FIXED`, `INERTIAL`, `J2000`, `ICRF`, `MeanEclpJ2000`, default `INERTIAL` |
+| `from_frame` | `FromCbFrame` | Source frame, server options `FIXED`, `INERTIAL`, `J2000`, `ICRF`, `MeanEclpJ2000`, `EclpJ2000ICRF`, default `INERTIAL` |
 | `to_frame` | `ToCbFrame` | Target frame, same options, default `FIXED` |
 | `order` | `Order` | Rotation motion order: `0` returns the quaternion only, `1` returns the quaternion and angular velocity; passed through as an integer |
 
-`order` is preserved as an integer and lowered to the server as-is; the SDK does not rewrite the branch. The `Rotation` field of the response is a numeric array: with `order=0` it has length 4 (quaternion `[qx, qy, qz, qw]`), and with `order=1` it has length 7 (quaternion plus angular-velocity components, unit rad/s per the server documentation). Verified numeric semantics include: for the same central body on both sides with `INERTIAL` frames on both sides, the server returns the identity quaternion with zero angular velocity at `order=1`; the Earth `INERTIAL`→`FIXED` quaternion and angular velocity; and the Earth→Moon `INERTIAL`→`FIXED` angular velocity at `order=1`. The Earth→Moon `INERTIAL`→`FIXED` quaternion is unresolved, and other combinations are unverified, so verify their meaning yourself before use.
+`order` is preserved as an integer and lowered to the server as-is; the SDK does not rewrite the branch. The `Rotation` field of the response is a numeric array: with `order=0` it has length 4 (quaternion `[qx, qy, qz, qw]`), and with `order=1` it has length 7 (quaternion plus angular-velocity components, unit rad/s per the server documentation). Verified numeric semantics include: for the same central body on both sides with `INERTIAL` frames on both sides, the server returns the identity quaternion with zero angular velocity at `order=1`; Earth→Earth `EclpJ2000ICRF`→`ICRF` follows the fixed J2000 mean-obliquity rotation with zero angular velocity at the two maintained epochs and `order=0/1`; the Earth `INERTIAL`→`FIXED` quaternion and angular velocity; and the Earth→Moon `INERTIAL`→`FIXED` angular velocity at `order=1`. The Earth→Moon `INERTIAL`→`FIXED` quaternion is unresolved, and other combinations are unverified, so verify their meaning yourself before use.
 
 ```python
 rotation = celestial.cb_axes_rotation(
@@ -113,28 +113,30 @@ celestial.mpc_ephemeris(
     observer_frame: str | None = None,
     start: str | None = None,
     stop: str | None = None,
+    step_s: float | None = None,
     target_elements: MpcOrbitalElements | None = None,
 ) -> dict[str, Any]
 ```
 
-Queries an MPC minor-planet ephemeris by asteroid name or number and returns a raw JSON response dictionary. When `target_elements` is provided, the server integrates the given MPC orbital elements directly instead of querying MPC over the network.
+Queries an MPC ephemeris by near-Earth asteroid (NEA) name or number and returns a raw JSON response dictionary. Name lookup uses the server's daily-refreshed local NEA catalog. When `target_elements` is provided, the server integrates the given MPC orbital elements directly without consulting that catalog; non-NEA asteroids must use this path.
 
 | Parameter | Wire parameter | Description |
 | --- | --- | --- |
-| `target_name` | `TargetName` | Asteroid name or number, e.g. `Ceres`, `99942` |
+| `target_name` | `TargetName` | Near-Earth asteroid name or number, e.g. `Apophis`, `99942`; non-NEAs also require `target_elements` |
 | `observer_frame` | `ObserverFrame` | Heliocentric frame, server options `FIXED`, `INERTIAL`, `J2000`, `ICRF`, `MeanEclpJ2000`, `EclpJ2000ICRF`, default `MeanEclpJ2000` |
 | `start` | `Start` | Start time (UTC); defaults to the orbital epoch and cannot be earlier than the orbital epoch (server rule) |
 | `stop` | `Stop` | Stop time (UTC); defaults to 1 year after `Start` |
-| `target_elements` | `TargetElements` | Explicit MPC orbital elements (built with `mpc_orbital_elements`); when omitted, the server queries MPC over the network |
+| `step_s` | `Step` | Output sample step, in s, server default 86400 s; pass `0` to output at the internal integration steps |
+| `target_elements` | `TargetElements` | Explicit MPC orbital elements (built with `mpc_orbital_elements`); when omitted, the server resolves `target_name` from its local NEA catalog |
 
-This route fetches orbital elements from the external MPC data source (element epoch in MJD TDT), which the server propagates heliocentrically with a fixed 3-day step, and outputs a heliocentric CZML Position structure. The response contains `OrbitElements` (orbital elements with keys `EpochMjdTdt`, `PeriTimeMjdTdt`, `Q`, `SemimajorAxis`, `Eccentricity`, `Inclination`, `Raan`, `ArgOfPeriapsis`, `MeanAnomaly`, `ReferenceFrame`) and `Position` (CZML structure, same as `ephemeris`). The orbital-element values come from external MPC data, are owned by that external data source, and may change with MPC updates. When `start`/`stop` are omitted, the server uses the orbital-epoch default window (`start` is the orbital epoch and `stop` is one year after it); an explicit fixed window depends on the orbital epoch at query time, and once the external MPC orbital epoch updates, a previously fixed window may fall before the new epoch and be rejected by the server, so prefer omitting the window parameters or following the current epoch.
+This route reads orbital elements from the server's local NEA catalog (element epoch in MJD TDT), which is refreshed daily. The server contract declares adaptive heliocentric integration followed by Hermite interpolation onto the fixed output grid selected by `step_s`; `step_s=0` requests output at the server-declared internal integration steps. The response is a heliocentric CZML Position structure containing `OrbitElements` (orbital elements with keys `EpochMjdTdt`, `PeriTimeMjdTdt`, `Q`, `SemimajorAxis`, `Eccentricity`, `Inclination`, `Raan`, `ArgOfPeriapsis`, `MeanAnomaly`, `ReferenceFrame`) and `Position` (CZML structure, same as `ephemeris`). The catalog's orbital-element values may change with each daily refresh. When `start`/`stop` are omitted, the server uses the orbital-epoch default window (`start` is the orbital epoch and `stop` is one year after it); an explicit fixed window depends on the orbital epoch at query time, and once the catalog epoch updates, a previously fixed window may fall before the new epoch and be rejected by the server, so prefer omitting the window parameters or following the current epoch.
 
-Verified (endpoint-internal invariant): passing the `OrbitElements` returned by a name query back as `target_elements` reproduces the name-query ephemeris exactly; the `reference_frame` values `EclpJ2000ICRF` (MPC convention, server default) and `MeanEclpJ2000` (JPL convention) are two distinguishable branches. See the [celestial validation page](../../../../validation/celestial.md) for the evidence.
+Verified (within-route invariants): passing the `OrbitElements` returned by a name query back as `target_elements` reproduces the name-query ephemeris exactly; omitting `step_s` exactly matches explicit `86400`, `172800` produces an exact subset of the daily grid, and `0` returns the same endpoints on a nonuniform internal integration grid; the `reference_frame` values `MeanEclpJ2000` (the server default for local-catalog and omitted values) and `EclpJ2000ICRF` are two distinguishable branches. This evidence verifies request branches and output-sampling semantics, not absolute orbit accuracy. See the [celestial validation page](../../../../validation/celestial.md) for details.
 
 ```python
-mpc = celestial.mpc_ephemeris(target_name="Ceres")
+mpc = celestial.mpc_ephemeris(target_name="Apophis", step_s=172800.0)
 
-print(f"Ceres MPC ephemeris: {len(mpc['Position']['cartesianVelocity']) // 7} state samples")
+print(f"Apophis MPC ephemeris: {len(mpc['Position']['cartesianVelocity']) // 7} state samples")
 ```
 
 ## Minor-planet MPC orbital elements
@@ -170,7 +172,7 @@ Builds a heliocentric MPC orbital-element fragment. When either the departure or
 | `raan_deg` | `Raan` | deg |
 | `argument_of_periapsis_deg` | `ArgOfPeriapsis` | deg |
 | `mean_anomaly_deg` | `MeanAnomaly` | deg |
-| `reference_frame` | `ReferenceFrame` | Heliocentric ecliptic frame variant: `MeanEclpJ2000` (JPL) or `EclpJ2000ICRF` (MPC, server default) |
+| `reference_frame` | `ReferenceFrame` | Heliocentric ecliptic frame variant: `MeanEclpJ2000` (server default) or `EclpJ2000ICRF` |
 
 ```python
 from astrox import celestial
@@ -190,7 +192,7 @@ elements = celestial.mpc_orbital_elements(
 print(elements.to_wire())
 ```
 
-`to_wire()` returns the ASTROX `MpcOrbElements` request fragment; the example above prints `{'EpochMjdTdt': 61000.0, 'PeriTimeMjdTdt': 60900.0, 'Q': 0.6740515, 'SemimajorAxis': 0.9898367, 'Eccentricity': 0.3190276, 'Inclination': 0.79379, 'Raan': 209.81829, 'ArgOfPeriapsis': 100.88187, 'MeanAnomaly': 120.0}`. When passed to `lambert_transfer_window`, the server propagates heliocentrically directly with these elements and no longer queries MPC over the network. The independent Kepler propagation of explicit elements in that route is unverified: the element system and time convention are not confirmed (the `reference_frame` option does not change the arrival states of that route); the `target_elements` branch of `mpc_ephemeris` is verified (see above), so verify the meaning yourself before use.
+`to_wire()` returns the ASTROX `MpcOrbElements` request fragment; the example above prints `{'EpochMjdTdt': 61000.0, 'PeriTimeMjdTdt': 60900.0, 'Q': 0.6740515, 'SemimajorAxis': 0.9898367, 'Eccentricity': 0.3190276, 'Inclination': 0.79379, 'Raan': 209.81829, 'ArgOfPeriapsis': 100.88187, 'MeanAnomaly': 120.0}`. When passed to `lambert_transfer_window`, the server propagates heliocentrically directly with these elements and no longer consults the local NEA catalog. The independent Kepler propagation of explicit elements in that route is unverified: the element system and time convention are not confirmed (the `reference_frame` option does not change the arrival states of that route); the `target_elements` branch of `mpc_ephemeris` is verified (see above), so verify the meaning yourself before use.
 
 ## Lambert transfer windows
 
@@ -227,12 +229,12 @@ Samples over the departure time window and the arrival time window, computes Lam
 | `departure_stop` | `DepartureInterval` | Departure time window end (UTC) |
 | `arrival_start` | `ArrivalInterval` | Arrival time window start (UTC); combined with `arrival_stop` into `"start/stop"` |
 | `arrival_stop` | `ArrivalInterval` | Arrival time window end (UTC) |
-| `sun_frame` | `SunFrameName` | Heliocentric frame, server options `MeanEclpJ2000`, `ICRF`, default `MeanEclpJ2000` |
+| `sun_frame` | `SunFrameName` | Heliocentric output frame; the server currently accepts `MeanEclpJ2000`, `EclpJ2000ICRF`, and `ICRF`; default `EclpJ2000ICRF` |
 | `min_time_of_flight_days` | `MinTofDays` | Minimum transfer time, in d, integer; server default 10 |
 | `departure_step_days` | `DepartureStepDay` | Departure time sample step, in d; server default 1 |
 | `arrival_step_days` | `ArrivalStepDay` | Arrival time sample step, in d; server default 1 |
-| `departure_elements` | `DepartureElements` | MPC orbital elements of the departure asteroid (built with `mpc_orbital_elements`); when omitted, the server queries MPC over the network |
-| `arrival_elements` | `ArrivalElements` | MPC orbital elements of the arrival asteroid; when omitted, the server queries MPC over the network |
+| `departure_elements` | `DepartureElements` | MPC orbital elements of the departure asteroid (built with `mpc_orbital_elements`); when omitted for a near-Earth asteroid, the server queries its local NEA catalog, while other asteroids require explicit elements |
+| `arrival_elements` | `ArrivalElements` | MPC orbital elements of the arrival asteroid; when omitted for a near-Earth asteroid, the server queries its local NEA catalog, while other asteroids require explicit elements |
 | `max_departure_delta_v_m_s` | `MaxDepartureDV` | Maximum departure velocity increment (departure hyperbolic excess speed magnitude), in m/s, integer; server default 10000, cases above it are filtered out |
 | `max_arrival_delta_v_m_s` | `MaxArrivalDV` | Maximum arrival velocity increment (arrival hyperbolic excess speed magnitude), in m/s, integer; server default 10000, cases above it are filtered out |
 | `max_time_of_flight_days` | `MaxTofDays` | Maximum transfer time, in d, integer; server default 500, cases above it are filtered out |
@@ -279,14 +281,15 @@ The response contains `TransferResults` (an array of transfer results; each elem
 | `TimeOfFlightDays` | number | Time of flight, in d; verified to be the exact day difference between `ArrivalTime` and `DepartureTime` |
 | `ArrivalLightAngle` | number | Sun lighting angle at arrival, in deg; verified to be the angle between `DeltaV2` and the `RV2` position vector |
 
-Verified (supported by independent cross-validation): with `sun_frame="ICRF"`, the transfer velocities in `RV1`/`RV2` follow the zero-revolution prograde Lambert relationship, and the endpoint position directions use the ICRF axes; `max_departure_delta_v_m_s`/`max_arrival_delta_v_m_s`/`max_time_of_flight_days` filter the sampled grid by the `DV1_Mag`/`DV2_Mag`/time-of-flight upper bounds respectively. Note that since 2026-08-20 the server defaults (10000 m/s each for departure/arrival, 500 d) filter out cases beyond the defaults, so scans over large-ΔV windows need explicitly widened bounds. Unresolved: the exact coordinate relationship between `MeanEclpJ2000` and ICRF, the physical meaning of `DeltaV` relative to the endpoint-body velocities, and independent Kepler propagation of explicit MPC elements (the `reference_frame` option does not change the arrival states of that route; the element convention is still unconfirmed). These branches currently have only request-construction and response-structure evidence, so verify their meaning yourself before use.
+Verified (supported by independent cross-validation): omitting `sun_frame` produces exactly the same `TransferResults` as explicit `EclpJ2000ICRF`; `EclpJ2000ICRF` output is the `ICRF` output rotated by the fixed 23.43929111111111° J2000 mean obliquity; with `sun_frame="ICRF"`, the transfer velocities in `RV1`/`RV2` follow the zero-revolution prograde Lambert relationship, and the endpoint position directions use the ICRF axes; `max_departure_delta_v_m_s`/`max_arrival_delta_v_m_s`/`max_time_of_flight_days` filter the sampled grid by the `DV1_Mag`/`DV2_Mag`/time-of-flight upper bounds respectively. Note that since 2026-08-20 the server defaults (10000 m/s each for departure/arrival, 500 d) filter out cases beyond the defaults, so scans over large-ΔV windows need explicitly widened bounds. Unresolved: the exact coordinate relationship between explicit `MeanEclpJ2000` and ICRF, the physical meaning of `DeltaV` relative to the endpoint-body velocities, and independent Kepler propagation of explicit MPC elements (the `reference_frame` option does not change the arrival states of that route; the element convention is still unconfirmed). The numeric semantics of those branches remain unverified, so check them before use.
 
 ## Convention notes
 
 - `ephemeris` `start` and `stop` are optional; when omitted they are not sent to ASTROX and the server selects January 1 to December 31 of the current year as the window.
 - Each `cartesianVelocity` sample is `[Time, X, Y, Z, dX, dY, dZ]`, with `Time` in seconds from the reference epoch, positions in m, and velocities in m/s.
 - `cb_axes_rotation` passes the integer `order` through as-is; the `Rotation` length corresponds to `order` (`0` → 4, `1` → 7).
-- `mpc_ephemeris` relies on the server's orbital-epoch default window when `start`/`stop` are omitted; an explicit fixed window may expire when the external MPC orbital epoch updates.
+- `mpc_ephemeris` relies on the server's orbital-epoch default window when `start`/`stop` are omitted; an explicit fixed window may expire when the orbital epoch in the local NEA catalog updates.
+- `mpc_ephemeris` `step_s` controls the output sampling grid; when omitted the server default is 86400 s, while `0` outputs at the internal integration steps.
 - The returns of all four functions on this page have the transport-level `IsSuccess` and `Message` removed, and the remaining server fields are preserved; errors are still raised by the HTTP layer (see error handling).
 - `lambert_transfer_window` combines `departure_start`/`departure_stop` and `arrival_start`/`arrival_stop` into the `"start/stop"` strings of `DepartureInterval`/`ArrivalInterval` respectively.
 - `mpc_orbital_elements` only performs the type checks required for lowering and does not perform physical-validity validation; fields that are not supplied do not appear in the `to_wire()` fragment.

{astrox_python-1.1.0 → astrox_python-1.2.1}/docs/i18n/en/manual/coverage/README.md

@@ -362,6 +362,8 @@ count_now = coverage.number_of_assets.by_grid_point_at_time(
 
 Response time returns statistics on uncovered gap durations for each grid point. `compute_type` supports `"Maximum"` and `"Minimum"`.
 
+The dynamic `by_grid_point_at_time` route returns `FOM_Value: null` when a point is currently uncovered and has no later access inside the analysis window. `Minimum`, `Maximum`, and `Average` from `grid_stats_over_time` can also be `null`, so callers should handle `None` when reading these fields.
+
 ```python
 response = coverage.response_time.grid_stats(
     start="2024-01-01T00:00:00.000Z",

{astrox_python-1.1.0 → astrox_python-1.2.1}/docs/manual/celestial/README.md

@@ -32,7 +32,7 @@ celestial.ephemeris(
 | `start` | `Start` | 分析开始时刻（UTC，`yyyy-MM-ddTHH:mm:ssZ`）。可选；服务端缺省为当年 1 月 1 日 |
 | `stop` | `Stop` | 分析结束时刻（UTC）。可选；服务端缺省为当年 12 月 31 日 |
 | `observer_name` | `ObserverName` | 观测者名称，如 `Earth`；服务端缺省为 `Sun` |
-| `observer_frame` | `ObserverFrame` | 观测者坐标系，服务端可选 `FIXED`、`INERTIAL`、`MeanEclpJ2000`、`J2000`，缺省为 `MeanEclpJ2000` |
+| `observer_frame` | `ObserverFrame` | 观测者坐标系，服务端当前接受 `FIXED`、`INERTIAL`、`MeanEclpJ2000`、`EclpJ2000ICRF`、`J2000`、`ICRF`，缺省为 `MeanEclpJ2000` |
 | `step_s` | `Step` | 采样步长，单位 s，服务端缺省 86400 s |
 
 `target_name` 是本函数唯一必填的请求字段；`start` 与 `stop` 可选，省略时不会被发往 ASTROX，由服务端选择当年 1 月 1 日至 12 月 31 日作为窗口，其它未提供的可选字段同样不会被发往 ASTROX，由服务器保留默认值。
@@ -43,7 +43,7 @@ from astrox import celestial
 start = "2026-01-01T00:00:00.000Z"
 stop = "2026-01-02T00:00:00.000Z"
 
-for frame in ("J2000", "MeanEclpJ2000"):
+for frame in ("J2000", "MeanEclpJ2000", "EclpJ2000ICRF"):
     ephemeris = celestial.ephemeris(
         target_name="Moon",
         start=start,
@@ -81,11 +81,11 @@ celestial.cb_axes_rotation(
 | `from_central_body` | `FromCbName` | 起始中心天体名称，如 `Earth` |
 | `to_central_body` | `ToCbName` | 目标中心天体名称，如 `Moon` |
 | `epoch` | `Epoch` | 历元时刻（UTC） |
-| `from_frame` | `FromCbFrame` | 起始坐标系，服务端可选 `FIXED`、`INERTIAL`、`J2000`、`ICRF`、`MeanEclpJ2000`，缺省为 `INERTIAL` |
+| `from_frame` | `FromCbFrame` | 起始坐标系，服务端可选 `FIXED`、`INERTIAL`、`J2000`、`ICRF`、`MeanEclpJ2000`、`EclpJ2000ICRF`，缺省为 `INERTIAL` |
 | `to_frame` | `ToCbFrame` | 目标坐标系，选项同上，缺省为 `FIXED` |
 | `order` | `Order` | 旋转运动阶数：`0` 仅返回四元数，`1` 返回四元数及角速度；整数原样传递 |
 
-`order` 保留为整数并原样 lower 到服务端，SDK 不做分支改写。响应中的 `Rotation` 是数值数组：`order=0` 时长度为 4（四元数 `[qx, qy, qz, qw]`），`order=1` 时长度为 7（四元数加角速度分量，服务端文档标注角速度单位为 rad/s）。已验证的数值语义包括：同一中心天体、两侧均为 `INERTIAL` 时，服务端返回单位四元数且 `order=1` 时角速度为 0；`Earth` 的 `INERTIAL`→`FIXED` 四元数与角速度；`Earth`→`Moon` 的 `INERTIAL`→`FIXED` 在 `order=1` 时的角速度。`Earth`→`Moon` 的 `INERTIAL`→`FIXED` 四元数尚未确认，其它组合未验证，使用前请自行核对。
+`order` 保留为整数并原样 lower 到服务端，SDK 不做分支改写。响应中的 `Rotation` 是数值数组：`order=0` 时长度为 4（四元数 `[qx, qy, qz, qw]`），`order=1` 时长度为 7（四元数加角速度分量，服务端文档标注角速度单位为 rad/s）。已验证的数值语义包括：同一中心天体、两侧均为 `INERTIAL` 时，服务端返回单位四元数且 `order=1` 时角速度为 0；`Earth`→`Earth` 的 `EclpJ2000ICRF`→`ICRF` 在两个已维护历元、`order=0/1` 下符合固定 J2000 平黄赤交角旋转且角速度为 0；`Earth` 的 `INERTIAL`→`FIXED` 四元数与角速度；`Earth`→`Moon` 的 `INERTIAL`→`FIXED` 在 `order=1` 时的角速度。`Earth`→`Moon` 的 `INERTIAL`→`FIXED` 四元数尚未确认，其它组合未验证，使用前请自行核对。
 
 ```python
 rotation = celestial.cb_axes_rotation(
@@ -113,28 +113,30 @@ celestial.mpc_ephemeris(
     observer_frame: str | None = None,
     start: str | None = None,
     stop: str | None = None,
+    step_s: float | None = None,
     target_elements: MpcOrbitalElements | None = None,
 ) -> dict[str, Any]
 ```
 
-按小行星名称或编号查询 MPC 小行星星历，返回原始 JSON 响应字典；提供 `target_elements` 时，服务端直接对给定 MPC 轨道根数积分，不再通过网络查询 MPC。
+按近地小行星（NEA）名称或编号查询 MPC 小行星星历，返回原始 JSON 响应字典。名称查询由服务端每日更新的本地 NEA 目录解析；提供 `target_elements` 时，服务端直接对给定 MPC 轨道根数积分，不再查询该目录，非 NEA 小行星也必须使用这一方式。
 
 | 参数 | wire 参数 | 说明 |
 | --- | --- | --- |
-| `target_name` | `TargetName` | 小行星名称或编号，如 `Ceres`、`99942` |
+| `target_name` | `TargetName` | 近地小行星名称或编号，如 `Apophis`、`99942`；非 NEA 小行星需同时提供 `target_elements` |
 | `observer_frame` | `ObserverFrame` | 日心坐标系，服务端可选 `FIXED`、`INERTIAL`、`J2000`、`ICRF`、`MeanEclpJ2000`、`EclpJ2000ICRF`，缺省为 `MeanEclpJ2000` |
 | `start` | `Start` | 开始时刻（UTC）；缺省为轨道历元时刻，不能早于轨道历元时刻（服务端规则） |
 | `stop` | `Stop` | 结束时刻（UTC）；缺省为 `Start` 起 1 年 |
-| `target_elements` | `TargetElements` | 显式 MPC 轨道根数（`mpc_orbital_elements` 构造）；省略时服务端通过网络查询 MPC |
+| `step_s` | `Step` | 输出采样步长，单位 s，服务端缺省 86400 s；传入 `0` 时按内部积分步长输出 |
+| `target_elements` | `TargetElements` | 显式 MPC 轨道根数（`mpc_orbital_elements` 构造）；省略时服务端从本地 NEA 目录解析 `target_name` |
 
-该路由从外部 MPC 数据源获取轨道根数（历元为 MJD TDT），由服务端以固定 3 天步长进行日心轨道递推，输出为日心系 CZML Position 结构。响应包含 `OrbitElements`（轨道根数，键为 `EpochMjdTdt`、`PeriTimeMjdTdt`、`Q`、`SemimajorAxis`、`Eccentricity`、`Inclination`、`Raan`、`ArgOfPeriapsis`、`MeanAnomaly`、`ReferenceFrame`）与 `Position`（CZML 结构，同 `ephemeris`）。轨道根数的数值来自外部 MPC 数据，属于外部数据所有，可能随 MPC 数据更新而变化。省略 `start`/`stop` 时，服务端使用轨道历元默认窗口（`start` 为轨道历元时刻，`stop` 为其后 1 年）；显式固定窗口依赖查询时的轨道历元，外部 MPC 轨道历元更新后，先前固定的窗口可能早于新历元而被服务端拒绝，建议省略窗口参数或跟随当前历元选择。
+该路由从服务端本地 NEA 目录读取轨道根数（历元为 MJD TDT），目录每日更新。服务端契约声明其使用自适应日心积分器递推，再通过 Hermite 插值重采样到 `step_s` 指定的固定输出网格；`step_s=0` 表示请求按服务端声明的内部积分步长输出。响应为日心系 CZML Position 结构，包含 `OrbitElements`（轨道根数，键为 `EpochMjdTdt`、`PeriTimeMjdTdt`、`Q`、`SemimajorAxis`、`Eccentricity`、`Inclination`、`Raan`、`ArgOfPeriapsis`、`MeanAnomaly`、`ReferenceFrame`）与 `Position`（CZML 结构，同 `ephemeris`）。目录中的轨道根数可能随每日数据刷新而变化。省略 `start`/`stop` 时，服务端使用轨道历元默认窗口（`start` 为轨道历元时刻，`stop` 为其后 1 年）；显式固定窗口依赖查询时的轨道历元，目录更新后，先前固定的窗口可能早于新历元而被服务端拒绝，建议省略窗口参数或跟随当前历元选择。
 
-已验证（端点间不变量）：把名称查询返回的 `OrbitElements` 以 `target_elements` 原样回传，得到的星历与名称查询结果完全一致；`reference_frame` 的 `EclpJ2000ICRF`（MPC 约定，服务端缺省）与 `MeanEclpJ2000`（JPL 约定）是可区分的两个分支。验证证据见 [celestial 验证页](../../validation/celestial.md)。
+已验证（路由内不变量）：把名称查询返回的 `OrbitElements` 以 `target_elements` 原样回传，得到的星历与名称查询结果完全一致；省略 `step_s` 与显式传入 `86400` 结果完全一致，`172800` 输出是日采样网格的精确子集，`0` 返回端点一致但中间时间不等距的内部积分网格；`reference_frame` 的 `MeanEclpJ2000`（本地 NEA 目录与省略值时的服务端缺省）与 `EclpJ2000ICRF` 是可区分的两个分支。这些证据验证请求分支与输出采样语义，不验证绝对轨道精度；详见 [celestial 验证页](../../validation/celestial.md)。
 
 ```python
-mpc = celestial.mpc_ephemeris(target_name="Ceres")
+mpc = celestial.mpc_ephemeris(target_name="Apophis", step_s=172800.0)
 
-print(f"Ceres MPC 星历: {len(mpc['Position']['cartesianVelocity']) // 7} 个状态样本")
+print(f"Apophis MPC 星历: {len(mpc['Position']['cartesianVelocity']) // 7} 个状态样本")
 ```
 
 ## 小行星 MPC 轨道根数
@@ -170,7 +172,7 @@ celestial.mpc_orbital_elements(
 | `raan_deg` | `Raan` | deg |
 | `argument_of_periapsis_deg` | `ArgOfPeriapsis` | deg |
 | `mean_anomaly_deg` | `MeanAnomaly` | deg |
-| `reference_frame` | `ReferenceFrame` | 日心平黄道坐标系变体：`MeanEclpJ2000`（JPL）或 `EclpJ2000ICRF`（MPC，服务端缺省） |
+| `reference_frame` | `ReferenceFrame` | 日心平黄道坐标系变体：`MeanEclpJ2000`（服务端缺省）或 `EclpJ2000ICRF` |
 
 ```python
 from astrox import celestial
@@ -190,7 +192,7 @@ elements = celestial.mpc_orbital_elements(
 print(elements.to_wire())
 ```
 
-`to_wire()` 返回 ASTROX `MpcOrbElements` 请求片段，上面的示例输出 `{'EpochMjdTdt': 61000.0, 'PeriTimeMjdTdt': 60900.0, 'Q': 0.6740515, 'SemimajorAxis': 0.9898367, 'Eccentricity': 0.3190276, 'Inclination': 0.79379, 'Raan': 209.81829, 'ArgOfPeriapsis': 100.88187, 'MeanAnomaly': 120.0}`。传入 `lambert_transfer_window` 后，服务端直接使用这些根数进行日心轨道递推，不再通过网络查询 MPC。显式根数在该路由中的独立开普勒递推尚未验证，其元素系与时间约定未确认（`reference_frame` 选项不改变该路由的到达状态）；`mpc_ephemeris` 的 `target_elements` 分支已验证（见上文），使用前请自行核对。
+`to_wire()` 返回 ASTROX `MpcOrbElements` 请求片段，上面的示例输出 `{'EpochMjdTdt': 61000.0, 'PeriTimeMjdTdt': 60900.0, 'Q': 0.6740515, 'SemimajorAxis': 0.9898367, 'Eccentricity': 0.3190276, 'Inclination': 0.79379, 'Raan': 209.81829, 'ArgOfPeriapsis': 100.88187, 'MeanAnomaly': 120.0}`。传入 `lambert_transfer_window` 后，服务端直接使用这些根数进行日心轨道递推，不再查询本地 NEA 目录。显式根数在该路由中的独立开普勒递推尚未验证，其元素系与时间约定未确认（`reference_frame` 选项不改变该路由的到达状态）；`mpc_ephemeris` 的 `target_elements` 分支已验证（见上文），使用前请自行核对。
 
 ## Lambert 转移窗口
 
@@ -227,12 +229,12 @@ celestial.lambert_transfer_window(
 | `departure_stop` | `DepartureInterval` | 出发时间窗口终点（UTC） |
 | `arrival_start` | `ArrivalInterval` | 到达时间窗口起点（UTC），与 `arrival_stop` 一起 lower 为 `"start/stop"` |
 | `arrival_stop` | `ArrivalInterval` | 到达时间窗口终点（UTC） |
-| `sun_frame` | `SunFrameName` | 日心参考系，服务端可选 `MeanEclpJ2000`、`ICRF`，缺省为 `MeanEclpJ2000` |
+| `sun_frame` | `SunFrameName` | 日心输出参考系，服务端当前接受 `MeanEclpJ2000`、`EclpJ2000ICRF`、`ICRF`，缺省为 `EclpJ2000ICRF` |
 | `min_time_of_flight_days` | `MinTofDays` | 最小转移时间，单位 d，整数；服务端缺省 10 |
 | `departure_step_days` | `DepartureStepDay` | 出发时间采样步长，单位 d；服务端缺省 1 |
 | `arrival_step_days` | `ArrivalStepDay` | 到达时间采样步长，单位 d；服务端缺省 1 |
-| `departure_elements` | `DepartureElements` | 出发小行星的 MPC 轨道根数（`mpc_orbital_elements` 构造）；省略时服务端通过网络查询 MPC |
-| `arrival_elements` | `ArrivalElements` | 到达小行星的 MPC 轨道根数；省略时服务端通过网络查询 MPC |
+| `departure_elements` | `DepartureElements` | 出发小行星的 MPC 轨道根数（`mpc_orbital_elements` 构造）；近地小行星省略时服务端查询本地 NEA 目录，其他小行星需显式提供 |
+| `arrival_elements` | `ArrivalElements` | 到达小行星的 MPC 轨道根数；近地小行星省略时服务端查询本地 NEA 目录，其他小行星需显式提供 |
 | `max_departure_delta_v_m_s` | `MaxDepartureDV` | 最大出发速度增量（出发双曲超速大小），单位 m/s，整数；服务端缺省 10000，超出的算例被过滤 |
 | `max_arrival_delta_v_m_s` | `MaxArrivalDV` | 最大到达速度增量（到达双曲超速大小），单位 m/s，整数；服务端缺省 10000，超出的算例被过滤 |
 | `max_time_of_flight_days` | `MaxTofDays` | 最大转移时间，单位 d，整数；服务端缺省 500，超出的算例被过滤 |
@@ -279,14 +281,15 @@ print(
 | `TimeOfFlightDays` | number | 飞行时间，单位 d；已验证为 `ArrivalTime` 与 `DepartureTime` 的精确天数差 |
 | `ArrivalLightAngle` | number | 到达时刻太阳光照角，单位 deg；已验证为 `DeltaV2` 与 `RV2` 位置矢量的夹角 |
 
-已验证（独立交叉验证支持）：`sun_frame="ICRF"` 时，`RV1`/`RV2` 中的转移速度遵循零圈顺行 Lambert 关系，端点位置方向使用 ICRF 轴；`max_departure_delta_v_m_s`/`max_arrival_delta_v_m_s`/`max_time_of_flight_days` 分别按 `DV1_Mag`/`DV2_Mag`/飞行时间上限过滤采样网格。注意 2026-08-20 起服务端缺省值（出发/到达各 10000 m/s、500 d）会过滤掉超出缺省的算例，扫描大 ΔV 窗口时需显式放宽。未解决：`MeanEclpJ2000` 与 ICRF 之间的精确坐标关系、`DeltaV` 相对端点天体速度的物理含义、显式 MPC 根数的独立开普勒递推（`reference_frame` 选项不改变该路由的到达状态，元素约定仍未确认）。这些分支目前只有请求构造与响应结构层面的证据，使用前请自行核对。
+已验证（独立交叉验证支持）：省略 `sun_frame` 与显式传入 `EclpJ2000ICRF` 的 `TransferResults` 完全一致；`EclpJ2000ICRF` 输出是 `ICRF` 输出按 23.43929111111111° J2000 平黄赤交角进行的固定旋转；`sun_frame="ICRF"` 时，`RV1`/`RV2` 中的转移速度遵循零圈顺行 Lambert 关系，端点位置方向使用 ICRF 轴；`max_departure_delta_v_m_s`/`max_arrival_delta_v_m_s`/`max_time_of_flight_days` 分别按 `DV1_Mag`/`DV2_Mag`/飞行时间上限过滤采样网格。注意 2026-08-20 起服务端缺省值（出发/到达各 10000 m/s、500 d）会过滤掉超出缺省的算例，扫描大 ΔV 窗口时需显式放宽。未解决：显式 `MeanEclpJ2000` 与 ICRF 之间的精确坐标关系、`DeltaV` 相对端点天体速度的物理含义、显式 MPC 根数的独立开普勒递推（`reference_frame` 选项不改变该路由的到达状态，元素约定仍未确认）。这些分支的数值语义尚未验证，使用前请自行核对。
 
 ## 约定说明
 
 - `ephemeris` 的 `start` 与 `stop` 可选；省略时不会被发往 ASTROX，由服务端选择当年 1 月 1 日至 12 月 31 日作为窗口。
 - `cartesianVelocity` 每个样本为 `[Time, X, Y, Z, dX, dY, dZ]`，`Time` 为相对历元的秒数，位置 m、速度 m/s。
 - `cb_axes_rotation` 的 `order` 是整数，SDK 原样传递；`Rotation` 长度与 `order` 对应（`0` → 4，`1` → 7）。
-- `mpc_ephemeris` 省略 `start`/`stop` 时由服务端使用轨道历元默认窗口；显式固定窗口可能因外部 MPC 轨道历元更新而过期。
+- `mpc_ephemeris` 省略 `start`/`stop` 时由服务端使用轨道历元默认窗口；显式固定窗口可能因本地 NEA 目录中的轨道历元更新而过期。
+- `mpc_ephemeris` 的 `step_s` 控制输出采样网格；省略时服务端缺省为 86400 s，传入 `0` 时按内部积分步长输出。
 - 本页四个函数的返回都移除了传输层 `IsSuccess` 与 `Message`，保留其余服务器字段；错误仍由 HTTP 层抛出（见错误处理）。
 - `lambert_transfer_window` 的 `departure_start`/`departure_stop` 与 `arrival_start`/`arrival_stop` 分别组合为 `DepartureInterval`/`ArrivalInterval` 的 `"start/stop"` 字符串。
 - `mpc_orbital_elements` 只做 lowering 所需的类型检查，不做物理有效性校验；未提供的字段不出现在 `to_wire()` 片段中。

{astrox_python-1.1.0 → astrox_python-1.2.1}/docs/manual/coverage/README.md

@@ -362,6 +362,8 @@ count_now = coverage.number_of_assets.by_grid_point_at_time(
 
 响应时间返回每个网格点未被覆盖的间隙时长统计。`compute_type` 支持 `"Maximum"` 和 `"Minimum"`。
 
+指定时刻接口 `by_grid_point_at_time` 在网格点当前未覆盖且分析窗口内没有后续覆盖时返回 `FOM_Value: null`；`grid_stats_over_time` 的 `Minimum`、`Maximum`、`Average` 也可能为 `null`，读取这些字段时应处理 `None`。
+
 ```python
 response = coverage.response_time.grid_stats(
     start="2024-01-01T00:00:00.000Z",

{astrox_python-1.1.0 → astrox_python-1.2.1}/docs/test-principles.md

@@ -68,6 +68,8 @@ Start with the most obvious external convention and expect it to fail. Deliberat
 
 The bounded investigation limit is three external adjustments plus two branch-variant probes per branch. If no explainable residual is found after that budget, mark the case `unresolved` and stop. Do not random-walk parameters.
 
+The budget applies to work against the shared live server. Exploratory probing beyond the budget—wider parameter sweeps, larger case batches, trial-and-error triage—is allowed only against a local ASTROX runtime (see `tests/validation/README.md`). When a local probe finds a candidate convention or mismatch, reduce it to a hypothesis-driven case within the budget and re-confirm it against the live server before it becomes a committed test, snapshot, or evidence claim.
+
 Tolerances are precision bounds for an explained comparison. They are set at the start based on the comparison's claimed precision. They are never widened to absorb an unexplained residual, a unit mistake, a frame confusion, or a branch misunderstanding.
 
 If the residual is stable and can be characterized as "ASTROX does X instead of Y," that is valid calibration. Document the observed ASTROX convention. Do not judge ASTROX against a textbook; the goal is to understand what ASTROX actually does.

{astrox_python-1.1.0 → astrox_python-1.2.1}/docs/validation/celestial.md

@@ -4,59 +4,64 @@ This page records the cross-validation and live-snapshot evidence for `astrox.ce
 
 ## Ephemeris
 
-Status of `celestial.ephemeris`: `partial` — response, wire-declared frame, epoch, and sample-layout fields are `verified`; the numeric geometric state semantics are `unresolved`.
+Status of `celestial.ephemeris`: `partial` — response, wire-declared frame, epoch, sample-layout fields, and the `EclpJ2000ICRF`↔`ICRF` coordinate relation are `verified`; the absolute numeric geometric state semantics are `unresolved`.
 
 - Response structure: `verified` through live snapshots for an explicit Moon window — envelope (`Position`, `Period`; the transport status wrapper fields `IsSuccess`/`Message` are removed from curated returns) and the `Position` keys (`CentralBody`, `referenceFrame`, `epoch`, `interval`, `interpolationAlgorithm`, `interpolationDegree`, `cartesianVelocity`), with `cartesianVelocity` as a 7-value-per-sample list `[Time, X, Y, Z, dX, dY, dZ]` where positions are m and velocities are m/s.
-- Wire-declared frame and central body: `verified` for the maintained cases. `Position.CentralBody` is `Earth` and `Position.referenceFrame` matches the requested `observer_frame` for `J2000` and `MeanEclpJ2000` at the requested epoch.
-- Geometric state semantics: `unresolved`. The maintained executable comparison uses Skyfield 1.54 with the DE421 ephemeris as the independent target-minus-Earth geometric state at the same epoch; `MeanEclpJ2000` is obtained by applying the standard J2000 mean-obliquity rotation (23.439291111 deg) to the same geometric state. The comparison intentionally does not use Skyfield `observe()`, which would apply light-time and compare a retarded apparent state with ASTROX's sampled same-epoch state. DE430t is only probe history (its kernel contains a Mars barycenter segment rather than a Mars center segment) and is not part of the maintained comparison. ASTROX's internal planetary kernel is not known to be identical to Skyfield's, so the comparison stays a calibration probe: the residual is not explained and no passing tolerance is derived.
+- Wire-declared frame and central body: `verified` for the maintained cases. `Position.CentralBody` is `Earth` and `Position.referenceFrame` matches the requested `observer_frame` for `J2000`, `MeanEclpJ2000`, `ICRF`, and `EclpJ2000ICRF` at the requested epoch.
+- `EclpJ2000ICRF`↔`ICRF` coordinate relation: `verified` for Moon and Mars at the three maintained sample offsets. Applying a fixed 23.43929111111111° J2000 mean-obliquity rotation to the live ICRF position and velocity reproduces the live `EclpJ2000ICRF` state within `ECLIPTIC_RELATION_POSITION_ABS_M = 1e-3 m` and `ECLIPTIC_RELATION_VELOCITY_ABS_M_S = 1e-10 m/s`; current maximum residuals are approximately 6.2e-5 m and 7.3e-12 m/s. This verifies the relation between two live branches, not their absolute ephemeris accuracy.
+- Absolute geometric state semantics: `unresolved`. The maintained executable comparison uses Skyfield 1.54 with the DE421 ephemeris as the independent target-minus-Earth geometric state at the same epoch; `MeanEclpJ2000` is obtained by applying the standard J2000 mean-obliquity rotation (23.43929111111111 deg) to the same geometric state. The comparison intentionally does not use Skyfield `observe()`, which would apply light-time and compare a retarded apparent state with ASTROX's sampled same-epoch state. DE430t is only probe history (its kernel contains a Mars barycenter segment rather than a Mars center segment) and is not part of the maintained comparison. ASTROX's internal planetary kernel is not known to be identical to Skyfield's, so the comparison stays a calibration probe: the residual is not explained and no passing tolerance is derived.
 
 Key constants and probes from [`tests/validation/cross_validation/celestial/test_ephemeris_skyfield.py`](../../tests/validation/cross_validation/celestial/test_ephemeris_skyfield.py):
 
 - `START = "2026-01-01T00:00:00.000Z"`, `STOP = "2026-01-02T00:00:00.000Z"`, sample step 43200 s, sample offsets 0, 43200, and 86400 s.
 - Diagnostic resolution thresholds only: position 1e-6 km, velocity 1e-12 km/s. These are not passing tolerances; the numeric comparisons are retained as strict calibration xfails.
-- Coverage: Moon and Mars × `J2000`/`MeanEclpJ2000` × three sample offsets (12 comparisons).
+- Coverage: Moon and Mars × `J2000`/`MeanEclpJ2000` × three sample offsets for the unresolved external-kernel comparisons, plus Moon and Mars × three offsets for the verified live `EclpJ2000ICRF`↔`ICRF` relation.
 
 Known residuals and probe history: at the maintained 2026-01 window the Moon residuals are approximately 0.056 km / 2.37e-7 km/s and the Mars barycenter residuals are approximately 33.6 km / 1.26e-5 km/s; DE421 is similar. Applying an ERFA frame-bias rotation in either direction does not explain both position and velocity residuals. A second 2026-06 window changes the Mars position residual to about 69.8 km, and a 3600 s sample step leaves the 2026-01 residual essentially unchanged. The numeric geometric semantics therefore remain `unresolved`: the comparisons stay visible as strict calibration xfails with the probe notes preserved in the script, and no tolerance is derived from these observations.
 
 ## Central-body axes rotation
 
-Status of `celestial.cb_axes_rotation`: `partial` — the same-body identity invariant, the Earth INERTIAL→FIXED transformation, and the Earth→Moon order=1 angular velocity are `verified`; the Earth→Moon quaternion remains `unresolved`.
+Status of `celestial.cb_axes_rotation`: `partial` — the same-body identity invariant, the Earth→Earth `EclpJ2000ICRF`→`ICRF` relation, the Earth INERTIAL→FIXED transformation, and the Earth→Moon order=1 angular velocity are `verified`; the Earth→Moon quaternion remains `unresolved`.
 
 - Response structure: `verified` through live snapshots for `order=0` (Rotation length 4) and `order=1` (Rotation length 7), with numeric items, on the default Earth→Moon request.
 - Same-body identity invariant: `verified` through [`tests/validation/cross_validation/celestial/test_cb_axes_rotation_invariants.py`](../../tests/validation/cross_validation/celestial/test_cb_axes_rotation_invariants.py). With the same central body on both sides (`Earth` and `Moon`) and `INERTIAL` frames on both sides, the returned Rotation is the identity quaternion `(0, 0, 0, 1)` and the angular-velocity suffix is zero for `order=1`, within `ABS_TOL = 1e-12`, at two maintained epochs (`2026-01-01T00:00:00.000Z` and `2026-06-01T00:00:00.000Z`), for 8 checks total.
+- Earth→Earth `EclpJ2000ICRF`→`ICRF` transformation: `verified` for `order=0` and `order=1` at the two maintained epochs against the analytic fixed 23.43929111111111° J2000 mean-obliquity rotation, within `MATRIX_ABS_TOL = 1e-8`; the current matrix residual is approximately 1.1e-16 and the `order=1` angular velocity is zero within `ABS_TOL = 1e-12`.
 - Earth INERTIAL→FIXED transformation: `verified` for `order=0` and `order=1` against an independent ERFA construction (`c2i06a` plus the Earth rotation angle evaluated with UTC, matching the service's observed UTC rotation convention), at the two maintained epochs, within `MATRIX_ABS_TOL = 1e-8` and `ANGULAR_VELOCITY_ABS_TOL = 1e-10` rad/s.
 - Earth→Moon INERTIAL→FIXED angular velocity (`order=1`): `verified` against an independent SPICE J2000→IAU_MOON orientation derivative (`xf2rav` on the maintained public PCK/DE440 data), at the two maintained epochs; the residual is about 4.7e-11 rad/s, within `ANGULAR_VELOCITY_ABS_TOL = 1e-10` rad/s.
 - Earth→Moon INERTIAL→FIXED quaternion (`order=0`): `unresolved`. The independent SPICE DE440 IAU_MOON orientation differs by 0.001–0.003 degrees across the maintained epochs; the comparison is retained as a strict calibration xfail (`QUATERNION_RESOLUTION_DEG = 1e-6` is a diagnostic resolution, not a passing tolerance) until the ASTROX Moon frame/model convention is identified.
-- Scope boundary: the maintained evidence covers the identity invariant, the Earth INERTIAL→FIXED branch, and the Earth→Moon order=1 angular velocity; the Earth→Moon quaternion and frame combinations beyond these remain `unverified`.
+- Scope boundary: the maintained evidence covers the identity invariant, the Earth→Earth `EclpJ2000ICRF`→`ICRF` relation, the Earth INERTIAL→FIXED branch, and the Earth→Moon order=1 angular velocity; the Earth→Moon quaternion and frame combinations beyond these remain `unverified`.
 
 ## MPC ephemeris
 
-Status of `celestial.mpc_ephemeris`: structure `verified`, `target_elements` branch `verified`, numeric values external-data-owned.
+Status of `celestial.mpc_ephemeris`: structure, `target_elements`, `reference_frame`, and output-cadence branches `verified`; absolute numeric values remain catalog-data-owned and `unverified`.
 
-- Response structure: `verified` through the live snapshot for `target_name="Ceres"` with the server-owned default window (fixed `Start`/`Stop` omitted) — envelope (`OrbitElements`, `Position`; the transport status wrapper fields are removed from curated returns), `OrbitElements` keys (`EpochMjdTdt`, `PeriTimeMjdTdt`, `Q`, `SemimajorAxis`, `Eccentricity`, `Inclination`, `Raan`, `ArgOfPeriapsis`, `MeanAnomaly`, `ReferenceFrame`), and a `Position` CZML-like structure with the same keys as `ephemeris`.
-- Numeric values: `unverified` as ASTROX semantics. The route fetches orbital elements from the external MPC API (`https://data.minorplanetcenter.net/api/get-orb`, element epoch in MJD TDT) and propagates them heliocentrically; since 2026-08-20 the server uses a fixed 3-day step (previously 1-day). The numeric orbital values are external-data-owned and may change with MPC updates. No independent oracle is maintained, so no semantic cross-validation is claimed. The maintained case omits `Start`/`Stop` so the server applies its orbital-epoch default window, avoiding fixed windows that could fall before a future MPC orbital epoch and be rejected.
-- `target_elements` explicit-element branch: `verified` through [`tests/validation/cross_validation/celestial/test_mpc_target_elements.py`](../../tests/validation/cross_validation/celestial/test_mpc_target_elements.py) as an endpoint-to-endpoint invariant: feeding the `OrbitElements` parsed from a name-based Ceres lookup back through `target_elements` reproduces the name-based ephemeris exactly (`ROUNDTRIP_ABS_M = 1e-6`, observed residual 0). This verifies branch wiring, not the absolute ephemeris semantics, which remain external-data-owned.
-- `reference_frame` branch: `verified` as a distinguishing pair. The same Ceres elements labelled `EclpJ2000ICRF` (MPC convention, server default) versus `MeanEclpJ2000` (JPL convention) produce ephemerides separated by about 87 km at the maintained 2026-01 window (`FRAME_SEPARATION_MIN_M = 1000`), so the two labels are live, distinguishable branches; the absolute convention of each label is not independently promoted.
+- Response structure: `verified` through the live snapshot for `target_name="Apophis"` with the server-owned default window (fixed `Start`/`Stop` omitted) — envelope (`OrbitElements`, `Position`; the transport status wrapper fields are removed from curated returns), `OrbitElements` keys (`EpochMjdTdt`, `PeriTimeMjdTdt`, `Q`, `SemimajorAxis`, `Eccentricity`, `Inclination`, `Raan`, `ArgOfPeriapsis`, `MeanAnomaly`, `ReferenceFrame`), and a `Position` CZML-like structure with the same keys as `ephemeris`.
+- Numeric values: `unverified` as absolute ASTROX ephemeris semantics. The route reads orbital elements from the server's daily-refreshed local NEA catalog (element epoch in MJD TDT); the current server contract declares adaptive heliocentric integration followed by Hermite resampling onto the requested fixed output grid. The numeric orbital values are catalog-data-owned and may change with each refresh. No independent orbit oracle is maintained, so no absolute physical-accuracy claim is made. The live snapshot omits `Start`/`Stop` so the server applies its orbital-epoch default window, avoiding fixed windows that could fall before a future catalog epoch and be rejected.
+- `target_elements` explicit-element branch: `verified` through [`tests/validation/cross_validation/celestial/test_mpc_target_elements.py`](../../tests/validation/cross_validation/celestial/test_mpc_target_elements.py) as an endpoint-to-endpoint invariant: feeding the `OrbitElements` parsed from a name-based Apophis lookup back through `target_elements` reproduces the name-based ephemeris exactly (`ROUNDTRIP_ABS_M = 1e-6`, observed residual 0). This verifies branch wiring, not the absolute ephemeris semantics, which remain catalog-data-owned.
+- Output cadence: `verified` on a six-day window derived from the current Apophis element epoch. Omitting `step_s` exactly matches explicit `step_s=86400`; explicit `step_s=172800` returns the exact matching subset of the daily grid; and `step_s=0` returns a distinct, strictly increasing, nonuniform internal grid with the same interval endpoints. The current internal-grid case has four samples, with adjacent intervals from approximately 76910 s to 355090 s. `OUTPUT_GRID_ABS_TOL = 1e-6` is a precision bound for the matching fixed-grid values, whose observed residual is 0. This verifies sampling behavior, not integration accuracy.
+- `reference_frame` branch: `verified` as a distinguishing pair. The same Apophis elements labelled `MeanEclpJ2000` (the local-catalog and omitted-value server default) versus `EclpJ2000ICRF` produce ephemerides separated by approximately 25.3 km on the maintained orbit-epoch-derived window (`FRAME_SEPARATION_MIN_M = 1000`), so the two labels are live, distinguishable branches; the absolute convention of each label is not independently promoted.
 
 ## Lambert transfer windows
 
-Status of `celestial.lambert_transfer_window`: `partial` — the ICRF transfer-state relation for the maintained Earth→Mars grid, the ICRF axis identification of the `RV1`/`RV2` endpoint position directions, the `MinTofDays`/`MaxTofDays`/`MaxDepartureDV`/`MaxArrivalDV` filtering behavior, the DV-magnitude norm invariant, and the `TimeOfFlightDays`/`ArrivalLightAngle` field invariants are `verified`; the MeanEclpJ2000↔ICRF coordinate relation, the physical endpoint-body-velocity interpretation of `DeltaV`, and the independent Kepler semantics of explicit MPC elements are `unresolved`.
+Status of `celestial.lambert_transfer_window`: `partial` — the server-default frame, the `EclpJ2000ICRF`↔`ICRF` coordinate relation, the ICRF transfer-state relation for the maintained Earth→Mars grid, the ICRF axis identification of the `RV1`/`RV2` endpoint position directions, the `MinTofDays`/`MaxTofDays`/`MaxDepartureDV`/`MaxArrivalDV` filtering behavior, the DV-magnitude norm invariant, and the `TimeOfFlightDays`/`ArrivalLightAngle` field invariants are `verified`; the explicit `MeanEclpJ2000`↔`ICRF` coordinate relation, the physical endpoint-body-velocity interpretation of `DeltaV`, and the independent Kepler semantics of explicit MPC elements are `unresolved`.
 
 - ICRF Earth→Mars zero-revolution prograde transfer states: `verified` through [`tests/validation/cross_validation/celestial/test_lambert_transfer_lamberthub.py`](../../tests/validation/cross_validation/celestial/test_lambert_transfer_lamberthub.py). The maintained case compares the complete six UTC departure/arrival timestamp pairs in a 2 departure days × 3 arrival days grid; the independent solver is `lamberthub.izzo2015` with the Sun gravitational parameter (`1.3271244004193938e20 m^3/s^2`), `M=0`, `prograde=True`, and `low_path=True` (a zero-revolution prograde Lambert solution), using the ASTROX `RV1`/`RV2` endpoint positions as its inputs. The ASTROX transfer velocities match the solver within `SOLVER_ABS_TOL_M_S = 1e-6` m/s. The endpoint positions themselves are the solver inputs; their full celestial-state meaning beyond the independently checked directions is not promoted here.
-- ICRF endpoint position-direction axis identification: `verified` through [`tests/validation/cross_validation/celestial/test_lambert_transfer_lamberthub.py`](../../tests/validation/cross_validation/celestial/test_lambert_transfer_lamberthub.py). For each of the six maintained Earth→Mars results, the `RV1`/`RV2` position directions at the returned UTC departure/arrival epochs are compared with independent Skyfield DE421 heliocentric Earth/Mars position directions (body-minus-Sun positions at the same epochs). The direct angular-separation maximum is approximately 8.54e-7 deg, within the pre-set `ICRF_AXIS_IDENTIFICATION_MAX_ANGLE_DEG = 0.01`; the best of the fixed ±23.439291111 deg obliquity rotations applied to the independent directions stays at approximately 22.35 deg maximum separation, above `WRONG_FRAME_MIN_SEPARATION_DEG = 1.0`. This verifies only the identification of the ICRF axes for the endpoint position directions — not full numerical-kernel precision, and not the celestial-state meaning of the endpoint positions beyond their direction. The MeanEclpJ2000↔ICRF coordinate relation, the `DeltaV` physical interpretation, and the explicit MPC-element semantics remain separate `unresolved` items.
+- ICRF endpoint position-direction axis identification: `verified` through [`tests/validation/cross_validation/celestial/test_lambert_transfer_lamberthub.py`](../../tests/validation/cross_validation/celestial/test_lambert_transfer_lamberthub.py). For each of the six maintained Earth→Mars results, the `RV1`/`RV2` position directions at the returned UTC departure/arrival epochs are compared with independent Skyfield DE421 heliocentric Earth/Mars position directions (body-minus-Sun positions at the same epochs). The direct angular-separation maximum is approximately 8.54e-7 deg, within the pre-set `ICRF_AXIS_IDENTIFICATION_MAX_ANGLE_DEG = 0.01`; the best of the fixed ±23.43929111111111 deg obliquity rotations applied to the independent directions stays at approximately 22.35 deg maximum separation, above `WRONG_FRAME_MIN_SEPARATION_DEG = 1.0`. This verifies only the identification of the ICRF axes for the endpoint position directions — not full numerical-kernel precision, and not the celestial-state meaning of the endpoint positions beyond their direction. The explicit `MeanEclpJ2000`↔`ICRF` coordinate relation, the `DeltaV` physical interpretation, and the explicit MPC-element semantics remain separate `unresolved` items.
+- Server-default frame: `verified` on the maintained Earth→Mars grid by exact `TransferResults` equality between omitted `sun_frame` and explicit `sun_frame="EclpJ2000ICRF"`. The default result is distinguishable from explicit `MeanEclpJ2000`, with a current maximum state-vector separation of about 54 km.
+- `EclpJ2000ICRF`↔`ICRF` coordinate relation: `verified` on every `RV1`, `RV2`, `DeltaV1`, and `DeltaV2` vector in the maintained grid. A fixed 23.43929111111111° J2000 mean-obliquity rotation reproduces the ecliptic output from the independently anchored ICRF output within `ECLIPTIC_RELATION_POSITION_ABS_TOL_M = 1e-3 m` and `ECLIPTIC_RELATION_VELOCITY_ABS_TOL_M_S = 1e-9 m/s`; current maximum residuals are approximately 3.1e-5 m and 1.1e-11 m/s.
 - `MinTofDays` filtering: `verified` on a fixed 2×2 Earth→Mars sampling grid (departure 2028-06-01/06-03, arrival 2028-06-05/06-15, `departure_step_days=2.0`, `arrival_step_days=10.0`, `sun_frame="ICRF"`) by exact timestamp-pair comparison: with `min_time_of_flight_days=1` the response contains all four pairs (transfer times of 2, 4, 12, and 14 days), and with `min_time_of_flight_days=10` exactly the 12- and 14-day pairs remain. The evidence covers these two thresholds on this grid only; no other threshold values or grids are covered. Since 2026-08-20 the short-window grid requires explicit wide `MaxDepartureDV`/`MaxArrivalDV` bounds (its transfers need up to about 2e6 m/s), because the server now applies default ΔV/TOF filters.
 - `MaxTofDays`/`MaxDepartureDV`/`MaxArrivalDV` filtering: `verified` on the maintained 2×3 ICRF grid since 2026-08-20. Each bound retains exactly the pairs whose maintained `DV1_Mag`/`DV2_Mag`/timestamp-delta values satisfy it (`max_departure_delta_v_m_s=15000` retains the three 2028-06-03 departures, `max_arrival_delta_v_m_s=5500` retains the three 2028-06-03 arrivals, `max_time_of_flight_days=304` retains the four pairs with TOF ≤ 304 days), and each retained set is strictly smaller than the unfiltered grid, so the fixtures remain distinguishing. The server defaults (10000 m/s departure and arrival, 500 days) filter the maintained grid to zero results, so the maintained fixtures pass explicit wide bounds (`10000000` m/s, `1000` days).
 - `TimeOfFlightDays` field: `verified` since 2026-08-20 as the exact day delta between `ArrivalTime` and `DepartureTime` (abs tol 1e-9 days) on the maintained grid.
 - `ArrivalLightAngle` field: `verified` since 2026-08-20 as the angle in degrees between `DeltaV2` and the `RV2` position vector (abs tol 1e-9 deg, observed residuals at machine precision) on the maintained grid.
 - DV magnitude norm invariant: `verified` on the same maintained grid — `DV1_Mag`/`DV2_Mag` equal the Euclidean norms of `DeltaV1`/`DeltaV2` within `NORM_REL_TOL = 1e-12` and `NORM_ABS_TOL_M_S = 1e-9` m/s.
-- MeanEclpJ2000 ↔ ICRF exact relationship: `unresolved`. Fixed mean-obliquity rotations (±23.439291111 deg) applied to the ICRF transfer states do not explain the MeanEclpJ2000 states. The comparison is retained as a strict calibration xfail; `FRAME_POSITION_DIAGNOSTIC_TOL_M = 1 m` and `FRAME_VELOCITY_DIAGNOSTIC_TOL_M_S = 1e-6 m/s` are diagnostic thresholds, not passing tolerances, and the xfail note explicitly says they must not be widened to absorb the unknown frame relation.
+- Explicit MeanEclpJ2000 ↔ ICRF exact relationship: `unresolved`. Fixed mean-obliquity rotations (±23.43929111111111 deg) applied to the ICRF transfer states do not explain the explicit `MeanEclpJ2000` states. The comparison is retained as a strict calibration xfail; `MEAN_FRAME_POSITION_DIAGNOSTIC_TOL_M = 1 m` and `MEAN_FRAME_VELOCITY_DIAGNOSTIC_TOL_M_S = 1e-6 m/s` are diagnostic thresholds, not passing tolerances, and the xfail note explicitly says they must not be widened to absorb the unknown frame relation.
 - `DeltaV` physical interpretation: `unresolved`. The route does not return the endpoint bodies' velocity convention, so a Skyfield DE421-based endpoint-body-velocity interpretation of `DeltaV1`/`DeltaV2` is retained as a strict calibration xfail with an unexplained residual.
 - Explicit MPC-element independent Kepler semantics: `unresolved`. A local standard elliptic Kepler propagation of the supplied MPC elements (both mean-anomaly-epoch and periapsis-time variants) does not reproduce the ASTROX arrival states; the server's exact element frame and time convention is not identified. The 2026-08-20 `ReferenceFrame` element option was probed with both `EclpJ2000ICRF` and `MeanEclpJ2000` and does not change this route's arrival states, so it does not resolve the convention. The comparison is a strict calibration xfail with `ELEMENT_POSITION_DIAGNOSTIC_TOL_M = 1 m` as a diagnostic threshold.
-- Response structure: `verified` through live snapshots for the Earth→Mars server-default-frame case and the Earth→2015 XF261 explicit-elements ICRF case — `TransferResults` is a non-empty array, and each entry carries `DepartureTime`/`ArrivalTime` strings, `DeltaV1`/`DeltaV2` numeric 3-vectors, `DV1_Mag`/`DV2_Mag` numbers, `RV1`/`RV2` numeric 6-vectors, and (since 2026-08-20) `TimeOfFlightDays`/`ArrivalLightAngle` numbers. Both snapshot cases pass explicit wide filter bounds because the 2026-08-20 server defaults would filter the maintained grids to zero results.
+- Response structure: `verified` through live snapshots for the Earth→Mars server-default-`EclpJ2000ICRF` case and the Earth→2015 XF261 explicit-elements ICRF case — `TransferResults` is a non-empty array, and each entry carries `DepartureTime`/`ArrivalTime` strings, `DeltaV1`/`DeltaV2` numeric 3-vectors, `DV1_Mag`/`DV2_Mag` numbers, `RV1`/`RV2` numeric 6-vectors, and (since 2026-08-20) `TimeOfFlightDays`/`ArrivalLightAngle` numbers. Both snapshot cases pass explicit wide filter bounds because the 2026-08-20 server defaults would filter the maintained grids to zero results.
 
 ## Live snapshot coverage
 
-The celestial functions are exercised in [`tests/validation/live_snapshot/celestial/test_celestial.py`](../../tests/validation/live_snapshot/celestial/test_celestial.py), with sidecar [`tests/validation/live_snapshot/celestial/celestial.snap.json`](../../tests/validation/live_snapshot/celestial/celestial.snap.json) covering `ephemeris` (Moon, explicit window), `cb_axes_rotation` (order 0 and 1), `mpc_ephemeris` (Ceres, server-owned default window), and `lambert_transfer_window` (Earth→Mars with the server-default frame, and Earth→2015 XF261 with explicit MPC elements and `sun_frame="ICRF"`). The snapshots freeze recursive nested type/layout descriptors: per-field value kinds, the CZML `cartesianVelocity` 7-value grouping, the order-dependent `Rotation` lengths (4 for `order=0`, 7 for `order=1`), the MPC `OrbitElements` key set (including `ReferenceFrame` since 2026-08-20), and the transfer-result grid with its `DeltaV` 3-vector and `RV` 6-vector layouts plus the `TimeOfFlightDays`/`ArrivalLightAngle` numbers (since 2026-08-20); volatile numeric values are not frozen, and the MPC numeric values remain external-data-owned. Curated returns remove the transport status wrapper fields `IsSuccess`/`Message`, so the frozen shapes contain only server data fields. These live snapshots are drift detectors for the response shape of maintained public inputs.
+The celestial functions are exercised in [`tests/validation/live_snapshot/celestial/test_celestial.py`](../../tests/validation/live_snapshot/celestial/test_celestial.py), with sidecar [`tests/validation/live_snapshot/celestial/celestial.snap.json`](../../tests/validation/live_snapshot/celestial/celestial.snap.json) covering `ephemeris` (Moon, explicit window), `cb_axes_rotation` (order 0 and 1), `mpc_ephemeris` (Apophis, server-owned default window), and `lambert_transfer_window` (Earth→Mars with the server-default `EclpJ2000ICRF` frame, and Earth→2015 XF261 with explicit MPC elements and `sun_frame="ICRF"`). The snapshots freeze recursive nested type/layout descriptors: per-field value kinds, the CZML `cartesianVelocity` 7-value grouping, the order-dependent `Rotation` lengths (4 for `order=0`, 7 for `order=1`), the MPC `OrbitElements` key set (including `ReferenceFrame` since 2026-08-20), and the transfer-result grid with its `DeltaV` 3-vector and `RV` 6-vector layouts plus the `TimeOfFlightDays`/`ArrivalLightAngle` numbers (since 2026-08-20); volatile numeric values are not frozen, and the MPC numeric values remain catalog-data-owned. Curated returns remove the transport status wrapper fields `IsSuccess`/`Message`, so the frozen shapes contain only server data fields. These live snapshots are drift detectors for the response shape of maintained public inputs.
 
 Cross-validation scripts:
 - [`tests/validation/cross_validation/celestial/test_ephemeris_skyfield.py`](../../tests/validation/cross_validation/celestial/test_ephemeris_skyfield.py)

{astrox_python-1.1.0 → astrox_python-1.2.1}/docs/validation/coverage.md

@@ -168,8 +168,8 @@ FOM cross-validation is organized across [`test_fom_interval_invariants.py`](../
 | `ValueByGridPointAtTime` before first access | verified as remaining duration until next positive-asset interval |
 | `ValueByGridPointAtTime` during access | verified as `0` |
 | `ValueByGridPointAtTime` mixed covered/not-yet-covered | verified pointwise against remaining time to next access |
-| `ValueByGridPointAtTime` after final access | unresolved; live ASTROX HTTP 500 is guarded in live snapshots |
-| `GridStatsOverTime` for intermittent coverage | unresolved; live ASTROX HTTP 500 is guarded in live snapshots |
+| `ValueByGridPointAtTime` after final access | verified as `null` when no later access exists inside the analysis window |
+| `GridStatsOverTime` for intermittent coverage | partial; returns nullable statistics instead of an HTTP error, while exact mixed-null aggregation remains unresolved |
 | `ValueByGridPointAtTime` outside analysis window | verified to reject with an API error, not a silent clamp |
 
 ### Revisit Time
@@ -190,12 +190,13 @@ Known findings:
 - FOM grid statistics use simple arithmetic statistics over point values, not coverage grid weights. This is verified on a representative `LatLonBounds` grid where arithmetic and weighted averages differ.
 - At-time FOM routes use ASTROX's internal transition precision, not the rounded millisecond strings returned in `ComputeCoverage` intervals. A rounded access-start timestamp can still evaluate as uncovered when the precise transition occurs a fraction of a millisecond later.
 - `ResponseTime` differs from `RevisitTime`: when uncovered before a later access, `ResponseTime` returns remaining time until the next access, while `RevisitTime` returns the whole containing gap duration.
+- Dynamic `ResponseTime` returns `null` for an uncovered point when no later access exists inside the analysis window. A never-covered grid therefore returns null per-point values and all-null over-time statistics.
 - For no-coverage cases, `ComputeCoverage` itself currently returns a worker "Index was out of range" error, but most FOM static, at-time, and over-time routes return meaningful edge-case values: `0` for `SimpleCoverage`, `CoverageTime`, and `NumberOfAssets`; full-window duration for `ResponseTime` and `RevisitTime`.
 - For continuous-coverage cases, `ComputeCoverage` also returns a worker error in the covered fixture, but the FOM routes return `1` for `SimpleCoverage` and `NumberOfAssets`, full-window duration for `CoverageTime`, and `0` for `ResponseTime` and `RevisitTime`.
 - Unsupported `ComputeType` strings are rejected by ASTROX for routes that expose `ComputeType`; they are not ignored, defaulted, or silently remapped.
 - `AzElMask` is rejected consistently across representative FOM routes and `ComputeCoverage` in the coverage grid-point role.
 
-Live snapshot sidecar: `coverage.snap.json` covers all public FOM routes, including drift guards for the `ResponseTime` dynamic HTTP 500 cases.
+Live snapshot sidecar: `coverage.snap.json` covers all public FOM routes, including nullable dynamic `ResponseTime` results.
 
 ## Live Snapshot Coverage
 
@@ -206,7 +207,7 @@ The live snapshot layer proves maintained response shape, not semantic correctne
 - Coverage compute with elevation and range grid-point constraints.
 - `percent_coverage` and `coverage_by_asset` reports for one SGP4 asset.
 - All 18 public FOM functions: `simple_coverage`, `coverage_time`, `number_of_assets`, `response_time`, and `revisit_time` across `by_grid_point`, `by_grid_point_at_time`, `grid_stats`, and `grid_stats_over_time` where exposed.
-- Drift guards for `response_time.by_grid_point_at_time` and `response_time.grid_stats_over_time` HTTP 500 behavior in intermittent and no-coverage cases.
+- Nullable `response_time.by_grid_point_at_time` and `response_time.grid_stats_over_time` results in intermittent and no-coverage cases.
 - Drift guard for site-entity coverage assets currently returning a worker error.
 
 The snapshot tolerance is `COVERAGE_SNAPSHOT_ABS_TOL = 2.0e-3`; cross-validation owns semantic precision.