MapLibreParticleLab/docs/50_Step记录/STEP-074_QBIN2_V4_EncodedIngress与Decoder_v4.md

STEP-074 — QBIN2 V4 Encoded Ingress 与 Decoder v4

状态：完成

日期：2026-09-13

目标

仅修正 v3 AcceptsRawLimitWithCanonicalPaddingExcluded 的边界 fixture，使它严格证明 decoded raw 数据不超过 32 MiB、canonical packed payload 超过 32 MiB、整个 QBIN 文件不超过 64 MiB 时 production Decoder 仍接受。

基线

• 开始 HEAD：f4a495ff38b77f586f97853493dda02ab067b26d。
• 开始前已有 STEP-062 文档修改及历史 untracked/build 文件；均未清理、覆盖、暂存或纳入本 Step。

必做项

• AcceptsRawLimitWithCanonicalPaddingExcluded 改为 1101×1890（2,080,890 cells）、17 plane：1 个 single shared validity BITSET 与 16 个 UINT8 numeric plane；descriptor 依 semantic 3、4–19 canonical 排序。
• 测试直接计算并断言 rawSum=33,554,352 <= 33,554,432、payloadLength=33,554,448 > 33,554,432、payloadLength > rawSum、totalQbinBytes=33,555,104 <= 67,108,864。
• fixture 经 production QbinV2Decoder::decode(...) 返回 Accepted。
• cells、planes、canonical packing、single shared validity、descriptor 与 64 MiB 文件限制均在构造及断言内满足。

允许修改

• test/particle/qbin_v2_decoder.test.cpp。
• 本 Step 记录、完成报告与粒子开发记录。

禁止修改

• Production Decoder、Host、网络、JNI、RN、Binding/Projection、Renderer、Store submission、Android/iOS 平台路径。

构建测试

• cmake --build build-linux-opengl --target mbgl-test-runner -j3：PASS（输出节流器；实际目标已重新检查并确认最新）。
• ParticleQbinV2Decoder.*:ParticleEncodedFieldIngress.*：实际 Running 24，24/24 PASS（XML：Decoder 22、Ingress 2）。
• ParticleFieldRuntime.*:ParticleFieldProfileValidator.*：实际 Running 11，11/11 PASS。
• Source.ParticleFieldDataAdapter*:Source.RasterArrayTimeline*:Source.HostField*：实际 Running 11，11/11 PASS。
• git diff --check：PASS。

当前结果

旧 fixture 的 payload 仍低于 32 MiB，不能捕获把 packed payload 误当 decoded raw limit 的实现错误。新 fixture 以 16 个每个 6-byte canonical padding 的 numeric plane 将 payload 推至 limit 以上 16 bytes，同时 raw sum 比 limit 小 80 bytes；production Decoder 接受，未发现生产缺陷，故未修改 production 代码。

阻塞与下一步

无范围内阻塞。未执行 Android Gradle/APK/ADB/Jest；按任务要求停止，不进入下一 Step。