MapLibreParticleLab/docs/报告/STEP-092_ContinuousRange可退化分段RetainedCache_Codex完成报告_v1.md

STEP-092 Continuous Range 可退化分段 Retained Cache Codex 完成报告 v1

1. 执行结论

PARTIAL：实现完成，等待 RDC 独立编译、Native directed test、OpenGL/Metal 验证。

未把静态审计写成编译通过，也未把 Android 项写成已执行；因此当前不满足任务的最终 PASS Gate。

2. Git 基线

• 机器：Mac-mini-tei.lan，Darwin x86_64。
• 仓库：/Users/tei/dev/MapLibreParticleLab。
• branch：particle/main。
• Starting HEAD：b29e564944197072a0effaec36ca95c48fe0649b。
• 起始 origin/particle/main：b29e564944197072a0effaec36ca95c48fe0649b。
• 起始 dirty：仅用户提供的 untracked STEP-092 任务书；已保留并纳入本任务文档范围。
• Implementation commit：a9eaec6b65cc26aa70e03002bdc1326c46cad245。
• Implementation message：feat: add continuous retained render ranges。
• Implementation push：SUCCESS，b29e56494..a9eaec6b6 HEAD -> particle/main。
• 文档提交无法在自身内容中自指其最终 SHA；closeout SHA、最终本地/远端 HEAD 与最终 status 由提交后回读写入最终交付响应。

3. 修改文件

C++ Renderer / Map

• include/mbgl/map/map.hpp
• include/mbgl/renderer/retained_underlay.hpp
• src/mbgl/map/map.cpp
• src/mbgl/renderer/continuous_layer_range.hpp（新增）
• src/mbgl/renderer/render_orchestrator.cpp/.hpp
• src/mbgl/renderer/renderer_impl.cpp/.hpp
• src/mbgl/renderer/retained_underlay_cache.cpp/.hpp
• src/mbgl/renderer/retained_underlay_runtime_state.hpp

Android API / bridge

• platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/MapLibreMap.java
• platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMap.java
• platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMapView.java
• platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/RetainedUnderlayDiagnostics.java
• platform/android/MapLibreAndroid/src/cpp/native_map_view.cpp/.hpp

iOS API / bridge

• platform/ios/src/MLNMapView.h/.mm
• packages/maplibre-particle-rn/ios/WeatherRuntimeBridge.mm

RN API

• packages/maplibre-particle-rn/src/NativeWeatherRuntimeBridge.ts
• packages/maplibre-particle-rn/src/RendererRuntime.ts
• packages/maplibre-particle-rn/src/types.ts
• packages/maplibre-particle-rn/android/src/main/java/org/navsea/maplibre/particle/weather/WeatherRuntimeBridgeModule.kt

Tests / docs

• test/renderer/retained_underlay_cache.test.cpp
• docs/40_任务/STEP-092_ContinuousRange可退化分段RetainedCache_Codex任务_v1.md
• docs/50_Step记录/STEP-092_ContinuousRange可退化分段RetainedCache_v1.md
• 本报告
• 粒子开发记录.md

4. Range config 所有者与解析

• map-scoped owner：Map::Impl::retainedUnderlayState。
• thread safety：atomic control/counters + mutex-protected ID/config/resolution。
• revision：每次实际 ID pair 变化单调递增；重复相同配置不前进。
• ID→index：RenderOrchestrator::createRenderTree() 在完整 orderedLayers 上解析，visibility 不参与。
• explicit valid 时只使用 [startIndex, endIndex + 1)；不读取 legacy boundary。
• explicit invalid 时 index 置 -1、资源/prepared gate 失效并 full fallback；不按 Particle/Weather 类型纠正。

5. 1/2/3 Render Range 与 0/1/2 cache

• single-layer Continuous 正式支持。
• Bottom+Continuous+Top / Bottom+Continuous / Continuous+Top / Continuous-only 全部由同一 plan 表达。
• 两个 cache holder 分别代表 Bottom/Top capability；只有 range present 才建立 key 并 lazy 创建 RGBA texture/render target/compositor。
• empty drawable content 不会把 Style 中实际存在的 Bottom/Top topology 偷偷消掉；可构建透明 retained texture。

6. Renderer、Z-order 与 Top 正确性

• Bottom build/reuse/composite → Continuous render → Top build/reuse/composite。
• Opaque reverse、Translucent forward 保持；original ordinal、currentLayer、depthRangeSize 按全 Style 计算。
• Top 使用透明 clear、RGBA offscreen、direct sample shader 与 alpha-blended premultiplied composite，可覆盖 Continuous Particle。
• 未增加 LandMask RT、业务 Layer ID、Anchor/Marker 或第二套 metadata Z-order。

7. Invalidation / legacy / Fast Path

• STEP-089 content/topology/static revision 继续作为 conservative invalidation 基础；range config/end index/Top topology 已纳入。
• 未配置 explicit range：保持 legacy retained-underlay。
• explicit valid：legacy startsRetainedDynamicRange() 只可用于 fast-safety 类型证明，不参与 topology/boundary。
• fast gate 对不存在 cache 不要求 valid；实际存在 Bottom/Top 都必须 valid/buildRevision 匹配。
• unknown Continuous layer 不能证明 particle-only 安全时 full CPU fallback；正常 full range render/cache 不受影响。

8. Diagnostics

已增加并跨 C++/Android/iOS/RN 暴露：

• rangeConfigured, rangeValid
• startLayerId, endLayerId, startIndex, endIndex
• bottomPresent, bottomBuild, bottomReuse, bottomInvalidation
• topPresent, topBuild, topReuse, topInvalidation
• 保留 aggregate fallback, lastReason 与原有 enabled/build/reuse/invalidation。

Continuous-only 的 Bottom/Top present 均为 false，仍可为 rangeValid=true。

9. Native tests

测试源码新增覆盖：

• start == end、start < end、start > end
• start/end missing
• hidden endpoint ID 仍参与完整 ordered list
• reorder、endpoint 删除后重新解析
• 四种 topology 与 0/1/2 cache decision
• Bottom/Top 不存在不造成 fast cache miss
• config empty-ID/revision/same-ID
• explicit valid/invalid 均不混用 legacy boundary

实际 test runner 尚未由 Codex 执行，等待 RDC。

10. OpenGL / Metal / Android

• OpenGL：源码实现完成；未执行 build/runtime，等待 RDC。
• Metal：共用 range/cache topology 与既有 Metal compositor；源码实现完成；未执行 ios-sdk-static，等待 RDC。
• Native directed tests：未执行，等待 RDC。
• Android 项：未执行 Android Gradle、AAR/APK、ADB、安装、设备视觉或生命周期验证。
• Jest：按任务要求未新增、未执行。

11. 静态检查与验证命令

Codex 已执行 git diff --check；最终提交前再次执行并回读。

RDC 精确命令：

cmake --build build-step088-opengl --target mbgl-test-runner -j3
build-step088-opengl/mbgl-test-runner \
  --gtest_filter='ContinuousLayerRange.*:RetainedDynamicBoundary.*:RetainedLayerGroupRange.*:RetainedUnderlayCache.*:RetainedUnderlayRevision.*:ParticleFastPath.*'
cmake --build build-ios --target ios-sdk-static -- -quiet
git diff --check

12. Known limitations / 未完成

• 尚无 RDC 编译结果，桥接/codegen/ObjC++/C++ 编译结论不得写 PASS。
• 尚无 OpenGL/Metal frame capture 或资源计数运行证据。
• 尚无 Android lifecycle/style mutation/视觉验收。
• 本任务只支持一个 explicit Continuous Range；无 clear API、多个 Range 或 N Segment Planner。

13. Git 收尾

• scoped staging：只纳入本任务上列源码、测试与文档。
• 禁止项：未使用 git add -A、git add .、reset、clean 或 force push。
• Implementation commit SHA/message：a9eaec6b65cc26aa70e03002bdc1326c46cad245 / feat: add continuous retained render ranges。
• Implementation push result：SUCCESS。
• Remote branch：origin/particle/main。
• Final HEAD / origin/particle/main / git status --short：待提交与 push 后外部回读；在两者一致前不声明 Git 完成。