MapLibreParticleLab/docs/40_任务/STEP-119_Symbol稳定结果证书与R首次Build_Fast准入_Codex任务_v1.md

STEP-119 Symbol稳定结果证书与R首次Build/Fast安全准入

日期2026-10-11。用户批准立即继续实施上一轮讨论的Shared Core方案，不是只读调查。 项目 /Users/tei/dev/MapLibreParticleLab，particle/main基线869930046b11dbeb3b147e3be952a2e847316292；Integration /Users/tei/dev/navsea-particle-integration已同步origin/main=80667d6c343411d03a760425438e3d292f452118。实际Codex须GPT-6.1-Sol High（gpt-6.1-sol，model_reasoning_effort=high）。 Codex负责开发、定向非Jest测试源码、中文文档，不执行Gradle/ADB/Native大编译/Bazel/Jest/commit/push。RDC独立核验、限定Git收尾并按用户授权集中执行一次APK build、install和真实设备验证。

优先读取

根AGENTS.md、PARTICLE_BASELINE.md、docs/00_项目规范、docs/00_项目总则README和4份当前总则；Integration的instructions/PARTICLE_PROJECT_INSTRUCTIONS.md、README.md、WORKFLOW.md、coordination/TEAM_MODEL.md、contracts/、rfc/、adr/、status/、compatibility/。STEP117根因调查 docs/20_调查/STEP-117_PBF_R首次缓存Build安全证据_v1.md 与STEP118真机报告 docs/60_测试/STEP-118_潮汐清理新APK设备实测结果_20261011.md及STEP112-116关键报告。必须逐段核对src/mln/text/placement.cpp、render_orchestrator.cpp、renderer_impl.cpp、render_tree.cpp、retained_underlay_cache.cpp、include/mln/renderer/render_segment.hpp、RenderSymbolLayer/SymbolBucket/atlas/shader、24FastGate/RevisionBook及现有测试。

已证实

STEP118原生产63基础PBF图层测试副本只排除一条失效tide-spots（用户允许），保留其它62基础层、天气2层=Native64；R[0,62)、C[62,64)，missingSourceIds=[]、R fallback=static-placement、R Cache Build0/Reuse0；90.008s FastDelta0 FullDelta942；PlacementGatePassed=false，24Gate mismatch0。当前源码perSegment Gate对Symbol要求 !placementChanged && symbolFadeChange==0 && !placementTransitionActive；Full新排布置changed=true，recent复用设stale->hasTransitions=true，而Fade完全稳定时通常>=1而非0。独立global retainedPlacementStable/retainedStaticStable/retainedSupported/particlePreparedSceneSupported又阻断。首次Build与Fast复用需要分开。 旧设备真实证据在Git忽略artifacts/maplibre-particle/android-validation/step113-retest-20261011_140448/static_rc_no_tide/result.json和screen.png。新测试APK源commit=3051196054c7b69815c298040dae61d26499d9f2、SHA=44afcfabe0cf4f1ec93f35899241bd73093aa6db4b5cb82ca2120dd531b8f3e9。现HEAD较新只包含报告。

本次必须优先真正实施的内容

1. 在平台无关的Shared Core内部区分Placement计算调用与最终Renderable Symbol结果变化，建立可检验稳定状态、revisions/epoch/证书。不能用单一布尔值代替真正GPU输入一致性，不能把placed结果布尔不变当成vertices/opacity/atlas全部一致。保留跨瓦片collision、text/icon、variable anchors/方向、fade、glyph/icon/atlas、shader uniform/tweaker及绘制层序语义。必须检查GL和Metal两侧shader的symbolFadeChange clamp行为。普通Full应完成placement、updateBuckets/vertices、processChanges、tweakers/uploads，才决定可安全建立R缓存（同次或下一帧）。Build/reuse需要匹配版本，任何可影响像素的异步状态立即invalid并走Full。
2. 解决Placement::placementIsRecent / setPlacementStale / hasTransitions语义和symbolFadeChange的>=1状态对首次Build的逻辑死锁。重新计算 != 真正GPU结果变化；stale不是强制正在fade。fade未完成仍必须阻断，所有真实动态Symbol/tiles/glyphs/Source/style/camera/viewport/pixelRatio/context/Annotation更新都fail-closed。不得简单常置false或单改renderSegmentPlacementGatePassed、删除24Gate、修改计数或强行把其它Symbol放进C。
3. 必须同时审查并修复global/perSegment稳定性、revision/state跟踪和preparedSceneSupported，让首次R在安全的Full后建立Build，Reuse后才能Fast。缺失证明的Symbol子类严格拒绝，不能用概括性稳定状态假设可缓存。尽可能真正做到原62基础层静止时Build>0、Reuse>0、FastDelta>0；若架构上无法证明，明示BLOCKED，安全停止危险路径，但应尽量完成有证明的实现。
4. 非Jest C++定向测试（已登记test/renderer文件），覆盖真实PlacementController生命周期、fresh->settled->build->reuse、fade过程拒绝、相机/缩放/旋转、纹理字形异步、新Source/style、Annotation、Context、tile/wrap/crossTile collisions、跨段LayerGroup安全重建；不能把无GPU predicate当真正GPU等价。
5. 不改RN/JNI/ObjC/Java/Kotlin公共API与ABI、正式PBF/Source/MapLibre外部URL或NavSea/iOS业务、不变更Core-owned timeline/playback、不能改天气层语义。跨项目公共接口新语义须Integration RFC/ADR授权，必要则只报告并保留旧合同。
6. 保持原STEP113 63 PBF和新STEP118 STATIC_RC_NO_TIDE派生测试、原24Gate、现有真实version/SHA的严格核对。不能新增虚构tide数据。
7. 不触碰用户两个未跟踪 docs/40_任务/STEP-110_...与STEP-111_...，不git add . / add -A / reset --hard / clean；不修改Git忽略旧真机证据。Codex不运行Gradle/ADB/Jest/Native大编译、也不commit/push，最后交RDC。

必做中文输出文件（缺一不得完成）

• 实际Core实现+必要非Jest C++测试源码及直接相关诊断/README改动。
• docs/20_调查/STEP-119_Symbol结果证书与R缓存Build实现依据_v1.md：真实渲染生命周期、核心不变量、结果证书如何绑定真实GPU绘制、反例、风险。
• docs/50_Step记录/STEP-119_Symbol缓存实际实现_v1.md：状态、变更、验证、下一步。
• docs/60_测试/STEP-119_原PBF_FAST实机联合验收计划_v1.md：一次build/install，新STATIC_RC_NO_TIDE >=90秒真实Build/Reuse/Fast+24Gate mismatch0，原63负对照及source/style/camera/glyph/annotation/context负例，视觉核验与fail closed。
• docs/报告/STEP-119_Symbol缓存_Codex完成报告_v1.md：真实模型档位、文件、已实施/未实施、清楚BLOCKED或IMPLEMENTED_WAITING_ANDROID、静态检查、RDC命令、git commit由RDC负责。
• 粒子开发记录.md在末尾中文追加。 Codex只跑轻量静态范围和git diff --check；不可宣称Native/Android/iOS/用户视觉PASS。

RDC严格实机目标

有实质Shared Core行为修改且独立审计通过后，Mac标准 ./tools/particle_android_validation/build_validation_apk.sh 一次Android OpenGL x86_64 APK；设备FZG1-2 ADB serial 192.168.200.139:5555且全部命令显式-s；运行 python3 -B tools/particle_android_validation/verify_step113_fast_path.py --scenario STATIC_RC_NO_TIDE --seconds 90。必须真实R Build>0、Reuse>0、FastDelta>0、Symbol画面/24Gate一致、更新时缓存失效与Full正确。失败最多5轮当前步骤修复，不能跳过并声称通过。无行为改动则不重编毫无意义APK。