MapLibreParticleLab/docs/50_Step记录/STEP-100_SourceScoped_RenderSegment局部失效_v1.md

STEP-100 SourceScoped RenderSegment 局部失效记录 v1

状态：CLOSED / PASS（Android runtime） 日期：2026-10-06

基线

• worktree：/Users/tei/dev/MapLibreParticleLab-step100
• branch：step100-segment-local-source-invalidation
• start HEAD：c4b481fd2c5b5da20d31f6ae54011f0552d7dbd0
• V17 tag：maplibre-particle/rn/13.4.1-particle.17
• V17 frozen commit：e8b451fe70054107773e82484c80e90df3889147

实现

• Source/Tile mutation 增加 source-scoped revision；
• global retained content revision 继续保留；
• production renderer 与 diagnostics 共用 source→segment dependency；
• RETAINED Segment 独立 readiness / stability / Build / Reuse / Fallback；
• unrelated source unloaded/fading 不再拖垮该 Segment；
• full CPU mixed execution 支持 R0 Reuse + C Live + R1 Fallback；
• Fast Path gate、singleContinuous、多 Continuous语义未改；
• Source::isLoaded 与 global renderTree loaded 语义未改。

Android Build

标准 validation pipeline 最终：

RC=0
BUILD SUCCESS
variant=OpenglDebug
abi=x86_64
apk_bytes=61956640
libmaplibre_bytes=39636472
sha256=86e22bf081bf7d3196f0bf0e7c56af51bde01e9f0b01e0bab238cb794273315a

RDC 另修复 validation script 的 pipefail/SIGPIPE 141： awk ... {print $1; exit} → 完整消费管道。

FZG1-2

• Android 13
• API 33
• x86_64
• ADB：192.168.200.139:5555

T1 STATIC

• false window：1
• avg/max：203 ms
• R0/R1 build=1 后持续 reuse

T4 R-C-R 主验收

窗口：

• baseline：tick 8
• final：tick 130
• 约 61.6 s

global revision： 128 → 973

R0：

build          1 → 1
invalidation   20 → 20
reuse          132 → 4042
sourceRevision unchanged

R1：

build          5 → 135
invalidation   26 → 211

结论：

• R0 buildDelta=0
• R0 invalidationDelta=0
• R0 reuseDelta=+3910
• global revision 仍增长
• dynamic source affected=[2]

主硬门槛 PASS。

T2 GEOJSON 1HZ

• 约 35 s
• falseWindowCount=6
• avg=203 ms
• max=205 ms
• R0 build=1 / invalidation=18 保持稳定，reuse 增长

T3 PERMANENT UNREADY

global loaded=false 持续约 21.468 s。

unready source：

• no layer
• enabled=false
• isLoaded=false

R0/R1：

• build=1 不变
• invalidation=19 不变
• reuse：11 → 1200
• decision=reuse

说明 global loaded 兼容事实仍为 false，但无关 retained cache 继续安全复用。

Native Host Test

Codex 已新增 RenderSegmentLocality.* 测试源码。

当前 Intel Mac 缺 libuv，Metal host configure 被环境阻塞。RDC 曾尝试 Homebrew 安装，但发现会连带升级 CMake/OpenSSL/Python 且 Intel 无 bottle 支持，已主动停止。

因此：

• Native host GTest：ENV BLOCKED / NOT RUN
• Android full native build：PASS
• Android runtime：PASS

Jest：NOT RUN。

结论

STEP-100 功能目标成立：

GeoJSON Source 更新只刷新依赖它的 retained segment；无关 retained segment 不再一起刷新。

允许进入 V18 unified release。