@gitruck/cli 1.3.1 → 1.3.4

package/contracts/gsap-emit-v1-evidence.md

@@ -1,196 +1,200 @@
-# gsap-emit v1 · 证据附录
-
-本文件供契约维护者追溯实验、版本和阈值来源，不是 agent 执行时的必读文档。当前有效规则以 [`gsap-emit-v1.md`](gsap-emit-v1.md) 为准；本附录中的日期、样本和版本不能覆盖正文契约。
-
----
-
-## 回调与 seek 语义（2026-07-26 增补 · 补此前留白）
-
-> **一句话**：颗粒**可以**用时间线回调（`onUpdate` 等）驱动画面；**保证这些回调在定帧时被触发是渲染引擎侧的义务**，不是颗粒作者的义务。
-> 本节是该主题的**唯一口径来源**——契约引用（`skills/gtrk-style-maker/references/contracts-ref.md`）与消费侧检查（`gtrk mg lint`）的文案都指向这里，不得各自表述。
-
-### 一、GSAP 3.13.0 实测事实（写死在此，免后来者重测）
-
-复现方式：拉铁律⑤指定 CDN 的 `gsap.min.js` 到本地，Node `vm` 里造 `paused` timeline + proxy 对象 + 计数回调，**每种定位方式各新建一条 timeline 单独跑**（回调计数互不串）。
-
-**样本一**——10s、`ease:"none"` 的单条 tween（`{v:0}` → `{v:100}`），分别 seek 到 t=5（中途）与 t=10（末端）：
-
-| 定位方式 | `onUpdate` / `onStart` | `onComplete` | 补间目标属性 |
-|---|---|---|---|
-| `tl.seek(t)`（默认，`suppressEvents` 缺省为 `true`） | **不触发** | **不触发**——连 `seek(10)`（到末端）也不触发 | 已更新（t=5 → `v=50.00`；t=10 → `v=100.00`） |
-| `tl.seek(t, true)` | 不触发 | 不触发 | 已更新 |
-| `tl.seek(t, false)` | 触发 | `seek(10,false)` 触发；`seek(5,false)` 不触发 | 已更新 |
-| `tl.time(t)` / `tl.progress(p)` / `tl.totalTime(t)` | 触发 | 同上（按是否到末端） | 已更新 |
-
-⚠️ **`onComplete` 那两行必须分清**：默认 seek 下它**到末端也不触发**，这才是「被抑制」的证据；而 `false` 模式下 `seek(5,false)` 的 `onComplete` 不触发，只是「补间尚未走完」的正常语义。混为一谈，后来者会拿后者误判成「垫片无效」。
-
-**样本二（含真实 DOM 写入 · 引擎侧条款的直接依据）**——同一 t=1.0 定帧点，补间在 t=1.0 处的目标属性期望值 75.0，`onUpdate` 体内做一次真实 DOM 写入：
-
-| 定位方式（同一 t=1.0 定帧点） | `onUpdate` 触发次数 | 补间目标属性 | 回调内的 DOM 写入 |
-|---|---|---|---|
-| `tl.seek(1.0)`（默认） | **0 次** | 已更新为 **75.0** | **未执行** |
-| `tl.seek(1.0, false)` | 1 次 | 75.0 | 正常 |
-| `tl.time(1.0)` | 1 次 | 75.0 | 正常 |
-| `tl.progress(0.5)` | 1 次 | 75.0 | 正常 |
-
-要害是**「值更新了、回调没跑」**：补间目标对象的属性照常插值，但写在 `onUpdate` 里的 DOM 写入一次都不执行。所以这种翻车**不是黑屏，是画面定在初始态**——本地播放器与客户端预览都完全正常，比黑屏更难发现。
-
-样本二同时给出条款一的**可行性依据**：三种「不抑制」写法（`seek(t,false)` / `time(t)` / `progress(p)`）行为**完全一致**，故对引擎侧的要求**可实现且不挑实现**——引擎爱用哪种用哪种，只要不是裸 `seek(t)`。
-
-### 二、条款
-
-1. **引擎侧（MUST）**：渲染引擎定帧时 **MUST 保证 GSAP 时间线回调可达**——MUST 用 `seek(t, false)` 或 `time(t)` / `progress(p)` / `totalTime(t)`，**MUST NOT 用默认的 `seek(t)`**。违反后果：补间目标属性照常更新、回调内的 DOM 写入不执行 → 画面**定在初始态而非黑屏**，本地播放器与客户端预览均看不出异常。
-2. **颗粒侧（合规声明）**：颗粒**可以**用时间线回调（`onUpdate` / `onStart` / `onComplete` / `onRepeat`）写 DOM / 属性来驱动画面——这是**合规**写法（相机推进、数值读数这类效果用纯属性补间难以表达）。其可达性由条款 1 承担；契约 **MUST NOT** 反过来要求颗粒作者自行保证。
-3. **颗粒侧（不应）**：颗粒**不应**在运行时覆写引擎所调用的 API——重新赋值 `tl.seek`、或把 `window.__timelines[…]` 换成包装对象。两条实测理由：① 覆写会推翻引擎**显式**传入的 `seek(t, true)`（实测：打上垫片后 `seek(5)` 与 `seek(6, true)` 两次调用回调都触发），颗粒无权静默否决引擎的意图；② 垫片只作用于 `seek`，引擎改走 `time()` / `progress()` 时**完全失效**，而作者不会知道。
-   已存在的垫片属**过渡态**：**新颗粒不应再加**。**2026-07-26 更新**——条款 1 的前提已经真引擎核实（见下「三」），垫片赖以存在的「真空期」已结束，故已存在的垫片**可择期清理**（清理是**可做**、不是 MUST 做；删后须重跑 lint 并**重渲复验**）。垫片留着也无害：实测引擎既然本就不抑制回调，垫片对画面结果无影响，只会被 lint 记一条非致命的 `x-engine-api-override`。
-4. **作者侧应知（这不是甩锅）**：作者 MUST 知晓——回调可达性的保证方是**引擎侧**，且该保证当前的核实状态见下「三」（2026-07-26 起为**已核实（行为层）· 绑定引擎 0.6.101**）。`gtrk mg lint` 会对「回调驱动画面且无任何兜底」的颗粒给一条**非致命**提醒，那是**哨兵**（引擎换实现或失守时有人喊一声），**不是**「请作者自行保证 seek 下回调可达」——**核实之后哨兵照留**，因为结论绑死引擎版本，换版即须重测。
-
-### 三、核实状态：**已核实（行为层）· 2026-07-26 · 绑定渲染引擎 producer `0.6.101`**
-
-**把某条引擎行为写成 MUST，MUST NOT 被当作它已被核实**——二者在本节分别成文。本小节记的是**核实到了什么、以及没核实到什么**。
-
-**结论：真渲染引擎在定帧时 `onUpdate` 回调可达，条款 1 的前提成立。** 结论**绑定上述引擎版本**，换版即失效、须重测。
-
-- **核实方式（真引擎，非本地无头模拟）**：造一颗最小颗粒 `seekcb-probe`，**不打任何 seek 垫片**，画面正中的大号数字**只**由一条 tween 的 `onUpdate` 写入（proxy `{v:0}` → `480`，`ease:"none"`，16s），初值静态写死 `CB 000`；同屏并排一组**纯属性补间**对照物（方块横移 + 进度条拉长，均无回调），刻度尺与回调数字**同单位 0..480**，故单帧之内即可比对「应该是多少」与「实际是多少」。该颗粒先过 `gtrk mg lint`（`lint.ok=true`，`opaque=true`，只出 `x-callback-driven` 哨兵、无 `x-engine-api-override`），排除「因不合规才没渲」。走生产同款装配（`CompositionRender` 整轨路径 / 同底轨 `bed.mp4` / 1920×1080 / fps=60 / 15.97s / 958 帧分片 13 chunk）。
-- **实测结果（三帧，肉眼判读整帧 PNG）**：
-
-  | 抽帧时刻 | 回调驱动的数字（onUpdate 唯一驱动） | 纯属性补间对照物 | 期望值 |
-  |---|---|---|---|
-  | t=2s | **CB 060** | 进度条/方块 @ 60 | 060 |
-  | t=8s | **CB 240** | 进度条/方块 @ 240 | 240 |
-  | t=14s | **CB 420** | 进度条/方块 @ 420 | 420 |
-
-  三帧数字**各不相同**、**无一帧停在初值 `CB 000`**，且**逐帧与同单位对照物精确重合**——即回调不仅被触发，还是在**当前帧对应的时间点**上触发的（不是滞后一帧的陈值）。对照物同时移动，排除「整颗没渲/时间线没被定位」这一混淆解释。
-- **证据留档**：三帧整帧 PNG、成片、颗粒与渲染脚本一并留档，落点见本仓 change `define-seek-suppress-events-contract` 的工件（复现件的本地路径与文件名不进入分发契约）。引擎版本取自渲染日志自报的 producer `0.6.101`。
-- **⚠️ 本次核实的边界（MUST NOT 越界引用）**：核实的是**可观测行为**（回调可达），**不是调用形态**。引擎仍是无源码第三方包，本轮**没有**读到定帧调用点，故**无法区分**它走的是 `seek(t,false)` / `time(t)` / `progress(p)`，还是压根不经 GSAP 定位 API 的自有推进方式。条款 1 里那串 API 白名单仍是**应然的实现约束**，只有「回调 MUST 可达」这个**结果**被真机背书。调用形态的核实仍由 gitruck-infra 侧联动 change `link-guarantee-seek-callback-reachability` 承接（读调用点 + 把「纯回调驱动无垫片颗粒渲两帧、像素 MUST 不同」挂进引擎版本变更门禁）。
-- **旁证（本轮之前的间接证据，保留备查）**：gitruck-infra 自家 9 个 music_visualizer 模板 **9/9** 把整块画面挂在单条 tween 的 `onUpdate` 上、且 **0/9** 带任何垫片，走的正是同一渲染内核，而 `gtrk music-visualizer` 是**已上线**能力——若引擎默认抑制回调，这 9 个模板早该渲成静止首帧。本仓 exemplar b06/b07/b08 同理。本轮直接核实**与旁证同向**。
-- **假设失效的后果（哨兵为何 MUST 留）**：结论绑定 `0.6.101`；引擎升版换调用方式 → 全部回调驱动型颗粒（MG 与 music_visualizer 模板）**一起静默冻结**，lint 全绿、退出码 0、无任何告警。故 `gtrk mg lint` 的 `x-callback-driven` 哨兵（条款 4）**MUST NOT 因本次核实而撤**——它防的正是「换版后无人喊一声」。
-
-### 四、连带风险：回调可达 = 逐帧反复触发
-
-条款 1 的另一面：逐帧 scrub 时 `onComplete` / `onStart` / `onRepeat` 会**反复触发**（每帧一次）。故颗粒 **MUST NOT** 把「只跑一次」的逻辑写进回调——累加计数、`push` 进数组、一次性 DOM 插入、抽样。那会把「静默冻结」换成「静默错乱」。
-
-**2026-07-26 起这条从「假设的另一面」变成「已确证的现实风险」**：上「三」已实测该引擎**确实**在逐帧定位时触发回调，故本条不是防患于未然，而是**当下就在生效**的约束。
-
-**推荐写法**：回调做成**幂等**的——每次都从补间状态**重算**整个画面，不依赖上一次的结果（真机与 exemplar 的 `render()` / `apply()` / `paint()` 均如此）。
-
-### 五、优先级
-
-**本节口径优先于任何栏目指南的招式建议。** 栏目指南若与本节冲突，以本节为准。（当前二者同向：栏目指南推荐的 `onUpdate` 驱动写法在本节下**合规**，作坊侧**无需修订**——本节不向作坊侧派发任何待办。此条照写不误，它防的是将来的分歧。）
-
----
-
-### 铁律 4「实心底下沉子层」的真机证据锚（2026-07-26）
-
-本条断言的是**渲染引擎行为**（「根元素的绘制属性在挂载时被丢弃」），故按契约库要求附可追溯证据锚：
-
-- **结论**：根 `style` 的 `background` **不落成像素**；同一颗粒把同一底色改写到根下首个全幅子层则**满屏落地并盖住底轨**。
-- **实验日期 / 机器**：2026-07-26 · 真机（生产同款渲染主机；真渲，非本地无头模拟）。
-- **引擎版本口径**：渲染引擎 CLI 与 producer 同版 `0.6.101` · 无头浏览器内核 `131.x`。
-- **设计**：同颗粒母本造两个变体，**唯一变量 = 实心底摆在根 `style` 还是根下首个全幅子层**，其余逐字节相同；
-  底色临时取高饱和标志色以便与「根合成兜底黑」区分；底轨用一段有明显画面、非黑的真人镜头；抽同一时间点 `t=8.0s` 的帧，
-  取四角 `crop=40:40` 于 `(20,20) (1860,20) (20,1020) (1860,1020)` 后 `scale=1:1` 读像素。
-- **观测**（整轨拆分渲染路径，两格同素材同引擎同批）。
-  ⚠️ 下表的六位数字是**抽帧读出的 RGB 像素读数**（实验观测），**不是本契约规定的任何底色**——
-  轴一边界照旧：契约不点名任何色值，底色取值永远由调用方栏目决定：
-
-  | 变体 | 四角像素 | 判读 |
-  |---|---|---|
-  | 实心底写**根 `style`** | `dfdad4 / fafcfb / 4e4f52 / f9fbfb` | ≈ 底轨基线 → **底丢失、底轨透出** |
-  | 实心底写**根下首个全幅子层** | `01ff81 / 00fe80 / 01fd80 / 01fd80` | ≈ 标志色 → **底存活、满屏盖住底轨** |
-  | 底轨本身（阴性对照） | `e0dbd4 / fbfdfc / 4f5052 / fbfdfd` | 四角始终高亮非黑，对照有效 |
-
-- **阳性对照（关键，排除平凡解）**：「写根」那格的整帧里颗粒**前景元素完整渲出**（标题文字、网格、连线、色块都在）——
-  所以它**不是「颗粒没渲上」，而是「颗粒渲上了、根 `background` 被丢掉」**。缺这一步，两种情况在像素上同解。
-- **复现方式**：造上述两变体 → 同一批走整轨拆分渲染 → 按上「设计」段的抽帧与四角取样口径（`t=8.0s` 单帧 / `crop=40:40` / `scale=1:1`）取样，
-  再以 RGB24 原始字节读出四角的十六进制像素值。取样工具与复现件的本地路径不进入分发契约（同铁律 8 证据锚口径）。
-- **历史**：本条现象最早由创作侧于 **2026-07-15** 记载（一颗满屏颗粒的根 `background` 丢帧、成片只剩浮空面板），
-  当时未进框架契约，框架正本反而长期要求「写在根上」——2026-07-26 的实验复现并坐实了该记载，本条据此改写。
-- **相关跨仓 change**：`gitruck-cli` / `align-particle-solid-backdrop-contract`（本条的来源）；
-  `gitruck-infra` / `add-html-animate-opaque-fullscreen-cover`（**另一个独立问题**：渲染侧要不要按 `opaque` 位替颗粒兜一层黑底）。
-  ⚠️ 两者**互不依赖**：上表的观测正是在后者**未 apply** 时取得的——即**本条的修法（下沉子层）当场生效，不需要渲染侧任何配合**。
-
-### 铁律 8「重复图元合并」的真机证据锚（2026-07-26）
-
-本条断言的是一条**作者侧规避写法**及其在真渲染中的效果，不断言已知触发轴。证据锚如下：
-
-- **结论**：同一故障样本把 37 条满幅 `<line>` 合为一条 `<path>` 多子路径后，目标画面逐像素不变，横带重复率由 **65%～68% 降至 2%**；规避当场有效，但合并同时改变了图元数、DOM 结构与栅格化路径，故本实验**不能证明是哪一个变量生效**。
-- **实验日期 / 机器**：2026-07-26 · 真机（生产同款渲染主机；真渲，非本地无头模拟）。
-- **引擎版本口径**：渲染引擎 CLI 与 producer 同版 `0.6.101` · 无头浏览器内核 `131.x`。
-- **二分设计**：以同一颗粒为母本逐项只改一个构建块，每个变体各做一次真渲；每格抽取 168 帧，按等高横带间的重复像素统计复现率。装配路径、分辨率、帧率、底轨与其余颗粒代码保持一致。
-- **范围限定（硬约束）**：下表全部是**同一颗粒内部**的二分结果，**MUST NOT 跨颗粒外推**；它只能说明这些改动在该颗粒内与复现率同向变化，不能推出「元素数少就安全」或任何数字门槛。
-
-  | 同一颗粒内的变体 | 重复率 | 限定读法 |
-  |---|---:|---|
-  | 原件：背景网格为 37 条满幅 `<line>` | **65%～68%**（复跑一致） | 故障基线 |
-  | 37 条 `<line>` 合为一条 `<path>` 多子路径 | **2%** | 本条规避正例；目标画面逐像素不变 |
-  | 整块删除背景网格 | **2%** | 与合并同档；只说明该块在本颗粒内参与复现 |
-  | 删除两个静态术语文本块 | **0%～1%** | 删除任一块负载都退烧；作用域仅限本颗粒，机制未知 |
-  | 删除三行静态标签文本块 | **0%～1%** | 同上 |
-  | 换字体族 / 去斜体 / 关闭 3D 加速 / 改入场位移 / 把文字改为 SVG `<text>` / 给根加变换提示 / 把网格改静态 | **仍为 65%+** | 均无效 |
-  | 增加满屏失效脉冲层 | **14%** | 作者侧强制全幅失效仍不能根治 |
-  | 极简结构（20 个静态 `<div>` + 1 个网格） | **0%** | 空载变体不复现；不得外推为通用预算 |
-
-- **阳性对照（排除平凡解）**：合并版仍完整绘制与原件相同的整张网格，逐像素对拍一致；它不是「把内容删没了所以不重复」。同一颗粒内另有 24 条局部短线在合并版中继续保留，故 24 与 37 也 **MUST NOT** 被写成安全 / 故障分界。
-- **跨颗粒反证（同批全量体检）**：同装配、同引擎、同机完成 **21 颗粒 + 六 beat 同页聚合，共 24 次渲染 / 约 22,000 帧**。这些结果专门限制上表的外推范围：
-
-  | 样本 | 真渲结果 | 可否证的候选轴 |
-  |---|---:|---|
-  | 另一密阵样本：884 条短划、全颗共 921 个绘制图元 | **0.0% 脏帧** | 图元总数、同父同类聚簇 |
-  | 六 beat 同页聚合：约 1,400 个绘制图元 | **0.0% 脏帧** | 同页累积负载 |
-  | 当前修复版样本（回归 / 阴性对照） | **0.0% 脏帧** | 规避在整轨分片路径下仍稳 |
-  | 未修版样本（阳性对照） | **70.3% 脏帧** | 缺陷仍活且可稳定复现 |
-
-  **真实触发轴至今未知**；当前已否证的候选轴 = **图元总数 / 同页累积负载 / 同父同类聚簇**。上表中「921 个图元干净」与「较少图元的阳性对照中招」同时成立，因此数字方向不存在可据此写入契约的安全门槛。
-- **复现方式**：从同一母本生成上述单变量变体 → 走生产同款整轨分片渲染 → 对每格 168 帧计算等高横带间的重复率并抽取高分帧肉眼复核；再以同一口径跑 21 颗全量语料、六 beat 同页聚合、修复版阴性对照与未修版阳性对照。复现件的本地路径与文件名不进入分发契约。
-- **相关 change / 根治状态**：本仓 `add-particle-primitive-merge-law` 收录作者侧规避；渲染管线侧根治**未立项（2026-07-26，本 change 实施会话按非目标不代提；待主理人另行决定）**。根治上线并经真机确认后，按铁律 8 的预案把 MUST 降为 SHOULD。
-
----
-
-### 证据锚（只收有出处的数；每条带测量日期 + 语料标注）
-
-- **测量日期**：2026-07-30。**版本口径**：渲染引擎 CLI 与 producer 同版 `0.7.82` · 无头浏览器内核 `152.x`。
-  测量在真机（生产同款渲染主机）取得，非本地无头模拟。
-- **现网既有栏目语料（21 颗生产颗粒）**：去掉真卷积滤镜的可省墙钟 **0~3.1%**——即**本节对现有语料近似零收益**，
-  它立在这里是**前置门**（防止大批带滤镜的新语料进渲染管线后整批返工），**不是**提速手段。
-- ⚠️ **「去滤镜省墙钟」依颗粒形态而定，MUST NOT 一概而论**（2026-08-06 真机同颗粒对照，**测出方向相反的两侧**）：
-  | 形态 | 去滤镜后墙钟 | 产物字节 | 方向 |
-  |---|---|---|---|
-  | **局部**滤镜、底下**平坦**（现网真颗粒：790×290 衬底 + 词光） | 51.66s → **46.10s（省 10.76%）** | −62% | **省** |
-  | **整幅**滤镜、底下**带抖动渐变** | 38.07s → **69.70s（慢 83%）** | +29%（356 MB → 459 MB） | **亏** |
-  **机制是同一条**：本管线的墙钟由 **capture + encode** 主导（capture 约占单次 CLI 全程 **89%**），
-  而 `blur` **抹掉高频** ⇒ 每帧截图与 ProRes 4444 编码都更便宜。
-  ⇒ **决定墙钟的是「去掉滤镜后画面频谱的变化方向」，不是「有没有滤镜」**——
-  去滤镜让画面变平就省，让高频回来就亏。
-  📌 **这条不动摇本节的立项与条文**：本节真正要抓的是**每帧重卷积导致缓存失效**那一类
-  （补间驱动 `filter` / 静态 filter 而 `transform` 被补间驱动），它们是**同一颗粒内的对照**、方向确定为正
-  （实测 **+36.2%** / **+42.7%**），与「去不去某个滤镜」是两个不同的问题。
-- **单次误用的止损量级（同一颗粒内对照）**：**1.3~3.3×**。
-- **同一颗粒内的形态对照（2026-08-06 真机，1920×1080 / 180 帧 / 30fps，每档 3 次取中位数）**——
-  这组才是本节条文的直接依据（**控制内容不变、只换 filter 的用法**）：
-  | 形态 | 中位墙钟 | 相对整幅静态 blur |
-  |---|---|---|
-  | 整幅**静态** `blur(24px)`（基准） | 38.07s | — |
-  | `gsap.set` **只设一次** filter | 38.29s | **+0.6%（噪声内，产物逐字节相同）** ⇒ 等价于静态 |
-  | 整幅 blur **被补间驱动**（8→40px） | 51.86s | **+36.2%** |
-  | **静态** filter、其 `transform` **被补间驱动** | 54.32s | **+42.7%（最贵的一档）** |
-- **滤镜重语料（技法颗粒，单颗 646 帧）**：**7.0×**（339.6s → 48.3s）。
-  ⚠️ 该数**只对该语料成立**，MUST NOT 外推成通用提速承诺。
-- **消费侧沉默不等于便宜**：`gtrk mg lint` 的四个成本项（`c-filter-animated` / `c-filter-static-fullbleed` /
-  **`c-filter-static-transformed`**（2026-08-06 增补，覆盖上面那条 +42.7% 的漏报面）/ `c-filter-indeterminate`）
-  是**形态提示**，**当期一律非致命、不拦铺轨**；没报**不代表**这颗渲得快——
-  真判据永远是**真渲染出片计时**。
-- **致命性的升级触发器（登记在此，免得日后凭印象改）**：把 `c-filter-animated` 提为**致命**
-  SHALL 另走一个独立 change，且 SHALL 同时满足两项前提——① 「滤镜重语料批量进渲染管线」那条路线**已立项**；
-  ② 提级前对现网生产语料**全量复扫且零命中**（复扫在生产颗粒上命中 > 0 即 MUST NOT 提级）。
-  触发一次评估的时机 = 上述路线立项 **或** 本节首次改版，以先到者为准。
-  **MUST NOT** 以「规范就该严」为由径直提级，也 **MUST NOT** 把致命性做成可现场翻转的运行期开关。
-
-### 根治登记
-
-- **① 这是降本规范、不是缺陷规避**：命中项的画面本身是对的，逐帧也正确，只是每帧贵。
-- **② 成本的根在渲染管线侧**：逐帧路径走**软件光栅**（无图形硬件加速），卷积按面积×半径吃 CPU。
-- **③ 根治状态 = 明确不立项（2026-07-30）**：改走图形硬件加速路径会破坏「逐帧确定性」与「产出端版本对齐」这两项前提
-  （异构机器还会破坏分片与单次的产物等价），渲染侧调研已把它列为**已排除项**。故本节以作者侧写法收敛，不等渲染侧。
-- **④ 根治后的处置预案**：若渲染侧将来换掉光栅路径并经真机复测确认成本塌陷，本节由 MUST NOT/SHOULD **降为提示**，
-  并保留「本节曾于 2026-07-30、本证据锚所载版本口径下作为降本规范所必需」的历史记录。
+# gsap-emit v1 · 证据附录
+
+本文件供契约维护者追溯实验、版本和阈值来源，不是 agent 执行时的必读文档。当前有效规则以 [`gsap-emit-v1.md`](gsap-emit-v1.md) 为准；本附录中的日期、样本和版本不能覆盖正文契约。
+
+---
+
+## 回调与 seek 语义（2026-07-26 增补 · 补此前留白）
+
+> **一句话**：颗粒**可以**用时间线回调（`onUpdate` 等）驱动画面；**保证这些回调在定帧时被触发是渲染引擎侧的义务**，不是颗粒作者的义务。
+> 本节是该主题的**唯一口径来源**——契约引用（`skills/gtrk-style-maker/references/contracts-ref.md`）与消费侧检查（`gtrk mg lint`）的文案都指向这里，不得各自表述。
+
+### 当前版本补记（2026-10-13）
+
+发布物只读确认 CLI / producer 均为 0.7.100，适配器 `suppressEvents===true` 才抑制，缺省以 totalTime(t,false) 定位；无 totalTime 时回退 seek(t,false)。2026-09-16 双入口真实断言（120 帧，#30 / #90）均通过；本次源码核对未当作新的真渲。原始短摘录与 SHA-256 在 infra `.plans/p1p2-2026-10-13/mg-source.json`。内部一次性回调依赖、tween 结束后的静态去重仍未直接验证，换版门禁和哨兵保留。
+
+### 一、GSAP 3.13.0 实测事实（写死在此，免后来者重测）
+
+复现方式：拉铁律⑤指定 CDN 的 `gsap.min.js` 到本地，Node `vm` 里造 `paused` timeline + proxy 对象 + 计数回调，**每种定位方式各新建一条 timeline 单独跑**（回调计数互不串）。
+
+**样本一**——10s、`ease:"none"` 的单条 tween（`{v:0}` → `{v:100}`），分别 seek 到 t=5（中途）与 t=10（末端）：
+
+| 定位方式 | `onUpdate` / `onStart` | `onComplete` | 补间目标属性 |
+|---|---|---|---|
+| `tl.seek(t)`（默认，`suppressEvents` 缺省为 `true`） | **不触发** | **不触发**——连 `seek(10)`（到末端）也不触发 | 已更新（t=5 → `v=50.00`；t=10 → `v=100.00`） |
+| `tl.seek(t, true)` | 不触发 | 不触发 | 已更新 |
+| `tl.seek(t, false)` | 触发 | `seek(10,false)` 触发；`seek(5,false)` 不触发 | 已更新 |
+| `tl.time(t)` / `tl.progress(p)` / `tl.totalTime(t)` | 触发 | 同上（按是否到末端） | 已更新 |
+
+⚠️ **`onComplete` 那两行必须分清**：默认 seek 下它**到末端也不触发**，这才是「被抑制」的证据；而 `false` 模式下 `seek(5,false)` 的 `onComplete` 不触发，只是「补间尚未走完」的正常语义。混为一谈，后来者会拿后者误判成「垫片无效」。
+
+**样本二（含真实 DOM 写入 · 引擎侧条款的直接依据）**——同一 t=1.0 定帧点，补间在 t=1.0 处的目标属性期望值 75.0，`onUpdate` 体内做一次真实 DOM 写入：
+
+| 定位方式（同一 t=1.0 定帧点） | `onUpdate` 触发次数 | 补间目标属性 | 回调内的 DOM 写入 |
+|---|---|---|---|
+| `tl.seek(1.0)`（默认） | **0 次** | 已更新为 **75.0** | **未执行** |
+| `tl.seek(1.0, false)` | 1 次 | 75.0 | 正常 |
+| `tl.time(1.0)` | 1 次 | 75.0 | 正常 |
+| `tl.progress(0.5)` | 1 次 | 75.0 | 正常 |
+
+要害是**「值更新了、回调没跑」**：补间目标对象的属性照常插值，但写在 `onUpdate` 里的 DOM 写入一次都不执行。所以这种翻车**不是黑屏，是画面定在初始态**。旧客户端预览也曾使用裸 `seek(t)`，同样会冻结；2026-09-11 客户端修复改为 `seek(t,false)` / `pause(0,false)`。只有包含该修复的客户端才可作为预览对照，不能笼统说所有客户端都正常。
+
+样本二给出条款一的**可行性依据**，但三种不抑制写法的等价性仅限本样本的无 repeat 时间线。2026-09-11 GSAP 3.13.0 对照：根时间线 repeat=1 / yoyo=true、2s 补间 v:0→100，请求 3.5s，`seek(3.5,false)` / `totalTime(3.5)` 得 v=25，`time(3.5)` 得 v=75（totalTime=1.5）。`time` / `progress` 定位当前迭代，不能泛化为完整时间轴定位。
+
+### 二、条款
+
+1. **引擎侧（MUST）**：定帧必须保证回调可达和完整时间轴落点正确，优先 `seek(t,false)` / `totalTime(t,false)`；`time` / `progress` 只可用于无 repeat 的根时间线。不得用裸 `seek(t)`。否则可能出现属性更新而 DOM 冻结，旧客户端预览也可能同样受影响；预览修复不替代云端断言。
+2. **颗粒侧（合规声明）**：颗粒**可以**用时间线回调（`onUpdate` / `onStart` / `onComplete` / `onRepeat`）写 DOM / 属性来驱动画面——这是**合规**写法（相机推进、数值读数这类效果用纯属性补间难以表达）。其可达性由条款 1 承担；契约 **MUST NOT** 反过来要求颗粒作者自行保证。
+3. **颗粒侧（不应）**：颗粒**不应**在运行时覆写引擎所调用的 API——重新赋值 `tl.seek`、或把 `window.__timelines[…]` 换成包装对象。两条实测理由：① 覆写会推翻引擎**显式**传入的 `seek(t, true)`（实测：打上垫片后 `seek(5)` 与 `seek(6, true)` 两次调用回调都触发），颗粒无权静默否决引擎的意图；② 垫片只作用于 `seek`，引擎改走 `time()` / `progress()` 时**完全失效**，而作者不会知道。
+   已存在的垫片属**过渡态**：**新颗粒不应再加**。**2026-07-26 更新**——条款 1 的前提已经真引擎核实（见下「三」），垫片赖以存在的「真空期」已结束，故已存在的垫片**可择期清理**（清理是**可做**、不是 MUST 做；删后须重跑 lint 并**重渲复验**）。垫片留着也无害：实测引擎既然本就不抑制回调，垫片对画面结果无影响，只会被 lint 记一条非致命的 `x-engine-api-override`。
+4. **作者侧应知（这不是甩锅）**：作者 MUST 知晓——回调可达性的保证方是**引擎侧**，且该保证当前的核实状态见下「三」（2026-07-26 起为**已核实（行为层）· 绑定引擎 0.6.101**）。`gtrk mg lint` 会对「回调驱动画面且无任何兜底」的颗粒给一条**非致命**提醒，那是**哨兵**（引擎换实现或失守时有人喊一声），**不是**「请作者自行保证 seek 下回调可达」——**核实之后哨兵照留**，因为结论绑死引擎版本，换版即须重测。
+
+### 三、核实状态：**已核实（行为层）· 2026-07-26 · 绑定渲染引擎 producer `0.6.101`**
+
+**把某条引擎行为写成 MUST，MUST NOT 被当作它已被核实**——二者在本节分别成文。本小节记的是**核实到了什么、以及没核实到什么**。
+
+**结论：真渲染引擎在定帧时 `onUpdate` 回调可达，条款 1 的前提成立。** 结论**绑定上述引擎版本**，换版即失效、须重测。
+
+- **核实方式（真引擎，非本地无头模拟）**：造一颗最小颗粒 `seekcb-probe`，**不打任何 seek 垫片**，画面正中的大号数字**只**由一条 tween 的 `onUpdate` 写入（proxy `{v:0}` → `480`，`ease:"none"`，16s），初值静态写死 `CB 000`；同屏并排一组**纯属性补间**对照物（方块横移 + 进度条拉长，均无回调），刻度尺与回调数字**同单位 0..480**，故单帧之内即可比对「应该是多少」与「实际是多少」。该颗粒先过 `gtrk mg lint`（`lint.ok=true`，`opaque=true`，只出 `x-callback-driven` 哨兵、无 `x-engine-api-override`），排除「因不合规才没渲」。走生产同款装配（`CompositionRender` 整轨路径 / 同底轨 `bed.mp4` / 1920×1080 / fps=60 / 15.97s / 958 帧分片 13 chunk）。
+- **实测结果（三帧，肉眼判读整帧 PNG）**：
+
+  | 抽帧时刻 | 回调驱动的数字（onUpdate 唯一驱动） | 纯属性补间对照物 | 期望值 |
+  |---|---|---|---|
+  | t=2s | **CB 060** | 进度条/方块 @ 60 | 060 |
+  | t=8s | **CB 240** | 进度条/方块 @ 240 | 240 |
+  | t=14s | **CB 420** | 进度条/方块 @ 420 | 420 |
+
+  三帧数字**各不相同**、**无一帧停在初值 `CB 000`**，且**逐帧与同单位对照物精确重合**——即回调不仅被触发，还是在**当前帧对应的时间点**上触发的（不是滞后一帧的陈值）。对照物同时移动，排除「整颗没渲/时间线没被定位」这一混淆解释。
+- **证据留档**：三帧整帧 PNG、成片、颗粒与渲染脚本一并留档，落点见本仓 change `define-seek-suppress-events-contract` 的工件（复现件的本地路径与文件名不进入分发契约）。引擎版本取自渲染日志自报的 producer `0.6.101`。
+- **⚠️ 本次核实的边界（MUST NOT 越界引用）**：核实的是**可观测行为**（回调可达），**不是调用形态**。引擎仍是无源码第三方包，本轮**没有**读到定帧调用点，故**无法区分**它走的是 `seek(t,false)` / `time(t)` / `progress(p)`，还是压根不经 GSAP 定位 API 的自有推进方式。条款 1 里那串 API 白名单仍是**应然的实现约束**，只有「回调 MUST 可达」这个**结果**被真机背书。调用形态的核实仍由 gitruck-infra 侧联动 change `link-guarantee-seek-callback-reachability` 承接（读调用点 + 把「纯回调驱动无垫片颗粒渲两帧、像素 MUST 不同」挂进引擎版本变更门禁）。
+- **旁证（本轮之前的间接证据，保留备查）**：gitruck-infra 自家 9 个 music_visualizer 模板 **9/9** 把整块画面挂在单条 tween 的 `onUpdate` 上、且 **0/9** 带任何垫片，走的正是同一渲染内核，而 `gtrk music-visualizer` 是**已上线**能力——若引擎默认抑制回调，这 9 个模板早该渲成静止首帧。本仓 exemplar b06/b07/b08 同理。本轮直接核实**与旁证同向**。
+- **假设失效的后果（哨兵为何 MUST 留）**：结论绑定 `0.6.101`；引擎升版换调用方式 → 全部回调驱动型颗粒（MG 与 music_visualizer 模板）**一起静默冻结**，lint 全绿、退出码 0、无任何告警。故 `gtrk mg lint` 的 `x-callback-driven` 哨兵（条款 4）**MUST NOT 因本次核实而撤**——它防的正是「换版后无人喊一声」。
+
+### 四、连带风险：回调可达 = 逐帧反复触发
+
+条款 1 的另一面：逐帧 scrub 时 `onComplete` / `onStart` / `onRepeat` 会**反复触发**（每帧一次）。故颗粒 **MUST NOT** 把「只跑一次」的逻辑写进回调——累加计数、`push` 进数组、一次性 DOM 插入、抽样。那会把「静默冻结」换成「静默错乱」。
+
+**2026-07-26 起这条从「假设的另一面」变成「已确证的现实风险」**：上「三」已实测该引擎**确实**在逐帧定位时触发回调，故本条不是防患于未然，而是**当下就在生效**的约束。
+
+**推荐写法**：回调做成**幂等**的——每次都从补间状态**重算**整个画面，不依赖上一次的结果（真机与 exemplar 的 `render()` / `apply()` / `paint()` 均如此）。
+
+### 五、优先级
+
+**本节口径优先于任何栏目指南的招式建议。** 栏目指南若与本节冲突，以本节为准。（当前二者同向：栏目指南推荐的 `onUpdate` 驱动写法在本节下**合规**，作坊侧**无需修订**——本节不向作坊侧派发任何待办。此条照写不误，它防的是将来的分歧。）
+
+---
+
+### 铁律 4「实心底下沉子层」的真机证据锚（2026-07-26）
+
+本条断言的是**渲染引擎行为**（「根元素的绘制属性在挂载时被丢弃」），故按契约库要求附可追溯证据锚：
+
+- **结论**：根 `style` 的 `background` **不落成像素**；同一颗粒把同一底色改写到根下首个全幅子层则**满屏落地并盖住底轨**。
+- **实验日期 / 机器**：2026-07-26 · 真机（生产同款渲染主机；真渲，非本地无头模拟）。
+- **引擎版本口径**：渲染引擎 CLI 与 producer 同版 `0.6.101` · 无头浏览器内核 `131.x`。
+- **设计**：同颗粒母本造两个变体，**唯一变量 = 实心底摆在根 `style` 还是根下首个全幅子层**，其余逐字节相同；
+  底色临时取高饱和标志色以便与「根合成兜底黑」区分；底轨用一段有明显画面、非黑的真人镜头；抽同一时间点 `t=8.0s` 的帧，
+  取四角 `crop=40:40` 于 `(20,20) (1860,20) (20,1020) (1860,1020)` 后 `scale=1:1` 读像素。
+- **观测**（整轨拆分渲染路径，两格同素材同引擎同批）。
+  ⚠️ 下表的六位数字是**抽帧读出的 RGB 像素读数**（实验观测），**不是本契约规定的任何底色**——
+  轴一边界照旧：契约不点名任何色值，底色取值永远由调用方栏目决定：
+
+  | 变体 | 四角像素 | 判读 |
+  |---|---|---|
+  | 实心底写**根 `style`** | `dfdad4 / fafcfb / 4e4f52 / f9fbfb` | ≈ 底轨基线 → **底丢失、底轨透出** |
+  | 实心底写**根下首个全幅子层** | `01ff81 / 00fe80 / 01fd80 / 01fd80` | ≈ 标志色 → **底存活、满屏盖住底轨** |
+  | 底轨本身（阴性对照） | `e0dbd4 / fbfdfc / 4f5052 / fbfdfd` | 四角始终高亮非黑，对照有效 |
+
+- **阳性对照（关键，排除平凡解）**：「写根」那格的整帧里颗粒**前景元素完整渲出**（标题文字、网格、连线、色块都在）——
+  所以它**不是「颗粒没渲上」，而是「颗粒渲上了、根 `background` 被丢掉」**。缺这一步，两种情况在像素上同解。
+- **复现方式**：造上述两变体 → 同一批走整轨拆分渲染 → 按上「设计」段的抽帧与四角取样口径（`t=8.0s` 单帧 / `crop=40:40` / `scale=1:1`）取样，
+  再以 RGB24 原始字节读出四角的十六进制像素值。取样工具与复现件的本地路径不进入分发契约（同铁律 8 证据锚口径）。
+- **历史**：本条现象最早由创作侧于 **2026-07-15** 记载（一颗满屏颗粒的根 `background` 丢帧、成片只剩浮空面板），
+  当时未进框架契约，框架正本反而长期要求「写在根上」——2026-07-26 的实验复现并坐实了该记载，本条据此改写。
+- **相关跨仓 change**：`gitruck-cli` / `align-particle-solid-backdrop-contract`（本条的来源）；
+  `gitruck-infra` / `add-html-animate-opaque-fullscreen-cover`（**另一个独立问题**：渲染侧要不要按 `opaque` 位替颗粒兜一层黑底）。
+  ⚠️ 两者**互不依赖**：上表的观测正是在后者**未 apply** 时取得的——即**本条的修法（下沉子层）当场生效，不需要渲染侧任何配合**。
+
+### 铁律 8「重复图元合并」的真机证据锚（2026-07-26）
+
+本条断言的是一条**作者侧规避写法**及其在真渲染中的效果，不断言已知触发轴。证据锚如下：
+
+- **结论**：同一故障样本把 37 条满幅 `<line>` 合为一条 `<path>` 多子路径后，目标画面逐像素不变，横带重复率由 **65%～68% 降至 2%**；规避当场有效，但合并同时改变了图元数、DOM 结构与栅格化路径，故本实验**不能证明是哪一个变量生效**。
+- **实验日期 / 机器**：2026-07-26 · 真机（生产同款渲染主机；真渲，非本地无头模拟）。
+- **引擎版本口径**：渲染引擎 CLI 与 producer 同版 `0.6.101` · 无头浏览器内核 `131.x`。
+- **二分设计**：以同一颗粒为母本逐项只改一个构建块，每个变体各做一次真渲；每格抽取 168 帧，按等高横带间的重复像素统计复现率。装配路径、分辨率、帧率、底轨与其余颗粒代码保持一致。
+- **范围限定（硬约束）**：下表全部是**同一颗粒内部**的二分结果，**MUST NOT 跨颗粒外推**；它只能说明这些改动在该颗粒内与复现率同向变化，不能推出「元素数少就安全」或任何数字门槛。
+
+  | 同一颗粒内的变体 | 重复率 | 限定读法 |
+  |---|---:|---|
+  | 原件：背景网格为 37 条满幅 `<line>` | **65%～68%**（复跑一致） | 故障基线 |
+  | 37 条 `<line>` 合为一条 `<path>` 多子路径 | **2%** | 本条规避正例；目标画面逐像素不变 |
+  | 整块删除背景网格 | **2%** | 与合并同档；只说明该块在本颗粒内参与复现 |
+  | 删除两个静态术语文本块 | **0%～1%** | 删除任一块负载都退烧；作用域仅限本颗粒，机制未知 |
+  | 删除三行静态标签文本块 | **0%～1%** | 同上 |
+  | 换字体族 / 去斜体 / 关闭 3D 加速 / 改入场位移 / 把文字改为 SVG `<text>` / 给根加变换提示 / 把网格改静态 | **仍为 65%+** | 均无效 |
+  | 增加满屏失效脉冲层 | **14%** | 作者侧强制全幅失效仍不能根治 |
+  | 极简结构（20 个静态 `<div>` + 1 个网格） | **0%** | 空载变体不复现；不得外推为通用预算 |
+
+- **阳性对照（排除平凡解）**：合并版仍完整绘制与原件相同的整张网格，逐像素对拍一致；它不是「把内容删没了所以不重复」。同一颗粒内另有 24 条局部短线在合并版中继续保留，故 24 与 37 也 **MUST NOT** 被写成安全 / 故障分界。
+- **跨颗粒反证（同批全量体检）**：同装配、同引擎、同机完成 **21 颗粒 + 六 beat 同页聚合，共 24 次渲染 / 约 22,000 帧**。这些结果专门限制上表的外推范围：
+
+  | 样本 | 真渲结果 | 可否证的候选轴 |
+  |---|---:|---|
+  | 另一密阵样本：884 条短划、全颗共 921 个绘制图元 | **0.0% 脏帧** | 图元总数、同父同类聚簇 |
+  | 六 beat 同页聚合：约 1,400 个绘制图元 | **0.0% 脏帧** | 同页累积负载 |
+  | 当前修复版样本（回归 / 阴性对照） | **0.0% 脏帧** | 规避在整轨分片路径下仍稳 |
+  | 未修版样本（阳性对照） | **70.3% 脏帧** | 缺陷仍活且可稳定复现 |
+
+  **真实触发轴至今未知**；当前已否证的候选轴 = **图元总数 / 同页累积负载 / 同父同类聚簇**。上表中「921 个图元干净」与「较少图元的阳性对照中招」同时成立，因此数字方向不存在可据此写入契约的安全门槛。
+- **复现方式**：从同一母本生成上述单变量变体 → 走生产同款整轨分片渲染 → 对每格 168 帧计算等高横带间的重复率并抽取高分帧肉眼复核；再以同一口径跑 21 颗全量语料、六 beat 同页聚合、修复版阴性对照与未修版阳性对照。复现件的本地路径与文件名不进入分发契约。
+- **相关 change / 根治状态**：本仓 `add-particle-primitive-merge-law` 收录作者侧规避；渲染管线侧根治**未立项（2026-07-26，本 change 实施会话按非目标不代提；待主理人另行决定）**。根治上线并经真机确认后，按铁律 8 的预案把 MUST 降为 SHOULD。
+
+---
+
+### 证据锚（只收有出处的数；每条带测量日期 + 语料标注）
+
+- **测量日期**：2026-07-30。**版本口径**：渲染引擎 CLI 与 producer 同版 `0.7.82` · 无头浏览器内核 `152.x`。
+  测量在真机（生产同款渲染主机）取得，非本地无头模拟。
+- **现网既有栏目语料（21 颗生产颗粒）**：去掉真卷积滤镜的可省墙钟 **0~3.1%**——即**本节对现有语料近似零收益**，
+  它立在这里是**前置门**（防止大批带滤镜的新语料进渲染管线后整批返工），**不是**提速手段。
+- ⚠️ **「去滤镜省墙钟」依颗粒形态而定，MUST NOT 一概而论**（2026-08-06 真机同颗粒对照，**测出方向相反的两侧**）：
+  | 形态 | 去滤镜后墙钟 | 产物字节 | 方向 |
+  |---|---|---|---|
+  | **局部**滤镜、底下**平坦**（现网真颗粒：790×290 衬底 + 词光） | 51.66s → **46.10s（省 10.76%）** | −62% | **省** |
+  | **整幅**滤镜、底下**带抖动渐变** | 38.07s → **69.70s（慢 83%）** | +29%（356 MB → 459 MB） | **亏** |
+  **机制是同一条**：本管线的墙钟由 **capture + encode** 主导（capture 约占单次 CLI 全程 **89%**），
+  而 `blur` **抹掉高频** ⇒ 每帧截图与 ProRes 4444 编码都更便宜。
+  ⇒ **决定墙钟的是「去掉滤镜后画面频谱的变化方向」，不是「有没有滤镜」**——
+  去滤镜让画面变平就省，让高频回来就亏。
+  📌 **这条不动摇本节的立项与条文**：本节真正要抓的是**每帧重卷积导致缓存失效**那一类
+  （补间驱动 `filter` / 静态 filter 而 `transform` 被补间驱动），它们是**同一颗粒内的对照**、方向确定为正
+  （实测 **+36.2%** / **+42.7%**），与「去不去某个滤镜」是两个不同的问题。
+- **单次误用的止损量级（同一颗粒内对照）**：**1.3~3.3×**。
+- **同一颗粒内的形态对照（2026-08-06 真机，1920×1080 / 180 帧 / 30fps，每档 3 次取中位数）**——
+  这组才是本节条文的直接依据（**控制内容不变、只换 filter 的用法**）：
+  | 形态 | 中位墙钟 | 相对整幅静态 blur |
+  |---|---|---|
+  | 整幅**静态** `blur(24px)`（基准） | 38.07s | — |
+  | `gsap.set` **只设一次** filter | 38.29s | **+0.6%（噪声内，产物逐字节相同）** ⇒ 等价于静态 |
+  | 整幅 blur **被补间驱动**（8→40px） | 51.86s | **+36.2%** |
+  | **静态** filter、其 `transform` **被补间驱动** | 54.32s | **+42.7%（最贵的一档）** |
+- **滤镜重语料（技法颗粒，单颗 646 帧）**：**7.0×**（339.6s → 48.3s）。
+  ⚠️ 该数**只对该语料成立**，MUST NOT 外推成通用提速承诺。
+- **消费侧沉默不等于便宜**：`gtrk mg lint` 的四个成本项（`c-filter-animated` / `c-filter-static-fullbleed` /
+  **`c-filter-static-transformed`**（2026-08-06 增补，覆盖上面那条 +42.7% 的漏报面）/ `c-filter-indeterminate`）
+  是**形态提示**，**当期一律非致命、不拦铺轨**；没报**不代表**这颗渲得快——
+  真判据永远是**真渲染出片计时**。
+- **致命性的升级触发器（登记在此，免得日后凭印象改）**：把 `c-filter-animated` 提为**致命**
+  SHALL 另走一个独立 change，且 SHALL 同时满足两项前提——① 「滤镜重语料批量进渲染管线」那条路线**已立项**；
+  ② 提级前对现网生产语料**全量复扫且零命中**（复扫在生产颗粒上命中 > 0 即 MUST NOT 提级）。
+  触发一次评估的时机 = 上述路线立项 **或** 本节首次改版，以先到者为准。
+  **MUST NOT** 以「规范就该严」为由径直提级，也 **MUST NOT** 把致命性做成可现场翻转的运行期开关。
+
+### 根治登记
+
+- **① 这是降本规范、不是缺陷规避**：命中项的画面本身是对的，逐帧也正确，只是每帧贵。
+- **② 成本的根在渲染管线侧**：逐帧路径走**软件光栅**（无图形硬件加速），卷积按面积×半径吃 CPU。
+- **③ 根治状态 = 明确不立项（2026-07-30）**：改走图形硬件加速路径会破坏「逐帧确定性」与「产出端版本对齐」这两项前提
+  （异构机器还会破坏分片与单次的产物等价），渲染侧调研已把它列为**已排除项**。故本节以作者侧写法收敛，不等渲染侧。
+- **④ 根治后的处置预案**：若渲染侧将来换掉光栅路径并经真机复测确认成本塌陷，本节由 MUST NOT/SHOULD **降为提示**，
+  并保留「本节曾于 2026-07-30、本证据锚所载版本口径下作为降本规范所必需」的历史记录。

package/contracts/gsap-emit-v1.md

@@ -11,7 +11,7 @@
 
 > 颗粒可以用时间线回调（`onUpdate` 等）驱动画面；保证定帧时回调可达是渲染引擎侧的义务，不是颗粒作者的义务。本节是该主题的唯一口径来源。
 
-- **引擎侧（MUST）**：定帧时必须保证 GSAP 时间线回调可达，使用 `seek(t, false)`、`time(t)`、`progress(p)` 或 `totalTime(t)` 等等价方式，不能使用默认会抑制回调的裸 `seek(t)`。
+- **引擎侧（MUST）**：定帧时必须保证 GSAP 时间线回调可达，并定位到包含 repeat / yoyo 的完整时间轴。优先使用 `seek(t, false)` 或 `totalTime(t, false)`；`time(t)` / `progress(p)` 只适用于无 repeat 的根时间线，不能视为完整时间轴定位的通用等价替代。不能使用默认会抑制回调的裸 `seek(t)`。
 - **颗粒侧（MUST NOT）**：颗粒可以用 `onUpdate` / `onStart` / `onComplete` / `onRepeat` 写 DOM 或属性；不得运行时覆写 `tl.seek`，也不得替换 `window.__timelines[…]`。新颗粒不得添加 seek 垫片；已有垫片可在重渲复验后择期清理。
 - **幂等回调**：逐帧 scrub 会反复触发回调，回调必须从当前补间状态重算画面，不得累加计数、追加数组或执行一次性 DOM 插入。
 - **lint 哨兵**：`x-callback-driven`、`x-engine-api-override`、`x-raf-interval` 均为非致命提醒；它们用于提示引擎接口风险，不要求作者绕过契约自行添加垫片。