# 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 精确命令：

```bash
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 完成。