V26 Metal 混合 Segment 视觉缺陷——保留 Retained 修复调查报告 v3

日期：2026-10-13 状态：第二版 Stencil 状态修正 F 真机 FAIL / ABORTED；图标仍异常放大，且用户报告地图无法移动。已保存证据、恢复共用 JS E，并归档/撤销失败的源码补丁。不可发布 V27。正式发行：NOT RELEASED，不得标记 V27 PASS；保留 Retained 构建/复用/合成 上版：V26_Metal混合Segment视觉错误_Retained保留修复调查报告_v2.md（CommandBuffer 候选 F 真机失败）

1. 已证实事实

Pleiades iPad mini 5；Native 旧 V26 F，及第一版 CommandBuffer 候选 F，均真机 FAIL：背景 Retained 真实 Build/Reuse/Composite，但光弧或图标被放大、航向线消失、天气开关异常。旧版本 E（全 Continuous）多次由用户确认正常。
第一次候选 Native F 快照保留于 /tmp/navsea-v27-retained-ipad-stage/F-1851/start.json 与 end.json，其中 Retained R0 [0,1)、C1 [1,118)、build=13、reuse=1069、actualExecution=composite、valid=true、fallback=false。
不能据此认定 CommandBuffer 是根因。原候选 MapLibre.dynamic.xcframework.zip SHA-256 为 b89bc06bf03eba20a5790da21215fe7e167da20b3fdfa6a34782420bd503a354；旧候选补丁备份在 /tmp/navsea-v27-retained-ipad-stage/patches/V27_candidate1_commandbuffer_plus_current_context.patch。

2. 本次单变量改动

恢复前一版 CommandBuffer 改动的七个源码/测试文件，原 Candidate 1 不再参与当前源码编译。仅两个文件相对 particle/main HEAD b0f34cc9a2 发生功能代码修改：

src/mln/mtl/context.cpp：Context::renderTileClippingMasks 的 Metal Stencil ID 设置改走 mtlRenderPass.setStencilReference(...)，不再绕过 RenderPass 缓存直接调用 encoder->setStencilReferenceValue。
src/mln/mtl/tile_layer_group.cpp：3D Stencil Reference 也走 RenderPass 缓存，删除不再使用的局部 encoder 引用。

代码已确认存在 Metal 原先绕过 RenderPass 状态缓存的路径；其与 F 画面错误的因果关系尚待真机结果。没有变更 Retained Cache 或共享 RN API，未禁用 Retained，未引入 JS Android/iOS 平台分流。

3. 新 Native 制品与安装

Mac /Users/tei/dev/MapLibreParticleLab，bazel build -c opt --//:renderer=metal //platform/ios:MapLibre.dynamic，exit 0，约 49 秒；git diff --check PASS。
新 Metal ZIP SHA-256：5a8bef4e8419ae2b8c5bf22253361d40a4ed7ffd7c156ea73d5df8eae72b3393。
独立保留于 /tmp/navsea-v27-retained-ipad-stage/candidate2_stencil/MapLibre.dynamic.xcframework.zip；最小源码 patch 同目录 candidate2_stencil_only.patch。
RDC Mac 使用现有 scripts/ios-install-test-device.sh 的 scripts/pass.txt 所对应 Keychain 与签名身份，在暂存 App 替换完整 MapLibre.framework，重新签名并严格验证；覆盖安装 Pleiades com.navsea.app 成功，devicectl process launch 成功。
无卸载、无清数据、无 SwiftPM V26 正式仓库/Package 更改、无发布、无 Git Commit/Tag。
安装后 E Native 快照：/tmp/navsea-v27-retained-ipad-stage/candidate2_stencil/E-preF/start.json，时间 2026-10-13T12:00:50Z，valid=true，0 Retained / 1 Continuous、[0,118) Live。仅验证了运行时模式，并非用户视觉结果。

4. 第二版 F 真机结果（失败，已停止测试）

用户于 2026-10-13 21:09～21:10 JST 确认 F 仍有大图标，没有改进，并补充报告“也不移动了”。目前“无法移动”是手势没有作用，还是相机已变但视觉没有更新，仍需通过输入事件/相机指标判定，不得臆测。
从 Pleiades 实际取得 Library/Caches/navsea-render-segment-start.json 与 end.json，已保存在 /tmp/navsea-v27-retained-ipad-stage/candidate2_stencil/F-failed-20261013-2110/。其中 capturedAt 2026-10-13T12:10:12Z、generation=4、mapReactTag=804、styleLayerCount=118、valid=true/fallback=false；R0 [0,1) background，actualExecution=composite、build=14、reuse=6076、invalidation=14；C1 [1,118) actualExecution=live；fullCpuFrame=6231。帧计数不等于相机更新证明。
用户报告画面失败，Native 配置/执行链未发生全 Live 回退，因此第二版 Stencil 修正 FAIL。没有进入 RC，没有发布 V27。
Windows Metro 当前统一 Debug 开关已经恢复为 E_CONTINUOUS_ONLY，iOS Bundle HTTP 200，Android 同一 JS 源配置；用户需冷启动 iPad 才能加载 E。用户 2026-10-13 21:18 JST 已再次确认本次切回 E 后正常，包括地图移动；因此 E 恢复 PASS。
失败的第二版源码 diff 另存 /tmp/navsea-v27-retained-ipad-stage/candidate2_stencil/candidate2_failed_stencil_source.patch。已只针对两个改动的 Metal 源文件 git restore 回 particle/main HEAD；无其他功能文件变更，报告保留，iPad 上仍是已安装的 Candidate 2 二进制（仅 JS 回 E），不等于已更换 Native。
下一轮调查把相机/手势事件、Native 相机矩阵变化、Retained 的 camera-or-boundary invalidation、主画面真实绘制与 GPU 合成可视化分开验证，再制定单一变量修复；禁止无验证继续叠加补丁。

5. 范围与发布约束

仅本地候选，不代表 V27 已发行。
不接受关闭 Retained、全 Continuous 降级或 JS 平台分流作为最终修复。
若 F 依旧失败，下一轮应进一步检查 Retained Composite 顶点/纹理与 Metal Encoder 状态、Stencil/Depth、主画面 RenderPass，并用证据区分构建与合成副作用。

5.5 KiB Raw Blame History Unescape Escape