# STEP-089 静态渲染 Revision 与 Invalidation 基础层 v1

## 状态

**CLOSED / PASS**

STEP-089 已完成 retained underlay 的静态状态 revision / invalidation 基础层，为 STEP-090 Static CPU Fast Path 提供可靠的安全门控。

## 核心实现

- 新增单调递增的静态 revision / generation。
- retained cache build 时记录 buildRevision。
- reuse 前要求 buildRevision 与当前 staticRevision 一致。
- 新增稳定 topology snapshot：
  - dynamic boundary；
  - static prefix 中每个 LayerGroup 的 layerIndex；
  - groupName；
  - groupType。
- 真正的 LayerGroup 增删、排序、index 变化会推进 topologyRevision。
- Renderer 内部 transient drawable churn 不再直接推进 static revision。
- 等价的 stencil tile set 不因 shared_ptr identity 变化而误失效。
- 支持并记录以下语义失效来源：
  - camera / viewport / pixel ratio；
  - style / layer / source mutation；
  - tile content change；
  - image / sprite / glyph；
  - placement / fade；
  - context reset；
  - debug options；
  - 3D / unsupported custom/static layer。
- unsupported / uncertain 场景继续 fail-closed。
- STEP-088 runtime Cache ON/OFF 行为保持不变。
- 未实现 STEP-090 CPU fast path。

## Android 实机关键验证

测试场景：
- Android 13 / x86_64；
- NavSea 正式 63 层 PBF Style；
- Particle = AFTER_CLIP；
- 固定 Camera：Karatsu；
- Cache ON。

### 稳态

修复前曾出现：
- drawable-mutation 每帧失效；
- layer-group-mutation 每帧失效；
- staticRevision 每帧递增；
- build 每帧递增；
- reuse=0。

最终版本：

```text
frame=480  build=2  reuse=302  staticRevision=21  buildRevision=21
frame=600  build=2  reuse=422  staticRevision=21  buildRevision=21
frame=720  build=2  reuse=542  staticRevision=21  buildRevision=21
```

确认：
- staticRevision 稳定；
- buildRevision == staticRevision；
- build 不再增长；
- reuse 持续增长。

### Camera 变化

相机变化后：
- staticRevision: 41 -> 44；
- build: 18 -> 19；
- buildRevision = 44；

随后稳定：

```text
build=19
reuse=3519 -> 3639 -> 3759 -> 3879
staticRevision=44
buildRevision=44
```

确认真实变化会使 revision 前进并重建一次，稳定后恢复 reuse。

## Native 测试

Retained directed tests：12/12 PASS。

覆盖：
- dynamic boundary；
- layer group range；
- cache build/reuse/invalidation；
- runtime Cache ON/OFF；
- revision 单调；
- 无语义变化时 revision 不前进；
- 等价 intra-frame remove/add 不推进 topology；
- 持久 topology 变化只推进一次；
- ordering/index 变化推进 topology；
- buildRevision 匹配才允许 reuse；
- placement/fade 活跃时拒绝 stale cache。

## 构建验证

- Mac OpenGL mbgl-test-runner：PASS。
- Metal/iOS mbgl-core：BUILD SUCCEEDED。
- Android x86_64 stripped Debug Validation APK：BUILD SUCCESSFUL，约 57 MB。
- Android 实机稳态 reuse：PASS。
- Android Camera invalidation -> rebuild -> reuse：PASS。
- git diff --check：PASS。

## 结论

STEP-089 已建立可信的 static revision gate。后续 STEP-090 可以在该 gate 为稳定状态时尝试跳过静态 PBF/vector CPU processing；089 本身不做 CPU fast path。

## 下一步

进入 STEP-090：Static CPU Fast Path。