refactor(cmcd): vendor @svta/cml-cmcd, replace custom encoder + state machine

[littlespex]

Summary

Replaces shaka's custom CMCD wire-format encoding and state machine with a vendored Closure port of @svta/cml-cmcd (CML) under third_party/cml-cmcd/. Implementation in three sequential phases off feat/cmcd-cml-refactor:

• Phase 1 (Tasks 1.1-1.13) vendors the port and routes shaka's encoders through it. Three intentional wire-format changes (nor URL relativization, 'ld'/'lh' dropped, V2 SFV-conformant encoding).
• Phase 2 (Tasks 2.1-2.5) dedupes shaka's internal enums and key arrays in favor of cml.cmcd.* equivalents. Pure dedupe; no behavior change.
• Phase 3 (Tasks 3.1-3.15) rewrites lib/util/cmcd_manager.js (1580 → ~700 LoC) as a thin adapter around cml.cmcd.CmcdReporter. Deletes the state machine, sequence-number tracking, event timing, and mode-selection logic. Ships experimental v2 config renames (targets→eventTargets, per-target timeInterval→interval) and adds public EventType / PlayerState re-exports. Three additional wire-format alignments inherited from CML.

Phases 1 + 2 are behavior-preserving for shaka's public API, modulo documented intentional wire-format changes that align shaka with CTA-5004 / CTA-5004-B and CML's spec-conformant output. Phase 3 is the load-bearing behavioral change — the manager's external surface stays compatible, but the internal state machine, sequence-number scope, and event-mode dispatch path all flow through CML's reporter.

What's vendored

third_party/cml-cmcd/ mirrors the CML repo's libs/cmcd/src/ plus two shim files (cml_utils.js, cml_sfv.js), pinned at v2.3.0 / commit 22390e35dfbbe1e53d15648d3aace99cdf71f9dd**.

When shaka migrates to TypeScript (#8262), the vendored directory deletes and each goog.require('cml.cmcd.X') becomes import { X } from '@svta/cml-cmcd' — no other code changes.

Architectural decisions in the port

These are judgment calls during sub-phase B+C; please weigh in:

1. setInterval whitelisted in build/conformance.textproto for third_party/cml-cmcd/cmcd_reporter.js. The reporter calls setInterval directly for periodic time-interval event reporting. Alternatives considered: (a) patching the vendored reporter to use shaka.util.Timer (breaks verbatim parity, complicates per-bump diff workflow), (b) filing a CML upstream PR for injectable-timer support (delays Phase 1). Whitelist is pragmatic but means Phase 3 tests can't inject a fake timer — will need jasmine.clock() for interval testing.
2. fetch whitelisted in build/conformance.textproto for third_party/cml-cmcd/cml_utils.js. Used by cml.cmcd.defaultRequester — dead code at runtime because the shaka adapter always supplies a custom requester via NetworkingEngine. Closure ADVANCED is expected to strip the dead path; the conformance check runs first.
3. defaultRequester relocated from CmcdReporter.ts module scope into cml_utils.js as cml.cmcd.defaultRequester. Done to centralize the fetch whitelist scope to a single file. Per-bump CML diff workflow needs to know defaultRequester lives here, not in the reporter — otherwise CML 2.4.0+ bumps will look like the function vanished.

Wire-format changes (intentional)

Three changes; all align shaka with CTA-5004-B and CML's spec-conformant output. Test assertions updated to match.

1. nor URLs become root-relative + V2 inner-list format.

• V1: nor="next-seg.m4v" (path-relative against request URL).
• V2: nor=("next-seg.m4v") (RFC 8941 inner-list, root-relative against request origin per CTA-5004-B § 4.1).

cmcd_manager.js no longer pre-relativizes data.nor; CML's nor formatter relativizes against options.baseUrl (request URL's origin). For event-mode reports sent to a different-origin collector, nor stays absolute.

2. 'ld' and 'lh' StreamingFormat values dropped.

CTA-5004 / CTA-5004-B define only 'd' (DASH), 'h' (HLS), 's' (Smooth), 'o' (Other). 'ld' and 'lh' were from an old unreleased CMCD draft and are non-spec. Wire change: low-latency DASH content now emits sf=d; low-latency HLS now emits sf=h. setLowLatency() no longer mutates sf_; the LL flag is preserved for any external readers but has no effect on the encoded sf value.

3. V2 SFV-conformant encoding.

CML uses RFC 8941 Structured Field Values for V2 output; old shaka used a JSON-stringify-shaped quoting rule. Concrete differences:

• Token vs string formatting for e (event type) and sta (player state) values. Old: e="ps", sta="s". New: e=ps, sta=s. Per CTA-5004-B these values are spec-defined single-character tokens; SFV tokens don't take quotes.
• v=2 always present in V2 output. Per CTA-5004-B § 4.1, V2 output MUST include v. Old shaka emitted v only when explicitly present in input data. CML's prepareCmcdData enforces this, even when the user filters v out via includeKeys.
• ts no longer in request-mode output. Per CTA-5004-B ts is event-mode only. Old shaka emitted ts=<timestamp> in request-mode CMCD; CML's request-mode filter correctly drops it. (Event-mode and response-received reports continue to include ts.)

Behavior preserved otherwise

The state machine, sequence numbers (cmcdSequenceNumbers_ per-target counters), event timing, request/response routing, and the public shaka.util.CmcdManager API are unchanged. The setLowLatency, setMediaElement, configure, reset, applyRequestData, applyResponseData, appendSrcData, appendTextTrackData entry points retain their existing signatures and semantics. Phase 2 dedupes constants/enums; Phase 3 rewrites the state machine as a thin adapter around CmcdReporter and is the load-bearing behavioral change.

Implementation summary

shaka.util.CmcdManager static encoders now delegate:

• serialize(data, options) → cml.cmcd.encodeCmcd(data, options).
• toQuery(data, options) → cml.cmcd.encodeCmcd(data, options) (preserves shaka's "raw value, no CMCD= prefix" contract — CML's toCmcdQuery returns the prefixed form, which would break callers).
• toHeaders(data, options) → cml.cmcd.prepareCmcdData(data, options) once on the full input, then bucketed into shaka's existing 4-shard headerMap, then cml.cmcd.encodePreparedCmcd per shard. Calling the high-level encodeCmcd per shard would re-run prepareCmcdData and re-add v=2 to every non-empty shard.
• appendQueryToUri(uri, query) retained as a goog.Uri-based adapter — CML's appendCmcdQuery(url, cmcd, options) takes a data object, not a pre-encoded query string, so direct delegation isn't possible. Phase 3 deletes call sites entirely.
• urlToRelativePath deleted; the helper and its 9 unit tests are gone.

A new private getEncodeOptions_(uri, version, reportingMode) static helper builds cml.cmcd.CmcdEncodeOptions objects at the four CMCD-encoding call sites: appendSrcData, appendTextTrackData, sendCmcdRequest_ (event/response path), applyCmcdDataToRequest_ (request path). It threads this.config_.version and the reporting mode (CMCD_REQUEST_MODE for request paths, CMCD_EVENT_MODE for sendCmcdRequest_).

Verification (all three phases)

• python3 build/check.py --force exits 0 (lint, conformance, types, spelling).
• python3 build/all.py --force exits 0 (full bundle build: dash/hls/compiled/ui/experimental, debug + release).
• python3 build/test.py --filter Cmcd — 57 / 57 pass (Phase 3 deletes ~125 wire-format tests now in CML, adds adapter glue + smoke).
• python3 build/test.py --quick — 2927 / 2927 pass (no regressions outside CMCD; 4 environmental skips on this branch are unrelated to this work).
• Demo smoke test on bbb-dark-truths/dash.mpd — V1+query, V2+query, V2+headers (with unload→configure({useHeaders: true})→load cycle) all emit correct CMCD output. Sequence numbers 0-based, reset on sid change. v=2 only in CMCD-Session shard. Public re-exports (EventType, PlayerState, StreamingFormat) all readable at runtime from the compiled bundle. Zero CMCD-related console errors.