MapLibreParticleLab/docs/报告/STEP-075_QBIN2_V4_Binding与ProjectionIdentity_Codex完成报告_v1.md

STEP-075 QBIN2 V4 Binding 与 Projection Identity Codex 完成报告 v1

日期：2026-09-13

已完成

• 完成纯 Core 的 Color/Particle binding 与 projection resolver。Host 仅表达 binding intent；Core 仍拥有 requested forecast time 和 per-field window。
• Identity 由 binding selector、实际 T0/T1 window frame coordinate、所选 plane 与 shared validity 的 content identity 组成；SampleState 单独承载 requested time/mix。U/V/validity 未变化时，Scalar-only revision 不改变 Particle identity。
• U/V 强制 VELOCITY_COMPONENT、MPS equality、U_EAST/V_NORTH 与同组；Direction 强制 DIRECTION_ANGLE/NONE/unit equality。所有 lookup/assertion 都 fail-closed，绝不 fallback 到其他 fieldKey/plane。
• 增加 4 个独立 Binding tests：不同 cadence、MIX identity/storage、Scalar-only revision isolation、错误矩阵和 DirectionAngle。

验证结果

• cmake --build build-linux-opengl --target mbgl-test-runner -j3：PASS（真实重建，输出节流）。
• 规定 GTest filter：50 tests / 0 failures / 0 errors；Binding 4、Runtime/Profile 11、QBIN Decoder/Ingress 24、V3 Source 11。
• git diff --check：PASS。

未完成或无法验证

• Android Gradle/APK/ADB/Jest、iOS/Metal、Renderer/GPU、Host/JNI/RN 均按任务禁止或范围限制未执行，不能标记 PASS。
• 不可插值相邻帧由既有 FieldSeries submit 拒绝，因此合法 Store 不会产生该 resolve window；Resolver 仍保留 InterpolationIncompatible 防御返回。

Git

• 首个 scoped commit：c465b804c，feat: add V4 field binding projection identities。
• 首次 push：成功，31783f25a..c465b804c particle/main -> particle/main。
• 实现提交后的 origin/particle/main HEAD：c465b804c。本报告 Git 字段回填将作为独立 docs-only commit 再次推送。