From 0aab2bdc83f802669125342390dd81630c151db3 Mon Sep 17 00:00:00 2001
From: tei <tei@Mac-mini-tei.lan>
Date: Sat, 26 Sep 2026 09:15:31 +0900
Subject: [PATCH] docs(step097): record A1 test entries and RDC checks

---
 .../STEP-097_V13三轮问题去重与修复矩阵_v1.md        |  7 +++++++
 .../STEP-097_V13三轮审查问题合并修复_v1.md          |  5 +++++
 docs/60_测试/STEP-097_V13修复后集中验证清单_v1.md   | 13 +++++++++++++
 ...EP-097_V13三轮审查问题合并修复_Codex完成报告_v1.md |  6 ++++++
 粒子开发记录.md                                     |  4 ++++
 5 files changed, 35 insertions(+)

diff --git a/docs/30_设计/STEP-097_V13三轮问题去重与修复矩阵_v1.md b/docs/30_设计/STEP-097_V13三轮问题去重与修复矩阵_v1.md
index 5140cebab..4f690b800 100644
--- a/docs/30_设计/STEP-097_V13三轮问题去重与修复矩阵_v1.md
+++ b/docs/30_设计/STEP-097_V13三轮问题去重与修复矩阵_v1.md
@@ -49,3 +49,10 @@
 ## 2026-09-26 第 19 项 FZG1 设备辅助证据
 
 - 基于相同生产源码的 APK 在 FZG1-2 通过覆盖安装和设备 SHA-256 校验。两轮拓扑循环、重排、缓存 OFF/ON、缺失边界回退与恢复的 20 张截图及 UI 诊断已保存；有效场景的 B/T 粗粒度 textureCreate-resourceRelease 均为 0 或 1。此证据只支持 Android 运行态冒烟，不替代此前旧 revision 归属的 GTest 1/1 PASS，也不能证明 GPU 无泄漏。详见 `docs/报告/STEP-097_A1_第19项FZG1运行验证报告_v1.md`。A1 仍因 01/02/03 未闭合保持 PARTIAL。
+
+## 2026-09-26 A1 专用入口补充（待 RDC 执行）
+
+- 01：Android Validation Activity 的 STEP-093 菜单新增 STEP-097 same-source stencil 子菜单；`Step097StencilFixture` 用一个本地 GeoJSON source 与四个 fill layer 生成 R-R、R-C-R、C-R-R，菜单可重载与读 segment 诊断，既有 CACHE ON/OFF 可切换。RDC 仍需首帧/重建/reuse 的实际像素截图与 cache 计数；此处仅是可操作 fixture，未实测。
+- 02：`mtl_retained_attachments.test.cpp` 检查实际离屏资源的 color/depth/stencil 绑定、simulator/x86 combined attachment、无 depth/stencil 时跳过 clear；生产 `RenderPass` 共用的 clear 辅助函数可检查 load/clear/store。设备资源创建失败与 encoder 失败的运行注入仍待 RDC 验证。
+- 03：`render_orchestrator_error.test.cpp` 注入正/反向范围 visitor 异常，核对 observer/failed 标志，并用 cache 状态机核对失败后继续 Build、成功重试后 Reuse。真实 GPU 绘制故障与完整 renderer fallback 仍待 RDC 注入验证。
+- 01/02/03 均保持 `WAITING_RDC_BUILD_AND_RUNTIME`；源码入口准备不等于编译或运行 PASS。19 的既有实测状态不变。
diff --git a/docs/50_Step记录/STEP-097_V13三轮审查问题合并修复_v1.md b/docs/50_Step记录/STEP-097_V13三轮审查问题合并修复_v1.md
index 8fcea30d5..a92d2388b 100644
--- a/docs/50_Step记录/STEP-097_V13三轮审查问题合并修复_v1.md
+++ b/docs/50_Step记录/STEP-097_V13三轮审查问题合并修复_v1.md
@@ -31,3 +31,8 @@
 - Mac RDC 确认 APK 源码 `91c2491b0` 到当前 `237a3e660` 只改变文档，复用原 OpenGL x86_64 APK；在 FZG1-2（ADB `192.168.200.139:5555`）执行 `install -r` 得 `Success`，设备内 APK SHA-256 `8677197c5f83a22747cb51f0c261edffc5db4678fc25b3f366474f6ecb94dc99` 与源文件相同。
 - 两轮 A/B/C/D/E/A 拓扑循环及 TOP_REORDER、CROSS_CONTINUOUS、CACHE OFF/ON、缺失 START 后恢复完成：20 张 1920×1200 截图与 20 份 UI XML；18 个有效检查点 `valid=true/fallback=false`、预期无效检查点 fail-closed。B/T `textureCreate-resourceRelease` 在现有诊断的 19 个场景均为 0 或 1；实时日志无 FATAL/SIGSEGV/SIGABRT。
 - 设备辅助冒烟 **PASS**，前述 19 GTest **1/1 PASS**；没有 on-device GTest、逐 revision GPU 内部观测或显存泄漏证明。B/D `topPresent=true` 与视觉不一致的既有疑点仍待单独核查；01/02/03 专项测试未闭合，A1 整体继续 PARTIAL。报告：`docs/报告/STEP-097_A1_第19项FZG1运行验证报告_v1.md`。
+
+## 2026-09-26 Codex 继续 A1 测试入口
+
+- 新增 Android 同源同 tile 的 R-R/R-C-R/C-R-R 本地 fixture 与诊断菜单；新增 Metal 附件/clear GTest 源码；新增 LayerGroup 正反范围异常、observer 与 cache 失败后重试 GTest 源码。生产 Metal clear 逻辑抽成仅内部调用的辅助函数，使测试检查同一路径，不调整公开协议。
+- 本轮只做静态检查；构建、GTest、Jest、设备像素、Metal validation 均 **NOT RUN**。01/02/03 仍需 RDC 编译与设备验证；A1 保持 PARTIAL，A2/B/C 未启动。第 19 项原有 RDC 1/1 PASS 不受影响。
diff --git a/docs/60_测试/STEP-097_V13修复后集中验证清单_v1.md b/docs/60_测试/STEP-097_V13修复后集中验证清单_v1.md
index f15a3add6..0b0432b46 100644
--- a/docs/60_测试/STEP-097_V13修复后集中验证清单_v1.md
+++ b/docs/60_测试/STEP-097_V13修复后集中验证清单_v1.md
@@ -59,3 +59,16 @@ npm run typecheck
 
 - 经 RDC 在 FZG1-2 重新覆盖安装与 hash 复核，执行两轮 topology 轮换和资源诊断场景，20 个截图检查点；18 个有效配置均 valid=true/fallback=false，缺失 START fail-closed 后恢复。B/T 的粗粒度 create-release 差额 0/1，实时日志中无应用崩溃记录。详见 `docs/报告/STEP-097_A1_第19项FZG1运行验证报告_v1.md` 与 Mac 忽略目录 `artifacts/maplibre-particle/step097-fzg1-gtest19-device/`。
 - 这次是 Android Runtime 冒烟，前述第 19 项精确计数归属 GTest 由 Mac 原生测试覆盖；01 同 source/tile stencil、02 Metal、03 绘制异常注入仍缺，A1 整体 PARTIAL，A2/B/C 未实施。
+
+## 2026-09-26 A1 新入口执行清单（RDC，NOT RUN）
+
+通用 Core（当前 OpenGL 构建目录）：
+
+```sh
+cmake --build build-step088-opengl --target mbgl-test-runner -j3
+build-step088-opengl/mbgl-test-runner --gtest_filter='RenderOrchestratorError.*:RenderSegmentDiagnostics.OldCacheReleaseCannotChargeReplacementAtSameIndex'
+```
+
+预期异常 observer/failed 与 cache 不复用、重试后 Reuse；第 19 项保持 1/1 PASS。Metal GTest `MetalRetainedAttachments.*` 需由 RDC 使用可在 Mac 主机执行且配置 `MLN_WITH_METAL=ON` 的 `mbgl-test-runner` 构建目录执行；先检查所用目录的 CMakeCache、目标和 Metal device，再编译、执行并记录命令与日志。不能用 iOS 静态库构建替代主机 GTest。真机/simulator 的创建失败、encoder 失败与 API Validation 仍单独执行。
+
+Android 同源 stencil：以本提交标准脚本构建 Validation APK，打开 Particle Core Layer Validation → STEP-093 → STEP-097 SAME SOURCE STENCIL；依次选择 RR、RCR、CRR。每种拓扑在 CACHE ON 首帧、稳定 reuse、REBUILD CURRENT 后，再切 CACHE OFF 与 ON；保存每个检查点截图、`STEP097_STENCIL_PLAN/READY/DIAGNOSTICS` 日志及 `READ SNAPSHOT`。预期 `accepted=true`、`valid=true`、`fallback=false`，多个 retained 段分别 build/reuse，四层同一 source 的轮廓与填充在缓存切换后无残影/漏裁剪。再以相机移动强制重建；记录主目标与离屏结果。此清单是待执行判据，不能据此宣称像素 PASS。真正 GPU 绘制异常及下一帧 full fallback/recovery 需 RDC 专项注入；GTest 状态机不能代替它。
diff --git a/docs/报告/STEP-097_V13三轮审查问题合并修复_Codex完成报告_v1.md b/docs/报告/STEP-097_V13三轮审查问题合并修复_Codex完成报告_v1.md
index 54cfaf0d2..9b97415d2 100644
--- a/docs/报告/STEP-097_V13三轮审查问题合并修复_Codex完成报告_v1.md
+++ b/docs/报告/STEP-097_V13三轮审查问题合并修复_Codex完成报告_v1.md
@@ -49,3 +49,9 @@
 - A2 的 PLAY/endpoint/零量化/Mercator，B 的 JSON/坏帧/Android listener/Host 版本，C 的 diagnostics/ordinal/物化/资源优化均未实施。不得将本报告用于关闭这些问题。
 - Integration C-001/RFC-001 未更新；23 的 Compatibility/Status 及 24 的共享地理 Ocean Mask 需粒子负责人协调。此次未触发需要改变公共合同的实现，因此没有伪造“公共接口阻塞报告”或声称决定已被接受。
 - 建议继续 STEP-097 A1 的测试入口与独立审查，在完成当前检查点后再按原任务书进入 A2；不自行创建下一 Step。
+
+## 8. 2026-09-26 A1 测试入口续作（补充，历史结论保留）
+
+从 `be5b9080ed926a2632c5126c3522e242a2a85967` 的 clean `particle/main` 继续，只处理 A1 01/02/03 测试入口。新增 `Step097StencilFixture.kt` 与 Validation Activity 菜单，提供一个 GeoJSON source 上的 R-R/R-C-R/C-R-R；新增 `render_orchestrator_error.test.cpp` 正反范围异常/observer/cache 重试 GTest；新增 `mtl_retained_attachments.test.cpp` 离屏附件和 clear/load/store GTest。`render_pass.{hpp,cpp}` 将生产 clear 逻辑抽为内部辅助函数供测试共用；`test/CMakeLists.txt` 登记两个测试源。更新矩阵、Step、集中验证清单和开发记录。
+
+代码 scoped commit：`d0ced7235`。此续作的 `git diff --check` 静态检查无输出；构建、GTest、Jest、APK、Metal/iOS、设备截图及软件发布均 **NOT RUN**。RDC 已于本续作之前执行第 19 项 GTest 1/1 PASS 和 FZG1 设备辅助冒烟；不能把那些旧结果归到本次新测试源码。01/02/03 仍需 RDC 编译与 runtime 验证，特别是 Metal 失败注入和 GPU 层异常 fallback，A1 仍 PARTIAL；A2/B/C 未开始。文档 scoped commit 与远端状态以最终 Git 记录为准。
diff --git a/粒子开发记录.md b/粒子开发记录.md
index 43492cd82..aa4b49a57 100644
--- a/粒子开发记录.md
+++ b/粒子开发记录.md
@@ -964,3 +964,7 @@ Android V3-08 单次综合验收已完成并关闭。Native `13.4.1-particle.2`
 
 - 在 FZG1-2 重新安装源码等价的 OpenGL x86_64 APK，设备内 SHA-256 与构建产物相同。20 个截图与 UI XML、两轮 topology 轮换、缓存 OFF/ON、非法范围与恢复均已 ADB 实跑，粗粒度 B/T 资源创建减释放值均为 0 或 1；最终脚本 exit 0，实时日志无崩溃记录。
 - 设备报告：`docs/报告/STEP-097_A1_第19项FZG1运行验证报告_v1.md`；原生 GTest 1/1 与诊断组 5/5 已通过。B/D topPresent 诊断疑点待复核，A1 其余 01/02/03 仍未完成，未进入 A2/B/C 或发布。
+
+### 2026-09-26 STEP-097 A1 专项测试入口续作
+
+- Codex 增加本地同源 GeoJSON 的 R-R/R-C-R/C-R-R Android 操作入口、Metal 附件及 clear GTest、LayerGroup 异常与 cache 重试 GTest；仅静态检查，未运行构建、GTest、Jest 或设备。A1 仍待 RDC 验证，A2/B/C 不启动。