Session 回放与时间轴

Perfowl 的 Session 是追加写入的事实流。时间轴是从事实流派生出的回放坐标，供指标曲线、截图、标注、窗口筛选和导出共享；它不会覆盖或重新排列原始事件。

适用范围

• 输入：NormalizedPerformanceEvent 的 hostReceiveMonotonicNs、wallTimestamp 与原始追加序号 ordinal。
• 输出：每个事件的 elapsedSeconds、点质量、Session 时间轴质量和可选持续时长。
• 当前阶段：P4 基础能力，E2 构建与测试证据；未代表真实设备截图或逐帧回放已经闭环。

坐标计算

首选：Host monotonic clock

当 Session 中每个事件都有大于 0 的 Host monotonic 接收时间时，取首事件作为锚点：

anchorNs = first.hostReceiveMonotonicNs
elapsedSeconds = (event.hostReceiveMonotonicNs - anchorNs) / 1_000_000_000

monotonic 值小于锚点的事件不产生负时间；该事件标记为 out-of-order，时间轴质量降级为 degraded。正常单调事件点标记为 valid。

兼容旧归档：wall clock fallback

只要 Session 中有任一事件的 monotonic 字段为 0，就对整个 Session 统一使用 wall clock，避免在一条时间轴中混合两种时钟：

wallAnchor = first.wallTimestamp
elapsedSeconds = max(0, event.wallTimestamp - wallAnchor)

该坐标可用于回放但不是单调时钟真值，所有点标记为 estimated，时间轴质量为 estimated。Date 差值非有限时保持空值。

空值与持续时长

• 没有事件：时间轴质量为 missing，点列表为空，持续时长为空。
• 无法计算坐标：elapsedSeconds = null，保留事件和质量原因，不写入 0。
• durationSeconds 是可用 elapsed 坐标的最大值，不把缺失点或 wall clock 之前的负差值算入时长。

回放排序与窗口

playbackPoints 是派生排序，不改变 points 的 raw 追加顺序：

1. 有 elapsed 坐标的点按 elapsedSeconds 升序；
2. elapsed 相同按原始 ordinal 升序，保证稳定回放；
3. 坐标缺失的点排在有坐标点之后，并仍按 ordinal 保序。

窗口查询使用播放坐标的闭区间：

points(in: start...end)

只返回 elapsedSeconds 存在且落在 [start, end] 内的点；缺失坐标不会被误纳入窗口。

质量语义

质量	含义	展示建议
valid	monotonic 坐标可用且事件顺序单调	正常回放
estimated	使用 wall clock 兼容坐标	展示“估算时间轴”标识
out-of-order	单点 monotonic 早于前一事件或锚点	保留点，标记异常
degraded	时间轴存在乱序点，但仍有可回放坐标	允许复查，报告提示降级
missing	Session 为空或没有任何可用坐标	展示空态与原因

这些状态与指标自身的 warmup、missing、counter-reset、suspect-static 等质量语义正交：时间轴可用不代表某条指标一定有值，指标有值也不改变时间轴质量。

版本与证据

项	值
算法版本	session-timeline.v1
实现	SessionTimelineBuilder
证据	E2：Swift 49/49，通过单调、乱序、fallback、窗口和空 Session 测试
真机状态	尚未完成 E4 截图 / 逐帧源闭环

后续演进

• Session Store 建立持久化回放索引，导出原始时钟、锚点、算法版本和时间轴质量。
• 截图事件、用户标注和 Note 使用同一 elapsed 坐标，避免按墙上时间二次猜测。
• 接入 DVT Graphics / xctrace 逐帧记录后，复用此坐标层挂载 FrameTime、Jank 候选和报告游标；候选值继续携带来源与证据等级。

版本历史

版本	日期	变更
v1	2026-09-04	发布 Session 回放时间轴的时钟选择、公式、排序和质量语义

来源批次：P4 Session Review 时间轴基础。