MapLibreParticleLab/docs/40_任务/STEP-087_QBIN_V3解码与13.4.1-particle.9升级_Codex任务_v1.md

STEP-087 QBIN V3 解码与 13.4.1-particle.9 升级 Codex 任务 v1

1. 任务目标

在 Mac 专用工作树 /Users/tei/dev/MapLibreParticleLab-qbv3-p9 上完成 QBIN V3（Magic=QBV3, version=3）正式解码支持，并将统一 Native / RN 源码版本升级到 13.4.1-particle.9。

本任务必须以以下设计稿为权威依据：

• docs/30_设计/WeatherV2_QBIN_V3通用天气场二进制格式与React独立Render_Binding设计_v2.2_最终冻结稿.md

该设计稿是用户提供原文，必须保留，不得改写、覆盖或删减。实现中如发现规范真实矛盾，只能在完成报告中记录并停止相关 ABI 决策，不得自行修改规范来迁就代码。

2. 当前基线

执行前必须核对：

• 工作树分支：particle/qbv3-p9
• 基线必须包含 release/particle-8 的两笔发布提交，至少到 77744dd9f
• platform/android/VERSION 与 packages/maplibre-particle-rn/package.json 当前均应为 13.4.1-particle.8
• 不得修改其他 Mac 工作树
• 主线目标仍为 origin/particle/main

先阅读项目根目录 AGENTS.md（如存在）、docs/00_项目总则、docs/00_项目规范，以及 STEP-073～085 中与 QBIN ingress、FieldProfile、发布和 iOS device-arm64 相关的最新记录。## 3. Phase 0：只读现状调查

在写代码前完成一次只读调查并在报告中记录结论，至少确认：

• QbinV2Decoder、EncodedFieldIngress::decodeAndValidate()、DecodedFieldFrame、FieldProfileValidator 的真实接口。
• QBV2 source/test 在 Bazel/CMake/平台构建中的注册位置。
• RN / Android / iOS 当前 encoded-field 入口是否只是透传 bytes，确认 QBV3 不需要新增 JS/TS 公共业务 API。
• .8 版本号实际出现在哪些“当前版本”文件中；禁止全仓替换历史文档中的旧版本号。
• 现有 Wind / Rain / Wave / Current QBIN Golden Fixture 的来源、尺寸与可复用性。

结论应坚持：

• V2 与 V3 只在 Encoded Field Ingress 前分流。
• Decoder 后继续输出同一 DecodedFieldFrame / Plane Registry。
• Runtime / Binding / Renderer 不感知 QBV2/QBV3。
• 不把 Provider、Weather Service、HTTP、Manifest、缓存、React 业务逻辑放进 Native Decoder。

4. Block Geometry 冻结

v2.2 规范只剩 BLOCK_WIDTH / BLOCK_HEIGHT 未冻结，本任务必须在正式 QBV3 Decoder 固化前完成选择。

使用现有四类真实 Golden 数据：

• integration/react-native/MapLibreParticleRNTestHost/assets/qbin-golden/wind/
• rain/
• wave/
• current/

优先复用 QBV2 Decoder 得到 canonical quantized integer grid + validity，再用测试/benchmark 专用 deterministic QBV3 encoder/prototype 比较 16×16 与 32×32。该 encoder 仅用于测试、fixture 和 benchmark，不得演变成 Weather Provider/生产 Writer。比较必须使用同一 predictor / ZigZag / Rice 规则，至少记录：

• encoded bytes
• block count / non-empty block count
• encode time
• entropy decode time
• total decode time
• CRC time（若可独立测）
• peak temporary bytes（若现有工具不能可靠测量，报告中明确说明，不得伪造）

选择原则：

1. 首先保证规范一致和 bit-exact round-trip。
2. 压缩率差异很小时，优先更低 decode/encode 开销、更少 block、实现更简单的一项。
3. 最终必须只留下一个 production Block Geometry。
4. production Decoder 不得同时“猜测”16×16/32×32，也不得根据解码是否成功试两遍。
5. 测试代码可以保留两个候选参数用于 benchmark，但正式 QBV3 ABI 常量必须唯一。

把选择依据写入：

• docs/30_设计/MapLibreParticle_QBIN_V3_Decoder与BlockGeometry实施决策_v1.md

该文档是粒子侧实施补充，不改写用户提供的 WeatherV2 v2.2 原文。

5. 正式 QBV3 Decoder

新增清晰独立的 QBV3 decoder 文件，优先采用：

• include/mbgl/particle/ingress/qbin_v3_decoder.hpp
• src/mbgl/particle/ingress/qbin_v3_decoder.cpp

如现有构建结构要求轻微调整可据实处理，但禁止把 V3 逻辑塞成 qbin_v2_decoder.cpp 内的大量 version 分支。实现必须逐项遵守 v2.2 normative 主体，重点包括：

• 112-byte Header、32-byte Descriptor、Little Endian。
• Magic=QBV3、version=3；FRAME 固定 layout/projection/sampleOrder/gridRegistration/tile 字段。
• Version 3 limits：planeCount 32、cellCount 2,097,152、file 64 MiB、decoded frame 32 MiB。
• Header bounds finite、Web Mercator 范围、binary64 数值零禁止 -0.0。
• Numeric dtype 只允许 INT16/UINT16/UINT8/INT8；FLOAT32 与 Numeric BITSET reject。
• semantic==3 ⇔ valueClass==VALIDITY ⇔ dtype==BITSET，且只允许一个 Shared Validity Plane。
• Validity LSB-first；tail unused high bits 必须为 0。
• unknown fieldType（包括 0）只作为 opaque hint，不得单独 reject。
• Numeric scale > 0 finite，offset finite；数值为 0 时只接受 binary32 +0.0。
• Parser 顺序保持：结构与 budget → CRC → padding/Validity → Rice decode。
• CRC-32/ISO-HDLC，CRC field 76..79 计算时视为 0。
• all-invalid 合法：Validity 全 0、Numeric byteLength=0、decoded raw 全 0。
• zero-length Plane 可以共享 canonical byteOffset；只对真实非零 range 做 overlap 判断。
• Numeric Plane byteLength 是各 non-empty block encoded bytes 之和，不含 align16 padding。

Rice / predictor 必须严格实现：

• Predictor 在全 Grid 连续，不在 block 边界 reset。
• invalid cell 不消费 Rice symbol，materialize raw=0。
• ZigZag 使用无 UB 的 widened fixed-width arithmetic。
• Rice bitstream 与 remainder 都按 byte 内 LSB-first。
• riceK 允许 0..31；Decoder permissive，不因非最优 k 单独 reject。
• unary quotient、MAX_Q、residual、raw reconstruction 全部 checked；非法立即 fail-closed。
• block padding high unused bits 必须为 0，symbolCount 必须精确。
• Direction 使用 canonical float32(360/N)、N=floor(360/scale+0.5)、raw∈[0,N)。
• Direction predictor 必须 normalize；half-circle tie 固定 -N/2。## 6. Ingress 与兼容性

EncodedFieldIngress::decodeAndValidate() 必须按 bytes 中的 magic/version 做显式 dispatch：

• QBV2 / version=2 → QbinV2Decoder
• QBV3 / version=3 → QbinV3Decoder
• 其他组合 fail-closed

要求：

• QBV2 frozen behavior 不得改变。
• V3 decode 成功后继续走现有 FieldProfileValidator。
• Binary-valid 与 Profile-valid 继续分层；V3 Decoder 不得根据 wind/wave/rain/current 名称要求业务 Plane。
• V2/V3 decoded Plane 的 ContentIdentity 必须继续使用项目既有 canonical identity 语义，避免 Runtime 因容器版本产生无意义 identity 漂移。
• 如需要抽取共享 helper，可做小范围重构，但不得把公共 API 扩大到 Renderer/Binding。

7. 测试与 Fixture

新增 C++ 定向测试，不新增或运行 Jest。

至少覆盖：

• Wind / Rain / Wave / Current integer + validity bit-exact round-trip。
• INT16 / UINT16 / INT8 / UINT8。
• all-valid、部分 invalid、all-invalid。
• zero-length shared offset。
• bad magic/version/endian、reserved、bounds、negative zero、descriptor order/duplicate、packing、CRC。
• malformed Rice、unterminated unary、riceK>31、symbolCount 少/多、nonzero block padding、MAX_Q/residual/raw overflow。
• non-optimal but otherwise-valid riceK 必须 accept。
• fieldType=0 与 unknown fieldType 必须 accept。
• Direction 359↔0、N-1↔0、half-circle tie、predictor wrap。
• WEB_MERCATOR + NODE sample 公式的定位 Golden Test。

最终冻结 Geometry 后生成唯一正式 QBV3 Golden Fixture 集，至少覆盖四类场；实验 16/32 双候选 fixture 不得混入 production fixture 目录。## 8. 构建与验证

本任务在 Mac 上执行 Native/C++ 开发和精确编译验证。

必须：

• 运行与 QBV2/QBV3 decoder 直接相关的 C++ 定向测试。
• 运行必要的 Mac 原生精确编译，确认新增 source/header 被真实构建目标消费。
• 对 iOS 只验证 iPhone/iPad device arm64 路径；不得恢复 simulator slice。
• 如执行 noisy compile/test，遵循当前 Codex 全局输出节流规则。
• git diff --check 必须 PASS。

禁止：

• Android Gradle build
• AAR/APK 构建或安装
• ADB
• 启动 Android App / 清理数据
• Android 实机/虚拟机冒烟

Android 最终构建安装仍由用户手工执行。本任务应在报告中给出最少的用户手工验证入口，但不要代替用户执行。

9. 升级到 13.4.1-particle.9

以已纳入的 .8 为基线，将当前有效版本升级为： 13.4.1-particle.9

按 .8 的真实发布结构更新所有“当前版本”源文件/配置，包括 Native VERSION、RN package、插件/Android 依赖引用、CHANGELOG/README 中的当前安装示例，以及 release pipeline 需要的当前版本元数据。

禁止：

• 全仓替换历史 STEP / 报告中的 .1～.8。
• 覆盖既有 .8 artifact、tag 或发布目录。
• 未经用户明确要求发布外部 Maven/npm/CDN artifact。
• 未经用户明确要求创建正式 release tag。## 10. 文档输出

除本任务书和用户提供设计稿外，任务必须生成/更新：

• docs/30_设计/MapLibreParticle_QBIN_V3_Decoder与BlockGeometry实施决策_v1.md
• docs/50_Step记录/STEP-087_QBIN_V3解码与13.4.1-particle.9升级_v1.md
• docs/报告/STEP-087_QBIN_V3解码与13.4.1-particle.9升级_Codex完成报告_v1.md

完成报告必须写清：

• 起始 HEAD / 最终 HEAD
• 选定的 Block Geometry 与 benchmark 证据
• 新增/修改的主要代码文件
• QBV2 回归结果
• QBV3 测试结果
• Mac 原生精确编译结果
• 未执行的 Android 手工门槛
• 版本号变更位置
• 仍存在的风险或未完成项

如同主题报告已存在，按 v2/v3 递增，不覆盖旧报告。

11. Git 收尾

完成规定代码、测试、版本和文档后：

1. 只提交本任务相关变更。
2. 不提交无关 untracked 文件或其他工作树内容。
3. commit message 使用清晰英文，例如：feat: add QBIN V3 decoder for particle.9。
4. 将最终结果 push 到公开远端 origin/particle/main。
5. push 失败不得声称完成。
6. 完成报告必须记录最终 commit hash、commit message、push result、remote branch、Final HEAD。
7. 最终再次确认本地 HEAD 与 origin/particle/main 一致。

12. 停止条件

如果实际 benchmark 无法用现有真实 fixture 对 16×16/32×32 做可信选择，或 v2.2 存在导致合法文件无法唯一解释的真实矛盾：

• 不得猜测 production Geometry。
• 完成可独立验证的代码/调查部分后停止。
• 在 docs/报告/ 生成接口/规范阻塞说明，明确缺什么数据或决定。
• 不得把支持两种 production Geometry 的“兼容 decoder”当成完成方案。

除此之外，应完成实现，不要因为普通工程细节反复向用户确认。