@svta/cml-cmcd 2.4.1 → 2.6.0

package/dist/index.js

@@ -315,9 +315,12 @@ const CMCD_REQUEST_KEYS = [
 
 //#endregion
 //#region src/isCmcdCustomKey.ts
-const CUSTOM_KEY_REGEX = /^[a-zA-Z0-9.-]+$/;
+const CUSTOM_KEY_REGEX = /^[a-z][a-z0-9.-]*$/;
 /**
-* Check if a key is a custom key.
+* Check if a key is a valid custom key: a lowercase first letter, then
+* characters from `a-z 0-9 . -`, with a hyphen that is neither the first
+* nor the last character. These are the CTA-5004-B custom-key rules
+* restricted to names that survive RFC 8941 key serialization.
 *
 * @param key - The key to check.
 *
@@ -569,6 +572,9 @@ function downConvertToV1(obj) {
 * @param options - Options for encoding.
 *
 * @public
+*
+* @example
+* {@includeCode ../test/prepareCmcdData.test.ts#example}
 */
 function prepareCmcdData(obj, options = {}) {
 	const results = {};
@@ -587,6 +593,8 @@ function prepareCmcdData(obj, options = {}) {
 		if (!keys.includes("e") && eventType != 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");
+		if (!keys.includes("url") && data["url"] != null && eventType === CMCD_EVENT_RESPONSE_RECEIVED) keys.push("url");
 		const requiredField = eventType ? CMCD_STATE_EVENT_FIELDS.get(eventType) : void 0;
 		if (requiredField && data[requiredField] != null && !keys.includes(requiredField)) keys.push(requiredField);
 	}
@@ -962,6 +970,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
 /**
@@ -1465,6 +1500,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) {
@@ -1473,7 +1552,8 @@ function createEncodingOptions(reportingMode, config, baseUrl) {
 		version: config.version || CMCD_V2,
 		reportingMode,
 		filter: (key) => enabledKeySet.has(key),
-		baseUrl
+		baseUrl,
+		customHeaderMap: config.customHeaderMap
 	};
 }
 /**
@@ -1523,17 +1603,115 @@ const STATE_FIELDS = /* @__PURE__ */ Array.from(CMCD_STATE_EVENT_FIELDS, ([event
 	};
 });
 const STATE_FIELDS_BY_EVENT = /* @__PURE__ */ new Map(/* @__PURE__ */ STATE_FIELDS.map((e) => [e.event, e]));
+/**
+* Maps each event type to the key CTA-5004-B requires beyond `e` and `ts`.
+* Built from the state-change table plus the three event types whose
+* required key rides the caller's per-event data.
+*/
+const CMCD_REQUIRED_EVENT_KEYS = /* @__PURE__ */ new Map([
+	...CMCD_STATE_EVENT_FIELDS,
+	[CMCD_EVENT_CUSTOM_EVENT, "cen"],
+	[CMCD_EVENT_ERROR, "ec"],
+	[CMCD_EVENT_RESPONSE_RECEIVED, "url"]
+]);
+/**
+* Whether a required key's value will survive report preparation.
+*
+* This is `isValid` minus its `false` exclusion, plus an empty-array check.
+* `false` must count as usable because `bg: false` is a legitimate value on a
+* backgrounded-mode event, which the encoder emits as `?0`; treating it as
+* unusable would let restoration silently revert a transform that cleared it.
+* Empty strings, empty lists and non-finite numbers are dropped downstream, so
+* a transform substituting one leaves the report short a required key.
+*/
+function isUsableRequiredValue(value) {
+	if (value == null || value === "") return false;
+	if (typeof value === "number") return Number.isFinite(value);
+	return !Array.isArray(value) || value.length > 0;
+}
+/**
+* Copies an `SfItem`-shaped value and its `params` record.
+*
+* The prototype is preserved because `prepareCmcdData`, the formatter map,
+* validation, and the structured-field encoder all branch on
+* `instanceof SfItem`. A plain spread (and `structuredClone`) would return a
+* prototype-less object and silently change what goes on the wire.
+*/
+function copyItemValue(value) {
+	if (value === null || typeof value !== "object") return value;
+	const copy = Object.assign(Object.create(Object.getPrototypeOf(value)), value);
+	if (copy.params !== null && typeof copy.params === "object") copy.params = { ...copy.params };
+	return copy;
+}
+/**
+* Copies the nested values of a report in place so a transform cannot mutate
+* the reporter's persistent data, or another target's report for the same
+* event, by mutating an array or an `SfItem` it was handed.
+*
+* 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. 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;
+	for (const key in record) {
+		const value = record[key];
+		if (Array.isArray(value)) {
+			const copy = new Array(value.length);
+			for (let i = 0; i < value.length; i++) copy[i] = copyItemValue(value[i]);
+			record[key] = copy;
+		} else if (value !== null && typeof value === "object") record[key] = copyItemValue(value);
+	}
+	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,
@@ -1541,7 +1719,8 @@ function createCmcdReporterConfig(config) {
 				url: target.url,
 				events: target.events.slice(),
 				interval: target.interval ?? CMCD_DEFAULT_TIME_INTERVAL,
-				batchSize: target.batchSize || 1
+				batchSize: target.batchSize || 1,
+				transform: target.transform
 			});
 			return acc;
 		}, [])
@@ -1550,6 +1729,14 @@ function createCmcdReporterConfig(config) {
 /**
 * The CMCD reporter.
 *
+* `C` describes the player's own `customData`, which the reporter passes
+* through to each configured `transform`. It is inferred from the
+* configuration, so annotating a single `transform` types the request in every
+* other one; the default leaves `customData` values `unknown`.
+*
+* @typeParam C - The shape of the player's `customData`. Defaults to
+*                `Record<string, unknown>`.
+*
 * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#reporting-modes-when-we-send-data | CTA-5004-B Reporting Modes}
 *
 * @public
@@ -1565,27 +1752,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.
@@ -1595,16 +1796,37 @@ var CmcdReporter = class {
 	* populated before calling start().
 	*/
 	start() {
-		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.started = true;
+		let failure;
+		const session = this.session;
+		session.eventTargets.forEach((target, config) => {
+			this.disarmInterval(config);
+			if (target.disposed || !this.armInterval(config)) return;
+			try {
+				this.recordTargetEvent(session, target, config, CMCD_EVENT_TIME_INTERVAL);
 				this.processEventTargets();
-			};
-			target.intervalId = setInterval(timeIntervalEvent, config.interval * 1e3);
-			timeIntervalEvent();
+			} catch (error) {
+				failure ??= { error };
+			}
 		});
+		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.
@@ -1612,10 +1834,9 @@ var CmcdReporter = class {
 	* @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.
@@ -1653,17 +1874,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.
@@ -1698,23 +1965,49 @@ 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(this.session, type, data);
+	}
+	/**
+	* 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
+	*                  one exists. Only `recordResponseReceived()`
+	*                  populates this; it is threaded through to each
+	*                  target's `transform`.
+	*/
+	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) });
 		}
-		this.eventTargets.forEach((target, config) => {
-			this.recordTargetEvent(target, config, type, data);
+		let failure;
+		session.eventTargets.forEach((target, config) => {
+			try {
+				this.recordTargetEvent(session, target, config, type, data, request);
+			} catch (error) {
+				failure ??= { error };
+			}
 		});
 		this.processEventTargets();
+		if (failure) throw failure.error;
 	}
 	/**
 	* Records an event for a target. Called by the reporter when an event occurs.
@@ -1725,21 +2018,58 @@ var CmcdReporter = class {
 	* @param data - Additional data to record with the event. This data
 	*               only applies to this event report. Persistent data should
 	*               be updated using `update()`.
+	* @param request - The media request that triggered the event, when
+	*                  one exists. Passed to the target's `transform`.
 	*/
-	recordTargetEvent(target, config, type, data = {}) {
-		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(),
-			sn: target.sn++
+			ts: data.ts ?? Date.now()
 		};
-		if (!isNaN(this.msd) && !target.msdSent) {
-			item.msd = this.msd;
-			target.msdSent = true;
+		const { transform } = config;
+		if (!transform) {
+			this.queueTargetEvent(session, target, config, item, type);
+			return;
 		}
-		target.queue.push(item);
+		copyReportValues(item);
+		const requiredKey = CMCD_REQUIRED_EVENT_KEYS.get(type);
+		const requiredValue = requiredKey ? item[requiredKey] : void 0;
+		const ts = item.ts;
+		const report = transform(item, request);
+		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(session, target, config, report, type);
+	}
+	/**
+	* 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`, 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(session, target, config, report, type) {
+		report.e = type;
+		report.sn = target.sn++;
+		report.sid = session.sid;
+		if (!isNaN(session.msd) && !target.msdSent && config.enabledKeys?.includes("msd")) {
+			report.msd = session.msd;
+			target.msdSent = true;
+		} 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
@@ -1756,14 +2086,57 @@ var CmcdReporter = class {
 	* Additional keys like `ttfbb`, `cmsdd`, `cmsds`, and `smrt` can be
 	* supplied via the `data` parameter if the player has access to them.
 	*
+	* 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 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 = {
@@ -1778,12 +2151,26 @@ var CmcdReporter = class {
 			}
 			if (timing.duration != null) derived.ttlb = Math.round(timing.duration);
 		}
-		const cmcd = request.customData?.cmcd ?? {};
-		this.recordEvent(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
@@ -1806,9 +2193,45 @@ 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.
 	*
+	* A reporter given a concrete `C` requires the request's `customData` to
+	* satisfy it, so a request the configured transform could not read is
+	* rejected here rather than reaching it; see
+	* {@link CmcdReporterCustomData}.
+	*
+	* @typeParam R - The request being decorated. Its `customData` must satisfy
+	*                the reporter's `C`.
+	*
 	* @param request - The request to apply the CMCD request report to.
 	* @param data - The data to apply to the request. This data only
 	*               applies to this request report. Persistent data
@@ -1822,27 +2245,38 @@ 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 url = new URL(report.url);
-		const cmcdData = {
-			...this.data,
+		const session = this.session;
+		const merged = {
+			...session.data,
 			...data,
-			sn: this.requestTarget.sn++
+			sid: session.sid
 		};
-		const options = createEncodingOptions(CMCD_REQUEST_MODE, this.config, report.url);
-		if (!isNaN(this.msd) && !this.requestTarget.msdSent) {
-			cmcdData.msd = this.msd;
-			this.requestTarget.msdSent = true;
+		const { transform } = this.config;
+		let cmcdData = merged;
+		if (transform) {
+			copyReportValues(merged);
+			cmcdData = transform(merged, request);
+			if (cmcdData == null) return report;
 		}
-		const cmcd = report.customData.cmcd = prepareCmcdData(cmcdData, options);
+		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 = 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;
@@ -1859,16 +2293,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();
 	}
@@ -1876,44 +2313,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).
-	*/
-	disarmInterval(target) {
-		clearInterval(target.intervalId);
-		target.intervalId = void 0;
-	}
-	/**
-	* 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).
+	* 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).
 	*/
-	disposeEventTarget(config) {
-		const target = this.eventTargets.get(config);
-		if (!target) return;
-		this.disarmInterval(target);
-		this.eventTargets.delete(config);
+	disarmInterval(config) {
+		clearInterval(this.intervals.get(config));
+		this.intervals.delete(config);
 	}
 	/**
-	* Resets the session related data. Called when the session ID changes.
+	* 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.
 	*/
-	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);
+		});
 	}
 };
 
@@ -1976,51 +2411,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
 /**
@@ -2941,5 +3331,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