MapLibreParticleLab/docs/报告/STEP-094_通用RenderSegment分段渲染与Style分类诊断_Codex完成报告_v1.md

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

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

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 已安装依赖环境中执行：

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

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。