数据流、时钟与断链规则

这页回答：一个 iOS 系统事实如何经过 Perfowl 变成工作台、报告和可回放 Session 中的正式指标。

公共数学模型见指标计算模型与窗口语义；具体 metricID 当前 source、unit、sourceKey、definitionVersion 见 Registry 指标合同索引。

一、从系统事实到产品指标的八层链路

text

iOS System / Device Source
        ↓
Single Transport Owner
        ↓
Raw Adapter + RawEventEnvelope
        ↓
Normalized Domain Event
        ↓
Metric / Domain Projector
        ↓
Product Sample / MetricFrame
        ↓
Online Report + Immutable Session
        ↓
Swift Workbench / Replay / Export

层	责任	明确禁止
System / Device Source	提供 sysmontap、Graphics、Network、CoreProfile、ActivityTrace、Energy、Diagnostics 等系统事实	把未证明私有字段自动解释成物理量
Transport Owner	统一持有 DTX / Lockdown / RSD 生命周期，避免多 reader 抢同一连接	第二个并发 DTX socket reader
Raw Adapter	记录 sourceID、sequence、host monotonic、PID/generation、decode/identity 状态	在 Raw 层填 0、做 UI 结论或隐式 fallback
Normalized Domain Event	把复杂 Raw 变成有明确语义的 Frame、Startup、Network interval 等领域事件	丢弃 sourceEpoch / timestamp / quality 等重放所需事实
Metric / Domain Projector	执行 gauge 、rate、event interval、rolling window、quality gate	跨 generation / reconnect / display 偷算连续值
Product Sample / MetricFrame	以产品发布节拍输出当前值、quality 与 source 状态	把底层每条高频事件都强制映射成 UI refresh
Online Report / Session	增量聚合、统计、append-only 资产、manifest / SHA-256	停止时重新解释 Raw 得出另一套语义
Workbench / Replay / Export	展示、时间轴、报告、历史回放	UI 自己重新计算或把 null 格式化成 0 后写回事实层

Raw envelope 序号与来源本地序号

RawEventEnvelope.sequence 是 Session 内的全局 Raw 顺序号；rawPayload.adapterSequence 保留适配器来源本地的编号。两者回答不同问题：全局序号用于跨来源排列、封存 Raw 逐点定位和绑定同一条 Raw 的 receipt；适配器序号用于来源内部顺序与诊断。不能用 adapterSequence 代替 lastRawSequence 等 Raw receipt 字段，也不能因某个来源序号重启就把 Session 全局顺序误判为回退。

实时高频路径先完成有界 ingress 容量准入，再预留同一个 Session 全局编号。实时 projector 只接收这个整数编号作为 receipt identity，原事件与 payload 不复制；单一 writer 按 FIFO 将原事件与预留号落 Raw。未消费的预留会阻止 completed finalize，因此失败尾项不能被重新编号或隐藏。已有历史 Session 按其原始 envelope 与算法版本解释，不回写旧数据。

这项实现/软件合同于2026-10-22完成E2复核；完整Sidecar、Jitter专项及性能配对证据见Raw序号修复记录。它证明受控软件链路对齐，不证明真机来源精度或指标五轮通过。

二、为什么需要 Normalized Domain Event

不是所有 source 都适合直接变成 metric。

例如：

text

CoreProfile / ActivityTrace Raw
        ↓
Frame / Launch domain event
        ↓
FrameTime / Startup Total / Phase metrics

以及：

text

Networking callback
        ↓
normalized interval event
        ↓
Send / Recv rate

Domain Event 层的价值是把“协议格式”与“产品指标公式”分开。底层 source 可以迁移，只要新的 domain event 合同保持语义清晰，上层报告和体验指标不应该重新理解二进制协议。

三、四类时间概念

时间概念	用途	不能做什么
Host Monotonic `hostReceiveMonotonicNs`	Session elapsed、host 接收延迟、publisher / rolling window 推进	不能冒充设备事件真正发生时刻
Source-native Timestamp	NetworkStatistics 等服务自己的 interval / Cocoa timestamp	只能与同 source、同 clock domain 的 timestamp 相减
Device Mach / Event Clock	Startup span、Frame presentation 等设备高精度事件	必须使用设备动态 timebase；不能硬编码某台设备 numer/denom
Product Timeline	工作台与报告统一横轴	是投影坐标，不反过来生成 source event timestamp

核心原则：任何差值都先确认两个端点属于同一个 clock domain。

text

Device Mach - Device Mach      ✓
Host Monotonic - Host Monotonic ✓
同源 Cocoa TS - 同源 Cocoa TS   ✓

Device Mach - Host Receive       ✗
不同 source clock 直接相减        ✗

四、Mach timebase 的规则

对 Mach ticks，应先对 tick 差使用动态 numer / denom 做整数换算：

text

durationNs = (endTicks - startTicks) × numer / denom

不要：

text

convert(endTicks) - convert(startTicks)

也不要写死 POC 某台设备的 125 / 3。timebase 属于设备/source 运行时事实。

五、Source Cadence、Publisher Cadence、Report Cadence

Perfowl 明确解耦三个节拍：

text

Source Cadence
设备原始事件到达速度
        ↓
Processing Cadence
每条事件/窗口如何计算
        ↓
Publisher Cadence
MetricFrame / UI snapshot 多久发布一次
        ↓
Report Cadence
在线累计和最终 Session 统计

例如 Display FrameLifetime 可以高频到达，但工作台没有必要为每一帧重绘。反过来，降低 Publisher 频率也不会减少已经从设备传上来的原始流量；源带宽优化必须发生在 source/config/filter 层。

这条原则也是此前 CoreProfile FrameTime 高吞吐问题与 ActivityTrace 低带宽替代源研究中最重要的架构经验之一。

六、断链规则：什么时候必须重新 warmup

依赖前值或窗口的算法必须跟踪连续性。以下边界默认触发状态清理或重新建立 anchor：

sourceEpoch 变化；
reconnectGeneration 变化；
targetGeneration / PID identity 变化；
target 前后台转换；
displayID 变化；
cumulative counter reset / wrap；
source timestamp 类型或 clock domain 改变；
schema / source role 切换。

典型例子

text

旧 PID counter
+ 新 PID counter
→ 不能算一个连续 rate

text

foreground 最后一帧
+ background SpringBoard 帧
+ foreground 第一帧
→ 不能算目标 App 连续 FrameTime

text

ActivityTrace source restart 前最后一帧
+ restart 后第一帧
→ 第一帧只建 anchor，不发布跨 epoch FrameTime

七、Bridge 只能用于明确允许的目的

有时需要用 Host Monotonic 帮助推进产品窗口，但 bridge 必须严格限定用途。

例如目标 Display FPS 模型中：

text

lastPresentationDeviceTime
+ host elapsed since last receive
→ estimate display-window "now"

这个 bridge 可以帮助 trailing 1s 窗口在静止页面继续淘汰旧 frame，使 FPS 合理降到 0；但它不能用来构造新的 presentation timestamp，也不能生成 FrameTime。

这类规则必须在 Canonical 指标页明确写出，不能由 UI 自己猜。

八、Quality 与计算是同一条链路的一部分

公式能算出数值，不代表应该发布。

text

Raw Decoded
+ identity valid
+ scope valid
+ clock/window valid
+ continuity valid
+ runtime condition valid
→ Metric value

如果任何条件失败，应得到：

text

warmup
missing
not-foreground
not-applicable
counter-reset
discontinuity
unsupported

而不是：

text

0
last-known-value
synthetic fallback

完整质量语义见数据质量与 0 值判定准则。

九、不可变 Session 与确定性回放

Perfowl 的 Raw / Domain Event / Metric / Report 资产用于回答四类审计问题：

设备到底返回了什么；
identity、scope、clock 和 continuity 是否成立；
同一 Raw 在相同 definitionVersion 下能否确定性重算；
Live UI、最终报告和 Replay 是否消费同一语义。

metrics-manifest.json、Raw/Metric 哈希、frame/startup 资产与报告 seal 共同保证停止测试以后仍能复查，而不是只能相信当时屏幕上的曲线。

历史 Session 必须保留其原始 source / definitionVersion 语义。新的 source migration 不应该让旧 Session 被静默重新解释。

采集进程退出与会话隔离

进程退出不代表所有管道字节已经进入 Session。收尾先封闭新的读取准入，再等待已准入的读取完成，排空 stdout / stderr 并处理没有换行的最后一条记录，最后才发出终止事件。迟到的旧进程或旧管道回调不得结束新会话；同一监督对象复用时，解析缓冲与诊断缓冲必须按新会话重新初始化。

这些检查保护消息顺序、末行字节和会话归属，不产生设备没有提供的采样值。成功退出但缺少 stopped / seal 时仍保留完整性缺口，不补造结束记录。主机管道完整也不等于设备来源实时、每秒有值或数值已经独立校准。当前修复为 E2 自动化证据，54项非启动独立可信与固定五轮100%门仍待真机验证。本批来源

十、当前与迁移中的 source 要分开记录

知识库始终同时区分：

text

Current Registry Fact
vs
Target Architecture

例如 Display Performance 的 FPS / FrameTime 已经完整切源到 ActivityTrace FrameLifetime（Registry / CapturePlan / Report / UI 均已指向 activitytrace-framelifetime，E2 闭环完成），这是当前 Registry Fact；但这不等于所有系统、所有产品场景都已完成 E4 真机长稳验证——具体哪些门禁仍开放，以 Registry 指标合同索引与 Display Performance 总览顶部的当前实现状态为准，不要把某个 iOS 版本的短时 POC 结果外推为全部场景已经生产可用。

同样，旧 source 在退出新 Session 主采集后，也可能继续保留为 historical replay / compare reader；这属于兼容能力，不等于它仍拥有 production source ownership。

十一、公式和数据流变更治理

以下变化都需要同步审阅 Canonical 合同：

source ownership 改变；
normalized event schema 改变；
scope / unit 改变；
window / percentile / freshness 改变；
discontinuity / reset 改变； -合法 0 / missing 语义改变；
report aggregate 改变。

优先阅读顺序：

text

指标计算模型与窗口语义
    ↓
本页：数据流、时钟与断链
    ↓
数据质量语义
    ↓
具体 Canonical 指标页
    ↓
Registry 指标合同索引

版本历史

版本	日期	变更
v4	2026-10-22	区分 Session-global Raw envelope sequence 与 source-local adapterSequence；记录 ingress 预留、writer FIFO 消费及未消费 finalize 拒绝语义，来源为 Jitter Raw 序号修复 E2 增量
v3	2026-10-05	补退出读取准入、末行排空与连续会话隔离；区分管道完整、设备来源连续与独立校准，未提升54项真机验收状态
v2	2026-09-17	从六层 Raw→Metric 模型升级为八层 source→domain event→projector→sample→report 模型；补 source/publisher/report cadence、clock domain、bridge、断链与历史回放规则
v1	2026-09-08	建立基础数据流、三类时钟、计算形态和哈希重算语义

数据流、时钟与断链规则 ​

一、从系统事实到产品指标的八层链路 ​

Raw envelope 序号与来源本地序号 ​

二、为什么需要 Normalized Domain Event ​

三、四类时间概念 ​

四、Mach timebase 的规则 ​

五、Source Cadence、Publisher Cadence、Report Cadence ​

六、断链规则：什么时候必须重新 warmup ​

典型例子 ​

七、Bridge 只能用于明确允许的目的 ​

八、Quality 与计算是同一条链路的一部分 ​

九、不可变 Session 与确定性回放 ​

采集进程退出与会话隔离 ​

十、当前与迁移中的 source 要分开记录 ​

十一、公式和数据流变更治理 ​

版本历史 ​

数据流、时钟与断链规则

一、从系统事实到产品指标的八层链路

Raw envelope 序号与来源本地序号

二、为什么需要 Normalized Domain Event

三、四类时间概念

四、Mach timebase 的规则

五、Source Cadence、Publisher Cadence、Report Cadence

六、断链规则：什么时候必须重新 warmup

典型例子

七、Bridge 只能用于明确允许的目的

八、Quality 与计算是同一条链路的一部分

九、不可变 Session 与确定性回放

采集进程退出与会话隔离

十、当前与迁移中的 source 要分开记录

十一、公式和数据流变更治理

版本历史