5.6 KiB
STEP-093 Continuous Range 运行态综合验收 Codex 完成报告 v1
1. 交付结论
IMPLEMENTED / WAITING_RUNTIME_VALIDATION
Codex 已完成 STEP-093 所需的 Android 可重复运行态测试入口、最小 diagnostics 可观察性、Fast Path fail-closed 原因、跨平台字段透传与定向测试源码，并完成静态一致性审查。Android/iOS runtime 均未实际执行，所以没有任何运行态场景被标记为 PASS。
2. Git 信息
- Repository：
/Users/tei/dev/MapLibreParticleLab - Branch：
particle/main - Starting HEAD / starting remote：
8a5d88008c142e2a80e0ff602d228e0e67de2d83 - Implementation commit：
b3ec8edc87ece404b5f7b3706f5acf2a70de6862（feat: add STEP-093 runtime validation tooling） - Documentation closeout：本报告所在 scoped commit，在报告写入后生成；准确 hash、push 和最终 remote 回读以最终交付消息为准。
3. 修改文件
Core/Renderer：
include/mbgl/renderer/retained_underlay.hppsrc/mbgl/renderer/particle_fast_path.hppsrc/mbgl/renderer/renderer_impl.cpp/.hppsrc/mbgl/renderer/retained_underlay_cache.cpp/.hppsrc/mbgl/renderer/retained_underlay_runtime_state.hpptest/renderer/retained_underlay_cache.test.cpp
Android：
platform/android/MapLibreAndroid/src/cpp/native_map_view.cppplatform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/RetainedUnderlayDiagnostics.java- Test App Manifest、validation Activity 与 layout。
iOS / RN：
platform/ios/src/MLNMapView.h/.mm- RN TypeScript types/spec、Android/iOS bridge、RN Test Host diagnostics display。
文档：
- STEP-093 任务书、Step 记录、Codex 完成报告；
粒子开发记录.md追加记录。
4. 测试入口
Android：启动 ParticleCoreLayerValidationActivity，点击底部 STEP 093。菜单提供 A/B/C/D 四种 topology、E single-layer、mutation/cross-range、endpoint/visibility、invalid range、camera 与 Fast Path fail-closed；屏幕显示完整 pull diagnostics。
iOS：正式 diagnostics API 与 RN bridge 字段已补齐，但本轮没有建立/运行 iOS 专用 STEP-093 validation UI。状态为 WAITING_IOS_RUNTIME_VALIDATION。
完整 RDC 命令、逐项操作、判定标准和验收矩阵见同版本 Step 记录。
5. Diagnostics
新增并端到端暴露：
- Range configured/valid/IDs/index/continuous bounds/fallback/last reason；
- Bottom/Top present/cache state/build/reuse/invalidation/last reason；
- Bottom/Top texture create/composite create/resource release；
- Fast Path eligible/active/fallback reason/hit/miss/full CPU frame；
- unsupported Continuous layer 的
unsupported-continuous-layer原因。
所有数据复用 STEP-092 map-scoped runtime state；没有增加 topology metadata 或 Z-order 真相源。counter 只代表事件累计，不代表 GPU memory bytes。
6. 静态审查与实际测试结果
实际执行并通过：
- Native → Android/iOS → RN diagnostics 字段与 Android 39 项 ABI 索引静态核对；
- 场景 layer 顺序、endpoint 与菜单接线静态审查；
xmllint --noout检查 Test App Manifest/layout：PASS；git diff --check：PASS。
明确未执行：
- CMake/Ninja/Xcode/Gradle 编译：NOT RUN；
- Native directed tests：NOT RUN；
- TypeScript/codegen/Android JNI 实际编译：NOT RUN；
- APK build/install、ADB、模拟器/真机：NOT RUN；
- Android runtime/视觉/长时间运行：
WAITING_ANDROID_RUNTIME_VALIDATION； - iOS/Metal runtime/视觉/长时间运行：
WAITING_IOS_RUNTIME_VALIDATION； - Jest：未新增、未执行。
STEP-092 的 OpenGL/Metal build 与 29/29 tests 是起始历史证据，不是本轮新增代码的验证结果。
7. Android runtime 结果
WAITING_ANDROID_RUNTIME_VALIDATION
没有执行 Android Gradle、APK、ADB、安装、启动或画面操作。A–E、Z-order、stable reuse、invalidation、mutation、endpoint、visibility、invalid、Fast Path 与 alpha 全部为 NOT RUN。
8. iOS/Metal runtime 结果
WAITING_IOS_RUNTIME_VALIDATION
没有执行 iOS build/install/simulator/device/Metal runtime。Android 后续即使 PASS，也不能自动推导 iOS PASS；Metal Native build 历史结果也不能替代 runtime rendering。
9. 架构边界
本轮没有：
- 修改
[startLayerId,endLayerId]闭区间或内部半开区间数学； - 增加第二套 Bottom/Continuous/Top metadata；
- 增加 anchor/marker、特殊 layer type、多 range 或频率分类；
- 在 Renderer 硬编码业务 Layer ID；
- 重构 RenderGraph/PBF/Particle 算法；
- 把 visibility 变成 topology 规则；
- 为 Fast Path 移动未知 Continuous layer。
Style layer 顺序仍是唯一 Z-order 真相；App 只提供 endpoint ID，Native 解析 index。
10. 风险与已知限制
- 尚无任何运行态证据，不能确认真实 GPU 资源、画面合成或平台差异。
- Android diagnostics 每秒 pull 一次但不逐秒 log；证据需手动
READ DIAGNOSTICS、截图或外部采样。 - counter 在同一 Map 生命周期累计，RDC 应对比增量。
- iOS 缺专用 STEP-093 validation 页面，需后续补齐实际可操作入口。
- 本轮新增定向测试源码尚未编译/运行，任何预期 test 数都不能写成 PASS。
11. 最终状态
- 实现：完成；
- 静态一致性审查：完成；
- Android runtime：
WAITING_ANDROID_RUNTIME_VALIDATION； - iOS/Metal runtime：
WAITING_IOS_RUNTIME_VALIDATION； - 综合：IMPLEMENTED / WAITING_RUNTIME_VALIDATION。
Git push、HEAD == origin/particle/main 与 clean worktree 由本报告之后的 scoped 文档提交和最终回读确认；这些 Git 结果不改变 runtime 尚未执行的事实。