docs: audit upstream MapLibre Native upgrade compatibility

docs/40_任务/UPSTREAM-001_MapLibre官方升级兼容性架构审计_Codex任务_v1.md

@@ -0,0 +1,39 @@
+# UPSTREAM-001 MapLibre 官方升级兼容性架构审计（只读代码，2026-10-09）
+
+## 授权与模式
+- 用户明确授权 Mac 使用 **GPT-6 Astra High** 做以未来跟随官方升级为目的的架构审计。
+- Codex 执行器须显式指定 `gpt-6-astra`、`model_reasoning_effort=high`，实际配置从 Codex JSONL 开始事件核实；如不一致，报告 BLOCKED，不能伪称。
+- 只读源代码。仅允许生成/修改本任务书和 `docs/报告/UPSTREAM-001_MapLibre官方升级兼容性架构审计_Codex完成报告_v1.md`；禁止改 C++、RN、Java、ObjC、构建脚本和依赖。
+- 仓库为独立干净审计 worktree，基于正式远端 `origin/particle/main` 的 `.21`，不可操作其他已有脏工作树。无需构建 APK、AAR、Xcode，无需 Jest。不能伪造运行验收。
+- 不修改 Integration COORD/RFC/ADR/Contract；如建议跨平台契约变化仅列出待协调项。
+
+## 权威输入
+- `/root/sourceserver/navsea-particle-integration` 为 Linux Integration；已由 RDC 同步到 `80667d6c343411d03a760425438e3d292f452118`。Mac 上可读取到的合同以已存在文件为准，不要猜测。
+- 阅读本仓库 `AGENTS.md`、`PARTICLE_BASELINE.md`、`docs/10_架构/20_粒子系统总体架构设计_v1.md`、`docs/00_项目总则/粒子系统项目规则与设计决策_v1.md`、`docs/30_设计/STEP-094_通用RenderSegment模型与Style分类Diagnostics设计_v1.md` 和相关 STEP-098/099/100/101/102/103 实现记录。
+- 自定义现行发布：`630ec657687bad4200c059bbccbb950d9c6f7ce9` (`13.4.1-particle.21`)。
+- 初始 upstream Core：`18545ca10d296704b2cba675b182ff2c8da24588` (见 `PARTICLE_BASELINE.md`)；验证实际 merge-base。
+- 官方 MapLibre Native Android `android-v13.6.1` peeled commit `c7506d6aff3800e946f89e1a51432fc22d1a6534`。
+- 官方 MapLibre Native iOS `ios-v6.31.0` peeled commit `01791ad02c1bfe3b22c42a97619b972aba962f82`。
+- 官方 MapLibre React Native `v11.5.0`；现有 Particle RN `11.3.6` peer/dev 锁及 Android AAR replacement、iOS SPM/Podspec 需独立审计。不能混淆 RN 11.5.0 与 Native 13.6.1。
+
+## 必查问题
+1. 原始目标“官方可持续升级、自研粒子和 RenderSegment 可重复移植”离目前真实代码有多远？用逐文件证据分类：**纯新增扩展**、**不可避免的官方接入 hook**、**可外提的官方修改**、**深耦合必须重构**，另列构建/平台桥接。不要用“62 个修改文件 = 62 个冲突”。
+2. 在 `git diff` 与 `git merge-tree` dry-run 基础上，对 Android 13.6.1 和 iOS 6.31.0 分别量化冲突文件与交叉文件、可自动合并与疑似行为冲突。绝不可真实 merge/rebase 任何生产分支。优先核对 `renderer_impl.cpp`、`render_orchestrator.cpp`、`render_target.cpp`、`render_layer.hpp`、`render_source.cpp`、`paint_parameters.cpp`、RenderSegment/Retained cache、GPU backend、Style/Layer factory、JNI/Android/iOS 对接代码。
+3. 以源代码里的函数/类名证明现有 Particle Core/Field/WeatherColorLayer/GPU 模块是否独立；列出真正只需 hook 的文件和未来易碎调用。用修复方案区分 thin hook、抽象接口、适配器、source-to-segment dependency、offscreen target/placement 等，不得建议一刀切“重写”。
+4. RenderSegment 与 Particle Fast Path 的数据依赖、分层失效、Style 顺序、Opaque/Translucent、Placement、Context loss、资源所有权、Top/Bottom Retained、multi-segment 未来兼容约束。区分已实现功能和目前 fail-closed 限制。
+5. 核查 `packages/maplibre-particle-rn` 的 `package.json`、`app.plugin.js`、`MapLibreParticleRN.podspec`、Native API 等；给出 RN 11.5.0 受官方 Android 13.6.1/iOS 6.31.0 依赖推动的单 SDK 依赖收敛风险、代码适配点、功能验证清单。
+6. 准备升级顺序和可回滚 Gate：什么必须先重构、什么可以直接合并、哪些要不同平台分别验证，什么情况下必须停止并回 Integration 新 RFC/Contract。建议未来 upstream 版本跟踪工作流和“patch footprint budget”；明确对长期维护代价影响。
+7. 逐项目给出 P0/P1/P2 表，包含路径、当前耦合证据、方案、风险、工作量相对估计、验收标准、Android/iOS影响；结论为 GO / CONDITIONAL GO / BLOCKED，不得把未编译当 PASS。
+
+## 调查方法与客观限制
+- 最少执行 `git merge-base`、`git diff --name-status`、`git merge-tree --write-tree --messages` 对两个官方 Native 目标作三方模拟；记录命令、exit code、冲突路径。merge-tree 会在 Git object db 创建对象但不改源码或分支，允许。
+- 深入看源码定义和调用，不只扫描关键词；尽量提供可读且可复核的 `path:line` 和 commit hash。
+- 官方 tag 比较若产生无共同祖先、shallow、无法下载等障碍，如实记录并提出可复现替代方案。
+- 不强行运行常规编译、Android 实机、iOS 设备或 Jest。
+- 对官方 RN 版本差异使用 release changelog、已有源码；未下载的 RN 文件不得假称已审查。
+- 审计报告必须中文，章节包含：结论摘要、核对的版本与 SHA、方法和数据可信度、两条 Native 升级线冲突统计与具体文件、Particle 耦合清单、RenderSegment 耦合清单、RN 11.5.0 适配风险、改造优先级矩阵、阶段性迁移与验收、阻塞和未知、实际模型和文件修改清单。
+
+## 必做输出和 Git 收尾
+- 写入 `docs/报告/UPSTREAM-001_MapLibre官方升级兼容性架构审计_Codex完成报告_v1.md`；如不存在 `docs/报告/` 则创建。
+- 工作树中仅允许审计任务 MD 和审计报告两份新增文档；完成 `git diff --check`、路径与报告完整性检查。
+- **不要自行 commit 或 push**；执行器将先独立核对报告，再将仅这两份文档以隔离分支提交、确认快进后 push 到 `origin/particle/main`，最终回填 Git 状态。若未收到执行器的最终 Git 回执，报告必须写 `Git 收尾待 RDC 验收`，不能自称已推送。

docs/报告/UPSTREAM-001_MapLibre官方升级兼容性架构审计_Codex完成报告_v1.md

@@ -0,0 +1,610 @@
+# UPSTREAM-001 MapLibre 官方升级兼容性架构审计 Codex 完成报告 v1
+
+日期：2026-10-09（JST）。任务基线：`630ec657687bad4200c059bbccbb950d9c6f7ce9`。本报告只交付架构审计、三方干跑与后续建议，没有实施升级。
+
+## 1. 结论摘要
+
+**结论：CONDITIONAL GO。** 可以立项开展隔离迁移；不允许据本报告直接发布升级版本。必须先完成命名空间/接口迁移、Renderer 适配边界与两端单 SDK 收敛，再由 RDC/用户独立构建和运行验收。本次没有编译、运行、设备或发行 PASS。
+
+- Particle 的 Field/Ingress/Binding 具备可移植基础，WeatherColor 与 Particle 为独立 RenderLayer；不需要重写引擎。但 GPU 实现在新增的 `render_particle_validation_layer.cpp` 内，仍依赖 MapLibre 内部 RenderTarget、LayerGroup、Heatmap 顶点结构、PaintParameters 和生命周期，不能把“新增文件”解释成“独立 SDK”。
+- 长期维护的主要负担是 `Renderer::Impl` 与 `RenderOrchestrator` 中的缓存调度、Fast Path 输入签名、source/placement 失效及资源所有权。相对初始基线，两个 `.cpp` 分别增加/删除 **632/39**、**505/5** 行，已超过 thin-hook 的含义。
+- 官方目标均发生 `mbgl` → `mln` 目录和 C++ 命名空间迁移。标准 dry-run：Android **76** 个冲突路径（31 content + 44 file location + 1 modify/delete）；iOS **78** 个（33 + 44 + 1）。两者退出码均 **1：模拟完成且存在冲突**，不是执行失败，也不是升级成功。
+- `.21` 相对初始基线共 **765** 个变化路径：680 新增、85 修改。两条官方升级线原路径交叉分别 **72/76**，其中可自动合并的交叉路径为 **40/42**。不能把 85、72、76 或旧说法中的“62 个修改文件”当作文本冲突数。
+- 已读官方目标函数定义，确认 `RenderLayer::update()` 新增 `const PaintParameters&`、`PaintParameters` 增加 `renderableSize`、`RenderStaticData::backendSize` 被移除。新增粒子层、Fast Path 和 retained key 的调用必须适配；这是确定的源码接口差异，未执行编译，不能伪称已观察到编译报错。
+- RN 11.5.0 必须与 Native 升级分开验收。当前 RN peer/dev/Podspec 锁 11.3.6，Android 插件强制 13.4.1/`.21`，iOS 借用 MLRN 私有 SPM helper。只升 npm 版本会留下版本约束与 API/二进制风险。
+
+## 2. 核对的版本与 SHA
+
+| 项目 | 本次核实结果 | 证据边界 |
+| --- | --- | --- |
+| 机器 | `Darwin Mac.lan 24.6.0`，x86_64 | `uname -a`，无设备操作 |
+| 工作区 | `/Users/tei/dev/MapLibreParticleLab-upstream-audit-20261009` | 独立审计 worktree |
+| 分支 / HEAD | `audit/upstream-native-20261009` / `630ec657687bad4200c059bbccbb950d9c6f7ce9` | 起点与收尾一致 |
+| 本地远端跟踪引用 | `origin/particle/main` = 同上 SHA | `git ls-remote origin refs/heads/particle/main` 退出 128，DNS 失败；不能宣称实时远端 HEAD 已回读 |
+| 初始 Core | `18545ca10d296704b2cba675b182ff2c8da24588` | HEAD 与两条目标各自的 merge-base 均为此 SHA，退出 0 |
+| Android 目标 | `c7506d6aff3800e946f89e1a51432fc22d1a6534` | 本地 commit subject 为 Release MapLibre Android 13.6.1；任务书给定 tag 对应关系 |
+| iOS 目标 | `01791ad02c1bfe3b22c42a97619b972aba962f82` | 本地 commit subject 为 Release MapLibre iOS 6.31.0；任务书给定 tag 对应关系 |
+| 官方目标相互关系 | 两者 merge-base 为 Android 目标 SHA | Android 目标是 iOS 目标祖先；不能把它们当成两个无关 Core |
+| 本地 tags | `android-v13.6.1^{commit}`、`ios-v6.31.0^{commit}` 均退出 128 | tag 引用未安装；以完整 commit SHA 复现，不伪称完成 tag 公网认证 |
+| 当前 Android / RN | `13.4.1-particle.21` | `platform/android/VERSION`、RN package.json、release manifest |
+| 当前 iOS | `6.28.0-particle.21`，Metal，模块 MapLibre | `release/maplibre-particle/ios/release-manifest.json` |
+| `.21` 制品源码 | manifest 的 `sourceCommit=16a5d15f164dc93d220e3fac62de66a9c9527ccc` | 与审计 HEAD/发行记录提交是不同概念；未重新下载或核验制品 |
+| 官方 RN | v11.5.0，release 页面短 SHA `059f46b`，2026-10-04 | 没有取得完整 RN tag checkout，不能声称审查了全部 RN 11.5.0 源码 |
+| Integration | Mac 现存 `/Users/tei/dev/navsea-particle-integration` HEAD=`80667d6c343411d03a760425438e3d292f452118` | 只读 README/规则/COORD-005/C-001/C-002/状态；未访问 Linux 文件系统或修改合同 |
+| Git / submodule | Git 2.54.0；非 shallow；39 个 submodule 均未初始化（`-`） | submodule status 退出 0；不构成构建环境就绪 |
+
+根目录总则当前路线 v2 仍描述 `.3`，Integration 部分状态仍是旧开发状态，STEP-094 设计仍描述 source 全局失效；以 `.21` 代码与后续 STEP-100/102 实现事实为准，不回写历史文档。已阅读 STEP-098～102 记录及 STEP-094 设计；**本审计基线的 docs 中没有 STEP-103 文件**，因此不把其他 dirty worktree 或临时执行日志中的 STEP-103 当成 `.21` 已有能力。
+
+## 3. 方法和数据可信度
+
+### 3.1 执行范围
+
+读取根规则、项目规范、四份有效总则、架构设计、任务书、相关 Step、实际源码与 base→HEAD diff。未启动子代理、第二个 Codex、后台构建、Jest、Gradle/APK/AAR、Xcode、ADB 或设备步骤。未真实 merge/rebase、未变更分支/index、未修改源码/依赖/构建脚本/Integration。任务书允许的两份文档中，本轮仅新增本报告，任务书保持原样。
+
+证据临时目录：`/private/tmp/upstream-001-audit-20261009/`。Git object 写入也隔离于其 `objects/`，原共享对象库仅作只读 alternate。临时目录不是项目交付文件，RDC 应连同 JSONL/stdout/stderr 归档；本报告已嵌入冲突全表、命令与关键哈希，不依赖临时目录才能理解结论。
+
+### 3.2 失败与恢复过程
+
+| 操作 | 实际退出码 | 事实 |
+| --- | --- | --- |
+| 三个 `git merge-base HEAD <base/Android/iOS>` | 0 | 均为初始 Core SHA |
+| 初次 `git diff --name-status base <Android/iOS>` | 各 128 | promisor 补取 `3354d3daaf97803cc42e43758177cb126a7f1671` 时 github.com DNS 失败 |
+| 初次标准 `git merge-tree --write-tree --messages HEAD <目标>` | 各 128 | promisor 补取 `0e98150849597096c3fe2f1128b6e89884dcabdb` 时 DNS 失败；stdout 为空，不能计作零冲突 |
+| 原对象目录、关闭 rename 的诊断干跑 | 各 128 | `unable to create temporary file: Operation not permitted` / `failure to merge` |
+| `git diff --no-renames --name-status base <目标>` | 各 0 | 可得原路径交叉统计，但把移动表示为 D+A |
+| 临时可写对象目录、标准 rename 干跑 | 各 1 | 完成，产生 tree 与冲突清单；未要求越过权限或修改原共享对象目录 |
+| 同一临时对象目录标准干跑复跑 | 各 1 | 两次 stdout 字节完全一致，tree SHA 相同，stderr 为空 |
+| 临时对象目录普通 `git diff --name-status` | 各 0 | rename-aware 清单取得成功 |
+| 临时对象目录关闭 rename 的对照干跑 | 各 1 | Android 63、iOS 64 个路径；人为禁用目录迁移识别，**不是主结论** |
+| 远端 HEAD / 本地 tag 验证 | 128 | 分别为 DNS 失败 / 本地引用不存在，尚待 RDC |
+
+失败原始日志保留，没有把后一次完成倒写成首轮成功。成功使用的环境覆盖没有改 Git 配置或合并算法；没有使用 `-Xours`、`-Xtheirs` 或关闭冲突检测。没有证据证明网络后来恢复，不能从本地干跑成功推导网络已通。另有探索性旧路径读取、缺失测试文件名及 glob 查询失败，随后按实际新路径/文件定位；这些不是编译或测试失败。
+
+### 3.3 统计定义
+
+1. footprint：base→HEAD 的 Git 路径与 numstat，文档/fixture/测试/构建均分开说明。
+2. 原路径交叉：关闭 rename 时两边变更路径集合的交集。Android 23 M+49 D=72；iOS 27 M+49 D=76。49 D 中 48 被 Git 识别为 rename，shader_manifest 为 modify/delete；不是 49 个独立算法冲突。
+3. 冲突路径：标准 merge-tree stdout 第一段 stage 记录的路径去重；不把 stage 1/2/3 三条算三文件，也不靠 `Auto-merging` 文本计数。冲突类型另由 `CONFLICT (...)` 消息统计，恰与本轮路径数一致。
+4. 自动合并交叉路径：交叉集合中，旧路径及其 `mbgl→mln` 对应路径均不在 unmerged 清单者。它仅说明文本可合并；不代表符号、ABI、shader、资源或视觉正确。
+5. 行号默认是审计 HEAD。标注“目标”的 `src/mln/...` 行号来自指定官方 commit blob；审查用 namespace 归一 diff 只写临时文件，**未用归一文本作为正式干跑输入**。
+
+## 4. 两条 Native 升级线冲突统计与具体文件
+
+| 指标 | Android 13.6.1 | iOS 6.31.0 |
+| --- | ---: | ---: |
+| 官方 diff（rename-aware）路径数 | 2196 | 2250 |
+| A / M / D / R | 91 / 709 / 27 / 1369 | 117 / 719 / 69 / 1345 |
+| 官方 diff（no-renames）A / M / D | 1460 / 709 / 1396 | 1462 / 719 / 1414 |
+| 与我方原路径交叉 | 72 | 76 |
+| 交叉中冲突的官方既有文件 | 32 | 34 |
+| 交叉中自动合并的官方既有文件 | 40 | 42 |
+| 新增扩展的 file-location 冲突 | 44 | 44 |
+| 全部 unmerged 路径 | **76** | **78** |
+| content / file location / modify-delete | **31 / 44 / 1** | **33 / 44 / 1** |
+| stage 条目数（不可当文件数） | 139 | 145 |
+| 标准 dry-run 退出码 | **1** | **1** |
+| 结果 tree | `9509597174b70c9eede21d6900b6f54fb092fefa` | `ae31097f803a49be28c27eca6291252baebfa4c0` |
+
+iOS 比 Android 多出的文本冲突是 `platform/darwin/src/MLNStyleLayerManager.mm` 和 `src/mln/shaders/shader_source.cpp`。虽然目标名标注某个平台，比较对象是整个 Native 仓库，Android 干跑同样可能报告 iOS 文件冲突。
+
+完整冲突路径见附录 A；全部 85 个官方修改文件及交叉标记见附录 B。自动合并不能豁免审查，尤其包括 `render_layer.hpp`、`paint_parameters.*`、`render_target.*`、`gfx/context.hpp`、`mtl/offscreen_texture.cpp`、`mtl/texture2d.cpp`。
+
+### 4.1 目标源码证据与合并含义
+
+| 位置 / 函数 | 已核实差异 | 迁移处理 |
+| --- | --- | --- |
+| 目标 `src/mln/renderer/render_layer.hpp:159`，`RenderLayer::update` | 新增 `const PaintParameters&` 参数；该官方文件本次文本自动合并 | 同步 Particle/WeatherColor override、声明、普通/hidden cleanup/Fast Path 调用；不能只修改 factory |
+| 目标 `src/mln/renderer/renderer_impl.cpp:184`、`:224`、`:302` | 使用 `renderableSize` 构造 PaintParameters，并以其作为 UBO world size | retained viewport/key、scissor、target size 与主画布统一取当前 frame 数据 |
+| 目标 `src/mln/renderer/render_static_data.hpp` | 删除 `backendSize`，增加 symbol geometry 方法 | `.21` renderer_impl.cpp:745、:766 等旧引用需适配；不能恢复旧字段掩盖所有权变化 |
+| 目标 `src/mln/renderer/render_orchestrator.cpp`，`updateLayers` / `onSymbolError` | 传递新 PaintParameters，并增加 symbol error 转发 | 外提适配器须保留官方 observer 行为，包括 `.21` 自有的 source revision 和 teardown |
+| 目标 `src/mln/renderer/render_source.cpp` / `include/mln/style/types.hpp` | 新增 CustomMVTVector 与 source factory 分支 | 合并保留官方新增 source 与自定义 RasterArray，source dependency 不认识的新类型需 fail closed |
+| 目标 `src/mln/renderer/render_target.cpp`、`include/mln/gfx/context.hpp` | 审查的归一 diff 无其它差异；本地追加 isRenderable / depth-stencil 接口 | 可保留薄能力接口，仍做 GL/Metal clear、bind、恢复验证 |
+| 目标 `src/mln/mtl/render_pass.cpp` | 保存 commandBuffer，并修改 encoder 构造附近代码 | 合并自有 clear/store 与 vertex texture 逻辑时同时保留官方 commandBuffer 生命周期 |
+| 目标 `src/mln/mtl/offscreen_texture.cpp` | 官方也已把基类构造参数 `size` 修正为 `size_` | 删除重复维护的修复补丁；保留并单独审查自有 stencil/renderability 扩展 |
+| 两条目标 shader_manifest | Git 不识别为 rename，旧头删除与我方追加冲突 | 按新 shader manifest/生成机制注册扩展，不能把旧头直接并排保留 |
+
+44 个位置冲突解决为“搬到 mln”后，文件内容仍可能保留 `namespace mbgl` / `<mbgl/...>`。标准结果 tree 中还保留 **25 个 `/mbgl/` 路径**：24 个完全新增的 particle 子树文件及旧 shader_manifest。已直接读取模拟结果，确认搬到 `src/mln/renderer/layers/render_raster_particle_layer.hpp` 的内容仍是旧 namespace/include 和旧 update 签名。因此“解决冲突标记”不是完整升级；新增纯模块也需要机械命名迁移。
+
+## 5. Particle 耦合清单
+
+### 5.1 可保留的独立模块与实际边界
+
+| 代码证据 | 独立性判断 | 适配重点 |
+| --- | --- | --- |
+| `src/mbgl/particle/field/field_runtime.cpp:173`，FieldSeries::submit；`:223`，resolve | Shared Core 内按 validTime 排序、候选集合原子校验后 swap；exact 时 T0/T1 指向同帧；插值检查批次身份；不依赖 renderer | 迁移 namespace/include，保留 C-002 八帧、拒绝零淘汰与单帧真实时刻语义 |
+| `src/mbgl/particle/ingress/qbin_v2_decoder.cpp:75`，EncodedFieldIngress::decodeAndValidate | 字节解码→profile 校验→decoded frame，在 Core；未把 HTTP/provider 放进 renderer | 二进制/数值/错误枚举一致性；不得用升级机会改变 QBIN 公共契约 |
+| `src/mbgl/style/sources/raster_array_source.cpp:431`，submitEncodedField | host metadata/contract/raw bytes→Ingress→Store→refreshV4RendererState；不在提交中偷偷改目标时间 | Source::Impl/observer 桥是版本适配层；建议把 Store/Projection 协调留在专用 runtime，不继续扩充官方 Map |
+| `src/mbgl/renderer/layers/render_particle_validation_layer.cpp:1175`，prepare | 只消费 RenderRasterArraySource projection，绑定 T0/T1/mix；没有平台专属引擎 | 此 renderer 源文件实际实现正式 RenderRasterParticleLayer，不能按文件名把它当可删除测试 |
+| 同文件 `ParticleGpuResources:320`、update:1211、GPU tweaker:524 | state/trail A/B、shader、texture、timeline 与 context 生命周期集中在新增文件；使用 gfx 资源 | 2136 行集成了 fixture/正式路径、GPU pass、时钟和诊断；P1 外提资源与 pass executor，保持 engine 一套 |
+| `render_weather_color_layer.cpp:163`、prepare:197、update:229 | 与 Particle 有独立 class/resources，消费同一 projection；scalar/vector magnitude 分离 | 复用 `HeatmapTextureLayoutVertex`/RenderStaticData geometry（:274）是内部布局耦合，宜专用 quad adapter |
+| `render_particle_validation_layer.cpp:1141`、:1157、:1223 | layerRemoved 移除注册 target；contextDestroyed 标志；清空 field 时清 drawable、解除 target/tweaker/resource 环 | 跨版本必须保持 render-thread 销毁；不能用任意 UI 线程 delete 或通用 shared_ptr 推断无环 |
+| `src/mbgl/layermanager/raster_particle_layer_factory.cpp:19` | 创建专用 RenderRasterParticleLayer；default/Android/Darwin 仅注册类型 | factory 注册、SourceType、source switch 是真正应保留的薄 hook |
+
+本次口径仅取 `src/` 与 `include/` 下所有 base→HEAD 变化：68 个新增文件、11438 新增行；47 个官方既有文件、2035 新增行/133 删除行。新增文件承载新增行比例 **84.90%**，不是目标“约 95%”；它是可复现的近似工程指标，不是全部平台/测试代码比例，更不能衡量语义独立性。附录 C 列出 68 个新增 Core 文件；另外 612 个新增路径主要为文档、平台/测试、RN、fixture、集成与工具，不可拿它们稀释核心耦合。
+
+### 5.2 真正 thin hook、可外提和深耦合
+
+- **不可避免的官方接入 hook**：LayerManager 三平台注册、SourceType/RenderSource factory、shader registry/enum/清单、repaint/hidden-source-cleanup 扩展点、Map runtime state 传递、PaintParameters target 边界重置。目标是窄调用和能力描述，不在 hook 中展开业务策略。
+- **可外提的官方修改**：`style/conversion/source.cpp:206` 的 103 行 RasterArray parser 应移到专用 converter；`map/map_impl.cpp:115` 的 RasterArray 类型扫描/forecast tick 应由 source frame participant 适配器承担；JNI `native_map_view.cpp:1192` 的 field/layer 控制实现、MapLibreMap/MLNMapView diagnostics 可委托独立 facade。公开方法与生命周期所有者仍留在正式 SDK，不能以 global map registry 替代。
+- **深耦合必须分步重构**：Renderer::Impl 直接组织段 key/revision/cache 与主 buffer；RenderOrchestrator 同时管理 topology、dependency、source readiness、placement 与快路径；MTL Texture2D::bind 对所有纹理镜像 vertex binding，影响所有官方层，宜改为 shader-stage-aware backend 能力。
+- **通用 backend 修复应独立维护/争取上游化**：offscreen depth/stencil、clear/store、attachment-aware pipeline key。这些不能全塞入 Particle 私有 adapter，否则普通地图 target 仍可能不一致；保留在 gfx 的窄语义接口，并隔离成单独补丁与回归项。
+- **Vulkan 尚不能宣称等价**：现有新增 shader 源及注册明确覆盖 GL/Metal；在 `src/mbgl/vulkan`、`include/mbgl/shaders/vulkan`、`cmake/vulkan.cmake` 未找到 ParticleGpuValidation/RetainedUnderlayComposite 注册。context 的 override 补齐不等于 Vulkan 粒子功能已实现。后续必须验证能力返回/fail-closed 与专用实现，不能继承早期普通 Vulkan 构建 PASS。
+
+## 6. RenderSegment 耦合清单
+
+| 主题 | `.21` 已实现事实 | 未来兼容约束 / 验收 |
+| --- | --- | --- |
+| 单一 topology | `render_segment_plan.hpp:32` 解析 explicit/legacy/continuous-range；`:160` 检查完整覆盖；全局 Style index 不重新编号 | boundary 删除、重排、hidden、新插层、非法 JSON 均重解；不能复用旧合法 cache 掩盖非法 plan |
+| source→segment | `include/mbgl/renderer/render_segment.hpp:50` 从 Style metadata 统一推导依赖；`:114` RevisionBook；orchestrator:1172 查询 source loaded/fading | shared source 使多个段失效；无 source 的 background 不造依赖；custom/unknown/missing fail closed；remove/recreate 同 id 保留 revision 身份 |
+| 分层失效 | renderer_impl:631–676 合并 source revision、layer fingerprint、pixelRatio，逐段 Build/Reuse/Fallback；orchestrator:260 保留全局 revision | source/tile/feature-state 走 source epoch；image/glyph/style/context 等共享事件走 global epoch；不能漏掉新的官方 mutation 入口 |
+| loaded 与局部复用 | orchestrator:698 仍是 `styleLoaded && isLoaded()`；full CPU segment gate 用自己的 dependency/readiness | unrelated unloaded source 可阻塞 global loaded/快路径，不能据此禁用无关段的局部复用；也不能改 loaded 语义造 PASS |
+| placement | `render_segment.hpp:75` 结构性 symbol 能力；renderer_impl:645–656 按段 gate | 无 symbol 段可在别段 placement 活跃时复用；含 symbol 段仍受 changed/fade/transition 约束；不是 segment-local placement 算法 |
+| Fast Path | renderer.cpp:47 尝试快路径；:51 在全帧前释放 prepared tree；renderer_impl:199 起匹配签名/全局内容/拓扑/cache/稳定性；particle_fast_path.hpp:97 逐项 gate | singleContinuous 限制保持；sources/layers/images/light/font 等身份或参数变化必须回全帧；新增上游输入必须纳入签名，不能只检查 camera |
+| 全局限制 | orchestrator:1155 的 retainedRangeIsStable 检查所有 source fading；快路径 dynamic state 含 pending/light/placement/非粒子 repaint/annotation | STEP-100/102 的 full CPU 局部复用不等于快路径局部化；多 Continuous 正常执行仍需 full CPU |
+| Style / pass 顺序 | renderer_impl:805 构建 retained 段；:880/:904 opaque reverse/translucent forward；保留 layerGroup 原 ordinal 与全局 depthRange；:1005 顺序执行 composite/live | 半透明 fill/line/symbol、跨段遮挡与自定义层必须视觉对照；3D、debug、custom、legacy 等保守退回 live，不可简单按段局部重编号 |
+| Top / Bottom | renderer_impl:506–524 按 segmentIndex 创建独立 cache；遇到首个 Continuous 后用 Top 兼容 role；cache:310 透明 clear，:286 禁 depth composite | Top/Bottom 是旧诊断兼容角色，不是只有两张 texture；多段以 segment diagnostics 为准，不能复用 Bottom texture 充当 Top |
+| Context / target | paint_parameters.cpp:111 beginRenderTarget 清 stencil ID 和 tile mask；cache:246 depth+stencil offscreen、:310 clear、:320 present | 新目标 renderableSize、Metal attachment 格式/commandBuffer 与 GL FBO/stencil 恢复都要测；context generation 变化不得复用旧 texture |
+| 所有权 / teardown | orchestrator:180–209 两次 tagged drain、中间 detach observer 并销毁 sources；render_source.cpp:74 nullObserver；renderer prepared tree 在替换前丢弃引用 | tagged drain 不等于排空独立 render jobs；reset 循环、source cancel 回调、style reload、后台恢复必须独立验证 |
+
+建议内部抽出 `SegmentPlanner/DependencyTracker`（不持 GPU）、`RetainedSegmentExecutor`（持 cache、执行顺序与 target scope）、`FrameReuseAdapter`（官方 Update/Paint/Placement 输入映射）、`ParticleGpuResources/PassExecutor`（动画资源）。这些是建议职责，不是本轮新建 API。官方文件只传入明确 snapshot/事件并调用；资源生命周期和 Style 顺序必须保留在 renderer 所有权范围，不能外提成第二个 renderer。
+
+## 7. RN 11.5.0 适配风险
+
+### 7.1 官方信息与未取得材料
+
+[RN v11.4.0 官方 release](https://github.com/maplibre/maplibre-react-native/releases/tag/v11.4.0) 明确升级 Android Native 13.6.1、iOS Native 6.31.0；[官方 release 列表](https://github.com/maplibre/maplibre-react-native/releases) 记载 v11.4.1 的 iOS SPM target 挂接修复；[v11.5.0 release](https://github.com/maplibre/maplibre-react-native/releases/tag/v11.5.0) 增加 feature state API。这是 release 证据，不是对 11.5.0 每个构建文件的逐行认证。
+
+尝试 raw/GitHub 的 v11.5.0 android/build.gradle、Podspec 及 packages 子路径，返回 404 或 Cache miss，**未取得完整 RN 目标源码**。因此其私有 helper 签名、组件内部布局、Gradle property 名称是否保持均列为待核实，不伪造兼容结论。
+
+### 7.2 当前包已核对的问题
+
+| 文件与证据 | 风险与建议 |
+| --- | --- |
+| `packages/maplibre-particle-rn/package.json:34` / devDependencies | MLRN peer/dev 均精确 11.3.6；迁移时与 consumer lockfile 一起更新，经兼容 Gate 后锁定新版本，不能用宽泛 range 掩盖不支持 |
+| `app.plugin.js:22–23` | 已有 marker 就提前返回；项目升级若保留旧生成块，可能继续锁旧 `.21`。建议版本化且幂等替换受管块，验证重复 prebuild；本轮没有运行 prebuild |
+| `app.plugin.js:23` / `android/build.gradle:17` | substitution 只覆盖 `org.maplibre.gl:android-sdk-opengl`；另直接 implementation 自有 `.21`；nativeVersion=13.4.1、variant=opengl | 必须确认 MLRN 11.5 请求仍被替换，debug/release 每 configuration 仅一个 SDK、每 ABI 一个 libmaplibre.so；若官方改坐标/variant，旧替换可能漏掉。强制旧 SDK 也可能使 RN 新 API 缺失 |
+| `MapLibreParticleRN.podspec:10–34` / `:47` | 依赖 MLRN 11.3.6，借 `$MLRN._add_spm_to_target` 与 `$MLRN_SPM_SPEC`，属于私有 helper 耦合 | 检查 v11.4.1 SPM 修复后 helper 的参数/调用顺序与 targets；只复用一套 MapLibre product，不另外加官方 Pod/XCFramework |
+| `ios/WeatherRuntimeBridge.mm:103–118` | fresh Fabric registry→`MLRNMapViewComponentView`→contentView→`MLRNMapView`/MLNMapView；按类名识别内部组件 | 新 RN 组件名/包装结构变化即失效；用单独 MLRN adapter 集中适配，保留 stale tag/wrong tag 拒绝 |
+| `android/.../WeatherRuntimeBridgeModule.kt:363–369` | Fabric resolveView、强类型 MLRNMapView、view.mapLibreMap | 核实 11.5 Kotlin 类/属性/可见性；attach owner 仍跟随 concrete MapLibreMap，不能用进程全局表绕过销毁 |
+| `src/NativeWeatherRuntimeBridge.ts` / `RendererRuntime.ts` / 两端 bridge | typed TS→schema JSON→platform→Core；V4 submit/time、attach/detach、diagnostics | 维持公开签名/错误、JS safe integer 与平台 uint64 边界；codegen 构建由 RDC 后续执行 |
+| `.21` Core orchestrator:1015–1046 | set/removeFeatureState 已推进 source revision | RN 11.5 新 feature-state 入口需证明实际命中这一链；不能仅验证方法调用成功，必须观察依赖段刷新与无关段 reuse |
+
+功能验证必须覆盖：1）单 SDK 依赖树和制品身份；2）Fabric 新旧 map attach/detach、style reload、销毁后调用、20 次 reset；3）V4 单帧向量持续运动、标量无粒子、双帧 mix、八帧滚动、跨批次 unavailable、坏帧零副作用；4）RenderSegment R-C-R/C-R/R-C/多段、连续与 retained 中 feature-state/GeoJSON 更新；5）相机/pitch/wrap/resize、mask、透明度/颜色定量；6）GL 与 iOS Metal context loss/后台恢复和内存趋势。Android/iOS 各自提交日志/截图/计数，不互相替代。
+
+## 8. 改造优先级矩阵
+
+工作量为相对估计：S=局部少量文件，M=跨数个接口/模块，L=跨执行链和平台 Gate；不是承诺工期。P0 指迁移正确性前置，P1 指长期维护治理，P2 指后续优化。
+
+| 级别 / 项目 | 路径与当前耦合证据 | 方案 | 风险 / 工作量 | 验收标准 | Android / iOS |
+| --- | --- | --- | --- | --- | --- |
+| P0 命名与构建移植 | 68 新增 Core 文件、44 location 冲突、24 particle 文件未随目录移走；附录 A/B/C | 独立机械迁移补丁处理路径/namespace/include/清单；删旧 shader_manifest 接法 | 漏引用/并存 namespace，M | 全部自定义符号单 namespace，生成清单一致；无旧 include、缺失 source 或重复 shader | 共用 Core，双端 |
+| P0 帧接口适配 | render_layer.hpp 新 PaintParameters；renderer_impl 旧 backendSize；新增粒子 override | 建立 FrameReuseAdapter，先接全帧，再接 Fast Path；不恢复被官方移除状态 | 错 viewport/override/失效输入，M | 同帧 size/matrix 一致；普通/hidden/Fast 三入口完整；编译与 resize Gate | GL/Vulkan/Metal |
+| P0 执行边界 | renderer_impl.cpp:501–1020 +632/-39，orchestrator.cpp +505/-5 | 先外提 segment 决策/执行与官方输入映射，行为保持；策略不继续嵌入官方主函数 | Z-order、placement、stale cache，L | retained on/off 图像对照；global index/pass 顺序；source/placement/资源失败逐项验证 | 双端必测 |
+| P0 offscreen / MTL 生命周期 | gfx context overload、paint target reset、mtl render_pass clear 与新 commandBuffer | 窄 offscreen descriptor/target scope，保留官方所有权并独立迁移通用修复 | stencil 污染/格式错配/释放次序，M | GL stencil；Metal clear depth/stencil、pipeline format、device/simulator、context reset | Android GL；iOS/Metal |
+| P0 单 SDK 收敛 | RN package/plugin/podspec 与 `.21` implementation | 同时更新支持锁、替换规则、SPM helper adapter 与发行 manifest | 双二进制/旧 API/生成块残留，M | Gradle/Pods/SPM 仅一个 Native；Symbols/headers 来自同一源码 | 两端分别验收 |
+| P0 回归证据 | STEP-102 未完整运行验收即纳入 V21；STEP-103 本基线无文件 | 冻结旧版作对照；建立升级候选完整 Gate | 继承未知行为，M | 独立日志、同源制品 SHA、真实设备结果；无测试豁免冒充 PASS | 各平台明确状态 |
+| P1 source dependency | render_segment.hpp:50 / RevisionBook；orchestrator:242/1172 | 从 diagnostics DTO 分离 typed dependency snapshot/event adapter，保持 shared/global/unknown | 新 source/feature-state 漏失效，M | 同 source 多段刷新，无关段 reuse，remove/recreate、unknown fail closed | 共用 |
+| P1 GPU 模块外提 | render_particle_validation_layer.cpp 2136 行，Heatmap geometry 与资源环 | 专用 quad/资源/pass/lifecycle 模块，RenderLayer 只转发 | 跨 pass commit 与清理退化，M | 同样 state/trail generation、同帧推进一次、clear/reset 无泄漏 | GL/Metal；Vulkan另 Gate |
+| P1 backend stage 抽象 | mtl/texture2d.cpp:262 全纹理镜像 vertex bind | 用 shader-stage/binding metadata 描述需要的 stage，通用修复尽量上游化 | 影响普通层 binding/cache，M | 既有地图 shader 与 Particle 都正确；无无效 stage 绑定 | iOS/Metal 主，Core接口共用 |
+| P1 公共桥减重 | native_map_view.cpp:1192、MapLibreMap.java、MLNMapView.mm | 专用 Native facade/adapter 持实现，官方类保留方法与 map 生命周期 hook | JNI/ObjC API/销毁顺序，M | 方法签名不变，错误一致，stale tag/destroy callback 验证 | 两端 |
+| P1 parser / 时钟薄接入 | style/conversion/source.cpp:206；map_impl.cpp:115 | RasterArray converter 外提；source frame participant tick | clock 改变错误/数据所有权，S–M | submit 不改目标时间；cadence/pause/background 正确 | 共用 |
+| P1 Vulkan 能力闭环 | Vulkan 缺本任务 shader 注册证据 | 确认能力与 fail-closed；专用 backend 实现另立项 | 不支持被误报支持，L | Android Vulkan 粒子与 retained 实测；不能只编译普通地图 | Android Vulkan |
+| P2 多 Continuous Fast Path | singleContinuousSegment / 全局 signature | 先保留 full CPU；待依赖模型和预算稳定再单独设计 | 跨段 placement/顺序/上传遗漏，L | 多段对照、source mutation/placement 全组合，必要时 RFC | 共用 |
+| P2 footprint 预算与上游补丁 | 85 官方修改、47 Core 原文件 | 建 ledger、自动审计、补丁主题拆分、删除已上游化修复 | 日常维护成本，S | 每版本 diff/冲突/功能 gate 有独立可复现证据 | 共用 |
+
+不是所有 P1 都应阻塞首个候选。Field/Ingress/Binding、专用 layer/factory 和窄注册点可以在机械迁移后直接移植；Renderer 调度与新帧接口、offscreen 生命周期、单 SDK 必须先界定并验证。不得先做多段高级优化再补基础升级验收。
+
+## 9. 阶段性迁移与验收
+
+### Gate 0：冻结与可回滚准备
+
+RDC 回读 origin HEAD，认证两个官方 tag→SHA，归档 `.21` 的源码/manifest/制品；取得 RN 11.5.0 完整源码、11.3.6→11.5.0 diff。统一选择一个 Shared Core 候选：iOS 目标包含 Android 目标，但能否由该 commit 同时发行两端须构建验证，不能据祖先关系直接定版。本轮只给建议，不创建升级分支。
+
+回滚点：保留 `.21` 不可变制品与 consumer 锁。任何 Gate 失败，停止推进；候选分支可丢弃，生产分支/旧制品不覆盖。需运行回退时可用既有 map-scoped retained enable 开关关闭优化，另保留完整旧版本回退；不把关闭功能当作新版本通过。
+
+### Gate 1：行为保持的边界整理
+
+在旧基线单独重构 segment executor / frame adapter / target scope；保持 C-001/C-002、Style 顺序与既有 fail-closed，不顺带提高 Fast Path 支持范围。RDC 完成旧基线等价回归后冻结此检查点。若无法保持行为，停下修复，不混进 namespace 迁移使定位困难。
+
+### Gate 2：机械迁移与 Native 三方整合
+
+从选定官方目标在隔离候选中按主题移植：Core/字段→类型注册→shader/backend→Renderer adapter→平台 bridge→测试/发行清单。先统一 mln namespace/include，适配 PaintParameters/renderableSize、source enum、symbol observer；处理 shader_manifest 删除和官方已有修复。保留官方新功能，禁止整文件选 ours/theirs。
+
+RDC 记录每主题冲突解决、构建日志和 patch footprint；无冲突标记、无未注册新 shader/重复 namespace 后才进入功能 Gate。Android 和 iOS release tag 是同仓库不同发布点，不建立两套 Core fork。
+
+### Gate 3：分 backend / 平台验证
+
+由 RDC 在目标版本实际支持的 CMake/Bazel target 上配置/编译；本次没有替它运行。可复用旧仓库文档中的 host 路径仅作候选，目标改名后应以配置输出确定 runner，不能硬称 `mbgl-test-runner` 必然保留。已有 runner 的定向过滤器如下（由 RDC 设置真实路径）：
+
+```bash
+"$UPSTREAM_AUDIT_TEST_RUNNER" --gtest_filter='Particle*.*:Source.RasterArray*:Retained*.*:ContinuousLayerRange.*:RenderSegment*.*:RenderOrchestratorTeardown.*'
+```
+
+该变量必须指向同候选源码构建的测试程序。额外执行官方基础地图回归。Android Gradle/APK/安装/ADB/实体机仍按用户手工规则；iOS/Metal host 编译不能替代 iOS 设备。GL、Vulkan、Metal 分别记录结果，不以某 backend 通过覆盖其它 backend。
+
+硬门槛：R-C-R 动态 source 只刷依赖段；无关 source 永久 unloaded 时局部 retained 仍可复用；含 symbol / 无 symbol 的 placement 场景正确；global live fallback 不错过图层；feature-state set/remove 使依赖段更新；camera/pitch/wrap/resize/context reset 无旧纹理；20 次 teardown、clear/reload 无回调到已销毁对象；单帧/八帧 C-002 同两端语义；定量 WeatherColor 和统一 mask 不退化。记录实际 build/reuse/invalidation、actualExecution、sourceRevision、fastPath miss reason、日志与图像对照。
+
+### Gate 4：RN 与发行
+
+确认 Android 每个 debug/release dependency graph 中仅自有一个 Native SDK；由用户手工 Gradle 验证 dependencyInsight 和 APK so 唯一性。iOS 检查 Podfile.lock、Package.resolved、Pods/宿主 target 的同一个 MapLibre SPM product 与私有 helper 兼容。两端 Fabric bridge 功能通过后，再由授权发行任务升版本、build/publish/readback/finalize；不覆盖 `.21`，manifest 绑定同一源码。
+
+必须回 Integration RFC/Contract 的情形：公共 API/返回值/错误、attach/detach 与资源所有权、QBIN/profile/time/window/mask 语义、Host/Native 责任边界、Android/iOS 公共行为产生分叉；或希望把多 Continuous/placement 新语义公开为能力。纯 namespace、内部模块外提和行为保持适配不自动要求新 Contract。
+
+### 长期跟踪与 patch footprint budget（建议，未修改总则）
+
+每个官方 release 单独审计 SHA/merge-base、rename-aware diff、三方冲突和自动合并后的行为清单。维护四组补丁：独立扩展、注册 hook、通用 backend 修复、平台/发行；每组有 owner、原因、上游替代情况和回归场景。不能只重放历史 Step 提交而不核对最终 diff。
+
+建议预算：新增功能中 ≥95% 实现新增行进入专用模块（排除文档/fixture/generated/tests 的分母）；官方函数内 hook 原则上一个调用、每处目标 ≤10 行；超过 30 行策略逻辑须评审外提；一次功能新增官方接点 >3 个须解释；本轮先让 47 个 Core 既有文件的修改规模不增长，重点把 renderer_impl/orchestrator 的新增策略行量减少至少一半，最终数字由行为保持 Gate 核定。预算是预警，不可为达数字拆碎代码或把复杂性藏进宏。
+
+长期收益：把下一次官方 renderer 签名变化限制到 adapter/窄 hook；Field/GPU 逻辑继续复用。仍需承担 backend 与 Fabric 私有接口回归费用；“新增文件比例高”无法消除 API/ABI 和行为升级成本。
+
+## 10. 阻塞和未知
+
+- 本次没有实际编译/测试/设备/发布，所有升级运行验收为 **NOT RUN**；静态审计与 merge-tree 不等于功能 PASS。
+- RN 11.5.0 目标源码未完整取得，私有 SPM helper/Fabric 细节待 RDC 审核；本地 Native tags 与实时 origin HEAD 未认证。
+- `.21` STEP-102 记录明确以源码审查接受部分未跑 Gate 后发行；本轮不将其补写为运行 PASS。STEP-103 不在冻结基线，不能用未合入实现支持结论。
+- Vulkan 粒子/retained 注册缺口、Metal vertex texture 全局绑定、资源环与 target clear 的跨设备行为需专项验证；没有测量内存/FPS，不给性能承诺。
+- 完整 target source 不是全部逐文件审完；重点读取了本报告所列函数与自动合并热点，未下载到的 RN 文件已单列。单次三方模拟只能描述指定 SHA，不能预测所有未来上游版本。
+- Git 收尾待 RDC 验收。未 commit/push，未收到执行器的最终 Git 回执。
+
+## 11. 实际模型、退出状态与文件修改清单
+
+实际配置来自当前会话 JSONL，不由默认 config.toml 或自称推断：
+
+```text
+文件：/Users/tei/.codex/sessions/2026/10/09/rollout-2026-10-09T08-48-37-01a11deb-3653-73b2-8b2d-43f0e59ccc3a.jsonl
+第 1 行：session_meta
+  id=01a11deb-3653-73b2-8b2d-43f0e59ccc3a
+  cwd=/Users/tei/dev/MapLibreParticleLab-upstream-audit-20261009
+  originator=codex_exec; cli_version=0.161.0; source=exec; model_provider=openai
+第 8 行：turn_context，时间 2026-10-08T23:48:46.536Z
+  model=gpt-6-astra
+  effort=high
+  collaboration_mode.settings.model=gpt-6-astra
+  collaboration_mode.settings.reasoning_effort=high
+环境 CODEX_THREAD_ID 与上述 id 一致。
+```
+
+模型 Gate 符合 GPT-6 Astra High；未切换模型或推理档位。**本 Codex 执行器进程最终退出码在本轮结束前无法由本进程自证，待 RDC 从外层执行器回执填写。** 不把任意 shell 的 exit 0 或本报告写入成功当成 Codex 全任务退出 0；已观测的 dry-run exit 1、失败 exit 128 和检查退出状态见本报告及末尾收尾记录。
+
+实际项目修改：只新增 `docs/报告/UPSTREAM-001_MapLibre官方升级兼容性架构审计_Codex完成报告_v1.md`。预先存在的未跟踪 `docs/40_任务/UPSTREAM-001_MapLibre官方升级兼容性架构审计_Codex任务_v1.md` 未修改。没有生成其它项目文档，因此没有更新 Step 或开发记录；本任务明确只允许这两份文档，优先于常规收尾规则。
+
+独立验收需要：本报告、下列全路径表/命令/哈希、原始干跑 stdout/stderr、当前 JSONL 开始配置与外层结束回执、工作树 scoped diff、远端 HEAD 回读，以及后续单独授权的构建/设备证据。本轮可交付审计结论，不可交付新 SDK 功能 PASS。
+
+## 附录 A：标准干跑完整冲突路径
+
+路径为 merge-tree 的 unmerged 路径；`mln` 是模拟目标路径，并未创建到源码工作树。`—` 表示该升级线无此冲突。位置冲突不等于文本冲突。
+
+| 路径 | Android | iOS |
+| --- | --- | --- |
+| `CMakeLists.txt` | 文本 | 文本 |
+| `bazel/core.bzl` | 文本 | 文本 |
+| `cmake/metal.cmake` | 文本 | 文本 |
+| `cmake/opengl.cmake` | 文本 | 文本 |
+| `include/mbgl/shaders/shader_manifest.hpp` | 修改/删除 | 修改/删除 |
+| `include/mln/layermanager/particle_validation_layer_factory.hpp` | 位置 | 位置 |
+| `include/mln/layermanager/raster_particle_layer_factory.hpp` | 位置 | 位置 |
+| `include/mln/layermanager/weather_color_layer_factory.hpp` | 位置 | 位置 |
+| `include/mln/map/map.hpp` | 文本 | 文本 |
+| `include/mln/renderer/layers/weather_color_texture_lifecycle.hpp` | 位置 | 位置 |
+| `include/mln/renderer/render_segment.hpp` | 位置 | 位置 |
+| `include/mln/renderer/retained_underlay.hpp` | 位置 | 位置 |
+| `include/mln/shaders/gl/particle_gpu_validation.hpp` | 位置 | 位置 |
+| `include/mln/shaders/gl/retained_underlay_composite.hpp` | 位置 | 位置 |
+| `include/mln/shaders/mtl/particle_gpu_validation.hpp` | 位置 | 位置 |
+| `include/mln/shaders/mtl/retained_underlay_composite.hpp` | 位置 | 位置 |
+| `include/mln/shaders/particle_gpu_validation_ubo.hpp` | 位置 | 位置 |
+| `include/mln/style/layers/particle_validation_layer.hpp` | 位置 | 位置 |
+| `include/mln/style/layers/raster_particle_layer.hpp` | 位置 | 位置 |
+| `include/mln/style/layers/weather_color_layer.hpp` | 位置 | 位置 |
+| `include/mln/style/layers/weather_color_stop.hpp` | 位置 | 位置 |
+| `include/mln/style/sources/raster_array_source.hpp` | 位置 | 位置 |
+| `include/mln/style/types.hpp` | 文本 | 文本 |
+| `platform/android/MapLibreAndroid/src/cpp/native_map_view.cpp` | 文本 | 文本 |
+| `platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/FeatureOverviewActivity.kt` | 文本 | 文本 |
+| `platform/android/MapLibreAndroidTestApp/src/main/res/values/strings.xml` | 文本 | 文本 |
+| `platform/android/VERSION` | 文本 | 文本 |
+| `platform/android/buildSrc/src/main/kotlin/maplibre.gradle-publish.gradle.kts` | 文本 | 文本 |
+| `platform/darwin/src/MLNStyleLayerManager.mm` | — | 文本 |
+| `platform/default/src/mln/layermanager/layer_manager.cpp` | 文本 | 文本 |
+| `platform/ios/src/MLNMapView.mm` | 文本 | 文本 |
+| `src/mln/gl/offscreen_texture.cpp` | 文本 | 文本 |
+| `src/mln/layermanager/particle_validation_layer_factory.cpp` | 位置 | 位置 |
+| `src/mln/layermanager/raster_particle_layer_factory.cpp` | 位置 | 位置 |
+| `src/mln/layermanager/weather_color_layer_factory.cpp` | 位置 | 位置 |
+| `src/mln/map/map_impl.cpp` | 文本 | 文本 |
+| `src/mln/map/map_impl.hpp` | 文本 | 文本 |
+| `src/mln/mtl/render_pass.cpp` | 文本 | 文本 |
+| `src/mln/mtl/renderer_backend.cpp` | 文本 | 文本 |
+| `src/mln/renderer/continuous_layer_range.hpp` | 位置 | 位置 |
+| `src/mln/renderer/layers/render_particle_validation_layer.cpp` | 位置 | 位置 |
+| `src/mln/renderer/layers/render_particle_validation_layer.hpp` | 位置 | 位置 |
+| `src/mln/renderer/layers/render_raster_particle_layer.hpp` | 位置 | 位置 |
+| `src/mln/renderer/layers/render_weather_color_layer.cpp` | 位置 | 位置 |
+| `src/mln/renderer/layers/render_weather_color_layer.hpp` | 位置 | 位置 |
+| `src/mln/renderer/particle_fast_path.hpp` | 位置 | 位置 |
+| `src/mln/renderer/particle_viewport_reseed.hpp` | 位置 | 位置 |
+| `src/mln/renderer/render_orchestrator.cpp` | 文本 | 文本 |
+| `src/mln/renderer/render_orchestrator.hpp` | 文本 | 文本 |
+| `src/mln/renderer/render_segment_json.hpp` | 位置 | 位置 |
+| `src/mln/renderer/render_segment_plan.hpp` | 位置 | 位置 |
+| `src/mln/renderer/render_source.cpp` | 文本 | 文本 |
+| `src/mln/renderer/renderer.cpp` | 文本 | 文本 |
+| `src/mln/renderer/renderer_impl.cpp` | 文本 | 文本 |
+| `src/mln/renderer/renderer_impl.hpp` | 文本 | 文本 |
+| `src/mln/renderer/retained_underlay_cache.cpp` | 位置 | 位置 |
+| `src/mln/renderer/retained_underlay_cache.hpp` | 位置 | 位置 |
+| `src/mln/renderer/retained_underlay_runtime_state.hpp` | 位置 | 位置 |
+| `src/mln/renderer/sources/render_raster_array_source.hpp` | 位置 | 位置 |
+| `src/mln/renderer/update_parameters.hpp` | 文本 | 文本 |
+| `src/mln/shaders/mtl/particle_gpu_validation.cpp` | 位置 | 位置 |
+| `src/mln/shaders/mtl/retained_underlay_composite.cpp` | 位置 | 位置 |
+| `src/mln/shaders/mtl/shader_program.cpp` | 文本 | 文本 |
+| `src/mln/shaders/shader_source.cpp` | — | 文本 |
+| `src/mln/style/conversion/source.cpp` | 文本 | 文本 |
+| `src/mln/style/layers/particle_render_layer_properties.hpp` | 位置 | 位置 |
+| `src/mln/style/layers/particle_validation_layer.cpp` | 位置 | 位置 |
+| `src/mln/style/layers/particle_validation_layer_impl.hpp` | 位置 | 位置 |
+| `src/mln/style/layers/raster_particle_layer.cpp` | 位置 | 位置 |
+| `src/mln/style/layers/raster_particle_layer_impl.hpp` | 位置 | 位置 |
+| `src/mln/style/layers/weather_color_layer.cpp` | 位置 | 位置 |
+| `src/mln/style/layers/weather_color_layer_impl.hpp` | 位置 | 位置 |
+| `src/mln/style/sources/raster_array_source.cpp` | 位置 | 位置 |
+| `src/mln/style/sources/raster_array_source_impl.hpp` | 位置 | 位置 |
+| `test/CMakeLists.txt` | 文本 | 文本 |
+| `test/gl/gl_functions.test.cpp` | 文本 | 文本 |
+| `test/style/source.test.cpp` | 文本 | 文本 |
+| `test/style/style_layer.test.cpp` | 文本 | 文本 |
+
+## 附录 B：85 个官方既有修改文件逐项清单
+
+`+/-` 来自 base→HEAD numstat；行号是首个修改 hunk 的 HEAD 起始行，详细函数解释见正文。主分类不抹除平台桥中的可外提逻辑。A/I：`C` 文本冲突、`D` 修改/删除、`净` 交叉但自动合并、`未交叉` 仅我方变动。旧路径迁移到 mln 后计同一文件。
+
+| HEAD 路径:行 | +/- | 主分类 | 当前耦合/处理 | A / I |
+| --- | --- | --- | --- | --- |
+| `.gitignore:16` | +1/-0 | 构建/平台 | 忽略本地 artifact | 未交叉 / 净 |
+| `CMakeLists.txt:183` | +54/-0 | 构建/平台 | 扩展 source/header/shader 清单接入 | C / C |
+| `bazel/core.bzl:102` | +67/-0 | 构建/平台 | 扩展 source/header/shader 清单接入 | C / C |
+| `cmake/metal.cmake:50` | +4/-0 | 构建/平台 | 扩展 source/header/shader 清单接入 | C / C |
+| `cmake/opengl.cmake:40` | +1/-0 | 构建/平台 | 扩展 source/header/shader 清单接入 | C / C |
+| `include/mbgl/gfx/context.hpp:85` | +4/-0 | 必要 hook | depth/stencil offscreen 虚接口 | 净 / 净 |
+| `include/mbgl/map/map.hpp:17` | +10/-0 | 必要 hook | 公开 retained/segment API | C / C |
+| `include/mbgl/mtl/context.hpp:109` | +4/-1 | 必要 hook | depth/stencil virtual override 声明 | 净 / 净 |
+| `include/mbgl/mtl/render_pass.hpp:20` | +23/-2 | 深耦合 | 新增 clear helper、vertex texture/sampler 缓存 | 净 / 净 |
+| `include/mbgl/renderer/render_target.hpp:37` | +3/-0 | 必要 hook | isRenderable 能力 | 净 / 净 |
+| `include/mbgl/shaders/gl/shader_info.hpp:152` | +14/-0 | 必要 hook | 新增 shader/UBO/texture/attribute 注册；生成机制随目标迁移 | 净 / 净 |
+| `include/mbgl/shaders/shader_defines.hpp:130` | +33/-0 | 必要 hook | 新增 shader/UBO/texture/attribute 注册；生成机制随目标迁移 | 净 / 净 |
+| `include/mbgl/shaders/shader_manifest.hpp:27` | +2/-0 | 必要 hook | 新增 shader/UBO/texture/attribute 注册；生成机制随目标迁移 | D / D |
+| `include/mbgl/shaders/shader_source.hpp:33` | +2/-0 | 必要 hook | 新增 shader/UBO/texture/attribute 注册；生成机制随目标迁移 | 净 / 净 |
+| `include/mbgl/style/types.hpp:18` | +2/-1 | 必要 hook | RasterArray SourceType | C / C |
+| `include/mbgl/vulkan/context.hpp:109` | +4/-1 | 必要 hook | depth/stencil virtual override 声明 | 净 / 净 |
+| `include/mbgl/webgpu/context.hpp:46` | +4/-1 | 必要 hook | depth/stencil virtual override 声明 | 净 / 净 |
+| `platform/android/MapLibreAndroid/src/cpp/map_renderer.cpp:198` | +4/-0 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | 净 / 净 |
+| `platform/android/MapLibreAndroid/src/cpp/native_map_view.cpp:6` | +453/-0 | 构建/平台 | JNI field/layer/segment 实现可外提，官方类保留注册/生命周期 | C / C |
+| `platform/android/MapLibreAndroid/src/cpp/native_map_view.hpp:204` | +49/-0 | 构建/平台 | JNI facade 方法与签名 | 净 / 净 |
+| `platform/android/MapLibreAndroid/src/cpp/style/layers/layer_manager.cpp:22` | +7/-0 | 构建/平台 | Android Core-only factory 薄注册 | 净 / 净 |
+| `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/MapLibreMap.java:15` | +243/-0 | 构建/平台 | runtime ownership、destroy listener、公开 facade，可外提实现 | 未交叉 / 未交叉 |
+| `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMap.java:142` | +60/-0 | 构建/平台 | Native 内部接口表 | 未交叉 / 未交叉 |
+| `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMapView.java:656` | +221/-0 | 构建/平台 | state guard 与 Native JNI 转发 | 净 / 净 |
+| `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/renderer/surfaceview/SurfaceViewMapRenderer.java:4` | +3/-0 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | 未交叉 / 未交叉 |
+| `platform/android/MapLibreAndroidTestApp/build.gradle.kts:19` | +6/-1 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | 净 / 净 |
+| `platform/android/MapLibreAndroidTestApp/src/main/AndroidManifest.xml:289` | +13/-0 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | 净 / 净 |
+| `platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/FeatureOverviewActivity.kt:11` | +12/-0 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | C / C |
+| `platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_feature_overview.xml:8` | +12/-1 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | 未交叉 / 未交叉 |
+| `platform/android/MapLibreAndroidTestApp/src/main/res/values/descriptions.xml:4` | +1/-0 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | 净 / 净 |
+| `platform/android/MapLibreAndroidTestApp/src/main/res/values/strings.xml:11` | +45/-0 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | C / C |
+| `platform/android/MapLibreAndroidTestApp/src/main/res/values/titles.xml:28` | +1/-0 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | 净 / 净 |
+| `platform/android/VERSION:1` | +1/-1 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | C / C |
+| `platform/android/buildSrc/src/main/kotlin/maplibre.artifact-settings.gradle.kts:1` | +6/-6 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | 未交叉 / 未交叉 |
+| `platform/android/buildSrc/src/main/kotlin/maplibre.gradle-publish.gradle.kts:7` | +12/-0 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | C / C |
+| `platform/darwin/src/MLNStyleLayerManager.mm:17` | +7/-0 | 构建/平台 | Darwin factory 薄注册 | 净 / C |
+| `platform/default/src/mbgl/layermanager/layer_manager.cpp:13` | +7/-0 | 必要 hook | 注册三种新增 LayerFactory | C / C |
+| `platform/default/src/mbgl/storage/offline_download.cpp:219` | +8/-0 | 必要 hook | RasterArray 无 offline tileset，switch 明确忽略 | 净 / 净 |
+| `platform/ios/BUILD.bazel:152` | +0/-4 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | 未交叉 / 未交叉 |
+| `platform/ios/app/CMakeLists.txt:27` | +31/-0 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | 未交叉 / 未交叉 |
+| `platform/ios/app/MBXViewController.mm:19` | +741/-2 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | 未交叉 / 净 |
+| `platform/ios/bazel/files.bzl:8` | +2/-0 | 构建/平台 | 平台构建/发行/验证 App 或日志配套 | 未交叉 / 未交叉 |
+| `platform/ios/src/MLNMapView.h:31` | +64/-0 | 构建/平台 | 公开诊断与 segment 方法 | 未交叉 / 未交叉 |
+| `platform/ios/src/MLNMapView.mm:8` | +125/-0 | 构建/平台 | diagnostics ObjC 对象/JSON/Map 转发可委托专用 adapter | C / C |
+| `platform/ios/src/Mapbox.h:45` | +1/-0 | 构建/平台 | 导出 MLNParticleFieldRuntime | 未交叉 / 净 |
+| `shaders/manifest.json:147` | +14/-0 | 构建/平台 | 扩展 source/header/shader 清单接入 | 未交叉 / 净 |
+| `src/mbgl/annotation/annotation_manager.cpp:224` | +6/-0 | 必要 hook | hasPendingChanges 持锁读取 dirty，快路径观察 | 净 / 净 |
+| `src/mbgl/annotation/annotation_manager.hpp:45` | +1/-0 | 必要 hook | hasPendingChanges 声明 | 净 / 净 |
+| `src/mbgl/gl/context.cpp:439` | +27/-1 | 可外提 | 通用 depth/stencil FBO 能力，独立 backend 补丁/上游化 | 净 / 净 |
+| `src/mbgl/gl/context.hpp:137` | +6/-0 | 必要 hook | 通用 offscreen/FBO 声明 | 净 / 净 |
+| `src/mbgl/gl/offscreen_texture.cpp:11` | +19/-4 | 可外提 | 通用 attachment 实现，独立 backend 补丁 | C / C |
+| `src/mbgl/gl/offscreen_texture.hpp:15` | +3/-1 | 必要 hook | depth/stencil 构造参数 | 净 / 净 |
+| `src/mbgl/gl/renderer_backend.cpp:138` | +2/-0 | 必要 hook | 新增 shader/UBO/texture/attribute 注册；生成机制随目标迁移 | 净 / 净 |
+| `src/mbgl/map/map.cpp:97` | +32/-0 | 必要 hook | 公开配置/查询委托 runtime 并 onUpdate | 净 / 净 |
+| `src/mbgl/map/map_impl.cpp:6` | +10/-0 | 可外提 | 直接识别 RasterArray 并 tickForecastClock | C / C |
+| `src/mbgl/map/map_impl.hpp:16` | +3/-0 | 必要 hook | map-scoped runtime state 所有权 | C / C |
+| `src/mbgl/mtl/offscreen_texture.cpp:8` | +60/-10 | 可外提 | 通用 attachment/renderability 修复；官方已有 size_ 修复 | 净 / 净 |
+| `src/mbgl/mtl/render_pass.cpp:9` | +61/-13 | 深耦合 | clear/store/encoder/vertex binding 与官方 commandBuffer 合并 | C / C |
+| `src/mbgl/mtl/renderer_backend.cpp:30` | +4/-0 | 必要 hook | 新增 shader/UBO/texture/attribute 注册；生成机制随目标迁移 | C / C |
+| `src/mbgl/mtl/texture2d.cpp:260` | +4/-0 | 深耦合 | 所有 Texture2D::bind 镜像 vertex stage | 净 / 净 |
+| `src/mbgl/renderer/layers/render_location_indicator_layer.hpp:47` | +1/-0 | 必要 hook | legacy rendering 分类 | 净 / 净 |
+| `src/mbgl/renderer/paint_parameters.cpp:111` | +8/-0 | 必要 hook | beginRenderTarget 清 stencil id/mask cache | 净 / 净 |
+| `src/mbgl/renderer/paint_parameters.hpp:115` | +3/-0 | 必要 hook | target boundary 声明 | 净 / 净 |
+| `src/mbgl/renderer/render_layer.hpp:109` | +21/-0 | 必要 hook | repaint/粒子能力/legacy/hidden cleanup 默认虚函数 | 净 / 净 |
+| `src/mbgl/renderer/render_orchestrator.cpp:2` | +505/-5 | 深耦合 | 依赖/revision/placement/readiness/teardown 与官方调度交织 | C / C |
+| `src/mbgl/renderer/render_orchestrator.hpp:18` | +184/-1 | 深耦合 | 上述状态、事件、遍历方法与 mutex | C / C |
+| `src/mbgl/renderer/render_source.cpp:11` | +5/-1 | 必要 hook | RasterArray factory 与 nullObserver 恢复 | C / C |
+| `src/mbgl/renderer/render_source.hpp:14` | +21/-0 | 可外提 | readiness DTO/诊断方法与正式 source 类相连 | 净 / 净 |
+| `src/mbgl/renderer/render_target.cpp:24` | +5/-3 | 必要 hook | isRenderable 与 target boundary | 净 / 净 |
+| `src/mbgl/renderer/render_tree.hpp:102` | +11/-0 | 必要 hook | prepared tree 的快帧时间与 repaint 更新 | 净 / 净 |
+| `src/mbgl/renderer/renderer.cpp:27` | +14/-1 | 必要 hook | 先快帧、全帧前释放引用树、提交 prepared tree | C / C |
+| `src/mbgl/renderer/renderer_impl.cpp:4` | +632/-39 | 深耦合 | segment 决策/资源/执行与 Fast Path 主控制链 | C / C |
+| `src/mbgl/renderer/renderer_impl.hpp:4` | +63/-1 | 深耦合 | cache/prepared tree、UpdateParameters 镜像签名所有权 | C / C |
+| `src/mbgl/renderer/sources/render_tile_source.cpp:489` | +17/-0 | 可外提 | tilePyramid 计数诊断，可委托 source adapter | 净 / 净 |
+| `src/mbgl/renderer/sources/render_tile_source.hpp:26` | +1/-0 | 必要 hook | readiness 查询 override | 净 / 净 |
+| `src/mbgl/renderer/update_parameters.hpp:12` | +4/-0 | 必要 hook | 传递 map-scoped retained runtime state | C / C |
+| `src/mbgl/shaders/gl/shader_info.cpp:290` | +27/-0 | 必要 hook | 新增 shader/UBO/texture/attribute 注册；生成机制随目标迁移 | 净 / 净 |
+| `src/mbgl/shaders/mtl/shader_program.cpp:12` | +22/-9 | 可外提 | pipeline key 纳入 attachment format，独立通用修复 | C / C |
+| `src/mbgl/shaders/shader_source.cpp:9` | +40/-37 | 必要 hook | 新增 shader/UBO/texture/attribute 注册；生成机制随目标迁移 | 净 / C |
+| `src/mbgl/style/conversion/source.cpp:13` | +106/-0 | 可外提 | 103 行 RasterArray JSON parser 可独立 converter | C / C |
+| `src/mbgl/style/types.cpp:15` | +2/-1 | 必要 hook | raster-array 字符串映射 | 净 / 净 |
+| `test/CMakeLists.txt:21` | +16/-0 | 测试配套 | 新增类型/生命周期测试或平台条件；本轮未运行 | C / C |
+| `test/gl/gl_functions.test.cpp:7` | +11/-0 | 测试配套 | 新增类型/生命周期测试或平台条件；本轮未运行 | C / C |
+| `test/style/source.test.cpp:15` | +883/-0 | 测试配套 | 新增类型/生命周期测试或平台条件；本轮未运行 | C / C |
+| `test/style/style_layer.test.cpp:19` | +106/-0 | 测试配套 | 新增类型/生命周期测试或平台条件；本轮未运行 | C / C |
+
+分类合计：构建/平台 32；必要 hook 34；深耦合 7；可外提 8；测试配套 4。各类相加为 85；分类为审计判断，不代表冲突严重性排序。
+
+## 附录 C：68 个纯新增 Core 扩展文件
+
+“纯新增”是 Git 身份，独立程度仍按正文函数审计；GPU/RenderSegment 新文件也存在官方内部 API 耦合。以下为完整 `src/`、`include/` 新增清单（24 个 particle 子树文件、其余 44 个 layer/source/renderer/shader 等文件）。
+
+```text
+include/mbgl/layermanager/particle_validation_layer_factory.hpp
+include/mbgl/layermanager/raster_particle_layer_factory.hpp
+include/mbgl/layermanager/weather_color_layer_factory.hpp
+include/mbgl/particle/field/field_binding.hpp
+include/mbgl/particle/field/field_data_adapter.hpp
+include/mbgl/particle/field/field_profile_contract.hpp
+include/mbgl/particle/field/field_profile_contract_json.hpp
+include/mbgl/particle/field/field_profile_validator.hpp
+include/mbgl/particle/field/field_projection_materialization.hpp
+include/mbgl/particle/field/field_runtime.hpp
+include/mbgl/particle/field/local_particle_field_feed.hpp
+include/mbgl/particle/field/particle_gpu_math.hpp
+include/mbgl/particle/ingress/encoded_field_transport.hpp
+include/mbgl/particle/ingress/qbin_v2_decoder.hpp
+include/mbgl/particle/ingress/qbin_v3_decoder.hpp
+include/mbgl/particle/renderer_debug_counters.hpp
+include/mbgl/renderer/layers/weather_color_texture_lifecycle.hpp
+include/mbgl/renderer/render_segment.hpp
+include/mbgl/renderer/retained_underlay.hpp
+include/mbgl/shaders/gl/particle_gpu_validation.hpp
+include/mbgl/shaders/gl/retained_underlay_composite.hpp
+include/mbgl/shaders/mtl/particle_gpu_validation.hpp
+include/mbgl/shaders/mtl/retained_underlay_composite.hpp
+include/mbgl/shaders/particle_gpu_validation_ubo.hpp
+include/mbgl/style/layers/particle_validation_layer.hpp
+include/mbgl/style/layers/raster_particle_layer.hpp
+include/mbgl/style/layers/weather_color_layer.hpp
+include/mbgl/style/layers/weather_color_stop.hpp
+include/mbgl/style/sources/raster_array_source.hpp
+src/mbgl/layermanager/particle_validation_layer_factory.cpp
+src/mbgl/layermanager/raster_particle_layer_factory.cpp
+src/mbgl/layermanager/weather_color_layer_factory.cpp
+src/mbgl/particle/field/field_binding.cpp
+src/mbgl/particle/field/field_data_adapter.cpp
+src/mbgl/particle/field/field_profile_contract_json.cpp
+src/mbgl/particle/field/field_profile_validator.cpp
+src/mbgl/particle/field/field_projection_materialization.cpp
+src/mbgl/particle/field/field_runtime.cpp
+src/mbgl/particle/field/local_particle_field_feed.cpp
+src/mbgl/particle/field/offline_fixture_particle_adapter.cpp
+src/mbgl/particle/field/offline_fixture_particle_adapter.hpp
+src/mbgl/particle/ingress/qbin_v2_decoder.cpp
+src/mbgl/particle/ingress/qbin_v3_decoder.cpp
+src/mbgl/renderer/continuous_layer_range.hpp
+src/mbgl/renderer/layers/render_particle_validation_layer.cpp
+src/mbgl/renderer/layers/render_particle_validation_layer.hpp
+src/mbgl/renderer/layers/render_raster_particle_layer.hpp
+src/mbgl/renderer/layers/render_weather_color_layer.cpp
+src/mbgl/renderer/layers/render_weather_color_layer.hpp
+src/mbgl/renderer/particle_fast_path.hpp
+src/mbgl/renderer/particle_viewport_reseed.hpp
+src/mbgl/renderer/render_segment_json.hpp
+src/mbgl/renderer/render_segment_plan.hpp
+src/mbgl/renderer/retained_underlay_cache.cpp
+src/mbgl/renderer/retained_underlay_cache.hpp
+src/mbgl/renderer/retained_underlay_runtime_state.hpp
+src/mbgl/renderer/sources/render_raster_array_source.hpp
+src/mbgl/shaders/mtl/particle_gpu_validation.cpp
+src/mbgl/shaders/mtl/retained_underlay_composite.cpp
+src/mbgl/style/layers/particle_render_layer_properties.hpp
+src/mbgl/style/layers/particle_validation_layer.cpp
+src/mbgl/style/layers/particle_validation_layer_impl.hpp
+src/mbgl/style/layers/raster_particle_layer.cpp
+src/mbgl/style/layers/raster_particle_layer_impl.hpp
+src/mbgl/style/layers/weather_color_layer.cpp
+src/mbgl/style/layers/weather_color_layer_impl.hpp
+src/mbgl/style/sources/raster_array_source.cpp
+src/mbgl/style/sources/raster_array_source_impl.hpp
+```
+
+## 附录 D：可复现命令、退出状态与证据摘要
+
+以下 Python 仅执行 Git 读取和 merge-tree 干跑，并将输出/object 写入新临时目录，不执行真实 merge/rebase 或更新源码/index/ref。在同工作区与 Git 2.54.0 下运行；若原对象不足/网络不可用，保留退出码并报告阻塞，不将空 stdout 算零冲突。本轮未设置 merge.renames/directoryRenames/renameLimit 或 diff.renames/renameLimit 覆盖；检查这些配置未发现显式条目。
+
+```python
+import os, pathlib, subprocess, tempfile, json, re, collections, hashlib
+BASE = "18545ca10d296704b2cba675b182ff2c8da24588"
+OURS = "630ec657687bad4200c059bbccbb950d9c6f7ce9"
+TARGETS = {
+    "android": "c7506d6aff3800e946f89e1a51432fc22d1a6534",
+    "ios": "01791ad02c1bfe3b22c42a97619b972aba962f82",
+}
+root = pathlib.Path(tempfile.mkdtemp(prefix="upstream-001-reproduce-"))
+(root / "objects").mkdir()
+original = subprocess.check_output([
+    "git", "rev-parse", "--path-format=absolute", "--git-path", "objects"
+], text=True).strip()
+env = dict(os.environ, GIT_OBJECT_DIRECTORY=str(root / "objects"),
+           GIT_ALTERNATE_OBJECT_DIRECTORIES=original)
+def run(name, args):
+    r = subprocess.run(["git", *args], capture_output=True, env=env)
+    (root / (name + ".stdout")).write_bytes(r.stdout)
+    (root / (name + ".stderr")).write_bytes(r.stderr)
+    print(name, "exit", r.returncode,
+          "stdout-sha256", hashlib.sha256(r.stdout).hexdigest())
+    return r
+def paths(r):
+    if r.returncode != 0:
+        raise RuntimeError("路径 diff 未完成，停止计数")
+    return {line.split("\t")[-1] for line in r.stdout.decode().splitlines()}
+ours = paths(run("ours-paths", ["diff", "--no-renames", "--name-status", BASE, OURS]))
+for label, target in TARGETS.items():
+    run(label + "-base", ["merge-base", OURS, target])
+    run(label + "-diff", ["diff", "--name-status", BASE, target])
+    upstream = paths(run(label + "-paths", ["diff", "--no-renames", "--name-status", BASE, target]))
+    overlap = ours & upstream
+    r = run(label + "-merge", ["merge-tree", "--write-tree", "--messages", OURS, target])
+    if r.returncode not in (0, 1) or not r.stdout:
+        print(label, "BLOCKED，冲突数未知")
+        continue
+    lines = r.stdout.decode().splitlines()
+    unmerged = {m.group(1) for line in lines
+                if (m := re.match(r"[0-7]{6} [0-9a-f]+ [123]\t(.+)$", line))}
+    kinds = collections.Counter(m.group(1) for line in lines
+                                if (m := re.match(r"CONFLICT \(([^)]+)\)", line)))
+    clean = {p for p in overlap if p not in unmerged
+             and p.replace("/mbgl/", "/mln/") not in unmerged}
+    print(label, "tree", lines[0], "intersection", len(overlap),
+          "unmerged", len(unmerged), "types", dict(kinds), "clean-overlap", len(clean))
+    (root / (label + "-conflict-paths.txt")).write_text("\n".join(sorted(unmerged)) + "\n")
+print("证据目录", root)
+```
+
+本轮临时对象库：`/private/tmp/upstream-001-audit-20261009/objects`；只读 alternate：`/Users/tei/dev/MapLibreParticleLab/.git/objects`。这是审计 worktree 原本共享的 Git object 来源，未操作其它工作树源码或状态。
+
+| 证据文件（临时目录内） | SHA-256 | 说明 |
+| --- | --- | --- |
+| `ours-no-renames.txt` | `7e63240f4460f8c502dfec535b9fcbb0f11872ae221b87b550d68a05bb70bf48` | Git 路径证据 |
+| `android-rename-aware.txt` | `fa42160229b3407eeaa13fd90d0dfb9c4d7425e8f0dfa860b01db1ff7f18984c` | Git 路径证据 |
+| `ios-rename-aware.txt` | `e836b7699dc32c8300f8b0bfdcad16be17eeb526c48057d9a16cfa7734f32e61` | Git 路径证据 |
+| `android-isolated-default.stdout` | `3526b74fc8152e61f72641d571c16e9055500deb1cd31540f2eacf26047b4fb6` | 标准干跑，exit 1；复跑一致 |
+| `ios-isolated-default.stdout` | `d553091afaec4f381991bfbf6e60cd0d887177d5bccd172fac4f46e70f347261` | 标准干跑，exit 1；复跑一致 |
+| `android-conflict-paths.txt` | `4c61654d97bee7bca76879d9b828db8ca5c1d4a0610e3cfb6d43edeb73029039` | Git 路径证据 |
+| `ios-conflict-paths.txt` | `013ebe7121eaea79bf8491a1e3a55198e87acc7865b7b27bda6fdf81da993235` | Git 路径证据 |
+
+首轮失败见 `android/ios-diff.stderr`、`android/ios-merge.stderr`；原目录权限失败见 `android/ios-merge-no-renames.stderr`；成功命令与 rc 见对应 `.json`；复跑比对见 `android/ios-repeat.json`。对照禁用 rename 的 tree 为 Android `59de9836b81e90c3fef4a5a0377454bd464f5ef9`、iOS `b419b471131eb4fa3244e5cc3082ee7f2bd8e1e9`，仅用于证明 rename 口径影响，不用于迁移决策。
+
+已观察退出状态：标准干跑两线均 1（冲突），路径 diff/merge-base 0；原始失败 128；报告最终静态检查见下节。Codex 进程最终状态和 Git 发布回执由外层执行器/RDC 独立补证。
+
+## 附录 E：最终静态收尾记录
+
+- 报告内复现脚本已原样提取并执行，脚本退出 **0**；其中两次 merge-tree 各退出 **1**，Android 76 / iOS 78 个路径与正文完全一致。该脚本退出 0 只表示采集/计数完成，不是升级 PASS。复现临时目录 `/tmp/upstream-001-reproduce-58mf60um`，采集日志位于主证据目录 `embedded-reproduce.stdout/.stderr`。
+- `git diff --check`：退出 **0**，无输出；tracked 与 staged 的 `git diff --name-only` 均为空，退出 0。
+- 未跟踪报告另用 `git diff --no-index --check /dev/null <报告>` 检查：退出 **1**，stdout/stderr 均为空；这里 1 表示新增文件有差异，没有空白错误，不解释为测试失败或运行成功。
+- 报告要求的 11 个章节齐全，Markdown 围栏闭合；完整本地路径:行引用的文件均存在。冲突附录为 78 个并集路径，官方修改清单 85 个，新增 Core 清单 68 个。
+- 收尾 HEAD 仍为 `630ec657687bad4200c059bbccbb950d9c6f7ce9`；工作树只有以下两份未跟踪文档，没有源码或已跟踪文件改动：
+
+```text
+?? docs/40_任务/UPSTREAM-001_MapLibre官方升级兼容性架构审计_Codex任务_v1.md
+?? docs/报告/UPSTREAM-001_MapLibre官方升级兼容性架构审计_Codex完成报告_v1.md
+```
+
+任务书 SHA-256：`2e2ba4b5b1e94bedf0846cea616611eab758467a3e9ffaf01a4c8691fc01c112`。本轮没有编辑任务书，未 commit/push。最终外层 Codex 进程退出码仍待执行器回执，**Git 收尾待 RDC 验收**。