MapLibreParticleLab/docs/30_设计/STEP-097_V13三轮问题去重与修复矩阵_v1.md

STEP-097 V13 三轮问题去重与修复矩阵 v1

基线：Mac-mini-tei.lan；particle/main；起始 720d309364628f85049cf9969d71c71e8dfacce9，与查询时 origin/particle/main 一致；工作区干净。冻结 .13 tag 指向 ee0b89e71。该 HEAD 相对任务书的 b5c1c4879 只新增 STEP-097 任务文档。Integration 本地 C-001/RFC-001 已只读；其远端是否最新尚未由 RDC 证实。所有构建、测试和运行验证：NOT RUN。

公共不变量

fieldId/generation/validTime、东向 U/北向 V、T0/T1/MIX、旧 T1→新 T0 复用、Style 全局 Z 顺序、每个 R 独立缓存、WeatherColor 与 Particle 分离、Host 拥有天气获取。无权改变 C-001 的公开生命周期、错误或数据所有权语义。

以下“入口”均为待执行回归，不能当作运行结果。源码状态随阶段更新；WAITING_RDC_BUILD_AND_RUNTIME 表示仅完成定位，尚未实现。

# / 原编号	当前源码定位与最短触发	反例/安全约束	拟修文件与回归入口	状态 / commit / 平台待测
01 N01/B01	paint_parameters.cpp:185 tile 集合相同跨 R-R target 复用 CPU mask	同一未清 stencil target 可复用	PaintParameters、Renderer、RenderTarget 已在新目标重置；同 tiles R-R/R-C-R 像素入口尚缺	WAITING_RDC_BUILD_AND_RUNTIME / e67e4961b / GL、Metal
02 N02/B02	mtl/render_pass.cpp:21 仅 color clear；offscreen_texture.cpp:67 附件创建	无 depth/stencil 的 target 不可盲设附件	Metal descriptor/combined 附件已修改；专用附件故障测试源码尚缺	WAITING_RDC_BUILD_AND_RUNTIME / e67e4961b / Metal
03 N03/B12	render_orchestrator.hpp:156 catch；renderer_impl.cpp:824 仍 mark success	失败后 full fallback、下帧重试	visitor 错误标志与 fallback 已接入；异常注入测试源码尚缺	WAITING_RDC_BUILD_AND_RUNTIME / e67e4961b / GL、Metal
04 N04/B06	Map::Impl::onUpdate() 在 Continuous update 驱动每个 RasterArraySource；Source 使用 monotonic tick，并用 forecastTickInProgress 阻止同步 SourceObserver 重入二次推进	显式 setTime/PLAY/PAUSE/rate 由一个 Core clock owner 推进；平台 timer 只唤醒	map_impl.cpp、RasterArraySource、Android/iOS WeatherRuntime；RasterArrayV4ProductionClockTicksOnceForBothBindingsAndResetsOnCommands、RasterArrayV4ClockSourceNotificationReentryDoesNotAdvanceTwice	CODE_IMPLEMENTED_STATIC_CHECKED / A2 源码提交 f49ffa68a / OpenGL 与 Metal host A2 定向 3/3 PASS；FZG1 V4 Golden PLAY/PAUSE/速率/clear/reload PASS；无 iOS runtime（用户豁免）
05 B13	sameFieldGpuContent() 保持 revision/version 无关的 payload 相等；renderer GPU 槽位更新使用严格 sameFieldGpuEndpoint()；Source mix-only cache 使用 projection identity、binding、immutable frame 和 plane/validity storage pointer identity	mix-only 复用同一 T0/T1 snapshot；frame/revision、grid、validity、U/V、encoding 或 binding 改变则重物化并失效；invalid/clear fail-closed	field_data_adapter.hpp、projection materialization、RasterArraySource 与 renderer；Source cache 测试 + ParticleGpuField.*	CODE_IMPLEMENTED_STATIC_CHECKED / A2 源码提交 f49ffa68a / broad OpenGL 与 Metal host 各 121/121 PASS，A2 定向各 3/3 PASS；FZG1 stable mix 时 upload/reset 计数稳定；clear/reload 后合法增加
06 B07	新增内部 signed RGBA8 编码，byte 128 明确表示零；GL/Metal shader 以 high precision 还原 byte	不改公开 QBIN/FieldProfile encoding；量化误差与 sub-half-quantum 微速边界明确测试	particle_gpu_math.hpp、GL/Metal shader 源及生成头、particle_gpu_math.test.cpp	CODE_IMPLEMENTED_STATIC_CHECKED / A2 源码提交 f49ffa68a / broad OpenGL 与 Metal host 各 121/121 PASS，含 signed zero、取消、NaN/invalid 与微速边界；两次 shader generator 幂等；无 iOS runtime
07 B08	统一 helper 与 GL/Metal 粒子位移路径都为 Mercator 东向 U、北向 V 应用相同 cos(latitude) metric，并夹紧极区分母	保持 U/V canonical m/s、V 北向为正、既有视觉时间倍率	particle_gpu_math.hpp、renderer 与 GL/Metal shader 源及生成头；0°/45°/60° 四方向和极区测试	CODE_IMPLEMENTED_STATIC_CHECKED / A2 源码提交 f49ffa68a / broad OpenGL 与 Metal host 各 121/121 PASS，含数学定向测试；Android FZG1 场景闭环通过；无 iOS runtime
08 N05	长度感知 JSON 解析，拒绝 NUL/重复键/非法 schema，invalid fail-closed	清旧计划、合法恢复	render_segment_json.hpp、双平台 bridge 与 GTest	CODE_IMPLEMENTED / B Core 定向 6/6、扩展 139/139 PASS；待 B Git，iOS runtime 未测
09 N06	FieldProfileValidator 在 Store commit 前检验有效数值及 scale/offset	validity=0/noData 合法；坏高 revision 不覆盖好帧	FieldProfileValidator/Source GTest，修正旧 16-bit fixture	CODE_IMPLEMENTED / B Core 定向 6/6、扩展 139/139 PASS；待 B Git
10 N07	View owner、generation guard、map destroy observer 源码已写	旧 map 回调不得影响新世代，监听须释放	Kotlin/Java JUnit，真实 MapLibreMap.onDestroy	Android Native JUnit 2/2、Java 编译与 owner 隔离 JVM JUnit 4/4 PASS；BLOCKED_NATIVE_AAR_COMPATIBILITY：正式 .13 缺新 Map 方法，默认 RN consumer 不可配对编译，B 不判 PASS
11 F01/C01	renderer_impl.cpp:505 full diagnostics 快照	外部 pull schema 不变	runtime/renderer；快照计数	WAITING_RDC_BUILD_AND_RUNTIME / 待提交 / Core
12 F02/C02/B03	Metal offscreen swap() 同步等待	不删不明依赖 wait	Metal；GPU capture	DEFERRED_DESIGN / 无 / Metal
13 F03/C03/B04	cache revision 变化释放 texture	target clear 必须先正确	cache；同尺寸重绘/resize	WAITING_RDC_BUILD_AND_RUNTIME / 待提交 / GL、Metal
14 F04/C04	R 数 × viewport 独立附件内存	保留独立 R 与失败 fallback	cache；资源阶梯、失败注入	DEFERRED_DESIGN / 无 / GL、Metal
15 C04/B11	encoded Store 无总 key/byte 预算	不静默驱逐绑定窗口	Store；容量/旧读者	DEFERRED_DESIGN / 无 / Core
16 F07/C05	render_orchestrator.hpp:156 每段前缀 distance	全局 ordinal 与 Z 顺序不变	orchestrator；重排/正反遍历	WAITING_RDC_BUILD_AND_RUNTIME / 待提交 / Core
17 C06/B05/B10	A2 已处理相同 immutable projection 的 mix-only 重物化；其余 diagnostics pull、ordinal 与 UI owner 世代发布仍属后续范围	A2 mix-only 不再复制/比较整张浮点快照；不据此宣称 C 阶段整体完成	A2 部分：RasterArraySource cache 定向测试及 FZG1；C 部分仍按原任务另行实施	A2 mix-only 子项已验证 / 当前工作树 5bb1a0e / OpenGL、Metal host 定向 3/3 PASS；C 其余项目未开始
18 C07	drawable/tweaker tick 重建、端点复制	不保留 stale GPU 引用	Particle renderer；tick/resize	DEFERRED_DESIGN / 无 / GL、Metal
19 F09/O01	runtime_state.hpp:230 新 topology；旧 cache 析构按 index 计数	总量与当前 topology 分离	runtime/cache 按 revision 过滤；新增 OldCacheReleaseCannotChargeReplacementAtSameIndex GTest	CODE_IMPLEMENTED_STATIC_CHECKED / e67e4961b / 2026-09-26 Core GTest 1/1 PASS，诊断组 5/5 PASS；GPU 资源验收仍待测
20 F05/E01	Test Host package/lock 已对齐正式 .13，SHA-256/SRI 核对一致	RN/Native 必须精确同版，不改 .13 产物	package/lock、release manifest、默认 RN 编译	STATIC_VERSION_LOCK_PASS；B10 新 Native method 不在正式 .13，默认消费者仍阻塞
21 F06	renderer_impl.cpp multi-C 走 full CPU	保留安全 fallback	后续 A/B 设计	DEFERRED_DESIGN / 无 / GL、Metal
22 F08	source/tile 等全局失效	无依赖图前不缩窄	后续依赖设计	DEFERRED_DESIGN / 无 / Core
23 F10/E02	Integration status/compatibility 仍写 .5	发布≠NavSea 支持	负责人协调证据请求	DEFERRED_DESIGN / 无 / 跨项目
24 STEP-095 §7/B09	synthetic mask 非共享地理 mask	不新建公开 mask API	C-001/RFC/ADR 协调	DEFERRED_DESIGN / 无 / 跨项目

操作次数模型（静态，非性能实测）

• A1：跨 target 清除 CPU mask 为每次目标切换一次 O(1) 状态清理；当前同 tiles 可能零次重绘但产生错误像素。Metal clear 每个 pass 最多各一次附件 load 设置。异常后额外一次 full fallback，避免错误缓存跨帧复用。
• A2：PLAY 由唯一 Map/Source clock 每次 update 推进一次；V4 mix-only 的投影重物化计数为 0（50 次 Source tick 定向测试），decoded endpoint 变化时 color/particle projection 各物化一次。FZG1 日志在单次 stable mix-only epoch 内 upload/reset 计数不变；clear/reload 会合法增加计数。以上是源码测试和该次设备记录，不构成普遍 GPU 性能结论。
• B：JSON 严格校验 O(输入字节长度)，有效数值验证 O(有效 cell × plane 数)，View/map 每世代各至多一活跃监听；源码已实施，但正式 .13 Native ABI 不含新方法。无 GPU 性能实测。
• C：预期 full diagnostics 深复制从每 render 次降到每外部 pull 次；ordinal 前缀从每段 O(G) 降到 topology 更新 O(G)；同时间物化从 O(cell) 降为 O(1)。尚未实施。

2026-09-26 第 19 项实测更新

• RDC 使用 0d13552be 重编译并执行 GTest，第 19 项 1/1 PASS、RenderSegmentDiagnostics 全组 5/5 PASS；详见 docs/报告/STEP-097_A1_第19项GTest运行验证报告_v1.md。其他问题状态不因此变化，A1 仍为 PARTIAL。

2026-09-26 第 19 项 FZG1 设备辅助证据

• 基于相同生产源码的 APK 在 FZG1-2 通过覆盖安装和设备 SHA-256 校验。两轮拓扑循环、重排、缓存 OFF/ON、缺失边界回退与恢复的 20 张截图及 UI 诊断已保存；有效场景的 B/T 粗粒度 textureCreate-resourceRelease 均为 0 或 1。此证据只支持 Android 运行态冒烟，不替代此前旧 revision 归属的 GTest 1/1 PASS，也不能证明 GPU 无泄漏。详见 docs/报告/STEP-097_A1_第19项FZG1运行验证报告_v1.md。A1 仍因 01/02/03 未闭合保持 PARTIAL。

2026-09-26 A1 专用入口补充（待 RDC 执行）

• 01：Android Validation Activity 的 STEP-093 菜单新增 STEP-097 same-source stencil 子菜单；Step097StencilFixture 用一个本地 GeoJSON source 与四个 fill layer 生成 R-R、R-C-R、C-R-R，菜单可重载与读 segment 诊断，既有 CACHE ON/OFF 可切换。RDC 仍需首帧/重建/reuse 的实际像素截图与 cache 计数；此处仅是可操作 fixture，未实测。
• 02：mtl_retained_attachments.test.cpp 检查实际离屏资源的 color/depth/stencil 绑定、simulator/x86 combined attachment、无 depth/stencil 时跳过 clear；生产 RenderPass 共用的 clear 辅助函数可检查 load/clear/store。设备资源创建失败与 encoder 失败的运行注入仍待 RDC 验证。
• 03：render_orchestrator_error.test.cpp 注入正/反向范围 visitor 异常，核对 observer/failed 标志，并用 cache 状态机核对失败后继续 Build、成功重试后 Reuse。真实 GPU 绘制故障与完整 renderer fallback 仍待 RDC 注入验证。
• 01/02/03 均保持 WAITING_RDC_BUILD_AND_RUNTIME；源码入口准备不等于编译或运行 PASS。19 的既有实测状态不变。

2026-09-26 A1 Android/Core 实测收口

• 01：same-source tiled fixture RR/RCR/CRR 两轮、rebuild/cache OFF/ON 共 18 点，屏幕中心与区域外采样两组像素均 18/18 一致；状态 valid=true/fallback=false，Android FZG1 实测通过。源码/测试提交 d0ced7235，编译修正 8c006ac83。
• 02：Metal host runner 已编译，GTest 两个测试均因没有 Metal device SKIP；用户决定不执行 iOS 运行测试，记 USER_ACCEPTED_WITHOUT_IOS_RUNTIME_TEST，不得称 Metal 实测 PASS。
• 03：RenderOrchestratorError.* 原生测试 2/2 PASS；真实 Android GPU fault injection 不在本次证据中。
• 19：前述 Core 1/1 PASS、诊断组 5/5 PASS、FZG1 辅助测试均保留。A1 在 Android/Core 验收及 iOS 用户豁免口径下进入 A2；详细事实见 docs/报告/STEP-097_A1_Android专项验收报告_v1.md。

2026-09-26 A2 RDC 最终验证

• 04–07 已在同一 dirty 源码工作树完成实现与 RDC 独立验证。旧 sameFieldGpuContent() 测试断言修复后原 58 项 58/58 PASS；更新后的 broad filter OpenGL 与 Metal host 各 121/121 PASS，三项 A2 Source 定向测试两平台各 3/3 PASS。
• 标准 Android Validation APK 为 OpenGL Debug/x86_64，61,753,803 bytes，SHA-256 27bf4a6cc191bd86c4d1c10398478d81c2999edd61fe7242e40e5188516b0ca5；安装到 FZG1-2 后设备 APK hash 相同。V4 Golden Wind test-only T0/T1 场景 17 张 PNG、24 个步骤、runner exit 0、ANR=0；PLAY 30 秒 UI 可响应，PAUSE 稳定，clear/reload 后再次 PLAY/PAUSE。
• 日志按资源窗口分别记录：clear/reload 前 mix-only epoch fieldUploadCount=6/resetCount=2 稳定；explicit clear/reload 后计数合法增加，达到 fieldUploadCount=10/resetCount=4，此后 replay 稳定。不可把 clear/reload 期间的上传与 reset 写成零。
• build source diff SHA-256 18927a5f30a88f5c1c3a00e0017473dc33b04151c227e4baf52250dc4ad2e6a2 与忽略目录中的 APK source snapshot 完全一致。未运行 iOS device runtime，按用户豁免记 USER_ACCEPTED_WITHOUT_IOS_RUNTIME_TEST；不得称 Metal host GTest 为 iOS PASS。A2 Android/Core 完成，B/C 未开始，整个 STEP-097 仍 PARTIAL。

2026-09-26 B 独立验证及阻塞

• RDC Core 定向 4/4、修正旧 16-bit fixture 后 broad 134/134 PASS；正式 .13 Android SDK 缺 B10 新 map destroy observer，默认 RN consumer 无法与该新源码配对。B PARTIAL，C 不启动；详见 B 独立报告。