135 lines
15 KiB
Markdown
135 lines
15 KiB
Markdown
# STEP-114 Fast Path 安全准入与 Test App 闭环 Codex 完成报告 v1
|
||
|
||
日期：2026-10-11（JST）。
|
||
|
||
## 1. 执行结论
|
||
|
||
**PARTIAL：受控安全子集源码、独立最小场景与中文交付已完成；真实 Fast、编译和设备闭环未验收。Symbol R 准入 BLOCKED，CustomMVTVector 与非粒子 C 继续 fail-closed。**
|
||
|
||
核心结果：完整场景无任何结构性 Symbol 时，全局 Placement controller 的 stale 单独不再阻止 #13；有隐藏/空Symbol或AnnotationSymbol时保持原判定。R缺源明确报missing-source，仍拒绝Build/Reuse，revision登记机制不变。独立FAST_SMOKE用现有安全GeoJSON/circle R + WeatherColor/Particle C及真实Native计数；另交付3个反向场景，不直接注入candidate或人工Frame结果。
|
||
|
||
本机旧STEP-113 JSON明确navsea_delivery为普通Vector，R还依赖未在Native source表中的tide；不能把该unknown-dependency归因于CustomMVTVector。这项新事实已记录于调查，旧报告与正式PBF五场景不改。
|
||
|
||
## 2. 实际模型、Git与版本
|
||
|
||
- **GPT-6.1-Sol（gpt-6.1-sol）/ high**。实际从本机 `/Users/tei/.codex/sessions/2026/10/11/rollout-2026-10-11T09-44-12-01a1286a-d6a4-7e32-b91a-a9f3e63d8f3e.jsonl` 的最新 `turn_context.model/effort/cwd` 核实；未切换/升级模型，未启动子代理、另一实例或后台Codex。
|
||
- Mac / Darwin 24.6.0 / x86_64；仓库 `/Users/tei/dev/MapLibreParticleLab`。
|
||
- 起点branch=`particle/main`，start HEAD=`b02e54de3d45fcf612126ae8f037cba204f590ea`；无分支/worktree变更，未commit/push，收尾HEAD保持起点。
|
||
- 起点tracked clean；已有STEP-110/111/114三份未跟踪任务书。STEP-110/111原样保护，STEP-114只读不修改；暂存区未写。
|
||
- `git submodule status` 起点全部空格前缀，无未初始化或偏移标记；未操作子模块。
|
||
- Native/Test App=`13.6.1-particle.23`；没有改版本、RN公共方法/类型、Source Lock或发行。当前旧APK不包含本轮新源码。
|
||
- Integration相关正式Contracts/RFC/ADR只读；任务提供main=`80667d6c343411d03a760425438e3d292f452118`采用既有RDC事实，没有同步/fetch/pull或远端回读，没有跨项目写入。
|
||
|
||
## 3. 实际修改文件（tracked）
|
||
|
||
| 文件 | 实际内容与影响 |
|
||
|---|---|
|
||
| `src/mln/renderer/particle_fast_path.hpp` | 内部结构检测helper；非空完整层表无Symbol才可忽略controller transition；生产24Gate evaluator与失败掩码未改 |
|
||
| `src/mln/renderer/render_orchestrator.cpp` | #13输入按全场结构限定，层表数量不符保守；缺RenderSource先报missing-source；CustomMVT拒绝仍保留 |
|
||
| `test/renderer/retained_underlay_cache.test.cpp` | 3个Step114FastPathSafety用例源码：无Symbol/其它Gate保护，隐藏/空/AnnotationSymbol保护，revision/cache注册/异步失效/全局失效状态机 |
|
||
| `platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt` | 独立菜单/Intent/状态恢复、统一场景退出、诊断区域与前后台生命周期；原STEP-113菜单明确标正式PBF |
|
||
| `粒子开发记录.md` | 仅末尾追加本轮中文状态与下一步 |
|
||
|
||
## 4. 实际新增文件
|
||
|
||
1. `platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/Step114FastSmokeScene.kt`：独立离线FAST_SMOKE/3负场景，真实Native低频UI、操作前后文件、Source/Image/Camera/缓存/真实Annotation操作及Reload/生命周期取证。
|
||
2. `docs/20_调查/STEP-114_FastPath安全准入与闭环判定_v1.md`：R/C/Placement控制流、旧JSON事实、mutation追踪、安全前提/反例及停止范围。
|
||
3. `docs/60_测试/STEP-114_独立FastSmoke场景与RDC验收_v1.md`：场景说明、Mac精确定向命令、后续Android用户手工命令、实际JSON正向检查与反向/生命周期矩阵。
|
||
4. `docs/50_Step记录/STEP-114_FastPath安全准入与TestApp闭环_v1.md`：已做/未做勾选、真实结果与待验收表。
|
||
5. 本报告。
|
||
|
||
用户提供的未跟踪STEP-114任务书不是本轮生成物。旧STEP-110/111未跟踪文件未修改/暂存；原STEP-113场景类与STEP-102 fixture未修改。
|
||
|
||
## 5. 安全范围、兼容与零修改部分
|
||
|
||
R准入/RevisionBook/GPUcache算法零语义修改；缺源只修正诊断原因。没有证明CustomMVT完整revision契约，保留其拒绝。普通Vector和GeoJSON不是CustomMVT，不混淆类型。独立GeoJSON子集现有sourceDiff/immutable signature/onTileChanged/资源epoch/key保护详见调查。
|
||
|
||
非粒子C准入与Scene复合条件零修改，#22/#23保留。FAST_SMOKE独立Style在没有Annotation实例时移除其空内建layer；保留source，不改AnnotationManager。ANNOTATION_BLOCKED重新加载合法Style，保留内建layer并创建真实marker；不是生产零重载Annotation能力。原正式PBF五场景完整保留。
|
||
|
||
Symbol R的Build gate、commit/fade、scene placementStable、全图碰撞、controller计算、资源链均零修改；无最终GPU输入结果证书，停止新增签名设计。#13改动只影响完整无Symbol场景；空表/数量不一致保守，有一个隐藏/空Symbol也按原transition阻止。尚未进入旧表的新layer被immutable signature、Annotation pending和其它原Gate保护。
|
||
|
||
Shared Core没有平台分叉，没有新RN/JS/JNI控制API/ABI。既有可选诊断schema和24Gate顺序未改；缺源理由从模糊unknown-dependency变为已有理由missing-source是有意诊断差异。preFastPlacementTransition为本轮限定后的实际输入，post原始placementTransitionActive可能仍true；此差异不是shadow mismatch，也不是修改controller。
|
||
|
||
风险/限制：Native与Kotlin未编译；FAST_SMOKE尚未实测；本地sceneReady不是Native运行PASS；自动短延迟采样可能漏瞬态；App私有快照文件随显式操作增长；性能/像素/GL与Metal差异未测。Future新Placement-capable类型须同步扩展结构检测，当前只有Symbol声明CrossTileIndex::Required。
|
||
|
||
## 6. 与任务书差异与停止点
|
||
|
||
按步骤完成源码审查与可安全范围实现；任务允许PARTIAL。没有危险地放行CustomMVT、Annotation C或Symbol R，也没有复刻NavSea113层。R cache正向利用现有已支持GeoJSON，不新增未证source准入。新增无Symbol场景#13限定是调查中确认的安全局部修复；缺源更准确诊断使真正失败点可见。
|
||
|
||
真实Fast/反向/lifecycle闭环仍待执行。Symbol R结果证书需要更大跨平台设计，列BLOCKED；若涉及公共语义/API，回Integration RFC，不自行扩改。任务允许改测试源但禁止Codex运行编译/测试，遵守该边界。
|
||
|
||
## 7. 精确定向 RDC 验收命令
|
||
|
||
下面只交RDC/普通Terminal执行。进入仓库后逐项执行，任何失败立即停止链，保留完整日志，不用旧runner；带完整退出码保护的可复制脚本在测试说明第2节。
|
||
|
||
```bash
|
||
cd /Users/tei/dev/MapLibreParticleLab
|
||
cmake --preset macos-metal
|
||
cmake --build build-macos-metal --target mbgl-test-runner --parallel 3
|
||
build-macos-metal/mbgl-test-runner --gtest_filter='Step114FastPathSafety.*:FastGateTrace.*:ParticleFastPath.*:RetainedUnderlayCache.*:RetainedUnderlayRevision.*:RenderSegmentPlacementFree.*:RenderSegmentLocality.*:RenderSegmentPlan.*:RenderSegmentDiagnostics.*:RenderOrchestratorError.*:RenderOrchestratorTeardown.*:ImageManager.*:GlyphPBF.*' --gtest_color=no
|
||
```
|
||
|
||
renderer=Metal，Debug preset，parallel=3，target仅mbgl-test-runner。记录命令/exit/耗时/log路径/实际用例数量/skipped；新增3个Step114用例必须被发现并执行。STEP-113缺libuv的配置失败日志仍是既有证据，本轮未再次配置、未安装依赖；若仍失败，保留首错并记BLOCKED，不能宣称测试通过。
|
||
|
||
Android由用户后续一次手工运行 `./tools/particle_android_validation/build_validation_apk.sh`；其后手工安装/启动/取证命令逐条见测试说明第3—5节，固定serial=`192.168.200.139:5555`。入口Intent=`--es step114_scenario FAST_SMOKE`，三个负场景名为CIRCLE_C_BLOCKED/ANNOTATION_BLOCKED/SYMBOL_R_BLOCKED。完整快照为App files/step114-*.json；保存source/image/camera/cache动作前、提交后、100/500/1500ms证据。Codex没有执行这些命令。
|
||
|
||
## 8. 已执行检查与未执行验收
|
||
|
||
已执行：前置规范/任务/实际源码阅读，Git branch/HEAD/status/submodule只读；本地当前rollout模型字段核实；保留的STEP-113JSON解析、SourceType与缺tide取证；无构建静态函数/范围/哈希/追加完整性核对；tracked及新增文件空白检查。
|
||
|
||
**NOT RUN**：CMake/Ninja/Bazel/Native编译链接、C++测试、Kotlin编译、Gradle/APK/AAR、ADB/安装/logcat/截图/设备、Jest、性能/GPU/像素对照、iOS实机、发行、commit/push/远端HEAD。没有本轮编译/测试失败日志，也不能据此推断会通过。3个新增C++用例是源码交付，不是运行PASS；状态机markBuildSucceeded不是GPU成功证据。
|
||
|
||
静态检查的最终实际结果与保护哈希在第12节记录。终态仍有本轮tracked/untracked改动，未暂存、未提交。
|
||
|
||
## 9. 产物
|
||
|
||
实际产物仅源文件、测试源、四份中文文档与开发记录追加。无本轮APK/AAR/XCFramework、版本/SHA、构建/设备日志或运行截图。artifact目录的STEP-113JSON属于旧RDC证据，本轮只读未修改，不作为本轮新产物。
|
||
|
||
## 10. 剩余阻塞与未完成事项
|
||
|
||
| 项目 | 状态/原因 |
|
||
|---|---|
|
||
| 独立smoke真实Fast | 未验证；必须NativeFull/Fast/Build/Reuse及24Gate和截图共同证明 |
|
||
| Mac配置/编译/测试 | 未执行；旧libuv阻塞是否仍存在未知 |
|
||
| Android编译与设备闭环 | 未执行，留用户一次手工统一验收 |
|
||
| Source异步变化/资源/camera/cache/Reload/前后台/销毁 | 已有源码和精确取证入口，运行证据待执行；捕获失败不可假称安全反向PASS |
|
||
| Glyph实际结果/资源失效 | 未新增TestApp glyph控制；无Symbolbaseline不含glyph像素；现有资源回归不能代替Symbol证书 |
|
||
| Symbol R首次Build | BLOCKED；commit/fade没有充分稳定结果证书，不做危险简化 |
|
||
| CustomMVT/非粒子C | fail-closed；无完整revision/复合等价证明 |
|
||
| PBF缺tide/大量Symbol | 缺源诊断已清楚，原数据/业务层不改；不承诺生产Fast |
|
||
| iOS/Metal设备与CPU/GPU收益 | NOT VERIFIED；不以Android或Mac状态机结果替代 |
|
||
|
||
## 11. 独立验收证据与后续
|
||
|
||
RDC先核对本报告/调查/源码diff与安全前提，再跑Mac定向命令；用户后续统一Android。baseline必须真实4层与R[0,2)/C[2,4)，至少一个completed fast-rendered、knownMask=0xffffff/failMask=0、decisionMismatch=0、cacheInputs valid/revision相等，Full>0、Build>0、同生命周期Fast/Reuse delta>0；同时截图确认Rcircle/天气/粒子及反向重建正确。测试说明含读取真实JSON的断言。
|
||
|
||
负场景必须继续阻止Fast并正确显示/更新内容；Source/Tile/Image/Camera/缓存禁用/Reload/前后台/Teardown、旧PBF5场景及STEP-102独立回归仍需日志/快照与可见结果。只见Fast数字不等于安全/性能PASS。若未达真实Fast维持PARTIAL，失败保留现场再返回受控修复。
|
||
|
||
本轮禁止Git提交/push；后续达合理门槛且获授权后RDC仅scoped提交本轮明确路径并核对origin远端HEAD。不得含原STEP-110/111，不发行，不自行创建后续Step。
|
||
|
||
## 12. 收尾静态事实
|
||
|
||
- `git diff --check` 退出0；五个tracked修改路径，无其它tracked修改。四份新中文文档与新Kotlin文件各执行no-index空白检查，无诊断；Markdown代码围栏成对。
|
||
- 生产`evaluateParticleFastPath`和`particleFastGateFailureMask`与HEAD提取的完整函数逐字相同；C范围准入、R全局/局部稳定性函数逐字相同，CustomMVT拒绝分支仍在。3个新增用例仅核对源码数量，未运行。
|
||
- 原`Step113PbfGateScene.kt`与HEAD字节相同，SHA-256=`6e7befeb90ae172aaeff4b636a7640274dfb1065d8c97744cbc6af8d22b4ccae`；`Step102PlacementFixture.kt`同样未变，SHA-256=`e44912970dd6353787be7a3e5f9924fe1249e2305d495f1e25e707352c97d3c7`。
|
||
- 开发记录的HEAD原始162365字节前缀完整保留，原SHA-256=`0479875a30577cb497b973f89a0d74b3b8b8d300d5dfb683ed3a537749b37b3f`；仅9行/1583字节追加。
|
||
- STEP-110 SHA-256=`33037df71b4b30aa7956d59f4b99f77af3085405b24111bc0fe11ec857a93db0`，STEP-111=`f3a5806f25384bf46055db2edfea0d21bfbc4124184bc813b46e38b8079c1ec4`，与既有保护值相同；本次任务书只读SHA-256=`415c20df0e8d514b68dfa79cd6d9394e4c6d2c4f215c402d9a4a365862c87cfc`。
|
||
- 旧RDC完整`source-change-after-full.json`只读SHA-256=`24a06fa1cb072a628c650723c58a880895ec656f4972fa55d3cb064bfb2aabda`；本轮新场景需要的两个cycle各metadata.json/field.f32已静态确认存在。
|
||
- 一次用Python stdin追加中文记录的尝试因UTF-8源码解析退出1，未写文件；随后用apply_patch完成追加。最终原前缀核对通过。这是工具文本编码失败，不是构建/测试失败。
|
||
- 终态`particle/main@b02e54de3d45fcf612126ae8f037cba204f590ea`；`git diff --cached --name-only`为空。status为本轮5个tracked修改、5个新增文件，以及原有STEP-110/111/114三任务书；未commit/push/回读远端。
|
||
|
||
以上只证明静态一致性、范围与保护文件完整性，不作为Native/Kotlin编译、GPU/Fast或全任务PASS。
|
||
|
||
|
||
## RDC 独立审核追加（2026-10-11）
|
||
|
||
**结论：源码/差异/接口静态审核 PASS；Native 与 Android 编译、Fast 帧 NOT VERIFIED；整体 STEP-114 PARTIAL。**
|
||
|
||
- RDC 独立阅读本轮 Native diff、C++ 新用例、STEP-114 Android Test App 新场景与菜单、生命周期接线；git diff --check 退出码 0。本轮只有范围内的五个 tracked 改动和新增 Kotlin/中文文档；原 STEP-110/111 未跟踪任务书不修改、不暂存。
|
||
- 新增三项 Step114FastPathSafety 用例存在，覆盖无 Symbol、隐藏/Annotation Symbol 和 Source revision/cache 状态机，但**没有实际运行**。
|
||
- Step113PbfGateScene.kt SHA-256 为 6e7befeb90ae172aaeff4b636a7640274dfb1065d8c97744cbc6af8d22b4ccae，Step102PlacementFixture.kt SHA-256 为 e44912970dd6353787be7a3e5f9924fe1249e2305d495f1e25e707352c97d3c7，均未变化。
|
||
- Java SDK 只读核对实际提供 Style.removeLayer(String) 与 MapLibreMap.getAnnotations()。Kotlin/Gradle 编译未执行。
|
||
- Mac 预检：pkg-config --exists libuv 返回 1，与先前 macos-metal CMake required libuv 失败一致。独立 C++ header -fsyntax-only 试验退出码 1，首错为 Xcode AppleClang 找不到标准 C++ 头文件 array，实际在进入项目源码检查前终止。日志存于 Mac /tmp/step114-header-check.log。两项均是环境阻塞，不是本轮 Native 测试 PASS 或已证明代码错误；未安装/修改依赖。
|
||
- 实际 Fast Path 命中、正反 GPU 渲染、Android 设备、性能、iOS 均未验证。正式 PBF 仍有 tide 缺源、Symbol R Placement、内建 Annotation C 的阻断。STEP-114 独立最小场景属于待用户一次 Android 手工构建集中验收内容，不能用旧 APK。
|
||
- 后续 scoped Git 收尾若执行仅表示 PARTIAL 源码及测试入口已归档，**不代表正式发布或 Fast Path 修复完成**，不打 Tag/Source Lock。
|