STEP-116 STEP-113 原 PBF 专用 APP 验收 v1

日期：2026-10-11（JST）。以下命令交 RDC / 用户执行，Codex 本轮全部未运行。 本轮源码状态 PARTIAL；缺 tide 与 Symbol R 准入仍阻塞，预期仍可能 Fast=0。不得拿 STEP114 Smoke 或旧 V23 APK 替代原 STATIC_RC。

1. RDC 源码锁定和 Native 定向验证

先重新读取 AGENTS、当前基线、STEP-116 审查/报告与 diff。审计包含 Native Annotation 修复的线程/生命周期、原63层逐层定义/顺序、移除对象重载、stop恢复、后续marker/style添加、五场景分支、生产Gate未变和七项新测试。执行只读命令：

cd /Users/tei/dev/MapLibreParticleLab
git branch --show-current
git rev-parse HEAD
git status --short
git diff --check
git diff -- src/mln/annotation/annotation_manager.cpp src/mln/annotation/annotation_manager.hpp src/mln/renderer/render_segment_json.hpp test/api/annotations.test.cpp test/renderer/retained_underlay_cache.test.cpp platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/Step113PbfGateScene.kt tools/particle_android_validation/verify_step113_fast_path.py tools/particle_android_validation/README.md 粒子开发记录.md
shasum -a 256 docs/40_任务/STEP-110_R0_Placement跨段归因只读调查_Codex任务_v1.md docs/40_任务/STEP-111_R段Placement结果等价与独立刷新可行性只读调查_Codex任务_v1.md

两任务书 SHA 应分别为 33037df71b4b30aa7956d59f4b99f77af3085405b24111bc0fe11ec857a93db0、f3a5806f25384bf46055db2edfea0d21bfbc4124184bc813b46e38b8079c1ec4。不要暂存它们。RDC按获授权的scoped流程收尾后，记录真正的最新HEAD；本报告起点 e2d202b 并不包含本轮修改。构建前 tracked 必须 clean；原未跟踪任务书可保留，build-info 的 git_dirty 不能单独用来推断源码不一致。

Native 定向命令逐项执行，上一项失败立即停止，保存完整 stdout/stderr 与首个真实 error；历史缺 libuv 不当成新结果，不运行旧runner：

cmake --preset macos-metal

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

build-macos-metal/mbgl-test-runner --gtest_filter='Step116Safety.*:Annotations.*:FastGateTrace.*:ParticleFastPath.*:RenderSegmentDiagnostics.*:RenderSegmentPlacementFree.*:RenderSegmentLocality.*:RenderSegmentPlan.*' --gtest_color=no

Annotations.Step116 三用例使用现有 point_annotation 图像做实际渲染比较；不能仅检查 getLayer 指针就声称像素 PASS。账本/谓词用例不构成 GPU rendered Fast，Metal host 成功也不代替 Android OpenGL/设备回退。若依赖/编译阻塞，保持现场并在报告标 BLOCKED/NOT RUN，Android集中构建是否继续由用户安排。

2. 用户一次手工 Android 构建与安装

在锁定的最新 HEAD 上，用户手工依序执行，Codex/RDC不得代用户启动 Android 构建或安装：

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

标准脚本使用 Java17、OpenGL/x86_64、strip native debug symbols，保存 build-info/build.log，检查 ZIP/ABI/体积/SHA。失败不得续用原路径旧 APK。

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

记录源码HEAD、branch、精确修改文件/SHA、构建日志、APK大小/ABI/SHA、设备序号及型号。不能仅凭 13.6.1-particle.23 或安装 Success 认定是新源码。

3. STEP115 preflight → 原 STATIC_RC ≥75秒

用户安装成功后，由 RDC / 用户执行，serial/adb路径明确：

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

preflight 检查当前 tracked clean、build-info.commit==HEAD、APK SHA==build-info.sha256、设备 ABI x86_64、安装包 SHA==本地 APK。STALE_APK / SOURCE_NOT_LOCKED / SHA失败时停止，必须先纠正版本。PREFLIGHT_PASS只代表版本一致。

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

使用90秒，脚本在取得 PID 后实际等待完整90秒（≥75秒）；加载太慢导致摘要不足则 INSUFFICIENT_SAMPLES / NO_READY_SUMMARY，不推断Fast。保留 result.json、logcat.txt、launch.txt、实际观察秒数。摘要须同sceneGeneration/lifecycle、planValid/basePreserved、24项、mismatch=0、累计计数单调；独立blocked日志和摘要撤销不能被早先Fast盖过。退出2为没有可接受Fast证据，退出3为版本/环境等阻塞，不能改成0制造PASS。

FAST_OBSERVED仅指真实 Native fastRendered 增量>0，不是安全/像素/性能终验。要求原63层manifest、NavSea原PBF/Sprite/Glyph/Vector URI及定义/顺序不变，仅声明SDK空辅助层调整；正常静态预期Native65层/C仅weather-color和raster-particle，实际以新导出为准。PUBLIC PBF若变成非63层，场景保留现场并 BLOCKED，不更换简化Style来通过。

4. 手动导出完整120帧及设备画面

保持同次 STATIC_RC 运行，用户在 STEP093 → STEP113 菜单选择 EXPORT LAST SNAPSHOT。这是最近一次3秒共享采样，不额外渲染。以下由 RDC / 用户回读，必须核对所选文件确属本次新运行：

mkdir -p artifacts/maplibre-particle/android-validation/step116
step116_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 "$step116_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/$step116_file" > artifacts/maplibre-particle/android-validation/step116/static-rc-full.json
shasum -a 256 artifacts/maplibre-particle/android-validation/step116/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/step116/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/step116/crash.log

test -n失败立即停止后续命令。同一个Full JSON先做离线证据结构检查（不是安全测试）：

python3 -B - <<'PY'
import json
from pathlib import Path
p = Path('artifacts/maplibre-particle/android-validation/step116/static-rc-full.json')
v = json.loads(p.read_text())
assert v['scenario'] == 'STATIC_RC' and v['sceneReady'] and not v['blockedReason']
assert v['commands']['emptyBuiltinAnnotationLayerRemoved'] is True
assert v['commands']['annotationInstancesAtRemoval'] == 0
assert v['commands']['annotationSourcePreserved'] is True
assert v['styleParity']['baseLayerCount'] == 63 and v['styleParity']['baseLayersPreserved']
assert not v['styleParity']['full113Equivalent']
n = v['native']; t = n['fastGateTrace']; frames = t['frames']
assert n['valid'] and len(frames) == 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 frames)
assert all(a['sequence'] < b['sequence'] for a, b in zip(frames, frames[1:]))
complete = [f for f in frames if f['completed']]
assert complete and all(f['post'] is not None for f in complete)
print('结构完整；仍须独立核对源码/制品SHA、同次generation/lifecycle及用户画面')
print('生命周期 Full/Fast:', t['fullRendered'], t['fastRendered'])
print('窗口 completed/Full/Fast:', len(complete), t['windowFullRendered'], t['windowFastRendered'])
for s in n['segments']:
    if s['strategy'] == 'RETAINED':
        print('R', s['beginIndex'], s['endExclusive'], s['missingSourceIds'],
              s['placementGatePassed'], s['cache'])
print('窗口失败项:', [(g['order'], g['reason'], g['windowFailures']) for g in t['gates'] if g['windowFailures']])
PY

允许最后一帧 pending，但不能把其post作为当前Full。pre为上次完成树、post/full为本次完成树，避免跨帧拼状态。环形窗口可能覆盖Mutation瞬间，必须变更前/后分别及时手动导出，若没捕获则如实 NOT VERIFIED。120条帧不等于120条completed。

用户确认基础PBF/标注/天气色带/粒子可见、无漏内容/闪烁/层序错误；截图归档及用户判断不能代替同条件Full/Fast像素比较。当前缺源/Placement未解时应记录 Fast0 和每项失败，不宣布性能提升。

5. 失败定位与受保护回归

结果	判断与下一步
missingSourceIds含tide，R Build0	正式Style缺源仍fail-closed；不补假源、不删tide-spots，记录Source类型/缺失层ID
缺源消失但Symbol placementGatePassed=false	独立Symbol准入阻塞，检查Full changed/stale/fade与pre/post；不要用等候时间放行
#22仍失败	查Native C范围实际层清单；空层调整是否被撤销/失败，普通circle或真实Annotation仍应阻挡
#23仍失败	查retainedSupported和preparedScene聚合，消除#22不保证#23通过
mismatch>0 / unknown Gate /版本不符	停止记录通过，保留首错和完整证据
Fast>0	先核查没有缺源/场景撤销、原Style完整，继续资源变化/回退/画面对照；仅记FAST_OBSERVED

原五场景仍在。每项独立运行并保留导出，不连续启动冒充采样：

python3 -B tools/particle_android_validation/verify_step113_fast_path.py --scenario PBF63 --seconds 90
python3 -B tools/particle_android_validation/verify_step113_fast_path.py --scenario PARTICLE_OFF --seconds 90
python3 -B tools/particle_android_validation/verify_step113_fast_path.py --scenario PARTIAL_RCRR --seconds 90
python3 -B tools/particle_android_validation/verify_step113_fast_path.py --scenario SOURCE_CHANGE --seconds 90

这些场景可能预期Fast0，脚本退出2是受保护负例结果，不自动视为回归失败或改预期。SOURCE_CHANGE保留circle与Annotation；用户执行一次原 MUTATE PROBE SOURCE ONCE，导出前后commands和native lastMutation/affectedSegmentIndices，区分同时发生的真实瓦片更新。

Native七项新测试之外，还需 RDC/用户记录：遗留Annotation拒绝移除；STATIC_RC后添加真实Marker（同步恢复points再Full、像素可见），no-op更新；额外Style.addLayer/重排不删除新内容；disable、退出到STEP102、Style reload及后台恢复；Source创建/同名更新/async Tile、Glyph/Image变化必定invalid/Full。Test App没有新增自动Mutation来假装覆盖这些事件；若当前UI无法触发，标该项设备NOT VERIFIED并使用对应Native真实测试/另行授权的操作。STEP114四场景回归使用其既有命令；Smoke结果只归其独立场景。

最终提交证据应包含最新HEAD/精确源码diff、Native日志/首错、用户build-info/build.log/APK及安装SHA、设备信息、原STATIC_RC摘要和完整JSON、manifest、24Gate/真实Build/Reuse/Full/Fast增量、回退与画面。编译成功、preflight成功或静态检查都不把STEP-116判为CLOSED/PASS。

12 KiB Raw Permalink Blame History Unescape Escape