docs: hand off STEP-093 runtime validation

docs/40_任务/STEP-093_ContinuousRange运行态综合验收_Codex任务_v1.md

@@ -0,0 +1,652 @@
+# STEP-093：Continuous Range 运行态综合验收
+
+## 1. 任务目标
+
+在 STEP-092 已完成并关闭的 Continuous Range / Retained Cache 架构基础上，进入真实 Renderer 运行态综合验收。
+
+本任务不重新设计 STEP-092 架构，不引入新的 Z-order 体系，不重做 retained cache 结构。目标是通过可重复、可观察、可诊断的运行态场景，确认以下核心事实在真实渲染过程中成立：
+
+1. Style Layer 顺序仍然是唯一 Z-order 真相。
+2. `[startLayerId, endLayerId]` 能稳定解析为一个 Continuous Range。
+3. Bottom / Continuous / Top 四种合法退化结构均能正确工作。
+4. 实际 retained cache 数量严格为 0 / 1 / 2，不存在的 range 不创建无意义 GPU 资源。
+5. Particle 连续播放时，稳定的普通 Style/PBF 内容能够命中 retained cache，而不是每帧重复完整绘制。
+6. Top range 能真实覆盖 Continuous 中的 Particle，验证最终画面顺序为：`Bottom → Continuous → Top`。
+7. Camera、viewport、style、layer/source 等变化发生时能够正确 invalidation、rebuild，并重新进入稳定 reuse。
+8. Fast Path 失败时必须安全退回 full CPU frame，但不得破坏 Continuous Range、retained cache 和 Z-order。
+9. Android/OpenGL 与 iOS/Metal 最终表现一致；若本阶段只能先完成 Android，则 iOS 可明确记录为后续待验收，不得虚报通过。
+
+---
+
+## 2. 当前基线
+
+开始任务前必须先检查真实仓库，不得只依赖任务书中的 SHA。
+
+预期起始基线：
+
+- Repository: `MapLibreParticleLab`
+- Branch: `particle/main`
+- STEP-092 最终状态：`CLOSED / PASS（Mac Native 验证闭环）`
+- STEP-092 最终已知 HEAD：`8a5d88008c142e2a80e0ff602d228e0e67de2d83`
+- `HEAD == origin/particle/main`
+- 工作区应为 clean
+
+STEP-092 已完成的关键内容包括：
+
+- Continuous Range 显式配置；
+- Bottom / Continuous / Top 三段模型；
+- 四种合法退化拓扑；
+- 0 / 1 / 2 retained cache；
+- Bottom/Top retained cache；
+- Top 透明 RGBA + premultiplied alpha 合成；
+- Style mutation 后重新解析；
+- invalid explicit range 的安全 fallback；
+- Particle Fast Path 与 retained cache 的协同；
+- Android / iOS Bridge 接口；
+- OpenGL Native build；
+- iOS Metal-only native build；
+- 定向 Native tests 29/29 PASS。
+
+本 STEP 不重新证明上述静态设计，而是证明它们在真实运行态画面与资源生命周期中成立。
+
+---
+
+## 3. 开始前必读
+
+Codex 开始前必须读取：
+
+1. 仓库根目录 `AGENTS.md`
+2. 当前粒子系统总规则 / 架构约束文档
+3. `docs/50_Step记录/STEP-092_ContinuousRange可退化分段RetainedCache_v2.md`
+4. `docs/报告/STEP-092_ContinuousRange可退化分段RetainedCache_Codex完成报告_v2.md`
+5. STEP-092 相关实现文件与 diagnostics 实现
+6. 当前 Android/iOS Particle Test App / validation 页面 / Host runtime 实现
+7. 当前可用的测试按钮、场景、日志和 diagnostics 展示入口
+
+如实际仓库结构与本任务书描述不一致，以当前真实代码为准，并在报告中写明差异。
+
+---
+
+## 4. 本任务职责划分
+
+### 4.1 Codex 负责
+
+Codex 负责：
+
+- 调查当前可用的运行态测试入口；
+- 为 STEP-093 补齐必要的 Test/Validation UI、场景切换、diagnostics 展示和最小测试辅助代码；
+- 只在确有必要时补充可观察性；
+- 修复在准备阶段发现的明确、局部、与 STEP-093 验收直接相关的问题；
+- 为 RDC / 用户准备清晰、可逐项执行的运行态验收入口；
+- 更新中文 STEP 记录、完成报告和开发记录；
+- 提交并 push 自己完成的代码与文档。
+
+### 4.2 RDC / 用户负责
+
+实际 Android / iOS 编译、安装、启动、真机或模拟器运行、视觉操作与最终画面确认由 RDC / 用户执行。
+
+Codex 不得仅依据静态代码、日志或自己推测就把运行态测试标记为 PASS。
+
+如果没有实际执行某个运行态场景，必须写为 `NOT RUN`、`WAITING_RUNTIME_VALIDATION` 或其他明确的未完成状态，不得写成 PASS。
+
+---
+
+## 5. 严格保护的 STEP-092 架构
+
+本 STEP 禁止借“测试方便”修改以下既定架构：
+
+1. Style 顺序是唯一 Z-order 真相。
+2. App/RN 只提供 `startLayerId`、`endLayerId`。
+3. Native 自行解析 index。
+4. Continuous Range 为闭区间 `[startLayerId, endLayerId]`。
+5. 内部：`continuousBegin = startIndex`，`continuousEndExclusive = endIndex + 1`。
+6. 三段：Bottom `[0, begin)`、Continuous `[begin, endExclusive)`、Top `[endExclusive, layerCount)`。
+7. `start == end` 合法。
+8. Continuous-only 合法，不是 fallback。
+9. 不允许加入 anchor / marker layer。
+10. 不允许增加第二套 BOTTOM / CONTINUOUS / TOP metadata 真相源。
+11. 不允许 Renderer 硬编码 NavSea/AIS/Alarm/Wind/Wave 等业务 Layer ID。
+12. Visibility 不改变 topology。
+13. explicit range 有效时不得再混用旧 `startsRetainedDynamicRange()` 作为 topology boundary。
+14. 不允许把普通 style layer 改造成新的特殊 layer type 来解决测试问题。
+15. 不做任意 N-range planner。
+16. 不做多个 Continuous Range。
+17. 不做频率分类系统。
+18. 不做 PBF 通用重构。
+19. 不做 RenderGraph 重构。
+20. 不加入 Jest。
+
+---
+
+# 6. STEP-093 必测场景
+
+## 6.1 场景 A：Bottom + Continuous + Top
+
+构造至少：Bottom 为普通 Style/PBF Layer，Continuous 为 Particle / Weather 动态 Layer，Top 为普通 Style/PBF Layer。
+
+必须验证：
+
+- explicit range valid；
+- Bottom present = true；
+- Top present = true；
+- retained cache 实际数量 = 2；
+- Bottom cache 可 build/reuse；
+- Top cache 可 build/reuse；
+- 最终画面顺序 `Bottom → Continuous → Top`；
+- Top 内容能够真实覆盖 Particle；
+- 无明显黑边、错误透明、旧 cache 或层序颠倒。
+
+## 6.2 场景 B：Bottom + Continuous
+
+Continuous 结束于当前 Style 最顶层。
+
+必须验证：
+
+- Bottom present = true；
+- Top present = false；
+- retained cache 实际数量 = 1；
+- 不得创建 Top texture/FBO/compositor；
+- 不存在的 Top 不得阻塞 Fast Path；
+- 画面顺序正确。
+
+## 6.3 场景 C：Continuous + Top
+
+Continuous 从当前 Style 最底层开始。
+
+必须验证：
+
+- Bottom present = false；
+- Top present = true；
+- retained cache 实际数量 = 1；
+- 不得创建 Bottom texture/FBO/compositor；
+- 不存在的 Bottom 不得阻塞 Fast Path；
+- Top 可正确覆盖 Particle。
+
+## 6.4 场景 D：Continuous only
+
+Continuous 覆盖全部 Style Layer。
+
+必须验证：
+
+- Bottom present = false；
+- Top present = false；
+- explicit range valid = true；
+- retained cache 实际数量 = 0；
+- 这是合法 Continuous-only，不得被识别为 fallback；
+- 不创建 retained texture/FBO/compositor；
+- Particle/continuous renderer 正常运行。
+
+## 6.5 场景 E：Single-layer Continuous
+
+设置 `startLayerId == endLayerId`。
+
+必须验证：
+
+- range valid；
+- startIndex == endIndex；
+- continuousEndExclusive == startIndex + 1；
+- 正常参与 Bottom/Top 切分；
+- 不得 fallback；
+- 不得被误认为空 range。
+
+---
+
+# 7. Z-order 核心视觉验收
+
+这是 STEP-093 的最高优先级运行态验收。
+
+必须构造一个肉眼可以清楚确认覆盖关系的场景：
+
+1. Bottom 中放一个明显底图/填充层；
+2. Continuous 中运行 Particle；
+3. Top 中放一个能够明显覆盖 Particle 的普通 Style Layer。
+
+优先使用已有普通 Style Layer；如果测试环境缺少合适图层，可添加纯测试用普通 Style Layer，但不得引入新的特殊 layer type 或业务硬编码。
+
+建议 Top 验证至少覆盖：opaque fill、半透明 fill、line；如当前测试环境可行，再加入 symbol/text。
+
+必须确认：
+
+- Top 真正绘制在 Particle 上方；
+- Particle 不会穿透 opaque Top；
+- 半透明 Top 与 Particle 合成正确；
+- 无黑边；
+- 无颜色异常变暗；
+- 无错误双重 alpha；
+- 无 cache 旧内容残留。
+
+---
+
+# 8. Stable Frame / Cache Reuse 验收
+
+在 Camera、viewport、Style、普通 PBF/source 内容都不变化，仅 Particle 持续动画时，必须观察：
+
+- Bottom/Top retained cache build 后持续 reuse；
+- 不应每个 Particle frame 重建 retained cache；
+- 不应每 frame 重建 retained texture；
+- 不应每 frame 重建 FBO/offscreen texture；
+- 不应每 frame 重建 composite group；
+- Fast Path 在满足条件时能够持续命中；
+- diagnostics 能够区分 build / reuse / invalidation。
+
+如果现有 diagnostics 无法证明资源生命周期，可增加最小 debug-only counter / reason 字段。禁止为了测试引入生产环境高频日志风暴。
+
+---
+
+# 9. Camera / Viewport invalidation
+
+至少验证：Pan、Zoom、Rotate、Pitch、viewport resize/orientation 或等价尺寸变化，以及测试环境可实际触发时的 pixel ratio 变化。
+
+每项检查：
+
+- 旧 retained cache 被正确 invalidation；
+- 下一帧或正确时点 rebuild；
+- rebuild 后重新进入 reuse；
+- 不出现 stale cache；
+- 不出现错位；
+- 不出现黑屏；
+- 不出现 Particle 与地图不同步；
+- topology 不应无故改变。
+
+---
+
+# 10. Style Mutation / Topology 重新解析
+
+必须提供可重复测试入口，至少覆盖：
+
+### 10.1 Continuous 内部变更
+
+添加 Layer、删除非 endpoint Layer、reorder Continuous 内部 Layer。
+
+预期：重新解析必要状态；range 仍有效时保持正确 topology；cache 根据需要 invalidation；不产生第二套 Z-order。
+
+### 10.2 Bottom 内变更
+
+添加、删除、reorder，检查 Bottom cache invalidation / rebuild / reuse。
+
+### 10.3 Top 内变更
+
+添加、删除、reorder，检查 Top cache invalidation / rebuild / reuse。
+
+### 10.4 Layer 跨边界移动
+
+将某个普通 Layer 做有代表性的 Bottom → Continuous、Continuous → Top 或 Top → Bottom 跨 range 移动。
+
+必须验证：
+
+- ID → index 重新解析；
+- topology/cache/prepared state 正确 invalidation；
+- 新 Z-order 正确；
+- 不使用旧 index；
+- 不出现 stale cache。
+
+---
+
+# 11. Endpoint 删除与恢复
+
+删除 start endpoint 时：explicit range 立即 invalid；不 crash；不猜测新 start；不继续使用 stale index/cache；进入既定安全 fallback；diagnostics 有明确 lastReason。
+
+恢复 start endpoint 时：Native 能重新解析；explicit range 恢复 valid；正确重建需要的 cache；不需要重建整个 Map instance。
+
+对 end endpoint 做同等验证。
+
+---
+
+# 12. Visibility 不改变 topology
+
+对 start endpoint、end endpoint 或 Continuous 内普通 Layer 做 visible → hidden → visible。
+
+必须验证：
+
+- topology 仍以 Style 顺序解析；
+- startIndex/endIndex 不因 visibility 改变；
+- hidden endpoint 仍是 endpoint；
+- 不自动收缩 Continuous Range；
+- ON/OFF 只作为内容变化处理；
+- 如需 cache invalidation，应是内容 invalidation，不得变成新的 topology 规则。
+
+---
+
+# 13. Invalid Explicit Range
+
+至少验证：
+
+1. startLayerId 不存在；
+2. endLayerId 不存在；
+3. startIndex > endIndex；
+4. Style 尚未 ready 时配置；
+5. 空 ID / 未配置（按实际 API 合法性处理）。
+
+预期：不 crash；不猜测；不复用 stale cache；不按 Layer 类型自动修正；进入明确安全 fallback；diagnostics 显示 invalid 原因；条件恢复后能够重新进入 explicit range。
+
+---
+
+# 14. Particle Fast Path
+
+## 14.1 可命中场景
+
+Continuous 内只保留当前 Fast Path 已支持的动态内容。
+
+检查：Fast Path 可持续命中；Bottom/Top 的存在与否只影响实际存在的 retained cache；0 cache 的 Continuous-only 不得因为“没有 retained cache”而错误阻止 Fast Path。
+
+## 14.2 Fail Closed 场景
+
+在 Continuous 中加入当前 Fast Path 不支持的普通/未知 Continuous Layer。
+
+必须验证：
+
+- Fast Path 退回 full CPU frame；
+- 不 crash；
+- 不错误跳过该 Layer；
+- Continuous Range 本身保持 valid；
+- Bottom / Top retained cache Z-order 仍正确；
+- 不允许为了 Fast Path 强行把未知 Layer 移出 Continuous。
+
+---
+
+# 15. Top Alpha / Premultiplied Alpha 验收
+
+必须重点看 Top retained cache 合成：transparent background、opaque fill、semi-transparent fill、line，以及可行时 symbol/text。
+
+检查：透明区域正确露出 Particle；半透明区域正常叠加；opaque 区域完整覆盖；无黑色边缘；无 halo；无颜色被错误乘两次；无残影；OpenGL 与 Metal 设计保持一致。
+
+---
+
+# 16. 长时间运行与资源稳定性
+
+在测试环境允许情况下进行持续运行测试，至少包括：Particle 连续播放、多次 Pan/Zoom/Rotate、多次 range 配置变化、endpoint 删除/恢复、visibility 切换、style mutation、再次稳定运行。
+
+观察：
+
+- 无持续 GPU resource 增长迹象；
+- retained texture/FBO 不因 stable frame 每帧新建；
+- 无明显内存持续增长；
+- 无黑屏；
+- 无闪屏；
+- 无 stale cache；
+- 无偶发层序颠倒；
+- 无 Particle 停止后恢复不了的问题。
+
+如果当前工程缺少可靠 GPU memory 数字来源，不要求伪造数值；允许使用资源创建/释放 counter、diagnostics 和稳定运行现象作为当前阶段证据，并明确限制。
+
+---
+
+# 17. Diagnostics 要求
+
+STEP-093 的测试入口必须能清楚观察至少以下信息：
+
+### Range
+
+- configured
+- valid
+- startLayerId
+- endLayerId
+- startIndex
+- endIndex
+- continuousBegin
+- continuousEndExclusive
+- fallback / lastReason
+
+### Bottom
+
+- present
+- cache state
+- build count
+- reuse count
+- invalidation count
+- last invalidation reason
+
+### Top
+
+- present
+- cache state
+- build count
+- reuse count
+- invalidation count
+- last invalidation reason
+
+### Fast Path
+
+- eligible / active
+- fallback reason
+- full CPU frame count 或等价诊断（若现有已有）
+- unknown continuous layer 导致 fail-closed 的可观察原因
+
+如当前已有字段足够，不得重复造一套 diagnostics。
+
+---
+
+# 18. Test UI / Playground 要求
+
+优先复用现有 Particle Test App / validation UI。
+
+如果需要新增 STEP-093 面板，要求：
+
+- 不影响生产 MapLibre API 语义；
+- 不引入 NavSea 业务逻辑；
+- 场景按钮命名明确；
+- 能一键切换四种 topology；
+- 能设置 single-layer range；
+- 能触发 invalid range；
+- 能隐藏/显示 endpoints；
+- 能删除/恢复 endpoint；
+- 能触发代表性的 reorder / cross-boundary move；
+- 能显示当前 diagnostics；
+- 能恢复默认测试场景。
+
+测试 UI 本身不应成为复杂新框架。
+
+---
+
+# 19. Android 运行态验收
+
+Android 作为本 STEP 首要完整运行态验收平台。
+
+Codex 必须准备：
+
+- 明确的 build/install/run 手工命令；
+- STEP-093 测试入口位置；
+- 每项场景的操作步骤；
+- 需要采集的日志/diagnostics；
+- PASS/FAIL 判定。
+
+实际 Android Gradle / APK / ADB / 真机或模拟器操作由 RDC / 用户执行。
+
+不得由 Codex 仅凭代码静态分析代替 Android 实机/模拟器结论。
+
+---
+
+# 20. iOS / Metal 运行态验收
+
+Android 完整通过后，再进行 iOS / Metal 对等测试。
+
+至少需要验证：四 topology、Single-layer Continuous、Top 覆盖 Particle、Stable cache reuse、Camera invalidation、endpoint missing/recovery、visibility、Fast Path fail-closed、Top alpha。
+
+如果本 STEP 暂未执行 iOS runtime：
+
+- 报告必须明确写 `WAITING_IOS_RUNTIME_VALIDATION`；
+- Android PASS 不得自动推导为 iOS PASS；
+- Metal native build PASS 也不能替代 Metal runtime rendering PASS。
+
+---
+
+# 21. 编译与测试原则
+
+1. MapLibre Native 的 Android/iOS 开发与编译统一使用 Mac。
+2. 不安排 Linux Native 编译。
+3. noisy native build 遵循 Mac/Codex 全局构建输出节流规则。
+4. 不加入 Jest。
+5. 可运行已有 Native 精确测试；如代码变更影响 STEP-092 核心逻辑，应重跑相关现有 Native tests。
+6. 不为了“让测试绿”删除或弱化 STEP-092 已有覆盖。
+
+---
+
+# 22. 发现问题时的处理规则
+
+### 22.1 小型、事实明确、局部问题
+
+例如测试 UI 接线错误、diagnostics 漏展示、明确计数器错误、局部 invalidation reason 错误、编译错误、测试工具小缺陷，允许直接修复，并重新验收受影响项目。
+
+### 22.2 架构级问题
+
+如果发现需要修改 Continuous Range 数学定义、Style 顺序唯一 Z-order、0/1/2 retained cache 模型、renderer 大范围遍历结构、Fast Path 核心模型、第二套 layer metadata、新特殊 layer type、新 RenderGraph 或大规模 GPU cache redesign，必须停止当前修复扩张，先生成明确的“STEP-093 架构阻塞报告”，说明实际问题、复现方式、为什么 STEP-092 架构无法满足、建议方案和影响范围。
+
+不得在运行态测试任务中擅自重构架构。
+
+---
+
+# 23. 验收矩阵
+
+最终报告必须至少给出以下矩阵：
+
+| 类别 | 场景 | Android | iOS/Metal | 关键证据 | 结论 |
+|---|---|---|---|---|---|
+| Topology | Bottom+Continuous+Top | | | | |
+| Topology | Bottom+Continuous | | | | |
+| Topology | Continuous+Top | | | | |
+| Topology | Continuous-only | | | | |
+| Range | Single-layer Continuous | | | | |
+| Z-order | Top covers Particle | | | | |
+| Cache | Stable reuse | | | | |
+| Invalidation | Pan/Zoom/Rotate/Pitch | | | | |
+| Mutation | Continuous internal mutation | | | | |
+| Mutation | Cross-range move | | | | |
+| Endpoint | start missing/recovery | | | | |
+| Endpoint | end missing/recovery | | | | |
+| Visibility | hidden endpoint topology | | | | |
+| Invalid | missing/reversed range | | | | |
+| Fast Path | eligible | | | | |
+| Fast Path | unknown layer fail-closed | | | | |
+| Alpha | Top premultiplied composite | | | | |
+| Stability | repeated operations / long run | | | | |
+
+状态只允许使用清楚枚举，例如：PASS、FAIL、NOT RUN、BLOCKED、WAITING_ANDROID_RUNTIME_VALIDATION、WAITING_IOS_RUNTIME_VALIDATION。
+
+---
+
+# 24. STEP-093 完成条件
+
+只有满足下面条件，才允许把 STEP-093 标记为 `CLOSED / PASS`：
+
+1. Android 运行态核心矩阵实际执行并通过；
+2. 四种 topology 实际验证；
+3. Single-layer Continuous 实际验证；
+4. Top 覆盖 Particle 实际验证；
+5. 0/1/2 cache 与 diagnostics 一致；
+6. Stable reuse 实际验证；
+7. Camera invalidation → rebuild → reuse 实际验证；
+8. endpoint missing/recovery 实际验证；
+9. visibility 不改变 topology 实际验证；
+10. invalid range fallback 实际验证；
+11. Fast Path eligible + fail-closed 实际验证；
+12. Top alpha 无明显错误；
+13. 发现的阻塞性缺陷已解决并回归；
+14. 文档与 Git 收尾完整；
+15. `HEAD == origin/particle/main`；
+16. 工作区 clean。
+
+如果 Android 已全部通过但 iOS 尚未运行，可记录为：`ANDROID CLOSED / PASS + IOS WAITING_RUNTIME_VALIDATION`。不得把未运行的平台写成 PASS。
+
+---
+
+# 25. 必做输出
+
+本任务所有需要 ChatGPT/RDC 后续审查的文件必须由 Codex 在任务中实际生成，不得在结束后临时补要。
+
+## 25.1 STEP 记录
+
+生成：
+
+`docs/50_Step记录/STEP-093_ContinuousRange运行态综合验收_v1.md`
+
+如果同名主题已有版本，递增为 v2/v3……，不得覆盖旧版。
+
+内容至少包括：起始 Git 基线、调查到的实际测试入口、新增/修改内容、Android/iOS 实际执行状态、验收矩阵、问题与修复、未执行项、当前状态、下一步。
+
+## 25.2 Codex 完成报告
+
+生成：
+
+`docs/报告/STEP-093_ContinuousRange运行态综合验收_Codex完成报告_v1.md`
+
+同主题已有版本时递增版本号。
+
+报告至少包含：任务目标、修改文件、测试入口、diagnostics、build/test 实际结果、Android runtime 实际结果、iOS runtime 实际结果、PASS/FAIL/WAITING 状态、Git commit、push、Final HEAD、origin/particle/main、git status、未执行事项、风险与已知限制。
+
+## 25.3 开发记录
+
+追加：
+
+`粒子开发记录.md`
+
+只追加，不覆盖历史内容。
+
+---
+
+# 26. Git 规则
+
+严格遵守项目 Git 规则：
+
+- 只提交本任务相关文件；
+- 禁止 `git add -A`；
+- 禁止 `git add .`；
+- 禁止 `git reset --hard`；
+- 禁止 `git clean`；
+- 不触碰无关 dirty/untracked；
+- 功能代码与文档可按合理 scoped commit 拆分；
+- push 到 `origin/particle/main`；
+- push 后确认 `HEAD == origin/particle/main`；
+- 最终确认 `git status --short`；
+- push 失败不得标记任务完成。
+
+---
+
+# 27. Codex 执行终态规则
+
+Codex 本轮结束时必须给出真实状态，而不是默认写 PASS。
+
+建议状态：
+
+- `IMPLEMENTED / WAITING_RUNTIME_VALIDATION`
+- `PARTIAL / WAITING_ANDROID_RUNTIME_VALIDATION`
+- `ANDROID PASS / WAITING_IOS_RUNTIME_VALIDATION`
+- `CLOSED / PASS`
+- `BLOCKED`
+- `FAILED`
+
+如果只是完成测试工具与代码准备，而 RDC/用户尚未真正运行 Android，则只能标记等待运行态验收。
+
+---
+
+# 28. 明确不做
+
+STEP-093 不做：
+
+- 任意 N-range planner；
+- 多 Continuous Range；
+- frequency class 自动分类；
+- 自动 Z-order；
+- anchor/marker layer；
+- 第二套 BOTTOM/CONTINUOUS/TOP metadata；
+- NavSea AIS 专用优化；
+- Alarm 专用优化；
+- Weather provider；
+- Route ETA；
+- LandMask 业务系统；
+- Wave/Tide 业务系统；
+- PBF 通用重构；
+- RenderGraph 大改；
+- 新粒子算法；
+- 粒子视觉美化；
+- unrelated performance tuning；
+- Jest。
+
+---
+
+# 29. 最终核心判定
+
+STEP-093 最终不是检查“按钮能不能点”，而是验证 STEP-092 的核心架构在真实渲染中确实成立：
+
+> 普通地图内容可以被合理拆成 Bottom / Top retained cache，Particle 所在 Continuous Range 保持高频实时绘制；Style 顺序仍然决定最终 Z-order；不存在的 retained range 不产生资源；缓存只在需要时失效，并在稳定状态持续复用。
+
+只要这个结论还没有通过真实运行态证据建立，STEP-093 就不能写成最终 `CLOSED / PASS`。

docs/50_Step记录/STEP-093_ContinuousRange运行态综合验收_v1.md

@@ -0,0 +1,238 @@
+# STEP-093 Continuous Range 运行态综合验收 v1
+
+## 1. 当前状态
+
+**IMPLEMENTED / WAITING_RUNTIME_VALIDATION**
+
+Codex 已完成 Android 运行态验收入口、跨平台 diagnostics 补强、Fast Path fail-closed 原因观测、定向 Native 测试源码和 RDC 操作手册。依照仓库职责分工与本轮用户指令，Codex 未执行 Android/iOS 长时间编译、安装、ADB、模拟器/真机操作或视觉验收。因此 Android 为 `WAITING_ANDROID_RUNTIME_VALIDATION`，iOS/Metal 为 `WAITING_IOS_RUNTIME_VALIDATION`；本版不能标记 `CLOSED / PASS`。
+
+## 2. 起始 Git 基线
+
+- Repository：`MapLibreParticleLab`
+- 机器：`Mac-mini-tei.lan`
+- 路径：`/Users/tei/dev/MapLibreParticleLab`
+- Branch：`particle/main`
+- Starting HEAD：`8a5d88008c142e2a80e0ff602d228e0e67de2d83`
+- Starting `origin/particle/main`：`8a5d88008c142e2a80e0ff602d228e0e67de2d83`
+- STEP-092 基线：`CLOSED / PASS（Mac Native 验证闭环）`
+- STEP-093 implementation commit：`b3ec8edc87ece404b5f7b3706f5acf2a70de6862`
+- 起始工作树差异：仅有本任务书 `docs/40_任务/STEP-093_ContinuousRange运行态综合验收_Codex任务_v1.md` 为 untracked；已保留并纳入本 Step 文档提交。
+
+## 3. 实际调查到的测试入口
+
+Android 已有入口为 `MapLibreAndroidTestApp` 的 `ParticleCoreLayerValidationActivity`。本 Step 复用该 Activity、既有 Host-submitted particle fixture、`weather-color` 和普通 Style layer，不建立新测试框架，也不引入特殊 layer type。
+
+新增底部 `STEP 093` 菜单与常驻 diagnostics 区。入口支持：
+
+- A：Bottom + Continuous + Top；
+- B：Bottom + Continuous；
+- C：Continuous + Top；
+- D：Continuous only；
+- E：Single-layer Continuous；
+- Continuous/Bottom/Top add 与 reorder；
+- 普通 layer 跨 Bottom/Continuous/Top 移动；
+- start/end endpoint visibility、删除与恢复；
+- missing start、missing end、reversed、style loading 期间配置、empty ID、恢复 valid；
+- Camera preset 循环覆盖 pan/zoom/rotate/pitch；
+- Continuous 内未知普通 layer 触发 Fast Path fail-closed；
+- 1 秒一次的屏幕 pull diagnostics；仅用户点 `READ DIAGNOSTICS` 或场景切换时写一条日志，不制造逐帧日志风暴。
+
+Android Activity 声明增加 `orientation|keyboardHidden|screenSize` config changes，使 RDC 可在不重建 Map/Style 的前提下用旋转或尺寸变化观察 viewport invalidation。
+
+iOS 当前只有正式 `MLNMapView` diagnostics API 与 RN bridge 字段补齐，没有新增专用 STEP-093 iOS validation 页面。因此 iOS runtime 必须后续由 RDC 准备实际入口并执行，不能由 Android 结果推导。
+
+## 4. 本轮新增/修改内容
+
+### 4.1 Renderer diagnostics
+
+在既有 map-scoped diagnostics 上追加，而非另造一套状态源：
+
+- Range：`continuousBegin`、`continuousEndExclusive`、`rangeFallback`；
+- Bottom/Top：`cacheState`、build/reuse/invalidation、last invalidation reason；
+- 资源生命周期：texture create、composite create、resource release；
+- Fast Path：eligible、active、fallback reason、hit、miss、full CPU frame；
+- 未知 Continuous layer 的明确原因：`unsupported-continuous-layer`。
+
+这些 counter 是 Map 生命周期内累计事件数，不是 GPU memory byte 数。它们用于证明 stable frame 不重复创建资源及 invalidation 后能重建/reuse；不能替代 profiler 或 GPU capture。
+
+### 4.2 跨端暴露
+
+- Android JNI/Java：diagnostics 字符串数组由 20 项扩为 39 项，Java 构造索引与 Native 顺序逐项一致；
+- iOS ObjC++：`MLNRetainedUnderlayDiagnostics` 暴露同组字段；
+- RN Android/iOS/TypeScript/Test Host：透传并显示同组字段；
+- 原有 aggregate build/reuse/fallback/invalidation 字段保持，不删除兼容语义。
+
+### 4.3 Android 可视场景
+
+测试 Style 中仅使用普通 background/fill/line、已有 WeatherColor 与 RasterParticle：
+
+- Bottom：深色 background + 青色 fill；
+- Continuous：WeatherColor + Particle；
+- Top：半透明黄色 fill、opaque 红色 fill、白色粗 line；
+- fail-closed：在 Continuous 内加入普通 fill；
+- cross-range：同一个普通 fill ID 分别位于 endpoint 前、endpoint 间、endpoint 后。
+
+最终 Z-order 仍完全由 Style layer 数组顺序决定。App 只调用 `setContinuousLayerRange(startLayerId, endLayerId)`；没有 anchor/marker、业务 layer metadata 或 Renderer 业务 ID 硬编码。
+
+### 4.4 定向测试源码
+
+新增 `RetainedUnderlayCache.RuntimeValidationDiagnosticsExposeRangeResourcesAndFastPath`，覆盖 Continuous index、cache state、资源 counter、Fast Path counter；既有 Fast Path gate 测试增加 `UnsupportedContinuousLayer` 原因断言。
+
+本轮未运行 test runner。STEP-092 既有 29/29 PASS 是历史基线，不能当作新增测试已通过；RDC 运行后预期相关 filter 共 30 项，但必须以实际 runner 输出为准。
+
+## 5. 静态一致性审查
+
+Codex 已完成：
+
+- Native diagnostics 定义、runtime state、Android JNI/Java、iOS、RN 字段名与顺序逐项比对；
+- 四种 topology 与 single-layer 的 Style layer 顺序/endpoint 位置审查；
+- mutation、cross-range、endpoint、invalid、camera、fail-closed 菜单接线审查；
+- absent Bottom/Top 仍沿用 STEP-092 `Disabled` / lazy resource 路径，没有新增固定 GPU 分配；
+- Fast Path eligibility 与 decision counter 接入既有 gate，失败仍进入 full CPU frame；
+- `xmllint --noout`：Android Manifest 与 layout PASS；
+- `git diff --check`：PASS。
+
+未执行：C++/Java/Kotlin/ObjC++/TypeScript 编译、Native tests、Gradle、APK、ADB、Android/iOS runtime。静态审查不等于运行态 PASS。
+
+## 6. RDC Android 构建、安装与启动
+
+在仓库根目录执行：
+
+```bash
+./tools/particle_android_validation/build_validation_apk.sh
+adb devices
+adb -s <serial> install -r artifacts/maplibre-particle/android-validation/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk
+adb -s <serial> shell am start -n org.maplibre.android.testapp/.activity.particle.ParticleCoreLayerValidationActivity
+```
+
+可选定向日志：
+
+```bash
+adb -s <serial> logcat -c
+adb -s <serial> logcat -v threadtime ParticleValidation:I MapLibre:I '*:S'
+```
+
+若使用非 x86_64 真机，当前 validation script 的固定 ABI 不适用；RDC 应按项目现行 Android 构建规则选择相符 ABI，并在证据中记录实际 APK、commit、ABI、设备与 renderer backend。
+
+## 7. RDC Native 精确回归命令
+
+如 RDC 使用 STEP-092 的现有 OpenGL build tree：
+
+```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.*'
+```
+
+必须记录真实 test 数与结果；不能直接抄写“30/30”。
+
+## 8. Android 逐项运行手册
+
+### 8.1 通用观察方法
+
+启动 Activity 后点 `STEP 093`。每次切场景等待 Style READY，再观察屏幕 diagnostics；需要固化证据时点 `READ DIAGNOSTICS` 并保存日志/截图。稳定性判断建议至少间隔 10–30 秒采两次快照：
+
+- Particle 持续运动；
+- 对存在的 cache，build/texture/composite 不再增长，reuse 与 Fast hit 应增长；
+- 不存在的 range 显示 `present=false`、`state=disabled`，对应资源创建数不因稳定帧增长；
+- counter 为累计值，切场景时应比较增量，不要求绝对值归零。
+
+### 8.2 Topology A–E
+
+1. A：选 `A BOTTOM + CONTINUOUS + TOP`。预期 range valid、Bottom/Top present、cache count 2；opaque 红块完整盖住 Particle，黄色半透明区域正确混合，白线在最上层，无黑边/halo/错误变暗。
+2. B：选 `B BOTTOM + CONTINUOUS`。预期 Bottom present、Top absent、cache count 1；Top state disabled，Top 资源不增长，Fast Path 不因 Top absent 被阻断。
+3. C：选 `C CONTINUOUS + TOP`。预期 Bottom absent、Top present、cache count 1；Bottom state disabled；Top 仍正确覆盖 Particle。
+4. D：选 `D CONTINUOUS ONLY`。预期 valid、Bottom/Top 均 absent、cache count 0、不是 fallback；Particle 正常运行，Fast Path 可命中。
+5. E：选 `E SINGLE-LAYER CONTINUOUS`。预期 start ID 等于 end ID、startIndex 等于 endIndex、`continuousEndExclusive = startIndex + 1`，不 fallback。
+
+### 8.3 Mutation 与跨边界
+
+在 `MUTATION / FAST PATH` 子菜单依次执行：
+
+- `CONTINUOUS ADD` → `CONTINUOUS REORDER` → `RESTORE DEFAULT`：恢复动作也等价验证非 endpoint layer 删除；
+- `BOTTOM ADD` → `BOTTOM REORDER` → restore；
+- `TOP ADD` → `TOP REORDER` → restore；
+- `CROSS → BOTTOM` → `CROSS → CONTINUOUS` → `CROSS → TOP`。
+
+每次检查 endpoint ID 重新解析出的 index、present topology、invalidation/build/reuse 增量及最终画面顺序；不得出现旧 index、旧 cache 或自动按 layer 类型修正 range。
+
+### 8.4 Endpoint 与 visibility
+
+在 `ENDPOINT / VISIBILITY` 子菜单：
+
+- start visible ↔ hidden、end visible ↔ hidden：index 与 topology 不变，hidden endpoint 仍是 endpoint；
+- `DELETE START`：range invalid、fallback、无 crash/stale cache；`RESTORE START` 后恢复 valid 并 rebuild/reuse；
+- 对 end 执行同样步骤。
+
+### 8.5 Invalid explicit range
+
+在 `INVALID RANGE` 子菜单依次执行 missing start、missing end、reversed、configure while style loading、empty ID、restore valid：
+
+- missing/reversed/style-not-ready：不得猜测 endpoint，不复用 stale cache，diagnostics 给出原因；
+- empty ID：当前 API 应同步返回 `accepted=false`；
+- restore 后无需重建 Map instance，应重新 valid、build、reuse。
+
+### 8.6 Camera/viewport
+
+连续点四次 `CAMERA NEXT`，覆盖 target/zoom/bearing/pitch 组合。每次检查 invalidation → build → reuse，topology 不变，无错位、黑屏或 Particle/地图不同步。
+
+旋转设备或改变模拟器窗口尺寸，确认同一 Activity/Map 上产生 viewport invalidation；如设备支持可改变 display scale/pixel ratio，并单独记录是否实际触发。
+
+### 8.7 Fast Path fail-closed
+
+先恢复 A，稳定后确认 eligible/active 与 hit 增长。再选 `FAST FAIL-CLOSED`：
+
+- Continuous Range 仍 valid；
+- fallback reason 为 `unsupported-continuous-layer`；
+- Fast Path 不 active，full CPU frame 增长；
+- 普通未知 layer 不被跳过或移出 Continuous；
+- Bottom/Top 与最终 Z-order 仍正确。
+
+### 8.8 长时间运行
+
+建议 RDC 在可用设备上连续运行 15–30 分钟，循环 topology、camera、mutation、endpoint、visibility、invalid/restore、再次稳定：观察 texture/composite create 与 release 增量、系统内存/GPU 工具可获得的数据、黑屏/闪屏/stale cache/偶发层序/Particle 恢复。若没有可靠 GPU byte 数，明确记录限制，不伪造内存数字。
+
+## 9. PASS / FAIL 判定
+
+- `PASS`：必须有实际设备/模拟器操作、画面确认与 diagnostics/log 证据，并满足该行预期。
+- `FAIL`：实际结果违背预期；保留首个真实错误、场景、截图/日志和 commit。
+- `WAITING_*`：入口已准备但平台尚未执行。
+- 编译 PASS、静态检查 PASS、另一平台 PASS 均不能替代当前平台 runtime PASS。
+
+## 10. 验收矩阵
+
+| 类别 | 场景 | Android | iOS/Metal | 关键证据 | 结论 |
+|---|---|---|---|---|---|
+| Topology | Bottom+Continuous+Top | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | A 按钮、range/index、2 cache、画面截图待采集 | NOT RUN |
+| Topology | Bottom+Continuous | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | B 按钮、Top disabled/资源增量待采集 | NOT RUN |
+| Topology | Continuous+Top | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | C 按钮、Bottom disabled/资源增量待采集 | NOT RUN |
+| Topology | Continuous-only | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | D 按钮、valid + 0 cache + 非 fallback 待采集 | NOT RUN |
+| Range | Single-layer Continuous | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | E 按钮、start=end、endExclusive=start+1 待采集 | NOT RUN |
+| Z-order | Top covers Particle | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | opaque/semi-transparent/line 视觉截图待采集 | NOT RUN |
+| Cache | Stable reuse | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | 两次 counter 快照待采集 | NOT RUN |
+| Invalidation | Pan/Zoom/Rotate/Pitch | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | camera preset 前后 invalid/build/reuse 待采集 | NOT RUN |
+| Mutation | Continuous internal mutation | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | add/reorder/restore diagnostics 待采集 | NOT RUN |
+| Mutation | Cross-range move | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | cross layer 三位置的 index/Z-order 待采集 | NOT RUN |
+| Endpoint | start missing/recovery | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | invalid reason + restore valid 待采集 | NOT RUN |
+| Endpoint | end missing/recovery | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | invalid reason + restore valid 待采集 | NOT RUN |
+| Visibility | hidden endpoint topology | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | visible/hidden index 不变待采集 | NOT RUN |
+| Invalid | missing/reversed range | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | fallback/lastReason/no stale cache 待采集 | NOT RUN |
+| Fast Path | eligible | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | eligible/active/hit/full counter 待采集 | NOT RUN |
+| Fast Path | unknown layer fail-closed | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | unsupported reason/full CPU frame 待采集 | NOT RUN |
+| Alpha | Top premultiplied composite | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | transparent/opaque/semi/line 视觉证据待采集 | NOT RUN |
+| Stability | repeated operations / long run | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | 长时间 counter/内存/画面记录待采集 | NOT RUN |
+
+## 11. 问题、限制与未执行项
+
+- 未发现需要修改 STEP-092 数学定义、Style 顺序、0/1/2 cache 或 Fast Path 核心模型的架构阻塞。
+- diagnostics 是累计 counter，不是 per-scene reset；RDC 应使用前后增量。
+- 资源 release counter 表示 holder 释放事件，不是释放字节数。
+- Android 场景 Style reload 是可重复的测试手段；跨场景比较必须等待 READY。
+- 当前 iOS 没有专用 STEP-093 面板，只有 diagnostics API/bridge；这是明确待办，不虚报 iOS runtime 能力完成。
+- Android/iOS build、Native tests、APK、安装、ADB、真机/模拟器、视觉、长时间运行均 NOT RUN。
+
+## 12. 下一步
+
+1. RDC 对 implementation commit `b3ec8edc87ece404b5f7b3706f5acf2a70de6862` 执行 Native 精确回归与 Android build/runtime 矩阵。
+2. 若 Android 核心矩阵全部实际通过，可更新为 `ANDROID CLOSED / PASS + IOS WAITING_RUNTIME_VALIDATION`。
+3. 准备 iOS/Metal 对等 validation UI 或可重复操作入口，再独立执行 iOS 矩阵。
+4. 只有任务书 24 节全部完成、Git 与文档闭环后，才能更新为 `CLOSED / PASS`。

docs/报告/STEP-093_ContinuousRange运行态综合验收_Codex完成报告_v1.md

@@ -0,0 +1,127 @@
+# STEP-093 Continuous Range 运行态综合验收 Codex 完成报告 v1
+
+## 1. 交付结论
+
+**IMPLEMENTED / WAITING_RUNTIME_VALIDATION**
+
+Codex 已完成 STEP-093 所需的 Android 可重复运行态测试入口、最小 diagnostics 可观察性、Fast Path fail-closed 原因、跨平台字段透传与定向测试源码，并完成静态一致性审查。Android/iOS runtime 均未实际执行，所以没有任何运行态场景被标记为 PASS。
+
+## 2. Git 信息
+
+- Repository：`/Users/tei/dev/MapLibreParticleLab`
+- Branch：`particle/main`
+- Starting HEAD / starting remote：`8a5d88008c142e2a80e0ff602d228e0e67de2d83`
+- Implementation commit：`b3ec8edc87ece404b5f7b3706f5acf2a70de6862`（`feat: add STEP-093 runtime validation tooling`）
+- Documentation closeout：本报告所在 scoped commit，在报告写入后生成；准确 hash、push 和最终 remote 回读以最终交付消息为准。
+
+## 3. 修改文件
+
+Core/Renderer：
+
+- `include/mbgl/renderer/retained_underlay.hpp`
+- `src/mbgl/renderer/particle_fast_path.hpp`
+- `src/mbgl/renderer/renderer_impl.cpp/.hpp`
+- `src/mbgl/renderer/retained_underlay_cache.cpp/.hpp`
+- `src/mbgl/renderer/retained_underlay_runtime_state.hpp`
+- `test/renderer/retained_underlay_cache.test.cpp`
+
+Android：
+
+- `platform/android/MapLibreAndroid/src/cpp/native_map_view.cpp`
+- `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/RetainedUnderlayDiagnostics.java`
+- Test App Manifest、validation Activity 与 layout。
+
+iOS / RN：
+
+- `platform/ios/src/MLNMapView.h/.mm`
+- RN TypeScript types/spec、Android/iOS bridge、RN Test Host diagnostics display。
+
+文档：
+
+- STEP-093 任务书、Step 记录、Codex 完成报告；
+- `粒子开发记录.md` 追加记录。
+
+## 4. 测试入口
+
+Android：启动 `ParticleCoreLayerValidationActivity`，点击底部 `STEP 093`。菜单提供 A/B/C/D 四种 topology、E single-layer、mutation/cross-range、endpoint/visibility、invalid range、camera 与 Fast Path fail-closed；屏幕显示完整 pull diagnostics。
+
+iOS：正式 diagnostics API 与 RN bridge 字段已补齐，但本轮没有建立/运行 iOS 专用 STEP-093 validation UI。状态为 `WAITING_IOS_RUNTIME_VALIDATION`。
+
+完整 RDC 命令、逐项操作、判定标准和验收矩阵见同版本 Step 记录。
+
+## 5. Diagnostics
+
+新增并端到端暴露：
+
+- Range configured/valid/IDs/index/continuous bounds/fallback/last reason；
+- Bottom/Top present/cache state/build/reuse/invalidation/last reason；
+- Bottom/Top texture create/composite create/resource release；
+- Fast Path eligible/active/fallback reason/hit/miss/full CPU frame；
+- unsupported Continuous layer 的 `unsupported-continuous-layer` 原因。
+
+所有数据复用 STEP-092 map-scoped runtime state；没有增加 topology metadata 或 Z-order 真相源。counter 只代表事件累计，不代表 GPU memory bytes。
+
+## 6. 静态审查与实际测试结果
+
+实际执行并通过：
+
+- Native → Android/iOS → RN diagnostics 字段与 Android 39 项 ABI 索引静态核对；
+- 场景 layer 顺序、endpoint 与菜单接线静态审查；
+- `xmllint --noout` 检查 Test App Manifest/layout：PASS；
+- `git diff --check`：PASS。
+
+明确未执行：
+
+- CMake/Ninja/Xcode/Gradle 编译：NOT RUN；
+- Native directed tests：NOT RUN；
+- TypeScript/codegen/Android JNI 实际编译：NOT RUN；
+- APK build/install、ADB、模拟器/真机：NOT RUN；
+- Android runtime/视觉/长时间运行：`WAITING_ANDROID_RUNTIME_VALIDATION`；
+- iOS/Metal runtime/视觉/长时间运行：`WAITING_IOS_RUNTIME_VALIDATION`；
+- Jest：未新增、未执行。
+
+STEP-092 的 OpenGL/Metal build 与 29/29 tests 是起始历史证据，不是本轮新增代码的验证结果。
+
+## 7. Android runtime 结果
+
+**WAITING_ANDROID_RUNTIME_VALIDATION**
+
+没有执行 Android Gradle、APK、ADB、安装、启动或画面操作。A–E、Z-order、stable reuse、invalidation、mutation、endpoint、visibility、invalid、Fast Path 与 alpha 全部为 NOT RUN。
+
+## 8. iOS/Metal runtime 结果
+
+**WAITING_IOS_RUNTIME_VALIDATION**
+
+没有执行 iOS build/install/simulator/device/Metal runtime。Android 后续即使 PASS，也不能自动推导 iOS PASS；Metal Native build 历史结果也不能替代 runtime rendering。
+
+## 9. 架构边界
+
+本轮没有：
+
+- 修改 `[startLayerId,endLayerId]` 闭区间或内部半开区间数学；
+- 增加第二套 Bottom/Continuous/Top metadata；
+- 增加 anchor/marker、特殊 layer type、多 range 或频率分类；
+- 在 Renderer 硬编码业务 Layer ID；
+- 重构 RenderGraph/PBF/Particle 算法；
+- 把 visibility 变成 topology 规则；
+- 为 Fast Path 移动未知 Continuous layer。
+
+Style layer 顺序仍是唯一 Z-order 真相；App 只提供 endpoint ID，Native 解析 index。
+
+## 10. 风险与已知限制
+
+- 尚无任何运行态证据，不能确认真实 GPU 资源、画面合成或平台差异。
+- Android diagnostics 每秒 pull 一次但不逐秒 log；证据需手动 `READ DIAGNOSTICS`、截图或外部采样。
+- counter 在同一 Map 生命周期累计，RDC 应对比增量。
+- iOS 缺专用 STEP-093 validation 页面，需后续补齐实际可操作入口。
+- 本轮新增定向测试源码尚未编译/运行，任何预期 test 数都不能写成 PASS。
+
+## 11. 最终状态
+
+- 实现：完成；
+- 静态一致性审查：完成；
+- Android runtime：`WAITING_ANDROID_RUNTIME_VALIDATION`；
+- iOS/Metal runtime：`WAITING_IOS_RUNTIME_VALIDATION`；
+- 综合：**IMPLEMENTED / WAITING_RUNTIME_VALIDATION**。
+
+Git push、`HEAD == origin/particle/main` 与 clean worktree 由本报告之后的 scoped 文档提交和最终回读确认；这些 Git 结果不改变 runtime 尚未执行的事实。