# STEP-117 FZG1 原 PBF 真实 Fast 验收计划 v1

日期：2026-10-11（JST）。**本计划全部运行命令交RDC/普通Terminal；Codex本轮未执行。当前安全准入BLOCKED，测试源码交付不表示真实Fast已修复。**

## 1. 执行顺序与停止条件

先独立审计STEP117调查、diff和七项测试，确认B1缺源零贡献与B2 Symbol结果证书仍未实现。本轮只有测试/文档，不应期待重新打APK获得不同Fast行为。RDC可先验证C++回归；粒子负责人协调Shared Core证书设计及正式tide语义，再授权具体实现。完成可证明的实现并复核后，安排一次完整Android build/install/原STATIC_RC集中验收。

本任务不授权Codex执行任何Native编译/测试、Gradle/ADB/安装、Jest、commit/push。RDC后续Git收尾须按独立授权scoped提交，核对origin远端HEAD，保护STEP110/111。Android与设备命令只能在用户明确授权的对应阶段执行。当前缺libuv历史记录只用于排查；不跳过失败、不改门槛、不运行旧runner、不改build-info使旧包冒充新源码。

遇到编译/测试失败、Source/Style版本不符、mismatch>0、未知Gate、错误恢复/漏内容或Fast仍为0，保存首个真实error/target及完整日志路径，停止相应通过判定。不要换STEP114烟测、删原层或补假tide来继续。

## 2. 独立源码与定向Native验收

```bash
cd /Users/tei/dev/MapLibreParticleLab
git branch --show-current
git rev-parse HEAD
git status --short
git diff --check
git diff -- test/renderer/retained_underlay_cache.test.cpp test/renderer/render_orchestrator_error.test.cpp 粒子开发记录.md
shasum -a 256 docs/40_任务/STEP-110_R0_Placement跨段归因只读调查_Codex任务_v1.md docs/40_任务/STEP-111_R段Placement结果等价与独立刷新可行性只读调查_Codex任务_v1.md
```

STEP110/111预期SHA分别为 `33037df71b4b30aa7956d59f4b99f77af3085405b24111bc0fe11ec857a93db0`、`f3a5806f25384bf46055db2edfea0d21bfbc4124184bc813b46e38b8079c1ec4`。查看新增四份文档及报告静态核查章节。生产src/include/Shader/TestApp/旧测试断言应与起点保持一致；不得把test fixture的markBuildSucceeded或测试线程注入事件当作实际GPU/并发完成。

以下逐项串行运行，上一项失败立即停止。使用当前Mac配置的CMake；如果PATH没有cmake，可用已配置的 `/Users/tei/Library/Android/sdk/cmake/3.31.6/bin/cmake`，不得自行升级依赖。

```bash
cmake --preset macos-metal
```

```bash
cmake --build build-macos-metal --target mbgl-test-runner --parallel 3
```

```bash
build-macos-metal/mbgl-test-runner --gtest_filter='Step117Safety.*:Step116Safety.*:Annotations.*:RenderOrchestratorError.*:RenderOrchestratorTeardown.*:FastGateTrace.*:ParticleFastPath.*:RetainedUnderlayCache.*:RetainedUnderlayRevision.*:RenderSegmentDiagnostics.*:RenderSegmentPlacementFree.*:RenderSegmentLocality.*:RenderSegmentPlan.*' --gtest_color=no
```

新增Step117Safety必须实际运行7项，不能以filter未匹配的exit0通过。test/CMakeLists.txt已登记两个源文件，不需要绕过原target。记录当前HEAD、runner构建来源、命令、exit/耗时、用例数量、完整日志路径。Annotations.Step116是实际出图比较；其通过也不替代原PBF的Symbol结果证明。Mac Metal runner成功不代表Android OpenGL或iOS设备PASS。

## 3. 一次未来授权的Android制品闭环

在B1/B2受控实现完成、源码已锁定且tracked clean后，用户授权RDC/普通Terminal逐项执行标准Pipeline。保护未跟踪MD保留，git_dirty=true需结合tracked状态判断。记录真正的源HEAD，不能拿本轮起点43e5f5b当作包含未来实现的提交。

```bash
cd /Users/tei/dev/MapLibreParticleLab
git rev-parse HEAD
git status --short
./tools/particle_android_validation/build_validation_apk.sh
```

Pipeline必须Java17、OpenGL/x86_64、strip，成功后核对ZIP、唯一ABI、libmaplibre.so、体积、完整build.log/build-info与SHA；失败不复用旧APK。版本名13.6.1-particle.23本身不能标识源码。

```bash
cat artifacts/maplibre-particle/android-validation/build-info.txt
shasum -a 256 artifacts/maplibre-particle/android-validation/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk
/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 install -r artifacts/maplibre-particle/android-validation/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk
```

不得卸载/清数据。设备serial须重新核实为FZG1-2；变化时显式记录并修改后续参数。回读已安装base.apk SHA，由以下现有工具复核同HEAD/本地APK/设备安装包：

```bash
python3 -B tools/particle_android_validation/verify_step113_fast_path.py --adb /Users/tei/Library/Android/sdk/platform-tools/adb --serial 192.168.200.139:5555 --preflight-only
```

STALE_APK、SOURCE_NOT_LOCKED、ABI/SHA不符立即停止。PREFLIGHT_PASS仅说明版本闭环；旧c48a72a9 APK与本轮源码HEAD不同，即使生产文件未改也不能修改来源记录。

## 4. 原STATIC_RC≥90秒正式验收

```bash
python3 -B tools/particle_android_validation/verify_step113_fast_path.py --adb /Users/tei/Library/Android/sdk/platform-tools/adb --serial 192.168.200.139:5555 --scenario STATIC_RC --seconds 90
```

从取得同PID起实际观察至少90秒，取得前后同sceneGeneration/lifecycle的摘要，计数单调、不撤销、不重置。保存result.json/logcat/launch、实际观察秒数。exit2/NO_FAST_OBSERVED如实失败；exit3为版本/环境阻塞。FAST_OBSERVED只是必要条件。

正式通过同时要求：

- 原Style的63基础层定义/顺序保留，记录productionFingerprint与baseLayerManifest、productionSources；原Style/Sprite/Glyph/Vector URI一致。若服务器内容改变导致fingerprint或层数不同，停止跨版本比较，交Style所有者协调。
- STEP116空SDK Annotation规则保留：零实例后一次受控移除points，Source保留；原C正常只有WeatherColor+Particle，Native65层/R[0,63)/C[63,65)。后续真实Annotation/Style改变不得被再次删除。
- 实际每个R Cache Build>0、Reuse>0，同生命周期FastDelta>0；completed fast-rendered帧必须cacheValid/revision一致、24Gate已知且全部PASS、mismatch=0。pending帧不计成功。
- 缺源准入若未来获证书，必须能回读该absent source的零绘制/旧数据排除及同名恢复失效证据；missingSourceIds非空不能自动通过，也不能简单规定非空一律失败而回避新证书审查。
- Symbol缓存绑定成功提交的R结果证书，列出受影响bucket/atlas/collision/opacity/动态属性/camera/context和变更代次；源码/设备证据中不得强制清三字段或改Gate。
- 用户验收底图、海岸/等深线、航标、文字、天气色带与粒子，无漏内容/闪烁/层序错误；同条件Full/Fast像素对照及资源变化回退分别取证。性能提升需额外相同条件测量，不能从Full减少单独推断。

## 5. 完整120帧与用户画面

同次运行在STEP093→STEP113菜单手动EXPORT LAST SNAPSHOT。导出由用户触发，RDC回读同次generation/lifecycle的文件；确认文件名/时间不属于旧运行。以下shell命令逐项执行，任何失败立即停；变量只用于本次任务：

```bash
mkdir -p artifacts/maplibre-particle/android-validation/step117
step117_file="$(/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 shell run-as org.maplibre.android.testapp ls -t files | tr -d '\r' | grep -E '^step113-STATIC_RC-.*[.]json$' | head -n 1)"
test -n "$step117_file"
/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 exec-out run-as org.maplibre.android.testapp cat "files/$step117_file" > artifacts/maplibre-particle/android-validation/step117/static-rc-full.json
shasum -a 256 artifacts/maplibre-particle/android-validation/step117/static-rc-full.json
/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 exec-out screencap -p > artifacts/maplibre-particle/android-validation/step117/static-rc-screen.png
/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 logcat -b crash -d > artifacts/maplibre-particle/android-validation/step117/crash.log
```

完整JSON离线结构核对示例（不是新安全证书/性能验收）：

```bash
python3 -B - <<'PY'
import json
from pathlib import Path
v = json.loads(Path('artifacts/maplibre-particle/android-validation/step117/static-rc-full.json').read_text())
assert v['scenario'] == 'STATIC_RC' and v['sceneReady'] and not v['blockedReason']
assert v['styleParity']['baseLayerCount'] == 63 and v['styleParity']['baseLayersPreserved']
assert v['commands']['emptyBuiltinAnnotationLayerRemoved']
assert v['commands']['annotationInstancesAtRemoval'] == 0
assert v['commands']['annotationSourcePreserved']
n = v['native']; t = n['fastGateTrace']; fs = t['frames']
assert n['valid'] and n['styleLayerCount'] == 65
assert len(fs) == t['windowCount'] == 120
assert len(t['gates']) == 24 and t['decisionMismatch'] == 0
assert [g['order'] for g in t['gates']] == list(range(1, 25))
assert all(f['knownMask'] == 0xffffff and f['decisionConsistent'] and len(f['gateStatus']) == 24 for f in fs)
assert all(a['sequence'] < b['sequence'] for a, b in zip(fs, fs[1:]))
assert all(f['post'] is not None for f in fs if f['completed'])
assert all(f['post'] is None for f in fs if not f['completed'])
assert [(s['strategy'], s['beginIndex'], s['endExclusive']) for s in n['segments']] == [
    ('RETAINED', 0, 63), ('CONTINUOUS', 63, 65)]
fast = [f for f in fs if f['completed'] and f['outcome'] == 'fast-rendered']
assert fast, '原PBF当前窗口没有完成Fast帧；保持FAIL/BLOCKED'
assert all(f['failMask'] == 0 and all(c['exists'] and c['valid'] and
    c['buildRevision'] == c['staticRevision'] for c in f['cacheInputs']) for f in fast)
assert all(s['cache']['build'] > 0 and s['cache']['reuse'] > 0 for s in n['segments'] if s['strategy'] == 'RETAINED')
print('必要结构/计数成立；继续检查证书、同次SHA/manifest、变更前后帧与用户画面')
PY
```

在当前STEP117无准入实现的代码上，Fast/Build断言预期不能通过；不得删除这些断言制造PASS。pre为上一完成树，post/full为本次完成树；#13另取当前controller，不能混为同帧。环形窗口可能覆盖变更瞬间，必须每项操作前/后及时导出；未捕获则NOT VERIFIED。

## 6. 安全反例与旧五场景

| 操作 | 必须取证的正确行为 | 当前入口/限制 |
|---|---|---|
| 初始缺源 | 没有证书时missing-source、Build/Fast0；未来证书需证明双group零贡献和无旧数据 | 原STATIC_RC真实缺tide；不补造source |
| 同名source创建/重建/数据到达 | 下一次尝试Full，旧证书和cache失效；真实内容可见后才重建 | 新C++真实sourceDiff用例及状态机；当前App没有生产tide注入入口，需Integration/真实来源协调，设备项NOT VERIFIED |
| 已有旧Symbol后缺源/合法Style替换 | 两类group停用请求执行，旧drawables/buckets排除；不得复用旧R | 当前测试只有registry生命周期，无实际GPU旧数据证书；必须追加真正渲染用例后验收 |
| Tile/Glyph/Image异步更新 | #5/#8/#14或对应稳定性Gate拒绝旧Fast，受影响R重建；未加载/fading继续fail-closed | C++回调注入不等同网络并发；实际资源延迟与事件顺序需独立工具/测试授权 |
| Symbol collision/fade/anchor/orientation/沿线 | Full/Fast最终像素等价；所有碰撞受害R失效；时间相关opacity不能冻结 | 结果证书当前不存在；不能用默认空桶测试代替 |
| Source mutation | 保留原SOURCE_CHANGE circle负例和手动MUTATE PROBE SOURCE ONCE；记录sourceId/affectedSegmentIndices与真实Full | 当前probe属C，不能冒充R的tide恢复 |
| Style mutation/重排/添加 | non-camera/topology/fingerprint拒绝旧树；内容不删除 | 原入口无自动全矩阵；没有触发能力则NOT VERIFIED |
| 真实Annotation add/no-op update/reload | STEP116同步恢复points并可见；#24/层表拒绝旧Fast；空层验收条件撤销 | Annotations.Step116图像回归和用户合法操作；不可周期删真实层 |
| Camera/viewport/pixelRatio/projection | #6/#7/#8、cache key/context失效，Full后正确重建，无拖影或错位 | 用户pan/zoom/rotate/pitch/resize；逐事件导出 |
| context/后台/恢复/disable/退出场景 | PreparedTree/资源正确失效释放，无旧GPU数据复活 | 用户设备生命周期及Native实际Renderer测试；现有callback用例不替代 |

原五场景依次独立运行、分别保存日志/导出/画面。以下复测工具命令由RDC在同SHA预检后执行，SOURCE_CHANGE保留普通circle与Annotation负例：

```bash
python3 -B tools/particle_android_validation/verify_step113_fast_path.py --adb /Users/tei/Library/Android/sdk/platform-tools/adb --serial 192.168.200.139:5555 --scenario PBF63 --seconds 90
python3 -B tools/particle_android_validation/verify_step113_fast_path.py --adb /Users/tei/Library/Android/sdk/platform-tools/adb --serial 192.168.200.139:5555 --scenario PARTICLE_OFF --seconds 90
python3 -B tools/particle_android_validation/verify_step113_fast_path.py --adb /Users/tei/Library/Android/sdk/platform-tools/adb --serial 192.168.200.139:5555 --scenario PARTIAL_RCRR --seconds 90
python3 -B tools/particle_android_validation/verify_step113_fast_path.py --adb /Users/tei/Library/Android/sdk/platform-tools/adb --serial 192.168.200.139:5555 --scenario SOURCE_CHANGE --seconds 90
```

受保护负例可能预期Fast0，exit2应按场景语义记录，不能调整工具返回码或删除负例。STATIC_RC正式正例仍要求真实Fast，不接受STEP114 FAST_SMOKE替代。

## 7. 最终证据包

RDC回填：锁定源HEAD与精确diff/相关源码SHA、scoped提交与远端HEAD（若获授权执行）、Native配置/构建/七测试日志、首错/阻塞；build-info/build.log/APK与安装包SHA、设备型号/serial；原Style fingerprint/63层manifest/C层表；同次90秒摘要、120帧完整JSON及SHA、每项24Gate/cache/Full/Fast/pre/post；Mutation前后/异步/碰撞/GPU生命周期证书；用户画面及同条件Full/Fast对照。

没有证书保持BLOCKED；编译成功、静态检查、PREFLIGHT_PASS或测试进程exit0不能代替原PBF真实Fast安全验收。