MapLibreParticleLab/docs/40_任务/STEP-114_FastPath安全准入与TestApp闭环_Codex任务_v1.md

STEP-114：Fast Path 安全准入受控修复与 Test App 闭环（Codex 任务 v1）

执行授权与基线

• 用户明确同意继续受控修复，不要求完全复刻 NavSea 113 层。
• Mac 仓库 /Users/tei/dev/MapLibreParticleLab，particle/main 起点 b02e54de3d45fcf612126ae8f037cba204f590ea。Integration 最新 main 80667d6c343411d03a760425438e3d292f452118 经 RDC 验证。
• Codex 固定 GPT-6.1-Sol High (gpt-6.1-sol / high)。先读 AGENTS.md、PARTICLE_BASELINE.md、docs/00_项目规范、docs/00_项目总则/README.md 及四份有效总则、STEP-112/113 报告、Integration 的正式 Contracts/RFC/ADR，严格遵守项目边界。
• 本轮 Codex 只改代码与文档；不能运行 Android Gradle、ADB、Jest、CMake/Ninja/Bazel 大编译或正式打包；Native 定向验证由 RDC 另行执行，Android 编译由用户在授权条件下手工统一验收。
• 不碰原有两份未跟踪 STEP-110/111 文件、无关文件、NavSea 源码和 Integration；禁止 git add -A / reset --hard / clean；不得变更 RN/JS 公共 ABI/API、发行版本或 Source Lock。

根因事实

• STEP-113 STATIC_RC 66 Native layers，R[0,63) Build=0、unknown-dependency；C[63,66) 含天气色场、粒子、内部 Annotation Symbol。Fast=0。
• 119 个最新 completed Full 帧：24 Gate shadow mismatch=0；#3 cache invalid、#4 revision mismatch、#22 unsupported continuous layer、#23 unsupported scene 全部失败；#12/#13 placement 105 帧失败。
• RenderOrchestrator::retainedSegmentSourceState 对 CustomMVTVector 明确 fail-closed，已有源码注释说明无 retained cache revision contract；不得删掉这个限制来伪造 Fast。
• continuousRangeSupportsParticleFastPath 要求 C 全层以 Particle dynamic API 标记；内部 Annotation Symbol 不满足，且 #23 聚合依赖部分与 #22 重合。
• STEP-112 证明含结构性 Symbol 的 R 在旧 Placement stale/changed/fade 时可能根本无法进入首次 Cache Build；禁止只删条件或假设视觉没变。

实施步骤（依次、受控）

1. 做当前源码静态闭环：明确 Test App 对应 SourceType、Source/Tile/Style/Glyph/Image/Annotation mutation 追踪、R 的初建失败点、C 准入及 Scene 复合条件、Placement 控制流。
2. R 缓存：只对确有完整 Source revision 与异步失效追踪的类型建立安全准入；若 CustomMVTVector 无法严格证明，保留其 fail-closed。优先为已支持的保守 source 子集提供可用的独立 R-cache 正向测试。保留 Source mutation、Tile update、camera、style reload、image/glyph、destroy/reset 的反向用例。
3. C 非粒子层：只有证明原有 GPU 复合内容/Source revision/Placement/Annotation 在静止场景与 Full 等价、变化时 Full 回退，才能受限放行。否则不可移除 Gate #22：可通过单独 Test App 最小场景或安全 Layer 拓扑证明能进入 Fast。不要丢失原始正式 PBF 5 场景。
4. Symbol R Placement：基于已提交的真实 Placement/资源 revision 与 transition/fade 审核是否有安全稳定窗口；如须新增独立结果签名或其他跨平台设计，停止该项并在报告中写 BLOCKED，不做危险简化。
5. 优先实现独立 Test App FAST_SMOKE 场景（如安全可行），按 UI 菜单明确区分正式 PBF 与独立最小场景。使用 Native 真实 Full/Fast/CacheBuild/Reuse 计数和24 Gate JSON，测试稳定、Source mutation、Annotation、Pan/Zoom、Reload、前后台/Teardown；不许伪造 Frame 结果或直接注入 candidate=true。
6. 所有公共 Shared Core 代码仍跨 Android/iOS 共用，不得建立平台分叉。任何需要改公共语义/API的部分暂停，留给 Integration RFC。

测试/运行要求

• 可改/新增现有非 Jest C++ 相关测试源，但 Codex 不执行测试/编译。
• 必须写出 RDC 可以执行的精确定向 Mac Native 检查命令；后续 Android 编译和设备 Gate 集中一次进行。
• 只证明能证明的部分；可产出 PARTIAL / BLOCKED 与可用局部修复，不允许“关掉Gate提升Fast数字”。

必做输出

1. 本次实际修改的 C++、Android Test App 和非 Jest 测试源（不能安全改的部分写明零修改）。
2. docs/20_调查/STEP-114_FastPath安全准入与闭环判定_v1.md：R/C/Placement 证据、可能的反例、实现范围、安全前提、实际测试方案。
3. docs/50_Step记录/STEP-114_FastPath安全准入与TestApp闭环_v1.md：当轮修改、状态、验证事实及后续步骤。
4. docs/报告/STEP-114_FastPath安全准入与TestApp闭环_Codex完成报告_v1.md：模型全名档位、改动文件、影响/兼容、RDC 具体命令、已做/未做的验收、Git check。
5. 追加中文 粒子开发记录.md：当前改动、当前状态、下一步。
6. 新增 Test App 入口时更新相关场景说明，清楚区分真实 PBF 与独立 smoke。
7. 文档必须实际写入并保留，不能任务后要求用户补交。

Git 收尾

• Codex 只能执行无构建型静态检查与 git diff --check，回报 git status 和必要的验证命令；禁止将未运行的测试写成 PASS。
• Codex 完成后先停下由 RDC 独立审计/运行定向检查；阶段结果达到合理门槛后由 RDC scoped commit 到 particle/main 并 push origin，核验远端 SHA。若未达真实 Fast，不得标示 Fast Path 已修复。正式发行独立处理。