astrox-python 1.2.0__tar.gz → 1.2.2__tar.gz

{astrox_python-1.2.0 → astrox_python-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: astrox-python
-Version: 1.2.0
+Version: 1.2.2
 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.2.0 → astrox_python-1.2.2}/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 (
@@ -372,11 +372,11 @@ def mpc_ephemeris(
     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. ``step_s`` controls the output sampling cadence; zero
+    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] = {

{astrox_python-1.2.0 → astrox_python-1.2.2}/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 窗口就属于这种情况。
 
 ## 读懂结果
@@ -62,10 +62,11 @@ python compute_lambert_transfer.py
 - `RV1`/`RV2`：出发/到达时的日心位置速度 `[x, y, z, vx, vy, vz]`（位置 m、速度 m/s）；ICRF 分支下转移速度与独立 Lambert 解一致，端点位置方向与 ICRF 轴方向一致。
 - `TimeOfFlightDays`：飞行时间（d），已验证为到达与出发时刻的精确天数差。
 - `ArrivalLightAngle`：到达时刻太阳光照角（deg），已验证为 `DeltaV2` 与 `RV2` 位置矢量的夹角。
+- `MinRangeAu`/`MaxRangeAu`：从出发到到达的转移弧上，距太阳的最小/最大距离（AU，包含端点）。
 
 ## 小行星与显式 MPC 根数
 
-要跳过服务端的 MPC 网络查询，可以显式传入轨道根数：
+要跳过服务端的本地 NEA 目录查询，或使用非 NEA 小行星，可以显式传入轨道根数：
 
 ```python
 elements = celestial.mpc_orbital_elements(

{astrox_python-1.2.0 → astrox_python-1.2.2}/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
@@ -63,10 +63,11 @@ Each result object contains:
 - `RV1`/`RV2`: heliocentric position and velocity at departure/arrival `[x, y, z, vx, vy, vz]` (positions m, velocities m/s); under the ICRF branch the transfer velocities agree with the independent Lambert solution, and the endpoint position directions match the ICRF axes.
 - `TimeOfFlightDays`: time of flight (d), verified to be the exact day difference between the arrival and departure times.
 - `ArrivalLightAngle`: Sun lighting angle at arrival (deg), verified to be the angle between `DeltaV2` and the `RV2` position vector.
+- `MinRangeAu`/`MaxRangeAu`: minimum/maximum distance from the Sun along the departure-to-arrival transfer arc (AU, including endpoints).
 
 ## 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.2.0 → astrox_python-1.2.2}/docs/i18n/en/manual/celestial/README.md

@@ -118,25 +118,25 @@ celestial.mpc_ephemeris(
 ) -> 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` |
 | `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 queries MPC over the network |
+| `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). 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 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 (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 `EclpJ2000ICRF` (MPC convention, server default) and `MeanEclpJ2000` (JPL convention) 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.
+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", step_s=172800.0)
+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
@@ -172,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
@@ -192,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
 
@@ -233,8 +233,8 @@ Samples over the departure time window and the arrival time window, computes Lam
 | `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 |
@@ -280,6 +280,7 @@ The response contains `TransferResults` (an array of transfer results; each elem
 | `RV1` / `RV2` | number[6] | Position and velocity at departure/arrival (heliocentric) `[x, y, z, vx, vy, vz]`, positions m, velocities m/s |
 | `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 |
+| `MinRangeAu` / `MaxRangeAu` | number | Minimum/maximum distance from the Sun along the departure-to-arrival transfer arc, in AU; includes endpoints, rather than describing the full orbit's perihelion/aphelion distances |
 
 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.
 
@@ -288,7 +289,7 @@ Verified (supported by independent cross-validation): omitting `sun_frame` produ
 - `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.

{astrox_python-1.2.0 → astrox_python-1.2.2}/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.2.0 → astrox_python-1.2.2}/docs/manual/celestial/README.md

@@ -118,25 +118,25 @@ celestial.mpc_ephemeris(
 ) -> 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 年 |
 | `step_s` | `Step` | 输出采样步长，单位 s，服务端缺省 86400 s；传入 `0` 时按内部积分步长输出 |
-| `target_elements` | `TargetElements` | 显式 MPC 轨道根数（`mpc_orbital_elements` 构造）；省略时服务端通过网络查询 MPC |
+| `target_elements` | `TargetElements` | 显式 MPC 轨道根数（`mpc_orbital_elements` 构造）；省略时服务端从本地 NEA 目录解析 `target_name` |
 
-该路由从外部 MPC 数据源获取轨道根数（历元为 MJD TDT）。服务端契约声明其使用自适应日心积分器递推，再通过 Hermite 插值重采样到 `step_s` 指定的固定输出网格；`step_s=0` 表示请求按服务端声明的内部积分步长输出。响应为日心系 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` 原样回传，得到的星历与名称查询结果完全一致；省略 `step_s` 与显式传入 `86400` 结果完全一致，`172800` 输出是日采样网格的精确子集，`0` 返回端点一致但中间时间不等距的内部积分网格；`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", step_s=172800.0)
+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 轨道根数
@@ -172,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
@@ -192,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 转移窗口
 
@@ -233,8 +233,8 @@ celestial.lambert_transfer_window(
 | `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，超出的算例被过滤 |
@@ -280,6 +280,7 @@ print(
 | `RV1` / `RV2` | number[6] | 出发/到达时的位置速度（日心系）`[x, y, z, vx, vy, vz]`，位置 m、速度 m/s |
 | `TimeOfFlightDays` | number | 飞行时间，单位 d；已验证为 `ArrivalTime` 与 `DepartureTime` 的精确天数差 |
 | `ArrivalLightAngle` | number | 到达时刻太阳光照角，单位 deg；已验证为 `DeltaV2` 与 `RV2` 位置矢量的夹角 |
+| `MinRangeAu` / `MaxRangeAu` | number | 从出发到到达的转移弧上，距太阳的最小/最大距离，单位 AU；包含端点，不是整条轨道的近日点/远日点距离 |
 
 已验证（独立交叉验证支持）：省略 `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` 选项不改变该路由的到达状态，元素约定仍未确认）。这些分支的数值语义尚未验证，使用前请自行核对。
 
@@ -288,7 +289,7 @@ print(
 - `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"` 字符串。

{astrox_python-1.2.0 → astrox_python-1.2.2}/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.2.0 → astrox_python-1.2.2}/docs/validation/celestial.md

@@ -33,19 +33,20 @@ Status of `celestial.cb_axes_rotation`: `partial` — the same-body identity inv
 
 ## MPC ephemeris
 
-Status of `celestial.mpc_ephemeris`: structure, `target_elements`, `reference_frame`, and output-cadence branches `verified`; absolute numeric values remain external-data-owned and `unverified`.
+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 absolute ASTROX ephemeris semantics. The route fetches orbital elements from the external MPC API (`https://data.minorplanetcenter.net/api/get-orb`, 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 external-data-owned and may change with MPC updates. 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 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.
-- Output cadence: `verified` on a six-day window derived from the current Ceres 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 67137 s to 364863 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 Ceres elements labelled `EclpJ2000ICRF` (MPC convention, server default) versus `MeanEclpJ2000` (JPL convention) produce ephemerides separated by tens of kilometres on the maintained orbit-epoch-derived window (currently about 90 km; `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 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`.
+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, the `MinRangeAu`/`MaxRangeAu` finite-arc extrema, 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.
+- Transfer-arc `MinRangeAu`/`MaxRangeAu`: `verified` using independent `lamberthub.izzo2015` velocities and SciPy DOP853 two-body integration with radial-stationary events and both endpoints. The 22 maintained transfers cover Earth→Mars in ICRF and EclpJ2000ICRF, explicit-element asteroid transfers in ICRF, and 2/4/12/14-day ICRF transfers. They exercise 40 interior and 4 endpoint extrema, distinguishing finite-arc bounds from full-orbit apsides. Maximum observed residual is 1.46e-11 AU, below the pre-set 1e-9 AU bound (the 1e-6 m/s Lambert velocity precision budget accumulated over roughly 300 days is about 2e-10 AU; the remaining margin allows propagation amplification and integration error). Integration uses AU/day units, rtol=2e-12 and atol=2e-14, and independently checks arrival-position closure within 1e-9 AU. This comparison conditions on returned endpoint positions; it does not validate the endpoint ephemerides or resolve the explicit MPC-element convention. SciPy is an existing development dependency.
 - 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.
@@ -61,7 +62,7 @@ Status of `celestial.lambert_transfer_window`: `partial` — the server-default
 
 ## 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 `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 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); the two range fields added in the 2026-09-19 upstream contract are also retained as numeric AU values with a 1e-9 AU absolute comparison tolerance; other 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 detect drift in response shape and the retained range values for 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.2.0 → astrox_python-1.2.2}/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.

{astrox_python-1.2.0 → astrox_python-1.2.2}/examples/11_celestial/celestial_queries.py

@@ -34,8 +34,8 @@ def main() -> None:
     )
     print(f"Earth→Moon 旋转: {len(rotation['Rotation'])} 个数值")
 
-    mpc = celestial.mpc_ephemeris(target_name="Ceres", step_s=172800.0)
-    print(f"Ceres MPC 星历: {len(mpc['Position']['cartesianVelocity']) // 7} 个状态样本")
+    mpc = celestial.mpc_ephemeris(target_name="Apophis", step_s=172800.0)
+    print(f"Apophis MPC 星历: {len(mpc['Position']['cartesianVelocity']) // 7} 个状态样本")
 
     transfer = celestial.lambert_transfer_window(
         departure_body="Earth",

{astrox_python-1.2.0 → astrox_python-1.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "astrox-python"
-version = "1.2.0"
+version = "1.2.2"
 description = "Python SDK for the ASTROX Web API."
 readme = "README.md"
 license = "MIT"
@@ -59,7 +59,7 @@ dev = [
     "astropy>=6.1.7",
     "spiceypy>=8.1.2",
     "scipy>=1.14",
-    "e2m2e==5.8.5",
+    "e2m2e==5.9.5",
 ]
 
 [tool.hatch.build.targets.wheel]

{astrox_python-1.2.0 → astrox_python-1.2.2}/tests/sdk/celestial/test_celestial.py

@@ -166,16 +166,16 @@ def test_cb_axes_rotation_omits_optional_server_defaults(
     )
 
 
-def test_mpc_ephemeris_preserves_external_route_defaults(
+def test_mpc_ephemeris_preserves_server_owned_route_defaults(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     calls = record_raw_post(monkeypatch, RESPONSE)
 
-    celestial.mpc_ephemeris(target_name="Ceres")
+    celestial.mpc_ephemeris(target_name="Apophis")
 
     assert_canonical_equal(
         calls[0],
-        {"endpoint": "/celestial/mpc", "json": {"TargetName": "Ceres"}},
+        {"endpoint": "/celestial/mpc", "json": {"TargetName": "Apophis"}},
     )
 
 
@@ -185,7 +185,7 @@ def test_mpc_ephemeris_lowers_optional_arguments(
     calls = record_raw_post(monkeypatch, RESPONSE)
 
     celestial.mpc_ephemeris(
-        target_name="Ceres",
+        target_name="Apophis",
         observer_frame="topocentric",
         start=START,
         stop=STOP,
@@ -197,7 +197,7 @@ def test_mpc_ephemeris_lowers_optional_arguments(
         {
             "endpoint": "/celestial/mpc",
             "json": {
-                "TargetName": "Ceres",
+                "TargetName": "Apophis",
                 "ObserverFrame": "topocentric",
                 "Start": START,
                 "Stop": STOP,
@@ -212,13 +212,13 @@ def test_mpc_ephemeris_preserves_zero_step(
 ) -> None:
     calls = record_raw_post(monkeypatch, RESPONSE)
 
-    celestial.mpc_ephemeris(target_name="Ceres", step_s=0)
+    celestial.mpc_ephemeris(target_name="Apophis", step_s=0)
 
     assert_canonical_equal(
         calls[0],
         {
             "endpoint": "/celestial/mpc",
-            "json": {"TargetName": "Ceres", "Step": 0.0},
+            "json": {"TargetName": "Apophis", "Step": 0.0},
         },
     )
 
@@ -229,7 +229,7 @@ def test_mpc_ephemeris_omits_none_optional_arguments(
     calls = record_raw_post(monkeypatch, RESPONSE)
 
     celestial.mpc_ephemeris(
-        target_name="Ceres",
+        target_name="Apophis",
         observer_frame=None,
         start=START,
         stop=None,
@@ -240,7 +240,7 @@ def test_mpc_ephemeris_omits_none_optional_arguments(
         calls[0],
         {
             "endpoint": "/celestial/mpc",
-            "json": {"TargetName": "Ceres", "Start": START},
+            "json": {"TargetName": "Apophis", "Start": START},
         },
     )
 
@@ -261,7 +261,7 @@ def test_mpc_ephemeris_omits_none_optional_arguments(
             "order",
         ),
         (celestial.mpc_ephemeris, {"target_name": 1}, "target_name"),
-        (celestial.mpc_ephemeris, {"target_name": "Ceres", "step_s": True}, "step_s"),
+        (celestial.mpc_ephemeris, {"target_name": "Apophis", "step_s": True}, "step_s"),
     ],
 )
 def test_celestial_rejects_mistyped_arguments(
@@ -372,7 +372,7 @@ def test_mpc_ephemeris_lowers_target_elements(
     )
 
     celestial.mpc_ephemeris(
-        target_name="Ceres",
+        target_name="Apophis",
         start=START,
         stop=STOP,
         target_elements=elements,
@@ -383,7 +383,7 @@ def test_mpc_ephemeris_lowers_target_elements(
         {
             "endpoint": "/celestial/mpc",
             "json": {
-                "TargetName": "Ceres",
+                "TargetName": "Apophis",
                 "Start": START,
                 "Stop": STOP,
                 "TargetElements": elements.to_wire(),
@@ -394,7 +394,7 @@ def test_mpc_ephemeris_lowers_target_elements(
 
 def test_mpc_ephemeris_rejects_mistyped_target_elements() -> None:
     with pytest.raises(TypeError, match="target_elements"):
-        celestial.mpc_ephemeris(target_name="Ceres", target_elements={})
+        celestial.mpc_ephemeris(target_name="Apophis", target_elements={})
 
 
 def test_lambert_transfer_window_lowers_delta_v_and_tof_filters(
@@ -451,7 +451,13 @@ def test_lambert_transfer_window_lowers_complete_payload_and_strips_status(
     transfer_response = {
         "IsSuccess": True,
         "Message": "Success",
-        "TransferResults": [{"RV1": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]}],
+        "TransferResults": [
+            {
+                "RV1": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0],
+                "MinRangeAu": 0.8,
+                "MaxRangeAu": 1.6,
+            }
+        ],
         "FutureField": {"preserve": True},
     }
     calls = record_raw_post(monkeypatch, transfer_response)
@@ -472,7 +478,13 @@ def test_lambert_transfer_window_lowers_complete_payload_and_strips_status(
     )
 
     assert response == {
-        "TransferResults": [{"RV1": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]}],
+        "TransferResults": [
+            {
+                "RV1": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0],
+                "MinRangeAu": 0.8,
+                "MaxRangeAu": 1.6,
+            }
+        ],
         "FutureField": {"preserve": True},
     }
     assert response is not transfer_response

{astrox_python-1.2.0 → astrox_python-1.2.2}/tests/validation/README.md

@@ -78,7 +78,7 @@ Run the live lighting cross-validation tests:
 ASTROX_BASE_URL=http://astrox.cn:8765 uv run python -m pytest tests/validation/cross_validation/lighting
 ```
 
-Orekit-backed lighting validation uses `orekit-jpype[jdk4py]` to compare ASTROX spacecraft solar intensity against Orekit's conical Earth-shadow lighting ratio, including a partial-shadow sample. The test loads Orekit data from `OREKIT_DATA_PATH`, defaulting to `/tmp/astrox-python-orekit-data.zip`, and downloads that zip if it is not present.
+Orekit-backed validation uses `orekit-jpype[jdk4py]` for independent lighting and libration comparisons. The test loads a commit-pinned Orekit data archive from `OREKIT_DATA_PATH`, defaulting to `$XDG_CACHE_HOME/astrox-python/orekit-data-<revision>.zip` (or `~/.cache` when `XDG_CACHE_HOME` is unset), and downloads it when the cached content is missing or invalid. Because GitLab-generated archive container bytes may change without a repository change, validation pins a canonical SHA-256 over the archive's member paths and uncompressed contents rather than the ZIP file bytes.
 
 GMAT-backed validation runs through a prepared Docker image. Scheduled SDK health pulls `ghcr.io/<owner>/astrox-gmat-validation:gmat-r2026a`, self-checks it, and sets `ASTROX_EXTERNAL_VALIDATION=strict` before running validation.