MapLibreParticleLab/docs/40_任务/STEP-089_静态渲染Revision与Invalidation基础层_Codex任务_v1.md

STEP-089 静态渲染 Revision 与 Invalidation 基础层 Codex 任务 v1

目标

为 STEP-090 Static CPU Fast Path 建立可靠、可验证的静态状态失效判据。

STEP-089 不负责跳过 static source/tile/render-tree/prepare，也不负责降低 CPU；只建立“静态前缀当前是否仍可安全复用”的 revision / invalidation 基础，确保后续 fast path 不会复用过期静态状态。

当前基线：

• branch: particle/main
• baseline HEAD: 07a17b4c701cd22c8e8b516ad84f4044f291f9fa
• STEP-088 retained underlay 已完成：
  • GPU static draw cache
  • map-scoped runtime Cache ON/OFF
  • Release 最小 diagnostics
  • Android/iOS/RN runtime API
  • Android NavSea 真实 PBF 性能场景
• 实测证明主要剩余成本是 Particle continuous repaint 下 PBF/vector/static renderer pipeline 被重复 processing。
• STEP-090 才负责 CPU fast path。

必做项

• 引入单调递增的 static/retained revision 机制，能表达“静态前缀相关输入已变化”。
• retained cache build 时记录所依据的 revision。
• reuse 前必须确认当前 revision 与 build revision 一致。
• 下列变化必须使 revision 前进或明确 invalidate：
  • camera / transform
  • viewport / size / pixel ratio
  • style reload / style mutation
  • layer add/remove/reorder/property mutation
  • source add/remove/change
  • tile / drawable 内容更新
  • image / sprite / glyph 变化
  • placement / symbol fade 状态变化
  • render context / surface / backend resource reset
  • debug render options
  • terrain / 3D / custom layer 等当前不能安全证明静态的场景
• symbol fade / placement transition 活跃时不得复用 stale static cache。
• unsupported / uncertain 情况继续 fail closed 到 full renderer。
• Cache OFF/ON runtime 行为保持不变。
• Release diagnostics 保持低成本；允许新增只读 revision 字段，但禁止 per-frame Release 日志。
• Debug 日志可增加 revision / invalidation reason，便于 RDC 验证。
• 原有 LayerGroup ordinal、dynamic boundary、transparent underlay、legacy ordering 语义不得回退。
• 不实现 STEP-090 的 static CPU processing skip。
• 不新增 React 管理的 renderer cache。
• 不把 provider/network/NavSea Store 逻辑引入 MapLibre Core。
• 不使用 Jest。

Revision 设计约束

优先采用单调 uint64_t revision / generation：

• revision 只增不减；
• 不依赖 wall clock；
• 不要求每种事件都维护独立缓存副本；
• 可以保留 reason/category 作为诊断，但 correctness 依赖 revision，而不是字符串 reason；
• revision wraparound 可按现实上不可达处理，但类型必须明确。

建议最少区分：

• 当前 static revision；
• retained underlay build revision；

如现有 Renderer/RenderOrchestrator 的生命周期更适合其他命名，可调整，但不要把模型复杂化。

Invalidation 范围原则

STEP-089 首选“安全偏保守”。

如果某类状态变化是否会影响 static prefix 无法可靠判断：

• 直接 bump revision / invalidate；
• 不做复杂局部 dependency graph；
• 不为了提高 hit rate 提前实现 STEP-090 级别的细粒度 source/layer dependency tracking。

目标是让 STEP-090 有一个可信的 fast-path gate，而不是在 089 追求最高 cache reuse。

Placement / Symbol 特别规则

已有 Android 真机证据：

• Particle 放到全部 63 层上方时，symbol-heavy prefix 会出现持续 static-placement / static-transition。
• BEFORE_SYMBOL_CLUSTER（fill/line 在下，symbol cluster 在上）是目前最稳定边界。

因此：

• placement/fade active 必须阻止旧 static state 被错误复用；
• fade/placement 稳定后允许重新 build 并记录新 revision；
• 不得简单忽略 symbol placement 来提高 TOP 场景 reuse。

Runtime API / Diagnostics

保持现有：

• setRetainedUnderlayEnabled
• getRetainedUnderlayDiagnostics

允许在 diagnostics 增加：

• staticRevision
• buildRevision

如增加，Android/iOS/RN 三端需一致；如果为了控制 STEP-089 范围决定暂不公开，也至少在 Debug Native 日志中可观察。

不要新增第二套 runtime module / map registry。

测试要求

新增/扩展 Native directed tests，至少覆盖：

1. revision 单调递增；
2. build revision 与 current revision 相等时允许 reuse；
3. camera/viewport/style/source 变化后 revision 改变并禁止旧 cache reuse；
4. placement/fade active 时不 reuse stale cache；
5. Cache OFF -> invalidate；重新 ON -> 下一次重新 build；
6. unsupported / resource failure 保持安全 fallback；
7. 原有 RetainedDynamicBoundary / LayerGroupRange / RetainedUnderlayCache 测试继续通过。

不要求 Jest。

Codex 执行规则

• 先完整阅读本任务、AGENTS.md、STEP-088 v3 Step/报告，以及 retained underlay 当前实现。
• 不需要提交实施计划。
• 直接实现。
• 不运行 Gradle / Android build / ADB / Xcode。
• 不运行大型 noisy build/test；编译和最终验证由 RDC 负责。
• 可以做必要的静态代码检查，但不要替代 RDC 编译。
• 不 commit/push，等 RDC 验证后统一收尾。
• 不触碰用户既有无关 dirty/untracked。
• 不使用 worktree。
• 无法完成的项明确说明，不得静默跳过。

完成时必须报告

逐项按“已完成 / 未完成 / 无法验证”报告上述必做项，并列出：

• 修改文件；
• revision 的实际所有者与生命周期；
• 每类 invalidation 在哪里触发；
• 新增测试名；
• RDC 应执行的精确 OpenGL / Metal / Android Validation 命令；
• 明确说明没有实现 STEP-090 fast path。