docs: close STEP-094 render segment validation

2026-09-25 13:56:50 +09:00
parent 016fd1fff6
commit 9d1f66c169
4 changed files with 341 additions and 0 deletions
--- a/docs/30_设计/STEP-094_通用RenderSegment模型与Style分类Diagnostics设计_v1.md
+++ b/docs/30_设计/STEP-094_通用RenderSegment模型与Style分类Diagnostics设计_v1.md
@@ -0,0 +1,141 @@
+# STEP-094 通用 Render Segment 模型与 Style 分类 Diagnostics 设计 v1
+
+## 1. 目标与边界
+
+Renderer 只接收 Style 顺序和一组连续 Segment 定义。每个 Segment 的执行策略只有 `RETAINED` 或 `CONTINUOUS`；不引入 LOW/MEDIUM/HIGH，不识别 AIS、Route、Weather 等业务语义，不改变 Style Z-order，也不增加 Anchor/Marker Layer。
+
+V12 的 Bottom Retained / Continuous / Top Retained 是本模型的兼容特例。新实现只有一套 resolved topology；旧 `setContinuousLayerRange()` 先转换为通用 Segment Plan，再进入同一 Renderer 路径。
+
+## 2. 公共数据模型
+
+Core 公共类型位于 `include/mbgl/renderer/render_segment.hpp`：
+
+```text
+RenderSegmentPlan
+  schemaVersion = 1
+  segments[1..N]
+    strategy = RETAINED | CONTINUOUS
+    startLayerId = 第 1 段省略；后续段必填
+```
+
+RN 公共类型位于 `packages/maplibre-particle-rn/src/types.ts`，`RendererRuntime.setRenderSegmentPlan(reactTag, plan)` 接收 typed object。TurboModule、Android/iOS package bridge 与 platform API 内部使用 schema-versioned JSON，JS 调用方不接触 raw JSON。
+
+## 3. Config / Resolve 生命周期
+
+1. map-scoped runtime state 保存 active config、`configSource` 和单调递增 `configRevision`。
+2. `setRenderSegmentPlan()` 将 active source 切到 `explicit-render-segment-plan`。
+3. `setContinuousLayerRange()` 将 active source 切到 `continuous-range-compat`，不会再并存第二套 Renderer topology。
+4. 没有显式配置时，既有 `startsRetainedDynamicRange()` 仅通过 `unconfigured/legacy` adapter 生成兼容 plan。
+5. RenderOrchestrator 只在 config、Style ready、Layer add/remove/change 时重新解析 boundary ID 和 diagnostics metadata；Particle 高频 Fast Path 不扫描/复制 Style 字符串，也不 stringify JSON。
+6. `topologyRevision` 只在 resolved strategy/begin/end 签名变化时递增。Visibility 变化更新 `visible`，不改变 topology revision。
+
+显式 plan 合法条件：definitions 非空；第 0 段无 boundary；第 1..N-1 段 boundary 存在、非空且 index 严格递增；每段非空；完整覆盖 `[0, layerCount)`。失败时 segments 为空、`valid=false`、释放旧 cache 并走 full renderer；ordered `styleLayers` 仍可读取。
+
+## 4. V12 Compatibility Mapping
+
+旧闭区间 `[startLayerId,endLayerId]` 解析为：
+
+```text
+startIndex > 0                -> RETAINED   [0,startIndex)
+                               CONTINUOUS [startIndex,endIndex+1)
+endIndex+1 < styleLayerCount  -> RETAINED   [endIndex+1,layerCount)
+```
+
+因此自然退化为 R-C-R、R-C、C-R 或 C。`configSource=continuous-range-compat`。旧 `getRetainedUnderlayDiagnostics()` 继续保留摘要；多段真实事实以新 API 为准。
+
+## 5. Renderer 执行与 Cache Ownership
+
+Resolved Segment 保留 Style 全局 `layerIndex` 和 LayerGroup 原 ordinal。Retained 构建继续使用 opaque reverse / translucent forward；Continuous 直接绘制同一全局 index 范围。`parameters.currentLayer` 和 `depthRangeSize` 不按 Segment 重新编号。
+
+Renderer 按 resolved topology 动态创建 `retainedSegmentCaches[segmentIndex]`：
+
+- RETAINED：独立 `RetainedUnderlayCache`、key、revision、texture、compositor 和 counters；
+- CONTINUOUS：对应 slot 为空，不创建 retained texture/FBO/compositor；
+- topology 改变：旧 cache 在 Renderer 线程释放，不能迁移或 composite stale resource；
+- GPU resource 仍由 `prepareResources()` lazy 创建，稳定 viewport 复用。
+
+主 buffer 按 Segment 顺序执行：Retained composite 或 Continuous direct render。相邻同策略不会合并。
+
+## 6. Invalidation
+
+Layer immutable Impl identity 与全局 Style index 组成 retained Segment content fingerprint。Layer property/visibility 在某 retained Segment 内变化时，只推进该 Segment 的 content revision；其他 retained Segment 可继续 reuse。
+
+以下仍保守 invalidate 全部 retained Segment：camera/viewport/pixel ratio、source/tile、image/sprite/glyph、placement/transition、context reset、debug/3D、style reload、resource/compositor failure。原因是当前 Core 没有足够稳定的通用 source-to-render-segment dependency graph；本 Step 不扩建该图。
+
+## 7. Particle Fast Path
+
+恰好一个 Continuous Segment、其内容满足既有 Particle-only 支持条件、所有实际 Retained cache 有效时，沿用 V12 Fast Path。缺少某个不存在的 retained cache 不构成 miss。
+
+多个 Continuous Segment 暂不做高级 Fast Path：gate 以 `unsupported-continuous-layer` fail closed，进入正常 full CPU frame；Segment topology、cache 与 Z-order 不变。
+
+## 8. Android / iOS / RN API
+
+```text
+RN RendererRuntime
+  setRenderSegmentPlan(reactTag, typedPlan)
+  getRenderSegmentDiagnostics(reactTag)
+        ↓ schemaVersion=1 JSON transport
+WeatherRuntimeBridge（既有唯一 bridge）
+        ↓
+Android MapLibreMap / iOS MLNMapView
+        ↓
+mbgl::Map typed RenderSegmentPlan / RenderSegmentDiagnostics
+        ↓
+RetainedUnderlayRuntimeState + RenderOrchestrator + RendererImpl
+```
+
+Android platform 内部 API 为 `setRenderSegmentPlan(String)` / `getRenderSegmentDiagnostics()`；iOS 为 `setRenderSegmentPlanJSON:` / `renderSegmentDiagnosticsJSON`。Core API 保持 typed。JSON/schema/strategy 非法时返回 REJECTED，同时把 active topology 置 invalid，避免继续复用旧 cache。
+
+## 9. Diagnostics Schema
+
+Snapshot 为 pull-based。顶层包含 enabled/configured/valid/configSource/configRevision/topologyRevision/counts/coverage/fallback/reason/Fast Path counters；`styleLayers[]` 始终按 Style 顺序；`segments[]` 包含 begin/end、实际 Layer 成员。Retained 的 `cache` 为 object；Continuous 的 `cache=null`，不会伪装为 disabled retained cache。
+
+完整示例：
+
+```json
+{
+  "schemaVersion": 1,
+  "enabled": true,
+  "configured": true,
+  "valid": true,
+  "configSource": "explicit-render-segment-plan",
+  "configRevision": 7,
+  "topologyRevision": 4,
+  "styleLayerCount": 6,
+  "segmentCount": 4,
+  "retainedSegmentCount": 3,
+  "continuousSegmentCount": 1,
+  "coverageComplete": true,
+  "fallback": false,
+  "lastReason": "none",
+  "fastPathEligible": true,
+  "fastPathActive": true,
+  "fastPathFallbackReason": "none",
+  "fastPathHit": 120,
+  "fastPathMiss": 3,
+  "fullCpuFrame": 4,
+  "styleLayers": [
+    {"layerIndex":0,"layerId":"background","layerType":"background","visible":true,"sourceId":null,"sourceLayer":null},
+    {"layerIndex":1,"layerId":"water","layerType":"fill","visible":true,"sourceId":"chart","sourceLayer":"water"},
+    {"layerIndex":2,"layerId":"rn-weather-color","layerType":"weather-color","visible":true,"sourceId":"rn-weather-fields","sourceLayer":null},
+    {"layerIndex":3,"layerId":"rn-weather-particles","layerType":"raster-particle","visible":true,"sourceId":"rn-weather-fields","sourceLayer":null},
+    {"layerIndex":4,"layerId":"land-area","layerType":"fill","visible":true,"sourceId":"chart","sourceLayer":"land"},
+    {"layerIndex":5,"layerId":"ais-layer","layerType":"symbol","visible":true,"sourceId":"ais","sourceLayer":null}
+  ],
+  "segments": [
+    {"segmentIndex":0,"strategy":"RETAINED","configuredStartLayerId":null,"beginIndex":0,"endExclusive":2,"resolvedStartLayerId":"background","resolvedEndLayerId":"water","layerCount":2,"layers":[{"layerIndex":0,"layerId":"background","layerType":"background","visible":true,"sourceId":null,"sourceLayer":null},{"layerIndex":1,"layerId":"water","layerType":"fill","visible":true,"sourceId":"chart","sourceLayer":"water"}],"cache":{"cacheState":"reuse","contentRevision":19,"build":1,"reuse":120,"invalidation":0,"lastInvalidationReason":"none","textureCreate":1,"compositeCreate":1,"resourceRelease":0}},
+    {"segmentIndex":1,"strategy":"CONTINUOUS","configuredStartLayerId":"rn-weather-color","beginIndex":2,"endExclusive":4,"resolvedStartLayerId":"rn-weather-color","resolvedEndLayerId":"rn-weather-particles","layerCount":2,"layers":[{"layerIndex":2,"layerId":"rn-weather-color","layerType":"weather-color","visible":true,"sourceId":"rn-weather-fields","sourceLayer":null},{"layerIndex":3,"layerId":"rn-weather-particles","layerType":"raster-particle","visible":true,"sourceId":"rn-weather-fields","sourceLayer":null}],"cache":null},
+    {"segmentIndex":2,"strategy":"RETAINED","configuredStartLayerId":"land-area","beginIndex":4,"endExclusive":5,"resolvedStartLayerId":"land-area","resolvedEndLayerId":"land-area","layerCount":1,"layers":[{"layerIndex":4,"layerId":"land-area","layerType":"fill","visible":true,"sourceId":"chart","sourceLayer":"land"}],"cache":{"cacheState":"ready","contentRevision":22,"build":2,"reuse":80,"invalidation":1,"lastInvalidationReason":"layer-mutation","textureCreate":2,"compositeCreate":2,"resourceRelease":1}},
+    {"segmentIndex":3,"strategy":"RETAINED","configuredStartLayerId":"ais-layer","beginIndex":5,"endExclusive":6,"resolvedStartLayerId":"ais-layer","resolvedEndLayerId":"ais-layer","layerCount":1,"layers":[{"layerIndex":5,"layerId":"ais-layer","layerType":"symbol","visible":true,"sourceId":"ais","sourceLayer":null}],"cache":{"cacheState":"reuse","contentRevision":11,"build":1,"reuse":40,"invalidation":0,"lastInvalidationReason":"none","textureCreate":1,"compositeCreate":1,"resourceRelease":0}}
+  ]
+}
+```
+
+有效 snapshot 保证 Segment layers 拼接等于 styleLayers，Layer 不重号、不遗漏、不重复。RN Test Host 的按钮只在用户操作时配置/拉取并显示一次完整 JSON，不轮询、不逐帧打印。
+
+## 10. 当前限制
+
+- 多 Continuous 只保证正确 full renderer，不提供高级 Particle Fast Path。
+- Source/Tile mutation 尚无通用 dependency graph，仍全 retained invalidation。
+- Legacy diagnostics 只是兼容摘要，不能表达任意 N Segment。
+- OpenGL/Metal 编译、Native tests、Android codegen/Gradle 与设备运行由 RDC 独立验证后才能形成 PASS 事实。
--- a/docs/50_Step记录/STEP-094_通用RenderSegment分段渲染与Style分类诊断_v1.md
+++ b/docs/50_Step记录/STEP-094_通用RenderSegment分段渲染与Style分类诊断_v1.md
@@ -0,0 +1,66 @@
+# STEP-094 通用 RenderSegment 分段渲染与 Style 分类诊断 v1
+
+## 状态
+
+**PASS / CLOSED（RDC 代码与构建验收完成）**
+
+Codex 完成实现后，RDC 已独立完成 OpenGL Native 编译与定向 tests、Metal-only iPhoneOS 编译、RN TypeScript/codegen、Android Validation APK 构建与产物自检。规定的代码/编译验收门槛全部通过；Android/iOS 实体机运行与视觉验证本 STEP 未执行，明确保留为 NOT RUN。
+
+## 起始基线
+
+- 机器：`Mac-mini-tei.lan`
+- 仓库：`/Users/tei/dev/MapLibreParticleLab`
+- 分支：`particle/main`
+- 起始 HEAD：`8fbb892a1236a55329ed9ef5a612640c9363d3f1`
+- 起始 `origin/particle/main`：同上
+- V12 tag：`maplibre-particle/rn/13.4.1-particle.12`（`7eaff6e12`）
+- 起始工作树：clean
+
+## 实现结果
+
+- 新增 typed Core `RenderSegmentPlan` / resolved plan / diagnostics model。
+- explicit plan、V12 Continuous Range 与 legacy boundary 统一进入一个 resolver。
+- Style boundary ID 在 RenderOrchestrator 按完整 orderedLayers 解析；hidden Layer 仍参与。
+- Renderer 改为 topology-sized cache vector；每个 Retained Segment 独立 lazy GPU cache，Continuous 无 retained resource。
+- Segment 按 Style 顺序执行，global layerIndex/original ordinal/currentLayer/depthRangeSize 保持。
+- Layer Impl fingerprint 支持明确 retained Segment 内的 layer-local invalidation；Source/Tile 等仍保守全 retained invalidation。
+- 单 Continuous 保留既有 Particle Fast Path；多 Continuous fail closed 到 full CPU frame。
+- pull diagnostics 返回完整 Style→Segment→Layer、config/topology revision、coverage 与每个 retained cache 统计。
+- Android/iOS/RN 沿既有 WeatherRuntimeBridge 增加 plan 与 diagnostics JSON ABI；RN public API 为 typed object/discriminated union。
+- RN Test Host 增加 `Apply C-R plan` 与 `Fetch Segment Diagnostics`，只在用户操作时拉取一次。
+
+## 定向测试源码
+
+在既有 `retained_underlay_cache.test.cpp` 增加 RenderSegmentPlan/Diagnostics tests，覆盖：全 Retained、全 Continuous、C-R-R、R-R-C、R-C-R-C-R、相邻 R 不合并、missing/duplicate/reversed、hidden boundary、插入 Layer membership、boundary 删除/恢复、compat R-C-R/Continuous-only、visibility 不推进 topology revision、Cache OFF diagnostics、完整 coverage/flatten、Continuous cache=null、严格 JSON strategy/schema。
+
+RDC 已执行过滤集：8 个 suite、43/43 tests PASS；其中 RenderSegmentPlan 9、RenderSegmentDiagnostics 4，并同时覆盖 V12 Continuous/Retained/Fast Path 回归。
+
+## RDC 验证结果
+
+- OpenGL：`mbgl-test-runner` 编译 PASS（exit 0）；定向过滤集 43/43 PASS。
+- Metal/iPhoneOS：确认 `MLN_WITH_METAL=ON`、`MLN_WITH_OPENGL=OFF`；`ios-sdk-static` 编译 PASS（exit 0）。
+- RN package TypeScript：PASS；RN Test Host 使用本工作树 package typecheck PASS。
+- RN codegen：顶层 `npx react-native codegen` 因工程未安装 `@react-native-community/cli` 无法作为入口；未修改依赖，改用当前已安装 RN 0.85 的 `@react-native/codegen` combine/generate-all 正式底层入口 PASS，并确认 Android Java/JNI、C++ JSI 与 iOS ObjC++ 生成物均含 `setRenderSegmentPlanJson` / `getRenderSegmentDiagnosticsJson`。
+- Android Validation APK：标准脚本 PASS；OpenglDebug / x86_64 / strip=true；APK 60,294,298 bytes；`libmaplibre.so` 39,421,736 bytes；SHA-256 `848c3196c64cee6dfb1e9627f4af32b6e235fdd82afd1cfb8474c7fc5d591c71`。
+- Android/iOS 实体机 runtime 与视觉：NOT RUN。
+- Jest：明确不加入、不执行。
+
+## RDC 验证重点
+
+1. Core 编译：重点检查 rapidjson header、RenderLayer Impl metadata、JNI String ABI 与 ObjC++ selector。
+2. Tests：验证 resolver/diagnostics 新 suites 及 V12 原有 Continuous/Retained/Fast Path suites。
+3. OpenGL/Metal：确认 N retained resource、相邻 retained 不合并、稳定帧不重复创建。
+4. RN codegen：确认新增两个 primitive JSON methods 在 Android/iOS generated Spec 与实现 selector 对齐。
+5. Runtime：拉取 snapshot，核对 `styleLayers` 与 flatten(segment.layers) 完全一致；Cache OFF 仍保留 topology。
+
+## 当前限制
+
+- 多 Continuous Fast Path 未优化，按任务边界明确 fail closed。
+- Source/Tile mutation 无安全通用 dependency graph，仍全 retained invalidation。
+- 旧 diagnostics 仅兼容摘要；新 API 才是多 Segment 权威事实。
+- 多 Continuous Fast Path 仍按设计 fail closed，不是本 STEP 缺陷。
+- Android/iOS 真机运行和视觉结果不在本次 PASS 证据内。
+
+## 下一步
+
+实现代码已以 `016fd1fff`（`feat: add generic render segment model`）提交并 push。完成报告与本 Step 记录作为独立文档收尾 commit 提交；后续如需产品级 runtime/视觉确认，应另做 Android/iOS 运行态验收，不反向改变本 STEP 的代码验收结论。
--- a/docs/报告/STEP-094_通用RenderSegment分段渲染与Style分类诊断_Codex完成报告_v1.md
+++ b/docs/报告/STEP-094_通用RenderSegment分段渲染与Style分类诊断_Codex完成报告_v1.md
@@ -0,0 +1,126 @@
+# STEP-094 通用 RenderSegment 分段渲染与 Style 分类诊断 Codex 完成报告 v1
+
+## 1. 执行结论
+
+**PASS / CLOSED（RDC 独立验证完成）**
+
+任务书范围的 Core、Renderer、Android/iOS/RN bridge、定向测试、diagnostics pull 入口和中文文档均已完成。Codex 负责实现，RDC 按 AGENTS.md 独立完成 OpenGL、Metal、RN codegen/typecheck 与 Android Validation APK 验证。规定的代码与构建 Gate 均通过；Android/iOS 实体机 runtime/视觉未执行，未将其虚报为 PASS。
+
+## 2. Git 基线
+
+- Branch：`particle/main`
+- Starting HEAD：`8fbb892a1236a55329ed9ef5a612640c9363d3f1`
+- Starting remote：`origin/particle/main` 同上
+- Implementation commit：`016fd1fff`（完整 SHA `016fd1fff6a33cf795c10d4f5c5413d308383677`，如最终 Git 回读一致则以 Git 为准）
+- Commit message：`feat: add generic render segment model`
+- Implementation push：PASS，已推送 `origin/particle/main`
+- 文档收尾：本报告、Step 记录、设计文档与开发记录在实现 commit 后独立提交；包含本报告的 commit 无法在文件自身内自引用 SHA，最终远端 HEAD 由 RDC push 后回读确认。
+
+## 3. 实际实现
+
+- `RenderSegmentStrategy/Definition/Plan/Diagnostics` typed Core model。
+- schemaVersion=1 JSON parser/serializer，非法输入使 active plan invalid，不复用 stale topology。
+- boundary Layer ID → ordered Style layerIndex resolver，完整 coverage、严格递增、非空 Segment。
+- N Segment Renderer 遍历与 topology-sized retained cache ownership。
+- 每个 retained cache 独立 revision/build/reuse/invalidation/resource counters；Continuous 无 cache。
+- topology change 释放旧 cache；稳定 viewport lazy reuse。
+- LayerMutation 通过 immutable Impl fingerprint segment-local invalidation；无法可靠归属的 mutation 全 retained invalidation。
+- V12 `setContinuousLayerRange()` compatibility mapping 与旧 diagnostics API 保留。
+- 单 Continuous Particle Fast Path 保留；多 Continuous 明确 fallback。
+- diagnostics 返回 ordered styleLayers、ordered segments、每段 layers、sourceId/sourceLayer（可取得时）和 cache stats。
+- Android/iOS platform API、既有 RN TurboModule、typed TS API 和 RN Test Host pull 入口完成。
+
+## 4. 修改文件类别
+
+- Core public/private：Map API、RenderSegment model/resolver/JSON、runtime state、orchestrator、renderer、retained cache。
+- Build：CMake 与 Bazel core header/source lists。
+- Android：MapLibreMap/NativeMap/NativeMapView/JNI。
+- iOS：MLNMapView public API 与 ObjC++ bridge。
+- RN：types、Native Spec、RendererRuntime、Android/iOS bridge、Test Host。
+- Tests：`test/renderer/retained_underlay_cache.test.cpp`。
+- Docs：STEP-094 设计、Step 记录、本报告、开发记录。
+
+准确逐文件列表以最终 `git status --short` 为准。
+
+## 5. Diagnostics 与一致性
+
+- valid 时 `segmentCount == segments.length`、`styleLayerCount == styleLayers.length`、Segment 连续覆盖 `[0,layerCount)`。
+- 每段 `layers` 从同一 ordered styleLayers slice 生成；flatten 后顺序与 styleLayers 完全一致。
+- 全局 layerIndex 不按 Segment 重编号。
+- Continuous `cache=null`；Retained cache object 包含 content revision 与生命周期 counters。
+- invalid plan 保留当前 ordered styleLayers，segments 为空且 `valid=false/fallback=true`。
+- snapshot 只在显式 pull 时 JSON stringify；Style 字符串 metadata 仅在 config/style layer metadata 变化时重建。
+
+## 6. OpenGL / Metal / Tests
+
+- OpenGL build：PASS。命令 `cmake --build build-step088-opengl --target mbgl-test-runner -j3`，exit 0；仅既有 Boost/macOS deployment warnings。
+- Native directed tests：PASS。过滤集共 8 suites / 43 tests，43/43 PASS；其中 `RenderSegmentPlan` 9、`RenderSegmentDiagnostics` 4，并包含 V12 Continuous/Retained/Fast Path 回归。
+- Metal build：PASS。预先确认 `MLN_WITH_METAL=ON`、`MLN_WITH_OPENGL=OFF`；`cmake --build build-ios --target ios-sdk-static -- -quiet` exit 0。存在既有 EAGL/statusBar deprecation 与 bundle-id warning，无编译/链接错误。
+- RN package TypeScript：PASS。
+- RN Test Host TypeScript：PASS，验证时临时将 node_modules package 指向本工作树，结束后恢复旧依赖。
+- RN codegen：PASS。工程的 `npx react-native codegen` 因缺少 `@react-native-community/cli` 入口返回 1；未升级/修改依赖，改用同一已安装 RN 0.85 `@react-native/codegen` 的 combine-js-to-schema + generate-all，exit 0，并在 Android Java/JNI/C++ JSI 与 iOS ObjC++ generated Spec 中确认两个新方法。
+- Android Validation APK：PASS。标准脚本 `build_validation_apk.sh`，Gradle `BUILD SUCCESSFUL in 4m 45s`；x86_64-only、strip=true；APK 60,294,298 bytes，`libmaplibre.so` 39,421,736 bytes，SHA-256 `848c3196c64cee6dfb1e9627f4af32b6e235fdd82afd1cfb8474c7fc5d591c71`。
+- Android/iOS runtime/视觉：NOT RUN。
+- Jest：未加入、未执行。
+
+## 7. RDC 精确验证命令
+
+### OpenGL Native runner
+
+```bash
+cd /Users/tei/dev/MapLibreParticleLab
+cmake --build build-step088-opengl --target mbgl-test-runner -j3
+build-step088-opengl/mbgl-test-runner --gtest_filter='RenderSegmentPlan.*:RenderSegmentDiagnostics.*:ContinuousLayerRange.*:RetainedDynamicBoundary.*:RetainedLayerGroupRange.*:RetainedUnderlayCache.*:RetainedUnderlayRevision.*:ParticleFastPath.*'
+```
+
+### Metal / iPhoneOS arm64 compile
+
+```bash
+cd /Users/tei/dev/MapLibreParticleLab
+cmake --build build-ios --target ios-sdk-static -- -quiet
+```
+
+RDC 必须先确认 `build-ios/CMakeCache.txt` 的 `MLN_WITH_METAL=ON`、`MLN_WITH_OPENGL=OFF`，不能用 target 名称推断后端。
+
+### RN TypeScript / Codegen
+
+在现有 RN Test Host 已安装依赖环境中执行：
+
+```bash
+cd /Users/tei/dev/MapLibreParticleLab/integration/react-native/MapLibreParticleRNTestHost
+npm run typecheck
+npx react-native codegen
+```
+
+若当前工程的 RN 0.85 codegen 正式入口由 Expo prebuild/Pods 驱动，RDC 应使用现行 STEP-083 流程，并核对 generated Android/iOS Spec 确实含 `setRenderSegmentPlanJson`、`getRenderSegmentDiagnosticsJson`，不要只看 TS。
+
+### Android compile / Validation APK
+
+```bash
+cd /Users/tei/dev/MapLibreParticleLab
+./tools/particle_android_validation/build_validation_apk.sh
+```
+
+若还需 RN Test Host Android compile，使用当前 STEP-080 v2 公网/本地 package handoff 流程生成包含本工作树 package 的测试依赖后再编译；不得误用远端 `.10` tgz 代替本轮源码。
+
+## 8. 需要验证的 targets / tests
+
+- `mbgl-test-runner`
+- `ios-sdk-static`（Metal-only iPhoneOS arm64）
+- Android `MapLibreAndroid` JNI/Java 与 `MapLibreAndroidTestApp` OpenGL Debug x86_64
+- RN `WeatherRuntimeBridgeSpec` Android/iOS codegen
+- RN Test Host TypeScript
+- Native suites：`RenderSegmentPlan`、`RenderSegmentDiagnostics` 及全部 V12 Continuous/Retained/Fast Path 回归
+- 运行态重点：R-C-R、C-R-R、R-R-C、R-C-R-C-R、相邻 R-R 独立 counters、invalid/recovery、hidden boundary、Cache OFF、单 Continuous Fast Path、多 Continuous fallback、Style/segment layer flatten 一致性
+
+## 9. Known limitations / 未完成
+
+- 多 Continuous Fast Path 未优化，按任务边界明确 fail closed。
+- Source/Tile mutation 仍为保守全 retained invalidation。
+- RN Test Host package.json 仍指向历史远端 `.10` tgz；本次通过临时工作树 package + 直接 RN 0.85 codegen 验证新接口，没有把旧包结果冒充新实现。
+- Android/iOS 实体机 runtime、视觉与性能观察 NOT RUN；本报告的 PASS 仅表示 STEP-094 规定的代码、编译、测试、ABI/codegen Gate 已通过。
+- Android Validation build-info 中 commit 字段为构建时尚未提交的起始 HEAD，且 `git_dirty=true`；这是预提交验证事实，产物 SHA 与验证结果有效，但不是发布 artifact。
+
+## 10. 最终状态
+
+代码/构建验收：`PASS / CLOSED`。实现 commit `016fd1fff` 已 push；文档收尾 commit 完成后由 RDC 再次确认 `HEAD == origin/particle/main` 与工作树 clean。