@hot-updater/plugin-insights 1.0.0-rc.35 → 1.0.0-rc.37

package/dist/server/recordEvent.cjs

@@ -1,6 +1,7 @@
+const require_eventRow = require("./eventRow.cjs");
+const require_schema = require("./schema.cjs");
 const require_contract = require("./contract.cjs");
 const require_overview = require("./overview.cjs");
-const require_schema = require("./schema.cjs");
 let _hot_updater_plugin_core = require("@hot-updater/plugin-core");
 //#region src/server/recordEvent.ts
 const hourOf = (ms) => ms - ms % require_schema.HOUR_MS;
@@ -13,13 +14,16 @@ const insightsIdentity = (identity) => require_overview.insightsOverviewId({
 	bucketStartMs: 0
 });
 /**
-* The bucket a head's gauges count it in, the UTC day of its event, and the
-* release its distribution row names: the one it runs, which a download
-* leaves at its source.
+* The bucket a head's gauges count it in, the UTC day of its event, and what
+* its distribution row names: the release it runs, which a download leaves
+* at its source, and the built-in bundle, when it runs the native build's.
+* A head stored without the built-in bundle ID counts in no built-in row, so
+* taking it back moves none.
 */
 const gaugeSlot = (head) => ({
 	bucket: dayOf(head.received_at_ms),
-	releaseId: head.type === "UPDATE_DOWNLOADED" ? head.from_release_id : head.to_release_id
+	releaseId: head.type === "UPDATE_DOWNLOADED" ? head.from_release_id : head.to_release_id,
+	builtinBundleId: require_eventRow.runningBuiltinBundleId(head)
 });
 /**
 * The `insights_latest_by_bundle` field of a head's (from, to) pair. A head
@@ -30,11 +34,12 @@ const PAIR_FIELD = "from_to";
 /** The pair gauge's `bundle_id`: a hash of the two bundle ids, which fit no single 36-character column. */
 const bundlePairKey = (from, to) => require_overview.insightsKey(`${from.length}:${from}${to.length}:${to}`);
 /**
-* Moves a head's gauges: the distribution row, one row per bundle it
-* references, and its pair; -1 takes back the head an event replaces.
+* Moves a head's gauges: the distribution row, and the built-in one when it
+* runs its build's built-in bundle, one row per bundle it references, and
+* its pair; -1 takes back the head an event replaces.
 */
 const countHead = (tx, head, delta) => {
-	const { bucket, releaseId } = gaugeSlot(head);
+	const { bucket, releaseId, builtinBundleId } = gaugeSlot(head);
 	const shardBy = head.install_id;
 	tx.aggregate("insights_distribution", {
 		channel: head.channel,
@@ -43,6 +48,14 @@ const countHead = (tx, head, delta) => {
 		release_id: releaseId ?? "",
 		bucket_start_ms: bucket
 	}, { latest_installations: delta }, { shardBy });
+	if (builtinBundleId !== null) tx.aggregate("insights_builtin_distribution", {
+		channel: head.channel,
+		platform: head.platform,
+		app_version: head.app_version,
+		release_id: releaseId ?? "",
+		builtin_bundle_id: builtinBundleId,
+		bucket_start_ms: bucket
+	}, { latest_installations: delta }, { shardBy });
 	for (const field of ["from_bundle_id", "to_bundle_id"]) {
 		const bundleId = head[field];
 		if (bundleId === null) continue;
@@ -123,16 +136,16 @@ const countEvent = (tx, event) => {
 	}
 };
 /**
-* A stored event's outcome rows: its bundle filter's hour, which a failed
-* check has none of, and every stored event's UTC day.
+* A stored event's outcome rows: its bundle filter's hour, when it has one
+* (`bundleRefsOf`), and every stored event's UTC day.
 */
 const countOutcome = (tx, event) => {
 	const shardBy = event.install_id;
-	if (!require_schema.isFailedCheck(event)) tx.aggregate("insights_outcomes", {
+	for (const bundleRef of require_schema.bundleRefsOf(event)) tx.aggregate("insights_outcomes", {
 		platform: event.platform,
 		channel: event.channel,
 		type: event.type,
-		bundle_ref: event.type === "RECOVERED" ? `from:${event.from_bundle_id}` : `to:${event.to_bundle_id}`,
+		bundle_ref: bundleRef,
 		bucket_start_ms: hourOf(event.received_at_ms)
 	}, { events: 1 }, { shardBy });
 	tx.aggregate("insights_outcomes", {
@@ -236,6 +249,126 @@ const countFailure = (tx, event) => {
 	}, { events: 1 }, { shardBy });
 };
 const isNewer = (event, head) => event.received_at_ms !== head.received_at_ms ? event.received_at_ms > head.received_at_ms : (0, _hot_updater_plugin_core.compareUtf8)(event.id, head.id) > 0;
+/** What a head says its installation runs: a download leaves it at the source. */
+const runningOf = (head) => head.type === "UPDATE_DOWNLOADED" ? {
+	bundle_id: head.from_bundle_id,
+	release_id: head.from_release_id
+} : {
+	bundle_id: head.to_bundle_id,
+	release_id: head.to_release_id
+};
+/** The native build a report or head came from, when its SDK says. */
+const minBundleIdOf = (row) => row.metadata?.min_bundle_id;
+/** When the client made a report, from the UUIDv7 it gave it. */
+const madeAt = (id) => (0, _hot_updater_plugin_core.isUUIDv7)(id) ? (0, _hot_updater_plugin_core.extractTimestampFromUUIDv7)(id) : null;
+/**
+* A report that arrived after its installation moved past it: a download or
+* an apply of the bundle the head already runs, or an UNCHANGED report of the
+* bundle an apply head left, made before that apply. A reload can cut one
+* runtime's report short and deliver it after the next runtime's. It stays
+* in history but moves and counts nothing.
+*/
+const isLate = (event, head) => {
+	if (head === null) return false;
+	if (event.type === "UPDATE_DOWNLOADED" || event.type === "UPDATE_APPLIED") return event.to_bundle_id === runningOf(head).bundle_id;
+	if (event.type === "UNCHANGED" && head.type === "UPDATE_APPLIED" && event.to_bundle_id === head.from_bundle_id) {
+		const made = madeAt(event.id);
+		const applied = madeAt(head.id);
+		return made !== null && applied !== null && made < applied;
+	}
+	return false;
+};
+/**
+* What an UNCHANGED report changes against its installation's head: the
+* running bundle or release, the app version, the channel, or the native
+* build (when both name it), with the head's values before it; `first_seen`
+* when the installation has no head. A report the head already answers, one
+* older than the head, a user switch and any other event type change
+* nothing, so no row keeps them.
+*/
+const changeOf = (event, head) => {
+	if (event.type !== "UNCHANGED") return null;
+	if (head === null) return {
+		kinds: ["first_seen"],
+		previous: null
+	};
+	if (!isNewer(event, head)) return null;
+	const running = runningOf(head);
+	const build = minBundleIdOf(event);
+	const headBuild = minBundleIdOf(head);
+	const kinds = [];
+	if (event.to_bundle_id !== running.bundle_id) kinds.push("bundle");
+	if (event.to_release_id !== running.release_id) kinds.push("release");
+	if (event.app_version !== head.app_version) kinds.push("app_version");
+	if (event.channel !== head.channel) kinds.push("channel");
+	if (build !== void 0 && headBuild !== void 0 && build !== headBuild) kinds.push("native_build");
+	return kinds.length === 0 ? null : {
+		kinds,
+		previous: {
+			bundle_id: running.bundle_id,
+			release_id: running.release_id,
+			app_version: head.app_version,
+			channel: head.channel,
+			...headBuild === void 0 ? {} : { min_bundle_id: headBuild }
+		}
+	};
+};
+/**
+* Whether a launch or a crash comes with no download report for its target:
+* its head shows neither that download nor the target already running. The
+* native build's built-in bundle is never downloaded, and without a head the
+* server knows nothing of the installation's past, so it implies nothing.
+*/
+const impliesDownload = (event, head) => {
+	const target = event.type === "RECOVERED" ? {
+		bundle: event.from_bundle_id,
+		release: event.from_release_id
+	} : require_schema.isLaunch(event) ? {
+		bundle: event.to_bundle_id,
+		release: event.to_release_id
+	} : null;
+	if (target === null || target.release === null || target.bundle === minBundleIdOf(event)) return false;
+	if (head === null) return false;
+	if (head.type === "UPDATE_DOWNLOADED" && head.to_bundle_id === target.bundle) return false;
+	return runningOf(head).bundle_id !== target.bundle;
+};
+/**
+* The event as recorded, with what only the server sets: what a kept
+* UNCHANGED report changed, a late report's flag, and a download its launch
+* or crash implied.
+*/
+const recordedOf = (event, head) => {
+	const { change: _change, late: _late, implied_download: _implied, ...metadata } = event.metadata;
+	const reported = {
+		...event,
+		metadata
+	};
+	const late = isLate(reported, head);
+	const change = late ? null : changeOf(reported, head);
+	const withChange = change === null ? reported : {
+		...reported,
+		metadata: {
+			...metadata,
+			change
+		}
+	};
+	return {
+		recorded: late && reported.type !== "UNCHANGED" ? {
+			...reported,
+			metadata: {
+				...metadata,
+				late: true
+			}
+		} : !late && impliesDownload(withChange, head) ? {
+			...withChange,
+			metadata: {
+				...withChange.metadata,
+				implied_download: true
+			}
+		} : withChange,
+		late
+	};
+};
 /** What an UNCHANGED report must share with its installation's head to repeat it. */
 const REPEATED_FIELDS = [
 	"channel",
@@ -270,23 +403,24 @@ const recordEvent = (db, event) => {
 		const [existing, previous] = await Promise.all([tx.findOne("bundle_events", { id: event.id }), tx.findOne("bundle_event_heads", { install_id: event.install_id })]);
 		if (existing !== null || previous?.id === event.id) return;
 		if (previous !== null && repeatsHead(event, previous)) return;
-		if (event.type !== "UNCHANGED") {
-			tx.create("bundle_events", event);
-			countOutcome(tx, event);
+		const { recorded, late } = recordedOf(event, previous);
+		if (recorded.type !== "UNCHANGED" || recorded.metadata.change !== void 0 && !late) {
+			tx.create("bundle_events", recorded);
+			countOutcome(tx, recorded);
 		}
-		if (event.type === "UPDATE_FAILED") {
-			countFailure(tx, event);
+		if (recorded.type === "UPDATE_FAILED") {
+			countFailure(tx, recorded);
 			return;
 		}
-		countEvent(tx, event);
-		if (previous !== null && !isNewer(event, previous)) return;
-		if (previous === null) tx.create("bundle_event_heads", event);
+		countEvent(tx, recorded);
+		if (previous !== null && (late || !isNewer(recorded, previous))) return;
+		if (previous === null) tx.create("bundle_event_heads", recorded);
 		else {
-			const { install_id: _, ...fields } = event;
+			const { install_id: _, ...fields } = recorded;
 			countHead(tx, previous, -1);
 			tx.update("bundle_event_heads", previous, fields);
 		}
-		countHead(tx, event, 1);
+		countHead(tx, recorded, 1);
 	});
 };
 //#endregion

package/dist/server/recordEvent.mjs

@@ -1,7 +1,8 @@
+import { runningBuiltinBundleId } from "./eventRow.mjs";
+import { DAILY_EVENTS, DAY_MS, HOUR_MS, bundleRefsOf, isLaunch } from "./schema.mjs";
 import { assertBundleEventRow } from "./contract.mjs";
 import { insightsKey, insightsOverviewDeltas, insightsOverviewId } from "./overview.mjs";
-import { DAILY_EVENTS, DAY_MS, HOUR_MS, isFailedCheck } from "./schema.mjs";
-import { addDistinct, compareUtf8 } from "@hot-updater/plugin-core";
+import { addDistinct, compareUtf8, extractTimestampFromUUIDv7, isUUIDv7 } from "@hot-updater/plugin-core";
 //#region src/server/recordEvent.ts
 const hourOf = (ms) => ms - ms % HOUR_MS;
 const dayOf = (ms) => ms - ms % DAY_MS;
@@ -13,13 +14,16 @@ const insightsIdentity = (identity) => insightsOverviewId({
 	bucketStartMs: 0
 });
 /**
-* The bucket a head's gauges count it in, the UTC day of its event, and the
-* release its distribution row names: the one it runs, which a download
-* leaves at its source.
+* The bucket a head's gauges count it in, the UTC day of its event, and what
+* its distribution row names: the release it runs, which a download leaves
+* at its source, and the built-in bundle, when it runs the native build's.
+* A head stored without the built-in bundle ID counts in no built-in row, so
+* taking it back moves none.
 */
 const gaugeSlot = (head) => ({
 	bucket: dayOf(head.received_at_ms),
-	releaseId: head.type === "UPDATE_DOWNLOADED" ? head.from_release_id : head.to_release_id
+	releaseId: head.type === "UPDATE_DOWNLOADED" ? head.from_release_id : head.to_release_id,
+	builtinBundleId: runningBuiltinBundleId(head)
 });
 /**
 * The `insights_latest_by_bundle` field of a head's (from, to) pair. A head
@@ -30,11 +34,12 @@ const PAIR_FIELD = "from_to";
 /** The pair gauge's `bundle_id`: a hash of the two bundle ids, which fit no single 36-character column. */
 const bundlePairKey = (from, to) => insightsKey(`${from.length}:${from}${to.length}:${to}`);
 /**
-* Moves a head's gauges: the distribution row, one row per bundle it
-* references, and its pair; -1 takes back the head an event replaces.
+* Moves a head's gauges: the distribution row, and the built-in one when it
+* runs its build's built-in bundle, one row per bundle it references, and
+* its pair; -1 takes back the head an event replaces.
 */
 const countHead = (tx, head, delta) => {
-	const { bucket, releaseId } = gaugeSlot(head);
+	const { bucket, releaseId, builtinBundleId } = gaugeSlot(head);
 	const shardBy = head.install_id;
 	tx.aggregate("insights_distribution", {
 		channel: head.channel,
@@ -43,6 +48,14 @@ const countHead = (tx, head, delta) => {
 		release_id: releaseId ?? "",
 		bucket_start_ms: bucket
 	}, { latest_installations: delta }, { shardBy });
+	if (builtinBundleId !== null) tx.aggregate("insights_builtin_distribution", {
+		channel: head.channel,
+		platform: head.platform,
+		app_version: head.app_version,
+		release_id: releaseId ?? "",
+		builtin_bundle_id: builtinBundleId,
+		bucket_start_ms: bucket
+	}, { latest_installations: delta }, { shardBy });
 	for (const field of ["from_bundle_id", "to_bundle_id"]) {
 		const bundleId = head[field];
 		if (bundleId === null) continue;
@@ -123,16 +136,16 @@ const countEvent = (tx, event) => {
 	}
 };
 /**
-* A stored event's outcome rows: its bundle filter's hour, which a failed
-* check has none of, and every stored event's UTC day.
+* A stored event's outcome rows: its bundle filter's hour, when it has one
+* (`bundleRefsOf`), and every stored event's UTC day.
 */
 const countOutcome = (tx, event) => {
 	const shardBy = event.install_id;
-	if (!isFailedCheck(event)) tx.aggregate("insights_outcomes", {
+	for (const bundleRef of bundleRefsOf(event)) tx.aggregate("insights_outcomes", {
 		platform: event.platform,
 		channel: event.channel,
 		type: event.type,
-		bundle_ref: event.type === "RECOVERED" ? `from:${event.from_bundle_id}` : `to:${event.to_bundle_id}`,
+		bundle_ref: bundleRef,
 		bucket_start_ms: hourOf(event.received_at_ms)
 	}, { events: 1 }, { shardBy });
 	tx.aggregate("insights_outcomes", {
@@ -236,6 +249,126 @@ const countFailure = (tx, event) => {
 	}, { events: 1 }, { shardBy });
 };
 const isNewer = (event, head) => event.received_at_ms !== head.received_at_ms ? event.received_at_ms > head.received_at_ms : compareUtf8(event.id, head.id) > 0;
+/** What a head says its installation runs: a download leaves it at the source. */
+const runningOf = (head) => head.type === "UPDATE_DOWNLOADED" ? {
+	bundle_id: head.from_bundle_id,
+	release_id: head.from_release_id
+} : {
+	bundle_id: head.to_bundle_id,
+	release_id: head.to_release_id
+};
+/** The native build a report or head came from, when its SDK says. */
+const minBundleIdOf = (row) => row.metadata?.min_bundle_id;
+/** When the client made a report, from the UUIDv7 it gave it. */
+const madeAt = (id) => isUUIDv7(id) ? extractTimestampFromUUIDv7(id) : null;
+/**
+* A report that arrived after its installation moved past it: a download or
+* an apply of the bundle the head already runs, or an UNCHANGED report of the
+* bundle an apply head left, made before that apply. A reload can cut one
+* runtime's report short and deliver it after the next runtime's. It stays
+* in history but moves and counts nothing.
+*/
+const isLate = (event, head) => {
+	if (head === null) return false;
+	if (event.type === "UPDATE_DOWNLOADED" || event.type === "UPDATE_APPLIED") return event.to_bundle_id === runningOf(head).bundle_id;
+	if (event.type === "UNCHANGED" && head.type === "UPDATE_APPLIED" && event.to_bundle_id === head.from_bundle_id) {
+		const made = madeAt(event.id);
+		const applied = madeAt(head.id);
+		return made !== null && applied !== null && made < applied;
+	}
+	return false;
+};
+/**
+* What an UNCHANGED report changes against its installation's head: the
+* running bundle or release, the app version, the channel, or the native
+* build (when both name it), with the head's values before it; `first_seen`
+* when the installation has no head. A report the head already answers, one
+* older than the head, a user switch and any other event type change
+* nothing, so no row keeps them.
+*/
+const changeOf = (event, head) => {
+	if (event.type !== "UNCHANGED") return null;
+	if (head === null) return {
+		kinds: ["first_seen"],
+		previous: null
+	};
+	if (!isNewer(event, head)) return null;
+	const running = runningOf(head);
+	const build = minBundleIdOf(event);
+	const headBuild = minBundleIdOf(head);
+	const kinds = [];
+	if (event.to_bundle_id !== running.bundle_id) kinds.push("bundle");
+	if (event.to_release_id !== running.release_id) kinds.push("release");
+	if (event.app_version !== head.app_version) kinds.push("app_version");
+	if (event.channel !== head.channel) kinds.push("channel");
+	if (build !== void 0 && headBuild !== void 0 && build !== headBuild) kinds.push("native_build");
+	return kinds.length === 0 ? null : {
+		kinds,
+		previous: {
+			bundle_id: running.bundle_id,
+			release_id: running.release_id,
+			app_version: head.app_version,
+			channel: head.channel,
+			...headBuild === void 0 ? {} : { min_bundle_id: headBuild }
+		}
+	};
+};
+/**
+* Whether a launch or a crash comes with no download report for its target:
+* its head shows neither that download nor the target already running. The
+* native build's built-in bundle is never downloaded, and without a head the
+* server knows nothing of the installation's past, so it implies nothing.
+*/
+const impliesDownload = (event, head) => {
+	const target = event.type === "RECOVERED" ? {
+		bundle: event.from_bundle_id,
+		release: event.from_release_id
+	} : isLaunch(event) ? {
+		bundle: event.to_bundle_id,
+		release: event.to_release_id
+	} : null;
+	if (target === null || target.release === null || target.bundle === minBundleIdOf(event)) return false;
+	if (head === null) return false;
+	if (head.type === "UPDATE_DOWNLOADED" && head.to_bundle_id === target.bundle) return false;
+	return runningOf(head).bundle_id !== target.bundle;
+};
+/**
+* The event as recorded, with what only the server sets: what a kept
+* UNCHANGED report changed, a late report's flag, and a download its launch
+* or crash implied.
+*/
+const recordedOf = (event, head) => {
+	const { change: _change, late: _late, implied_download: _implied, ...metadata } = event.metadata;
+	const reported = {
+		...event,
+		metadata
+	};
+	const late = isLate(reported, head);
+	const change = late ? null : changeOf(reported, head);
+	const withChange = change === null ? reported : {
+		...reported,
+		metadata: {
+			...metadata,
+			change
+		}
+	};
+	return {
+		recorded: late && reported.type !== "UNCHANGED" ? {
+			...reported,
+			metadata: {
+				...metadata,
+				late: true
+			}
+		} : !late && impliesDownload(withChange, head) ? {
+			...withChange,
+			metadata: {
+				...withChange.metadata,
+				implied_download: true
+			}
+		} : withChange,
+		late
+	};
+};
 /** What an UNCHANGED report must share with its installation's head to repeat it. */
 const REPEATED_FIELDS = [
 	"channel",
@@ -270,23 +403,24 @@ const recordEvent = (db, event) => {
 		const [existing, previous] = await Promise.all([tx.findOne("bundle_events", { id: event.id }), tx.findOne("bundle_event_heads", { install_id: event.install_id })]);
 		if (existing !== null || previous?.id === event.id) return;
 		if (previous !== null && repeatsHead(event, previous)) return;
-		if (event.type !== "UNCHANGED") {
-			tx.create("bundle_events", event);
-			countOutcome(tx, event);
+		const { recorded, late } = recordedOf(event, previous);
+		if (recorded.type !== "UNCHANGED" || recorded.metadata.change !== void 0 && !late) {
+			tx.create("bundle_events", recorded);
+			countOutcome(tx, recorded);
 		}
-		if (event.type === "UPDATE_FAILED") {
-			countFailure(tx, event);
+		if (recorded.type === "UPDATE_FAILED") {
+			countFailure(tx, recorded);
 			return;
 		}
-		countEvent(tx, event);
-		if (previous !== null && !isNewer(event, previous)) return;
-		if (previous === null) tx.create("bundle_event_heads", event);
+		countEvent(tx, recorded);
+		if (previous !== null && (late || !isNewer(recorded, previous))) return;
+		if (previous === null) tx.create("bundle_event_heads", recorded);
 		else {
-			const { install_id: _, ...fields } = event;
+			const { install_id: _, ...fields } = recorded;
 			countHead(tx, previous, -1);
 			tx.update("bundle_event_heads", previous, fields);
 		}
-		countHead(tx, event, 1);
+		countHead(tx, recorded, 1);
 	});
 };
 //#endregion

package/dist/server/schema.cjs

@@ -10,18 +10,53 @@ const bucketRetention = (days) => ({
 	field: "bucket_start_ms",
 	days
 });
+/** Every kind of row the table keeps belongs in installation history. */
 const MOVEMENTS = /* @__PURE__ */ new Set([
 	"UPDATE_DOWNLOADED",
 	"UPDATE_APPLIED",
 	"RECOVERED",
-	"UPDATE_FAILED"
+	"UPDATE_FAILED",
+	"UNCHANGED"
 ]);
 /** A failed update check: it names no target bundle, so no bundle list shows it. */
 const isFailedCheck = (row) => row.type === "UPDATE_FAILED" && row.metadata?.failure?.stage === "check";
+const metadataOf = (row) => row.metadata ?? {};
+/** A download or apply that arrived after its target ran: it counts nothing. */
+const isLateEvent = (row) => metadataOf(row).late === true;
 /**
-* Downloads, applies, recoveries, and update failures, whole. An UNCHANGED
-* report counts as a launch and moves its installation's head, but no list
-* shows it, so no row keeps it.
+* Whether a stored row launched its installation into a bundle release: an
+* apply, or a kept UNCHANGED row that moved the installation to another
+* bundle of a release, as when the apply report never arrived or a rollback
+* to the built-in bundle took it there. A first report, a release change of
+* the bundle already running, and a late row launch nothing.
+*/
+const isLaunch = (row) => {
+	if (isLateEvent(row)) return false;
+	if (row.type === "UPDATE_APPLIED") return true;
+	if (row.type !== "UNCHANGED") return false;
+	const kinds = metadataOf(row).change?.kinds ?? [];
+	return kinds.includes("bundle") && !kinds.includes("first_seen") && row.to_release_id !== null;
+};
+/**
+* The bundle a stored row's bundle filter matches: `from:<bundle>` for a
+* recovery; `to:<bundle>` for a download, an apply, and an update failure;
+* `on:<bundle>` for an UNCHANGED row that launched a bundle (`isLaunch`), a
+* key no other row uses. None for a failed check, which targets no bundle, a
+* late row, or any other UNCHANGED row.
+*/
+const bundleRefsOf = (row) => {
+	if (isFailedCheck(row) || isLateEvent(row)) return [];
+	if (row.type === "RECOVERED") return [`from:${row.from_bundle_id}`];
+	if (row.type === "UNCHANGED") return isLaunch(row) ? [`on:${row.to_bundle_id}`] : [];
+	return [`to:${row.to_bundle_id}`];
+};
+/** The key a bundle filter reads, as `bundleRefsOf` writes it. */
+const bundleRefOfFilter = (filter) => filter.type === "RECOVERED" ? `from:${filter.fromBundleId}` : filter.type === "UNCHANGED" ? `on:${filter.toBundleId}` : `to:${filter.toBundleId}`;
+/**
+* Downloads, applies, recoveries, update failures, and the UNCHANGED
+* reports that changed what their installation runs, whole. An UNCHANGED
+* report that changes nothing counts as a launch and moves its
+* installation's head, but no row keeps it.
 */
 const bundleEvents = (days) => (0, _hot_updater_plugin_core.defineTable)({
 	id: {
@@ -76,19 +111,16 @@ const bundleEvents = (days) => (0, _hot_updater_plugin_core.defineTable)({
 			type: "integer",
 			compute: (row) => row.received_at_ms - row.received_at_ms % DAY_MS
 		},
-		/** Set only for events that belong in installation history. */
+		/** Every stored event belongs in installation history. */
 		movement_install_id: {
 			type: "string",
 			compute: (row) => MOVEMENTS.has(row.type) ? row.install_id : null
 		},
-		/**
-		* The bundle a bundle filter matches: `from:<bundle>` for RECOVERED,
-		* none for a failed check, else `to:<bundle>`.
-		*/
+		/** The bundle a bundle filter matches (`bundleRefsOf`). */
 		bundle_ref: {
 			type: "string",
 			multi: true,
-			compute: (row) => isFailedCheck(row) ? [] : [row.type === "RECOVERED" && row.from_bundle_id !== null ? `from:${row.from_bundle_id}` : `to:${row.to_bundle_id}`]
+			compute: (row) => bundleRefsOf(row)
 		}
 	},
 	indexes: {
@@ -354,6 +386,55 @@ const insightsDistribution = (retention) => (0, _hot_updater_plugin_core.defineA
 	},
 	retention
 });
+/**
+* The installations of `insights_distribution` that run their native build's
+* built-in bundle, by its ID (`builtin_bundle_id`), within the same rows:
+* reads move them out of the row of their release, or of no release.
+*/
+const insightsBuiltinDistribution = (retention) => (0, _hot_updater_plugin_core.defineAggregate)({
+	channel: { type: "string" },
+	platform: {
+		type: "string",
+		maxLength: 16
+	},
+	app_version: { type: "string" },
+	release_id: {
+		type: "string",
+		maxLength: 36
+	},
+	builtin_bundle_id: {
+		type: "string",
+		maxLength: 36
+	},
+	bucket_start_ms: { type: "integer" }
+}, {
+	key: [
+		"channel",
+		"platform",
+		"app_version",
+		"release_id",
+		"builtin_bundle_id",
+		"bucket_start_ms"
+	],
+	gauges: ["latest_installations"],
+	shards: GAUGE_SHARDS,
+	batched: true,
+	indexes: {
+		byScope: {
+			eq: ["channel", "platform"],
+			sort: ["bucket_start_ms"]
+		},
+		byVersion: {
+			eq: [
+				"channel",
+				"platform",
+				"app_version"
+			],
+			sort: ["bucket_start_ms"]
+		}
+	},
+	retention
+});
 /** Latest events by the bundle they came from or went to, bucketed like the distribution. */
 const insightsLatestByBundle = (retention) => (0, _hot_updater_plugin_core.defineAggregate)({
 	platform: {
@@ -473,6 +554,7 @@ const createInsightsSchema = ({ rawDays, dailyDays } = DEFAULT_INSIGHTS_RETENTIO
 		insights_overview_lifetime: lifetimeCounters(),
 		insights_sketches_lifetime: lifetimeSketches(),
 		insights_distribution: insightsDistribution(daily),
+		insights_builtin_distribution: insightsBuiltinDistribution(daily),
 		insights_latest_by_bundle: insightsLatestByBundle(daily),
 		insights_outcomes: insightsOutcomes(hourly),
 		insights_failures: insightsFailures(hourly)
@@ -484,6 +566,10 @@ exports.DAILY_EVENTS = DAILY_EVENTS;
 exports.DAY_MS = DAY_MS;
 exports.DEFAULT_INSIGHTS_RETENTION = DEFAULT_INSIGHTS_RETENTION;
 exports.HOUR_MS = HOUR_MS;
+exports.bundleRefOfFilter = bundleRefOfFilter;
+exports.bundleRefsOf = bundleRefsOf;
 exports.createInsightsSchema = createInsightsSchema;
 exports.insightsSchema = insightsSchema;
 exports.isFailedCheck = isFailedCheck;
+exports.isLateEvent = isLateEvent;
+exports.isLaunch = isLaunch;