@video-lab/telemetry 3.0.1 → 4.0.0

package/README.md

@@ -1,8 +1,8 @@
 # @video-lab/telemetry
 
-宿主侧的播放器会话遥测核心。它只依赖
-[`@video-lab/protocol`](https://www.npmjs.com/package/@video-lab/protocol)，不发送 HTTP，
-不依赖 Sentry、React、Vue 或播放器内核。
+宿主应用的播放器会话遥测核心。它把五种接入方式交付的 `PlayerEvent` 归一为安全、可关联的 record，并在会话结束时生成 QoE summary。它只依赖 [`@video-lab/protocol`](https://www.npmjs.com/package/@video-lab/protocol)，不依赖播放器内核、React、Vue、Sentry 或 HTTP 客户端。
+
+它解决“播放器发生了什么、用户体验如何、是否恢复、发生在哪个宿主版本”的本地事实归一；它不解决网络上传、鉴权、采样、队列、重试或告警平台初始化。这些仍由宿主应用的传输层负责。
 
 ## 安装
 
@@ -10,17 +10,39 @@
 pnpm add @video-lab/telemetry
 ```
 
-业务应用通常将 `onRecord` 和 `onSummary` 接到已有的传输层；本包不负责网络请求或供应商 SDK 初始化。
+## 上报范围：四类事实，一层共同归因
+
+| 维度 | 回答的问题 | 包输出的事实 |
+| --- | --- | --- |
+| Error | 什么失败了、能否重试？ | 受控 `error` 事件、错误码、脱敏播放上下文；summary 的 `qoe.errors`。当前是 **19 个 `E_*` 错误码**。 |
+| QoE | 用户是否顺畅观看？ | 首帧、播放期卡顿、质量切换、换源、内核/音频/缓冲健康、PC 帧冻结，以及对应的 `unknown` coverage。 |
+| Behavior | 用户或宿主做了什么？ | SDK 控件产生的 `useraction` 原始事件；宿主显式写入的受限 `intent`。 |
+| Recovery | 自动恢复有没有真正恢复观看？ | `recovery` 生命周期、尝试/终态和“播放且位置推进”的恢复证据。 |
+| 共同归因 | 发生在哪里、数据是否可信？ | `application`、脱敏 `PlaybackContext`、`sessionId`、`eventId`、`sequence`、delivery 证据与 `completeness`。 |
+
+另有 **3 个 `W_*` 警告码**。错误码与警告码的完整定义、分类和可重试性以仓库的 `docs/protocol/errors.md` 和 `@video-lab/protocol` 的 `ERROR_META` 为准；不要自行拼错误文案或新增 code。
+
+### QoE 的具体行为
 
-## 用法
+`TelemetrySessionSummary.qoe` 覆盖：
 
-提供安全的原始事件记录、QoE 会话摘要和受限业务 intent：
+- `firstFrameMs`：首帧可见耗时；
+- `playbackStalls`：只累计 `kind='playback'` 的已结束卡顿，不把首播或 seek 等待混入；
+- `errors`：错误次数和有限错误码集合；
+- `qualityChanges`：自动与手动清晰度切换次数；
+- `sourceSwitches`：授权换源的尝试、成功/失败/取消、热切/重建和耗时；
+- `recovery`：恢复轮次、策略、终态和不完整/溢出事实；
+- `health.kernel`、`health.audio`、`health.buffer`、`health.frameFreezes`：内核、音频、缓冲和帧冻结健康信号。
+
+某个平台没有量具时，值是 `{ status: 'unknown' }`，不是 `0`。例如帧冻结目前是 PC-only；把缺失填成零会把覆盖率问题误判为体验良好。
+
+## 最小接入
+
+将唯一完整 `PlayerEvent` 事件流交给同一个会话。新版 SDK 事件的顶层 `delivery` 含生产端的 session、delivery ID、时间和 sequence，可让接收端可靠排序、去重和识别迟到事件。
 
 <!-- doc-snippet-preamble
 import type { PlayerEvent } from '@video-lab/protocol'
 declare const BUILD_SHA: string
-declare const event: PlayerEvent
-declare const deliveredEvent: import('@video-lab/protocol').DeliveredPlayerEvent
 declare function queueForDelivery(input: unknown): void
 declare function queueSessionSummary(input: unknown): void
 -->
@@ -29,6 +51,7 @@ declare function queueSessionSummary(input: unknown): void
 import { createTelemetrySession } from '@video-lab/telemetry'
 
 const telemetry = createTelemetrySession({
+  // release 是宿主应用版本，不是 telemetry 包或播放器包版本。
   application: { name: 'web-console', release: BUILD_SHA },
   sink: {
     onRecord: queueForDelivery,
@@ -36,56 +59,152 @@ const telemetry = createTelemetrySession({
   },
 })
 
-// 新 delivered 出口可直接绑定，保留 producer 时间、顺序与稳定投递 ID。
-telemetry.recordDelivered(deliveredEvent)
-// 旧 raw onPlayerEvent / player-event / embed.onAny 仍可调用 record(event)。
-telemetry.record(event)
+// React / Vue / 静态 iframe 统一使用完整事件出口。
+function onPlayerEvent(event: PlayerEvent): void {
+  telemetry.record(event)
+}
+
+// 业务自定义 UI、快捷键或 API 调用必须在发生处显式记录意图。
 telemetry.recordIntent({ type: 'retry', origin: 'user' })
-telemetry.finish({ reason: 'page_unload' })
+
+// 页面退出时才收口本会话，不要在创建 telemetry 后立即 finish。
+window.addEventListener('pagehide', () => {
+  telemetry.finish({ reason: 'page_unload' })
+}, { once: true })
 ```
 
-## 数据与隐私
+五种接入面的完整入口分别是 React 的 `onPlayerEvent`、Vue 的 `@player-event`，以及静态 iframe 的 `embed.onAny()`。旧 iframe 事件若无 `delivery`，`record()` 会如实标注去重不可验证。不要只监听 `onStalled` 等单项 UI 回调来拼会话。
+组件级播放器还应在 React effect cleanup 或 Vue `onScopeDispose()` 中以 `reason: 'destroyed'`
+收口；静态 iframe 同时退订监听器并销毁控制器。
+
+## 宿主需要准备什么
 
-每条 record 有 `eventId`、本地递增 `sequence`、时间、应用版本和最近的脱敏播放上下文。`recordDelivered()` 产生的 record 还带 `producerDelivery`（producer session、delivery id、源端时间与 producer sequence），供 sink 排序、去重与识别迟到事件。`error.payload.cause`
-会被移除；不会输出 URL query、签名、cookie、user ID 或业务 tags。
+`application.name` 是稳定的宿主名称；`application.release` 是宿主构建/发布版本，未提供时本包不会猜测。这样上报系统可以按“哪个业务应用的哪个版本”分组。
 
-## 会话行为
+播放器包版本、iframe artifact 版本、业务意图、用户/内容关联等不属于 `TelemetryApplication`。需要它们时，在宿主传输封装中添加，而不要伪造成 SDK 字段或反向塞进播放器配置：
+
+<!-- doc-snippet-preamble
+declare const packageRelease: string
+declare const iframeArtifactVersion: string | undefined
+-->
 
-优先使用 `recordDelivered(deliveredEvent)`；它以 producer session 与 delivery id 去重，并在 `producerDelivery` 中保留完整生产端证据。raw `record()` 保持既有形状，不伪造该证据。
-若宿主的传输层另有稳定 delivery id，也可传入 `telemetry.record(event, { deliveryId })` 来安全地去重重试。
-没有该 id 时，相同 payload 仍可能是合法的不同媒体事件，本包不会猜测并丢弃它。
+```ts
+import type { TelemetryRecord, TelemetrySessionSummary } from '@video-lab/telemetry'
+
+type HostTelemetryEnvelope = {
+  receivedAtMs: number
+  player: {
+    packageRelease: string
+    iframeArtifactRelease?: string
+  }
+  payload:
+    | { kind: 'record'; value: TelemetryRecord }
+    | { kind: 'summary'; value: TelemetrySessionSummary }
+}
+
+function wrapRecord(record: TelemetryRecord): HostTelemetryEnvelope {
+  return {
+    receivedAtMs: Date.now(),
+    player: { packageRelease, iframeArtifactRelease: iframeArtifactVersion },
+    payload: { kind: 'record', value: record },
+  }
+}
+```
 
-`finish()` 是幂等的：同一会话重复调用会返回同一份 summary。新的 `contextchange.sessionId` 会自动以
-`source_changed` 收口旧会话，并开始新会话。`TelemetrySessionSummary.qoe` 中的每一项都是
-`{ status: 'observed', value }` 或 `{ status: 'unknown' }`；没有收到平台专属信号（例如 PC-only
-`framefreeze`）时绝不会伪造 `0`。
+接收端至少应保存下列字段：
 
-`summary.support` 是收到 `sourceroute` 后的实际选源事实；它与是否显示画面分开。`summary.startup` 只有
-`firstframe` 才是 `started`，构造前 `unsupported` 或首帧前不可重试错误才是 `failed`，可重试错误和缺失
-事件保持 `unknown`。计算启动成功率时，分母只能取 `started | failed`，必须单列 `unknown` coverage。
-换源时，新 session 的 route 会等同 sessionId 的 `contextchange` 再归属，不能覆盖旧会话；未形成新 context
-的尝试仍会作为原始 record 送给 sink。
+| 字段 | 来源 | 用途 |
+| --- | --- | --- |
+| `application.name` / `application.release` | 创建 session 时由宿主提供 | 业务应用和宿主版本分桶。 |
+| `eventId`、`occurredAtMs`、`sequence` | telemetry record | 幂等、排序、排查迟到事件。 |
+| `producerDelivery` | `record(event)` 读取 `event.delivery` | iframe 跨重连时的稳定去重证据；旧事件没有时不能臆造。 |
+| `context.sessionId`、kernel、媒体类型、脱敏 origin/path | SDK 实际上下文 | 会话、内核、内容路径归因。 |
+| `event` / `intent` | player record | 原始播放器事实或受限业务动作。 |
+| `qoe`、`support`、`startup`、`completeness` | session summary | QoE 聚合、能力 coverage 与数据可信度判断。 |
+| 外层 `player.packageRelease` / `iframeArtifactRelease` | 宿主传输封装 | 播放器、iframe 版本的发布回归分析。 |
 
-## 边界
+不要把 URL query/hash、签名、token、cookie、`userId`、任意业务 tags、原始 `error.cause` 或内核自由文本放进 record。包已经移除一部分敏感信息；宿主出口仍要按自己的隐私规范做二次控制。
 
-`recordIntent()` 只接受固定的 `play`、`pause`、`seek`、`retry`、`source_change`、`exit` 和
-`user` / `api` origin。任意额外字段不会进入 record。sink 的异常被隔离，不会中断播放器；摘要的
-`completeness` 会报告 context、delivery-id 或 sink 证据缺口。
+## 输出结构与行为边界
 
-`onRecord` / `onSummary` 可以返回 `Promise<void>`。同步抛错和异步拒绝都计入产生该次投递的会话；换源后返回的失败不会污染新会话。若拒绝发生在 `finish()` 之后，已返回 summary 的 `completeness` 会更新，但不会再次调用 `onSummary`。因此摘要序列化后的副本不会自动补写，上传结果及重传仍由宿主传输层管理。
+`onRecord` 接收两种 `TelemetryRecord`：
 
-本包不是网络上报客户端。若使用 Sentry，请在业务项目中按自己的已初始化 client 实现 sink，
-不要把 `@sentry/*` 带进本包。跨框架映射规则与完整接入示例请向项目维护团队获取。
+| `kind` | 结构 | 何时产生 |
+| --- | --- | --- |
+| `player_event` | 公共基字段 + 安全 `PlayerEvent`；有生产端证据时包含 `producerDelivery` | 每一个通过校验的原始播放器事件。 |
+| `intent` | 公共基字段 + `{ type, origin }` | 宿主调用 `recordIntent()`。 |
 
-MIT
+公共基字段为 `eventId`、`schemaVersion: '2.0'`、`occurredAtMs`、递增 `sequence`、`application`、可选 `context`、`delivery: 'stable' | 'generated'` 和 `contextStatus: 'observed' | 'unattributed'`。
 
+`onSummary` 接收一份 `TelemetrySessionSummary`：`support` 是实际选源事实，`startup` 只有首帧才为 `started`；不可重试首帧前错误或构造前不支持才为 `failed`，其余未知情况保持 `unknown`。`completeness` 会表明 `deduplication_unknown`、`context_unattributed`、`sink_failure`、未闭合卡顿/换源、恢复不完整、本地溢出或非法事件等缺口。接收端不能把 `partial` summary 当成完整 QoE 样本。
 
-### schemaVersion 2.0
+行为观测分两部分：SDK 内置控件的 `useraction` 已在完整 `PlayerEvent` 中；宿主自定义按钮、快捷键和 API 调用应只写 `recordIntent({ type, origin })`。允许的 type 是 `play`、`pause`、`seek`、`retry`、`source_change`、`exit`，origin 是 `user` 或 `api`；任意 tags、用户 ID 和自由 payload 都不会进入 telemetry。
 
-`record()` 接受未知输入并校验；非法事件返回 `null`，计入 `completeness.invalidEvents` 与 `invalid_event`，不会调用 sink。错误 message 投影为稳定 code，cause、内核 detail、兼容 UA/原文、字幕/清晰度标签和用户动作自由文本不进入自动外发记录。源 origin/path 沿用协议的脱敏事实；业务路径仍可能包含敏感段，宿主出口应按自身规则进一步省略。
+`recovery.recovered` 不是收到了单个 `playing` / `canplay` 就成立：它需要 `playing_position_advance` 验证。403/鉴权错误也不会自动变成“已恢复”；宿主刷新签名、换源或业务重试后，仍应以 recovery 生命周期的真实终态判断。
 
-`qoe.recovery` 除最近终态外包含 episodes、实际观测 attempts、automatic/manual、durationMs、unclosed、incomplete 和 overflowEvents。只有完整观测轮次进入 recovered/failed 分组；成功率按对应组 recovered/(recovered+failed) 计算，分母为零为 N/A。取消、晚订阅和未闭合不会伪造成功或失败。
+## 高频与网络安全：宿主必须做的事
 
-每会话最多保留 128 个恢复轮次、每轮 64 个动作标识、1024 个 delivery 缓存、128 条意图及 128 个 ready 轨道项；溢出在 `localOverflow` / `local_overflow` 中报告，去重无法证明时标记 unknown。error count 保留事件次数，codes 为有限错误码集合。未结束的 playback stall 标记 `unclosed_stall`，不把缺失时长当作零。
+`onRecord` 是**本地观察回调**，不是“一次回调发一次 HTTP”的授权。每个有效 `PlayerEvent` 都会调用它；`timeupdate` 常见约 4 次/秒，即单播放器约 240 次/分钟。包内的 128/1024 等上限是会话聚合和 delivery cache 的内存边界，**不是**网络批量、节流、采样或重试策略。
 
-参考 Sentry sink 把可恢复 error 作为诊断 breadcrumb，failed recovery 按 `(sessionId,recoveryId)` 去重为事故；不可恢复 error 直接上报。使用 telemetry 作为调用边界，以便记录 sink 失败；本包不发送 HTTP，也不保证服务器已经接收。
+推荐按优先级分流：
+
+| 优先级 | 数据 | 建议宿主处理 |
+| --- | --- | --- |
+| P0 | 不可重试 error、`recovery.failed` | 进入错误平台；可立即发送，但要去重、限并发和保留失败计数。 |
+| P1 | `finish()` summary、已结束卡顿、健康退化、换源终态 | 入有界队列，按批量或短周期发送到 QoE/数仓管道。 |
+| P2 | `timeupdate`、progress、一般播放事件、逐条 intent | 默认不逐条上网；只作本地聚合、抽样或按会话摘要消费。 |
+
+下面是 sink 的接口样板。`HostTelemetryQueue` 必须由业务基础设施实现；它的 `enqueue()` 应是同步、快速且有界的，`flush()` 才进行网络工作。`onSummary` 主动 flush，确保会话结束尽快出队：
+
+```ts
+import type {
+  TelemetryRecord,
+  TelemetrySessionSummary,
+  TelemetrySink,
+} from '@video-lab/telemetry'
+
+type QueuedTelemetry =
+  | { kind: 'record'; value: TelemetryRecord }
+  | { kind: 'summary'; value: TelemetrySessionSummary }
+
+interface HostTelemetryQueue {
+  enqueue(item: QueuedTelemetry): void
+  flush(): Promise<void>
+}
+
+function createBatchedTelemetrySink(queue: HostTelemetryQueue): TelemetrySink {
+  return {
+    onRecord(record) {
+      queue.enqueue({ kind: 'record', value: record })
+    },
+    async onSummary(summary) {
+      queue.enqueue({ kind: 'summary', value: summary })
+      await queue.flush()
+    },
+  }
+}
+```
+
+实现这个队列时，至少明确并监控以下规则：
+
+- 最大队列、最大 batch、最大 in-flight 数；满载时按优先级丢弃 P2，不能静默挤掉 P0/P1；
+- 定时（例如 5–10 秒）或达到 batch 大小时 flush，页面卸载时尽力使用 `sendBeacon` / keepalive；
+- 有上限的指数退避和重试次数，失败后停止无限重放；
+- 上报 queue overflow、丢弃量、上传失败、重试次数和延迟；它们不是播放器 QoE；
+- 服务端按 `eventId` 或稳定 `producerDelivery.deliveryId` 做幂等，并限制单请求 body/事件数。
+
+sink 的同步异常和异步拒绝会被 telemetry 隔离，不会中断播放器；相应会话的 `completeness.sinkFailures` 会记录事实。但后台队列自己的失败发生在 sink 返回之后，必须由宿主队列自行监控，不能期待 telemetry 替你观测网络送达。
+
+## 会话生命周期与限制
+
+使用 `record(event)`；它从 `event.delivery` 读取 producer session 和 delivery ID 去重并保留生产端证据。若宿主从外部获得的事件没有该字段，仍可用 `record(event, { deliveryId })` 注入稳定 ID；没有该 ID 时，相同 payload 可能是两次真实媒体事实，本包不会猜测并丢弃它。
+
+`finish()` 幂等；同一会话重复调用返回同一份 summary。新 `contextchange.sessionId` 会以 `source_changed` 收口旧会话并开始新会话。每会话最多保留 128 个恢复轮次、每轮 64 个动作标识、1024 个 delivery cache、128 条 intent 和 128 个 ready 轨道项；溢出会如实写入 `localOverflow` / `local_overflow`，不会把信息缺失伪造为成功。
+
+## 与 Sentry 的关系
+
+本包不是 Sentry adapter，也不应把 `@sentry/*` 依赖带进它。业务应用可把不可重试 error 映射为 exception，`recovery.failed` 映射为去重后的 message，把已结束卡顿/健康退化作为低频 breadcrumb，并将 summary 发往 QoE 管道。不要把每个 `timeupdate` 写成 breadcrumb；它会很快冲掉真正的错误前线索。
+
+参考实现位于 `examples/team-video-vue/reporting/sentry-telemetry-sink.ts`；跨框架绑定方式见仓库的 `docs/guides/USER-GUIDE.md` 与 `docs/guides/PLAYER-OBSERVABILITY-QOE.md`。
+
+MIT

package/dist/index.cjs

@@ -108,6 +108,18 @@ function createAggregate() {
 		errorCodes: [],
 		qualityChangeCount: 0,
 		autoQualityChangeCount: 0,
+		sourceSwitchAttempts: 0,
+		sourceSwitchSucceeded: 0,
+		sourceSwitchFailed: 0,
+		sourceSwitchCancelled: 0,
+		sourceSwitchHotLoad: 0,
+		sourceSwitchRebuild: 0,
+		sourceSwitchElapsedMs: {
+			succeeded: 0,
+			failed: 0,
+			cancelled: 0
+		},
+		openSourceSwitches: /* @__PURE__ */ new Set(),
 		frameFreezeCount: 0,
 		frameFreezeDurationMs: 0,
 		intents: []
@@ -236,6 +248,7 @@ function createTelemetrySession(options) {
 	*/
 	let seenDeliveries = /* @__PURE__ */ new Map();
 	let pendingSourceRoute;
+	let pendingSourceSwitches = /* @__PURE__ */ new Set();
 	let aggregate = createAggregate();
 	let sequence = 0;
 	let completedSummary;
@@ -266,7 +279,7 @@ function createTelemetrySession(options) {
 	function emitRecord(record) {
 		deliver(aggregate, () => options.sink?.onRecord?.(record));
 	}
-	function recordEventFact(event) {
+	function recordEventFact(event, sourceSwitchScope) {
 		if (event.event === "firstframe") aggregate.firstFrameMs ??= event.payload.fvt;
 		if (event.event === "stalled" && event.payload.kind === "playback") {
 			aggregate.incompleteStall ||= event.payload.phase === "start" && aggregate.unclosedStall || event.payload.phase === "end" && event.payload.durationMs === void 0;
@@ -285,6 +298,32 @@ function createTelemetrySession(options) {
 			aggregate.qualityChangeCount += 1;
 			if (event.payload.auto) aggregate.autoQualityChangeCount += 1;
 		}
+		if (event.event === "sourceswitch") {
+			const key = `${sourceSwitchScope}:${event.payload.switchId}`;
+			if (event.payload.phase === "started") {
+				if (!aggregate.openSourceSwitches.has(key)) {
+					aggregate.openSourceSwitches.add(key);
+					aggregate.sourceSwitchAttempts += 1;
+				}
+				return;
+			}
+			if (!aggregate.openSourceSwitches.delete(key)) return;
+			if (event.payload.phase === "succeeded") {
+				aggregate.sourceSwitchSucceeded += 1;
+				aggregate.sourceSwitchElapsedMs.succeeded += event.payload.elapsedMs;
+				if (event.payload.strategy === "hot_load") aggregate.sourceSwitchHotLoad += 1;
+				else aggregate.sourceSwitchRebuild += 1;
+			}
+			if (event.payload.phase === "failed") {
+				aggregate.sourceSwitchFailed += 1;
+				aggregate.sourceSwitchElapsedMs.failed += event.payload.elapsedMs;
+			}
+			if (event.payload.phase === "cancelled") {
+				aggregate.sourceSwitchCancelled += 1;
+				aggregate.sourceSwitchElapsedMs.cancelled += event.payload.elapsedMs;
+			}
+			return;
+		}
 		if (event.event === "recovery") aggregate.recovery.record(event.payload);
 		if (event.event === "kernelhealth") aggregate.kernelHealth = {
 			degraded: event.payload.degraded,
@@ -311,6 +350,7 @@ function createTelemetrySession(options) {
 		if (recovery?.overflowEvents || aggregate.localOverflow) missing.push("local_overflow");
 		if (aggregate.invalidEvents) missing.push("invalid_event");
 		if (aggregate.unclosedStall || aggregate.incompleteStall) missing.push("unclosed_stall");
+		if (aggregate.openSourceSwitches.size > 0) missing.push("unclosed_source_switch");
 		const contextUnattributed = aggregate.unattributedRecord || !aggregate.currentContext;
 		if (aggregate.generatedDelivery) missing.push("deduplication_unknown");
 		if (contextUnattributed) missing.push("context_unattributed");
@@ -341,6 +381,15 @@ function createTelemetrySession(options) {
 					autoCount: aggregate.autoQualityChangeCount,
 					manualCount: aggregate.qualityChangeCount - aggregate.autoQualityChangeCount
 				}),
+				sourceSwitches: aggregate.sourceSwitchAttempts === 0 ? unknown() : observed({
+					attempts: aggregate.sourceSwitchAttempts,
+					succeeded: aggregate.sourceSwitchSucceeded,
+					failed: aggregate.sourceSwitchFailed,
+					cancelled: aggregate.sourceSwitchCancelled,
+					hotLoad: aggregate.sourceSwitchHotLoad,
+					rebuild: aggregate.sourceSwitchRebuild,
+					elapsedMs: aggregate.sourceSwitchElapsedMs
+				}),
 				recovery: recovery ? observed(recovery) : unknown(),
 				health: {
 					kernel: aggregate.kernelHealth ? observed(aggregate.kernelHealth) : unknown(),
@@ -382,16 +431,26 @@ function createTelemetrySession(options) {
 			}
 			const parsed = validation.data;
 			if (completedSummary) prepareForInput();
-			const deliveryId = metadata?.deliveryId;
-			const producerDelivery = metadata?.producerDelivery;
+			const producerDelivery = parsed.delivery ?? metadata?.producerDelivery;
+			const deliveryId = producerDelivery?.deliveryId ?? metadata?.deliveryId;
 			const identitySession = "sessionId" in parsed.payload ? parsed.payload.sessionId : aggregate.currentContext?.sessionId ?? aggregate.sourceRoute?.sessionId ?? "";
 			const deliveryKey = JSON.stringify(producerDelivery ? [producerDelivery.producerSessionId, producerDelivery.deliveryId] : [identitySession, deliveryId]);
 			if (deliveryId) {
 				const duplicate = seenDeliveries.get(deliveryKey);
 				if (duplicate) return duplicate;
 			}
-			if (parsed.event === "contextchange" && aggregate.currentContext && aggregate.currentContext.sessionId !== parsed.payload.sessionId && !completedSummary) finish("source_changed");
+			if (parsed.event === "contextchange" && aggregate.currentContext && aggregate.currentContext.sessionId !== parsed.payload.sessionId && !completedSummary) {
+				pendingSourceSwitches = new Set(aggregate.openSourceSwitches);
+				aggregate.sourceSwitchAttempts -= pendingSourceSwitches.size;
+				aggregate.openSourceSwitches.clear();
+				finish("source_changed");
+			}
 			prepareForInput();
+			if (pendingSourceSwitches.size > 0) {
+				aggregate.openSourceSwitches = pendingSourceSwitches;
+				aggregate.sourceSwitchAttempts += pendingSourceSwitches.size;
+				pendingSourceSwitches = /* @__PURE__ */ new Set();
+			}
 			const isPendingSourceRoute = parsed.event === "sourceroute" && !!aggregate.currentContext && aggregate.currentContext.sessionId !== parsed.payload.sessionId;
 			const currentSessionId = aggregate.currentContext?.sessionId ?? aggregate.sourceRoute?.sessionId;
 			const isForeignRecovery = parsed.event === "recovery" && currentSessionId !== void 0 && currentSessionId !== parsed.payload.sessionId;
@@ -423,7 +482,7 @@ function createTelemetrySession(options) {
 				aggregate.eventCount += 1;
 				aggregate.generatedDelivery ||= !deliveryId;
 				aggregate.unattributedRecord ||= record.contextStatus === "unattributed" && parsed.event !== "sourceroute";
-				recordEventFact(record.event);
+				recordEventFact(record.event, producerDelivery?.producerSessionId ?? "raw");
 			}
 			if (deliveryId) if (seenDeliveries.size < 1024) seenDeliveries.set(deliveryKey, record);
 			else {
@@ -433,18 +492,6 @@ function createTelemetrySession(options) {
 			emitRecord(record);
 			return record;
 		},
-		recordDelivered(event) {
-			return this.record(event.event, {
-				deliveryId: event.deliveryId,
-				occurredAtMs: event.occurredAtMs,
-				producerDelivery: {
-					producerSessionId: event.producerSessionId,
-					deliveryId: event.deliveryId,
-					occurredAtMs: event.occurredAtMs,
-					sequence: event.sequence
-				}
-			});
-		},
 		recordIntent(intent) {
 			prepareForInput();
 			const projectedIntent = projectIntent(intent);

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { DeliveredPlayerEvent, ErrorCode, PlaybackContext, PlayerEvent, RecoveryPayload, SourceRoutePayload } from "@video-lab/protocol";
+import { ErrorCode, PlaybackContext, PlayerEvent, RecoveryPayload, SourceRoutePayload } from "@video-lab/protocol";
 //#region src/recovery-summary.d.ts
 type Terminal = Extract<RecoveryPayload, {
   phase: 'recovered' | 'failed' | 'cancelled';
@@ -40,7 +40,7 @@ interface TelemetryRecordOptions {
   deliveryId?: string;
   /** 事件在播放器侧发生的时间；缺省时由会话时钟采样。 */
   occurredAtMs?: number;
-  /** `recordDelivered` 写入的生产端投递证据；raw `record` 默认不产生它。 */
+  /** 外部注入的生产端投递证据；SDK 事件优先读取 `event.delivery`。 */
   producerDelivery?: TelemetryProducerDelivery;
 }
 /** 可随 telemetry record 外发的生产端排序、去重与迟到识别证据。 */
@@ -70,7 +70,7 @@ interface TelemetryRecordBase {
 interface TelemetryPlayerRecord extends TelemetryRecordBase {
   kind: 'player_event';
   event: PlayerEvent;
-  /** 仅完整 delivered 流提供；raw `record` 保持既有输出形状。 */
+  /** 有生产端投递证据的事件提供；无证据事件省略。 */
   producerDelivery?: TelemetryProducerDelivery;
 }
 interface TelemetryIntentRecord extends TelemetryRecordBase {
@@ -128,6 +128,19 @@ interface TelemetrySessionSummary {
       autoCount: number;
       manualCount: number;
     }>;
+    sourceSwitches: TelemetryValue<{
+      attempts: number;
+      succeeded: number;
+      failed: number;
+      cancelled: number;
+      hotLoad: number;
+      rebuild: number;
+      elapsedMs: {
+        succeeded: number;
+        failed: number;
+        cancelled: number;
+      };
+    }>;
     recovery: TelemetryValue<TelemetryRecoverySummary>;
     health: {
       kernel: TelemetryValue<{
@@ -151,7 +164,7 @@ interface TelemetrySessionSummary {
   intents: TelemetryValue<readonly TelemetryIntent[]>;
   completeness: {
     status: 'complete' | 'partial';
-    missing: Array<'deduplication_unknown' | 'context_unattributed' | 'sink_failure' | 'unclosed_episode' | 'recovery_incomplete' | 'local_overflow' | 'invalid_event' | 'unclosed_stall'>;
+    missing: Array<'deduplication_unknown' | 'context_unattributed' | 'sink_failure' | 'unclosed_episode' | 'recovery_incomplete' | 'local_overflow' | 'invalid_event' | 'unclosed_stall' | 'unclosed_source_switch'>;
     deduplication: 'verified' | 'unknown';
     context: 'observed' | 'unattributed';
     sinkFailures: number;
@@ -172,8 +185,6 @@ interface CreateTelemetrySessionOptions {
 interface TelemetrySession {
   /** 把完整 PlayerEvent 归一成可重试、可排序的安全 record。 */
   record(event: unknown, options?: TelemetryRecordOptions): TelemetryPlayerRecord | null;
-  /** 直接消费五面同构的 producer delivery 证据。 */
-  recordDelivered(event: DeliveredPlayerEvent): TelemetryPlayerRecord | null;
   /** 记录有限、脱敏的宿主意图，不把任意业务数据带进遥测。 */
   recordIntent(intent: TelemetryIntent): TelemetryIntentRecord;
   /** 关闭当前播放会话；重复调用返回同一份 summary。 */

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { DeliveredPlayerEvent, ErrorCode, PlaybackContext, PlayerEvent, RecoveryPayload, SourceRoutePayload } from "@video-lab/protocol";
+import { ErrorCode, PlaybackContext, PlayerEvent, RecoveryPayload, SourceRoutePayload } from "@video-lab/protocol";
 //#region src/recovery-summary.d.ts
 type Terminal = Extract<RecoveryPayload, {
   phase: 'recovered' | 'failed' | 'cancelled';
@@ -40,7 +40,7 @@ interface TelemetryRecordOptions {
   deliveryId?: string;
   /** 事件在播放器侧发生的时间；缺省时由会话时钟采样。 */
   occurredAtMs?: number;
-  /** `recordDelivered` 写入的生产端投递证据；raw `record` 默认不产生它。 */
+  /** 外部注入的生产端投递证据；SDK 事件优先读取 `event.delivery`。 */
   producerDelivery?: TelemetryProducerDelivery;
 }
 /** 可随 telemetry record 外发的生产端排序、去重与迟到识别证据。 */
@@ -70,7 +70,7 @@ interface TelemetryRecordBase {
 interface TelemetryPlayerRecord extends TelemetryRecordBase {
   kind: 'player_event';
   event: PlayerEvent;
-  /** 仅完整 delivered 流提供；raw `record` 保持既有输出形状。 */
+  /** 有生产端投递证据的事件提供；无证据事件省略。 */
   producerDelivery?: TelemetryProducerDelivery;
 }
 interface TelemetryIntentRecord extends TelemetryRecordBase {
@@ -128,6 +128,19 @@ interface TelemetrySessionSummary {
       autoCount: number;
       manualCount: number;
     }>;
+    sourceSwitches: TelemetryValue<{
+      attempts: number;
+      succeeded: number;
+      failed: number;
+      cancelled: number;
+      hotLoad: number;
+      rebuild: number;
+      elapsedMs: {
+        succeeded: number;
+        failed: number;
+        cancelled: number;
+      };
+    }>;
     recovery: TelemetryValue<TelemetryRecoverySummary>;
     health: {
       kernel: TelemetryValue<{
@@ -151,7 +164,7 @@ interface TelemetrySessionSummary {
   intents: TelemetryValue<readonly TelemetryIntent[]>;
   completeness: {
     status: 'complete' | 'partial';
-    missing: Array<'deduplication_unknown' | 'context_unattributed' | 'sink_failure' | 'unclosed_episode' | 'recovery_incomplete' | 'local_overflow' | 'invalid_event' | 'unclosed_stall'>;
+    missing: Array<'deduplication_unknown' | 'context_unattributed' | 'sink_failure' | 'unclosed_episode' | 'recovery_incomplete' | 'local_overflow' | 'invalid_event' | 'unclosed_stall' | 'unclosed_source_switch'>;
     deduplication: 'verified' | 'unknown';
     context: 'observed' | 'unattributed';
     sinkFailures: number;
@@ -172,8 +185,6 @@ interface CreateTelemetrySessionOptions {
 interface TelemetrySession {
   /** 把完整 PlayerEvent 归一成可重试、可排序的安全 record。 */
   record(event: unknown, options?: TelemetryRecordOptions): TelemetryPlayerRecord | null;
-  /** 直接消费五面同构的 producer delivery 证据。 */
-  recordDelivered(event: DeliveredPlayerEvent): TelemetryPlayerRecord | null;
   /** 记录有限、脱敏的宿主意图，不把任意业务数据带进遥测。 */
   recordIntent(intent: TelemetryIntent): TelemetryIntentRecord;
   /** 关闭当前播放会话；重复调用返回同一份 summary。 */

package/dist/index.mjs

@@ -107,6 +107,18 @@ function createAggregate() {
 		errorCodes: [],
 		qualityChangeCount: 0,
 		autoQualityChangeCount: 0,
+		sourceSwitchAttempts: 0,
+		sourceSwitchSucceeded: 0,
+		sourceSwitchFailed: 0,
+		sourceSwitchCancelled: 0,
+		sourceSwitchHotLoad: 0,
+		sourceSwitchRebuild: 0,
+		sourceSwitchElapsedMs: {
+			succeeded: 0,
+			failed: 0,
+			cancelled: 0
+		},
+		openSourceSwitches: /* @__PURE__ */ new Set(),
 		frameFreezeCount: 0,
 		frameFreezeDurationMs: 0,
 		intents: []
@@ -235,6 +247,7 @@ function createTelemetrySession(options) {
 	*/
 	let seenDeliveries = /* @__PURE__ */ new Map();
 	let pendingSourceRoute;
+	let pendingSourceSwitches = /* @__PURE__ */ new Set();
 	let aggregate = createAggregate();
 	let sequence = 0;
 	let completedSummary;
@@ -265,7 +278,7 @@ function createTelemetrySession(options) {
 	function emitRecord(record) {
 		deliver(aggregate, () => options.sink?.onRecord?.(record));
 	}
-	function recordEventFact(event) {
+	function recordEventFact(event, sourceSwitchScope) {
 		if (event.event === "firstframe") aggregate.firstFrameMs ??= event.payload.fvt;
 		if (event.event === "stalled" && event.payload.kind === "playback") {
 			aggregate.incompleteStall ||= event.payload.phase === "start" && aggregate.unclosedStall || event.payload.phase === "end" && event.payload.durationMs === void 0;
@@ -284,6 +297,32 @@ function createTelemetrySession(options) {
 			aggregate.qualityChangeCount += 1;
 			if (event.payload.auto) aggregate.autoQualityChangeCount += 1;
 		}
+		if (event.event === "sourceswitch") {
+			const key = `${sourceSwitchScope}:${event.payload.switchId}`;
+			if (event.payload.phase === "started") {
+				if (!aggregate.openSourceSwitches.has(key)) {
+					aggregate.openSourceSwitches.add(key);
+					aggregate.sourceSwitchAttempts += 1;
+				}
+				return;
+			}
+			if (!aggregate.openSourceSwitches.delete(key)) return;
+			if (event.payload.phase === "succeeded") {
+				aggregate.sourceSwitchSucceeded += 1;
+				aggregate.sourceSwitchElapsedMs.succeeded += event.payload.elapsedMs;
+				if (event.payload.strategy === "hot_load") aggregate.sourceSwitchHotLoad += 1;
+				else aggregate.sourceSwitchRebuild += 1;
+			}
+			if (event.payload.phase === "failed") {
+				aggregate.sourceSwitchFailed += 1;
+				aggregate.sourceSwitchElapsedMs.failed += event.payload.elapsedMs;
+			}
+			if (event.payload.phase === "cancelled") {
+				aggregate.sourceSwitchCancelled += 1;
+				aggregate.sourceSwitchElapsedMs.cancelled += event.payload.elapsedMs;
+			}
+			return;
+		}
 		if (event.event === "recovery") aggregate.recovery.record(event.payload);
 		if (event.event === "kernelhealth") aggregate.kernelHealth = {
 			degraded: event.payload.degraded,
@@ -310,6 +349,7 @@ function createTelemetrySession(options) {
 		if (recovery?.overflowEvents || aggregate.localOverflow) missing.push("local_overflow");
 		if (aggregate.invalidEvents) missing.push("invalid_event");
 		if (aggregate.unclosedStall || aggregate.incompleteStall) missing.push("unclosed_stall");
+		if (aggregate.openSourceSwitches.size > 0) missing.push("unclosed_source_switch");
 		const contextUnattributed = aggregate.unattributedRecord || !aggregate.currentContext;
 		if (aggregate.generatedDelivery) missing.push("deduplication_unknown");
 		if (contextUnattributed) missing.push("context_unattributed");
@@ -340,6 +380,15 @@ function createTelemetrySession(options) {
 					autoCount: aggregate.autoQualityChangeCount,
 					manualCount: aggregate.qualityChangeCount - aggregate.autoQualityChangeCount
 				}),
+				sourceSwitches: aggregate.sourceSwitchAttempts === 0 ? unknown() : observed({
+					attempts: aggregate.sourceSwitchAttempts,
+					succeeded: aggregate.sourceSwitchSucceeded,
+					failed: aggregate.sourceSwitchFailed,
+					cancelled: aggregate.sourceSwitchCancelled,
+					hotLoad: aggregate.sourceSwitchHotLoad,
+					rebuild: aggregate.sourceSwitchRebuild,
+					elapsedMs: aggregate.sourceSwitchElapsedMs
+				}),
 				recovery: recovery ? observed(recovery) : unknown(),
 				health: {
 					kernel: aggregate.kernelHealth ? observed(aggregate.kernelHealth) : unknown(),
@@ -381,16 +430,26 @@ function createTelemetrySession(options) {
 			}
 			const parsed = validation.data;
 			if (completedSummary) prepareForInput();
-			const deliveryId = metadata?.deliveryId;
-			const producerDelivery = metadata?.producerDelivery;
+			const producerDelivery = parsed.delivery ?? metadata?.producerDelivery;
+			const deliveryId = producerDelivery?.deliveryId ?? metadata?.deliveryId;
 			const identitySession = "sessionId" in parsed.payload ? parsed.payload.sessionId : aggregate.currentContext?.sessionId ?? aggregate.sourceRoute?.sessionId ?? "";
 			const deliveryKey = JSON.stringify(producerDelivery ? [producerDelivery.producerSessionId, producerDelivery.deliveryId] : [identitySession, deliveryId]);
 			if (deliveryId) {
 				const duplicate = seenDeliveries.get(deliveryKey);
 				if (duplicate) return duplicate;
 			}
-			if (parsed.event === "contextchange" && aggregate.currentContext && aggregate.currentContext.sessionId !== parsed.payload.sessionId && !completedSummary) finish("source_changed");
+			if (parsed.event === "contextchange" && aggregate.currentContext && aggregate.currentContext.sessionId !== parsed.payload.sessionId && !completedSummary) {
+				pendingSourceSwitches = new Set(aggregate.openSourceSwitches);
+				aggregate.sourceSwitchAttempts -= pendingSourceSwitches.size;
+				aggregate.openSourceSwitches.clear();
+				finish("source_changed");
+			}
 			prepareForInput();
+			if (pendingSourceSwitches.size > 0) {
+				aggregate.openSourceSwitches = pendingSourceSwitches;
+				aggregate.sourceSwitchAttempts += pendingSourceSwitches.size;
+				pendingSourceSwitches = /* @__PURE__ */ new Set();
+			}
 			const isPendingSourceRoute = parsed.event === "sourceroute" && !!aggregate.currentContext && aggregate.currentContext.sessionId !== parsed.payload.sessionId;
 			const currentSessionId = aggregate.currentContext?.sessionId ?? aggregate.sourceRoute?.sessionId;
 			const isForeignRecovery = parsed.event === "recovery" && currentSessionId !== void 0 && currentSessionId !== parsed.payload.sessionId;
@@ -422,7 +481,7 @@ function createTelemetrySession(options) {
 				aggregate.eventCount += 1;
 				aggregate.generatedDelivery ||= !deliveryId;
 				aggregate.unattributedRecord ||= record.contextStatus === "unattributed" && parsed.event !== "sourceroute";
-				recordEventFact(record.event);
+				recordEventFact(record.event, producerDelivery?.producerSessionId ?? "raw");
 			}
 			if (deliveryId) if (seenDeliveries.size < 1024) seenDeliveries.set(deliveryKey, record);
 			else {
@@ -432,18 +491,6 @@ function createTelemetrySession(options) {
 			emitRecord(record);
 			return record;
 		},
-		recordDelivered(event) {
-			return this.record(event.event, {
-				deliveryId: event.deliveryId,
-				occurredAtMs: event.occurredAtMs,
-				producerDelivery: {
-					producerSessionId: event.producerSessionId,
-					deliveryId: event.deliveryId,
-					occurredAtMs: event.occurredAtMs,
-					sequence: event.sequence
-				}
-			});
-		},
 		recordIntent(intent) {
 			prepareForInput();
 			const projectedIntent = projectIntent(intent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@video-lab/telemetry",
-  "version": "3.0.1",
+  "version": "4.0.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -24,7 +24,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@video-lab/protocol": "3.0.1"
+    "@video-lab/protocol": "4.0.0"
   },
   "devDependencies": {
     "tsdown": "^0.22.9",