@svta/cml-cmcd 2.5.0 → 2.6.1

package/dist/index.js

@@ -522,6 +522,26 @@ function isValid(value) {
 	return value != null && value !== "" && value !== false;
 }
 
+//#endregion
+//#region src/toTokenString.ts
+/**
+* Resolve the text of a token value.
+*
+* A token may be a plain string, a registry `Symbol`, an `SfToken`, or an
+* `SfItem` that wraps one of those.
+*
+* @param value - The value to resolve.
+*
+* @returns The token text, or `undefined` when the value is not a token.
+*
+* @internal
+*/
+function toTokenString(value) {
+	if (value instanceof SfItem) return toTokenString(value.value);
+	if (typeof value === "string") return value;
+	if (typeof value === "symbol" || value instanceof SfToken) return symbolToStr(value);
+}
+
 //#endregion
 //#region src/prepareCmcdData.ts
 const filterMap = {
@@ -534,7 +554,8 @@ const filterMap = {
 function unwrapValue(value, ot) {
 	if (Array.isArray(value)) {
 		let item;
-		if (ot) item = value.find((item$1) => item$1.params?.ot === ot);
+		const otText = toTokenString(ot);
+		if (otText) item = value.find((item$1) => toTokenString(item$1.params?.ot) === otText);
 		if (!item) item = value[0];
 		return unwrapValue(item);
 	}
@@ -582,15 +603,15 @@ function prepareCmcdData(obj, options = {}) {
 	const version = options.version || obj["v"] || CMCD_V2;
 	const reportingMode = options.reportingMode || CMCD_REQUEST_MODE;
 	const data = version === 1 ? downConvertToV1(obj) : obj;
+	const eventType = toTokenString(data["e"]);
 	const keyFilter = version === 1 ? isCmcdV1Key : filterMap[reportingMode];
 	let keys = Object.keys(data).filter(keyFilter);
-	if (data["e"] && data["e"] !== CMCD_EVENT_RESPONSE_RECEIVED) keys = keys.filter((key) => !isCmcdResponseReceivedKey(key));
+	if (data["e"] && eventType !== CMCD_EVENT_RESPONSE_RECEIVED) keys = keys.filter((key) => !isCmcdResponseReceivedKey(key));
 	const filter = options.filter;
 	if (typeof filter === "function") keys = keys.filter(filter);
 	const isEventMode = reportingMode === CMCD_EVENT_MODE;
 	if (isEventMode) {
-		const eventType = data["e"];
-		if (!keys.includes("e") && eventType != null) keys.push("e");
+		if (!keys.includes("e") && data["e"] != null) keys.push("e");
 		if (!keys.includes("ts")) keys.push("ts");
 		if (!keys.includes("cen") && data["cen"] != null && eventType === CMCD_EVENT_CUSTOM_EVENT) keys.push("cen");
 		if (!keys.includes("ec") && data["ec"] != null && eventType === CMCD_EVENT_ERROR) keys.push("ec");
@@ -612,11 +633,14 @@ function prepareCmcdData(obj, options = {}) {
 		if (typeof formatter === "function") value = formatter(value, formatterOptions);
 		if (key === "v") if (version === 1) continue;
 		else value = version;
-		if (key === "pr" && value === 1 && !(isEventMode && data["e"] === CMCD_EVENT_PLAYBACK_RATE)) continue;
+		if (key === "pr" && value === 1 && !(isEventMode && eventType === CMCD_EVENT_PLAYBACK_RATE)) continue;
 		if (isEventMode && key === "ts" && !Number.isFinite(value)) value = Date.now();
-		const isBgFalseTransition = isEventMode && value === false && key === "bg" && data["e"] === CMCD_EVENT_BACKGROUNDED_MODE;
+		const isBgFalseTransition = isEventMode && value === false && key === "bg" && eventType === CMCD_EVENT_BACKGROUNDED_MODE;
 		if (!isValid(value) && !isBgFalseTransition) continue;
-		if (isTokenField(key) && typeof value === "string") value = new SfToken(value);
+		if (isTokenField(key)) {
+			if (typeof value === "string") value = new SfToken(value);
+			else if (value instanceof SfItem && typeof value.value === "string") value = new SfItem(new SfToken(value.value), value.params);
+		}
 		results[key] = value;
 	}
 	return results;
@@ -970,6 +994,33 @@ const CMCD_KEYS = /* @__PURE__ */ [
 */
 const CMCD_MIME_TYPE = "application/cmcd";
 
+//#endregion
+//#region src/CMCD_REQUEST_PROVENANCE.ts
+/**
+* The `customData` key under which `CmcdReporter.createRequestReport()`
+* stamps session provenance on every request it returns.
+*
+* The value is a frozen `CmcdRequestProvenance` record: `sid` names the
+* session that issued the request, `cid` is the content id in effect when
+* the request was issued, and `data` carries the request's per-call data
+* as an encoded CMCD string. `CmcdReporter.recordResponseReceived()` reads
+* the record to attribute a late response to its session and to rebuild
+* the request-time report keys.
+* Spread and `Object.assign` carry the record through ordinary request
+* clones, but `JSON.stringify` and structured clone drop symbol-keyed
+* properties: read the value before such a boundary and restore it
+* afterward. The record itself survives JSON, and attribution is by the
+* `sid` value rather than object identity, so a revived plain-object copy
+* attributes exactly. A record naming a `sid` the reporter does not retain
+* drops the response rather than relabeling it.
+*
+* Backed by the symbol registry so duplicated copies of this library in
+* one bundle interoperate. The registry key is stable across versions.
+*
+* @public
+*/
+const CMCD_REQUEST_PROVENANCE = /* @__PURE__ */ Symbol.for("@svta/cml-cmcd/request-provenance");
+
 //#endregion
 //#region src/CMCD_V1.ts
 /**
@@ -1473,6 +1524,50 @@ const CmcdTransmissionMode = {
 	HEADERS: CMCD_HEADERS
 };
 
+//#endregion
+//#region src/upConvertToV2.ts
+/**
+* Up-convert V1 CMCD data to V2 format.
+*
+* - Wraps plain scalar values in arrays for inner-list keys.
+* - Wraps `nor` string in an array.
+*
+* If the data is already V2 (has `v: 2`), it is returned unchanged.
+*
+* @internal
+*/
+function upConvertToV2(obj) {
+	if (obj["v"] === CMCD_V2) return obj;
+	const result = {};
+	for (const [key, value] of Object.entries(obj)) {
+		if (value == null) {
+			result[key] = value;
+			continue;
+		}
+		if (CMCD_INNER_LIST_KEYS.has(key) && !Array.isArray(value)) result[key] = [value];
+		else if (key === "nor" && typeof value === "string") result[key] = [value];
+		else result[key] = value;
+	}
+	return result;
+}
+
+//#endregion
+//#region src/decodeCmcd.ts
+function reduceValue(value, useSymbol) {
+	if (Array.isArray(value)) return value.map((item) => reduceValue(item, useSymbol));
+	if (typeof value === "symbol") return useSymbol === void 0 ? symbolToStr(value) : value;
+	if (value instanceof SfItem) return value.params ? new SfItem(reduceValue(value.value, useSymbol), value.params) : reduceValue(value.value, useSymbol);
+	return value;
+}
+function decodeCmcd(cmcd, options) {
+	if (!cmcd) return {};
+	const sfDict = decodeSfDict(cmcd, options);
+	const result = {};
+	for (const [key, item] of Object.entries(sfDict)) result[key] = reduceValue(item, options?.useSymbol);
+	if (options?.convertToLatest) return upConvertToV2(result);
+	return result;
+}
+
 //#endregion
 //#region src/CmcdReporter.ts
 function createEncodingOptions(reportingMode, config, baseUrl) {
@@ -1579,8 +1674,10 @@ function copyItemValue(value) {
 *
 * Complete for the CMCD value space rather than best-effort: `CmcdValue` and
 * `CmcdCustomValue` admit only primitives, `SfItem<primitive>`, and arrays of
-* those, and `SfItem.params` is a flat record. Only called where a transform
-* is configured.
+* those, and `SfItem.params` is a flat record. Called where a transform is
+* configured, on the ended session's store at archival (detaching the frozen
+* snapshot from caller-held references), and on the request's stored
+* player-facing view.
 */
 function copyReportValues(data) {
 	const record = data;
@@ -1594,17 +1691,51 @@ function copyReportValues(data) {
 	}
 	return data;
 }
+/**
+* Decodes the per-call data snapshot a provenance record carries into
+* fresh, encodable report data: tokens revive as `SfToken` and
+* params-bearing items as `SfItem` (`useSymbol: false`), so every value
+* keeps its wire type through re-encoding. Only called in
+* `recordResponseReceived()`. Returns an empty object when the record is
+* absent, carries no snapshot, or the snapshot does not parse (a value
+* this reporter did not write); the response then reports its derived keys
+* over the session's data alone.
+*/
+function decodeSnapshot(provenance) {
+	const encoded = provenance !== null && typeof provenance === "object" ? provenance.data : void 0;
+	if (typeof encoded !== "string" || !encoded) return {};
+	try {
+		return decodeCmcd(encoded, { useSymbol: false });
+	} catch {
+		return {};
+	}
+}
+/**
+* Mints a session's frozen base provenance record: the issuing `sid`, and
+* the `cid` in effect at mint time. `update()` re-mints on every `cid`
+* change, so requests issued before a mid-session content change keep the
+* `cid` they were issued under while later requests carry the new one.
+*/
+function mintProvenance(sid, cid) {
+	return Object.freeze(typeof cid === "string" && cid ? {
+		sid,
+		cid
+	} : { sid });
+}
 function defaultRequester(request) {
 	const { url,...init } = request;
 	return fetch(url, init);
 }
 function createCmcdReporterConfig(config) {
 	const { version = CMCD_V2, eventTargets = [], sid = uuid(), transmissionMode = CMCD_QUERY,...rest } = config;
+	const retention = config.sessionRetention;
+	const sessionRetention = typeof retention === "number" ? Math.floor(retention) : NaN;
 	return {
 		...rest,
 		version,
 		transmissionMode,
 		sid,
+		sessionRetention: sessionRetention >= 0 ? sessionRetention : 2,
 		eventTargets: eventTargets.reduce((acc, target) => {
 			if (target?.url && target.events?.length) acc.push({
 				version: target.version || CMCD_V2,
@@ -1645,27 +1776,41 @@ var CmcdReporter = class {
 	*/
 	constructor(config, requester = defaultRequester) {
 		this.timeOrigin = performance.timeOrigin || performance.timing?.fetchStart || Date.now() - performance.now();
-		this.data = {};
-		this.msd = NaN;
-		this.eventTargets = /* @__PURE__ */ new Map();
-		this.lastEmitted = {};
-		this.requestTarget = {
-			sn: 0,
-			msdSent: false
-		};
+		this.sessions = /* @__PURE__ */ new Map();
+		this.intervals = /* @__PURE__ */ new Map();
+		this.started = false;
 		this.config = createCmcdReporterConfig(config);
-		this.data = {
+		this.session = this.createSession(this.config.sid, {
 			cid: this.config.cid,
-			sid: this.config.sid,
 			v: this.config.version
-		};
+		});
+		this.sessions.set(this.session.sid, this.session);
 		this.requester = requester;
-		for (const target of this.config.eventTargets) this.eventTargets.set(target, {
-			intervalId: void 0,
+	}
+	/**
+	* Creates the state for a new session: fresh counters, gates, queues and
+	* dedup baseline for every configured target.
+	*/
+	createSession(sid, data) {
+		const eventTargets = /* @__PURE__ */ new Map();
+		for (const target of this.config.eventTargets) eventTargets.set(target, {
 			sn: 0,
 			msdSent: false,
-			queue: []
+			queue: [],
+			disposed: false
 		});
+		return {
+			sid,
+			provenance: mintProvenance(sid, data.cid),
+			data,
+			msd: NaN,
+			lastEmitted: {},
+			eventTargets,
+			requestTarget: {
+				sn: 0,
+				msdSent: false
+			}
+		};
 	}
 	/**
 	* Starts the CMCD reporter. Called by the player when the reporter is enabled.
@@ -1675,17 +1820,15 @@ var CmcdReporter = class {
 	* populated before calling start().
 	*/
 	start() {
+		this.started = true;
 		let failure;
-		this.eventTargets.forEach((target, config) => {
-			this.disarmInterval(target);
-			if (config.interval === 0 || !config.events.includes(CMCD_EVENT_TIME_INTERVAL)) return;
-			const timeIntervalEvent = () => {
-				this.recordTargetEvent(target, config, CMCD_EVENT_TIME_INTERVAL);
-				this.processEventTargets();
-			};
-			target.intervalId = setInterval(timeIntervalEvent, config.interval * 1e3);
+		const session = this.session;
+		session.eventTargets.forEach((target, config) => {
+			this.disarmInterval(config);
+			if (target.disposed || !this.armInterval(config)) return;
 			try {
-				timeIntervalEvent();
+				this.recordTargetEvent(session, target, config, CMCD_EVENT_TIME_INTERVAL);
+				this.processEventTargets();
 			} catch (error) {
 				failure ??= { error };
 			}
@@ -1693,15 +1836,31 @@ var CmcdReporter = class {
 		if (failure) throw failure.error;
 	}
 	/**
+	* Arms the time-interval timer for an event target when its config calls
+	* for one. Returns whether a timer was armed. The callback reports into
+	* whichever session is current when it fires.
+	*/
+	armInterval(config) {
+		if (config.interval === 0 || !config.events.includes(CMCD_EVENT_TIME_INTERVAL)) return false;
+		this.intervals.set(config, setInterval(() => {
+			const session = this.session;
+			const target = session.eventTargets.get(config);
+			if (target) {
+				this.recordTargetEvent(session, target, config, CMCD_EVENT_TIME_INTERVAL);
+				this.processEventTargets();
+			}
+		}, config.interval * 1e3));
+		return true;
+	}
+	/**
 	* Stops the CMCD reporter. Called by the player when the reporter is disabled.
 	*
 	* @param flush - Whether to flush the event targets.
 	*/
 	stop(flush = false) {
+		this.started = false;
 		if (flush) this.flush();
-		this.eventTargets.forEach((target) => {
-			this.disarmInterval(target);
-		});
+		for (const config of this.config.eventTargets) this.disarmInterval(config);
 	}
 	/**
 	* Forces the sending of all event reports, regardless of the batch size or interval.
@@ -1739,17 +1898,63 @@ var CmcdReporter = class {
 	*
 	* A `sid` change resets the dedup baseline.
 	*
+	* `sid` and `msd` are session-owned: the reporter tracks them itself and
+	* stamps them onto every outgoing report, so this method is the only way
+	* to change them. A per-call value on {@link CmcdReporter.recordEvent},
+	* {@link CmcdReporter.createRequestReport}, or
+	* {@link CmcdReporter.recordResponseReceived} has no effect; response
+	* attribution is by the provenance record alone.
+	* `msd` must be a finite number of milliseconds between `0` and
+	* `999_999_999_999_999` (the RFC 8941 integer maximum); it is rounded to
+	* the nearest integer, and invalid values are ignored.
+	*
 	* @param data - The data to update.
 	*/
 	update(data) {
-		if (data.sid && data.sid !== this.data.sid) this.resetSession();
-		if (data.msd && !isNaN(data.msd)) this.msd = data.msd;
-		this.data = {
-			...this.data,
+		if (data.sid && data.sid !== this.session.sid) this.startSession(data.sid);
+		const session = this.session;
+		const { msd } = data;
+		if (typeof msd === "number" && Number.isFinite(msd) && msd >= 0) {
+			const rounded = Math.round(msd);
+			if (rounded <= 999999999999999) session.msd = rounded;
+		}
+		session.data = {
+			...session.data,
 			...data,
+			sid: void 0,
 			msd: void 0
 		};
-		for (const entry of STATE_FIELDS) if (entry.field in data && !entry.equal(this.data[entry.field], this.lastEmitted[entry.field])) this.recordEvent(entry.event);
+		if (session.data.cid !== session.provenance.cid) session.provenance = mintProvenance(session.sid, session.data.cid);
+		for (const entry of STATE_FIELDS) if (entry.field in data && !entry.equal(session.data[entry.field], session.lastEmitted[entry.field])) this.recordEvent(entry.event);
+	}
+	/**
+	* Starts a new session: the current one is archived in place for stale
+	* attribution, a fresh one takes over, ended sessions are drained, and
+	* the oldest are evicted beyond the configured retention.
+	*
+	* The data store is carried over, and the archived snapshot is frozen:
+	* the ended session's value graph is detached first, so nested values
+	* the caller handed to `update()` can no longer mutate it, and the new
+	* session starts from a shallow copy of the detached graph, so `cid`,
+	* `br`, custom keys and the rest survive a `sid` change as they always
+	* have. Sessions are keyed by `sid`, which CTA-5004-B expects to be
+	* unique per playback session: reusing one replaces the retained
+	* namesake, whose remaining state dies as if evicted and whose late
+	* responses relabel onto the replacement.
+	*/
+	startSession(sid) {
+		this.session.data = copyReportValues({ ...this.session.data });
+		this.session = this.createSession(sid, { ...this.session.data });
+		this.sessions.delete(sid);
+		this.sessions.set(sid, this.session);
+		this.processEventTargets();
+		for (const key of this.sessions.keys()) {
+			if (this.sessions.size <= this.config.sessionRetention + 1) break;
+			this.sessions.delete(key);
+		}
+		if (this.started) {
+			for (const config of this.config.eventTargets) if (!this.intervals.has(config)) this.armInterval(config);
+		}
 	}
 	/**
 	* Records an event. Called by the player when an event occurs.
@@ -1784,15 +1989,21 @@ var CmcdReporter = class {
 	* @param data - Additional data to record with the event. This data
 	*               only applies to this event report, except for the dedup
 	*               field of a state-change event, which is also persisted
-	*               into the reporter's data store.
+	*               into the reporter's data store. Session-owned keys
+	*               (`sid`, `msd`) supplied here are ignored; the reporter
+	*               stamps its own values.
 	*/
 	recordEvent(type, data = {}) {
-		this.emitEvent(type, data);
+		this.emitEvent(this.session, type, data);
 	}
 	/**
-	* Records an event across every configured target, applying
+	* Records an event across every configured target of a session, applying
 	* state-change dedup once before per-target fan-out.
 	*
+	* @param session - The session the event belongs to. Everything the event
+	*                  touches (data store, dedup baseline, counters, queues)
+	*                  is that session's; only `recordResponseReceived()` ever
+	*                  passes an archived one.
 	* @param type - The type of event to record.
 	* @param data - Additional data to record with the event.
 	* @param request - The media request that triggered the event, when
@@ -1800,21 +2011,21 @@ var CmcdReporter = class {
 	*                  populates this; it is threaded through to each
 	*                  target's `transform`.
 	*/
-	emitEvent(type, data, request) {
+	emitEvent(session, type, data, request) {
 		const entry = STATE_FIELDS_BY_EVENT.get(type);
 		if (entry) {
 			const field = entry.field;
 			const incoming = data[field];
-			if (incoming !== void 0) Object.assign(this.data, { [field]: incoming });
-			const current = this.data[field];
+			if (incoming !== void 0) Object.assign(session.data, { [field]: incoming });
+			const current = session.data[field];
 			if (current === void 0) return;
-			if (entry.equal(current, this.lastEmitted[field])) return;
-			Object.assign(this.lastEmitted, { [field]: entry.snapshot(current) });
+			if (entry.equal(current, session.lastEmitted[field])) return;
+			Object.assign(session.lastEmitted, { [field]: entry.snapshot(current) });
 		}
 		let failure;
-		this.eventTargets.forEach((target, config) => {
+		session.eventTargets.forEach((target, config) => {
 			try {
-				this.recordTargetEvent(target, config, type, data, request);
+				this.recordTargetEvent(session, target, config, type, data, request);
 			} catch (error) {
 				failure ??= { error };
 			}
@@ -1834,17 +2045,18 @@ var CmcdReporter = class {
 	* @param request - The media request that triggered the event, when
 	*                  one exists. Passed to the target's `transform`.
 	*/
-	recordTargetEvent(target, config, type, data = {}, request) {
-		if (!config.events.includes(type)) return;
+	recordTargetEvent(session, target, config, type, data = {}, request) {
+		if (target.disposed || !config.events.includes(type)) return;
 		const item = {
-			...this.data,
+			...session.data,
 			...data,
+			sid: session.sid,
 			e: type,
 			ts: data.ts ?? Date.now()
 		};
 		const { transform } = config;
 		if (!transform) {
-			this.queueTargetEvent(target, item, type);
+			this.queueTargetEvent(session, target, config, item, type);
 			return;
 		}
 		copyReportValues(item);
@@ -1855,27 +2067,33 @@ var CmcdReporter = class {
 		if (report == null) return;
 		if (!isUsableRequiredValue(report.ts)) report.ts = ts;
 		if (requiredKey && isUsableRequiredValue(requiredValue) && !isUsableRequiredValue(report[requiredKey])) Object.assign(report, { [requiredKey]: requiredValue });
-		this.queueTargetEvent(target, report, type);
+		this.queueTargetEvent(session, target, config, report, type);
 	}
 	/**
-	* Stamps the reporter-owned fields on a finished event report and pushes it
-	* to the target's queue.
+	* Stamps the reporter-owned fields on a finished event report, encodes it,
+	* and pushes the wire line to the target's queue.
 	*
 	* Called after any transform has run, so a transform cannot bypass the
-	* target's `events` filter via `e` or break `sn` continuity.
+	* target's `events` filter via `e`, break `sn` continuity, or substitute
+	* the session identity carried by `sid` and `msd`. Encoding here means a
+	* report that cannot serialize throws inside the recording call that
+	* produced it, instead of rejecting the batch send and re-queueing
+	* forever.
 	*
 	* @param target - The target to queue the report for.
+	* @param config - The configuration for the target.
 	* @param report - The finished report data.
 	* @param type - The type of event being reported.
 	*/
-	queueTargetEvent(target, report, type) {
+	queueTargetEvent(session, target, config, report, type) {
 		report.e = type;
 		report.sn = target.sn++;
-		if (!isNaN(this.msd) && !target.msdSent) {
-			report.msd = this.msd;
+		report.sid = session.sid;
+		if (!isNaN(session.msd) && !target.msdSent && config.enabledKeys?.includes("msd")) {
+			report.msd = session.msd;
 			target.msdSent = true;
-		}
-		target.queue.push(report);
+		} else delete report.msd;
+		target.queue.push(encodeCmcd(report, createEncodingOptions(CMCD_EVENT_MODE, config)));
 	}
 	/**
 	* Records a response-received event. Called by the player when a media
@@ -1894,26 +2112,55 @@ var CmcdReporter = class {
 	*
 	* The request's `customData` is generic, so a player can pass a request
 	* carrying its own taxonomy (e.g. `{ requestType: 'segment' }`) without a
-	* cast. The reporter only reads the optional `cmcd` key that
-	* {@link CmcdReporter.createRequestReport} writes there; every other key is
-	* left untouched and stays visible to an event target's `transform` via
-	* its `request` argument.
+	* cast. The reporter reads only the provenance record that
+	* {@link CmcdReporter.createRequestReport} writes there; every other key
+	* is left untouched and stays visible to an event target's `transform`
+	* via its `request` argument.
 	*
 	* A reporter given a concrete `C` requires the request to satisfy it, so a
 	* request the configured transforms could not read is rejected here rather
 	* than reaching them; see {@link CmcdReporterCustomData}.
 	*
+	* The event is attributed to the session that issued the request, and to
+	* nothing else: the provenance record that
+	* {@link CmcdReporter.createRequestReport} stored on the request's
+	* `customData` (under {@link CMCD_REQUEST_PROVENANCE}) selects the
+	* session by its `sid`, or the response is dropped rather than
+	* relabeled. There is no other key: a record lost to a serialization
+	* boundary (and not restored; see the bridge notes on
+	* {@link CMCD_REQUEST_PROVENANCE}) and a session no longer retained
+	* (see `CmcdReporterConfig.sessionRetention`) both drop, and a per-call
+	* `data.sid` cannot substitute. The record is honored wherever its
+	* `sid` resolves: a request decorated by another reporter configured
+	* with the same session attributes here, as does a hand-built record.
+	* A response that completes after a `sid` change reports under its own
+	* retained session, with that session's data snapshot and sequence
+	* numbers.
+	*
+	* Request-time report keys come from the record's encoded per-call
+	* `data` snapshot, decoded fresh per response, and the record's `cid`
+	* reports in place of the session's current one, so a response that
+	* completes after a mid-session content change keeps the meaning it
+	* had when its request was issued.
+	*
 	* @typeParam RD - The `customData` this request carries. Defaults to the
 	*                reporter's own `C`.
 	*
 	* @param response - The HTTP response received.
 	* @param data - Additional CMCD data to include with the event.
 	*               Values provided here override any auto-derived values.
+	*               Session-owned keys (`sid`, `msd`) supplied here are
+	*               ignored; attribution is by the provenance record alone.
 	*/
 	recordResponseReceived(response, data = {}) {
 		const { request } = response;
 		const url = data.url ?? request?.url;
 		if (!url) return;
+		const provenance = request.customData?.[CMCD_REQUEST_PROVENANCE];
+		const session = this.resolveSession(provenance);
+		if (!session) return;
+		const cmcd = decodeSnapshot(provenance);
+		const { cid } = provenance;
 		const urlObj = new URL(url);
 		urlObj.searchParams.delete(CMCD_PARAM);
 		const derived = {
@@ -1928,14 +2175,28 @@ var CmcdReporter = class {
 			}
 			if (timing.duration != null) derived.ttlb = Math.round(timing.duration);
 		}
-		const cmcd = request.customData?.cmcd ?? {};
-		this.emitEvent(CMCD_EVENT_RESPONSE_RECEIVED, {
+		this.emitEvent(session, CMCD_EVENT_RESPONSE_RECEIVED, {
+			...typeof cid === "string" && cid ? { cid } : void 0,
 			...cmcd,
 			...derived,
 			...data
 		}, request);
 	}
 	/**
+	* Resolves the session a response belongs to: the provenance record's
+	* `sid` names one of this reporter's retained sessions, or the response
+	* is dropped. There is no other key — a record that was lost, or that
+	* names an evicted or never-seen `sid`, resolves nothing, and
+	* attributing it anywhere else would relabel it. The `sid` is read
+	* structurally, so a JSON-revived copy of a record attributes exactly,
+	* and a hand-built record naming a retained session is honored.
+	*/
+	resolveSession(provenance) {
+		if (provenance === null || typeof provenance !== "object") return;
+		const { sid } = provenance;
+		return typeof sid === "string" ? this.sessions.get(sid) : void 0;
+	}
+	/**
 	* Applies the CMCD request report data to the request. Called by the player
 	* before sending the request.
 	*
@@ -1956,6 +2217,34 @@ var CmcdReporter = class {
 		return !!this.config.enabledKeys?.length;
 	}
 	/**
+	* The provenance record to stamp on a returned request: the session's
+	* frozen base record, extended with the caller's per-call data encoded
+	* as a CMCD string when there is any. Requests without per-call data
+	* share the base record, so decoration stays a single property write.
+	* The snapshot never contains reporter-stamped fields, and a value that
+	* cannot encode contributes no snapshot rather than failing the
+	* request; its response still attributes and reports derived keys over
+	* session data, matching `decodeSnapshot()`'s tolerance on the read
+	* side.
+	*/
+	createRequestProvenance(data, baseUrl) {
+		const base = this.session.provenance;
+		if (!data) return base;
+		try {
+			const encoded = encodeCmcd(data, {
+				version: this.config.version,
+				reportingMode: CMCD_REQUEST_MODE,
+				baseUrl
+			});
+			return encoded ? Object.freeze({
+				...base,
+				data: encoded
+			}) : base;
+		} catch {
+			return base;
+		}
+	}
+	/**
 	* Creates a new request with the CMCD request report data applied. Called by the player
 	* before sending the request.
 	*
@@ -1980,13 +2269,16 @@ var CmcdReporter = class {
 			headers: { ...headers },
 			customData: {
 				...customData,
-				cmcd: {}
+				cmcd: {},
+				[CMCD_REQUEST_PROVENANCE]: this.createRequestProvenance(data, request.url)
 			}
 		};
 		if (!this.config.enabledKeys?.length || !report.url) return report;
+		const session = this.session;
 		const merged = {
-			...this.data,
-			...data
+			...session.data,
+			...data,
+			sid: session.sid
 		};
 		const { transform } = this.config;
 		let cmcdData = merged;
@@ -1995,19 +2287,20 @@ var CmcdReporter = class {
 			cmcdData = transform(merged, request);
 			if (cmcdData == null) return report;
 		}
-		cmcdData.sn = this.requestTarget.sn++;
-		if (!isNaN(this.msd) && !this.requestTarget.msdSent) {
-			cmcdData.msd = this.msd;
-			this.requestTarget.msdSent = true;
-		}
+		cmcdData.sn = session.requestTarget.sn++;
+		cmcdData.sid = session.sid;
+		const sendMsd = !isNaN(session.msd) && !session.requestTarget.msdSent;
+		if (sendMsd) cmcdData.msd = session.msd;
+		else delete cmcdData.msd;
 		const url = new URL(report.url);
 		const options = createEncodingOptions(CMCD_REQUEST_MODE, this.config, report.url);
-		const cmcd = report.customData.cmcd = prepareCmcdData(cmcdData, options);
+		const cmcd = report.customData.cmcd = copyReportValues(prepareCmcdData(cmcdData, options));
+		if (sendMsd && cmcd.msd !== void 0) session.requestTarget.msdSent = true;
+		const encoded = encodePreparedCmcd(cmcd);
 		switch (this.config.transmissionMode) {
 			case CMCD_QUERY:
-				const param = encodePreparedCmcd(cmcd);
-				if (param) {
-					url.searchParams.set(CMCD_PARAM, param);
+				if (encoded) {
+					url.searchParams.set(CMCD_PARAM, encoded);
 					report.url = url.toString();
 				}
 				break;
@@ -2024,16 +2317,19 @@ var CmcdReporter = class {
 	*/
 	processEventTargets(flush = false) {
 		let reprocess = false;
-		this.eventTargets.forEach((target, config) => {
-			const { queue } = target;
-			if (!queue.length) return;
-			if (queue.length < config.batchSize && !flush) return;
-			const deleteCount = flush ? queue.length : config.batchSize;
-			const events = queue.splice(0, deleteCount);
-			this.sendEventReport(config, events).catch(() => {
-				target.queue.unshift(...events);
+		this.sessions.forEach((session) => {
+			const drain = flush || session !== this.session;
+			session.eventTargets.forEach((target, config) => {
+				const { queue } = target;
+				if (target.disposed || !queue.length) return;
+				if (queue.length < config.batchSize && !drain) return;
+				const deleteCount = drain ? queue.length : config.batchSize;
+				const events = queue.splice(0, deleteCount);
+				this.sendEventReport(session, config, events).catch(() => {
+					target.queue.unshift(...events);
+				});
+				reprocess ||= queue.length > 0;
 			});
-			reprocess ||= queue.length > 0;
 		});
 		if (reprocess) this.processEventTargets();
 	}
@@ -2041,44 +2337,42 @@ var CmcdReporter = class {
 	* Sends an event report. Called by the reporter when a batch is ready to be sent.
 	*
 	* @param config - The target config to send the event report to.
-	* @param data - The data to send in the event report.
+	* @param data - The encoded report lines to send in the event report.
 	*/
-	async sendEventReport(config, data) {
-		const options = createEncodingOptions(CMCD_EVENT_MODE, config);
+	async sendEventReport(session, config, data) {
 		const { status } = await this.requester({
 			url: config.url,
 			method: "POST",
 			headers: { "Content-Type": CMCD_MIME_TYPE },
-			body: data.map((item) => encodeCmcd(item, options)).join("\n") + "\n"
+			body: data.join("\n") + "\n"
 		});
-		if (status === 410) this.disposeEventTarget(config);
+		if (status === 410) this.disposeEventTarget(session, config);
 		else if (status === 429 || status > 499 && status < 600) throw new Error(`Event report failed with status ${status}`);
 	}
 	/**
-	* Cancels the time-interval timer for an event target and clears the stored id.
-	* Safe to call when no timer is armed (clearInterval(undefined) is a no-op).
+	* Cancels the time-interval timer for an event target config and clears the
+	* stored id. Safe to call when no timer is armed (clearInterval(undefined)
+	* is a no-op).
 	*/
-	disarmInterval(target) {
-		clearInterval(target.intervalId);
-		target.intervalId = void 0;
+	disarmInterval(config) {
+		clearInterval(this.intervals.get(config));
+		this.intervals.delete(config);
 	}
 	/**
-	* Permanently removes an event target: cancels its timer and removes it from the
-	* eventTargets map. Used when the collector signals the target is gone (HTTP 410).
+	* Silences an event target URL for the remainder of its session: drops the
+	* queues and blocks further enqueues for every config in the session that
+	* reports to the URL, per CTA-5004-B's per-target-URL suppression scope,
+	* and cancels their timers when the session is the live one. Used when the
+	* collector signals the target is gone (HTTP 410). A session started after
+	* the disposal is unaffected, since it gets fresh target state.
 	*/
-	disposeEventTarget(config) {
-		const target = this.eventTargets.get(config);
-		if (!target) return;
-		this.disarmInterval(target);
-		this.eventTargets.delete(config);
-	}
-	/**
-	* Resets the session related data. Called when the session ID changes.
-	*/
-	resetSession() {
-		this.eventTargets.forEach((target) => target.sn = 0);
-		this.requestTarget.sn = 0;
-		this.lastEmitted = {};
+	disposeEventTarget(session, config) {
+		session.eventTargets.forEach((target, sibling) => {
+			if (sibling.url !== config.url || target.disposed) return;
+			target.disposed = true;
+			target.queue.length = 0;
+			if (session === this.session) this.disarmInterval(sibling);
+		});
 	}
 };
 
@@ -2141,51 +2435,6 @@ const CmcdValidationSeverity = {
 	WARNING: CMCD_VALIDATION_SEVERITY_WARNING
 };
 
-//#endregion
-//#region src/upConvertToV2.ts
-/**
-* Up-convert V1 CMCD data to V2 format.
-*
-* - Wraps plain scalar values in arrays for inner-list keys.
-* - Wraps `nor` string in an array.
-*
-* If the data is already V2 (has `v: 2`), it is returned unchanged.
-*
-* @internal
-*/
-function upConvertToV2(obj) {
-	if (obj["v"] === CMCD_V2) return obj;
-	const result = {};
-	for (const [key, value] of Object.entries(obj)) {
-		if (value == null) {
-			result[key] = value;
-			continue;
-		}
-		if (CMCD_INNER_LIST_KEYS.has(key) && !Array.isArray(value)) result[key] = [value];
-		else if (key === "nor" && typeof value === "string") result[key] = [value];
-		else result[key] = value;
-	}
-	return result;
-}
-
-//#endregion
-//#region src/decodeCmcd.ts
-function reduceValue(value) {
-	if (Array.isArray(value)) return value.map(reduceValue);
-	if (typeof value === "symbol") return symbolToStr(value);
-	if (value instanceof SfItem && !value.params) return reduceValue(value.value);
-	if (typeof value === "string") return value;
-	return value;
-}
-function decodeCmcd(cmcd, options) {
-	if (!cmcd) return {};
-	const sfDict = decodeSfDict(cmcd);
-	const result = {};
-	for (const [key, item] of Object.entries(sfDict)) result[key] = reduceValue(item.value);
-	if (options?.convertToLatest) return upConvertToV2(result);
-	return result;
-}
-
 //#endregion
 //#region src/ensureHeaders.ts
 /**
@@ -2386,7 +2635,8 @@ function validateCmcdStructure(data, options) {
 		});
 	}
 	if ("e" in data) {
-		if (data["e"] === CMCD_EVENT_CUSTOM_EVENT) {
+		const eventType = toTokenString(data["e"]);
+		if (eventType === CMCD_EVENT_CUSTOM_EVENT) {
 			if (!("cen" in data)) issues.push({
 				key: "cen",
 				message: "Custom event (e=\"ce\") requires the \"cen\" key to be present.",
@@ -2397,7 +2647,7 @@ function validateCmcdStructure(data, options) {
 			message: "The \"cen\" key must only be present when e=\"ce\".",
 			severity: CMCD_VALIDATION_SEVERITY_ERROR
 		});
-		if (data["e"] === CMCD_EVENT_RESPONSE_RECEIVED) {
+		if (eventType === CMCD_EVENT_RESPONSE_RECEIVED) {
 			if (!("url" in data)) issues.push({
 				key: "url",
 				message: "Response received event (e=\"rr\") requires the \"url\" key to be present.",
@@ -2408,12 +2658,12 @@ function validateCmcdStructure(data, options) {
 			message: `Response key "${key}" must only be present when e="rr".`,
 			severity: CMCD_VALIDATION_SEVERITY_ERROR
 		});
-		for (const [eventType, requiredField] of CMCD_STATE_EVENT_FIELDS) if (data["e"] === eventType && !(requiredField in data)) issues.push({
+		for (const [stateEventType, requiredField] of CMCD_STATE_EVENT_FIELDS) if (eventType === stateEventType && !(requiredField in data)) issues.push({
 			key: requiredField,
-			message: `State-change event (e="${eventType}") requires the "${requiredField}" key to be present.`,
+			message: `State-change event (e="${stateEventType}") requires the "${requiredField}" key to be present.`,
 			severity: CMCD_VALIDATION_SEVERITY_ERROR
 		});
-		if (data["e"] === CMCD_EVENT_ERROR && !("ec" in data)) issues.push({
+		if (eventType === CMCD_EVENT_ERROR && !("ec" in data)) issues.push({
 			key: "ec",
 			message: "Error event (e=\"e\") requires the \"ec\" key to be present.",
 			severity: CMCD_VALIDATION_SEVERITY_ERROR
@@ -2799,9 +3049,10 @@ function validateCmcdValues(data, options) {
 				break;
 			case CMCD_KEY_TYPE_TOKEN: {
 				const validValues = CMCD_TOKEN_VALUES[key];
-				if (validValues && !validValues.includes(value)) issues.push({
+				const token = toTokenString(value);
+				if (validValues && (token === void 0 || !validValues.includes(token))) issues.push({
 					key,
-					message: `Key "${key}" has invalid token value "${String(value)}". Expected one of: ${validValues.join(", ")}.`,
+					message: `Key "${key}" has invalid token value "${token ?? String(value)}". Expected one of: ${validValues.join(", ")}.`,
 					severity: CMCD_VALIDATION_SEVERITY_ERROR
 				});
 				break;
@@ -3106,5 +3357,5 @@ function extractHeaderRecord(headers) {
 }
 
 //#endregion
-export { CMCD_DEFAULT_TIME_INTERVAL, CMCD_EVENT_AD_BREAK_END, CMCD_EVENT_AD_BREAK_START, CMCD_EVENT_AD_END, CMCD_EVENT_AD_START, CMCD_EVENT_BACKGROUNDED_MODE, CMCD_EVENT_BITRATE_CHANGE, CMCD_EVENT_CONTENT_ID, CMCD_EVENT_CUSTOM_EVENT, CMCD_EVENT_ERROR, CMCD_EVENT_KEYS, CMCD_EVENT_MODE, CMCD_EVENT_MUTE, CMCD_EVENT_PLAYBACK_RATE, CMCD_EVENT_PLAYER_COLLAPSE, CMCD_EVENT_PLAYER_EXPAND, CMCD_EVENT_PLAY_STATE, CMCD_EVENT_RESPONSE_RECEIVED, CMCD_EVENT_SKIP, CMCD_EVENT_TIME_INTERVAL, CMCD_EVENT_UNMUTE, CMCD_FORMATTER_MAP, CMCD_HEADERS, CMCD_HEADER_FIELDS, CMCD_HEADER_MAP, CMCD_JSON, CMCD_KEYS, CMCD_MIME_TYPE, CMCD_OBJECT, CMCD_PARAM, CMCD_QUERY, CMCD_RECORDED_REPORT_MODE_EVENT, CMCD_RECORDED_REPORT_MODE_HEADER, CMCD_RECORDED_REPORT_MODE_QUERY, CMCD_RECORDED_REQUEST_TYPE_EVENT, CMCD_RECORDED_REQUEST_TYPE_MANIFEST, CMCD_RECORDED_REQUEST_TYPE_SEGMENT, CMCD_RECORDED_REQUEST_TYPE_UNKNOWN, CMCD_REQUEST, CMCD_REQUEST_KEYS, CMCD_REQUEST_MODE, CMCD_RESPONSE_KEYS, CMCD_SESSION, CMCD_STATUS, CMCD_V1, CMCD_V1_KEYS, CMCD_V2, CMCD_VALIDATION_SEVERITY_ERROR, CMCD_VALIDATION_SEVERITY_WARNING, CmcdEventType, CmcdHeaderField, CmcdObjectType, CmcdPlayerState, CmcdRecordedReportMode, CmcdRecordedRequestType, CmcdReportRecorder, CmcdReporter, CmcdReportingMode, CmcdStreamType, CmcdStreamingFormat, CmcdTransmissionMode, CmcdValidationSeverity, appendCmcdHeaders, appendCmcdQuery, createFetchTransport, createXhrTransport, decodeCmcd, encodeCmcd, fromCmcdHeaders, fromCmcdQuery, fromCmcdUrl, groupCmcdHeaders, isCmcdCustomKey, isCmcdEventKey, isCmcdRequestKey, isCmcdResponseReceivedKey, isCmcdV1Data, isCmcdV1Key, isCmcdV2Data, prepareCmcdData, toCmcdHeaders, toCmcdQuery, toCmcdUrl, toCmcdValue, validateCmcd, validateCmcdEventReport, validateCmcdEvents, validateCmcdHeaders, validateCmcdKeys, validateCmcdRequest, validateCmcdStructure, validateCmcdValues };
+export { CMCD_DEFAULT_TIME_INTERVAL, CMCD_EVENT_AD_BREAK_END, CMCD_EVENT_AD_BREAK_START, CMCD_EVENT_AD_END, CMCD_EVENT_AD_START, CMCD_EVENT_BACKGROUNDED_MODE, CMCD_EVENT_BITRATE_CHANGE, CMCD_EVENT_CONTENT_ID, CMCD_EVENT_CUSTOM_EVENT, CMCD_EVENT_ERROR, CMCD_EVENT_KEYS, CMCD_EVENT_MODE, CMCD_EVENT_MUTE, CMCD_EVENT_PLAYBACK_RATE, CMCD_EVENT_PLAYER_COLLAPSE, CMCD_EVENT_PLAYER_EXPAND, CMCD_EVENT_PLAY_STATE, CMCD_EVENT_RESPONSE_RECEIVED, CMCD_EVENT_SKIP, CMCD_EVENT_TIME_INTERVAL, CMCD_EVENT_UNMUTE, CMCD_FORMATTER_MAP, CMCD_HEADERS, CMCD_HEADER_FIELDS, CMCD_HEADER_MAP, CMCD_JSON, CMCD_KEYS, CMCD_MIME_TYPE, CMCD_OBJECT, CMCD_PARAM, CMCD_QUERY, CMCD_RECORDED_REPORT_MODE_EVENT, CMCD_RECORDED_REPORT_MODE_HEADER, CMCD_RECORDED_REPORT_MODE_QUERY, CMCD_RECORDED_REQUEST_TYPE_EVENT, CMCD_RECORDED_REQUEST_TYPE_MANIFEST, CMCD_RECORDED_REQUEST_TYPE_SEGMENT, CMCD_RECORDED_REQUEST_TYPE_UNKNOWN, CMCD_REQUEST, CMCD_REQUEST_KEYS, CMCD_REQUEST_MODE, CMCD_REQUEST_PROVENANCE, CMCD_RESPONSE_KEYS, CMCD_SESSION, CMCD_STATUS, CMCD_V1, CMCD_V1_KEYS, CMCD_V2, CMCD_VALIDATION_SEVERITY_ERROR, CMCD_VALIDATION_SEVERITY_WARNING, CmcdEventType, CmcdHeaderField, CmcdObjectType, CmcdPlayerState, CmcdRecordedReportMode, CmcdRecordedRequestType, CmcdReportRecorder, CmcdReporter, CmcdReportingMode, CmcdStreamType, CmcdStreamingFormat, CmcdTransmissionMode, CmcdValidationSeverity, appendCmcdHeaders, appendCmcdQuery, createFetchTransport, createXhrTransport, decodeCmcd, encodeCmcd, fromCmcdHeaders, fromCmcdQuery, fromCmcdUrl, groupCmcdHeaders, isCmcdCustomKey, isCmcdEventKey, isCmcdRequestKey, isCmcdResponseReceivedKey, isCmcdV1Data, isCmcdV1Key, isCmcdV2Data, prepareCmcdData, toCmcdHeaders, toCmcdQuery, toCmcdUrl, toCmcdValue, validateCmcd, validateCmcdEventReport, validateCmcdEvents, validateCmcdHeaders, validateCmcdKeys, validateCmcdRequest, validateCmcdStructure, validateCmcdValues };
 //# sourceMappingURL=index.js.map