@rpcbase/migrations 0.0.0

package/dist/index.js

@@ -0,0 +1,1566 @@
+import { createHash, randomUUID } from "node:crypto";
+import { BSON } from "mongodb";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, extname, isAbsolute, resolve } from "node:path";
+import { ImportType, initSync, parse } from "es-module-lexer";
+//#region src/canonical.ts
+var normalizeSerializedValue = (value) => {
+	if (Array.isArray(value)) return value.map(normalizeSerializedValue);
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, normalizeSerializedValue(item)]));
+	return value;
+};
+var normalizeValue = (value) => normalizeSerializedValue(BSON.EJSON.serialize(value, { relaxed: false }));
+var canonicalStringify = (value) => JSON.stringify(normalizeValue(value));
+var sha256 = (value) => createHash("sha256").update(value).digest("hex");
+var canonicalChecksum = (value) => sha256(canonicalStringify(value));
+//#endregion
+//#region src/resources.ts
+var scopes = /* @__PURE__ */ new Set([
+	"global",
+	"tenant",
+	"filesystem"
+]);
+var assertName = (value, label) => {
+	const normalized = value.trim();
+	if (!normalized) throw new Error(`${label} is required`);
+	if (normalized.includes("\0")) throw new Error(`${label} cannot contain a null byte`);
+	return normalized;
+};
+var assertScope = (scope) => {
+	if (!scopes.has(scope)) throw new Error(`Invalid migration scope: ${String(scope)}`);
+};
+var copyDocument = (value) => {
+	if (!value) return void 0;
+	return structuredClone(value);
+};
+var collectionIdentity$1 = (resource) => `${resource.scope}:${resource.name}`;
+var indexIdentity$1 = (resource) => `${resource.scope}:${resource.collection}:${resource.name}`;
+var validatorIdentity$1 = (resource) => `${resource.scope}:${resource.collection}`;
+var uniqueResources = (resources, identity, label) => {
+	const seen = /* @__PURE__ */ new Map();
+	for (const resource of resources) {
+		const key = identity(resource);
+		const canonical = canonicalStringify(resource);
+		const previous = seen.get(key);
+		if (previous && previous !== canonical) throw new Error(`Conflicting ${label} resource: ${key}`);
+		if (previous) throw new Error(`Duplicate ${label} resource: ${key}`);
+		seen.set(key, canonical);
+	}
+	return resources;
+};
+var normalizeCollection = (resource) => {
+	assertScope(resource.scope);
+	return {
+		scope: resource.scope,
+		name: assertName(resource.name, "Collection name"),
+		...resource.options ? { options: copyDocument(resource.options) } : {}
+	};
+};
+var normalizeIndex = (resource) => {
+	assertScope(resource.scope);
+	if (Object.keys(resource.key).length === 0) throw new Error("Index key cannot be empty");
+	return {
+		scope: resource.scope,
+		collection: assertName(resource.collection, "Index collection"),
+		name: assertName(resource.name, "Index name"),
+		key: structuredClone(resource.key),
+		...resource.options ? { options: copyDocument(resource.options) } : {}
+	};
+};
+var normalizeSearchIndex = (resource) => {
+	assertScope(resource.scope);
+	return {
+		scope: resource.scope,
+		collection: assertName(resource.collection, "Search index collection"),
+		name: assertName(resource.name, "Search index name"),
+		definition: structuredClone(resource.definition)
+	};
+};
+var normalizeValidator = (resource) => {
+	assertScope(resource.scope);
+	return {
+		scope: resource.scope,
+		collection: assertName(resource.collection, "Validator collection"),
+		validator: structuredClone(resource.validator),
+		...resource.validationLevel ? { validationLevel: resource.validationLevel } : {},
+		...resource.validationAction ? { validationAction: resource.validationAction } : {}
+	};
+};
+var sortByIdentity = (resources, identity) => [...resources].sort((left, right) => identity(left).localeCompare(identity(right)));
+var checksumInput = (resources) => ({
+	collections: resources.collections.map((resource) => ({
+		...resource,
+		options: resource.options ?? {}
+	})),
+	indexes: resources.indexes.map((resource) => ({
+		...resource,
+		key: Object.entries(resource.key),
+		options: resource.options ?? {}
+	})),
+	searchIndexes: resources.searchIndexes,
+	collectionValidators: resources.collectionValidators
+});
+var defineMongoResources = (input = {}) => {
+	const resources = {
+		collections: sortByIdentity(uniqueResources((input.collections ?? []).map(normalizeCollection), collectionIdentity$1, "collection"), collectionIdentity$1),
+		indexes: sortByIdentity(uniqueResources((input.indexes ?? []).map(normalizeIndex), indexIdentity$1, "index"), indexIdentity$1),
+		searchIndexes: sortByIdentity(uniqueResources((input.searchIndexes ?? []).map(normalizeSearchIndex), indexIdentity$1, "Search index"), indexIdentity$1),
+		collectionValidators: sortByIdentity(uniqueResources((input.collectionValidators ?? []).map(normalizeValidator), validatorIdentity$1, "collection validator"), validatorIdentity$1)
+	};
+	return Object.freeze({
+		checksum: canonicalChecksum(checksumInput(resources)),
+		...resources
+	});
+};
+var filterMongoResources = (resources, scope) => defineMongoResources({
+	collections: resources.collections.filter((resource) => resource.scope === scope),
+	indexes: resources.indexes.filter((resource) => resource.scope === scope),
+	searchIndexes: resources.searchIndexes.filter((resource) => resource.scope === scope),
+	collectionValidators: resources.collectionValidators.filter((resource) => resource.scope === scope)
+});
+var mergeMongoResources = (resourceSets) => {
+	const collections = /* @__PURE__ */ new Map();
+	const indexes = /* @__PURE__ */ new Map();
+	const searchIndexes = /* @__PURE__ */ new Map();
+	const validators = /* @__PURE__ */ new Map();
+	const merge = (target, resource, identity, label) => {
+		const key = identity(resource);
+		const previous = target.get(key);
+		if (previous && canonicalStringify(previous) !== canonicalStringify(resource)) throw new Error(`Conflicting ${label} resource across migration sources: ${key}`);
+		target.set(key, resource);
+	};
+	for (const resources of resourceSets) {
+		for (const resource of resources.collections) merge(collections, resource, collectionIdentity$1, "collection");
+		for (const resource of resources.indexes) merge(indexes, resource, indexIdentity$1, "index");
+		for (const resource of resources.searchIndexes) merge(searchIndexes, resource, indexIdentity$1, "Search index");
+		for (const resource of resources.collectionValidators) merge(validators, resource, validatorIdentity$1, "collection validator");
+	}
+	return defineMongoResources({
+		collections: [...collections.values()],
+		indexes: [...indexes.values()],
+		searchIndexes: [...searchIndexes.values()],
+		collectionValidators: [...validators.values()]
+	});
+};
+//#endregion
+//#region src/diffResources.ts
+var collectionIdentity = (resource) => `${resource.scope}:${resource.name}`;
+var indexIdentity = (resource) => `${resource.scope}:${resource.collection}:${resource.name}`;
+var validatorIdentity = (resource) => `${resource.scope}:${resource.collection}`;
+var indexComparisonValue = (resource) => ({
+	...resource,
+	key: Object.entries(resource.key)
+});
+var diffSet = (before, after, identity, comparisonValue = (resource) => resource) => {
+	const beforeById = new Map(before.map((resource) => [identity(resource), resource]));
+	const afterById = new Map(after.map((resource) => [identity(resource), resource]));
+	return [.../* @__PURE__ */ new Set([...beforeById.keys(), ...afterById.keys()])].sort().flatMap((id) => {
+		const previous = beforeById.get(id);
+		const next = afterById.get(id);
+		if (!previous && next) return [{
+			kind: "added",
+			after: next
+		}];
+		if (previous && !next) return [{
+			kind: "removed",
+			before: previous
+		}];
+		if (previous && next && canonicalStringify(comparisonValue(previous)) !== canonicalStringify(comparisonValue(next))) return [{
+			kind: "changed",
+			before: previous,
+			after: next
+		}];
+		return [];
+	});
+};
+var diffMongoResources = (before, after) => {
+	const collections = diffSet(before.collections, after.collections, collectionIdentity);
+	const indexes = diffSet(before.indexes, after.indexes, indexIdentity, indexComparisonValue);
+	const searchIndexes = diffSet(before.searchIndexes, after.searchIndexes, indexIdentity);
+	const collectionValidators = diffSet(before.collectionValidators, after.collectionValidators, validatorIdentity);
+	const changes = [
+		...collections,
+		...indexes,
+		...searchIndexes,
+		...collectionValidators
+	];
+	const offline = changes.some((change) => change.kind !== "added");
+	return {
+		collections,
+		indexes,
+		searchIndexes,
+		collectionValidators,
+		changed: changes.length > 0,
+		mode: offline ? "offline" : "online"
+	};
+};
+//#endregion
+//#region src/registry.ts
+var migrationIdPattern = /^\d{8}(?:\d{6})?-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var sourceNamePattern = /^(?:@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)$/;
+var scopeRank = {
+	global: 0,
+	tenant: 1,
+	filesystem: 2
+};
+var assertMigration = (migration) => {
+	if (!migrationIdPattern.test(migration.id)) throw new Error(`Invalid migration id "${migration.id}"`);
+	if (!(migration.scope in scopeRank)) throw new Error(`Invalid migration scope for ${migration.id}`);
+	if (migration.mode !== "online" && migration.mode !== "offline") throw new Error(`Invalid migration mode for ${migration.id}`);
+	if (migration.rollback !== void 0 && migration.rollback !== "compatible" && migration.rollback !== "incompatible") throw new Error(`Invalid migration rollback compatibility for ${migration.id}`);
+	if (typeof migration.up !== "function") throw new Error(`Migration ${migration.id} is missing up()`);
+	if (migration.resources && migration.resources.before === migration.resources.after) throw new Error(`Migration ${migration.id} has an unchanged resource transition`);
+};
+var defineMigration = (migration) => {
+	assertMigration(migration);
+	return Object.freeze({
+		...migration,
+		rollback: migration.rollback ?? (migration.mode === "online" ? "compatible" : "incompatible"),
+		dependsOn: Object.freeze([...migration.dependsOn ?? []]),
+		...migration.resources ? { resources: Object.freeze({ ...migration.resources }) } : {}
+	});
+};
+var defineMigrationSource = (source) => {
+	const name = source.name.trim();
+	if (!sourceNamePattern.test(name)) throw new Error(`Invalid migration source name "${source.name}"`);
+	let previousId = null;
+	const ids = /* @__PURE__ */ new Set();
+	for (const migration of source.migrations) {
+		assertMigration(migration);
+		if (ids.has(migration.id)) throw new Error(`Duplicate migration id in ${name}: ${migration.id}`);
+		if (previousId && migration.id <= previousId) throw new Error(`Migration ids in ${name} must be strictly increasing: ${previousId}, ${migration.id}`);
+		ids.add(migration.id);
+		previousId = migration.id;
+	}
+	return Object.freeze({
+		...source,
+		name,
+		migrations: Object.freeze([...source.migrations]),
+		resourceSnapshots: Object.freeze([...source.resourceSnapshots ?? []]),
+		checksums: Object.freeze({ ...source.checksums ?? {} })
+	});
+};
+var resolveDependencyId = (source, dependency) => dependency.includes(":") ? dependency : `${source}:${dependency}`;
+var migrationChecksum = (migration, source) => {
+	const injectedChecksum = migration.__rpcbaseIntegrity ?? source.checksums?.[migration.id];
+	if (injectedChecksum !== void 0 && (typeof injectedChecksum !== "string" || !/^[a-f0-9]{64}$/.test(injectedChecksum))) throw new Error(`Migration ${source.name}:${migration.id} has an invalid source checksum`);
+	const codeChecksum = injectedChecksum ?? canonicalChecksum(migration.up.toString());
+	return {
+		checksum: canonicalChecksum({
+			id: migration.id,
+			source: source.name,
+			scope: migration.scope,
+			mode: migration.mode,
+			rollback: migration.rollback ?? (migration.mode === "online" ? "compatible" : "incompatible"),
+			dependsOn: migration.dependsOn ?? [],
+			resources: migration.resources ?? null,
+			codeChecksum
+		}),
+		sealed: Boolean(injectedChecksum)
+	};
+};
+var sortMigrations = (migrations) => {
+	const byId = new Map(migrations.map((migration) => [migration.qualifiedId, migration]));
+	const visiting = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	const ordered = [];
+	const visit = (migration) => {
+		if (visited.has(migration.qualifiedId)) return;
+		if (visiting.has(migration.qualifiedId)) throw new Error(`Cyclic migration dependency involving ${migration.qualifiedId}`);
+		visiting.add(migration.qualifiedId);
+		for (const dependencyId of migration.dependsOn) {
+			const dependency = byId.get(dependencyId);
+			if (!dependency) throw new Error(`Unknown dependency ${dependencyId} for ${migration.qualifiedId}`);
+			if (scopeRank[dependency.scope] > scopeRank[migration.scope]) throw new Error(`${migration.qualifiedId} cannot depend on later scope migration ${dependencyId}`);
+			if (dependency.source === migration.source && dependency.scope === migration.scope && dependency.sourcePosition > migration.sourcePosition) throw new Error(`${migration.qualifiedId} cannot depend on a later migration in its source: ${dependencyId}`);
+			visit(dependency);
+		}
+		visiting.delete(migration.qualifiedId);
+		visited.add(migration.qualifiedId);
+		ordered.push(migration);
+	};
+	for (const migration of [...migrations].sort((left, right) => {
+		const scopeDifference = scopeRank[left.scope] - scopeRank[right.scope];
+		if (scopeDifference !== 0) return scopeDifference;
+		const sourceDifference = left.sourcePriority - right.sourcePriority;
+		if (sourceDifference !== 0) return sourceDifference;
+		return left.sourcePosition - right.sourcePosition;
+	})) visit(migration);
+	return Object.freeze(ordered);
+};
+var compileMigrationRegistry = (inputSources, options = {}) => {
+	const sourceNames = /* @__PURE__ */ new Set();
+	const migrations = [];
+	const compiledSources = [];
+	for (const [priority, inputSource] of inputSources.entries()) {
+		const source = defineMigrationSource(inputSource);
+		if (sourceNames.has(source.name)) throw new Error(`Duplicate migration source: ${source.name}`);
+		sourceNames.add(source.name);
+		const snapshots = /* @__PURE__ */ new Map();
+		for (const snapshot of [...source.resourceSnapshots ?? [], ...source.resources ? [source.resources] : []]) {
+			const normalized = defineMongoResources(snapshot);
+			if (normalized.checksum !== snapshot.checksum) throw new Error(`Invalid resource snapshot checksum in ${source.name}: ${snapshot.checksum}`);
+			snapshots.set(normalized.checksum, normalized);
+		}
+		const sourceMigrations = source.migrations.map((migration, sourcePosition) => {
+			if (migration.resources) {
+				if (migration.resources.before && !snapshots.has(migration.resources.before)) throw new Error(`Missing before resource snapshot for ${source.name}:${migration.id}`);
+				if (!snapshots.has(migration.resources.after)) throw new Error(`Missing after resource snapshot for ${source.name}:${migration.id}`);
+			}
+			const integrity = migrationChecksum(migration, source);
+			if (options.requireSealed && !integrity.sealed) throw new Error(`Migration ${source.name}:${migration.id} has no build-injected checksum`);
+			const compiled = Object.freeze({
+				...migration,
+				qualifiedId: `${source.name}:${migration.id}`,
+				source: source.name,
+				sourcePosition,
+				sourcePriority: priority,
+				dependsOn: Object.freeze((migration.dependsOn ?? []).map((id) => resolveDependencyId(source.name, id))),
+				rollback: migration.rollback ?? (migration.mode === "online" ? "compatible" : "incompatible"),
+				checksum: integrity.checksum,
+				sealed: integrity.sealed
+			});
+			migrations.push(compiled);
+			return compiled;
+		});
+		for (const scope of Object.keys(scopeRank)) {
+			let previousChecksum = null;
+			let previousResources = defineMongoResources();
+			for (const migration of sourceMigrations.filter((item) => item.scope === scope && item.resources)) {
+				const transition = migration.resources;
+				if (!transition) continue;
+				const beforeResources = transition.before ? snapshots.get(transition.before) : defineMongoResources();
+				if (!beforeResources || filterMongoResources(beforeResources, scope).checksum !== filterMongoResources(previousResources, scope).checksum) throw new Error(`Non-contiguous resource transition for ${migration.qualifiedId}: expected ${previousChecksum ?? "null"}`);
+				previousChecksum = transition.after;
+				previousResources = snapshots.get(previousChecksum) ?? defineMongoResources();
+			}
+			const currentForScope = source.resources ? filterMongoResources(source.resources, scope) : defineMongoResources();
+			if (currentForScope.collections.length > 0 || currentForScope.indexes.length > 0 || currentForScope.searchIndexes.length > 0 || currentForScope.collectionValidators.length > 0 || previousChecksum) {
+				if (!previousChecksum) throw new Error(`Source ${source.name} has unmanaged ${scope} resources without a migration`);
+				const previousSnapshot = snapshots.get(previousChecksum);
+				if (!previousSnapshot || filterMongoResources(previousSnapshot, scope).checksum !== currentForScope.checksum) throw new Error(`Latest ${scope} resource transition for ${source.name} does not match current resources`);
+			}
+		}
+		compiledSources.push(Object.freeze({
+			...source,
+			priority,
+			migrations: Object.freeze(sourceMigrations),
+			resourceSnapshots: snapshots
+		}));
+	}
+	const ordered = sortMigrations(migrations);
+	const migrationsById = /* @__PURE__ */ new Map();
+	for (const migration of ordered) {
+		if (migrationsById.has(migration.qualifiedId)) throw new Error(`Duplicate migration: ${migration.qualifiedId}`);
+		migrationsById.set(migration.qualifiedId, migration);
+	}
+	mergeMongoResources(compiledSources.flatMap((source) => source.resources ? [source.resources] : []));
+	return Object.freeze({
+		protocolVersion: 1,
+		sources: Object.freeze(compiledSources),
+		migrations: ordered,
+		migrationsById,
+		checksum: canonicalChecksum(ordered.map((migration) => ({
+			id: migration.qualifiedId,
+			checksum: migration.checksum
+		})))
+	});
+};
+//#endregion
+//#region src/indexDefinition.ts
+var ignoredIndexOptions = /* @__PURE__ */ new Set([
+	"background",
+	"key",
+	"name",
+	"ns",
+	"v"
+]);
+var falseDefaultOptions = /* @__PURE__ */ new Set([
+	"hidden",
+	"sparse",
+	"unique"
+]);
+var collationDefaults = /* @__PURE__ */ new Map([
+	["alternate", "non-ignorable"],
+	["backwards", false],
+	["caseFirst", "off"],
+	["caseLevel", false],
+	["maxVariable", "punct"],
+	["normalization", false],
+	["numericOrdering", false],
+	["strength", 3]
+]);
+var isDocument = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var hasDirection = (key, direction) => Object.values(key).some((value) => value === direction);
+var normalizeCollation = (value) => {
+	if (!isDocument(value)) return value;
+	return Object.fromEntries(Object.entries(value).filter(([name, option]) => name !== "version" && collationDefaults.get(name) !== option));
+};
+var normalizeWeights = (value) => {
+	if (!isDocument(value)) return value;
+	return Object.fromEntries(Object.entries(value).filter(([, weight]) => Number(weight) !== 1));
+};
+var normalizeIndexOptions = (options, key) => {
+	const normalized = Object.fromEntries(Object.entries(options).filter(([name, value]) => value !== void 0 && !ignoredIndexOptions.has(name) && !(falseDefaultOptions.has(name) && value === false)));
+	if (normalized.collation !== void 0) normalized.collation = normalizeCollation(normalized.collation);
+	if (normalized.weights !== void 0) {
+		normalized.weights = normalizeWeights(normalized.weights);
+		if (isDocument(normalized.weights) && Object.keys(normalized.weights).length === 0) delete normalized.weights;
+	}
+	if (hasDirection(key, "text")) {
+		if (normalized.default_language === "english") delete normalized.default_language;
+		if (normalized.language_override === "language") delete normalized.language_override;
+		if (Number(normalized.textIndexVersion) === 3) delete normalized.textIndexVersion;
+	}
+	if (hasDirection(key, "2dsphere") && Number(normalized["2dsphereIndexVersion"]) === 3) delete normalized["2dsphereIndexVersion"];
+	return normalized;
+};
+var normalizeIndexKey = (key, options, declaredKey) => {
+	const entries = Object.entries(key);
+	if (!(entries.some(([name, direction]) => name === "_fts" && direction === "text") && entries.some(([name, direction]) => name === "_ftsx" && direction === 1)) || !isDocument(options.weights)) return entries;
+	const actualTextFields = Object.keys(options.weights);
+	const actualTextFieldSet = new Set(actualTextFields);
+	const declaredTextFields = Object.entries(declaredKey).filter(([, direction]) => direction === "text").map(([name]) => name);
+	const orderedTextFields = [...declaredTextFields.filter((name) => actualTextFieldSet.has(name)), ...actualTextFields.filter((name) => !declaredTextFields.includes(name)).sort()];
+	return entries.flatMap(([name, direction]) => {
+		if (name === "_fts" && direction === "text") return orderedTextFields.map((field) => [field, "text"]);
+		if (name === "_ftsx" && direction === 1) return [];
+		return [[name, direction]];
+	});
+};
+var normalizeIndexDefinition = (key, options = {}, declaredKey = key) => ({
+	key: normalizeIndexKey(key, options, declaredKey),
+	options: normalizeIndexOptions(options, key)
+});
+//#endregion
+//#region src/inspectResources.ts
+var selectKeys = (document, expected) => {
+	if (!expected) return {};
+	return Object.fromEntries(Object.keys(expected).map((key) => [key, document?.[key]]));
+};
+var normalizeValidatorDefinition = (document) => ({
+	...document?.validator !== void 0 ? { validator: document.validator } : {},
+	...document?.validationLevel !== void 0 && document.validationLevel !== "strict" ? { validationLevel: document.validationLevel } : {},
+	...document?.validationAction !== void 0 && document.validationAction !== "error" ? { validationAction: document.validationAction } : {}
+});
+var same$1 = (left, right) => canonicalStringify(left) === canonicalStringify(right);
+var message = (collection, resource, detail) => `${collection}${resource ? `.${resource}` : ""}: ${detail}`;
+var inspectMongoResources = async (db, resources, options = {}) => {
+	const divergences = [];
+	const signal = options.signal;
+	signal?.throwIfAborted();
+	const collectionNames = /* @__PURE__ */ new Set([
+		...resources.collections.map((resource) => resource.name),
+		...resources.indexes.map((resource) => resource.collection),
+		...resources.searchIndexes.map((resource) => resource.collection),
+		...resources.collectionValidators.map((resource) => resource.collection)
+	]);
+	const listedCollections = collectionNames.size > 0 ? await db.listCollections({ name: { $in: [...collectionNames] } }, { nameOnly: false }).toArray() : [];
+	const collectionsByName = new Map(listedCollections.map((collection) => [collection.name, collection]));
+	for (const expected of resources.collections) {
+		const actual = collectionsByName.get(expected.name);
+		if (!actual) {
+			divergences.push({
+				code: "missing_collection",
+				scope: expected.scope,
+				collection: expected.name,
+				message: message(expected.name, void 0, "managed collection is missing")
+			});
+			continue;
+		}
+		const expectedOptions = expected.options ?? {};
+		const actualOptions = selectKeys(actual.options, expectedOptions);
+		if (!same$1(actualOptions, expectedOptions)) divergences.push({
+			code: "collection_options_mismatch",
+			scope: expected.scope,
+			collection: expected.name,
+			expected: expectedOptions,
+			actual: actualOptions,
+			message: message(expected.name, void 0, "collection options differ")
+		});
+	}
+	const indexesByCollection = /* @__PURE__ */ new Map();
+	for (const expected of resources.indexes) {
+		if (!collectionsByName.has(expected.collection)) {
+			divergences.push({
+				code: "missing_index",
+				scope: expected.scope,
+				collection: expected.collection,
+				resource: expected.name,
+				message: message(expected.collection, expected.name, "index collection is missing")
+			});
+			continue;
+		}
+		let indexes = indexesByCollection.get(expected.collection);
+		if (!indexes) {
+			indexes = await db.collection(expected.collection).listIndexes().toArray();
+			indexesByCollection.set(expected.collection, indexes);
+		}
+		const actual = indexes.find((index) => index.name === expected.name);
+		if (!actual) {
+			divergences.push({
+				code: "missing_index",
+				scope: expected.scope,
+				collection: expected.collection,
+				resource: expected.name,
+				message: message(expected.collection, expected.name, "managed index is missing")
+			});
+			continue;
+		}
+		const actualDefinition = normalizeIndexDefinition(actual.key ?? {}, actual, expected.key);
+		const expectedDefinition = normalizeIndexDefinition(expected.key, expected.options ?? {});
+		if (!same$1(actualDefinition.key, expectedDefinition.key)) divergences.push({
+			code: "index_key_mismatch",
+			scope: expected.scope,
+			collection: expected.collection,
+			resource: expected.name,
+			expected: expected.key,
+			actual: Object.fromEntries(actualDefinition.key),
+			message: message(expected.collection, expected.name, "index keys differ")
+		});
+		const expectedOptions = expectedDefinition.options;
+		const actualOptions = actualDefinition.options;
+		if (!same$1(actualOptions, expectedOptions)) divergences.push({
+			code: "index_options_mismatch",
+			scope: expected.scope,
+			collection: expected.collection,
+			resource: expected.name,
+			expected: expectedOptions,
+			actual: actualOptions,
+			message: message(expected.collection, expected.name, "index options differ")
+		});
+	}
+	for (const expected of resources.collectionValidators) {
+		const collection = collectionsByName.get(expected.collection);
+		const actual = collection?.options;
+		const expectedValidator = normalizeValidatorDefinition({
+			validator: expected.validator,
+			...expected.validationLevel ? { validationLevel: expected.validationLevel } : {},
+			...expected.validationAction ? { validationAction: expected.validationAction } : {}
+		});
+		const actualValidator = normalizeValidatorDefinition(actual);
+		if (!collection || !same$1(actualValidator, expectedValidator)) divergences.push({
+			code: "collection_validator_mismatch",
+			scope: expected.scope,
+			collection: expected.collection,
+			expected: expectedValidator,
+			actual: collection ? actualValidator : void 0,
+			message: message(expected.collection, void 0, "collection validator differs")
+		});
+	}
+	const searchIndexesByCollection = /* @__PURE__ */ new Map();
+	for (const expected of resources.searchIndexes) {
+		let indexes = searchIndexesByCollection.get(expected.collection);
+		if (!indexes) {
+			try {
+				indexes = await db.collection(expected.collection).listSearchIndexes().toArray();
+			} catch (error) {
+				indexes = error instanceof Error ? error : new Error(String(error));
+			}
+			searchIndexesByCollection.set(expected.collection, indexes);
+		}
+		if (indexes instanceof Error) {
+			divergences.push({
+				code: "search_unavailable",
+				scope: expected.scope,
+				collection: expected.collection,
+				resource: expected.name,
+				actual: indexes.message,
+				message: message(expected.collection, expected.name, "MongoDB Search inspection is unavailable")
+			});
+			continue;
+		}
+		const actual = indexes.find((index) => index.name === expected.name);
+		if (!actual) {
+			divergences.push({
+				code: "missing_search_index",
+				scope: expected.scope,
+				collection: expected.collection,
+				resource: expected.name,
+				message: message(expected.collection, expected.name, "managed Search index is missing")
+			});
+			continue;
+		}
+		if (!same$1(actual.latestDefinition, expected.definition)) divergences.push({
+			code: "search_index_definition_mismatch",
+			scope: expected.scope,
+			collection: expected.collection,
+			resource: expected.name,
+			expected: expected.definition,
+			actual: actual.latestDefinition,
+			message: message(expected.collection, expected.name, "Search index definition differs")
+		});
+		if (options.requireSearchReady && (actual.status !== "READY" || actual.queryable !== true)) divergences.push({
+			code: "search_index_not_ready",
+			scope: expected.scope,
+			collection: expected.collection,
+			resource: expected.name,
+			expected: {
+				status: "READY",
+				queryable: true
+			},
+			actual: {
+				status: actual.status,
+				queryable: actual.queryable
+			},
+			message: message(expected.collection, expected.name, "Search index is not ready and queryable")
+		});
+	}
+	signal?.throwIfAborted();
+	return divergences;
+};
+//#endregion
+//#region src/helpers.ts
+var namespaceExists = (error) => {
+	if (!error || typeof error !== "object") return false;
+	const value = error;
+	return value.code === 48 || value.codeName === "NamespaceExists";
+};
+var namespaceMissing = (error) => {
+	if (!error || typeof error !== "object") return false;
+	const value = error;
+	return value.code === 26 || value.codeName === "NamespaceNotFound";
+};
+var indexMissing = (error) => {
+	if (!error || typeof error !== "object") return false;
+	const value = error;
+	return value.code === 27 || value.codeName === "IndexNotFound";
+};
+var same = (left, right) => canonicalStringify(left) === canonicalStringify(right);
+var wait = async (milliseconds, signal) => {
+	signal.throwIfAborted();
+	await new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, milliseconds);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal.reason);
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+	signal.throwIfAborted();
+};
+var createMigrationHelpers = (db, signal, options = {}) => {
+	const searchTimeoutMs = options.searchTimeoutMs ?? 10 * 6e4;
+	const searchPollIntervalMs = options.searchPollIntervalMs ?? 1e3;
+	const ensureCollection = async (name, collectionOptions = {}) => {
+		signal.throwIfAborted();
+		if (await db.listCollections({ name }, { nameOnly: true }).hasNext()) return;
+		try {
+			await db.createCollection(name, collectionOptions);
+		} catch (error) {
+			if (!namespaceExists(error)) throw error;
+		}
+	};
+	const dropCollectionIfExists = async (name) => {
+		signal.throwIfAborted();
+		try {
+			await db.dropCollection(name);
+		} catch (error) {
+			if (!namespaceMissing(error)) throw error;
+		}
+	};
+	const ensureIndex = async (collectionName, key, indexOptions) => {
+		signal.throwIfAborted();
+		await ensureCollection(collectionName);
+		const collection = db.collection(collectionName);
+		const existing = (await collection.listIndexes().toArray()).find((index) => index.name === indexOptions.name);
+		if (existing) {
+			if (!same(normalizeIndexDefinition(existing.key ?? {}, existing, key), normalizeIndexDefinition(key, indexOptions))) throw new Error(`Index ${collectionName}.${indexOptions.name} exists with a different definition`);
+			return;
+		}
+		await collection.createIndex(key, indexOptions);
+	};
+	const dropIndexIfExists = async (collectionName, name) => {
+		signal.throwIfAborted();
+		try {
+			await db.collection(collectionName).dropIndex(name);
+		} catch (error) {
+			if (!namespaceMissing(error) && !indexMissing(error)) throw error;
+		}
+	};
+	const findDuplicateKeys = async (collectionName, key, duplicateOptions = {}) => {
+		signal.throwIfAborted();
+		const id = Object.keys(key).map((path) => `$${path}`);
+		const pipeline = [];
+		if (duplicateOptions.filter) pipeline.push({ $match: duplicateOptions.filter });
+		pipeline.push({ $group: {
+			_id: id,
+			count: { $sum: 1 }
+		} }, { $match: { count: { $gt: 1 } } }, { $limit: duplicateOptions.limit ?? 20 });
+		return (await db.collection(collectionName).aggregate(pipeline, duplicateOptions.collation ? { collation: duplicateOptions.collation } : {}).toArray()).map((document) => ({
+			key: document._id,
+			count: Number(document.count)
+		}));
+	};
+	const waitForSearchIndex = async (collectionName, name) => {
+		const deadline = Date.now() + searchTimeoutMs;
+		while (Date.now() < deadline) {
+			signal.throwIfAborted();
+			const index = (await db.collection(collectionName).listSearchIndexes(name).toArray())[0];
+			if (index?.status === "READY" && index.queryable === true) return;
+			if (index?.status === "FAILED") throw new Error(`Search index ${collectionName}.${name} failed to build`);
+			await wait(searchPollIntervalMs, signal);
+		}
+		throw new Error(`Timed out waiting for Search index ${collectionName}.${name}`);
+	};
+	const ensureSearchIndex = async (collectionName, name, definition) => {
+		signal.throwIfAborted();
+		await ensureCollection(collectionName);
+		const collection = db.collection(collectionName);
+		const existing = (await collection.listSearchIndexes(name).toArray())[0];
+		if (!existing) await collection.createSearchIndex({
+			name,
+			definition
+		});
+		else if (!same(existing.latestDefinition, definition)) await collection.updateSearchIndex(name, definition);
+		await waitForSearchIndex(collectionName, name);
+	};
+	const dropSearchIndexIfExists = async (collectionName, name) => {
+		signal.throwIfAborted();
+		const collection = db.collection(collectionName);
+		if ((await collection.listSearchIndexes(name).toArray()).length === 0) return;
+		await collection.dropSearchIndex(name);
+		const deadline = Date.now() + searchTimeoutMs;
+		while (Date.now() < deadline) {
+			signal.throwIfAborted();
+			if ((await collection.listSearchIndexes(name).toArray()).length === 0) return;
+			await wait(searchPollIntervalMs, signal);
+		}
+		throw new Error(`Timed out deleting Search index ${collectionName}.${name}`);
+	};
+	const setCollectionValidator = async (collection, validator, validatorOptions = {}) => {
+		signal.throwIfAborted();
+		await ensureCollection(collection);
+		await db.command({
+			collMod: collection,
+			validator,
+			...validatorOptions
+		});
+	};
+	return {
+		ensureCollection,
+		dropCollectionIfExists,
+		ensureIndex,
+		dropIndexIfExists,
+		findDuplicateKeys,
+		ensureSearchIndex,
+		dropSearchIndexIfExists,
+		setCollectionValidator,
+		reconcileResources: async (resources) => {
+			for (const collection of resources.collections) await ensureCollection(collection.name, collection.options);
+			for (const validator of resources.collectionValidators) await setCollectionValidator(validator.collection, validator.validator, {
+				...validator.validationLevel ? { validationLevel: validator.validationLevel } : {},
+				...validator.validationAction ? { validationAction: validator.validationAction } : {}
+			});
+			for (const index of resources.indexes) await ensureIndex(index.collection, index.key, {
+				name: index.name,
+				...index.options ?? {}
+			});
+			for (const index of resources.searchIndexes) await ensureSearchIndex(index.collection, index.name, index.definition);
+		}
+	};
+};
+//#endregion
+//#region src/errors.ts
+var MigrationIntegrityError = class extends Error {
+	code = "RB_MIGRATION_INTEGRITY";
+	constructor(message) {
+		super(message);
+		this.name = "MigrationIntegrityError";
+	}
+};
+var MigrationLockUnavailableError = class extends Error {
+	code = "RB_MIGRATION_LOCK_UNAVAILABLE";
+	constructor(message) {
+		super(message);
+		this.name = "MigrationLockUnavailableError";
+	}
+};
+var MigrationLockLostError = class extends Error {
+	code = "RB_MIGRATION_LOCK_LOST";
+	constructor(message) {
+		super(message);
+		this.name = "MigrationLockLostError";
+	}
+};
+//#endregion
+//#region src/history.ts
+var MIGRATIONS_COLLECTION = "rbmigrations";
+var readMigrationHistory = async (db) => db.collection(MIGRATIONS_COLLECTION).find({}).sort({
+	source: 1,
+	sourcePosition: 1
+}).toArray();
+//#endregion
+//#region src/databaseProvider.ts
+var normalizeAppName = (value) => {
+	const appName = value.trim();
+	if (!appName) throw new Error("Missing appName");
+	if (/[/\\."$*<>:|?]/.test(appName)) throw new Error(`Invalid appName: ${appName}`);
+	return appName;
+};
+var normalizeTenantId = (value) => {
+	const tenantId = value.trim();
+	if (!tenantId) throw new Error("Missing tenantId");
+	if (/[/\\."$*<>:|?]/.test(tenantId)) throw new Error(`Invalid tenantId: ${tenantId}`);
+	return tenantId;
+};
+var createMigrationDatabaseProvider = (options) => {
+	const appName = normalizeAppName(options.appName);
+	const globalDbName = `${appName}-global-db`;
+	const tenantCollection = options.tenantCollection?.trim() || "rbtenants";
+	return {
+		global: () => options.client.db(globalDbName),
+		tenantIds: async (signal) => {
+			signal.throwIfAborted();
+			const documents = await options.client.db(globalDbName).collection(tenantCollection).find({ $or: [{ provisioningStatus: { $exists: false } }, { provisioningStatus: "active" }] }, { projection: { tenantId: 1 } }).sort({ tenantId: 1 }).toArray();
+			signal.throwIfAborted();
+			return [...new Set(documents.flatMap((document) => typeof document.tenantId === "string" && document.tenantId.trim() ? [normalizeTenantId(document.tenantId)] : []))];
+		},
+		tenantExists: async (tenantId, signal) => {
+			signal.throwIfAborted();
+			const normalized = normalizeTenantId(tenantId);
+			const tenant = await options.client.db(globalDbName).collection(tenantCollection).findOne({ tenantId: normalized }, { projection: { _id: 1 } });
+			signal.throwIfAborted();
+			return Boolean(tenant);
+		},
+		tenant: (tenantId) => options.client.db(`${appName}-${normalizeTenantId(tenantId)}-db`),
+		filesystemRequired: options.filesystemRequired ?? (() => false),
+		filesystem: (tenantId) => options.client.db(`${appName}-${normalizeTenantId(tenantId)}-filesystem-db`)
+	};
+};
+var getMigrationDatabaseName = (db) => db.databaseName;
+//#endregion
+//#region src/planner.ts
+var neverAbortedSignal = new AbortController().signal;
+var toPlanItem = (migration) => ({
+	id: migration.qualifiedId,
+	checksum: migration.checksum,
+	source: migration.source,
+	scope: migration.scope,
+	mode: migration.mode,
+	rollback: migration.rollback,
+	dependsOn: migration.dependsOn
+});
+var historyById = (history) => new Map(history.map((record) => [record._id, record]));
+var validateKnownRecord = (migration, record, targetScope) => {
+	const errors = [];
+	if (record.checksum !== migration.checksum) errors.push(`${migration.qualifiedId}: checksum differs`);
+	if (record.source !== migration.source) errors.push(`${migration.qualifiedId}: source differs`);
+	if (record.sourcePosition !== migration.sourcePosition) errors.push(`${migration.qualifiedId}: source position differs`);
+	if (record.scope !== migration.scope) errors.push(`${migration.qualifiedId}: scope differs`);
+	if (migration.scope !== targetScope) errors.push(`${migration.qualifiedId}: migration history is stored in a ${targetScope} database`);
+	if (record.mode !== migration.mode) errors.push(`${migration.qualifiedId}: mode differs`);
+	if (record.rollback !== migration.rollback) errors.push(`${migration.qualifiedId}: rollback compatibility differs`);
+	if (![
+		"running",
+		"applied",
+		"failed"
+	].includes(record.status)) errors.push(`${migration.qualifiedId}: history status is invalid`);
+	const expectedBeforeHash = migration.resources?.before ?? void 0;
+	const expectedAfterHash = migration.resources?.after;
+	if (record.resourcesBeforeHash !== expectedBeforeHash) errors.push(`${migration.qualifiedId}: resource before checksum differs`);
+	if (record.resourcesAfterHash !== expectedAfterHash) errors.push(`${migration.qualifiedId}: resource after checksum differs`);
+	return errors;
+};
+var validateSourcePrefixes = (registry, scope, records) => {
+	const errors = [];
+	for (const source of registry.sources) {
+		let gap = null;
+		for (const migration of source.migrations.filter((item) => item.scope === scope)) {
+			const applied = records.get(migration.qualifiedId)?.status === "applied";
+			if (!applied && !gap) gap = migration;
+			if (applied && gap) errors.push(`${migration.qualifiedId}: applied after missing migration ${gap.qualifiedId}`);
+		}
+	}
+	return errors;
+};
+var getExpectedResources = (registry, scope, history) => {
+	const records = historyById(history);
+	const snapshots = [];
+	for (const source of registry.sources) {
+		let checksum = null;
+		for (const migration of source.migrations) {
+			if (migration.scope !== scope || !migration.resources) continue;
+			if (records.get(migration.qualifiedId)?.status === "applied") checksum = migration.resources.after;
+		}
+		if (!checksum) continue;
+		const snapshot = source.resourceSnapshots.get(checksum);
+		if (!snapshot) throw new Error(`Missing resource snapshot ${checksum} for ${source.name}`);
+		snapshots.push(filterMongoResources(snapshot, scope));
+	}
+	return mergeMongoResources(snapshots);
+};
+var planMigrationTarget = async (registry, target, options = {}) => {
+	const signal = options.signal ?? neverAbortedSignal;
+	signal.throwIfAborted();
+	const history = await readMigrationHistory(target.db);
+	const records = historyById(history);
+	const relevant = registry.migrations.filter((migration) => migration.scope === target.scope);
+	const integrityErrors = [];
+	const unknown = [];
+	for (const record of history) {
+		const migration = registry.migrationsById.get(record._id);
+		if (migration) {
+			integrityErrors.push(...validateKnownRecord(migration, record, target.scope));
+			continue;
+		}
+		unknown.push(record._id);
+		if (!(options.rollback && record.status === "applied" && record.mode === "online" && record.rollback === "compatible")) integrityErrors.push(`${record._id}: applied migration is absent from the registry`);
+	}
+	integrityErrors.push(...validateSourcePrefixes(registry, target.scope, records));
+	const applied = relevant.filter((migration) => records.get(migration.qualifiedId)?.status === "applied").map((migration) => migration.qualifiedId);
+	const pending = relevant.filter((migration) => !records.has(migration.qualifiedId)).map(toPlanItem);
+	const running = relevant.filter((migration) => records.get(migration.qualifiedId)?.status === "running").map((migration) => migration.qualifiedId);
+	const failed = relevant.filter((migration) => records.get(migration.qualifiedId)?.status === "failed").map((migration) => migration.qualifiedId);
+	const expectedResources = getExpectedResources(registry, target.scope, history);
+	const resourceDivergences = await inspectMongoResources(target.db, expectedResources, {
+		signal,
+		requireSearchReady: true
+	});
+	return {
+		database: target.db.databaseName,
+		scope: target.scope,
+		...target.tenantId ? { tenantId: target.tenantId } : {},
+		applied,
+		pending,
+		running,
+		failed,
+		unknown,
+		integrityErrors,
+		resourceDivergences
+	};
+};
+var collectMigrationTargets = async (provider, options = {}) => {
+	const signal = options.signal ?? neverAbortedSignal;
+	const targets = [{
+		db: await provider.global(),
+		scope: "global"
+	}];
+	let tenantIds;
+	if (options.tenantId) {
+		if (provider.tenantExists && !await provider.tenantExists(options.tenantId, signal)) throw new Error(`Unknown tenant: ${options.tenantId}`);
+		tenantIds = [options.tenantId];
+	} else tenantIds = [...await provider.tenantIds(signal)];
+	for (const tenantId of tenantIds) targets.push({
+		db: await provider.tenant(tenantId),
+		scope: "tenant",
+		tenantId
+	});
+	if (provider.filesystem) {
+		for (const tenantId of tenantIds) if (await provider.filesystemRequired?.(tenantId, signal) ?? false) targets.push({
+			db: await provider.filesystem(tenantId),
+			scope: "filesystem",
+			tenantId
+		});
+	}
+	return targets;
+};
+var planMigrations = async (registry, provider, options = {}) => {
+	const targets = await collectMigrationTargets(provider, options);
+	const databases = [];
+	for (const target of targets) databases.push(await planMigrationTarget(registry, target, options));
+	return {
+		protocolVersion: 1,
+		registryChecksum: registry.checksum,
+		databases,
+		hasPending: databases.some((database) => database.pending.length > 0 || database.running.length > 0 || database.failed.length > 0),
+		hasOffline: databases.some((database) => database.pending.some((migration) => migration.mode === "offline") || [...database.running, ...database.failed].some((id) => registry.migrationsById.get(id)?.mode === "offline")),
+		hasErrors: databases.some((database) => database.integrityErrors.length > 0 || database.running.length === 0 && database.failed.length === 0 && database.resourceDivergences.length > 0)
+	};
+};
+//#endregion
+//#region src/lock.ts
+var MIGRATION_LOCKS_COLLECTION = "rbmigrationlocks";
+var isDuplicateKey = (error) => Boolean(error && typeof error === "object" && "code" in error && error.code === 11e3);
+var acquireMigrationLock = async (db, options = {}) => {
+	const lockId = options.lockId?.trim() || "default";
+	const owner = options.owner?.trim() || randomUUID();
+	const runId = options.runId?.trim() || randomUUID();
+	const leaseMs = options.leaseMs ?? 12e4;
+	const heartbeatMs = options.heartbeatMs ?? 3e4;
+	if (leaseMs <= 0) throw new Error("Migration lock lease must be positive");
+	if (heartbeatMs <= 0 || heartbeatMs >= leaseMs) throw new Error("Migration lock heartbeat must be positive and shorter than the lease");
+	const collection = db.collection(MIGRATION_LOCKS_COLLECTION);
+	let document;
+	try {
+		await collection.updateOne({ _id: lockId }, { $setOnInsert: {
+			owner: "",
+			runId: "",
+			fence: 0,
+			expiresAt: /* @__PURE__ */ new Date(0)
+		} }, {
+			upsert: true,
+			writeConcern: { w: "majority" }
+		});
+		document = await collection.findOneAndUpdate({
+			_id: lockId,
+			$expr: { $or: [{ $lte: [{ $ifNull: ["$expiresAt", /* @__PURE__ */ new Date(0)] }, "$$NOW"] }, { $eq: ["$owner", owner] }] }
+		}, [{ $set: {
+			owner,
+			runId,
+			fence: { $add: [{ $ifNull: ["$fence", 0] }, 1] },
+			acquiredAt: "$$NOW",
+			heartbeatAt: "$$NOW",
+			expiresAt: { $dateAdd: {
+				startDate: "$$NOW",
+				unit: "millisecond",
+				amount: leaseMs
+			} }
+		} }], {
+			returnDocument: "after",
+			writeConcern: { w: "majority" }
+		});
+	} catch (error) {
+		if (isDuplicateKey(error)) throw new MigrationLockUnavailableError(`Migration lock ${lockId} is held by another runner`);
+		throw error;
+	}
+	if (!document || document.owner !== owner || document.runId !== runId) throw new MigrationLockUnavailableError(`Migration lock ${lockId} could not be acquired`);
+	const fence = document.fence;
+	const abortController = new AbortController();
+	let state = "active";
+	let heartbeatTimer;
+	let heartbeatPromise = null;
+	const lose = (reason, cause) => {
+		const error = new MigrationLockLostError(`Migration lock ${lockId} was lost: ${reason}`);
+		if (cause !== void 0) error.cause = cause;
+		if (state === "active") {
+			state = "lost";
+			if (heartbeatTimer) clearTimeout(heartbeatTimer);
+			abortController.abort(error);
+		}
+		return error;
+	};
+	const assertOwned = async () => {
+		if (state === "lost") throw abortController.signal.reason;
+		if (state !== "active") throw new MigrationLockLostError(`Migration lock ${lockId} is no longer active`);
+		if (!await collection.findOne({
+			_id: lockId,
+			owner,
+			runId,
+			fence,
+			$expr: { $gt: ["$expiresAt", "$$NOW"] }
+		}, { projection: { _id: 1 } })) throw lose("ownership or lease expiry could not be confirmed");
+	};
+	const heartbeat = async () => {
+		if (state !== "active") return;
+		if ((await collection.updateOne({
+			_id: lockId,
+			owner,
+			runId,
+			fence,
+			$expr: { $gt: ["$expiresAt", "$$NOW"] }
+		}, [{ $set: {
+			heartbeatAt: "$$NOW",
+			expiresAt: { $dateAdd: {
+				startDate: "$$NOW",
+				unit: "millisecond",
+				amount: leaseMs
+			} }
+		} }], { writeConcern: { w: "majority" } })).modifiedCount !== 1) throw lose("heartbeat was rejected");
+	};
+	const scheduleHeartbeat = () => {
+		if (state !== "active") return;
+		heartbeatTimer = setTimeout(() => {
+			heartbeatPromise = heartbeat().catch((error) => {
+				if (state === "active") lose("heartbeat failed", error);
+			}).finally(() => {
+				heartbeatPromise = null;
+				scheduleHeartbeat();
+			});
+		}, heartbeatMs);
+		heartbeatTimer.unref?.();
+	};
+	const release = async () => {
+		if (state === "released") return;
+		if (heartbeatTimer) clearTimeout(heartbeatTimer);
+		if (heartbeatPromise) await heartbeatPromise.catch(() => void 0);
+		if (state === "lost") return;
+		state = "released";
+		await collection.updateOne({
+			_id: lockId,
+			owner,
+			runId,
+			fence
+		}, {
+			$set: {
+				expiresAt: /* @__PURE__ */ new Date(0),
+				releasedAt: /* @__PURE__ */ new Date()
+			},
+			$unset: {
+				owner: "",
+				runId: ""
+			}
+		}, { writeConcern: { w: "majority" } });
+	};
+	scheduleHeartbeat();
+	return {
+		owner,
+		runId,
+		fence,
+		signal: abortController.signal,
+		assertOwned,
+		release
+	};
+};
+//#endregion
+//#region src/runner.ts
+var errorMessage = (error) => {
+	return (error instanceof Error ? error.message : String(error)).slice(0, 8e3);
+};
+var combineSignals = (...signals) => {
+	const active = signals.filter((signal) => Boolean(signal));
+	if (active.length === 0) return new AbortController().signal;
+	if (active.length === 1) return active[0];
+	return AbortSignal.any(active);
+};
+var assertPlanCanRun = (plan) => {
+	const retrying = plan.running.length > 0 || plan.failed.length > 0;
+	const errors = [...plan.integrityErrors, ...retrying ? [] : plan.resourceDivergences.map((divergence) => divergence.message)];
+	if (errors.length > 0) throw new MigrationIntegrityError(`${plan.database}: ${errors.join("; ")}`);
+};
+var recordForMigration = (migration, lock, attempt, release) => ({
+	_id: migration.qualifiedId,
+	checksum: migration.checksum,
+	source: migration.source,
+	sourcePosition: migration.sourcePosition,
+	scope: migration.scope,
+	mode: migration.mode,
+	rollback: migration.rollback,
+	status: "running",
+	attempt,
+	...migration.resources?.before ? { resourcesBeforeHash: migration.resources.before } : {},
+	...migration.resources ? { resourcesAfterHash: migration.resources.after } : {},
+	...release ? { release } : {},
+	runId: lock.runId,
+	fence: lock.fence,
+	startedAt: /* @__PURE__ */ new Date(),
+	heartbeatAt: /* @__PURE__ */ new Date()
+});
+var startMigration = async (collection, migration, lock, release) => {
+	await lock.assertOwned();
+	const existing = await collection.findOne({ _id: migration.qualifiedId });
+	if (existing?.status === "applied") return existing;
+	if (existing && existing.checksum !== migration.checksum) throw new MigrationIntegrityError(`${migration.qualifiedId}: checksum differs`);
+	const record = recordForMigration(migration, lock, (existing?.attempt ?? 0) + 1, release);
+	if (!existing) {
+		await collection.insertOne(record, { writeConcern: { w: "majority" } });
+		return record;
+	}
+	const { _id: _recordId, ...recordUpdates } = record;
+	const result = await collection.findOneAndUpdate({
+		_id: migration.qualifiedId,
+		checksum: migration.checksum,
+		status: { $in: ["running", "failed"] }
+	}, {
+		$set: {
+			...recordUpdates,
+			...existing.checkpoint !== void 0 ? { checkpoint: existing.checkpoint } : {}
+		},
+		$unset: {
+			error: "",
+			appliedAt: "",
+			durationMs: ""
+		}
+	}, {
+		returnDocument: "after",
+		writeConcern: { w: "majority" }
+	});
+	if (!result) throw new MigrationIntegrityError(`${migration.qualifiedId}: history state changed while starting`);
+	return result;
+};
+var createCheckpoint = (collection, migration, record, lock) => {
+	let value = record.checkpoint;
+	const update = async (next, clear) => {
+		await lock.assertOwned();
+		if ((await collection.updateOne({
+			_id: migration.qualifiedId,
+			checksum: migration.checksum,
+			status: "running",
+			runId: lock.runId,
+			fence: lock.fence
+		}, clear ? {
+			$unset: { checkpoint: "" },
+			$set: { heartbeatAt: /* @__PURE__ */ new Date() }
+		} : { $set: {
+			checkpoint: next,
+			heartbeatAt: /* @__PURE__ */ new Date()
+		} }, { writeConcern: { w: "majority" } })).matchedCount !== 1) throw new MigrationLockLostError(`${migration.qualifiedId}: checkpoint ownership was lost`);
+		value = next;
+	};
+	return {
+		get value() {
+			return value;
+		},
+		save: async (next) => update(next, false),
+		clear: async () => update(void 0, true)
+	};
+};
+var markFailed = async (collection, migration, lock, error) => {
+	await collection.updateOne({
+		_id: migration.qualifiedId,
+		checksum: migration.checksum,
+		status: "running",
+		runId: lock.runId,
+		fence: lock.fence
+	}, { $set: {
+		status: "failed",
+		error: errorMessage(error),
+		heartbeatAt: /* @__PURE__ */ new Date()
+	} }, { writeConcern: { w: "majority" } });
+};
+var markApplied = async (collection, migration, record, lock) => {
+	await lock.assertOwned();
+	const appliedAt = /* @__PURE__ */ new Date();
+	if ((await collection.updateOne({
+		_id: migration.qualifiedId,
+		checksum: migration.checksum,
+		status: "running",
+		runId: lock.runId,
+		fence: lock.fence
+	}, {
+		$set: {
+			status: "applied",
+			appliedAt,
+			heartbeatAt: appliedAt,
+			durationMs: appliedAt.getTime() - record.startedAt.getTime()
+		},
+		$unset: { error: "" }
+	}, { writeConcern: { w: "majority" } })).matchedCount !== 1) throw new MigrationLockLostError(`${migration.qualifiedId}: apply ownership was lost`);
+};
+var getExpectedTransitionSnapshot = (snapshots, checksum, scope) => {
+	const snapshot = snapshots.get(checksum);
+	if (!snapshot) throw new MigrationIntegrityError(`Missing resource snapshot ${checksum}`);
+	return filterMongoResources(snapshot, scope);
+};
+var applyMigration = async (registry, target, migration, lock, signal, release) => {
+	signal.throwIfAborted();
+	const collection = target.db.collection(MIGRATIONS_COLLECTION);
+	const record = await startMigration(collection, migration, lock, release);
+	if (record.status === "applied") return;
+	const checkpoint = createCheckpoint(collection, migration, record, lock);
+	const source = registry.sources.find((item) => item.name === migration.source);
+	const resourceTransition = migration.resources && source ? {
+		...migration.resources.before ? { before: getExpectedTransitionSnapshot(source.resourceSnapshots, migration.resources.before, target.scope) } : {},
+		after: getExpectedTransitionSnapshot(source.resourceSnapshots, migration.resources.after, target.scope)
+	} : void 0;
+	try {
+		await migration.up({
+			db: target.db,
+			...target.tenantId ? { tenantId: target.tenantId } : {},
+			checkpoint,
+			signal,
+			helpers: createMigrationHelpers(target.db, signal),
+			...resourceTransition ? { resources: resourceTransition } : {}
+		});
+		signal.throwIfAborted();
+		if (migration.resources) {
+			const hypothetical = (await readMigrationHistory(target.db)).map((item) => item._id === migration.qualifiedId ? {
+				...item,
+				status: "applied"
+			} : item);
+			const expected = getExpectedResources(registry, target.scope, hypothetical);
+			const divergences = await inspectMongoResources(target.db, expected, {
+				signal,
+				requireSearchReady: true
+			});
+			if (divergences.length > 0) throw new MigrationIntegrityError(divergences.map((divergence) => divergence.message).join("; "));
+		}
+		await markApplied(collection, migration, record, lock);
+	} catch (error) {
+		await markFailed(collection, migration, lock, error).catch(() => void 0);
+		throw error;
+	}
+};
+var sourcePredecessorsApplied = (registry, migration, applied) => registry.sources.find((source) => source.name === migration.source)?.migrations.filter((candidate) => candidate.scope === migration.scope && candidate.sourcePosition < migration.sourcePosition).every((candidate) => applied.has(candidate.qualifiedId)) ?? false;
+var runTarget = async (registry, target, lock, signal, options, earlierScopeDependencyApplied) => {
+	const plan = await planMigrationTarget(registry, target, { signal });
+	assertPlanCanRun(plan);
+	const applied = new Set(plan.applied);
+	const migrationsToRun = registry.migrations.filter((migration) => migration.scope === target.scope && !applied.has(migration.qualifiedId));
+	for (const migration of migrationsToRun) {
+		if (migration.mode === "offline" && !options.allowOffline) continue;
+		if (!sourcePredecessorsApplied(registry, migration, applied)) continue;
+		let dependenciesReady = true;
+		for (const dependencyId of migration.dependsOn) {
+			const dependency = registry.migrationsById.get(dependencyId);
+			if (!dependency) throw new MigrationIntegrityError(`Unknown dependency ${dependencyId}`);
+			if (!(dependency.scope === target.scope ? applied.has(dependencyId) : await earlierScopeDependencyApplied(dependency))) {
+				dependenciesReady = false;
+				break;
+			}
+		}
+		if (!dependenciesReady) continue;
+		await applyMigration(registry, target, migration, lock, signal, options.release);
+		applied.add(migration.qualifiedId);
+	}
+	return applied;
+};
+var runWithConcurrency = async (values, concurrency, action) => {
+	let nextIndex = 0;
+	let failed = false;
+	let failure;
+	const workers = Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+		while (nextIndex < values.length && !failed) {
+			const index = nextIndex;
+			nextIndex += 1;
+			try {
+				await action(values[index]);
+			} catch (error) {
+				if (!failed) failure = error;
+				failed = true;
+			}
+		}
+	});
+	await Promise.all(workers);
+	if (failed) throw failure;
+};
+var runMigrations = async (registry, provider, options = {}) => {
+	const concurrency = options.concurrency ?? 4;
+	if (!Number.isInteger(concurrency) || concurrency < 1) throw new Error("Migration concurrency must be a positive integer");
+	const lock = await acquireMigrationLock(await provider.global(), {
+		lockId: options.lockId,
+		leaseMs: options.leaseMs,
+		heartbeatMs: options.heartbeatMs
+	});
+	const signal = combineSignals(options.signal, lock.signal);
+	try {
+		const targets = await collectMigrationTargets(provider, {
+			tenantId: options.tenantId,
+			signal
+		});
+		const globalTarget = targets.find((target) => target.scope === "global");
+		if (!globalTarget) throw new Error("Migration provider did not return a global database");
+		let globalApplied = /* @__PURE__ */ new Set();
+		if (options.initializeTenant) {
+			const globalPlan = await planMigrationTarget(registry, globalTarget, { signal });
+			assertPlanCanRun(globalPlan);
+			if (globalPlan.pending.length > 0 || globalPlan.running.length > 0 || globalPlan.failed.length > 0) throw new MigrationIntegrityError("Global migrations must be current before initializing a tenant");
+			globalApplied = new Set(globalPlan.applied);
+		} else globalApplied = await runTarget(registry, globalTarget, lock, signal, options, async () => false);
+		const tenantApplied = /* @__PURE__ */ new Map();
+		await runWithConcurrency(targets.filter((target) => target.scope === "tenant"), concurrency, async (target) => {
+			const applied = await runTarget(registry, target, lock, signal, options, async (dependency) => dependency.scope === "global" && globalApplied.has(dependency.qualifiedId));
+			if (target.tenantId) tenantApplied.set(target.tenantId, applied);
+		});
+		await runWithConcurrency(targets.filter((target) => target.scope === "filesystem"), concurrency, async (target) => {
+			const appliedForTenant = target.tenantId ? tenantApplied.get(target.tenantId) : void 0;
+			await runTarget(registry, target, lock, signal, options, async (dependency) => {
+				if (dependency.scope === "global") return globalApplied.has(dependency.qualifiedId);
+				if (dependency.scope === "tenant") return appliedForTenant?.has(dependency.qualifiedId) ?? false;
+				return false;
+			});
+		});
+		return await planMigrations(registry, provider, {
+			tenantId: options.tenantId,
+			signal
+		});
+	} finally {
+		await lock.release();
+	}
+};
+var initializeTenantMigrations = async (registry, provider, tenantId, options = {}) => await runMigrations(registry, provider, {
+	...options,
+	tenantId,
+	allowOffline: true,
+	initializeTenant: true
+});
+//#endregion
+//#region src/assertCurrent.ts
+var assertMigrationsCurrent = async (registry, provider, options = {}) => {
+	const plan = await planMigrations(registry, provider, options);
+	const errors = [];
+	for (const database of plan.databases) {
+		if (database.pending.length > 0) errors.push(`${database.database}: ${database.pending.length} migration(s) pending`);
+		if (database.running.length > 0) errors.push(`${database.database}: migration running`);
+		if (database.failed.length > 0) errors.push(`${database.database}: migration failed`);
+		errors.push(...database.integrityErrors.map((error) => `${database.database}: ${error}`));
+		errors.push(...database.resourceDivergences.map((divergence) => `${database.database}: ${divergence.message}`));
+	}
+	if (errors.length > 0) throw new MigrationIntegrityError(errors.join("; "));
+	return plan;
+};
+//#endregion
+//#region src/integrity.ts
+var relativeImportPattern = /^(?:\.\.?\/)/;
+var migrationCallPattern = /defineMigration(?:<[^>]+>)?\s*\(\s*\{/;
+var incompleteCollectionMigrationPattern = /Implement the collection option migration for/;
+var typeOnlyImportPattern = /^import\s+type\b/;
+initSync();
+var resolveLocalImport = (importer, specifier) => {
+	const base = resolve(dirname(importer), specifier);
+	const resolved = (extname(base) ? [base] : [
+		`${base}.ts`,
+		`${base}.tsx`,
+		`${base}.js`,
+		`${base}.mjs`,
+		resolve(base, "index.ts"),
+		resolve(base, "index.tsx"),
+		resolve(base, "index.js")
+	]).find((candidate) => existsSync(candidate));
+	if (!resolved) throw new Error(`Cannot resolve migration import ${specifier} from ${importer}`);
+	return resolved;
+};
+var collectIntegrityFiles = (entry, rootDir, files, visiting) => {
+	const filePath = resolve(entry);
+	if (visiting.has(filePath) || files.has(filePath)) return;
+	if (!filePath.startsWith(`${rootDir}/`) && filePath !== rootDir) throw new Error(`Migration dependency escapes integrity root: ${filePath}`);
+	visiting.add(filePath);
+	const source = readFileSync(filePath, "utf8");
+	const [imports] = parse(source, filePath);
+	for (const imported of imports) {
+		if (imported.t === ImportType.Dynamic || imported.t === ImportType.DynamicSourcePhase || imported.t === ImportType.DynamicDeferPhase) throw new Error(`Dynamic imports are not allowed in migrations: ${filePath}`);
+		if (imported.t === ImportType.ImportMeta) continue;
+		const declaration = source.slice(imported.ss, imported.se);
+		if (typeOnlyImportPattern.test(declaration)) continue;
+		const specifier = imported.n;
+		if (!specifier) throw new Error(`Cannot resolve migration import in ${filePath}`);
+		if (specifier === "@rpcbase/migrations") continue;
+		if (!relativeImportPattern.test(specifier)) throw new Error(`Mutable runtime import "${specifier}" is not allowed in migration ${filePath}`);
+		collectIntegrityFiles(resolveLocalImport(filePath, specifier), rootDir, files, visiting);
+	}
+	visiting.delete(filePath);
+	files.set(filePath, source);
+};
+var computeMigrationIntegrity = (entry, options = {}) => {
+	const entryPath = resolve(entry);
+	const rootDir = resolve(options.rootDir ?? dirname(entryPath));
+	const files = /* @__PURE__ */ new Map();
+	collectIntegrityFiles(entryPath, rootDir, files, /* @__PURE__ */ new Set());
+	return canonicalChecksum([...files.entries()].map(([filePath, source]) => ({
+		path: filePath.slice(rootDir.length),
+		checksum: sha256(source)
+	})).sort((left, right) => left.path.localeCompare(right.path)));
+};
+var createMigrationIntegrityPlugin = (options = {}) => ({
+	name: "rpcbase-migration-integrity",
+	enforce: "pre",
+	transform(code, id) {
+		const cleanId = id.split("?", 1)[0];
+		if (!isAbsolute(cleanId) || !migrationCallPattern.test(code)) return null;
+		if (incompleteCollectionMigrationPattern.test(code)) throw new Error(`Incomplete collection option migration: ${cleanId}`);
+		const integrity = computeMigrationIntegrity(cleanId, { rootDir: resolve(options.rootDir ?? dirname(cleanId)) });
+		return {
+			code: code.replace(migrationCallPattern, (match) => `${match}\n  __rpcbaseIntegrity: ${JSON.stringify(integrity)},`),
+			map: null
+		};
+	}
+});
+//#endregion
+//#region src/testHarness.ts
+var testAppNamePattern = /^rbmtest-[a-f0-9]{24}$/;
+var testTenantIdPattern = /^[a-z0-9][a-z0-9_-]{0,15}$/;
+var createTestAppName = () => `rbmtest-${randomUUID().replaceAll("-", "").slice(0, 24)}`;
+var assertTestAppName = (appName) => {
+	if (!testAppNamePattern.test(appName)) throw new Error(`Refusing to use unsafe migrations test app name: ${appName}`);
+};
+var databaseNames = (appName, tenantId) => [
+	`${appName}-global-db`,
+	`${appName}-${tenantId}-db`,
+	`${appName}-${tenantId}-filesystem-db`
+];
+var testMigrationRegistry = async (options) => {
+	const appName = options.appName ?? createTestAppName();
+	const recoveryAppName = createTestAppName();
+	const tenantId = options.tenantId ?? "tenant";
+	assertTestAppName(appName);
+	assertTestAppName(recoveryAppName);
+	if (!testTenantIdPattern.test(tenantId)) throw new Error(`Refusing to use unsafe migrations test tenant id: ${tenantId}`);
+	const databases = [...databaseNames(appName, tenantId), ...databaseNames(recoveryAppName, tenantId)];
+	try {
+		const provider = createMigrationDatabaseProvider({
+			client: options.client,
+			appName,
+			filesystemRequired: () => true
+		});
+		await (await provider.global()).collection("rbtenants").insertOne({
+			tenantId,
+			provisioningStatus: "active"
+		});
+		await runMigrations(options.registry, provider, {
+			allowOffline: true,
+			concurrency: 1,
+			signal: options.signal
+		});
+		await assertMigrationsCurrent(options.registry, provider, { signal: options.signal });
+		const recoveryRegistry = compileMigrationRegistry([defineMigrationSource({
+			name: "rbmtest",
+			migrations: [defineMigration({
+				id: "20000101000000-checkpoint-recovery",
+				scope: "global",
+				mode: "online",
+				async up({ checkpoint }) {
+					if (checkpoint.value === 1) return;
+					await checkpoint.save(1);
+					throw new Error("simulated migration interruption");
+				}
+			})]
+		})]);
+		const recoveryProvider = createMigrationDatabaseProvider({
+			client: options.client,
+			appName: recoveryAppName
+		});
+		await runMigrations(recoveryRegistry, recoveryProvider, { signal: options.signal }).then(() => {
+			throw new Error("Checkpoint recovery probe did not interrupt");
+		}, (error) => {
+			if (!(error instanceof Error) || error.message !== "simulated migration interruption") throw error;
+		});
+		await runMigrations(recoveryRegistry, recoveryProvider, { signal: options.signal });
+		await assertMigrationsCurrent(recoveryRegistry, recoveryProvider, { signal: options.signal });
+		const history = await (await recoveryProvider.global()).collection(MIGRATIONS_COLLECTION).findOne({ _id: "rbmtest:20000101000000-checkpoint-recovery" });
+		if (!history || history.status !== "applied" || history.checkpoint !== 1 || history.attempt !== 2) throw new Error("Checkpoint recovery probe did not resume from its saved checkpoint");
+		return {
+			appName,
+			tenantId,
+			checkpointRecoveryAttempt: history.attempt
+		};
+	} finally {
+		await Promise.all(databases.map(async (databaseName) => {
+			if (!databaseName.startsWith(`${appName}-`) && !databaseName.startsWith(`${recoveryAppName}-`)) throw new Error(`Refusing to clean unsafe migrations test database: ${databaseName}`);
+			await options.client.db(databaseName).dropDatabase();
+		}));
+	}
+};
+var testSingleMigration = async (options) => {
+	const appName = createTestAppName();
+	assertTestAppName(appName);
+	const tenantId = options.tenantId ?? "tenant";
+	const scope = options.scope ?? options.migration.scope;
+	if (scope !== "global" && !testTenantIdPattern.test(tenantId)) throw new Error(`Refusing to use unsafe migrations test tenant id: ${tenantId}`);
+	const databaseName = scope === "global" ? `${appName}-global-db` : scope === "filesystem" ? `${appName}-${tenantId}-filesystem-db` : `${appName}-${tenantId}-db`;
+	const db = options.client.db(databaseName);
+	const controller = new AbortController();
+	const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+	try {
+		await options.prepare(db);
+		let checkpointValue = options.checkpoint;
+		const context = {
+			db,
+			...scope === "global" ? {} : { tenantId },
+			checkpoint: {
+				get value() {
+					return checkpointValue;
+				},
+				save: async (value) => {
+					checkpointValue = value;
+				},
+				clear: async () => {
+					checkpointValue = void 0;
+				}
+			},
+			signal,
+			helpers: createMigrationHelpers(db, signal)
+		};
+		await options.migration.up(context);
+		await options.verify(db);
+	} finally {
+		controller.abort();
+		await db.dropDatabase();
+	}
+};
+//#endregion
+export { MIGRATIONS_COLLECTION, MIGRATION_LOCKS_COLLECTION, MigrationIntegrityError, MigrationLockLostError, MigrationLockUnavailableError, acquireMigrationLock, assertMigrationsCurrent, canonicalChecksum, canonicalStringify, collectMigrationTargets, compileMigrationRegistry, computeMigrationIntegrity, createMigrationDatabaseProvider, createMigrationHelpers, createMigrationIntegrityPlugin, defineMigration, defineMigrationSource, defineMongoResources, diffMongoResources, filterMongoResources, getExpectedResources, getMigrationDatabaseName, initializeTenantMigrations, inspectMongoResources, mergeMongoResources, planMigrationTarget, planMigrations, readMigrationHistory, runMigrations, sha256, testMigrationRegistry, testSingleMigration };
+
+//# sourceMappingURL=index.js.map