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

STEP-074 — QBIN2 V4 Encoded Ingress 与 Decoder v3

状态：完成

日期：2026-09-13

目标

在不扩展 STEP-074 生产范围的前提下，收口 Decoder 入口错误、Little Endian fail-closed 与 32 MiB raw decoded-data 上限的最终测试覆盖。

基线

• 开始 HEAD：56b8dab90f914438e6fcaec6278146c96c8df638。
• 开始前已有 STEP-062 文档修改及历史 untracked 文件；均未清理、覆盖、暂存或提交。

必做项

• 空 span、1 byte、111 bytes 都经 production QbinV2Decoder::decode 返回 InputTooSmall。
• 112-byte 非 QBV2 输入返回 BadMagic；空 fieldID、零 generation 返回 InvalidRuntimeMetadata。
• 明确验证 dataVersion=0 的合法 frame 仍 Accepted。
• Header width 写成 big-endian 00 00 00 02 并重算 CRC 后以 LimitExceeded 结构化拒绝。
• Descriptor count 写成 mixed-endian 00 00 00 04 并重算 CRC 后以 InvalidDescriptor 结构化拒绝。
• raw sum 为 31,712,633 bytes、canonical payload 为 31,712,648 bytes 的 1447×1449 FRAME Accepted；15 bytes padding 未计入 32 MiB decoded limit。

允许修改

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

禁止修改

• Host、网络、JNI、Android/RN、Binding/Projection、Renderer、Store submission 与 production Decoder。

构建与测试

• cmake --build build-linux-opengl --target mbgl-test-runner -j3：PASS（经输出限流器，实际重编译/重链）。
• mbgl-test-runner --gtest_list_tests：PASS，Decoder/Ingress suite 已注册。
• ParticleQbinV2Decoder.*:ParticleEncodedFieldIngress.*：24/24 PASS。
• ParticleFieldRuntime.*:ParticleFieldProfileValidator.*：STEP-073 11/11 PASS。
• Source.ParticleFieldDataAdapter*:Source.RasterArrayTimeline*:Source.HostField*：既有 V3 11/11 PASS。
• git diff --check：PASS。

当前结果

仅补 6 个 production decode 覆盖测试，未发现生产 Decoder 缺陷，故未修改生产实现。STEP-074 由 v2 的 18 tests 扩至实际 24 tests，全部通过。

阻塞与下一步

无范围内阻塞。按任务要求完成 scoped commit 与 origin/particle/main push 尝试后停止，不进入 STEP-075。