e2m2e.api.catalog_ingest#

产物型 Facade 结果 → catalog 记录的构建纯函数（ADR 0031 决策 2/3/8）。

分类字段在生成时填写（不做事后推断）：构建器同时拿着原始请求模型与算法层结果，族类型、平动点、能量都是已知量。主振幅统一为几何主振幅（CR3BP 段位置三分量半极差最大值 × 特征长度，km）；各族定义不一的参数振幅保留在 request 快照中，不进分类字段。

分类学标签（ADR 0042）是**实测**：taxonomy_labels 由分类器对轨迹判定写入，设计侧族标签保留为 provenance；两者冲突记 warning 不失败。不在分类学内的族（拟周期 lissajous、horseshoe、星历冻结 elfo）按映射表置空标签，不跑分类器。

无产物时不建记录（返回 None）：族零成员、站保全样本失败（受控星历缺失）、转移无轨迹（组装失败或搜索零结果）都不产生记录。

Functions#

`stamp_taxonomy_labels`(→ tuple[list[str], list[str \| None]])	对轨道成员做分类学实测打标（ADR 0042 决策 4）。
`build_design_record`(→ tuple[dict, dict[str, ...)	从 design_orbit 的请求与结果构建记录（双段并存）。
`build_family_records`(→ tuple[str, list[tuple[dict[str, ...)	从族结果构建逐成员记录列表（ADR 0045：一轨一记录，绝不打捆）。
`build_family_bundle`(→ tuple[dict, dict[str, ...)	从族结果构建 v1 族束（基线分发包，ADR 0045 决策 8；ADR 0047 出包）。
`build_control_record`(→ tuple[dict, dict[str, ...)	从 control_orbit 的请求与结果构建记录（只含星历段）。
`build_transfer_record`(→ tuple[dict, dict[str, ...)	从 transfer_design 的请求与结果构建记录（#574 transfer record type）。
`finite_or_none`(→ float \| None)

Module Contents#

e2m2e.api.catalog_ingest.stamp_taxonomy_labels(orbit_family: str | None, orbits: collections.abc.Sequence[Any], *, periodicity: str = 'periodic', context: str = '') → tuple[list[str], list[str | None]]#

对轨道成员做分类学实测打标（ADR 0042 决策 4）。

期望集为空的族不跑分类器、全体置空；成员 states 为单点时按最小形态（须有 period）传播一个周期后分类。实测 primary 不在期望集 → 记 warning 不失败（两边都保留，设计侧标签是 provenance）。

Returns:: （记录级去重排序标签列表，成员级 primary 标签列表——无标签成员为 None）。

e2m2e.api.catalog_ingest.build_design_record(request: Any, result: Any) → tuple[dict, dict[str, numpy.ndarray]] | None#

从 design_orbit 的请求与结果构建记录（双段并存）。

Args:: request: DesignOrbitRequest``（已校验、含默认值）。 result: ``OrbitDesignResult。

e2m2e.api.catalog_ingest.build_family_records(request: Any, *, family: Any, status: e2m2e.data.templates.ConvergenceState, cause: e2m2e.data.templates.FailureCause, message: str, requested_members: int, generated_members: int) → tuple[str, list[tuple[dict[str, Any], dict[str, numpy.ndarray]]]] | None#

从族结果构建逐成员记录列表（ADR 0045：一轨一记录，绝不打捆）。

返回 (family_id, [(meta, arrays), …])；零成员返回 None。每条成员记录：族标签三件套（orbit_family + family_id + member_index）、CR3BP 段（states/times）、单点 jacobi 包络、几何主振幅、成员 primary 实测标签；运行级溯源（请求快照、 requested/generated、mu、特征长度、periodicity）随每条成员走。

Args:: request: ``FamilyGenerationRequest``（已校验、含默认值）。 family: ``OrbitFamily``（或读取接口兼容的响应对象）。

e2m2e.api.catalog_ingest.build_family_bundle(request: Any, *, family: Any, status: e2m2e.data.templates.ConvergenceState, cause: e2m2e.data.templates.FailureCause, message: str, requested_members: int, generated_members: int) → tuple[dict, dict[str, numpy.ndarray]] | None#

从族结果构建 v1 族束（基线分发包，ADR 0045 决策 8；ADR 0047 出包）。

仅供 scripts/generate_catalog_baseline.py 打 Release 资产；库内记录一律经 build_family_records() 逐成员写入。成员参数在元数据 members 内，成员数组在 cr3bp/members/ 段（传输格式冻结在 v1 布局，显式导入经 data/catalog/bundle.py 展开）。

Args:: request: ``FamilyGenerationRequest``（已校验、含默认值）。 family: ``OrbitFamily``（或读取接口兼容的响应对象）。

e2m2e.api.catalog_ingest.build_control_record(request: Any, result: Any, *, source_meta: dict[str, Any] | None = None) → tuple[dict, dict[str, numpy.ndarray]] | None#

从 control_orbit 的请求与结果构建记录（只含星历段）。

谱系：source_meta 给出被控轨道记录的元数据时（经 input_record_id 输入），source_record_id 指向它并继承其族/平动点分类；裸星历输入时谱系为空。全样本失败（受控星历缺失）不建记录。

Args:: request: ControlOrbitRequest。 result: ControlOrbitResult。 source_meta: 被控轨道记录的元数据（可选）。

e2m2e.api.catalog_ingest.build_transfer_record(request: Any, result: Any) → tuple[dict, dict[str, numpy.ndarray]] | None#

从 transfer_design 的请求与结果构建记录（#574 transfer record type）。

transfer 专属元数据（transfer_type/delta_v/tli_epoch/tof_sec/ state_frame）放 scalars，轨道分类 6 键置 None/False—— SCHEMA_VERSION 保持 1，零破坏。轨迹大数据走 transfer/ 二进制段（states + times，ADR 0040 契约数据系由 state_frame 标量注明；惯性几何另存 states_gcrs_km，#584——时刻共用 times，段键自带数据系标注）。 tli_epoch 原样存（UTC 字符串或 JD_TDB 浮点）；数值历元才入索引区间列（UTC 字符串历元不作区间过滤）。details 块原样存（后端 details 字段 + #575 结构化机动事件，共用契约）。无轨迹（组装失败或搜索零结果）不建记录。

Args:: request: TransferDesignRequest``（已校验、含默认值）。 result: ``TransferDesignResult。

e2m2e.api.catalog_ingest.finite_or_none(value: Any) → float | None#