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

## 1. 执行结论

**PASS：Codex 实现 + RDC 独立 Mac Native 验证闭环完成。**

本报告是在 v1 PARTIAL 基础上的验证收尾版。RDC 已完成 OpenGL test-runner 编译、定向 Native tests、Metal-only iOS 静态 SDK 编译，并修复两处真实验证问题后重新通过。Android Gradle/APK/ADB/实体机与 Metal GPU frame capture 未执行，均明确保留为未执行项。

## 2. Git 基线与提交

- 仓库：`/Users/tei/dev/MapLibreParticleLab`
- branch：`particle/main`
- Starting HEAD：`b29e564944197072a0effaec36ca95c48fe0649b`
- Codex implementation：`a9eaec6b65cc26aa70e03002bdc1326c46cad245`
- Codex v1 docs：`b89c8c8cb4d941abdcd704b278284e209ba7399b`
- RDC validation fix：`4908244d2`，message：`fix: close STEP-092 native validation issues`
- 文档收尾提交在本报告写入后产生，最终 HEAD / remote HEAD 由收尾回读确认。

## 3. Codex 实现范围

C++ Renderer：
- explicit Continuous Range config / resolution
- 0/1/2 retained range cache
- Bottom / Continuous / Top render slicing
- Fast Path gate
- diagnostics 与 invalidation

跨端 API：
- C++ Map API
- Android Java/JNI
- iOS ObjC++
- RN TypeScript / Android / iOS bridge
核心语义：
- `[startLayerId,endLayerId]` 为闭区间。
- single-layer Continuous 合法。
- hidden endpoint 仍决定 topology。
- Style Layer 顺序是唯一 Z-order。
- explicit valid 与 legacy boundary 排他。
- explicit invalid fail closed。
- Opaque reverse / Translucent forward 与 global ordinal 保持。

## 4. RDC 第一次 OpenGL 编译

命令：
`cmake --build build-step088-opengl --target mbgl-test-runner -j3`

结果：FAIL。

首个真实错误：
- `renderer_impl.cpp:873-874`
- `RenderItem` 无 `index` 成员。

原因：
- `layerRenderItems` 实际类型是 `std::set<LayerRenderItem>`；
- 代码把当前元素绑定为 `const RenderItem&` 后又读取派生类 `index`。

## 5. RDC 第二次 OpenGL 编译

第一次局部修复改为 `LayerRenderItem&` 后继续编译，新的真实错误为：
- `LayerRenderItem::hasRenderPass` private
- `LayerRenderItem::render` private

最终修复：
- `LayerRenderItem& layerItem` 专门读取 `index`；
- 再绑定 `const RenderItem& item = layerItem` 调用公开虚接口。

第三轮 OpenGL build：
- exit code：0
- target：`mbgl-test-runner`
- 结果：PASS。
## 6. Native directed tests

过滤器：
`ContinuousLayerRange.*:RetainedDynamicBoundary.*:RetainedLayerGroupRange.*:RetainedUnderlayCache.*:RetainedUnderlayRevision.*:ParticleFastPath.*`

第一轮：
- 29 tests / 6 suites
- PASS 28
- FAIL 1

唯一失败：
`RetainedUnderlayCache.RuntimeControlDisablesAndReenablesMapScopedCache`

实际值：
- disabled.invalidation = 3
- expected = 2

根因：
- baseline 中 `setEnabled(false)` 已记录一次 aggregate `runtime-disabled` invalidation；
- STEP-092 新增 range cache 同步路径再次调用 aggregate `invalidate()`；
- 因而同一 disable 事件被重复计入 aggregate diagnostics。

RDC 修复：
- disable 时不再重复调用 aggregate `recordInvalidation`；
- 保持 legacy aggregate 计数语义；
- 仍为实际 Bottom/Top cache 记录独立 `recordRangeInvalidation`。

第二轮：
- 29/29 PASS
- exit code：0
- 全部 6 suites PASS。
## 7. Metal / iOS 验证

后端真实性：
- `MLN_WITH_METAL=ON`
- `MLN_WITH_OPENGL=OFF`
- Xcode project 定义 `MLN_RENDER_BACKEND_METAL=1`

命令：
`cmake --build build-ios --target ios-sdk-static -- -quiet`

结果：
- exit code：0
- PASS
- 仅有既有 EAGL deprecated、bundle identifier / script phase warning。

因此本轮不是“iOS target 名称推断”，而是实际 Metal-only 配置下完成原生编译与链接。

## 8. GPU resource lifecycle / composite 核验

RDC 审计的实际代码路径：
- RendererImpl 常驻 Bottom/Top cache holder，但 GPU 资源不在构造时创建。
- `prepareResources()` 只在对应 decision 为 Build/Reuse 时进入。
- Range 不存在时 key/decision 为 Disabled，不执行 `prepareResources()`。
- `createOffscreenTexture(..., UnsignedByte, true, true)` 仅在 texture 不存在或 viewport 变化时执行。
- 同 viewport 复用已有 texture。
- `compositeLayerGroup` 存在时不重建 compositor。
- build render target clear color：透明 `0,0,0,0`。
- composite：`gfx::ColorMode::alphaBlended()`。
- `alphaBlended()` 使用 `src=One`、`dst=OneMinusSrcAlpha`，符合 premultiplied-alpha。
- OpenGL 与 Metal Composite Shader 均直接采样 retained RGBA texture。
- Renderer final 顺序：Bottom composite → Continuous render → Top composite。
- Native test 已验证四种 topology、0/1/2 cache decision、reuse/invalidation 与 absent cache fast gate。

这些结果共同证明当前源码中不存在固定分配两个 retained GPU target，也不存在 stable frame 每帧重建同尺寸 texture/compositor 的路径。

## 9. RDC 实际修改

1. `src/mbgl/renderer/renderer_impl.cpp`
   - 修复 legacy `LayerRenderItem` index 访问与基类虚接口调用。

2. `src/mbgl/renderer/retained_underlay_cache.cpp`
   - 修复 runtime disable aggregate invalidation 重复计数；
   - 保留 Bottom/Top range invalidation diagnostics。

RDC 修复提交：
- `4908244d2`
- `fix: close STEP-092 native validation issues`
- push：SUCCESS。

## 10. 未执行项目

- Android Gradle / AAR / APK：未执行。
- ADB / 安装 / Android 实体机视觉：未执行。
- iOS 实机 GPU runtime：未执行。
- Metal frame capture / GPU resource counter：未执行。
- Jest：未新增、未执行。

当前仓库未提供一个可直接运行的 STEP-092 Metal GPU runtime test target，因此未将 Metal compile PASS 描述成 frame-capture PASS。

## 11. 最终验收判断

STEP-092 的规定架构、四种 Range、0/1/2 retained cache、global layerIndex、Opaque/Translucent、Fast Path、diagnostics、RN/Android/iOS API、Native directed tests、OpenGL Native build、Metal-only iOS build、资源生命周期路径、文档和 Git 闭环均已完成。

结论：**CLOSED / PASS（Mac Native 范围）**。