docs: record STEP-111 per-R placement feasibility partial

docs/20_调查/STEP-111_R段Placement结果等价与独立刷新可行性调查_v1.md

@@ -0,0 +1,56 @@
+# STEP-111：R 段 Placement 结果等价与独立刷新可行性调查 v1
+
+**日期：2026-10-10｜状态：PARTIAL（初步可行性判断，不是 Codex 完整设计或运行验收）**
+
+## 1. 范围及真实证据
+- Mac `/Users/tei/dev/MapLibreParticleLab`，`particle/main`；调查时 HEAD `7ec9ac8c1635c7a3b607abc2ed4be4fd764e7b6d`。Integration `main` 与 `origin/main` 一致于 `80667d6c343411d03a760425438e3d292f452118`。
+- 使用可见 GNU Screen `7445.codex`，真实界面显示 **GPT-6 Astra high**；Codex 进行两轮源码浏览/调查后长期无新事件，第二轮缩窄至直接写报告仍无输出，随后终止会话；未生成任何要求的 STEP-111 正式调查文档。此文件由 GPT/RDC 对当下代码和既有 STEP-110 证据重新核对后撰写，**不冒称 Codex 已完成 STEP-111**。
+- 未改 C++/Swift/Kotlin/JS/测试代码，未编译、未测试、未跑设备；本文件是方案评估，不是新增 Native 功能。
+
+## 2. 现有实现的确定事实（RDC 逐行核验）
+1. `src/mln/renderer/render_orchestrator.cpp:775-810`：Continuous 渲染使用 `placementController.placementIsRecent` 得到全局 `placementChanged`，随后视情况新建 Placement、调用 `placeLayers(layersNeedPlacement)` 并更新 Controller；`symbolFadeChange` 和过渡也作为全局状态处理。这里的 `placementChanged` 表示重算触发，**不证明每一个 R 的最终输出改变**。
+2. `include/mln/renderer/render_segment.hpp:78-90`：R 中只要出现 `layerType == "symbol"` 就被标为 placementCapable；Gate 对这种 R 要求全局 `!placementChanged && symbolFadeChange==0 && !placementTransitionActive`。没有 per-R 最终 Symbol 结果比较。
+3. `src/mln/renderer/renderer_impl.cpp:638-686`：对每个 RETAINED 段已经独立计算内容 fingerprint、Source ready/stable/revision、segmentStable、placementCapable，并在 `cache->evaluate` 决定复用、构建或 fallback；`static-placement` 是 Gate 未通过时的失败原因。逐 R Cache 管理已存在，**缺的是含 Symbol 段的逐段结果等价证据**。
+4. STEP-110 已核对的 `src/mln/text/placement.cpp` CollisionGroups/opacity/fade 说明：Collision Domain 与 RenderSegment 边界不等价；跨 Source 碰撞开关、同 Source 跨段、text/icon Fade 等可能让别的段影响本段可见结果。STEP-102/106 仅能证明 placement-free 的安全复用，不直接证明含 Symbol R 的安全复用。
+
+## 3. 推荐的目标语义（待设计与实测）
+`R0-C0-R1-C1-R2-C2` 六段按图层顺序合成；若 R1 内 Symbol 的**最终绘制结果**与其上次成功 Build 的缓存版本等价，允许 R1 复用，而不因某个 R0/R2/C 段触发 global placementChanged 自动 Fallback。跨段碰撞真的改变 R1 Symbol 的显隐、锚点、位置、opacity 或其它绘制依赖时，R1 必须失效。
+
+**不等于**每个 R 拥有独立 Collision Index。第一阶段可以仍全图计算 Placement，之后对不同 R 的已完成结果分别判等，再控制各段纹理的 Build/Reuse；这只争取避免不必要的段重绘，不能自动省略全局 prepare/Placement、非 R 的 C 绘制或保证 Fast Path hit。
+
+### 待验证的候选签名（不是已实现结构）
+建议研究在 `placeLayers` 完毕之后、`renderer_impl.cpp:638-686` Cache 决定之前提供 `per-R PlacementResultRevision` 或严格结果比较，关联已缓存 Build 版本，而不只与上一帧比较。候选依赖包括：
+- 按层序可稳定归属到 R 的 text/icon 实例、Tile/Bucket/Source 世代与 placement/collision 可见性、锚点、偏移、实际绘制位置；
+- Fade/Opacity/Transition 的可绘制值或明确的“稳定可复用”条件；纹理/glyph/sprite/atlas 的有效世代；
+- Camera/projection/zoom/viewport/pixelRatio、Style 顺序与合成边界；这些可优先复用已有 Camera/Content/Resource Gate，不应盲目重复扫描；
+- 新旧结果缺失、ID 不稳定、资源生命周期不可证明、哈希碰撞或任意未知场景均 **fail-closed**。
+
+上述字段只是**候选调查清单**，现有代码尚未证明可以低开销取得稳定、完整的 per-R 视觉语义。简单“Symbol ID/位置没变”或单一 64-bit hash 相等都不足以证明最终像素安全等价。
+
+## 4. RCRCRC 反事实场景
+| 情况 | 希望达到的复用决策 | 当前证据边界 |
+|---|---|---|
+| C1 只有粒子/颜色更新，R0/R1/R2 视觉稳定 | R0/R1/R2 独立复用 | 当前 global Gate 可能挡住含 Symbol R；仍须取得最终结果不变证据 |
+| C1 Symbol 改变，仅使 R2 发生碰撞结果变化 | R2 重建；R0/R1 如证实未变可复用 | 事件来源不能替代逐 R 结果比较 |
+| C1 Symbol 改变，同时影响 R0 与 R1 | R0/R1 失效、不得复用旧遮挡 | 必须保留全局 Collision 正确性 |
+| R1 自身 Layer/Tile/Style 更改，R0/R2 不变 | R1 失效；其余分别判等 | 现有内容 revision 可局部区分，但 Symbol 仍有全局 Gate |
+| Camera/Zoom/Pitch、Annotation、Fade、Glyph 变化 | 受影响 R 失效；未知则全体安全回退 | 不得将各段等同独立碰撞域；须验证跨平台一致性 |
+
+## 5. 难度分级（GPT/RDC 初估，尚未经 Codex 最终复核）
+| 阶段 | 复杂度 1–5 | 输出与主要难点 |
+|---|---:|---|
+| A：只读设计 + 逐 R trace/reason | 2–3 | 诊断 event 来源与 per-R Cache 状态，不改变业务 |
+| B：Native per-R result fingerprint 的 shadow compare | 3 | 找齐最终 Placement 数据、稳定身份/世代、控制逐帧遍历成本；**只记录，不参与复用** |
+| C：用已验证等价结果替换含 Symbol R 的 global-only Gate | 4 | 与 Cache 生命周期/资源/层序/Fade 联动，必须零 false-reuse；Android OpenGL、iOS Metal 对照 |
+| D：真正把全图 Placement/Collision 改成分段增量计算 | 5 | 全局碰撞依赖与跨 Tile/Source 的更新传播，风险明显更高、不能简单按 R 切分 |
+
+工程周期目前**无法从静态代码得到可信承诺**。复杂度 3 表示可做有限验证原型；4 代表需多阶段视觉/性能门槛；5 代表核心架构重构，不能与缓存命中优化混为一谈。
+
+## 6. 后续建议及未完成项
+1. 下一次正式任务先补只读源码数据所有权审计：Placement 完成后在哪个对象/时间点能列出每 R 所属 symbol 的最终 placed/opacity，并确定 crossTileID、tile/glyph 资源失效契约。输出字段级“已有/缺失/必须新增”清单。
+2. 再授权仅做 **shadow-mode** 内部诊断：per-R `resultComparable/resultChanged/unknown` 与 global Gate 同步采样，**不改变 Gate**；采样成本与候选数量需量化，防止 O(N) 比较本身抵消收益。
+3. 真实 RCRCRC（每个 R 含 Symbol）覆盖同 Source/跨 Source 碰撞开关、Annotation、Fade、Camera、Tile、Layer 顺序及前后多帧；全缓存 ON/OFF 视觉一致，**false reuse 必须为零**。
+4. 通过后才另行授权 C 阶段优化，先看独立 R build/reuse/fallback 与 CPU/帧变化；Fast Path 对单 C、pending、non-particle repaint 等另有门槛，不作为此优化的当然收益。
+5. 若出现跨平台公共语义/公共接口改变，回 Integration RFC/ADR 处理；本阶段不得更改现有 API/Contract。
+
+**未完成：** Codex 未形成字段级可行性结论；无 per-R Placement 结果签名、运行对照、性能证据或真实 Native 修复。不可标“调查 PASS”或“独立刷新已实现”。

docs/50_Step记录/STEP-111_R段Placement结果等价调查_v1.md

@@ -0,0 +1,21 @@
+# STEP-111 R 段 Placement 结果等价调查 v1
+
+- 日期：2026-10-10
+- 状态：**PARTIAL；调查未完成，Native 未实施**
+- 仓库：Mac `/Users/tei/dev/MapLibreParticleLab`，`particle/main`
+- 任务起点 HEAD：`7ec9ac8c1635c7a3b607abc2ed4be4fd764e7b6d`
+- 模型：Codex CLI 0.161.0，实际可见 TUI `GPT-6 Astra high`。
+- 执行：Codex 两轮源码探索后停止新增事件；尝试同会话缩窄为直接出报告，仍无报告生成。会话已人工中断并退出，未取得可靠退出码，不能认定正常完成。
+- GPT/RDC 随后只读核验 `render_segment.hpp:85-90`、`render_orchestrator.cpp:775-810`、`renderer_impl.cpp:638-686` 与 STEP-110，并编写 PARTIAL 评估；不是 Codex 完整调查报告。
+
+## 有证据的阶段结论
+- Retained Cache 已逐 R 管理，但含 Symbol 的 R 使用全局 Placement/Fade Gate，未依据该 R 的最终 Symbol 结果判等。
+- 可以把“全图 Placement 后按 R 判断纹理是否复用”作为候选优化路线，不把 Segment 当作独立 Collision Domain。
+- 难度初估：诊断 2–3/5、shadow 比较 3/5、安全独立 Reuse 4/5、分段增量 Collision/Placement 5/5；数字仅为工程评估，未通过真实实现检验。
+
+## 未完成、禁止夸大
+- 未形成稳定/完整的 per-R 视觉等价签名设计或生命周期证明；无新 Native 插桩、运行数据、编译、测试、Jest 或设备 A/B。
+- Codex 未生成预定三份交付文件；由 GPT/RDC 记录 PARTIAL，不写“Codex PASS”。
+- 原有未跟踪 STEP-110 任务书和本次 STEP-111 任务书均保留，不参与文档 Git 提交。
+- 主报告：`docs/20_调查/STEP-111_R段Placement结果等价与独立刷新可行性调查_v1.md`。
+- 后续先审查稳定 ID、Fade 和 per-R 最终数据所有权，再考虑 shadow-mode 与缓存 Gate 改造。

docs/报告/STEP-111_R段Placement结果等价调查_Codex完成报告_v1.md

@@ -0,0 +1,44 @@
+# STEP-111 R 段 Placement 结果等价调查 — Codex 执行状态 / RDC 阶段报告 v1
+
+**2026-10-10｜PARTIAL，Codex 未完成任务，不是 Native 优化通过报告。**
+
+## 1. 执行来源
+- 设备：Mac.lan；仓库 `/Users/tei/dev/MapLibreParticleLab`；`particle/main`；起点 HEAD `7ec9ac8c1635c7a3b607abc2ed4be4fd764e7b6d`。
+- Integration `/Users/tei/dev/navsea-particle-integration` 同步核对：本地 `main` 与 `origin/main` 相同，HEAD `80667d6c343411d03a760425438e3d292f452118`。
+- Codex CLI `0.161.0`，用户可见 GNU Screen `20825.7445.codex` 新窗口 STEP111；启动参数 `-m gpt-6-astra -c model_reasoning_effort=high -s workspace-write -a never`；屏幕实际显示 `GPT-6 Astra high`。
+- 原始会话：`~/.codex/sessions/2026/10/10/rollout-2026-10-10T16-51-37-01a124cb-c9ae-75e3-afd8-c15a75815d1b.jsonl`（本机取证路径）；脚本记录 `/tmp/particle_step111_codex_tui.log`。
+- 17:00 前原始会话源码探索多次执行；最后连续完整事件停留于约 16:54:51；因长时间无新增结果，RDC 发送 ESC 中断并在同会话要求直接落盘报告。再次长时间没有输出，随后中断并退出 TUI。启动脚本没有可靠写出退出码；进程已消失，**不可声称自然成功退出**。
+
+## 2. 任务验收矩阵
+| 任务 | 判定 |
+|---|---|
+| STEP-111 只读任务书创建 | 已完成，原样保留未跟踪 |
+| Integration main/规则核验 | 已完成（RDC） |
+| GPT-6 Astra High 实际启动 | 已完成（TUI 确认） |
+| Codex 源码搜索与浏览 | 有部分实际轨迹；非完整调查交付 |
+| Codex 字段级 per-R Result Signature 论证 | **未完成** |
+| Codex RCRCRC 完整场景、A-D 难度证明 | **未完成** |
+| Codex 生成主报告、Step、完成报告、记录 | **未完成** |
+| GPT/RDC 独立核对当前 Gate/Cache 调用点 | 已完成 |
+| GPT/RDC 编写初步难度与后续候选方案 | 已完成，标为 PARTIAL |
+| Native 功能改动或设备性能改善 | **未执行/未验证** |
+| 构建、测试、Jest、Gradle、ADB、Bazel、CMake | **未执行** |
+| Source Lock、发行 Tag、正式交付 | **未执行** |
+
+## 3. 实际修改范围
+- **没有改动 Native/JS/Swift/Kotlin/Tests**。
+- GPT/RDC 依据 STEP-110 与本次只读核对，补充以下 PARTIAL 文档：
+  1. `docs/20_调查/STEP-111_R段Placement结果等价与独立刷新可行性调查_v1.md`
+  2. `docs/50_Step记录/STEP-111_R段Placement结果等价调查_v1.md`
+  3. `docs/报告/STEP-111_R段Placement结果等价调查_Codex完成报告_v1.md`
+  4. `粒子开发记录.md` 追加 STEP-111。
+- 不得把这三份文档称为 Codex 独立完成；实际作者为 GPT/RDC。
+- 已存在未跟踪 `STEP-110` 任务书及本次新建未跟踪 `STEP-111` 任务书不提交、不清理。
+
+## 4. 已核验的源码与部分结论
+`include/mln/renderer/render_segment.hpp:85-90` 含 Symbol R 使用全局 placementChanged/symbolFadeChange/placementTransitionActive Gate。源代码中 `src/mln/renderer/render_orchestrator.cpp:792-809` 是全局 Placement 更新；`src/mln/renderer/renderer_impl.cpp:638-686` 已有逐 Retained Segment Cache 的 fingerprint/source state/evaluate。由此可以合理提出“保留全局 Placement、后续逐 R 判断已完成结果是否等价”的设计调查方向，**但没有完成可以用于修改 Gate 的安全判据证明**。
+
+## 5. Git 与报告状态
+- 代码和正式发行状态未变化；本次只是调查阶段 PARTIAL。
+- Codex 不承担本轮 Git 收尾；RDC 后续 Git 实际 Commit/Push/远端 HEAD 以独立工具返回为准。当前撰写时**尚未验证提交与远端**，不得把文档写入视为 Push PASS。
+- 后续可以在可用模型/运行环境中重新开展限界的结果数据所有权审计和 shadow-mode 方案设计，但**不能将本轮 PARTIAL 当成允许直接修改 Gate 的授权**。