test: benchmark particle-only C FastPath CPU across R layouts

docs/50_Step记录/STEP-119_Symbol缓存实际实现_v1.md

@@ -64,3 +64,13 @@ Mac Metal原生CMake配置首次因PATH找不到cmake而失败，改用既有/us
 - Test App 增加三种 `RCRR_*_NO_TIDE` 场景，分别测试窄 C、宽 C 与错误动态 R；基于上述真实 Manifest 校准成 Native64 精确 R/C 区间，未修改正式 PBF/原场景/24 Gate。验证器精确验三段 R 边界；4项 Python unittest PASS、Style Manifest 静态索引核对 PASS、git diff --check PASS。
 - **尚未完成**：新 Kotlin Test App 的用户手工 APK 编译及三场景真机 90秒回归、图像目视、Camera/Source/Style/Tile/Annotation/Context 真机失效和恢复、STEP119 13项 GTest 真跑、Metal/iOS。Mac 原有 libuv 缺失限制保持，不擅自安装或升级工具链。STEP-119 **PARTIAL，不 CLOSED**。
 - 文档：`docs/60_测试/STEP-119_RCRR多配置验收矩阵_v1.md`、`docs/报告/STEP-119_RCRR多场景局限性_阶段验收_v1.md`。原始真机记录位于 ignored `artifacts/maplibre-particle/android-validation/step119-rcrr-observe-20261011_172720/partial_rcrr/`。
+
+## RDC STEP-119 粒子独占 C 与 CPU 效率收敛（2026-10-11 JST）
+
+- 用户确认：RCRR 正常运行的 `CONTINUOUS` 原则上**只含 `RasterParticleLayer`**，`WeatherColorLayer` 与其他非逐帧图层在 R；下一轮验收必须结合 CPU/帧、CPU/秒和实际 FPS，不只观察 FastDelta。
+- RDC 已同步 Integration `main`=`80667d6c343411d03a760425438e3d292f452118`；Particle 以 `1072816740fa69b7b23cd70602a402be19e5be2a` 为起点，现有 `particle/main` 与 STEP110/111 未跟踪文件不变。
+- Native 源码检查确认 `singleContinuousSegment(plan)` 是 Fast 准入条件，Fast 上传/绘制仅访问 C 范围，所有 R 需满足原24 Gate 与真实 Render/Symbol 缓存证书；WeatherColor 放 R 后是否能安全 Build/Reuse 尚待真机验证，不能提前 PASS。
+- 将 `RCRR_C_NARROW_NO_TIDE` 改为粒子独占 C[32,33)（WeatherColor 在 R[0,32)），新增 RCR 两 R、RCRRR 四 R，以及同 Style/Plan 关闭缓存的 Full 对照；保留旧 C 宽、粒子误入 R 两种负例和原63层 `PARTIAL_RCRR`。菜单 ID 改为100～102避免新增enum与操作冲突。
+- 新增严格 SHA/HEAD/设备锁的 CPU 采样器（App进程 utime+stime、6秒采样、35秒warmup、90秒观测）、A-B-A 对照比较器；对照同时列 CPU核秒/秒、CPU估算ms/完成帧、Native FPS、FastFraction≥95%、Build/Reuse/Invalidate。ADB实机只读确认 `CLK_TCK=100`，未以旧APK冒充新测试；未进行Android编译。
+- Python 非Jest结构+CPU测试 12项 PASS。正式测试矩阵 `docs/60_测试/STEP-119_RCRR多配置验收矩阵_v2.md`，本轮阶段报告 `docs/报告/STEP-119_粒子独占C与CPU效率_阶段验收_v1.md`。
+- **待验**：用户手工编译、安装新APK及Full-Fast-Full CPU实测，三种粒子独占C布局的Build/Reuse/Fast、视觉等价、变更后失效与恢复，13项GTest/Metal/iOS。STEP-119继续PARTIAL、不宣称CPU性能提升。

docs/60_测试/STEP-119_RCRR多配置验收矩阵_v2.md

@@ -0,0 +1,93 @@
+# STEP-119 RCRR 粒子独占 C 与 CPU 效率测试矩阵 v2
+
+日期：2026-10-11 JST。状态：**TEST SOURCE PREPARED / ANDROID NOT RUN / STEP-119 PARTIAL**。本 v2 取代 v1 对“窄 C 包含 WeatherColor+Particle”的测试建议；v1 保留为历史证据，不改写当时实机事实。
+
+## 一、目标与核心原则
+
+原则：**一个 Continuous 段只放 RasterParticleLayer**。WeatherColorLayer 不是逐帧运动图层，正常预测/颜色不变化期间可作为 R 候选，但数据提交、forecast time、色阶、Opacity、Style、Camera、Source/Tile/Atlas 等发生实际结果变化时必须安全撤销旧缓存并 Full，再重 Build/Reuse。这些具体动态失效条件仍需真机证明，不能因为分段配置正确而提前视为 PASS。
+
+Native 当前代码以 `singleContinuousSegment(plan)` 选择唯一 C；快路只在这个 C 范围执行 tweaker/upload/postRender，全部 R 需具备有效缓存、Revision 与 Symbol 结果证书；现有 24 Gate 不能放宽。因而“一个 C + 多个 R”符合技术实现边界，但不是任意 R 划分都必然适合 Fast。
+
+## 二、可比 Style 与真实图层顺序
+
+正式原 PBF Style 63 层、测试副本只排除无源 `tide-spots`，其余 62 层定义和次序完全保留，WeatherColor / Particle **按原插入点顺序**位于 `clip-outline` 之后，Native 预计总 64 层。基于设备导出与原正向成功相同指纹的 Style Manifest：
+
+- R 下部 [0,32)：含基础海图 [0,31)，并在索引31绘制 `rn-weather-color`；WeatherColor 留在 R 中。
+- Particle C 唯一图层 [32,33)：`rn-weather-particles`。
+- 上部 R [33,64)：各类静态海图、Symbol 和文字。按测试目的拆成 1/2/3 个 R 片段，不改实际图层顺序。
+
+**不要在 NavSea 产品中按本测试索引硬编码**；生产实际 Style 上应按图层 ID 验证真实边界。
+
+## 三、新一轮候选与负对照
+
+| 场景 | 预期分段 | 目的 |
+|---|---|---|
+| `RCRR_FULL_CONTROL_NO_TIDE` | R[0,32) C[32,33) R[33,63) R[63,64) | 与主 RCRR 相同 Style/Plan/Field，但关闭 Retained 缓存，取得 Full CPU 基线 |
+| `RCRR_C_NARROW_NO_TIDE` | R[0,32) C[32,33) R[33,63) R[63,64) | 主 RCRR 正向，仅粒子进入 C；3 个 R |
+| `RCR_PARTICLE_ONLY_NO_TIDE` | R[0,32) C[32,33) R[33,64) | 仅 2 个 R，测缓存片段数量收益/开销 |
+| `RCRRR_PARTICLE_ONLY_NO_TIDE` | R[0,32) C[32,33) R[33,38) R[38,63) R[63,64) | 4 个 R，测额外 RenderTarget/Composite/缓存生命周期成本 |
+| `RCRR_C_WIDE_NO_TIDE` | R[0,2) C[2,38) R[38,63) R[63,64) | 历史宽 C 错误配置，继续作为负对照，不作为性能候选 |
+| `RCRR_R_DYNAMIC_NO_TIDE` | R[0,33) C[33,38) R[38,63) R[63,64) | Particle 在 R 内的错误配置，必须 Fail-Closed |
+| 原 `PARTIAL_RCRR` | R[0,3) C[3,39) R[39,64) R[64,66) | **已经实测**：R0 缺 tide、R2/R3 各 Build1/Reuse536、FastDelta0/FullDelta596、decisionMismatch0 |
+
+旧正向 `STATIC_RC_NO_TIDE` 用于证明原有 FastPath（FastDelta1819），但天气层位置与粒子独占 C 的四个 A/B 场景不相同，**不能直接拿其 CPU 数据得出 RCRR 快慢结论**。
+
+## 四、CPU 指标及可比性
+
+使用 Android `/proc/<PID>/stat` 同一进程的 `utime+stime`（含 App 主线程与原生工作线程），以设备实际 `getconf CLK_TCK` 转换为 CPU 秒。记录该进程在观察期内消耗的累计 CPU 核秒。设备实测此接口可访问且 `CLK_TCK=100`，此预检不是新 APK 实测。
+
+每场景冷启动不同 PID，固定设备、x86_64 OpenGL APK、Style URL/PBF fingerprint、中心/zoom/rotation、1920×1200 设备条件、Weather 数据、forecast pause、1024 粒子和目标 FPS30。先 Warmup35 秒（等待载入/Placement/Cache settle），再观察至少 90 秒；每 6 秒读取一次 CPU 累计值，场景 Native summary 同样按 6 秒采样，最多允许 CPU/Native 边界时间差 9 秒，否则记测量不完整。
+
+同时必须记录：
+
+- `CPU 核秒/秒 = Δ(utime+stime)/CLK_TCK/观察秒数`；乘100为**相对单核的进程 CPU%**，多线程时可超过100%。
+- `Native FPS = (ΔFast+ΔFull)/Native摘要实际区间秒数`。
+- `估算 CPU ms/完成帧 = (CPU核秒/秒) × 1000 / Native FPS`；这是进程级近似值，不是 C++ 单次 render 函数的精确 CPU 耗时。
+- FastFraction、Full/Fast 增量、R Build/Reuse/Invalidate、24 Gate mismatch、源指纹、生命周期、帧率、帧率波动及进程 PID。
+- Full→Fast→Full（A-B-A）控制热机/网络缓存时序偏差；Full 前后的 CPU 核秒/秒漂移超过15%则需要复测，不凭一次高速帧数下性能结论。
+- 如果 Fast FPS 比 Full 高而 CPU/秒也提高，必须同时呈报“每帧成本下降”和“整机持续负载未必下降”。`CPUms/frame`改善不等于省电或 GPU time 已改善。
+
+## 五、顺序执行（用户手工编译一次，其余通过 RDC）
+
+必须先将本轮 Test App 修正提交/Push，**由用户手工使用当前 HEAD** 进行 Android APK 构建/安装；禁止用旧 `3d989a...` APK 冒充新场景。完成后 RDC 检查 build-info commit、SHA-256、设备 base.apk SHA 和目标 ABI。
+
+```bash
+cd /Users/tei/dev/MapLibreParticleLab
+./tools/particle_android_validation/build_validation_apk.sh
+adb -s 192.168.200.139:5555 install -r artifacts/maplibre-particle/android-validation/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk
+python3 -B tools/particle_android_validation/verify_step113_fast_path.py --serial 192.168.200.139:5555 --preflight-only
+
+# 每条命令执行完读取状态/result.json，再进入下一条；A-B-A:
+python3 -B tools/particle_android_validation/benchmark_step119_cpu.py --scenario RCRR_FULL_CONTROL_NO_TIDE --seconds 90 --warmup 35
+python3 -B tools/particle_android_validation/benchmark_step119_cpu.py --scenario RCRR_C_NARROW_NO_TIDE --seconds 90 --warmup 35
+python3 -B tools/particle_android_validation/benchmark_step119_cpu.py --scenario RCRR_FULL_CONTROL_NO_TIDE --seconds 90 --warmup 35
+python3 -B tools/particle_android_validation/benchmark_step119_cpu.py --scenario RCR_PARTICLE_ONLY_NO_TIDE --seconds 90 --warmup 35
+python3 -B tools/particle_android_validation/benchmark_step119_cpu.py --scenario RCRRR_PARTICLE_ONLY_NO_TIDE --seconds 90 --warmup 35
+```
+
+每次自动写入 Git 忽略目录：
+`artifacts/maplibre-particle/android-validation/step119-rcrr-cpu/<时间>-<场景>/result.json`；同目录保存日志和启动记录。脚本全程真实读取现有 Native 摘要，不改 Gate、不执行 Gradle。验证器 Fast 场景须稳定 Fast 比例≥95%，Full 对照须 FastDelta=0、FullDelta>0。未满足时标记 `MIXED_OR_NO_FAST` 或 `NO_EXPECTED_FRAMES`，**不把回退帧混入 Fast 成本声称速度提升**。
+
+在取得相应结果路径后使用：
+
+```bash
+python3 -B tools/particle_android_validation/compare_step119_cpu.py \
+  --full-before '<第1次Full/result.json>' \
+  --fast '<RCRR正向/result.json>' \
+  --full-after '<第2次Full/result.json>' \
+  --rcr '<RCR/result.json>' \
+  --rcrrr '<RCRRR/result.json>'
+```
+
+结果自动核验同 SHA/设备/Style 指纹、Native窗口、失配、Full控制与顺序漂移，输出 CPU per frame 节省比例、CPU 核秒/秒和 FPS 对照。若主 RCRR 尚不能稳定 Fast，不执行“有性能提升”的结论，只报告准确的 Gate 和成本。
+
+## 六、其他 STEP-119 待验
+
+相同视角的 Full/Fast 截图与 Symbol/文字/航标图层层序人工对比；Camera pan/zoom/rotate、Source/Style/Tile/Annotation/context/forecast 变更导致的证书失效和 Full → Build → Reuse 恢复；13 项新增 C++ GTest 真实运行和 macOS Metal/iOS 独立验证，均保持 NOT VERIFIED。Mac 现存 libuv CMake 配置缺口不授权升级第三方系统工具。全任务 STEP119 仍是 `PARTIAL`，本批仅准备测试能力，没有 Android 编译或新数据。
+
+## 七、保护
+
+- 不改变 Shared Core 公开 API、24 Gate、Renderer 行为、正式远端 PBF Style、发行 Tag/SOURCE_LOCK。
+- 原 `STATIC_RC` 63 层与历史 RCRR/负对照保留。
+- 不清理两份 STEP110/111 未跟踪文档。
+- 本阶段只把 Test App/CPU 工具/中文报告/Step/开发记录按 Git 任务范围提交到已有 `particle/main`，Push后回读远端 HEAD。

docs/报告/STEP-119_粒子独占C与CPU效率_阶段验收_v1.md

@@ -0,0 +1,51 @@
+# STEP-119 粒子独占 C 与 CPU 效率阶段验收报告 v1
+
+日期：2026-10-11（JST）。阶段结果：**SOURCE_READY / CPU_BENCH_READY / ANDROID_NEW_APK_NOT_RUN / STEP119_PARTIAL**。
+
+## 一、可行性结论
+
+用户确认 RCRR 的正常使用原则是 C 只放粒子，后续必须以实际 CPU 效率衡量 FastPath 而非单看 Fast 计数。源码检查确认：Native `tryRenderParticleFastFrame()` 使用 `singleContinuousSegment(plan)`；Fast 执行仅访问当前唯一 C 段的 LayerGroup，R 需全部缓存有效、无版本/内容/Placement/Annotation 等 24 Gate 安全问题。原则**有条件可行**，不等于 WeatherColor 放入 R 后已经获得 Fast 资格。
+
+**没有取得新 APK 的 Full/Fast CPU 性能对比数值**；本报告仅完成测试场景、测量器与验收准备。不能宣称 CPU 性能提升、GTest 或 iOS 完成。
+
+## 二、实际基线和执行状态
+
+- 设备 Mac.lan，通过 RDC 操作 `/Users/tei/dev/MapLibreParticleLab`；原有 `particle/main` 分支，起点 `1072816740fa69b7b23cd70602a402be19e5be2a`。
+- Integration `/Users/tei/dev/navsea-particle-integration` 已 `fetch main`、`merge --ff-only origin/main`，本地/远端一致 `80667d6c343411d03a760425438e3d292f452118`。已依据当前规则确认 Android/iOS/Shared Core 边界及项目 AGENTS。
+- 既有设备 APK 源 commit `3d989a00a822989339a6d7cb4d23acc04396670e`、SHA-256 `57d68800770d431a2ce9247406f636e7a01cc19fccaf4c59f5eb3a7c99128135`；**未重新编译或安装，不得对新场景使用旧 APK 验收**。
+- 之前的原 `PARTIAL_RCRR` 80秒真机负例保留：R0 因缺 tide Build=0/Reuse=0、R2/R3 各 Build=1/Reuse=536、FastDelta=0/FullDelta=596、decisionMismatch=0。旧 `STATIC_RC_NO_TIDE` 正向 Fast=1819，数据/图层顺序不同，不当作新 CPU 对照数据。
+
+## 三、新 Test App 结构
+
+不改生产 PBF、原 63 层场景或 Shared Core 的 24 Gate。Test App 在唯一无 tide 测试副本中得到 62 个基础层，插入的 WeatherColor 索引31、Particle 索引32。正常性能候选只允许 Particle C[32,33)：
+
+- `RCRR_C_NARROW_NO_TIDE`：R[0,32)、C[32,33)、R[33,63)、R[63,64)。
+- `RCR_PARTICLE_ONLY_NO_TIDE`：R[0,32)、C[32,33)、R[33,64)。
+- `RCRRR_PARTICLE_ONLY_NO_TIDE`：R[0,32)、C[32,33)、R[33,38)、R[38,63)、R[63,64)。
+- `RCRR_FULL_CONTROL_NO_TIDE`：与第一组同源、同图层、同 RCRR Plan，但调用 `setRetainedUnderlayEnabled(false)`，目的是同屏 Full CPU 基线；预期原生 Fast=0，实际须设备证明。
+
+老 `RCRR_C_WIDE_NO_TIDE`、`RCRR_R_DYNAMIC_NO_TIDE` 仍保留为错误划分安全负对照，不列为正常性能候选。原 `PARTIAL_RCRR` 和 `STATIC_RC` 及 v1 报告均保留历史事实。
+
+Test App 菜单的操作 ID 从10/11/12迁移到100/101/102，避免新增 enum 场景 10/11 与 Snapshot、Mutate 冲突；Full 对照按钮显示 CACHE OFF。Native 摘要新增 `sampleElapsedMs` 与 benchmark 档 6 秒报告周期，仅用于关联 CPU 采样，不修改 Gate 或 Render 路径。
+
+## 四、CPU 真实测量方案
+
+新增 `tools/particle_android_validation/benchmark_step119_cpu.py`：在用户提供相同源码构建并正确安装的 APK 上，调用既有严格 `inspect()` 锁 commit、SHA、ABI/安装设备；启动目标 Activity，Warmup35秒，稳定观察90秒，按6秒读取 Android `/proc/PID/stat` 的 utime+stime 和 `/proc/uptime`。设备访问能力已只读检查：真实 `CLK_TCK=100`，`/proc/<PID>/stat` 可读取，但**CPU Benchmark 本身尚未对新 APK 运行**。
+
+输出 `CPU Core Seconds`、`CPU Core Equivalent`（CPU%相对单核）、`Native FPS`、Fast/Full增量、FastFraction、估算 `CPU ms/完成帧` 和分段 Build/Reuse/Invalidation。CPU 为**整个 App 进程**的时间，并非 C++ renderer 独占的精准逐帧计时。Fast 稳定区间要求 FastFraction≥95%，Full 对照要求 Full>0、Fast=0，且 24 Gate mismatch=0；失败按原始事实保存 JSON 并返回非零。
+
+新增 `tools/particle_android_validation/compare_step119_cpu.py`：读取 Full→Fast→Full A-B-A 实际结果与 RCR/RCRRR 结果，校验同设备/APK SHA/Style 指纹、场景生命周期和 CPU/Native 边界，将 Full 两轮作为 CPU/帧基线，计算各 Fast 组 CPU/帧变化比例及 CPU/秒和 FPS。若 Full 两端 CPU/秒漂移大于15%，结果标记需复测。此比较用于检验 CPU FastPath 收益，**不代表 GPU 时间、能耗或省电已经证明**；FPS 不同时必须同时呈报 CPU每秒与CPU每帧。
+
+## 五、当前已执行验证与未执行项
+
+- Python 非 Jest 结构/CPU 算法测试：12 项 PASS，运行退出码 0；涵盖4类有效性能结构与2类保守负例、错误分段/缺源/Annotation失败、原 STATIC_RC / 原 PBF63 边界、proc/stat解析与 CPU/fps 归一计算。
+- CPU 工具 CLI 参数校验/AST：PASS；Android ADB 读设备时钟率：`100`（只读）。
+- `git diff --check`：本阶段代码检查通过，最终 commit/push 信息以后续 RDC 实际状态补充。
+- 新 Kotlin Test App 尚未经用户手工 Gradle 编译/打包；四种 CPU 场景 Native 真实 Full/Fast、CPU时间、帧率与图像仍为 **NOT VERIFIED**。
+- Source/Style/Tile/Camera/Annotation 等失效及恢复、13项 STEP119 Native GTest、Metal/iOS 独立验证均未完成。Mac libuv 既有缺失不擅自装依赖/升级系统工具。
+
+## 六、工程风险与下一步
+
+只有在 C[32,33) 实际得到 Fast、视觉匹配及 CPU/帧或 CPU/秒的受控改善后，才考虑产品采用。多 R 可能提高 FBO/Composite 成本；WeatherColor 放 R 可能因当前 Core 类型/动态数据结果证书被保守拒绝；如果 Main CPU 指标改善但持续功耗/热度上升，也不等于总体有益。
+
+详见 `docs/60_测试/STEP-119_RCRR多配置验收矩阵_v2.md`。本报告是阶段验收，不进入发行、不创建 Tag/SOURCE_LOCK，也不覆盖上轮或未跟踪的 STEP110/111。Git 以 RDC 实际新 commit/push/远端 SHA 返回为准。