@hot-updater/test-utils 1.0.0-rc.15

package/dist/index.mjs

@@ -0,0 +1,3569 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { NIL_UUID, createReleaseCatalogScopeKey, encodeChannelKey, selectDesiredRelease } from "@hot-updater/core";
+import { DatabaseAdapterContractError, createMemoryAdapter, findPhysicalIndex, indexOrderTuple, verifyAdapter } from "@hot-updater/plugin-core/internal";
+import { createServer } from "node:http";
+//#region src/adminApiTestClient.ts
+const jsonRequest = (method, body) => ({
+	method,
+	headers: { "content-type": "application/json" },
+	...body === void 0 ? {} : { body: JSON.stringify(body) }
+});
+/** A bundle row as the deploy route takes it. */
+const toDeployBundle = (row) => ({
+	id: row.id,
+	platform: row.platform,
+	gitCommitHash: row.git_commit_hash,
+	manifestStorageUri: row.manifest_storage_uri,
+	manifestFileHash: row.manifest_file_hash,
+	assetBaseStorageUri: row.asset_base_storage_uri,
+	...row.metadata === null ? {} : { metadata: row.metadata }
+});
+/**
+* Admin API protocol 2 over a test client. Each JSON call checks the answer
+* is private and names the request when it fails. `track` records what a
+* test wrote, and `cleanup` deletes it again: its releases, then its
+* bundles, newest first.
+*/
+const createAdminApiTestClient = (getClient) => {
+	const admin = (path, init) => getClient().admin(path, init);
+	const adminJson = async (path, init) => {
+		const response = await admin(path, init);
+		const text = await response.text();
+		expect(response.ok, `${init?.method ?? "GET"} ${path}: ${text}`).toBe(true);
+		expect(response.headers.get("cache-control")).toBe("private, no-store");
+		return text === "" ? void 0 : JSON.parse(text);
+	};
+	const releases = [];
+	const bundles = [];
+	/** One deployment through `POST /releases`: a new bundle, or a stored one's id. */
+	const deploy = async (deployment) => {
+		const { data } = await adminJson("/releases", jsonRequest("POST", { deployments: [deployment] }));
+		const release = data[0]?.release;
+		if (!release) throw new Error("The deploy answered no release.");
+		releases.push(release.id);
+		if ("bundle" in deployment) bundles.push(deployment.bundle.id);
+		return release;
+	};
+	const ensureChannel = async (name) => (await adminJson("/channels", jsonRequest("POST", { name }))).data;
+	/** Hard-deletes a release: disabled first, as the route requires. */
+	const removeRelease = async (id) => {
+		const current = await admin(`/releases/${encodeURIComponent(id)}`);
+		if (current.status === 404) {
+			await current.text();
+			return;
+		}
+		const { data: row } = await current.json();
+		if (row.enabled) await adminJson(`/releases/${encodeURIComponent(id)}`, jsonRequest("PATCH", { patch: { enabled: false } }));
+		await adminJson(`/releases/${encodeURIComponent(id)}?confirm=${encodeURIComponent(id)}`, jsonRequest("DELETE"));
+	};
+	const cleanup = async () => {
+		for (const id of releases.splice(0).reverse()) await removeRelease(id);
+		for (const id of bundles.splice(0).reverse()) await adminJson("/bundles/delete", jsonRequest("POST", { ids: [id] }));
+	};
+	return {
+		admin,
+		adminJson,
+		deploy,
+		ensureChannel,
+		removeRelease,
+		/** Tracks a release the server wrote for a test, such as a promotion's copy. */
+		track: (releaseId) => {
+			releases.push(releaseId);
+		},
+		/** Stops tracking a release a test already deleted. */
+		forget: (releaseId) => {
+			const index = releases.indexOf(releaseId);
+			if (index >= 0) releases.splice(index, 1);
+		},
+		cleanup
+	};
+};
+//#endregion
+//#region src/databaseTestFixtures.ts
+const fixtureId = (suffix) => `00000000-0000-7000-8000-${suffix.padStart(12, "0")}`;
+const createBundleRowFixture = (suffix, _channel = "production") => ({
+	id: fixtureId(suffix),
+	platform: "ios",
+	git_commit_hash: null,
+	metadata: { app_version: suffix },
+	manifest_storage_uri: `storage://bundles/${suffix}/manifest.json`,
+	manifest_file_hash: `manifest-hash-${suffix}`,
+	asset_base_storage_uri: "storage://assets"
+});
+const createBundlePatchRowFixture = (suffix, bundleId, baseBundleId, orderIndex = 0) => ({
+	id: `patch-${suffix}`,
+	bundle_id: bundleId,
+	base_bundle_id: baseBundleId,
+	base_file_hash: `base-hash-${suffix}`,
+	patch_file_hash: `patch-hash-${suffix}`,
+	patch_storage_uri: `storage://patches/${suffix}.patch`,
+	byte_size: 3000000002,
+	order_index: orderIndex
+});
+const createBundleEventRowFixture = (suffix, receivedAtMs) => ({
+	id: fixtureId(suffix),
+	type: "UPDATE_APPLIED",
+	install_id: `install-${suffix}`,
+	user_id: null,
+	metadata: {
+		username: null,
+		cohort: "0",
+		update_strategy: "appVersion",
+		fingerprint_hash: null,
+		sdk_version: null
+	},
+	from_bundle_id: fixtureId(`${Number(suffix) + 1e3}`),
+	from_release_id: null,
+	to_bundle_id: fixtureId(`${Number(suffix) + 2e3}`),
+	to_release_id: null,
+	platform: "ios",
+	app_version: "1.0.0",
+	channel: "production",
+	received_at_ms: receivedAtMs
+});
+const createBundleFixture = (suffix, _channel = "production") => ({
+	id: fixtureId(suffix),
+	platform: "ios",
+	gitCommitHash: null,
+	metadata: { app_version: suffix },
+	manifestStorageUri: `storage://bundles/${suffix}/manifest.json`,
+	manifestFileHash: `manifest-hash-${suffix}`,
+	assetBaseStorageUri: "storage://assets"
+});
+//#endregion
+//#region src/setupBundleMethodsTestSuite.ts
+/**
+* Bundles through admin API protocol 2: deployed with a release, read by
+* id, paged by key, changed, and deleted. Each test deletes what it wrote.
+*/
+const setupBundleMethodsTestSuite = (options) => {
+	describe("Bundle admin API", () => {
+		const api = createAdminApiTestClient(options.getClient);
+		const { admin, adminJson } = api;
+		let namespace;
+		beforeEach(() => {
+			namespace = crypto.randomUUID();
+		});
+		afterEach(async () => {
+			await api.cleanup();
+		});
+		/** A bundle id unique to the test, ordered by suffix. */
+		const bundleRow = (suffix, platform = "ios") => ({
+			...createBundleRowFixture(suffix),
+			id: `${namespace.slice(0, 8)}-0000-7000-8000-${suffix.padStart(12, "0")}`,
+			platform
+		});
+		const deploy = (row) => api.deploy({
+			bundle: toDeployBundle(row),
+			release: {
+				channel: `bundles-${namespace}`,
+				enabled: false,
+				fingerprintHash: null,
+				message: null,
+				shouldForceUpdate: false,
+				targetAppVersion: "*"
+			}
+		});
+		const mine = (page) => page.data.map(({ bundle }) => bundle.id).filter((id) => id.startsWith(namespace.slice(0, 8)));
+		it("stores a deployed bundle's fields", async () => {
+			const input = bundleRow("10");
+			await deploy(input);
+			const { data } = await adminJson(`/bundles/${input.id}`);
+			expect(data).toEqual({
+				bundle: input,
+				patches: [],
+				childCount: 0
+			});
+		});
+		it("answers 404 for a missing bundle", async () => {
+			const response = await admin(`/bundles/${bundleRow("99").id}`);
+			expect(response.status).toBe(404);
+			await response.text();
+		});
+		it("pages bundles by key and filters by platform", async () => {
+			const first = bundleRow("40");
+			const second = bundleRow("41");
+			const android = bundleRow("42", "android");
+			for (const row of [
+				first,
+				second,
+				android
+			]) await deploy(row);
+			const prefix = `${namespace.slice(0, 8)}-0000-7000-8000-000000000039`;
+			const page1 = await adminJson(`/bundles?order=asc&limit=1&cursor=${prefix}&platform=ios`);
+			const page2 = await adminJson(`/bundles?order=asc&limit=1&cursor=${page1.next}&platform=ios`);
+			const androidPage = await adminJson(`/bundles?order=asc&limit=100&cursor=${prefix}&platform=android`);
+			expect(mine(page1)).toEqual([first.id]);
+			expect(page1.next).toBe(first.id);
+			expect(mine(page2)).toEqual([second.id]);
+			expect(mine(androidPage)).toEqual([android.id]);
+		});
+		it("counts bundles with a page when asked", async () => {
+			const before = await adminJson("/bundles?limit=1&total=true");
+			await deploy(bundleRow("50"));
+			const after = await adminJson("/bundles?limit=1&total=true");
+			expect(after.total).toBe(before.total + 1);
+		});
+		it("changes a bundle's fields", async () => {
+			const input = bundleRow("60");
+			await deploy(input);
+			const response = await admin(`/bundles/${input.id}`, jsonRequest("PATCH", { gitCommitHash: "abc123" }));
+			expect(response.status).toBe(204);
+			expect((await adminJson(`/bundles/${input.id}`)).data.bundle.git_commit_hash).toBe("abc123");
+		});
+		it("refuses to delete a bundle a release uses, then deletes it", async () => {
+			const input = bundleRow("70");
+			const release = await deploy(input);
+			const refused = await admin("/bundles/delete", jsonRequest("POST", { ids: [input.id] }));
+			expect(refused.status).toBe(409);
+			await refused.text();
+			await api.removeRelease(release.id);
+			api.forget(release.id);
+			await adminJson("/bundles/delete", jsonRequest("POST", { ids: [input.id] }));
+			expect((await admin(`/bundles/${input.id}`)).status).toBe(404);
+		});
+	});
+};
+//#endregion
+//#region src/setupCoreAdminTestSuite.ts
+/**
+* Core's operations through admin API protocol 2 that the bundle and catalog
+* suites leave out: channels, deploy refusals, promotion, preflights, and a
+* bundle's patch children. Each test deletes what it wrote.
+*/
+const setupCoreAdminTestSuite = (options) => {
+	describe("Core admin API", () => {
+		const api = createAdminApiTestClient(options.getClient);
+		const { admin, adminJson } = api;
+		let namespace;
+		beforeEach(() => {
+			namespace = crypto.randomUUID();
+		});
+		afterEach(async () => {
+			await api.cleanup();
+		});
+		const bundleRow = (suffix) => ({
+			...createBundleRowFixture(suffix),
+			id: `${namespace.slice(0, 8)}-0000-7000-8000-${suffix.padStart(12, "0")}`
+		});
+		const policy = (channel, enabled = true) => ({
+			channel: `${channel}-${namespace}`,
+			enabled,
+			fingerprintHash: null,
+			message: null,
+			shouldForceUpdate: false,
+			targetAppVersion: "1.0.x"
+		});
+		it("keeps one channel per name and deletes only an unused one", async () => {
+			const name = `preview-${namespace}`;
+			const [first, second] = await Promise.all([api.ensureChannel(name), api.ensureChannel(name)]);
+			expect(second).toEqual(first);
+			expect((await adminJson(`/channels?name=${encodeURIComponent(name)}`)).data).toEqual(first);
+			expect((await adminJson("/channels")).data.filter((channel) => channel.name === name)).toEqual([first]);
+			const used = await api.deploy({
+				bundle: toDeployBundle(bundleRow("10")),
+				release: policy("used")
+			});
+			const usedChannel = (await adminJson(`/channels?name=used-${namespace}`)).data;
+			const refused = await admin(`/channels/${usedChannel.id}`, jsonRequest("DELETE"));
+			expect(refused.status).toBe(409);
+			expect(await refused.json()).toEqual({ data: {
+				deleted: false,
+				reason: "not_empty"
+			} });
+			expect(used.channel_id).toBe(usedChannel.id);
+			const deleted = await admin(`/channels/${first.id}`, jsonRequest("DELETE"));
+			expect(deleted.status).toBe(204);
+			await deleted.text();
+			const missing = await admin(`/channels/${first.id}`, jsonRequest("DELETE"));
+			expect(missing.status).toBe(404);
+			await missing.text();
+		});
+		it("keeps a release's channel when a delete races the deploy into it", async () => {
+			const channel = await api.ensureChannel(`race-${namespace}`);
+			const [deleted, release] = await Promise.all([admin(`/channels/${channel.id}`, jsonRequest("DELETE")), api.deploy({
+				bundle: toDeployBundle(bundleRow("15")),
+				release: policy("race")
+			})]);
+			await deleted.text();
+			const channels = (await adminJson("/channels")).data;
+			expect(channels.map(({ id }) => id)).toContain(release.channel_id);
+		});
+		it("refuses a malformed deployment and a stored bundle it does not hold", async () => {
+			const malformed = await admin("/releases", jsonRequest("POST", { deployments: [{
+				bundle: {
+					...toDeployBundle(bundleRow("20")),
+					platform: "web"
+				},
+				release: policy("production")
+			}] }));
+			const missing = await admin("/releases", jsonRequest("POST", { deployments: [{
+				bundleId: bundleRow("21").id,
+				release: policy("production")
+			}] }));
+			expect(malformed.status).toBe(400);
+			await malformed.text();
+			expect(missing.status).toBe(404);
+			expect(await missing.json()).toMatchObject({ code: "BUNDLE_NOT_FOUND" });
+		});
+		it("copies a release into another channel, and moves one", async () => {
+			const source = await api.deploy({
+				bundle: toDeployBundle(bundleRow("30")),
+				release: policy("production")
+			});
+			const copied = await adminJson(`/releases/${source.id}/promote`, jsonRequest("POST", { targetChannel: `beta-${namespace}` }));
+			const moved = await adminJson(`/releases/${source.id}/promote`, jsonRequest("POST", {
+				targetChannel: `staging-${namespace}`,
+				action: "move"
+			}));
+			for (const { data } of [copied, moved]) api.track(data.target.release.id);
+			expect(copied.data.source).toBeNull();
+			expect(copied.data.target.release).toMatchObject({
+				bundle_id: source.bundle_id,
+				enabled: true
+			});
+			expect(moved.data.target.release?.bundle_id).toBe(source.bundle_id);
+			expect(moved.data.source?.release?.enabled).toBe(false);
+			expect((await adminJson(`/releases/${source.id}`)).data.enabled).toBe(false);
+		});
+		it("previews a policy change and a catalog rebuild without writing", async () => {
+			const release = await api.deploy({
+				bundle: toDeployBundle(bundleRow("40")),
+				release: policy("production")
+			});
+			const catalogPath = `/release-catalogs/${encodeURIComponent(release.scope_key)}`;
+			const before = await adminJson(catalogPath);
+			const preflight = await adminJson(`/releases/${release.id}/preflight`, jsonRequest("POST", {
+				expectedRevision: 1,
+				patch: { enabled: false }
+			}));
+			const rebuild = await adminJson(`${catalogPath}/preflight`, jsonRequest("POST"));
+			expect(preflight.data).toBeDefined();
+			expect(rebuild.data).toBeDefined();
+			expect(await adminJson(catalogPath)).toEqual(before);
+			expect((await adminJson(`/releases/${release.id}`)).data).toEqual(release);
+		});
+		it("lists the patches that start from a bundle", async () => {
+			const base = bundleRow("50");
+			const target = bundleRow("51");
+			await api.deploy({
+				bundle: toDeployBundle(base),
+				release: policy("production", false)
+			});
+			await api.deploy({
+				bundle: {
+					...toDeployBundle(target),
+					patches: [{
+						baseBundleId: base.id,
+						baseFileHash: "base-hash",
+						byteSize: 10,
+						patchFileHash: "patch-hash",
+						patchStorageUri: "storage://patches/51.patch"
+					}]
+				},
+				release: policy("production", false)
+			});
+			const children = await adminJson(`/bundles/${base.id}/children`);
+			const detail = await adminJson(`/bundles/${base.id}`);
+			expect(children.data).toEqual([expect.objectContaining({
+				bundle_id: target.id,
+				base_bundle_id: base.id
+			})]);
+			expect(detail.data.childCount).toBe(1);
+		});
+	});
+};
+//#endregion
+//#region src/expectInsightsIndex.ts
+/** Allow committed secondary indexes to catch up; query failures still fail. */
+const expectInsightsIndex = async (query, expected) => {
+	const deadline = Date.now() + 5e3;
+	for (;;) {
+		const actual = await query();
+		try {
+			expect(actual).toEqual(expected);
+			return;
+		} catch (error) {
+			if (Date.now() >= deadline) throw error;
+		}
+		await new Promise((resolve) => setTimeout(resolve, 50));
+	}
+};
+//#endregion
+//#region src/setupInsightsHttpTestSuite.ts
+/**
+* The Insights plugin's routes on a database: a client reports an event, and
+* the admin routes read it back. The server must run `insights()`.
+*/
+const setupInsightsHttpTestSuite = (options) => {
+	describe("Insights HTTP routes", () => {
+		it("records a reported event and reads it back", async () => {
+			const client = options.getClient();
+			const installId = `install-${crypto.randomUUID()}`;
+			const userId = `user-${crypto.randomUUID()}`;
+			const channel = `insights-${crypto.randomUUID()}`;
+			const event = {
+				appVersion: "1.0.0",
+				channel,
+				cohort: "default",
+				fingerprintHash: null,
+				fromBundleId: null,
+				fromReleaseId: null,
+				installId,
+				platform: "ios",
+				toBundleId: "00000000-0000-7000-8000-000000000001",
+				toReleaseId: null,
+				type: "UNCHANGED",
+				updateStrategy: null,
+				userId,
+				username: "Jane",
+				sdkVersion: "2.0.0"
+			};
+			const reported = await client.client("/events", jsonRequest("POST", event));
+			expect(reported.status).toBe(204);
+			expect(reported.headers.get("x-hot-updater-insights")).toBeNull();
+			await reported.text();
+			const installation = await client.admin(`/installations/${encodeURIComponent(installId)}`);
+			expect(installation.status).toBe(200);
+			expect(await installation.json()).toMatchObject({
+				installId,
+				latestStatus: "UNCHANGED",
+				lastKnownBundleId: event.toBundleId,
+				channel
+			});
+			await expectInsightsIndex(async () => {
+				return (await (await client.admin(`/installations?userId=${encodeURIComponent(userId)}`)).json()).data.map(({ installId: id }) => id);
+			}, [installId]);
+			await expectInsightsIndex(async () => {
+				return (await (await client.admin(`/overview?platform=ios&channel=${encodeURIComponent(channel)}&window=24h`)).json()).reportingInstallations.count;
+			}, 1);
+		});
+		it("refuses a malformed event", async () => {
+			const response = await options.getClient().client("/events", jsonRequest("POST", { type: "UNCHANGED" }));
+			expect(response.status).toBe(400);
+			await response.text();
+		});
+	});
+};
+//#endregion
+//#region src/databaseTestRunner.ts
+var DatabaseUnavailableError = class extends Error {
+	constructor() {
+		super("The database is unavailable outside the test lifecycle");
+		this.name = "DatabaseUnavailableError";
+	}
+};
+const setupDatabaseTestRunner = (lifecycle, registerTests) => {
+	describe(lifecycle.name, () => {
+		let database;
+		const getDatabase = () => {
+			if (database === void 0) throw new DatabaseUnavailableError();
+			return database;
+		};
+		beforeAll(async () => {
+			await lifecycle.migrate();
+			database = await lifecycle.createDatabase();
+		});
+		beforeEach(async () => {
+			await lifecycle.reset(getDatabase());
+		});
+		afterAll(async () => {
+			await lifecycle.dispose(getDatabase());
+			database = void 0;
+		});
+		registerTests({ getDatabase });
+	});
+};
+//#endregion
+//#region src/insightsModelTests.ts
+const record = (model, event) => model.recordEvent({ event });
+const createMovementEvent = (suffix, receivedAtMs, type, installId) => {
+	const row = createBundleEventRowFixture(suffix, receivedAtMs);
+	return {
+		...row,
+		type,
+		install_id: installId,
+		from_bundle_id: row.to_bundle_id,
+		metadata: {
+			...row.metadata,
+			update_strategy: "appVersion"
+		}
+	};
+};
+/**
+* The Insights report contract on `InsightsModel`: what the Insights plugin
+* records and reads, through `createInsightsModel`, on one database.
+*/
+const registerInsightsModelTests = (state) => {
+	describe("Insights report contract", () => {
+		it("preserves ancillary JSON through event history and latest-event reads", async () => {
+			const model = state.getDatabase();
+			const base = createBundleEventRowFixture("979", 100);
+			const event = {
+				...base,
+				metadata: {
+					...base.metadata,
+					device: {
+						locale: "ko-KR",
+						tags: [
+							"minor",
+							null,
+							true,
+							2
+						]
+					},
+					diagnostic: null
+				}
+			};
+			await record(model, event);
+			await expect(model.findLatestEvents({ installId: event.install_id })).resolves.toEqual([event]);
+			await expectInsightsIndex(() => model.listEvents({
+				filter: { kind: "all" },
+				beforeReceivedAtMs: 101,
+				limit: 10
+			}), [event]);
+		});
+		it("selects the latest complete event across download, replacement, apply, and delayed reports", async () => {
+			const model = state.getDatabase();
+			const download = {
+				...createBundleEventRowFixture("980", 100),
+				type: "UPDATE_DOWNLOADED",
+				from_bundle_id: "00000000-0000-7000-8000-000000001980",
+				metadata: {
+					...createBundleEventRowFixture("980", 100).metadata,
+					update_strategy: "appVersion"
+				},
+				to_release_id: "00000000-0000-7000-8000-000000004980"
+			};
+			await record(model, download);
+			await record(model, download);
+			await expect(model.findLatestEvents({ installId: download.install_id })).resolves.toEqual([download]);
+			await expectInsightsIndex(() => model.listEvents({
+				filter: {
+					kind: "bundle",
+					type: "UPDATE_DOWNLOADED",
+					toBundleId: download.to_bundle_id,
+					platform: "ios",
+					channel: "production"
+				},
+				beforeReceivedAtMs: 200,
+				limit: 10
+			}), [download]);
+			const replacement = {
+				...download,
+				id: createBundleEventRowFixture("981", 110).id,
+				received_at_ms: 110,
+				to_bundle_id: "00000000-0000-7000-8000-000000002981"
+			};
+			await record(model, replacement);
+			await expect(model.findLatestEvents({ installId: download.install_id })).resolves.toEqual([replacement]);
+			const applied = {
+				...replacement,
+				type: "UPDATE_APPLIED",
+				id: createBundleEventRowFixture("982", 120).id,
+				received_at_ms: 120
+			};
+			await record(model, applied);
+			await record(model, {
+				...download,
+				id: createBundleEventRowFixture("983", 105).id,
+				received_at_ms: 105
+			});
+			await expect(model.findLatestEvents({ installId: download.install_id })).resolves.toEqual([applied]);
+			await expectInsightsIndex(() => model.listEvents({
+				filter: {
+					kind: "installationMovement",
+					installId: download.install_id
+				},
+				beforeReceivedAtMs: 200,
+				limit: 10
+			}), [
+				applied,
+				replacement,
+				{
+					...download,
+					id: createBundleEventRowFixture("983", 105).id,
+					received_at_ms: 105
+				},
+				download
+			]);
+		});
+		it("treats duplicate IDs as complete no-ops, including changed retry payloads", async () => {
+			const model = state.getDatabase();
+			const event = createBundleEventRowFixture("901", 100);
+			await Promise.all([
+				record(model, event),
+				record(model, event),
+				record(model, event)
+			]);
+			await record(model, event);
+			const changed = {
+				...event,
+				received_at_ms: 300,
+				user_id: "changed-user"
+			};
+			await record(model, changed);
+			const otherInstallation = {
+				...changed,
+				install_id: "different-install"
+			};
+			await record(model, otherInstallation);
+			await expect(model.findLatestEvents({ installId: event.install_id })).resolves.toEqual([event]);
+			await expect(model.findLatestEvents({ installId: otherInstallation.install_id })).resolves.toEqual([]);
+			await expectInsightsIndex(() => model.listEvents({
+				filter: { kind: "all" },
+				beforeReceivedAtMs: 400,
+				limit: 10
+			}), [event]);
+		});
+		it("keeps all concurrent events and the greatest timestamp/ID state, including logout", async () => {
+			const model = state.getDatabase();
+			const older = {
+				...createBundleEventRowFixture("912", 100),
+				install_id: "concurrent",
+				user_id: "previous"
+			};
+			const tied = {
+				...createBundleEventRowFixture("910", 200),
+				install_id: "concurrent",
+				user_id: "previous"
+			};
+			const newest = {
+				...createBundleEventRowFixture("911", 200),
+				install_id: "concurrent",
+				user_id: null
+			};
+			await Promise.all([
+				record(model, newest),
+				record(model, older),
+				record(model, tied)
+			]);
+			await record(model, older);
+			await expect(model.findLatestEvents({ installId: "concurrent" })).resolves.toEqual([newest]);
+			await expect(model.findLatestEvents({
+				userId: "previous",
+				limit: 10
+			})).resolves.toEqual([]);
+			await expectInsightsIndex(() => model.listEvents({
+				filter: { kind: "all" },
+				beforeReceivedAtMs: 201,
+				limit: 10
+			}), [
+				newest,
+				tied,
+				older
+			]);
+		});
+		it("rejects invalid event metadata before persisting a report", async () => {
+			const model = state.getDatabase();
+			const event = createBundleEventRowFixture("920", 100);
+			await expect(model.recordEvent({ event: {
+				...event,
+				metadata: {
+					...event.metadata,
+					cohort: 123
+				}
+			} })).rejects.toMatchObject({ code: "invalid-data" });
+			await expect(model.findLatestEvents({ installId: event.install_id })).resolves.toEqual([]);
+			await expect(model.listEvents({
+				filter: { kind: "all" },
+				beforeReceivedAtMs: 200,
+				limit: 10
+			})).resolves.toEqual([]);
+		});
+		it("shares scoped list/count predicates, recovery attribution, and half-open time bounds", async () => {
+			const model = state.getDatabase();
+			const bundleA = createBundleEventRowFixture("1", 0).to_bundle_id;
+			const bundleB = createBundleEventRowFixture("2", 0).to_bundle_id;
+			const bundleC = createBundleEventRowFixture("3", 0).to_bundle_id;
+			const applied = {
+				...createBundleEventRowFixture("930", 100),
+				install_id: "target",
+				to_bundle_id: bundleB
+			};
+			const recovered = {
+				...createBundleEventRowFixture("931", 120),
+				install_id: "target",
+				type: "RECOVERED",
+				from_bundle_id: bundleB,
+				to_bundle_id: bundleA,
+				metadata: {
+					...createBundleEventRowFixture("931", 120).metadata,
+					update_strategy: "appVersion"
+				}
+			};
+			const unchanged = {
+				...createBundleEventRowFixture("932", 130),
+				type: "UNCHANGED",
+				from_bundle_id: null,
+				to_bundle_id: bundleB,
+				metadata: {
+					...createBundleEventRowFixture("932", 130).metadata,
+					update_strategy: null
+				}
+			};
+			const excluded = [
+				{
+					...applied,
+					id: createBundleEventRowFixture("933", 99).id,
+					install_id: "before",
+					received_at_ms: 99
+				},
+				{
+					...applied,
+					id: createBundleEventRowFixture("934", 200).id,
+					install_id: "after",
+					received_at_ms: 200
+				},
+				{
+					...applied,
+					id: createBundleEventRowFixture("935", 110).id,
+					install_id: "android",
+					platform: "android"
+				},
+				{
+					...applied,
+					id: createBundleEventRowFixture("936", 110).id,
+					install_id: "preview",
+					channel: "preview"
+				},
+				{
+					...recovered,
+					id: createBundleEventRowFixture("937", 125).id,
+					install_id: "other-source",
+					from_bundle_id: bundleC,
+					to_bundle_id: bundleB
+				}
+			];
+			for (const row of [
+				applied,
+				recovered,
+				unchanged,
+				...excluded
+			]) await record(model, row);
+			await expect(async () => record(model, {
+				...applied,
+				type: "RELEASE_ADOPTED"
+			})).rejects.toThrow();
+			await expect(async () => record(model, {
+				...applied,
+				type: "UNCHANGED",
+				from_bundle_id: bundleB,
+				metadata: {
+					...applied.metadata,
+					update_strategy: "appVersion"
+				}
+			})).rejects.toThrow();
+			await expect(model.findLatestEvents({ installId: "target" })).resolves.toEqual([recovered]);
+			const cases = [
+				[{
+					platform: "ios",
+					channel: "production",
+					type: "UPDATE_APPLIED",
+					toBundleId: bundleB
+				}, applied],
+				[{
+					platform: "ios",
+					channel: "production",
+					type: "RECOVERED",
+					fromBundleId: bundleB
+				}, recovered],
+				[{
+					platform: "ios",
+					channel: "production",
+					type: "UNCHANGED",
+					toBundleId: bundleB
+				}, unchanged]
+			];
+			for (const [filter, expected] of cases) {
+				await expectInsightsIndex(() => model.countEvents({
+					filter,
+					sinceMs: 100,
+					beforeReceivedAtMs: 200
+				}), 1);
+				await expectInsightsIndex(() => model.listEvents({
+					filter: {
+						kind: "bundle",
+						...filter
+					},
+					sinceMs: 100,
+					beforeReceivedAtMs: 200,
+					limit: 1
+				}), [expected]);
+			}
+			await expectInsightsIndex(() => model.countLatestEvents({
+				platform: "ios",
+				channel: "production",
+				sinceMs: 100,
+				bundle: [{
+					field: "to_bundle_id",
+					value: bundleA,
+					types: [
+						"UNCHANGED",
+						"UPDATE_APPLIED",
+						"RECOVERED"
+					]
+				}]
+			}), 1);
+			await expectInsightsIndex(() => model.countLatestEvents({
+				platform: "ios",
+				channel: "production",
+				sinceMs: 100
+			}), 4);
+		});
+		it("uses exact identity and UTF-8 cursor order for user installations", async () => {
+			const model = state.getDatabase();
+			const ids = [
+				"Install-a",
+				"é",
+				"install-a",
+				"install-a ",
+				"é",
+				"",
+				"😀"
+			];
+			const events = ids.map((install_id, index) => ({
+				...createBundleEventRowFixture(String(950 + index), 100),
+				install_id,
+				user_id: "User-é"
+			}));
+			for (const event of events.toReversed()) await record(model, event);
+			const spacedUser = {
+				...createBundleEventRowFixture("960", 100),
+				install_id: "spaced-user-install",
+				user_id: "User-é "
+			};
+			await record(model, spacedUser);
+			await expectInsightsIndex(async () => {
+				const found = [];
+				let afterInstallId;
+				for (let pageIndex = 0; pageIndex <= ids.length; pageIndex++) {
+					const page = await model.findLatestEvents({
+						userId: "User-é",
+						afterInstallId,
+						limit: 2
+					});
+					found.push(...page.map((row) => row.install_id));
+					if (page.length < 2) return found;
+					const nextCursor = page[page.length - 1].install_id;
+					expect(nextCursor, "Insights cursor must advance").not.toBe(afterInstallId);
+					afterInstallId = nextCursor;
+				}
+				throw new Error("Insights pagination did not terminate");
+			}, ids);
+			await expectInsightsIndex(() => model.findLatestEvents({
+				userId: "User-é ",
+				limit: 10
+			}), [spacedUser]);
+			await expect(model.findLatestEvents({
+				userId: "user-é",
+				limit: 10
+			})).resolves.toEqual([]);
+			await expect(model.findLatestEvents({ installId: "INSTALL-a" })).resolves.toEqual([]);
+			await expect(model.findLatestEvents({ installId: "Install-a" })).resolves.toEqual([events[0]]);
+			await expect(model.findLatestEvents({ installId: "install-a " })).resolves.toEqual([events[3]]);
+			await expect(model.findLatestEvents({ installId: "install-a" })).resolves.toEqual([events[2]]);
+		});
+		it("counts overlapping bundle predicates once per latest installation", async () => {
+			const model = state.getDatabase();
+			const event = createBundleEventRowFixture("9700", 100);
+			await record(model, event);
+			const predicate = {
+				field: "to_bundle_id",
+				value: event.to_bundle_id,
+				types: [event.type]
+			};
+			await expectInsightsIndex(() => model.countLatestEvents({
+				platform: event.platform,
+				channel: event.channel,
+				sinceMs: 0,
+				bundle: [predicate, predicate]
+			}), 1);
+		});
+		it("returns zero for successful empty scalar queries", async () => {
+			const model = state.getDatabase();
+			await expect(model.countLatestEvents({
+				platform: "ios",
+				channel: "production",
+				sinceMs: 0
+			})).resolves.toBe(0);
+			await expect(model.countEvents({
+				filter: {
+					platform: "ios",
+					channel: "production",
+					type: "RECOVERED",
+					fromBundleId: createBundleEventRowFixture("1", 0).to_bundle_id
+				},
+				sinceMs: 0,
+				beforeReceivedAtMs: 100
+			})).resolves.toBe(0);
+		});
+		it("maintains idempotent release, scope, usage, and latest-distribution summaries", async () => {
+			const model = state.getDatabase();
+			const releaseA = "00000000-0000-7000-8000-000000008001";
+			const releaseB = "00000000-0000-7000-8000-000000008002";
+			const download = {
+				...createBundleEventRowFixture("9801", 1e3),
+				type: "UPDATE_DOWNLOADED",
+				install_id: "summary-install-a",
+				from_release_id: releaseA,
+				to_release_id: releaseB
+			};
+			const appliedA = {
+				...download,
+				id: createBundleEventRowFixture("9802", 2e3).id,
+				type: "UPDATE_APPLIED",
+				received_at_ms: 2e3
+			};
+			const appliedB = {
+				...appliedA,
+				id: createBundleEventRowFixture("9803", 2100).id,
+				install_id: "summary-install-b",
+				received_at_ms: 2100
+			};
+			const recovered = {
+				...appliedA,
+				id: createBundleEventRowFixture("9804", 3e3).id,
+				type: "RECOVERED",
+				from_release_id: releaseB,
+				to_release_id: releaseA,
+				received_at_ms: 3e3
+			};
+			for (const event of [
+				download,
+				appliedA,
+				appliedB,
+				appliedB,
+				recovered
+			]) await record(model, event);
+			const releases = [{
+				releaseId: releaseA,
+				platform: "ios",
+				channel: "production"
+			}, {
+				releaseId: releaseB,
+				platform: "ios",
+				channel: "production"
+			}];
+			const lifetime = await model.getReleaseActivity({ releases });
+			expect(lifetime.data.map(({ metrics }) => metrics)).toEqual([{
+				downloads: 0,
+				launches: 1,
+				failedLaunches: 0
+			}, {
+				downloads: 1,
+				launches: 2,
+				failedLaunches: 1
+			}]);
+			const scope = await model.getReleaseActivity({
+				scope: {
+					platform: "ios",
+					channel: "production"
+				},
+				timeRange: {
+					start: 0,
+					end: 36e5
+				}
+			});
+			expect(scope.data[0]?.metrics).toMatchObject({
+				downloads: 1,
+				launches: 3,
+				failedLaunches: 1,
+				uniqueUsers: 2
+			});
+			const usage = await model.getAppUsage({
+				channel: "production",
+				platform: "all",
+				timeRange: {
+					start: 0,
+					end: 36e5
+				},
+				intervalMs: 36e5
+			});
+			expect(usage.activeInstallations).toBe(2);
+			expect(usage.points).toEqual([{
+				startMs: 0,
+				installations: 2
+			}]);
+			expect(usage.bundleDistribution).toEqual(expect.arrayContaining([{
+				appVersion: "1.0.0",
+				platform: "ios",
+				releaseId: releaseA,
+				installations: 1
+			}, {
+				appVersion: "1.0.0",
+				platform: "ios",
+				releaseId: releaseB,
+				installations: 1
+			}]));
+		});
+		it("pages insights events newest first with a stable cursor", async () => {
+			const model = state.getDatabase();
+			const first = createBundleEventRowFixture("701", 100);
+			const second = createBundleEventRowFixture("702", 100);
+			const third = createBundleEventRowFixture("703", 200);
+			await model.recordEvent({ event: third });
+			await model.recordEvent({ event: second });
+			await model.recordEvent({ event: first });
+			await expectInsightsIndex(() => model.listEvents({
+				filter: { kind: "all" },
+				beforeReceivedAtMs: 201,
+				limit: 2
+			}), [third, second]);
+			await expectInsightsIndex(() => model.listEvents({
+				filter: { kind: "all" },
+				after: {
+					receivedAtMs: second.received_at_ms,
+					id: second.id
+				},
+				beforeReceivedAtMs: 201,
+				limit: 2
+			}), [first]);
+			await expectInsightsIndex(() => model.listEvents({
+				filter: { kind: "all" },
+				beforeReceivedAtMs: 200,
+				limit: 10
+			}), [second, first]);
+		});
+		it("filters installation movements before applying the page limit", async () => {
+			const model = state.getDatabase();
+			const unchanged = {
+				...createBundleEventRowFixture("711", 300),
+				type: "UNCHANGED",
+				install_id: "install-target",
+				from_bundle_id: null,
+				metadata: {
+					...createBundleEventRowFixture("711", 300).metadata,
+					update_strategy: null
+				}
+			};
+			const unrelated = createMovementEvent("712", 250, "UPDATE_APPLIED", "install-other");
+			const applied = createMovementEvent("713", 200, "UPDATE_APPLIED", "install-target");
+			const recovered = createMovementEvent("714", 100, "RECOVERED", "install-target");
+			for (const row of [
+				unchanged,
+				unrelated,
+				applied,
+				recovered
+			]) await model.recordEvent({ event: row });
+			await expectInsightsIndex(() => model.listEvents({
+				filter: {
+					kind: "installationMovement",
+					installId: "install-target"
+				},
+				beforeReceivedAtMs: 301,
+				limit: 1
+			}), [applied]);
+			await expectInsightsIndex(() => model.listEvents({
+				filter: {
+					kind: "installationMovement",
+					installId: "install-target"
+				},
+				after: {
+					receivedAtMs: applied.received_at_ms,
+					id: applied.id
+				},
+				beforeReceivedAtMs: 301,
+				limit: 1
+			}), [recovered]);
+		});
+	});
+};
+//#endregion
+//#region src/setupInsightsModelTestSuite.ts
+/**
+* The Insights report contract on one database: pass the Insights plugin's
+* model over it, `createInsightsModel(createDatabasePluginApis(database,
+* [insights()]).insights)`, as `createDatabase`.
+*/
+const setupInsightsModelTestSuite = (lifecycle) => setupDatabaseTestRunner(lifecycle, registerInsightsModelTests);
+//#endregion
+//#region src/setupSemverSatisfiesTestSuite.ts
+/**
+*
+* Filters based on semver. And sorts by the highest bundle version.
+*
+* * Range Expression Table:
+*
+* | Range Expression | Who gets the update                                                    |
+* |------------------|------------------------------------------------------------------------|
+* | 1.2.3            | Only devices running the specific binary app store version 1.2.3 of your app |
+* | *                | Any device configured to consume updates from your CodePush app         |
+* | 1.2.x            | Devices running major version 1, minor version 2 and any patch version of your app |
+* | 1.2.3 - 1.2.7    | Devices running any binary version between 1.2.3 (inclusive) and 1.2.7 (inclusive) |
+* | >=1.2.3 <1.2.7   | Devices running any binary version between 1.2.3 (inclusive) and 1.2.7 (exclusive) |
+* | 1.2              | Equivalent to >=1.2.0 <1.3.0                                            |
+* | ~1.2.3           | Equivalent to >=1.2.3 <1.3.0                                            |
+* | ^1.2.3           | Equivalent to >=1.2.3 <2.0.0                                            |
+*/
+const setupSemverSatisfiesTestSuite = ({ semverSatisfies }) => {
+	it("version 1.2.3 should satisfy version 1.2.3", async () => {
+		expect(await semverSatisfies("1.2.3", "1.2.3")).toBe(true);
+	});
+	it("version 1.2.4 should not satisfy version 1.2.3", async () => {
+		expect(await semverSatisfies("1.2.3", "1.2.4")).toBe(false);
+	});
+	it("version 1.2.4 should not satisfy version 1.2.3", async () => {
+		expect(await semverSatisfies("1.2.3", "1.2.4")).toBe(false);
+	});
+	it("version 1.2.4 should not satisfy version 1.2.3", async () => {
+		expect(await semverSatisfies("1.2.3", "1.2.4")).toBe(false);
+	});
+	it("1.x.x should satisfy version 1.0", async () => {
+		expect(await semverSatisfies("1.x.x", "1.0")).toBe(true);
+	});
+	it("1.x.x should satisfy version 1.12", async () => {
+		expect(await semverSatisfies("1.x.x", "1.12")).toBe(true);
+	});
+	it("1.x.x should satisfy version 1.0.0", async () => {
+		expect(await semverSatisfies("1.x.x", "1.0.0")).toBe(true);
+	});
+	it("1.x.x should satisfy version 1.2.3", async () => {
+		expect(await semverSatisfies("1.x.x", "1.2.3")).toBe(true);
+	});
+	it("1.x.x should not satisfy version 2.0.0", async () => {
+		expect(await semverSatisfies("1.x.x", "2.0.0")).toBe(false);
+	});
+	it("1.x.x should not satisfy version 2.0.0", async () => {
+		expect(await semverSatisfies("1.x.x", "2.0.0")).toBe(false);
+	});
+	it("1.2.x should satisfy version 1.2.5", async () => {
+		expect(await semverSatisfies("1.2.x", "1.2.5")).toBe(true);
+	});
+	it("1.2.x should not satisfy version 1.3.0", async () => {
+		expect(await semverSatisfies("1.2.x", "1.3.0")).toBe(false);
+	});
+	it("1.2.x should not satisfy version 1.3.0", async () => {
+		expect(await semverSatisfies("1.2.x", "1.3.0")).toBe(false);
+	});
+	it("range 1.2.3-1.2.7 should satisfy version 1.2.5", async () => {
+		expect(await semverSatisfies("1.2.3 - 1.2.7", "1.2.5")).toBe(true);
+	});
+	it("range 1.2.3-1.2.7 should satisfy version 1.2.5", async () => {
+		expect(await semverSatisfies("1.2.3 - 1.2.7", "1.2.5")).toBe(true);
+	});
+	it("range 1.2.3-1.2.7 should not satisfy version 1.3.0", async () => {
+		expect(await semverSatisfies("1.2.3 - 1.2.7", "1.3.0")).toBe(false);
+	});
+	it("range >=1.2.3 <1.2.7 should satisfy version 1.2.5", async () => {
+		expect(await semverSatisfies(">=1.2.3 <1.2.7", "1.2.5")).toBe(true);
+	});
+	it("range >=1.2.3 <1.2.7 should satisfy version 1.2.5", async () => {
+		expect(await semverSatisfies(">=1.2.3 <1.2.7", "1.2.5")).toBe(true);
+	});
+	it("range >=1.2.3 <1.2.7 should not satisfy version 1.2.7", async () => {
+		expect(await semverSatisfies(">=1.2.3 <1.2.7", "1.2.7")).toBe(false);
+	});
+	it("~1.2.3 should satisfy version 1.2.3", async () => {
+		expect(await semverSatisfies("~1.2.3", "1.2.3")).toBe(true);
+	});
+	it("~1.2.3 should satisfy version 1.2.4", async () => {
+		expect(await semverSatisfies("~1.2.3", "1.2.4")).toBe(true);
+	});
+	it("~1.2.3 should not satisfy version 1.3.0", async () => {
+		expect(await semverSatisfies("~1.2.3", "1.3.0")).toBe(false);
+	});
+	it("~1.2.3 should satisfy version 1.2.3", async () => {
+		expect(await semverSatisfies("~1.2.3", "1.2.3")).toBe(true);
+	});
+	it("~1.2.3 should satisfy version 1.2.4", async () => {
+		expect(await semverSatisfies("~1.2.3", "1.2.4")).toBe(true);
+	});
+	it("~1.2.3 should not satisfy version 1.3.0", async () => {
+		expect(await semverSatisfies("~1.2.3", "1.3.0")).toBe(false);
+	});
+	it("^1.2.3 should satisfy version 1.3.0", async () => {
+		expect(await semverSatisfies("^1.2.3", "1.3.0")).toBe(true);
+	});
+	it("^1.2.3 should satisfy version 1.3.0", async () => {
+		expect(await semverSatisfies("^1.2.3", "1.3.0")).toBe(true);
+	});
+	it("^1.2.3 should not satisfy version 2.0.0", async () => {
+		expect(await semverSatisfies("^1.2.3", "2.0.0")).toBe(false);
+	});
+	it("version 1.2 should satisfy version 1.2.0 (equivalent to >=1.2.0 <1.3.0)", async () => {
+		expect(await semverSatisfies("1.2", "1.2.0")).toBe(true);
+	});
+	it("version 1.2 should satisfy version 1.2.99 (equivalent to >=1.2.0 <1.3.0)", async () => {
+		expect(await semverSatisfies("1.2", "1.2.99")).toBe(true);
+	});
+	it("version 1.2 should not satisfy version 1.3.0", async () => {
+		expect(await semverSatisfies("1.2", "1.3.0")).toBe(false);
+	});
+	it("single-major '1' should satisfy version 1.0.0 (equivalent to >=1.0.0 <2.0.0)", async () => {
+		expect(await semverSatisfies("1", "1.0.0")).toBe(true);
+	});
+	it("single-major '1' should satisfy version 1.99.99", async () => {
+		expect(await semverSatisfies("1", "1.99.99")).toBe(true);
+	});
+	it("single-major '1' should not satisfy version 2.0.0", async () => {
+		expect(await semverSatisfies("1", "2.0.0")).toBe(false);
+	});
+	it("0.x.x should satisfy version 0.5.10", async () => {
+		expect(await semverSatisfies("0.x.x", "0.5.10")).toBe(true);
+	});
+	it("0.x.x should not satisfy version 1.0.0", async () => {
+		expect(await semverSatisfies("0.x.x", "1.0.0")).toBe(false);
+	});
+	it("2.x should satisfy version 2.0.0", async () => {
+		expect(await semverSatisfies("2.x", "2.0.0")).toBe(true);
+	});
+	it("2.x should satisfy version 2.10.1", async () => {
+		expect(await semverSatisfies("2.x", "2.10.1")).toBe(true);
+	});
+	it("2.x should not satisfy version 3.0.0", async () => {
+		expect(await semverSatisfies("2.x", "3.0.0")).toBe(false);
+	});
+	it("simple star * should satisfy any version, e.g. 10.11.12", async () => {
+		expect(await semverSatisfies("*", "10.11.12")).toBe(true);
+	});
+	it("simple star * should satisfy any version, e.g. 0.0.1", async () => {
+		expect(await semverSatisfies("*", "0.0.1")).toBe(true);
+	});
+	it("2.x.x should satisfy version 2.0.0", async () => {
+		expect(await semverSatisfies("2.x.x", "2.0.0")).toBe(true);
+	});
+	it("2.x.x should satisfy version 2.9.9", async () => {
+		expect(await semverSatisfies("2.x.x", "2.9.9")).toBe(true);
+	});
+	it("2.x.x should not satisfy version 3.0.0", async () => {
+		expect(await semverSatisfies("2.x.x", "3.0.0")).toBe(false);
+	});
+	it("0.x.x should satisfy version 0.1.0", async () => {
+		expect(await semverSatisfies("0.x.x", "0.1.0")).toBe(true);
+	});
+	it("0.x.x should satisfy version 0.9.9", async () => {
+		expect(await semverSatisfies("0.x.x", "0.9.9")).toBe(true);
+	});
+	it("0.x.x should not satisfy version 1.0.0", async () => {
+		expect(await semverSatisfies("0.x.x", "1.0.0")).toBe(false);
+	});
+	it("range 1.2.3 - 2.0.0 should satisfy version 1.2.4", async () => {
+		expect(await semverSatisfies("1.2.3 - 2.0.0", "1.2.4")).toBe(true);
+	});
+	it("range 1.2.3 - 2.0.0 should satisfy version 2.0.0", async () => {
+		expect(await semverSatisfies("1.2.3 - 2.0.0", "2.0.0")).toBe(true);
+	});
+	it("range 1.2.3 - 2.0.0 should satisfy version 1.5.0", async () => {
+		expect(await semverSatisfies("1.2.3 - 2.0.0", "1.5.0")).toBe(true);
+	});
+	it("range 1.2.3 - 2.0.0 should not satisfy version 2.0.1", async () => {
+		expect(await semverSatisfies("1.2.3 - 2.0.0", "2.0.1")).toBe(false);
+	});
+	it("range >= 5.7.0 <= 5.7.4 should satisfy version 5.7.3", async () => {
+		expect(await semverSatisfies(">= 5.7.0 <= 5.7.4", "5.7.3")).toBe(true);
+	});
+	it("range >= 5.7.0 <= 5.7.4 should satisfy version 5.7.0", async () => {
+		expect(await semverSatisfies(">= 5.7.0 <= 5.7.4", "5.7.0")).toBe(true);
+	});
+	it("range >= 5.7.0 <= 5.7.4 should satisfy version 5.7.4", async () => {
+		expect(await semverSatisfies(">= 5.7.0 <= 5.7.4", "5.7.4")).toBe(true);
+	});
+	it("range >= 5.7.0 <= 5.7.4 should not satisfy version 5.6.9", async () => {
+		expect(await semverSatisfies(">= 5.7.0 <= 5.7.4", "5.6.9")).toBe(false);
+	});
+	it("range >= 5.7.0 <= 5.7.4 should not satisfy version 5.7.5", async () => {
+		expect(await semverSatisfies(">= 5.7.0 <= 5.7.4", "5.7.5")).toBe(false);
+	});
+	it("range >=5.7.0 <=5.7.4 (no spaces around operators) should satisfy version 5.7.3", async () => {
+		expect(await semverSatisfies(">=5.7.0 <=5.7.4", "5.7.3")).toBe(true);
+	});
+	it("range >=  5.7.0  <=  5.7.4 (multiple spaces) should satisfy version 5.7.3", async () => {
+		expect(await semverSatisfies(">=  5.7.0  <=  5.7.4", "5.7.3")).toBe(true);
+	});
+	it("range >= 1.0.0 <= 2.0.0 should satisfy version 1.5.0", async () => {
+		expect(await semverSatisfies(">= 1.0.0 <= 2.0.0", "1.5.0")).toBe(true);
+	});
+	it("range >= 1.0.0 <= 2.0.0 should satisfy version 1.0.0", async () => {
+		expect(await semverSatisfies(">= 1.0.0 <= 2.0.0", "1.0.0")).toBe(true);
+	});
+	it("range >= 1.0.0 <= 2.0.0 should satisfy version 2.0.0", async () => {
+		expect(await semverSatisfies(">= 1.0.0 <= 2.0.0", "2.0.0")).toBe(true);
+	});
+	it("range >= 1.0.0 <= 2.0.0 should not satisfy version 0.9.9", async () => {
+		expect(await semverSatisfies(">= 1.0.0 <= 2.0.0", "0.9.9")).toBe(false);
+	});
+	it("range >= 1.0.0 <= 2.0.0 should not satisfy version 2.0.1", async () => {
+		expect(await semverSatisfies(">= 1.0.0 <= 2.0.0", "2.0.1")).toBe(false);
+	});
+};
+//#endregion
+//#region src/releaseCatalogHttpFixtures.ts
+const releaseCatalogDownloadUrl = (uri) => `https://storage.example.com/${encodeURIComponent(uri)}`;
+const targetId = createBundleRowFixture("302").id;
+const RELEASE_CATALOG_MANIFEST_URIS = {
+	small: `storage://test-bucket/small/bundles/${targetId}/manifest.json`,
+	large: `storage://test-bucket/large/bundles/${targetId}/manifest.json`
+};
+const RELEASE_CATALOG_DOWNLOAD_HASH = "a".repeat(64);
+const manifestAssets = { "index.ios.bundle": {
+	fileHash: "target-hbc-hash",
+	downloadFileHash: RELEASE_CATALOG_DOWNLOAD_HASH,
+	downloadByteSize: 1e3
+} };
+const releaseCatalogArtifact = (bundle) => ({
+	artifactProtocolVersion: 1,
+	manifestUrl: releaseCatalogDownloadUrl(bundle.manifest_storage_uri),
+	manifestFileHash: bundle.manifest_file_hash,
+	assets: { "index.ios.bundle": {
+		fileHash: "target-hbc-hash",
+		file: {
+			compression: "br",
+			url: releaseCatalogDownloadUrl(`${bundle.asset_base_storage_uri}/sha256/aa/${RELEASE_CATALOG_DOWNLOAD_HASH}.br`)
+		}
+	} }
+});
+/** Install these storage objects in the test server, independently of its DB. */
+const RELEASE_CATALOG_STORAGE_FIXTURES = Object.fromEntries(Object.entries(RELEASE_CATALOG_MANIFEST_URIS).map(([size, uri]) => [uri, JSON.stringify({
+	bundleId: targetId,
+	assets: manifestAssets,
+	archive: {
+		downloadFileHash: "b".repeat(64),
+		downloadByteSize: size === "small" ? 1 : 1e4,
+		tarByteSize: 2e4
+	}
+})]));
+/** Storage boundary shared by provider and separately spawned server tests. */
+const createReleaseCatalogTestStorage = () => ({
+	name: "catalog-test-storage",
+	protocol: "storage",
+	async get({ storageUri }) {
+		const suffix = /^storage:\/\/bundles\/([^/]+)\/manifest\.json$/.exec(storageUri)?.[1];
+		const body = RELEASE_CATALOG_STORAGE_FIXTURES[storageUri] ?? (suffix === void 0 ? void 0 : JSON.stringify({
+			bundleId: createBundleRowFixture(suffix).id,
+			assets: manifestAssets
+		}));
+		return { response: body === void 0 ? null : new Response(body) };
+	},
+	async getDownloadUrl({ storageUri }) {
+		return { url: releaseCatalogDownloadUrl(storageUri) };
+	}
+});
+//#endregion
+//#region src/releaseCatalogLifecycleTests.ts
+function setupReleaseCatalogLifecycleTests(options) {
+	const device = (minimumReleaseId = NIL_UUID) => ({
+		builtInBundleId: minimumReleaseId,
+		currentBundleId: minimumReleaseId,
+		activeReleaseId: null,
+		minimumReleaseId,
+		cohort: "1",
+		crashedBundleIds: []
+	});
+	const refresh = async (previous) => {
+		let next = previous;
+		await expect.poll(async () => {
+			next = await options.readCatalog();
+			return next.generation;
+		}, {
+			interval: 100,
+			timeout: 1e4
+		}).toBeGreaterThan(previous.generation);
+		expect(next.catalogId).toBe(previous.catalogId);
+		expect(next.catalogHash).not.toBe(previous.catalogHash);
+		return next;
+	};
+	const install = async (catalog, app, target, status) => {
+		const desired = selectDesiredRelease(catalog, app);
+		expect(desired).toMatchObject({
+			kind: "BUNDLE",
+			releaseId: target.release.id,
+			bundleId: target.bundle.id,
+			status,
+			release: {
+				message: target.release.message,
+				shouldForceUpdate: target.release.should_force_update
+			}
+		});
+		const response = await options.request(`/artifacts/v1/${desired.bundleId}/from/${app.currentBundleId}`);
+		expect(response.status).toBe(200);
+		expect(await response.json()).toEqual(releaseCatalogArtifact(target.bundle));
+		app.currentBundleId = desired.bundleId;
+		app.activeReleaseId = desired.releaseId;
+	};
+	const useBuiltin = (catalog, app) => {
+		expect(selectDesiredRelease(catalog, app)).toEqual({
+			kind: "BUILTIN",
+			releaseId: null,
+			bundleId: app.builtInBundleId,
+			release: null,
+			status: "ROLLBACK"
+		});
+		app.currentBundleId = app.builtInBundleId;
+		app.activeReleaseId = null;
+	};
+	const staysOn = (catalog, app) => {
+		expect(selectDesiredRelease(catalog, app)).toMatchObject({
+			bundleId: app.currentBundleId,
+			releaseId: app.activeReleaseId
+		});
+	};
+	describe("OTA lifecycle through HTTP and the client selector", () => {
+		it("runs built-in → OTA A → OTA B → rollback A → built-in after policy changes", async () => {
+			const app = device();
+			const first = await options.publish("801");
+			const second = await options.publish("802", {
+				enabled: false,
+				should_force_update: true
+			});
+			let catalog = await options.readCatalog();
+			await install(catalog, app, first, "UPDATE");
+			staysOn(catalog, app);
+			await options.update(second.release.id, { enabled: true });
+			catalog = await refresh(catalog);
+			await install(catalog, app, second, "UPDATE");
+			staysOn(catalog, app);
+			await options.update(second.release.id, { enabled: false });
+			catalog = await refresh(catalog);
+			await install(catalog, app, first, "ROLLBACK");
+			staysOn(catalog, app);
+			await options.update(first.release.id, { enabled: false });
+			catalog = await refresh(catalog);
+			useBuiltin(catalog, app);
+			staysOn(catalog, app);
+		}, 4e4);
+		it("rolls a deleted active Release back to older OTA bytes, then to built-in", async () => {
+			const app = device();
+			const first = await options.publish("811");
+			const second = await options.publish("812");
+			let catalog = await options.readCatalog();
+			await install(catalog, app, second, "UPDATE");
+			await options.remove(second.release.id);
+			catalog = await refresh(catalog);
+			await install(catalog, app, first, "ROLLBACK");
+			await options.remove(first.release.id);
+			catalog = await refresh(catalog);
+			useBuiltin(catalog, app);
+			staysOn(catalog, app);
+		}, 3e4);
+		it("respects the native minimum on fresh install and rollback with or without a Release receipt", async () => {
+			await options.publish("821");
+			const current = await options.publish("823", { enabled: false });
+			const app = device(createBundleRowFixture("822").id);
+			const catalog = await options.readCatalog();
+			useBuiltin(catalog, app);
+			for (const activeReleaseId of [current.release.id, null]) {
+				app.currentBundleId = current.bundle.id;
+				app.activeReleaseId = activeReleaseId;
+				useBuiltin(catalog, app);
+			}
+			expect(selectDesiredRelease(catalog, {
+				...device(current.bundle.id),
+				activeReleaseId: current.release.id
+			})).toBeNull();
+		});
+		it("re-evaluates cohort changes and rolls back even when the predecessor rollout is closed", async () => {
+			const app = {
+				...device(),
+				cohort: "staff"
+			};
+			const first = await options.publish("831", {
+				rollout_cohort_count: 0,
+				target_cohorts: ["staff"]
+			});
+			const second = await options.publish("832", {
+				rollout_cohort_count: 0,
+				target_cohorts: ["staff"]
+			});
+			const catalog = await options.readCatalog();
+			await install(catalog, app, second, "UPDATE");
+			app.cohort = "1";
+			await install(catalog, app, first, "ROLLBACK");
+			useBuiltin(catalog, app);
+			staysOn(catalog, app);
+		});
+		it("does not reinstall crashed OTAs after native recovery to a previous OTA or built-in", async () => {
+			const app = device();
+			const first = await options.publish("841");
+			const second = await options.publish("842", { enabled: false });
+			let catalog = await options.readCatalog();
+			await install(catalog, app, first, "UPDATE");
+			await options.update(second.release.id, { enabled: true });
+			catalog = await refresh(catalog);
+			await install(catalog, app, second, "UPDATE");
+			app.currentBundleId = first.bundle.id;
+			app.activeReleaseId = first.release.id;
+			app.crashedBundleIds = [second.bundle.id];
+			staysOn(catalog, app);
+			app.currentBundleId = app.builtInBundleId;
+			app.activeReleaseId = null;
+			app.crashedBundleIds = [first.bundle.id, second.bundle.id];
+			useBuiltin(catalog, app);
+			staysOn(catalog, app);
+			const fixed = await options.publish("843");
+			catalog = await refresh(catalog);
+			await install(catalog, app, fixed, "UPDATE");
+			staysOn(catalog, app);
+		}, 25e3);
+		it("selects a compatible OTA and stays on it despite a newer incompatible Release", async () => {
+			const app = device();
+			const compatible = await options.publish("851");
+			await options.publishIncompatible("852");
+			const catalog = await options.readCatalog();
+			await install(catalog, app, compatible, "UPDATE");
+			staysOn(catalog, app);
+		});
+	});
+}
+//#endregion
+//#region src/setupReleaseCatalogTestSuite.ts
+const NIL_UUID$1 = "00000000-0000-0000-0000-000000000000";
+const FALLBACK_POLICY = "BUILTIN_IF_ACTIVE_INELIGIBLE";
+const channelKey = (channel) => btoa(String.fromCharCode(...new TextEncoder().encode(channel))).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+/**
+* Server conformance through HTTP only, on admin API protocol 2. The caller
+* owns server, database, and storage setup. Releases are written with
+* `POST /releases` and changed with `PATCH /releases/:id`; lifecycle scenarios
+* feed HTTP catalogs to the production client selector. Each test deletes
+* what it wrote, so a long-lived server can run the suite again.
+*/
+const setupReleaseCatalogTestSuite = (options) => {
+	describe("Release Catalog HTTP contract", () => {
+		let channelNamespace;
+		const api = createAdminApiTestClient(options.getClient);
+		const { admin, adminJson } = api;
+		beforeEach(() => {
+			channelNamespace = crypto.randomUUID();
+		});
+		afterEach(async () => {
+			await api.cleanup();
+		}, 18e4);
+		const request = (path, init) => options.getClient().client(path, init);
+		const bundleRow = (suffix) => createBundleRowFixture(suffix);
+		for (const strategy of ["APP_VERSION", "FINGERPRINT"]) describe(strategy, () => {
+			const scope = (channel = "production", platform = "ios", fingerprint = "fingerprint-a") => {
+				channel = `${channel}-${channelNamespace}`;
+				const encodedChannel = channelKey(channel);
+				return {
+					channel,
+					channelKey: encodedChannel,
+					platform,
+					fingerprint: strategy === "FINGERPRINT" ? fingerprint : null,
+					key: strategy === "APP_VERSION" ? `v1:app-version:${platform}:${encodedChannel}` : `v1:fingerprint:${platform}:${encodedChannel}:${fingerprint}`
+				};
+			};
+			const catalogPath = (target = scope(), appVersion = "1.2.3") => `/release-catalogs/${strategy === "APP_VERSION" ? "app-version" : "fingerprint"}/${target.platform}/${target.channelKey}/${strategy === "APP_VERSION" ? appVersion : target.fingerprint}`;
+			const catalogRowPath = (target = scope()) => `/release-catalogs/${encodeURIComponent(target.key)}`;
+			const readCatalog = async (target = scope(), appVersion = "1.2.3") => {
+				const response = await request(catalogPath(target, appVersion));
+				expect(response.status).toBe(200);
+				expect(response.headers.get("content-type")).toBe("application/vnd.hot-updater.release-catalog+json; version=1");
+				expect(response.headers.get("cache-control")).toBe("public, max-age=0, s-maxage=5");
+				const catalog = await response.json();
+				expect(catalog).toMatchObject({
+					schemaVersion: 1,
+					scopeKey: target.key,
+					fallbackPolicy: FALLBACK_POLICY,
+					catalogId: expect.any(String),
+					catalogHash: expect.stringMatching(/^sha256:[0-9a-f]{64}$/)
+				});
+				return catalog;
+			};
+			/** Deploys a new bundle, or a stored one named by `bundle_id`, into `target`. */
+			const publish = async (suffix, patch = {}, target = scope()) => {
+				const bundle = {
+					...bundleRow(suffix),
+					platform: target.platform,
+					asset_base_storage_uri: "storage://test-bucket/assets"
+				};
+				const policy = {
+					channel: target.channel,
+					enabled: patch.enabled ?? true,
+					fingerprintHash: target.fingerprint,
+					message: patch.message === void 0 ? `release-${suffix}` : patch.message,
+					shouldForceUpdate: patch.should_force_update ?? false,
+					targetAppVersion: strategy === "APP_VERSION" ? patch.target_app_version ?? "*" : null,
+					...patch.rollout_cohort_count === void 0 ? {} : { rolloutCohortCount: patch.rollout_cohort_count },
+					...patch.target_cohorts === void 0 ? {} : { targetCohorts: [...patch.target_cohorts] }
+				};
+				const release = await api.deploy(patch.bundle_id === void 0 || patch.bundle_id === null ? {
+					bundle: toDeployBundle(bundle),
+					release: policy
+				} : {
+					bundleId: patch.bundle_id,
+					release: policy
+				});
+				return {
+					bundle: patch.bundle_id === void 0 || patch.bundle_id === null ? bundle : {
+						...bundle,
+						id: patch.bundle_id
+					},
+					release
+				};
+			};
+			const update = (releaseId, patch) => adminJson(`/releases/${releaseId}`, jsonRequest("PATCH", { patch }));
+			setupReleaseCatalogLifecycleTests({
+				readCatalog,
+				publish,
+				publishIncompatible: (suffix) => strategy === "APP_VERSION" ? publish(suffix, { target_app_version: ">=1.2.4" }) : publish(suffix, {}, scope("production", "ios", "fingerprint-b")),
+				update,
+				remove: async (id) => {
+					await update(id, { enabled: false });
+					await adminJson(`/releases/${id}?confirm=${id}&expectedRevision=2`, jsonRequest("DELETE"));
+					expect((await admin(`/releases/${id}`)).status).toBe(404);
+					api.forget(id);
+				},
+				request
+			});
+			it("pages all scoped Releases including disabled rows with an exclusive cursor", async () => {
+				const first = await publish("701");
+				const disabled = await publish("702", { enabled: false });
+				await publish("703", {}, scope("other"));
+				const path = `/releases?scopeKey=${encodeURIComponent(scope().key)}&limit=1&order=asc`;
+				const page1 = await adminJson(path);
+				expect(page1.data).toEqual([first.release]);
+				expect(page1.next).toBe(first.release.id);
+				const page2 = await adminJson(`${path}&cursor=${page1.next}`);
+				expect(page2.data).toEqual([disabled.release]);
+				expect((await adminJson(`${path}&cursor=${page2.next}`)).data).toEqual([]);
+				expect((await adminJson(`/releases?scopeKey=${encodeURIComponent(scope().key)}&enabled=false`)).data).toEqual([disabled.release]);
+			});
+			it("lets one of two concurrent policy changes at the same revision win", async () => {
+				const current = await publish("721");
+				const catalog = (await adminJson(catalogRowPath())).data;
+				const responses = await Promise.all(["first", "second"].map((message) => admin(`/releases/${current.release.id}`, jsonRequest("PATCH", {
+					expectedRevision: 1,
+					patch: { message }
+				}))));
+				const statuses = responses.map(({ status }) => status).sort();
+				expect(statuses).toEqual([200, 409]);
+				const winner = responses.findIndex(({ status }) => status === 200);
+				const loser = responses[1 - winner];
+				expect(await loser.json()).toMatchObject({ code: "VERSION_CONFLICT" });
+				await responses[winner].text();
+				expect((await adminJson(`/releases/${current.release.id}`)).data).toMatchObject({
+					revision: 2,
+					message: ["first", "second"][winner]
+				});
+				expect((await adminJson(catalogRowPath())).data).toMatchObject({ generation: catalog.generation + 1 });
+			});
+			it("hard deletes a Release, rebuilds its Catalog, and retains Bundle bytes", async () => {
+				const current = await publish("741", { enabled: false });
+				await adminJson(`/releases/${current.release.id}?confirm=${current.release.id}&expectedRevision=1`, jsonRequest("DELETE"));
+				api.forget(current.release.id);
+				expect((await admin(`/releases/${current.release.id}`)).status).toBe(404);
+				expect(await readCatalog()).toMatchObject({
+					releases: [],
+					rollbackReleases: []
+				});
+				const artifact = await request(`/artifacts/v1/${current.bundle.id}/from/${NIL_UUID$1}`);
+				expect(artifact.status).toBe(200);
+				expect(await artifact.json()).toMatchObject({ manifestUrl: releaseCatalogDownloadUrl(current.bundle.manifest_storage_uri) });
+			});
+			it("serves enabled Releases newest first and resolves artifacts by Bundle identity", async () => {
+				const first = await publish("101");
+				const { bundle, release } = await publish("102", {
+					message: "업데이트",
+					should_force_update: true
+				});
+				await publish("103", { enabled: false });
+				const catalog = await readCatalog();
+				expect(catalog.releases.map((item) => item.releaseId)).toEqual([release.id, first.release.id]);
+				expect(catalog.releases[0]).toMatchObject({
+					bundleId: bundle.id,
+					message: "업데이트",
+					shouldForceUpdate: true
+				});
+				const response = await request(`/artifacts/v1/${bundle.id}/from/${NIL_UUID$1}`);
+				expect(response.status).toBe(200);
+				expect(response.headers.get("cache-control")).toBe("private, no-store");
+				expect(await response.json()).toEqual(releaseCatalogArtifact(bundle));
+				expect((await request(`/artifacts/v1/${release.id}/from/${NIL_UUID$1}`)).status).toBe(404);
+			});
+			it("isolates channels, platforms, and update strategies", async () => {
+				const stable = await publish("111");
+				const beta = await publish("112", {}, scope("beta / 한글"));
+				const android = await publish("113", {}, scope("production", "android"));
+				for (const [target, release] of [
+					[scope(), stable.release],
+					[scope("beta / 한글"), beta.release],
+					[scope("production", "android"), android.release]
+				]) expect((await readCatalog(target)).releases.map((item) => item.releaseId)).toEqual([release.id]);
+				const otherPath = strategy === "APP_VERSION" ? `/release-catalogs/fingerprint/ios/${scope().channelKey}/fingerprint-a` : `/release-catalogs/app-version/ios/${scope().channelKey}/1.2.3`;
+				expect((await request(otherPath)).status).toBe(404);
+			});
+			it("returns an uncached 404 for an unknown scope", async () => {
+				const response = await request(catalogPath());
+				expect(response.status).toBe(404);
+				expect(response.headers.get("cache-control")).toBe("private, no-store");
+				await publish("121");
+				expect((await readCatalog()).releases).toHaveLength(1);
+			});
+			it("preserves rollout and named cohort policy without server-side cohort selection", async () => {
+				const stable = await publish("131");
+				const partial = await publish("132", { rollout_cohort_count: 500 });
+				const targeted = await publish("133", {
+					rollout_cohort_count: 0,
+					target_cohorts: ["qa"]
+				});
+				const catalog = await readCatalog();
+				expect(catalog.releases.map(({ releaseId, rolloutCohortCount, targetCohorts }) => ({
+					releaseId,
+					rolloutCohortCount,
+					targetCohorts
+				}))).toEqual([
+					{
+						releaseId: targeted.release.id,
+						rolloutCohortCount: 0,
+						targetCohorts: ["qa"]
+					},
+					{
+						releaseId: partial.release.id,
+						rolloutCohortCount: 500,
+						targetCohorts: []
+					},
+					{
+						releaseId: stable.release.id,
+						rolloutCohortCount: 1e3,
+						targetCohorts: []
+					}
+				]);
+			});
+			it("keeps the newest Release policy when Bundle bytes are reused", async () => {
+				const first = await publish("141");
+				const second = await publish("142", {
+					bundle_id: first.bundle.id,
+					message: "new policy"
+				});
+				const catalog = await readCatalog();
+				expect(catalog.releases[0]).toMatchObject({
+					releaseId: second.release.id,
+					bundleId: first.bundle.id,
+					message: "new policy"
+				});
+				expect(catalog.rollbackReleases?.map((item) => item.releaseId)).toEqual([second.release.id, first.release.id]);
+			});
+			it("revalidates immutable responses against the persisted Catalog", async () => {
+				await publish("161");
+				const response = await request(catalogPath());
+				const catalog = await response.json();
+				const etag = response.headers.get("etag");
+				expect(etag).toMatch(/^"sha256:[0-9a-f]{64}"$/);
+				const revalidated = await request(catalogPath(), { headers: { "if-none-match": etag } });
+				expect(revalidated.status).toBe(304);
+				expect(await revalidated.text()).toBe("");
+				const persisted = await adminJson(catalogRowPath());
+				expect(persisted.data).toMatchObject({
+					catalog_id: catalog.catalogId,
+					catalog_hash: catalog.catalogHash,
+					generation: catalog.generation
+				});
+				const rebuild = await adminJson(`${catalogRowPath()}/rebuild`, jsonRequest("POST"));
+				expect(rebuild.data.changed).toBe(false);
+				expect(rebuild.data.catalog.generation).toBe(catalog.generation);
+			});
+			it("refreshes a cached Catalog after HTTP policy changes and retains rollback candidates", async () => {
+				const predecessor = await publish("171", { rollout_cohort_count: 0 });
+				const current = await publish("172");
+				const response = await request(catalogPath());
+				const previous = await response.json();
+				await update(current.release.id, { enabled: false });
+				let refreshed;
+				await expect.poll(async () => {
+					const next = await request(catalogPath(), { headers: { "if-none-match": response.headers.get("etag") } });
+					const text = await next.text();
+					if (next.status === 200) refreshed = JSON.parse(text);
+					return next.status;
+				}, {
+					interval: 100,
+					timeout: 1e4
+				}).toBe(200);
+				expect(refreshed).toMatchObject({
+					catalogId: previous.catalogId,
+					generation: previous.generation + 1,
+					releases: []
+				});
+				expect(refreshed?.catalogHash).not.toBe(previous.catalogHash);
+				expect(refreshed?.rollbackReleases).toEqual([expect.objectContaining({
+					releaseId: predecessor.release.id,
+					bundleId: predecessor.bundle.id,
+					rolloutCohortCount: 0
+				})]);
+			}, 15e3);
+			it("publishes an empty tombstone after the last Release is disabled", async () => {
+				const current = await publish("181");
+				await update(current.release.id, { enabled: false });
+				expect(await readCatalog()).toMatchObject({
+					releases: [],
+					rollbackReleases: [],
+					fallbackPolicy: FALLBACK_POLICY
+				});
+				expect((await adminJson(catalogRowPath())).data.is_tombstone).toBe(true);
+			});
+			it("returns HTTP 409 for stale policy revisions without changing the persisted Catalog", async () => {
+				const current = await publish("191");
+				await update(current.release.id, { message: "new policy" });
+				const before = await adminJson(catalogRowPath());
+				const response = await admin(`/releases/${current.release.id}`, jsonRequest("PATCH", {
+					expectedRevision: 1,
+					patch: { enabled: false }
+				}));
+				expect(response.status).toBe(409);
+				expect(await response.json()).toMatchObject({ code: "VERSION_CONFLICT" });
+				expect(await adminJson(catalogRowPath())).toEqual(before);
+				expect((await adminJson(`/releases/${current.release.id}`)).data).toMatchObject({
+					enabled: true,
+					revision: 2,
+					message: "new policy"
+				});
+			});
+			if (strategy === "APP_VERSION") {
+				it("pages each release filter set by key, newest first", async () => {
+					const first = await publish("751", { enabled: false });
+					const second = await publish("752", {
+						bundle_id: first.bundle.id,
+						enabled: false
+					});
+					const third = await publish("753");
+					const elsewhere = await publish("754", { bundle_id: first.bundle.id }, scope("other"));
+					await publish("755", {}, scope("production", "android"));
+					const { data: channel } = await adminJson(`/channels?name=${encodeURIComponent(scope().channel)}`);
+					/** Every page of one filter set, one release per page. */
+					const pages = async (query) => {
+						const ids = [];
+						let cursor;
+						do {
+							const page = await adminJson(`/releases?${query}&limit=1${cursor === void 0 ? "" : `&cursor=${cursor}`}`);
+							ids.push(...page.data.map(({ id }) => id));
+							cursor = page.next;
+						} while (cursor !== void 0);
+						return ids;
+					};
+					const newestFirst = (...published) => published.map(({ release }) => release.id).sort().reverse();
+					const byChannel = `channelId=${channel.id}&platform=ios`;
+					expect(await pages(byChannel)).toEqual(newestFirst(first, second, third));
+					expect(await pages(`${byChannel}&enabled=false`)).toEqual(newestFirst(first, second));
+					expect(await pages(`bundleId=${first.bundle.id}`)).toEqual(newestFirst(first, second, elsewhere));
+					expect(await pages(`scopeKey=${encodeURIComponent(scope().key)}&enabled=true`)).toEqual(newestFirst(third));
+					expect((await admin(`/releases?platform=ios&enabled=false`)).status).toBe(400);
+				});
+				it("serves the newest Release among 200 distinct compatible version ranges", async () => {
+					await publish("400", { target_app_version: ">=0.0.0" });
+					for (let index = 1; index < 200; index++) await publish(String(400 + index), { target_app_version: `>=0.${index}.0` });
+					const catalog = await readCatalog(scope(), "1.0.0");
+					expect(catalog.releases[0]?.bundleId).toBe(bundleRow("599").id);
+					expect(catalog.rollbackReleases).toHaveLength(200);
+				}, 18e4);
+				it("keeps version projections separate in the HTTP cache", async () => {
+					const first = await publish("231", { target_app_version: "^1.0.0" });
+					const second = await publish("232", { target_app_version: "^2.0.0" });
+					for (const [version, releaseId] of [
+						["1.2.3", first.release.id],
+						["2.1.0", second.release.id],
+						["1.2.3", first.release.id]
+					]) expect((await readCatalog(scope(), version)).releases.map((release) => release.releaseId)).toEqual([releaseId]);
+				});
+				it.each([
+					[
+						"*",
+						"1.2.3",
+						true
+					],
+					[
+						"1.2.3",
+						"1.2.3",
+						true
+					],
+					[
+						"^1.0.0",
+						"1.2.3",
+						true
+					],
+					[
+						">=1.0.0 <2.0.0",
+						"2.0.0",
+						false
+					],
+					[
+						"~1.2.0",
+						"1.3.0",
+						false
+					],
+					[
+						"^1.0.0 || ^3.0.0",
+						"3.1.0",
+						true
+					],
+					[
+						">= 5.7.0 <= 5.7.4",
+						"5.7.3",
+						true
+					],
+					[
+						">= 5.7.0 <= 5.7.4",
+						"5.7.5",
+						false
+					]
+				])("projects %s for app version %s (compatible: %s)", async (range, version, compatible) => {
+					const current = await publish("201", { target_app_version: range });
+					expect((await readCatalog(scope(), version)).releases.map((item) => item.releaseId)).toEqual(compatible ? [current.release.id] : []);
+				});
+				it("rejects noncanonical versions and unsupported platforms with HTTP 400", async () => {
+					await publish("211");
+					for (const path of [catalogPath(scope(), "v1.2"), catalogPath().replace("/ios/", "/windows/")]) {
+						const response = await request(path);
+						expect(response.status).toBe(400);
+						expect(response.headers.get("cache-control")).toBe("private, no-store");
+					}
+				});
+			} else {
+				it("pages Catalogs in scope order with an exclusive cursor and limit", async () => {
+					const first = scope("production", "ios", "paging-a");
+					const second = scope("production", "ios", "paging-b");
+					await publish("761", {}, second);
+					await publish("762", {}, first);
+					const prefix = first.key.slice(0, -1);
+					const page1 = await adminJson(`/release-catalogs?limit=1&order=asc&cursor=${encodeURIComponent(prefix)}`);
+					expect(page1.data).toEqual([(await adminJson(catalogRowPath(first))).data]);
+					expect(page1.next).toBe(first.key);
+					expect((await adminJson(`/release-catalogs?limit=1&order=asc&cursor=${encodeURIComponent(page1.next)}`)).data).toEqual([(await adminJson(catalogRowPath(second))).data]);
+				});
+				it("isolates exact fingerprints", async () => {
+					const first = await publish("221");
+					const second = await publish("222", {}, scope("production", "ios", "fingerprint-b"));
+					expect((await readCatalog()).releases.map((item) => item.releaseId)).toEqual([first.release.id]);
+					expect((await readCatalog(scope("production", "ios", "fingerprint-b"))).releases.map((item) => item.releaseId)).toEqual([second.release.id]);
+					expect((await request(catalogPath(scope("production", "ios", "unknown")))).status).toBe(404);
+				});
+			}
+		});
+		it.each(["small", "large"])("retains original and patch plans alongside a %s optional archive", async (size) => {
+			const policy = {
+				channel: `artifacts-${channelNamespace}`,
+				enabled: false,
+				fingerprintHash: null,
+				message: null,
+				shouldForceUpdate: false,
+				targetAppVersion: "*"
+			};
+			const base = bundleRow("301");
+			const target = {
+				...bundleRow("302"),
+				manifest_storage_uri: RELEASE_CATALOG_MANIFEST_URIS[size],
+				manifest_file_hash: "manifest-hash",
+				asset_base_storage_uri: "storage://test-bucket/assets"
+			};
+			const patch = {
+				...createBundlePatchRowFixture("302", target.id, base.id),
+				byte_size: 10
+			};
+			await api.deploy({
+				bundle: toDeployBundle(base),
+				release: policy
+			});
+			await api.deploy({
+				bundle: {
+					...toDeployBundle(target),
+					patches: [{
+						baseBundleId: base.id,
+						baseFileHash: patch.base_file_hash,
+						byteSize: patch.byte_size,
+						patchFileHash: patch.patch_file_hash,
+						patchStorageUri: patch.patch_storage_uri
+					}]
+				},
+				release: policy
+			});
+			const response = await request(`/artifacts/v1/${target.id}/from/${base.id}`);
+			expect(response.status).toBe(200);
+			const artifact = await response.json();
+			const original = releaseCatalogArtifact(target);
+			const archiveUrl = releaseCatalogDownloadUrl(target.manifest_storage_uri.replace("manifest.json", "bundle.tar.br"));
+			expect(artifact).toEqual({
+				...original,
+				archiveUrl,
+				assets: { "index.ios.bundle": {
+					...original.assets["index.ios.bundle"],
+					patch: {
+						algorithm: "bsdiff",
+						baseBundleId: base.id,
+						baseFileHash: patch.base_file_hash,
+						patchFileHash: patch.patch_file_hash,
+						patchUrl: releaseCatalogDownloadUrl(patch.patch_storage_uri),
+						byteSize: patch.byte_size
+					}
+				} }
+			});
+			const freshInstall = await request(`/artifacts/v1/${target.id}/from/${NIL_UUID$1}`);
+			expect(freshInstall.status).toBe(200);
+			expect(await freshInstall.json()).toEqual({
+				...original,
+				archiveUrl
+			});
+		});
+	});
+};
+//#endregion
+//#region src/setupDatabaseTestSuite.ts
+/**
+* A provider's database under Hot Updater's server: core's operations, the
+* Release Catalog contract, bundles, and Insights, all through HTTP, on the
+* tables the provider's tooling creates; with `createInsightsModel`, also the
+* Insights report contract in process.
+*/
+const setupDatabaseTestSuite = (options) => {
+	setupDatabaseTestRunner(options, ({ getDatabase }) => {
+		let client;
+		beforeEach(async () => {
+			client = await options.createHttpClient({
+				database: getDatabase(),
+				storage: [createReleaseCatalogTestStorage()]
+			});
+		});
+		afterEach(async () => {
+			await client?.close();
+			client = void 0;
+		});
+		const getClient = () => {
+			if (client === void 0) throw new Error("HTTP test server has not started");
+			return client;
+		};
+		setupCoreAdminTestSuite({ getClient });
+		setupBundleMethodsTestSuite({ getClient });
+		setupReleaseCatalogTestSuite({ getClient });
+		setupInsightsHttpTestSuite({ getClient });
+		const { createInsightsModel } = options;
+		if (createInsightsModel !== void 0) describe("Insights model", () => {
+			registerInsightsModelTests({ getDatabase: () => createInsightsModel(getDatabase()) });
+		});
+	});
+};
+//#endregion
+//#region src/setupDatabaseAdapterConformanceSuite.ts
+const conformanceItems = {
+	name: "conformance_items",
+	columns: [
+		{
+			name: "id",
+			type: "string",
+			nullable: false,
+			maxLength: 64
+		},
+		{
+			name: "grp",
+			type: "string",
+			nullable: false,
+			maxLength: 64
+		},
+		{
+			name: "score",
+			type: "integer",
+			nullable: false
+		},
+		{
+			name: "ratio",
+			type: "number",
+			nullable: true
+		},
+		{
+			name: "flag",
+			type: "boolean",
+			nullable: false
+		},
+		{
+			name: "label",
+			type: "string",
+			nullable: true,
+			maxLength: 255
+		},
+		{
+			name: "tags",
+			type: "string",
+			nullable: true,
+			maxLength: 64,
+			multi: true
+		},
+		{
+			name: "payload",
+			type: "json",
+			nullable: true
+		},
+		{
+			name: "note",
+			type: "string",
+			nullable: true
+		},
+		{
+			name: "_v",
+			type: "integer",
+			nullable: false
+		}
+	],
+	key: ["id"],
+	indexes: [
+		{
+			name: "all",
+			eq: [],
+			sort: ["id"]
+		},
+		{
+			name: "byGroup",
+			eq: ["grp"],
+			sort: ["score"]
+		},
+		{
+			name: "byGroupFlag",
+			eq: ["grp", "flag"],
+			sort: ["score"]
+		},
+		{
+			name: "byLabel",
+			eq: ["label"],
+			sort: [],
+			unique: true
+		},
+		{
+			name: "byTag",
+			eq: ["tags"],
+			sort: ["score"]
+		}
+	]
+};
+const conformanceCounters = {
+	name: "conformance_counters",
+	columns: [
+		{
+			name: "scope",
+			type: "string",
+			nullable: false,
+			maxLength: 64
+		},
+		{
+			name: "shard",
+			type: "integer",
+			nullable: false
+		},
+		{
+			name: "hits",
+			type: "integer",
+			nullable: false
+		},
+		{
+			name: "_v",
+			type: "integer",
+			nullable: false
+		}
+	],
+	key: ["scope", "shard"],
+	indexes: [{
+		name: "byScope",
+		eq: ["scope"],
+		sort: ["shard"]
+	}]
+};
+const tables = [conformanceItems, conformanceCounters];
+const item = (id, values = {}) => ({
+	id,
+	grp: "g",
+	score: 0,
+	ratio: null,
+	flag: false,
+	label: null,
+	tags: null,
+	payload: null,
+	note: null,
+	_v: 0,
+	...values
+});
+const counterKey = (scope, shard = 0) => [scope, shard];
+const counterInit = (scope, shard = 0) => ({
+	scope,
+	shard,
+	hits: 0,
+	_v: 0
+});
+const insert = (row) => ({
+	type: "insert",
+	table: conformanceItems,
+	row
+});
+const shuffled = (values) => values.map((value) => ({
+	value,
+	order: Math.random()
+})).sort((left, right) => left.order - right.order).map(({ value }) => value);
+/**
+* The storage-adapter conformance contract (PRD S3 and S4 cases). Every
+* adapter runs it through `verifyAdapter`, which also checks each read and
+* write at the adapter boundary.
+*/
+const setupDatabaseAdapterConformanceSuite = (options) => {
+	const writers = options.writers ?? 32;
+	let cleanup;
+	const setup = async (context = {}) => {
+		const created = await options.createAdapter({
+			tables,
+			...context
+		});
+		cleanup = created.cleanup;
+		return verifyAdapter(created.adapter, { probeShortPages: true });
+	};
+	const ok = async (adapter, ops) => expect(await adapter.write(ops)).toEqual({ ok: true });
+	const one = async (adapter, id) => (await adapter.get(conformanceItems, [[id]]))[0] ?? null;
+	const query = (adapter, request) => adapter.query(conformanceItems, {
+		order: "asc",
+		limit: 500,
+		...request
+	});
+	const ids = (rows) => rows.map((row) => row.id);
+	const snapshot = async (adapter) => ({
+		items: await query(adapter, {
+			index: "all",
+			eq: []
+		}),
+		counters: await adapter.query(conformanceCounters, {
+			index: "byScope",
+			eq: ["c"],
+			order: "asc",
+			limit: 500
+		})
+	});
+	describe(`${options.name} database adapter conformance`, () => {
+		afterEach(async () => {
+			await cleanup?.();
+			cleanup = void 0;
+		});
+		it("round-trips every value type", async () => {
+			const adapter = await setup();
+			const rows = [item("round-trip", {
+				grp: "Ωmega 😀",
+				score: Number.MAX_SAFE_INTEGER,
+				ratio: -1.25,
+				flag: true,
+				label: "",
+				tags: ["b", "a"],
+				payload: {
+					nested: {
+						list: [
+							1,
+							"two",
+							null,
+							true
+						],
+						ключ: "значение"
+					},
+					empty: {},
+					none: []
+				},
+				note: "x".repeat(1e4)
+			}), item("round-trip-min", {
+				score: Number.MIN_SAFE_INTEGER,
+				ratio: .5
+			})];
+			await ok(adapter, rows.map(insert));
+			expect(await adapter.get(conformanceItems, [["round-trip"], ["round-trip-min"]])).toEqual(rows);
+		});
+		it("reads keys in request order with null for missing keys", async () => {
+			const adapter = await setup();
+			await ok(adapter, [insert(item("a")), insert(item("b"))]);
+			expect(await adapter.get(conformanceItems, [
+				["b"],
+				["missing"],
+				["a"]
+			])).toEqual([
+				item("b"),
+				null,
+				item("a")
+			]);
+			expect(await adapter.get(conformanceItems, [])).toEqual([]);
+		});
+		it("refuses an insert over an existing key", async () => {
+			const adapter = await setup();
+			await ok(adapter, [insert(item("a", { score: 1 }))]);
+			expect(await adapter.write([insert(item("a", { score: 2 }))])).toEqual({
+				ok: false,
+				failedOp: 0
+			});
+			expect(await one(adapter, "a")).toEqual(item("a", { score: 1 }));
+		});
+		it("patches named columns, bumps _v, and refuses a stale guard", async () => {
+			const adapter = await setup();
+			const row = item("a", { note: "keep" });
+			await ok(adapter, [insert(row)]);
+			const patch = (v, id = "a") => ({
+				type: "patch",
+				table: conformanceItems,
+				key: [id],
+				set: { score: 5 },
+				guard: { v },
+				previous: row
+			});
+			await ok(adapter, [patch(0)]);
+			expect(await one(adapter, "a")).toEqual({
+				...row,
+				score: 5,
+				_v: 1
+			});
+			expect(await adapter.write([patch(0)])).toEqual({
+				ok: false,
+				failedOp: 0
+			});
+			expect(await adapter.write([patch(0, "missing")])).toEqual({
+				ok: false,
+				failedOp: 0
+			});
+		});
+		it("deletes only with a matching guard", async () => {
+			const adapter = await setup();
+			const row = item("a");
+			await ok(adapter, [insert(row)]);
+			const remove = (v) => ({
+				type: "delete",
+				table: conformanceItems,
+				key: ["a"],
+				guard: { v },
+				previous: row
+			});
+			expect(await adapter.write([remove(1)])).toEqual({
+				ok: false,
+				failedOp: 0
+			});
+			await ok(adapter, [remove(0)]);
+			expect(await one(adapter, "a")).toBeNull();
+			expect(await adapter.write([remove(0)])).toEqual({
+				ok: false,
+				failedOp: 0
+			});
+		});
+		it("increments counters, creating a missing row from init", async () => {
+			const adapter = await setup();
+			const increment = (values = {}) => ({
+				type: "increment",
+				table: conformanceCounters,
+				key: counterKey("c"),
+				by: { hits: 2 },
+				init: counterInit("c"),
+				...values
+			});
+			await ok(adapter, [increment()]);
+			await ok(adapter, [increment({ by: { hits: 3 } })]);
+			expect(await adapter.get(conformanceCounters, [counterKey("c")])).toEqual([{
+				scope: "c",
+				shard: 0,
+				hits: 5,
+				_v: 2
+			}]);
+			expect(await adapter.write([increment({ guard: { v: 1 } })])).toEqual({
+				ok: false,
+				failedOp: 0
+			});
+			expect(await adapter.write([increment({
+				key: counterKey("c", 1),
+				init: void 0
+			})])).toEqual({
+				ok: false,
+				failedOp: 0
+			});
+		});
+		it("checks a row version without writing it", async () => {
+			const adapter = await setup();
+			await ok(adapter, [insert(item("a"))]);
+			const check = (v, id = "a") => ({
+				type: "check",
+				table: conformanceItems,
+				key: [id],
+				guard: { v }
+			});
+			await ok(adapter, [check(0)]);
+			expect(await one(adapter, "a")).toEqual(item("a"));
+			expect(await adapter.write([check(1)])).toEqual({
+				ok: false,
+				failedOp: 0
+			});
+			expect(await adapter.write([check(0, "missing")])).toEqual({
+				ok: false,
+				failedOp: 0
+			});
+		});
+		it("applies nothing when an op at any position fails", async () => {
+			const adapter = await setup();
+			const rows = [
+				item("a"),
+				item("b"),
+				item("d"),
+				item("e")
+			];
+			await ok(adapter, [...rows.map(insert), {
+				type: "increment",
+				table: conformanceCounters,
+				key: counterKey("c"),
+				by: { hits: 1 },
+				init: counterInit("c")
+			}]);
+			const before = await snapshot(adapter);
+			const batch = (stale) => [
+				insert(item(stale === 0 ? "e" : "x")),
+				{
+					type: "patch",
+					table: conformanceItems,
+					key: ["a"],
+					set: { score: 9 },
+					guard: { v: stale === 1 ? 7 : 0 },
+					previous: rows[0]
+				},
+				{
+					type: "delete",
+					table: conformanceItems,
+					key: ["b"],
+					guard: { v: stale === 2 ? 7 : 0 },
+					previous: rows[1]
+				},
+				{
+					type: "increment",
+					table: conformanceCounters,
+					key: counterKey("c"),
+					by: { hits: 1 },
+					guard: { v: stale === 3 ? 7 : 1 }
+				},
+				{
+					type: "check",
+					table: conformanceItems,
+					key: ["d"],
+					guard: { v: stale === 4 ? 7 : 0 }
+				}
+			];
+			for (let stale = 0; stale < 5; stale += 1) {
+				expect(await adapter.write(batch(stale))).toEqual({
+					ok: false,
+					failedOp: stale
+				});
+				expect(await snapshot(adapter)).toEqual(before);
+			}
+			await ok(adapter, batch(-1));
+			expect(ids(await query(adapter, {
+				index: "all",
+				eq: []
+			}))).toEqual([
+				"a",
+				"d",
+				"e",
+				"x"
+			]);
+		});
+		it("refuses a duplicate on a unique index with the failing op", async () => {
+			const adapter = await setup();
+			await ok(adapter, [insert(item("a", { label: "L" }))]);
+			expect(await adapter.write([insert(item("b", { label: "M" })), insert(item("c", { label: "L" }))])).toEqual({
+				ok: false,
+				failedOp: 1
+			});
+			expect(await one(adapter, "b")).toBeNull();
+			await ok(adapter, [insert(item("b", { label: "M" }))]);
+			expect(await adapter.write([{
+				type: "patch",
+				table: conformanceItems,
+				key: ["b"],
+				set: { label: "L" },
+				guard: { v: 0 },
+				previous: item("b", { label: "M" })
+			}])).toEqual({
+				ok: false,
+				failedOp: 0
+			});
+			await ok(adapter, [insert(item("d")), insert(item("e"))]);
+			await ok(adapter, [{
+				type: "delete",
+				table: conformanceItems,
+				key: ["a"],
+				guard: { v: 0 },
+				previous: item("a", { label: "L" })
+			}, insert(item("f", { label: "L" }))]);
+			expect(ids(await query(adapter, {
+				index: "byLabel",
+				eq: ["L"]
+			}))).toEqual(["f"]);
+		});
+		it("orders strings by UTF-8 bytes and numbers numerically", async () => {
+			const adapter = await setup();
+			const names = [
+				"b",
+				"B",
+				"a",
+				"a ",
+				"é",
+				"z",
+				"😀",
+				"ff",
+				"10",
+				"9"
+			];
+			const scores = [
+				10,
+				-5,
+				2,
+				0,
+				Number.MAX_SAFE_INTEGER
+			];
+			await ok(adapter, [...names.map((id) => insert(item(id, { grp: "names" }))), ...scores.map((score) => insert(item(`n${score}`, {
+				grp: "n",
+				score
+			})))]);
+			expect(ids(await query(adapter, {
+				index: "byGroup",
+				eq: ["names"]
+			}))).toEqual([
+				"10",
+				"9",
+				"B",
+				"a",
+				"a ",
+				"b",
+				"z",
+				"é",
+				"ff",
+				"😀"
+			]);
+			const byScore = await query(adapter, {
+				index: "byGroup",
+				eq: ["n"]
+			});
+			expect(byScore.map((row) => row.score)).toEqual([
+				-5,
+				0,
+				2,
+				10,
+				Number.MAX_SAFE_INTEGER
+			]);
+			const reversed = await query(adapter, {
+				index: "byGroup",
+				eq: ["n"],
+				order: "desc"
+			});
+			expect(ids(reversed)).toEqual(ids(byScore).toReversed());
+		});
+		it("pages through eq and bounds from a cursor without gaps or repeats", async () => {
+			const adapter = await setup();
+			const rows = Array.from({ length: 23 }, (_, index) => item(`p${String(index).padStart(2, "0")}`, {
+				grp: "p",
+				score: Math.floor(index / 2),
+				flag: index % 3 === 0
+			}));
+			await ok(adapter, [...rows.map(insert), insert(item("q", {
+				grp: "q",
+				score: 3
+			}))]);
+			for (const order of ["asc", "desc"]) {
+				const read = [];
+				for (;;) {
+					const last = read.at(-1);
+					const bound = last === void 0 ? {} : { [order === "asc" ? "lower" : "upper"]: {
+						values: indexOrderTuple(conformanceItems, findPhysicalIndex(conformanceItems, "byGroup"), last),
+						inclusive: false
+					} };
+					const page = await query(adapter, {
+						index: "byGroup",
+						eq: ["p"],
+						order,
+						limit: 3,
+						...bound
+					});
+					read.push(...page);
+					if (page.length < 3) break;
+				}
+				const expected = ids(rows);
+				expect(ids(read)).toEqual(order === "asc" ? expected : expected.toReversed());
+			}
+			expect(ids(await query(adapter, {
+				index: "byGroup",
+				eq: ["p"],
+				lower: {
+					values: [3],
+					inclusive: true
+				},
+				upper: {
+					values: [5],
+					inclusive: false
+				}
+			}))).toEqual([
+				"p06",
+				"p07",
+				"p08",
+				"p09"
+			]);
+			expect(ids(await query(adapter, {
+				index: "byGroupFlag",
+				eq: ["p", true],
+				lower: {
+					values: [6, "p12"],
+					inclusive: false
+				}
+			}))).toEqual([
+				"p15",
+				"p18",
+				"p21"
+			]);
+		});
+		it("indexes every value of a multi-valued field", async () => {
+			const adapter = await setup();
+			const a = item("a", {
+				tags: ["x", "y"],
+				score: 2
+			});
+			await ok(adapter, [
+				insert(a),
+				insert(item("b", {
+					tags: ["y"],
+					score: 1
+				})),
+				insert(item("c", { tags: [] })),
+				insert(item("d"))
+			]);
+			const tagged = async (tag) => ids(await query(adapter, {
+				index: "byTag",
+				eq: [tag]
+			}));
+			expect(await tagged("x")).toEqual(["a"]);
+			expect(await tagged("y")).toEqual(["b", "a"]);
+			await ok(adapter, [{
+				type: "patch",
+				table: conformanceItems,
+				key: ["a"],
+				set: { tags: ["z"] },
+				guard: { v: 0 },
+				previous: a
+			}]);
+			expect(await tagged("x")).toEqual([]);
+			expect(await tagged("z")).toEqual(["a"]);
+			await ok(adapter, [{
+				type: "delete",
+				table: conformanceItems,
+				key: ["a"],
+				guard: { v: 1 },
+				previous: {
+					...a,
+					tags: ["z"],
+					_v: 1
+				}
+			}]);
+			expect(await tagged("z")).toEqual([]);
+		});
+		it("fills every page when native pages are capped", async () => {
+			const adapter = await setup({ nativePageSize: 2 });
+			await ok(adapter, Array.from({ length: 9 }, (_, index) => insert(item(`r${index}`))));
+			const first = await query(adapter, {
+				index: "all",
+				eq: [],
+				limit: 5
+			});
+			expect(ids(first)).toEqual([
+				"r0",
+				"r1",
+				"r2",
+				"r3",
+				"r4"
+			]);
+			const second = await query(adapter, {
+				index: "all",
+				eq: [],
+				limit: 5,
+				lower: {
+					values: ["r4"],
+					inclusive: false
+				}
+			});
+			expect(ids(second)).toEqual([
+				"r5",
+				"r6",
+				"r7",
+				"r8"
+			]);
+		});
+		it(`lets exactly one of ${writers} concurrent writers win a contested key`, async () => {
+			const adapter = await setup();
+			const row = item("a");
+			await ok(adapter, [insert(row)]);
+			const results = await Promise.all(shuffled(Array.from({ length: writers }, (_, index) => index)).map((index) => adapter.write([{
+				type: "patch",
+				table: conformanceItems,
+				key: ["a"],
+				set: { score: index + 1 },
+				guard: { v: 0 },
+				previous: row
+			}])));
+			expect(results.filter((result) => result.ok)).toHaveLength(1);
+			expect(results.every((result) => result.ok || "retry" in result || result.failedOp === 0)).toBe(true);
+			expect(await one(adapter, "a")).toMatchObject({ _v: 1 });
+		});
+		it(`loses no increments under ${writers} concurrent writers`, async () => {
+			const adapter = await setup();
+			const incrementUntilCommitted = async () => {
+				for (let attempt = 0; attempt < 50; attempt += 1) {
+					const result = await adapter.write([{
+						type: "increment",
+						table: conformanceCounters,
+						key: counterKey("c"),
+						by: { hits: 1 },
+						init: counterInit("c")
+					}]);
+					if (result.ok) return;
+					if (!("retry" in result)) throw new Error("increment failed");
+				}
+				throw new Error("increment kept retrying");
+			};
+			await Promise.all(Array.from({ length: writers }, () => incrementUntilCommitted()));
+			expect(await adapter.get(conformanceCounters, [counterKey("c")])).toEqual([{
+				scope: "c",
+				shard: 0,
+				hits: writers,
+				_v: writers
+			}]);
+		});
+		it("rejects write skew between two checked writers", async () => {
+			const adapter = await setup();
+			const a = item("a");
+			const b = item("b");
+			await ok(adapter, [insert(a), insert(b)]);
+			const skew = (read, written) => [{
+				type: "check",
+				table: conformanceItems,
+				key: [read.id],
+				guard: { v: 0 }
+			}, {
+				type: "patch",
+				table: conformanceItems,
+				key: [written.id],
+				set: { score: 1 },
+				guard: { v: 0 },
+				previous: written
+			}];
+			const results = await Promise.all([adapter.write(skew(a, b)), adapter.write(skew(b, a))]);
+			expect(results.filter((result) => result.ok).length).toBeLessThanOrEqual(1);
+		});
+		it.skipIf(options.maxOps === void 0)("rejects an over-limit write before sending it", async () => {
+			const adapter = await setup();
+			const ops = Array.from({ length: (options.maxOps ?? 0) + 1 }, (_, index) => insert(item(`over${index}`)));
+			expect(adapter.fits(ops)).toBe(false);
+			await expect(adapter.write(ops)).rejects.toThrow(DatabaseAdapterContractError);
+			expect(await query(adapter, {
+				index: "all",
+				eq: []
+			})).toEqual([]);
+		});
+	});
+};
+//#endregion
+//#region src/setupReadBudgetTestSuite.ts
+const DAY = 864e5;
+const HOUR = 36e5;
+/** The UTC midnight Insights events start at. */
+const T0 = Date.UTC(2026, 8, 20);
+const NATIVE_PAGE_SIZE = 2;
+const bundleOf = (suffix, platform = "ios", bases = []) => ({
+	...createBundleFixture(suffix),
+	platform,
+	assetBaseStorageUri: "storage://read-budgets/assets",
+	patches: bases.map((base) => ({
+		baseBundleId: createBundleFixture(base).id,
+		baseFileHash: `base-hash-${base}`,
+		patchFileHash: `patch-hash-${suffix}-${base}`,
+		patchStorageUri: `storage://patches/${suffix}-${base}.patch`,
+		byteSize: 1e3
+	}))
+});
+/** Insights event `n`, from install `n` by default, `n` × 10 minutes after T0. */
+const eventOf = (n, overrides = {}) => ({
+	id: createBundleFixture(String(9e3 + n)).id,
+	type: "UPDATE_APPLIED",
+	install_id: `install-${n}`,
+	user_id: n % 2 === 0 ? "user-even" : "user-odd",
+	from_release_id: "release-a",
+	from_bundle_id: "bundle-a",
+	to_release_id: "release-b",
+	to_bundle_id: "bundle-b",
+	platform: "ios",
+	app_version: "1.0.0",
+	channel: "production",
+	metadata: {
+		username: null,
+		cohort: "1",
+		update_strategy: "appVersion",
+		fingerprint_hash: null,
+		sdk_version: null
+	},
+	received_at_ms: T0 + n * 10 * 6e4,
+	...overrides
+});
+/**
+* History event `n` of the day before T0, three an hour, on its own release
+* and bundles: every windowed read, which starts at T0 or later, skips it.
+*/
+const historyOf = (n) => eventOf(100 + n, {
+	install_id: `history-${n}`,
+	user_id: null,
+	from_bundle_id: "bundle-history-a",
+	to_release_id: "release-history",
+	to_bundle_id: "bundle-history-b",
+	received_at_ms: T0 - DAY + Math.floor((n - 1) / 3) * HOUR + (n - 1) % 3 * 6e5
+});
+const production = {
+	channel: "production",
+	enabled: true,
+	fingerprintHash: null,
+	message: null,
+	shouldForceUpdate: false,
+	targetAppVersion: "1.0.0"
+};
+const scopeKey = createReleaseCatalogScopeKey({
+	channelKey: encodeChannelKey("production"),
+	platform: "ios",
+	strategy: "APP_VERSION"
+});
+const bundleEvents = {
+	kind: "bundle",
+	platform: "ios",
+	channel: "production",
+	type: "UPDATE_APPLIED",
+	toBundleId: "bundle-b"
+};
+/** The target bundle's manifest, which artifact resolution reads from storage. */
+const storage = {
+	readStorageText: async (storageUri) => storageUri === createBundleFixture("106").manifestStorageUri ? JSON.stringify({
+		bundleId: createBundleFixture("106").id,
+		assets: { "index.ios.bundle": { fileHash: "hbc-hash-106" } }
+	}) : null,
+	resolveFileUrl: async (storageUri) => storageUri === null ? null : `https://storage.example.com/${encodeURIComponent(storageUri)}`
+};
+/**
+* Core's bundles, releases, channels, and a client API key, and 25 Insights
+* events: installs 1–24 ten minutes apart from T0, then install 1 again two
+* days later; and the day of history before T0, as a production database
+* holds, so a read that scans beyond its window examines more rows.
+*/
+const seed = async (database, server) => {
+	const { core } = database;
+	const api = database.api;
+	for (const name of [
+		"staging",
+		"beta",
+		"canary",
+		"nightly"
+	]) await core.ensureChannel(name);
+	const deploy = async (bundle, channel = "production") => {
+		const [deployed] = await core.deploy([{
+			bundle,
+			release: {
+				...production,
+				channel
+			}
+		}]);
+		return deployed.release.id;
+	};
+	const releases = [];
+	for (const suffix of [
+		"101",
+		"102",
+		"103",
+		"104",
+		"105"
+	]) releases.push(await deploy(bundleOf(suffix)));
+	releases.push(await deploy(bundleOf("106", "ios", ["105", "104"])));
+	for (const releaseId of releases.slice(1, 3)) await core.updateReleasePolicy({
+		releaseId,
+		patch: { enabled: false }
+	});
+	await core.promoteRelease({
+		releaseId: releases[4],
+		targetChannel: "beta"
+	});
+	await deploy(bundleOf("201", "android"));
+	await deploy(bundleOf("202", "android"));
+	await deploy(bundleOf("091"), "staging");
+	await deploy(bundleOf("092"), "staging");
+	const { apiKey } = await api.apiKeys.create({ name: "Read budgets" });
+	for (let n = 1; n <= 24; n += 1) await api.insights.recordEvent(eventOf(n));
+	await api.insights.recordEvent(eventOf(25, {
+		install_id: "install-1",
+		received_at_ms: T0 + 2 * DAY
+	}));
+	for (let n = 1; n <= 72; n += 1) await api.insights.recordEvent(historyOf(n));
+	const channel = (name) => core.findChannelByName(name).then((found) => found);
+	const productionId = (await channel("production")).id;
+	return {
+		core,
+		insights: api.insights,
+		clientAuth: database.clientAuth,
+		apiKey,
+		productionId,
+		nightlyId: (await channel("nightly")).id,
+		/** The auto-patch base key of a new production iOS 1.0.0 bundle. */
+		candidateKey: server.targetBaseCandidateKey({
+			channelId: productionId,
+			platform: "ios",
+			fingerprintHash: null,
+			appVersion: "1.0.0"
+		})
+	};
+};
+const budget = (entry) => entry;
+const reads = (gets, keys, queries, rows) => ({
+	gets,
+	keys,
+	queries,
+	rows
+});
+const updateCheck = {
+	strategy: "APP_VERSION",
+	platform: "ios",
+	channelKey: encodeChannelKey("production"),
+	appVersion: "1.0.0"
+};
+/** The PRD's read-budget list, each count exact at both boundaries. */
+const READ_BUDGETS = [
+	budget({
+		api: "update check: 1 catalog point read",
+		read: ({ core }) => core.getReleaseCatalog(updateCheck),
+		adapter: reads(1, 1, 0, 0),
+		engine: {
+			calls: 1,
+			rows: 1
+		},
+		check: (catalog) => expect(catalog?.releases).toHaveLength(4)
+	}),
+	budget({
+		api: "update check with api-keys: 1 catalog point read and 1 API-key read",
+		read: async ({ core, clientAuth, apiKey }) => {
+			const headers = new Headers({ "x-api-key": apiKey });
+			if (!await clientAuth.authenticate(headers)) return null;
+			return core.getReleaseCatalog(updateCheck);
+		},
+		adapter: reads(1, 1, 1, 1),
+		engine: {
+			calls: 2,
+			rows: 2
+		},
+		check: (catalog) => expect(catalog?.releases).toHaveLength(4)
+	}),
+	budget({
+		api: "artifact resolution: 1 batch get of 2 bundles and 1 unique patch read",
+		read: ({ core }) => core.getArtifactInfo(createBundleFixture("106").id, createBundleFixture("105").id, 1),
+		adapter: reads(1, 2, 1, 1),
+		engine: {
+			calls: 2,
+			rows: 3
+		},
+		check: (artifact) => expect(artifact).toMatchObject({
+			artifactProtocolVersion: 1,
+			manifestFileHash: createBundleFixture("106").manifestFileHash
+		})
+	}),
+	budget({
+		api: "bundle list page: limit rows and one byBundle query per returned bundle with patches",
+		read: ({ core }) => core.listBundles({
+			platform: "ios",
+			order: "desc",
+			limit: 3
+		}),
+		adapter: reads(0, 0, 2, 5),
+		engine: {
+			calls: 2,
+			rows: 5
+		},
+		returned: (page) => page.reduce((sum, detail) => sum + 1 + detail.patches.length, 0),
+		check: (page) => expect(page.map(({ bundle }) => bundle.id)).toEqual([
+			"106",
+			"105",
+			"104"
+		].map((suffix) => createBundleFixture(suffix).id))
+	}),
+	budget({
+		api: "bundle total: 1 counter row",
+		read: ({ core }) => core.countBundles("ios"),
+		adapter: reads(0, 0, 1, 1),
+		engine: {
+			calls: 1,
+			rows: 1
+		},
+		check: (total) => expect(total).toBe(8)
+	}),
+	budget({
+		api: "bundle children: nothing extra, the count is on the bundle row",
+		read: ({ core }) => core.getBundle(createBundleFixture("105").id),
+		adapter: reads(1, 1, 0, 0),
+		engine: {
+			calls: 1,
+			rows: 1
+		},
+		check: (detail) => expect(detail).toMatchObject({
+			patches: [],
+			childCount: 1
+		})
+	}),
+	budget({
+		api: "release list: limit rows from one enumerated index",
+		read: ({ core, productionId }) => core.listReleases({
+			filter: {
+				kind: "channelPlatform",
+				channelId: productionId,
+				platform: "ios",
+				enabled: true
+			},
+			limit: 3
+		}),
+		adapter: reads(0, 0, 1, 3),
+		engine: {
+			calls: 1,
+			rows: 3
+		},
+		returned: (releases) => releases.length
+	}),
+	budget({
+		api: "deploy base candidates: at most maxBaseBundles rows",
+		read: ({ core, candidateKey }) => core.findBaseBundleIds(candidateKey, createBundleFixture("107").id, 2),
+		adapter: reads(0, 0, 1, 2),
+		engine: {
+			calls: 1,
+			rows: 2
+		},
+		check: (ids) => expect(ids).toEqual(["106", "105"].map((suffix) => createBundleFixture(suffix).id))
+	}),
+	budget({
+		api: "deploy latest release id: byScope descending, limit 1",
+		read: ({ core }) => core.latestReleaseId(scopeKey),
+		adapter: reads(0, 0, 1, 1),
+		engine: {
+			calls: 1,
+			rows: 1
+		}
+	}),
+	budget({
+		api: "channel by name: 1 read",
+		read: ({ core }) => core.findChannelByName("staging"),
+		adapter: reads(0, 0, 1, 1),
+		engine: {
+			calls: 1,
+			rows: 1
+		},
+		returned: (channel) => channel === null ? 0 : 1
+	}),
+	budget({
+		api: "list events: limit rows, and one zero-row query per empty day",
+		read: ({ insights }) => insights.listEvents({
+			filter: bundleEvents,
+			sinceMs: T0,
+			beforeReceivedAtMs: T0 + 3 * DAY,
+			limit: 5
+		}),
+		adapter: reads(0, 0, 3, 5),
+		engine: {
+			calls: 3,
+			rows: 5
+		},
+		returned: (events) => events.length
+	}),
+	budget({
+		api: "latest events by install: 1 point read",
+		read: ({ insights }) => insights.findLatestEvents({ installId: "install-1" }),
+		adapter: reads(1, 1, 0, 0),
+		engine: {
+			calls: 1,
+			rows: 1
+		},
+		returned: (events) => events.length
+	}),
+	budget({
+		api: "latest events by user: limit rows",
+		read: ({ insights }) => insights.findLatestEvents({
+			userId: "user-even",
+			limit: 3
+		}),
+		adapter: reads(0, 0, 1, 3),
+		engine: {
+			calls: 1,
+			rows: 3
+		},
+		returned: (events) => events.length
+	}),
+	budget({
+		api: "countEvents: buckets in the window × shards, all used",
+		read: ({ insights }) => insights.countEvents({
+			filter: bundleEvents,
+			sinceMs: T0,
+			beforeReceivedAtMs: T0 + 2 * HOUR
+		}),
+		adapter: reads(0, 0, 1, 11),
+		engine: {
+			calls: 1,
+			rows: 2
+		},
+		check: (count) => expect(count).toBe(11)
+	}),
+	budget({
+		api: "countLatestEvents: buckets in the window × shards, all used",
+		read: ({ insights }) => insights.countLatestEvents({
+			platform: "ios",
+			channel: "production",
+			sinceMs: T0 + HOUR
+		}),
+		adapter: reads(0, 0, 1, 20),
+		engine: {
+			calls: 1,
+			rows: 5
+		},
+		check: (count) => expect(count).toBe(20)
+	}),
+	budget({
+		api: "countLatestEvents by bundle: buckets in the window × shards, all used",
+		read: ({ insights }) => insights.countLatestEvents({
+			platform: "ios",
+			channel: "production",
+			sinceMs: T0,
+			bundle: [{
+				field: "to_bundle_id",
+				value: "bundle-b",
+				types: ["UPDATE_APPLIED"]
+			}]
+		}),
+		adapter: reads(0, 0, 1, 24),
+		engine: {
+			calls: 1,
+			rows: 6
+		},
+		check: (count) => expect(count).toBe(24)
+	}),
+	budget({
+		api: "release activity: buckets × shards, all used",
+		read: ({ insights }) => insights.getReleaseActivity({ releases: [{
+			releaseId: "release-b",
+			platform: "ios",
+			channel: "production"
+		}] }),
+		adapter: reads(0, 0, 1, 8),
+		engine: {
+			calls: 1,
+			rows: 1
+		},
+		check: ({ data }) => expect(data[0].metrics.launches).toBe(25)
+	}),
+	budget({
+		api: "release activity over a window: buckets × shards, all used",
+		read: ({ insights }) => insights.getReleaseActivity({
+			scope: {
+				platform: "ios",
+				channel: "production"
+			},
+			timeRange: {
+				start: T0,
+				end: T0 + 3 * DAY
+			}
+		}),
+		adapter: reads(0, 0, 2, 24),
+		engine: {
+			calls: 2,
+			rows: 4
+		},
+		check: ({ data }) => expect(data[0].metrics.launches).toBe(25)
+	}),
+	budget({
+		api: "app usage: nonzero distribution and usage-sketch rows in the window, all used",
+		read: ({ insights }) => insights.getAppUsage({
+			channel: "production",
+			platform: "all",
+			timeRange: {
+				start: T0,
+				end: T0 + 3 * DAY
+			},
+			intervalMs: DAY
+		}),
+		adapter: reads(0, 0, 3, 39),
+		engine: {
+			calls: 3,
+			rows: 8
+		},
+		check: ({ versions }) => expect(versions).toEqual([{
+			name: "1.0.0",
+			installations: 24
+		}])
+	}),
+	budget({
+		api: "catalog compile: the scope's enabled releases, all used",
+		read: ({ core }) => core.deploy([{
+			bundle: bundleOf("107"),
+			release: production
+		}]),
+		adapter: (copies) => reads(copies ? 6 : 4, copies ? 9 : 4, 3, 6),
+		engine: {
+			calls: 6,
+			rows: 9
+		},
+		writes: 1
+	}),
+	budget({
+		api: "channel insert: 1 write, after the name's read finds nothing",
+		read: ({ core }) => core.ensureChannel("read-budgets"),
+		adapter: reads(0, 0, 1, 0),
+		engine: {
+			calls: 1,
+			rows: 0
+		},
+		writes: 1
+	}),
+	budget({
+		api: "channel delete: 1 read and 1 write",
+		read: ({ core, nightlyId }) => core.deleteChannel(nightlyId),
+		adapter: reads(1, 1, 0, 0),
+		engine: {
+			calls: 1,
+			rows: 1
+		},
+		writes: 1,
+		check: (result) => expect(result).toEqual({ deleted: true })
+	}),
+	budget({
+		api: "record an insights event: 2 dependent rounds of batch gets and 1 write",
+		read: ({ insights }) => insights.recordEvent(eventOf(26, {
+			install_id: "install-2",
+			received_at_ms: T0 + 3 * HOUR
+		})),
+		adapter: reads(5, 19, 0, 0),
+		engine: {
+			calls: 2,
+			rows: 1
+		},
+		writes: 1
+	})
+];
+/**
+* The read-budget suite (PRD S4) on one backend: core and the built-in
+* plugins in verify mode over the backend's adapter, native pages capped at
+* two rows. Every API in the read-budget list reads exactly its budget at the
+* adapter and at the engine; with `examined`, the database examines no more
+* rows than the adapter read, within the backend's native multipliers.
+*/
+const setupReadBudgetTestSuite = (options) => {
+	describe(`${options.name} read budgets`, () => {
+		let created;
+		let database;
+		let seeded;
+		let writes = 0;
+		beforeAll(async () => {
+			created = await options.createAdapter({
+				tables: options.server.builtInSchema.tables,
+				nativePageSize: NATIVE_PAGE_SIZE
+			});
+			const { adapter } = created;
+			database = options.server.createMeasuredDatabase({
+				...adapter,
+				write: (ops) => {
+					writes += 1;
+					return adapter.write(ops);
+				}
+			}, options.server.plugins, {
+				now: () => T0 + 10 * DAY,
+				storage
+			});
+			seeded = await seed(database, options.server);
+		}, 3e5);
+		afterAll(async () => {
+			await created?.cleanup?.();
+		});
+		for (const budget of READ_BUDGETS) it(budget.api, async () => {
+			const { examined, indexCopies = false } = created;
+			writes = 0;
+			examined?.reset();
+			const measured = await database.measureReads(() => budget.read(seeded));
+			const adapter = typeof budget.adapter === "function" ? budget.adapter(indexCopies) : budget.adapter;
+			expect({
+				adapter: measured.adapter,
+				engine: measured.engine
+			}).toEqual({
+				adapter,
+				engine: budget.engine
+			});
+			expect(writes, "writes").toBe(budget.writes ?? 0);
+			if (budget.returned) expect(budget.returned(measured.result), "rows returned").toBe(measured.engine.rows);
+			budget.check?.(measured.result);
+			if (examined) {
+				const { gets, keys, queries, rows } = measured.adapter;
+				expect(await examined.total(), "rows examined").toBeLessThanOrEqual((examined.perRow ?? 1) * (keys + rows) + (examined.perRead ?? 0) * (gets + queries));
+			}
+		});
+	});
+};
+//#endregion
+//#region src/sqlRowsExamined.ts
+/** Wraps executors so each read they run while counting is examined first. */
+const examineReads = (hooks) => {
+	let counting = false;
+	let examined = 0;
+	return {
+		/** The executor, examining each SELECT it runs outside a transaction. */
+		wrap: (executor) => ({
+			...executor,
+			async execute(statement) {
+				if (counting && /^\s*SELECT\b/iu.test(statement.sql)) {
+					const rows = await hooks.examine(statement);
+					examined += rows;
+				}
+				return executor.execute(statement);
+			}
+		}),
+		examined: {
+			reset() {
+				counting = true;
+				examined = 0;
+				hooks.onReset?.();
+			},
+			async total() {
+				counting = false;
+				return examined;
+			}
+		}
+	};
+};
+/** Rows each table read of a plan examined: rows it produced, filtered out, or rechecked away, over all its loops. */
+const postgresTableReads = (node, reads = /* @__PURE__ */ new Map()) => {
+	const relation = node["Relation Name"];
+	if (relation !== void 0) {
+		const table = node.Alias ?? relation;
+		const rows = (node["Actual Rows"] ?? 0) + (node["Rows Removed by Filter"] ?? 0) + (node["Rows Removed by Index Recheck"] ?? 0);
+		reads.set(table, (reads.get(table) ?? 0) + rows * (node["Actual Loops"] ?? 0));
+	}
+	for (const child of node.Plans ?? []) postgresTableReads(child, reads);
+	return reads;
+};
+/**
+* Planner settings under which a test's small tables plan as production-sized
+* ones: no sequential scan, which only a small table affords, and an index
+* entry weighted like a row, so a plan reads no more entries than the read
+* needs, as a large index forces.
+*/
+const POSTGRES_PLANNER = ["enable_seqscan = off", "cpu_index_tuple_cost = 1"];
+/**
+* Rows examined on PostgreSQL (PGlite or a server). Each SELECT a wrapped
+* executor runs is first run under `EXPLAIN (ANALYZE, FORMAT JSON)` on
+* `query`, one session with the planner settings above; each `reset` first
+* vacuums and analyzes, as autovacuum keeps a production database. A plan
+* then takes the index path a production-sized table takes, and a read no
+* index serves still scans. A statement counts the rows its busiest table
+* read examined, so an exact plan counts the rows it returns, a multi-valued
+* index's own table included.
+*/
+const postgresRowsExamined = (query) => {
+	let planner;
+	let stale = true;
+	return examineReads({
+		onReset: () => {
+			stale = true;
+		},
+		async examine({ sql, params }) {
+			planner ??= (async () => {
+				for (const setting of POSTGRES_PLANNER) await query(`SET ${setting}`, []);
+			})();
+			await planner;
+			if (stale) {
+				stale = false;
+				await query("VACUUM ANALYZE", []);
+			}
+			const [row] = await query(`EXPLAIN (ANALYZE, FORMAT JSON) ${sql}`, params);
+			const output = row?.["QUERY PLAN"];
+			const [plan] = typeof output === "string" ? JSON.parse(output) : output;
+			return Math.max(0, ...postgresTableReads(plan.Plan).values());
+		}
+	});
+};
+/**
+* An `EXPLAIN ANALYZE` iterator that reads a table: its table, and its actual
+* rows and loops. A primary-key read of constants runs while MySQL plans the
+* statement, and names no table.
+*/
+const MYSQL_TABLE_READ = /-> (?:(?:Table scan|(?:Covering )?[Ii]ndex (?:scan|lookup|range scan|skip scan)|Single-row (?:covering )?index lookup|Multi-range index scan) on (\S+)|Rows fetched before execution).*\(actual time=[\d.e+-]+\.\.[\d.e+-]+ rows=([\d.e+-]+) loops=(\d+)\)/u;
+/**
+* Rows examined on MySQL. Each SELECT a wrapped executor runs is first run
+* under `EXPLAIN ANALYZE` on `query`, one session, after `ANALYZE TABLE` of
+* the tables it reads once per `reset`, and with multi-range reads always
+* on, so a secondary index's range is costed with sorted row reads, as a
+* production-sized table's is. A statement counts the rows its busiest table
+* read examined; a filter above a table read drops rows that read produced.
+*/
+const mysqlRowsExamined = (query) => {
+	let planner;
+	const analyzed = /* @__PURE__ */ new Set();
+	return examineReads({
+		onReset: () => {
+			analyzed.clear();
+		},
+		async examine({ sql, params }) {
+			planner ??= query("SET SESSION optimizer_switch = 'mrr=on,mrr_cost_based=off'", []);
+			await planner;
+			const tables = [...sql.matchAll(/(?:FROM|JOIN) (`[^`]+`)/gu)].map(([, table]) => table).filter((table) => !analyzed.has(table));
+			for (const table of tables) analyzed.add(table);
+			if (tables.length > 0) await query(`ANALYZE TABLE ${tables.join(", ")}`, []);
+			const [row] = await query(`EXPLAIN ANALYZE ${sql}`, params);
+			const reads = /* @__PURE__ */ new Map();
+			for (const line of String(Object.values(row ?? {})[0]).split("\n")) {
+				const read = MYSQL_TABLE_READ.exec(line);
+				if (read === null) continue;
+				const [, table = "", rows, loops] = read;
+				reads.set(table, (reads.get(table) ?? 0) + Number(rows) * Number(loops));
+			}
+			return Math.max(0, ...reads.values());
+		}
+	});
+};
+//#endregion
+//#region src/runContentionHarness.ts
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Delays every adapter call by `ms`, like a round trip to a remote database. */
+const withAdapterLatency = (adapter, ms) => ({
+	...adapter,
+	get: async (table, keys) => {
+		await sleep(ms);
+		return adapter.get(table, keys);
+	},
+	query: async (table, request) => {
+		await sleep(ms);
+		return adapter.query(table, request);
+	},
+	write: async (ops) => {
+		await sleep(ms);
+		return adapter.write(ops);
+	}
+});
+/**
+* Starts `transactions` runs at a steady arrival rate through a fixed pool and
+* reports how they ended. Retry counts come from the engine's `onRetry`.
+*/
+const runContentionHarness = async (options) => {
+	const started = Date.now();
+	const errors = {};
+	const waiting = [];
+	let free = options.concurrency;
+	let committed = 0;
+	const acquire = () => free > 0 ? (free -= 1, Promise.resolve()) : new Promise((resolve) => waiting.push(resolve));
+	const release = () => {
+		const next = waiting.shift();
+		if (next) next();
+		else free += 1;
+	};
+	await Promise.all(Array.from({ length: options.transactions }, async (_, index) => {
+		await sleep(index * 1e3 / options.ratePerSecond);
+		await acquire();
+		try {
+			await options.run(index);
+			committed += 1;
+		} catch (error) {
+			const name = error instanceof Error ? error.name : "unknown";
+			errors[name] = (errors[name] ?? 0) + 1;
+		} finally {
+			release();
+		}
+	}));
+	return {
+		transactions: options.transactions,
+		committed,
+		errors,
+		durationMs: Date.now() - started
+	};
+};
+//#endregion
+//#region src/createPluginTestHarness.ts
+const builtInPlugin = Symbol.for("@hot-updater/server/built-in-plugin");
+/**
+* Runs one plugin the way `createHotUpdater` does, on a memory adapter in
+* verify mode, so tests can call its API and measure what each call reads.
+*/
+const createPluginTestHarness = async (plugin, options) => {
+	const adapter = options.adapter ?? createMemoryAdapter();
+	const module = {
+		id: plugin.id,
+		schema: plugin.schema,
+		...builtInPlugin in plugin ? {} : { namespace: plugin.id }
+	};
+	const schema = options.engine.resolveSchema([module]);
+	await adapter.migrations?.apply(schema.tables);
+	const engine = options.engine.createDatabaseEngine({
+		adapter,
+		schema,
+		verify: true
+	});
+	let clock = options.now ?? Date.now;
+	const db = engine.database(module);
+	const instance = plugin.init({
+		db,
+		core: {},
+		now: () => clock()
+	});
+	return {
+		api: instance.api,
+		instance,
+		/** The plugin's own database handle; cast it to its `HotUpdaterDatabase` type. */
+		db,
+		adapter,
+		tables: schema.tables,
+		/** Reads at both boundaries while `read` runs. */
+		measureReads: (read) => engine.measureReads(read),
+		setNow: (now) => {
+			clock = now;
+		}
+	};
+};
+//#endregion
+//#region src/httpTestClient.ts
+/** Connect the same contract suite to any running HTTP server. */
+function createHttpTestClient(options) {
+	const endpoint = (baseUrl, headers = {}) => (path, init) => {
+		const requestHeaders = new Headers(headers);
+		new Headers(init?.headers).forEach((value, key) => requestHeaders.set(key, value));
+		return fetch(`${baseUrl.replace(/\/$/, "")}${path}`, {
+			...init,
+			headers: requestHeaders
+		});
+	};
+	return {
+		client: endpoint(options.clientBaseUrl, options.clientHeaders),
+		admin: endpoint(options.adminBaseUrl, options.adminHeaders)
+	};
+}
+/** Workers run the same HTTP contract through their Web Request/Response boundary. */
+function createHandlerHttpTestClient(handlers) {
+	const endpoint = (handler) => (path, init) => handler(new Request(`https://updates.example.com${path}`, init));
+	return {
+		client: endpoint(handlers.client),
+		admin: endpoint(handlers.admin),
+		close: async () => {}
+	};
+}
+//#endregion
+//#region src/httpTestServer.ts
+/** Serve Web handlers over loopback TCP; contract tests use real fetch requests. */
+async function startHttpTestServer(handlers) {
+	const server = createServer(async (incoming, outgoing) => {
+		try {
+			const url = new URL(incoming.url, "http://127.0.0.1");
+			const target = url.pathname.startsWith("/admin/") ? "admin" : "client";
+			url.pathname = url.pathname.slice(target.length + 1);
+			const headers = new Headers();
+			for (const [key, value] of Object.entries(incoming.headers)) if (value !== void 0) headers.set(key, Array.isArray(value) ? value.join(", ") : value);
+			const chunks = [];
+			for await (const chunk of incoming) chunks.push(Buffer.from(chunk));
+			const response = await handlers[target](new Request(url, {
+				method: incoming.method,
+				headers,
+				body: chunks.length === 0 ? void 0 : Buffer.concat(chunks)
+			}));
+			outgoing.writeHead(response.status, Object.fromEntries(response.headers));
+			outgoing.end(Buffer.from(await response.arrayBuffer()));
+		} catch (error) {
+			outgoing.writeHead(500);
+			outgoing.end(String(error));
+		}
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(0, "127.0.0.1", resolve);
+	});
+	const address = server.address();
+	if (address === null || typeof address === "string") throw new Error("Missing HTTP test server address");
+	const baseUrl = `http://127.0.0.1:${address.port}`;
+	return {
+		...createHttpTestClient({
+			clientBaseUrl: `${baseUrl}/client`,
+			adminBaseUrl: `${baseUrl}/admin`
+		}),
+		close: () => new Promise((resolve, reject) => {
+			server.close((error) => error ? reject(error) : resolve());
+			server.closeIdleConnections();
+		})
+	};
+}
+//#endregion
+export { RELEASE_CATALOG_DOWNLOAD_HASH, RELEASE_CATALOG_MANIFEST_URIS, RELEASE_CATALOG_STORAGE_FIXTURES, conformanceCounters, conformanceItems, createAdminApiTestClient, createHandlerHttpTestClient, createHttpTestClient, createPluginTestHarness, createReleaseCatalogTestStorage, jsonRequest, mysqlRowsExamined, postgresRowsExamined, releaseCatalogArtifact, releaseCatalogDownloadUrl, runContentionHarness, setupBundleMethodsTestSuite, setupCoreAdminTestSuite, setupDatabaseAdapterConformanceSuite, setupDatabaseTestSuite, setupInsightsHttpTestSuite, setupInsightsModelTestSuite, setupReadBudgetTestSuite, setupReleaseCatalogTestSuite, setupSemverSatisfiesTestSuite, startHttpTestServer, toDeployBundle, withAdapterLatency };