MapLibreParticleLab/docs/60_测试/STEP-097_V13修复后集中验证清单_v1.md

STEP-097 V13 修复后集中验证清单 v1

状态：STEP-097 整体 PARTIAL；A1 与 A2 的 Android/Core 检查已完成，B/C 未开始。 下方较早段落按当时事实保留；后续 RDC 结果以本文末尾带日期的更新为准。Metal host Core 测试不等于 iOS runtime，iOS runtime 按用户豁免记 USER_ACCEPTED_WITHOUT_IOS_RUNTIME_TEST。

通用 Core 与现有测试入口（RDC）

在本仓 Mac 当前 checkout，使用已配置的现有 build 目录；若目录不存在，先按当前构建规范配置。此处不自动运行：

cmake --build build-step088-opengl --target mbgl-test-runner -j3
build-step088-opengl/mbgl-test-runner --gtest_filter='RenderSegmentPlan.*:RenderSegmentDiagnostics.*:RetainedUnderlayCache.*:RetainedUnderlayRevision.*:ParticleFastPath.*'

新入口 RenderSegmentDiagnostics.OldCacheReleaseCannotChargeReplacementAtSameIndex 预期同 index 的旧 revision release 不计入新 topology，当前 revision release 计 1。RetainedUnderlayCache.UnsupportedAndResourceFailureFallBackSafely 为旧入口，用于资源失败后的基础状态；尚不能替代真实 layer render 异常注入。失败保留完整日志，回传首个错误和日志路径。

Android OpenGL（Particle-Android / RDC，NOT RUN）

./tools/particle_android_validation/build_validation_apk.sh

RDC 应使用同一 commit 生成 APK，再由后续授权的 Win11/模拟器操作按标准流水线安装。现有 Test Host 仅有 C-R 控制，尚缺同一 vector source/same tiles 的 R-R、R-C-R、C-R-R fixture，故该 APK 即使构建成功也不能关闭 01/03。需比较 cache ON/OFF 的首帧、重建、reuse、主目标与离屏目标像素；失败后 diagnostics 不得 Ready，下帧可恢复。记录 Renderer、ABI、SHA-256、截图与日志。不得引用 STEP-094 历史 43/43 作为本轮结果。

iOS Metal（Particle-iOS / RDC，NOT RUN）

cmake --build build-ios --target ios-sdk-static -- -quiet

同 commit 的 iOS simulator 与真机需开启 Metal API Validation，捕获 retained R-R/R-C-R 的 color/depth/stencil texture、load/clear/store，特别确认 simulator 的 Depth32Float_Stencil8 同时绑定 depth 和 stencil。故障注入覆盖附件创建失败、encoder 创建失败及 layer render 异常；预期不发布 Ready cache、后续能 fallback/retry。专用自动测试入口尚缺，不能因静态修改或 ios-sdk-static 成功就宣称 Metal runtime PASS。

后续 GPU 性能（粒子负责人协调，NOT RUN）

完成 A1/A2/B/C 代码与平台测试入口后，以相同设备、commit、Style、视口和场数据采样 cache ON/OFF、R×viewport×fieldKey 阶梯，记录 30/60 FPS、p50/p95/p99、GPU/CPU frame time、纹理创建/释放、峰值/长稳内存、方向/缩放/状态恢复。Metal capture 记录 waitUntilCompleted 的实际同步点及资源依赖。未经运行不填写数字；F06 multi-C 与 F08 精细失效另行设计。

Test Host 依赖（B 阶段后，NOT RUN）

目前默认 RN .10 与 Native .13 错配，阶段 B 未开始，不得运行安装并声称配对成功。B 修正 package/lock/SPM 后，RDC 再在 Test Host 目录执行：

npm ci
npm run typecheck

必须同时检查实际已安装 RN tgz、Android Gradle substitution、iOS SPM exactVersion 与 lockfile；不得以 node_modules 临时软链代替默认安装结果。本清单不含 Jest 命令。

2026-09-25 FZG1 A1 部分执行结果（覆盖上方 Codex 交付时的 NOT RUN 状态）

• 标准构建脚本已由 Mac RDC 实际执行；HEAD 91c2491b0，x86_64 OpenGL Debug APK BUILD SUCCESSFUL，SHA-256 8677197c5f83a22747cb51f0c261edffc5db4678fc25b3f366474f6ecb94dc99。冻结于 artifacts/maplibre-particle/step097-fzg1/。
• ADB 192.168.200.139:5555 对 FZG1-2 实际执行覆盖安装、20 组截图/UI XML、既有 STEP-093 topology、CACHE OFF/ON、相机、非法范围恢复与 mutation/fail-closed，日志见 docs/报告/STEP-097_A1_FZG1测试APK与实机验证报告_v1.md。
• 此处只是设备冒烟；A1 的同 tile stencil fixture、Metal 附件验证、真正 LayerGroup exception 注入与 OldCacheReleaseCannotChargeReplacementAtSameIndex GTest 仍 NOT RUN／缺专用入口；A2/B/C 和软件发布亦未执行。

2026-09-26 第 19 项原生 GTest 已执行

• RDC 使用当前源码 HEAD 0d13552bed84f427dd43cae9856391bd26622179 增量重编译 mbgl-test-runner：95/95 steps，exit 0；第 19 项 OldCacheReleaseCannotChargeReplacementAtSameIndex 1/1 PASS；RenderSegmentDiagnostics.* 5/5 PASS，两次退出码均为 0。原始日志和分析见 docs/报告/STEP-097_A1_第19项GTest运行验证报告_v1.md。
• 上方第 19 项“NOT RUN”是 2026-09-25 FZG1 冒烟时点的历史事实，现已由本条更新。01 同 tile、02 Metal、03 render exception 测试仍未闭合；A1 不得整体标 PASS。

2026-09-26 第 19 项 FZG1 设备辅助测试结果

• 经 RDC 在 FZG1-2 重新覆盖安装与 hash 复核，执行两轮 topology 轮换和资源诊断场景，20 个截图检查点；18 个有效配置均 valid=true/fallback=false，缺失 START fail-closed 后恢复。B/T 的粗粒度 create-release 差额 0/1，实时日志中无应用崩溃记录。详见 docs/报告/STEP-097_A1_第19项FZG1运行验证报告_v1.md 与 Mac 忽略目录 artifacts/maplibre-particle/step097-fzg1-gtest19-device/。
• 这次是 Android Runtime 冒烟，前述第 19 项精确计数归属 GTest 由 Mac 原生测试覆盖；01 同 source/tile stencil、02 Metal、03 绘制异常注入仍缺，A1 整体 PARTIAL，A2/B/C 未实施。

2026-09-26 A1 新入口执行清单（RDC，NOT RUN）

通用 Core（当前 OpenGL 构建目录）：

cmake --build build-step088-opengl --target mbgl-test-runner -j3
build-step088-opengl/mbgl-test-runner --gtest_filter='RenderOrchestratorError.*:RenderSegmentDiagnostics.OldCacheReleaseCannotChargeReplacementAtSameIndex'

预期异常 observer/failed 与 cache 不复用、重试后 Reuse；第 19 项保持 1/1 PASS。Metal GTest MetalRetainedAttachments.* 需由 RDC 使用可在 Mac 主机执行且配置 MLN_WITH_METAL=ON 的 mbgl-test-runner 构建目录执行；先检查所用目录的 CMakeCache、目标和 Metal device，再编译、执行并记录命令与日志。不能用 iOS 静态库构建替代主机 GTest。真机/simulator 的创建失败、encoder 失败与 API Validation 仍单独执行。

Android 同源 stencil：以本提交标准脚本构建 Validation APK，打开 Particle Core Layer Validation → STEP-093 → STEP-097 SAME SOURCE STENCIL；依次选择 RR、RCR、CRR。每种拓扑在 CACHE ON 首帧、稳定 reuse、REBUILD CURRENT 后，再切 CACHE OFF 与 ON；保存每个检查点截图、STEP097_STENCIL_PLAN/READY/DIAGNOSTICS 日志及 READ SNAPSHOT。预期 accepted=true、valid=true、fallback=false，多个 retained 段分别 build/reuse，四层同一 source 的轮廓与填充在缓存切换后无残影/漏裁剪。再以相机移动强制重建；记录主目标与离屏结果。此清单是待执行判据，不能据此宣称像素 PASS。真正 GPU 绘制异常及下一帧 full fallback/recovery 需 RDC 专项注入；GTest 状态机不能代替它。

2026-09-26 A1 实测结果（覆盖上方待运行记录）

• Android/FZG1：新 APK 源码 8c006ac83，SHA-256 48df19cf5a4c4250934efa2596423d3ad9571fe49a65b9b704a81cdb41f58671；同 source/tile RR/RCR/CRR、重建、缓存 OFF/ON 18/18 状态与像素采样检查通过，无本次捕获的 FATAL。
• Core：03 RenderOrchestratorError.* 2/2 PASS；19 OldCacheReleaseCannotChargeReplacementAtSameIndex 1/1 PASS，诊断组 5/5 PASS。
• Metal：编译通过，2/2 SKIP（无 Metal device）；用户豁免 iOS runtime，标 USER_ACCEPTED_WITHOUT_IOS_RUNTIME_TEST，不是 iOS 运行测试 PASS。详见 docs/报告/STEP-097_A1_Android专项验收报告_v1.md。后续 A2/B/C 未执行。

2026-09-26 A2 中途静态/Core 结果（不是 A2 关闭）

• OpenGL mbgl-test-runner 编译 exit 0；定向 16/16 PASS；两次 Shader generator 均 exit 0 且输出一致。Metal host 可编译并执行同一跨 Core GTest 16/16 PASS，未运行 iOS 设备。
• 上述结果仅覆盖现有原生测试入口。Codex A2 代码尚未审查/提交，Android 设备/APK 仍 NOT RUN，不能推进 B/C。证据与完整边界见 docs/报告/STEP-097_A2_阶段验证记录_v1.md。

2026-09-26 A2 最终验证结果（RDC 独立执行）

Core / Shader

• 原先因旧测试断言与既有语义不一致而失败的 58 项完整集合，在修复断言后 58/58 PASS。sameFieldGpuContent() 仍表达忽略 producer generation/dataVersion 的解码 payload 等价；sameFieldGpuEndpoint() 单独负责严格 GPU endpoint identity。
• 当前 broad filter 在 OpenGL 与 Metal host mbgl-test-runner 各 121/121 PASS。命令：

build-step088-opengl/mbgl-test-runner --gtest_filter='Particle*.*:Source.RasterArray*:Source.HostField*:Source.ParticleField*:Source.CanonicalField*'
build-step097-metal-host/mbgl-test-runner --gtest_filter='Particle*.*:Source.RasterArray*:Source.HostField*:Source.ParticleField*:Source.CanonicalField*'

• 三项 A2 Source 定向回归在 OpenGL 与 Metal host 各 3/3 PASS：mix-only 50 ticks 不重物化、真 endpoint 与 revision 变化触发物化、同步通知重入不双推进、clear fail-closed。
• node shaders/generate_shader_code.mjs 两次执行成功且输出幂等。Metal host 是 Mac 上 Core 测试，不是 iOS device runtime。

Android / FZG1-2

• RDC 使用 ./tools/particle_android_validation/build_validation_apk.sh 构建标准 OpenGL Debug x86_64 APK；61,753,803 bytes，SHA-256 27bf4a6cc191bd86c4d1c10398478d81c2999edd61fe7242e40e5188516b0ca5。FZG1-2 192.168.200.139:5555 安装成功，设备 APK SHA-256 相同。
• Test-App-only V4 Golden Wind T0/T1：load、seek 25/75、speed 2x/1x、PLAY 30 秒、PLAY 时 UI/TIME 可响应、PAUSE/stable pause、replay、CLEAR、reload、再次 PLAY/PAUSE；脚本 exit 0、17 PNG、24 steps、ANR=0。05_play_15s.png 可见粒子。30 秒场景闭环不是长期稳定性或性能测试。
• stable mix-only epoch 中 renderer 日志的 fieldUploadCount=6/resetCount=2 保持不变；explicit CLEAR/reload 后 upload 合法增至 10，reset 增至 4；reload 后 playback 稳定在该新计数。不能宣称跨 CLEAR/reload 零上传/零 reset。
• APK 工作树源 diff 与 mix-reuse-build-source.diff SHA-256 均为 18927a5f30a88f5c1c3a00e0017473dc33b04151c227e4baf52250dc4ad2e6a2，源码快照一致。原始 build/device/test 日志、steps 与截图位于 artifacts/maplibre-particle/step097-a2-final-validation/。

历史失败与范围

• 12:43 首次 ANR 为 synchronous Source notification 重入 forecast tick；forecastTickInProgress guard 与重入 GTest 已修复并覆盖。
• 后续无 ANR 但主线程仍高负载、PLAY/TIME 无响应的试跑由 debuggerd 定位到每 tick 重物化大场和深比较；mix-only immutable endpoint reuse 后通过本次 FZG1 闭环。旧失败日志和 debuggerd 保留，不从报告中删除。
• 本次不测 iOS runtime；标 USER_ACCEPTED_WITHOUT_IOS_RUNTIME_TEST。没有完成 GPU 性能基准、FPS/pXX 或长期运行测试。STEP-097 整体仍 PARTIAL，B/C 未开始；不包含 Jest、STEP-098、发布 .13。

2026-09-26 A2 源码独立 scoped commit 核验

• A2 的 26 个生产源码、shader、TestApp-only V4 Golden fixture 和定向测试文件已固定为 f49ffa68a17e0a505199bdbeccf07f8543f3a05f 并推送，origin/particle/main 回读一致；没有 stage 用户未跟踪 STEP-098。完整代码/设备证据仍见 docs/报告/STEP-097_A2_阶段验证记录_v3.md，不因 Git 提交改变原 APK 的 git_dirty=true 来源事实。STEP-097 整体 PARTIAL，B/C 待用户指令。

2026-09-26 B 阶段 RDC 实测与待闭合

• Mac Core 增量构建 PASS；B 的 JSON 严格校验、非法配置清除与恢复、数值溢出拒绝和合法 validity=0 四项 GTest：4/4 PASS。
• 扩大回归初次 132/134，旧 16-bit fixture 误用 4-byte UInt8 storage；修正为合法四样本 8-byte 小端之后重新编译，broad 134/134 PASS，没有放宽生产校验。
• Test Host package.json/package-lock.json 的 RN tarball 均为正式 13.4.1-particle.13，实包 SHA-256/SRI 一致。
• Android 要分别验证本仓新源码的 MapLibreMap destroy listener JUnit 与 RN module 对正式 .13 AAR 的 compile；前者不能替代后者。正式 .13 source commit 无 addOnDestroyListener，因此当前 bridge 存在 ABI 阻塞，不能标 Android consumer PASS。
• C、STEP-098、Jest 与正式发布不执行；完整证据见 docs/报告/STEP-097_B_独立验收与版本阻塞报告_v1.md。

2026-09-26 B 阶段 RDC 验证更新

• Mac 最新 GTest runner：定向 6/6、扩展 139/139 PASS，旧 broad 2 项失败经纠正测试 fixture 后消除；完整日志 artifacts/maplibre-particle/step097-b-rdc/validation-*.log。
• Android Native OpenGL Debug：MapLibreMapDestroyListenerTest 2/2 PASS；compileOpenglDebugJavaWithJavac exit 0；owner Kotlin 独立 JVM JUnit 4/4 PASS（源码 SHA 与当前 B10 一致）。隔离单测不能替代 React Native 模块与发布 AAR 精确配对编译。
• B10 当前默认 RN Gradle 对已发布 .13 Native AAR 依赖新缺失符号 addOnDestroyListener；RN consumer 校验标 BLOCKED_NATIVE_AAR_COMPATIBILITY，禁止记录 PASS 或覆盖 .13。Linux 独立 Gradle 状态另记，C 与 STEP-098 均不得越过此门槛。