breakage 0.9.0 → 0.9.1

package/dist/{breakage-DIY49fzP.js → breakage-DJiIiLzL.js}

@@ -6,10 +6,10 @@ import { simpleGit } from "simple-git";
 import logger from "takua";
 import { spawn } from "node:child_process";
 import * as fs from "node:fs/promises";
-import { chmod, copyFile, lstat, mkdir, readFile, readdir, realpath, rename, rm, rmdir, writeFile } from "node:fs/promises";
+import { chmod, copyFile, glob, lstat, mkdir, readFile, readdir, realpath, rename, rm, rmdir, writeFile } from "node:fs/promises";
 import semver from "semver";
 import { type } from "arktype";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { setTimeout } from "node:timers/promises";
 import { existsSync } from "node:fs";
 import { cli, options } from "comline";
@@ -455,6 +455,235 @@ function validateConfig(value) {
 function validatePeerRanges(peers) {
 	for (const range of Object.values(peers)) eras(range);
 }
+// src/npm/matrix-model.ts
+const npmMatrixConfigSchema = type({
+	"+": `reject`,
+	configs: `string | string[]`,
+	prepare: type(`string`).or(type(`Function`).as()),
+	"label?": type(`Function`).as()
+});
+const transition = type({
+	previousVersion: `string`,
+	version: `string`,
+	delta: `'major' | 'premajor' | 'minor' | 'preminor' | 'patch' | 'prepatch' | 'prerelease' | 'release' | 'none'`
+});
+const identity = type({
+	version: `string`,
+	source: `'installed' | 'candidate'`
+});
+const reportSchema = type({
+	package: {
+		name: `string`,
+		version: `string`
+	},
+	mode: `'check' | 'test' | 'coverage-only'`,
+	exitCode: `0 | 1 | 2`,
+	errors: `string[]`,
+	coverage: type({
+		peer: `string`,
+		era: `string`,
+		representatives: `string[]`
+	}).array(),
+	support: {
+		status: `'unchanged' | 'breaking-release' | 'end-of-support' | 'first-release' | 'not-checked' | 'setup-error'`,
+		changes: type({
+			peer: `string`,
+			reason: `'narrowed-range' | 'required-peer'`,
+			previous: `string | null`,
+			current: `string | null`
+		}).array(),
+		"previousVersion?": `string`,
+		"release?": transition.and({ breaking: `boolean` }),
+		"error?": `string`
+	},
+	representatives: type({
+		path: `string`,
+		status: `'passed' | 'audited' | 'skipped' | 'compatibility-failure' | 'setup-error'`,
+		peers: { "[string]": identity.and({
+			path: `string`,
+			"archiveVersion?": `string`
+		}) },
+		suites: type({
+			peer: `string`,
+			status: `'passed' | 'compatibility-failure' | 'setup-error' | 'not-run'`,
+			"output?": `string`
+		}).array(),
+		warnings: `string[]`,
+		"error?": `string`
+	}).array()
+}).as();
+const npmPlanSchema = type({
+	"+": `reject`,
+	formatVersion: `1`,
+	id: `string`,
+	runId: `string`,
+	commit: `string`,
+	configs: `string[]`,
+	packages: type({
+		config: `string`,
+		directory: `string`,
+		name: `string`,
+		configDigest: `string`,
+		inputDigest: `string`,
+		audit: reportSchema,
+		releases: type({
+			context: {
+				packageName: `string`,
+				packageDirectory: `string`,
+				currentVersion: `string`,
+				"baseline?": {
+					version: `string`,
+					"ref?": `string`,
+					"commit?": `string`
+				}
+			},
+			"transition?": transition
+		}).array()
+	}).array(),
+	environments: type({
+		id: `string`,
+		label: `string`,
+		packageName: `string`,
+		representative: `string`,
+		suites: `string[]`,
+		peers: { "[string]": identity }
+	}).array(),
+	archives: type({
+		path: `string`,
+		file: `string`,
+		sha256: `string`
+	}).array()
+});
+const npmReceiptSchema = type({
+	"+": `reject`,
+	formatVersion: `1`,
+	planId: `string`,
+	id: `string`,
+	exitCode: `0 | 1 | 2`,
+	"report?": reportSchema,
+	"error?": `string`
+});
+/** Stable object ordering; arrays retain their semantic order. */
+function canonical(value) {
+	if (Array.isArray(value)) return `[${value.map(canonical).join(`,`)}]`;
+	if (value && typeof value === `object`) return `{${Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(`,`)}}`;
+	return JSON.stringify(value) ?? `undefined`;
+}
+function digest(value) {
+	return createHash(`sha256`).update(value).digest(`hex`);
+}
+function planDigest(plan) {
+	return digest(canonical(plan));
+}
+function peerIdentities(peers) {
+	return Object.fromEntries(Object.entries(peers).map(([name, { version, source }]) => [name, {
+		version,
+		source
+	}]));
+}
+function requireMatrix(condition, message) {
+	if (!condition) throw new Error(message);
+}
+function sameNames(actual, expected, message) {
+	const counts = (names) => {
+		const result = /* @__PURE__ */ new Map();
+		for (const name of names) result.set(name, (result.get(name) ?? 0) + 1);
+		return result;
+	};
+	const actualCounts = counts(actual);
+	const expectedCounts = counts(expected);
+	const missing = [...expectedCounts].filter(([name, count]) => (actualCounts.get(name) ?? 0) < count).map(([name]) => name);
+	const extra = [...actualCounts].filter(([name, count]) => count > (expectedCounts.get(name) ?? 0)).map(([name]) => name);
+	requireMatrix(!missing.length && !extra.length, `${message}${missing.length ? ` Missing: ${missing.join(`, `)}.` : ``}${extra.length ? ` Unexpected or duplicated: ${extra.join(`, `)}.` : ``}`);
+}
+/** Validate the audit as well as the plan envelope; empty or partial plans never pass. */
+function validateNpmPlan(value) {
+	const plan = npmPlanSchema.assert(value);
+	const { id, ...payload } = plan;
+	requireMatrix(id === planDigest(payload), `Plan digest does not match its contents.`);
+	requireMatrix(plan.runId.length > 0 && /^[a-f0-9]{40,64}$/.test(plan.commit), `Invalid plan source identity.`);
+	requireMatrix(plan.configs.length && plan.packages.length && plan.environments.length && plan.archives.length, `Plan must contain packages, environments, and archives.`);
+	for (const [name, values] of [
+		[`package`, plan.packages.map((p) => p.name)],
+		[`configuration`, plan.packages.map((p) => p.config)],
+		[`environment`, plan.environments.map((e) => e.id)],
+		[`archive`, plan.archives.map((a) => a.path)]
+	]) requireMatrix(new Set(values).size === values.length, `Duplicate ${name} identities in plan.`);
+	for (const archive of plan.archives) requireMatrix(/^[a-f0-9]{64}$/.test(archive.sha256) && archive.file === `archives/${archive.sha256}.tgz`, `Invalid archive digest or bundle path: ${archive.path}.`);
+	sameNames([...new Set(plan.environments.map((e) => e.packageName))], plan.packages.map((p) => p.name), `Plan environments do not match package audits.`);
+	for (const pkg of plan.packages) {
+		const audit = pkg.audit;
+		requireMatrix(audit.package.name === pkg.name && audit.mode === `coverage-only` && audit.exitCode === 0 && audit.errors.length === 0 && !audit.support.error, `Coverage audit failed for ${pkg.name}.`);
+		requireMatrix([
+			`unchanged`,
+			`breaking-release`,
+			`first-release`
+		].includes(audit.support.status), `Support audit did not pass for ${pkg.name}.`);
+		requireMatrix(audit.coverage.length && audit.coverage.every((c) => c.representatives.length), `Uncovered peer era for ${pkg.name}.`);
+		const expected = plan.environments.filter((e) => e.packageName === pkg.name);
+		requireMatrix(new Set(expected.map((e) => e.representative)).size === expected.length, `Duplicate representative paths for ${pkg.name}.`);
+		sameNames(audit.representatives.map((r) => r.path), expected.map((e) => e.representative), `Missing or duplicate audited environments for ${pkg.name}.`);
+		for (const env of expected) {
+			const result = audit.representatives.find((r) => r.path === env.representative);
+			requireMatrix(result.status === `audited` && !result.error && env.suites.length, `Environment was not audited: ${pkg.name} / ${env.representative}.`);
+			sameNames(result.suites.map((s) => s.peer), env.suites, `Audited suites differ: ${env.id}.`);
+			requireMatrix(new Set(env.suites).size === env.suites.length && result.suites.every((s) => s.status === `not-run`), `Invalid audited suites: ${env.id}.`);
+			requireMatrix(canonical(peerIdentities(result.peers)) === canonical(env.peers), `Audited peer identities differ: ${env.id}.`);
+		}
+		for (const coverage of audit.coverage) for (const name of coverage.representatives) requireMatrix(expected.some((e) => e.representative === name && e.suites.includes(coverage.peer)), `Coverage references an unplanned suite: ${pkg.name} / ${name} / ${coverage.peer}.`);
+	}
+	return plan;
+}
+/** Pure receipt verification; runner-local installation paths are diagnostic only. */
+function verifyNpmReceipts(value, receipts) {
+	const errors = [];
+	let environments = 0;
+	try {
+		const plan = validateNpmPlan(value);
+		environments = plan.environments.length;
+		const parsed = receipts.map((r, i) => {
+			try {
+				return npmReceiptSchema.assert(r);
+			} catch (cause) {
+				throw new Error(`Malformed receipt ${i + 1}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+			}
+		});
+		const environmentName = (id) => {
+			const env = plan.environments.find((e) => e.id === id);
+			return env ? `${env.packageName} / ${env.representative} (${id})` : id;
+		};
+		sameNames(parsed.map((r) => environmentName(r.id)), plan.environments.map((e) => environmentName(e.id)), `Missing, duplicate, or unexpected environment receipts.`);
+		for (const env of plan.environments) try {
+			const receipt = parsed.find((r) => r.id === env.id);
+			requireMatrix(receipt.planId === plan.id, `Receipt belongs to a different plan.`);
+			requireMatrix(receipt.exitCode === 0 && !receipt.error && receipt.report, receipt.error ?? `Environment execution failed.`);
+			const report = receipt.report;
+			const pkg = plan.packages.find((p) => p.name === env.packageName);
+			requireMatrix(canonical(report.package) === canonical(pkg.audit.package), `Wrong package identity.`);
+			requireMatrix(report.mode === `test` && report.exitCode === 0 && report.errors.length === 0 && report.support.status === `not-checked` && !report.support.error, `Receipt does not contain a successful execution report.`);
+			sameNames(report.representatives.map((r) => r.path), pkg.audit.representatives.map((r) => r.path), `Missing or duplicate representatives in execution report.`);
+			for (const result of report.representatives) {
+				if (result.path !== env.representative) {
+					requireMatrix(result.status === `skipped` && result.suites.length === 0 && !result.error, `Unexpected execution: ${result.path}.`);
+					continue;
+				}
+				requireMatrix(result.status === `passed` && !result.error, `Environment did not execute successfully.`);
+				sameNames(result.suites.map((s) => s.peer), env.suites, `Missing, duplicate, or unexpected relationship suites.`);
+				for (const suite of result.suites) requireMatrix(suite.status === `passed`, `Suite did not pass: ${suite.peer}.`);
+				requireMatrix(canonical(peerIdentities(result.peers)) === canonical(env.peers), `Installed peer identities differ from the audit.`);
+			}
+		} catch (error) {
+			errors.push(`${env.packageName} / ${env.representative}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	} catch (error) {
+		errors.push(error instanceof Error ? error.message : String(error));
+	}
+	return {
+		exitCode: errors.length ? 2 : 0,
+		errors,
+		environments
+	};
+}
 // src/config.ts
 const configFields = {
 	tagPattern: type(`string`),
@@ -477,7 +706,8 @@ const configSchema = type({
 	"verbose?": configFields.verbose.or(`undefined`),
 	"out?": configFields.out,
 	"release?": releaseSchema,
-	"npm?": npmConfigSchema
+	"npm?": npmConfigSchema,
+	"npmMatrix?": npmMatrixConfigSchema
 });
 /** The complete config, with no fields exposed to argv by this loader. */
 const configOptions = options(`Breakage configuration`, configSchema, {
@@ -490,7 +720,8 @@ const configOptions = options(`Breakage configuration`, configSchema, {
 	verbose: { configOnly: true },
 	out: { configOnly: true },
 	release: { configOnly: true },
-	npm: { configOnly: true }
+	npm: { configOnly: true },
+	npmMatrix: { configOnly: true }
 });
 /** Share the root release model with npm checks unless they supply their own. */
 function defineConfig(config) {
@@ -1029,7 +1260,7 @@ async function checkLocalReleases(config, base, manifest, representatives) {
 		}
 	}))).flat();
 }
-async function runRepresentative(config, base, manifest, directory, coverageOnly, selection) {
+async function runRepresentative(config, base, manifest, directory, coverageOnly, selection, plannedSuites) {
 	const result = {
 		path: path.relative(base, directory).split(path.sep).join(`/`),
 		status: `skipped`,
@@ -1052,6 +1283,7 @@ async function runRepresentative(config, base, manifest, directory, coverageOnly
 			const peers = Object.keys(config.suites).filter((peer) => {
 				const evidence = result.peers[peer];
 				if (!evidence) return false;
+				if (plannedSuites !== void 0) return plannedSuites.includes(peer);
 				if (selection && `peer` in selection) return peer === selection.peer;
 				if (selection && `representative` in selection) return true;
 				return matches(evidence.version, manifest.peerDependencies[peer]);
@@ -1086,7 +1318,7 @@ async function runRepresentative(config, base, manifest, directory, coverageOnly
 		return result;
 	}
 }
-async function run(config, baseDirectory, coverageOnly, selection) {
+async function run(config, baseDirectory, coverageOnly, selection, plannedSuites) {
 	const report = {
 		package: {
 			name: `(unresolved)`,
@@ -1139,7 +1371,7 @@ async function run(config, baseDirectory, coverageOnly, selection) {
 			} } : {}
 		};
 		const directories = await discover(config, base);
-		const [support, representatives] = await Promise.all([selection ? Promise.resolve(report.support) : checkSupport(effective, base, manifest), Promise.all(directories.map((directory) => runRepresentative(effective, base, manifest, directory, coverageOnly, selection)))]);
+		const [support, representatives] = await Promise.all([selection ? Promise.resolve(report.support) : checkSupport(effective, base, manifest), Promise.all(directories.map((directory) => runRepresentative(effective, base, manifest, directory, coverageOnly, selection, plannedSuites)))]);
 		report.support = support;
 		report.representatives = representatives;
 		if (!selection) {
@@ -1168,6 +1400,10 @@ async function npmCheck(config, options = {}) {
 async function npmTest(config, selection, options = {}) {
 	return await run(config, options.baseDirectory ?? process.cwd(), false, selection);
 }
+/** Internal matrix entrypoint: keep the full config for validation and peer identity checks. */
+async function npmTestPlanned(config, selection, options = {}) {
+	return await run(config, options.baseDirectory ?? process.cwd(), false, { representative: selection.representative }, selection.suites);
+}
 function formatNpmReport(report) {
 	const lines = [`${report.package.name}@${report.package.version} — npm ${report.mode}`];
 	for (const result of report.representatives) {
@@ -1188,6 +1424,393 @@ function formatNpmReport(report) {
 	if (report.mode === `coverage-only`) lines.push(`Coverage audit only; compatibility assertions were not executed.`);
 	return `${lines.join(`\n`)}\n`;
 }
+// src/npm/matrix.ts
+function relative(root, filename) {
+	const result = path.relative(root, path.resolve(filename)).split(path.sep).join(`/`) || `.`;
+	requireMatrix(!result.startsWith(`../`) && result !== `..` && !path.isAbsolute(result), `Matrix input escapes the source checkout: ${filename}.`);
+	return result;
+}
+function portablePath(value) {
+	requireMatrix(value.length && !value.includes(`\\`) && !path.posix.isAbsolute(value) && !/^[A-Za-z]:/.test(value) && !value.split(`/`).includes(`..`), `Invalid portable path: ${value}.`);
+}
+async function contained(root, filename) {
+	portablePath(filename);
+	const absolute = path.resolve(root, filename);
+	let ancestor = absolute;
+	for (;;) try {
+		await lstat(ancestor);
+		break;
+	} catch (error) {
+		if (error.code !== `ENOENT`) throw error;
+		ancestor = path.dirname(ancestor);
+	}
+	requireMatrix(within(await realpath(root), await realpath(ancestor)), `Path escapes its root through a symlink: ${filename}.`);
+	return absolute;
+}
+async function fileDigest(filename) {
+	requireMatrix((await lstat(filename)).isFile(), `Expected a regular file: ${filename}.`);
+	return digest(await readFile(filename));
+}
+async function sourceIdentity(root) {
+	const git = simpleGit(root);
+	requireMatrix(await realpath(await git.revparse([`--show-toplevel`])) === await realpath(root), `Matrix rootDirectory must be the Git checkout root.`);
+	requireMatrix(!(await git.status()).files.length, `Matrix planning and execution require a clean checkout, including untracked files. Ignore generated archives, bundles, and receipts.`);
+	return await git.revparse([`HEAD`]);
+}
+async function ignoredOutput(root, filename) {
+	const git = simpleGit(root);
+	requireMatrix(!(await git.raw([
+		`ls-files`,
+		`--`,
+		filename
+	])).trim() && (await git.raw([
+		`check-ignore`,
+		`--`,
+		filename
+	])).trim(), `Matrix output must be gitignored and untracked: ${filename}.`);
+}
+async function discoverConfigs(root, patterns) {
+	const files = /* @__PURE__ */ new Set();
+	for (const pattern of patterns) portablePath(pattern);
+	for await (const filename of glob(patterns, {
+		cwd: root,
+		exclude: [
+			`**/node_modules/**`,
+			`**/.git/**`,
+			`**/test/**`
+		]
+	})) {
+		const name = relative(root, path.resolve(root, filename));
+		if ((await loadConfig(await contained(root, name))).npm) files.add(name);
+	}
+	requireMatrix(files.size, `No npm configurations matched the matrix configs.`);
+	return [...files].sort();
+}
+function configDigest(config, root, base) {
+	return digest(canonical({
+		...config,
+		packageDirectory: relative(root, base),
+		artifact: relative(root, path.resolve(base, config.artifact)),
+		baseline: `baselineFile` in config.baseline && config.baseline.baselineFile ? {
+			...config.baseline,
+			baselineFile: relative(root, path.resolve(base, config.baseline.baselineFile))
+		} : config.baseline,
+		localPeers: Object.fromEntries(Object.entries(config.localPeers ?? {}).map(([name, peer]) => [name, {
+			directory: relative(root, path.resolve(base, peer.directory)),
+			artifact: relative(root, path.resolve(base, peer.artifact))
+		}])),
+		release: config.release ? {
+			resolveDelta: !!config.release.resolveDelta,
+			policy: !!config.release.policy
+		} : void 0
+	}));
+}
+async function packageConfig(root, filename) {
+	const config = (await loadConfig(await contained(root, filename))).npm;
+	validateConfig(config);
+	const baseDirectory = path.dirname(path.resolve(root, filename));
+	const base = path.resolve(baseDirectory, config.packageDirectory ?? `.`);
+	await contained(root, relative(root, base));
+	return {
+		config,
+		base,
+		baseDirectory
+	};
+}
+function portableContext(root, context) {
+	return {
+		...context,
+		packageDirectory: relative(root, context.packageDirectory)
+	};
+}
+async function archiveRequests(root, config, base) {
+	const manifest = await readManifest(path.join(base, `package.json`));
+	const requests = [{
+		packageName: manifest.name,
+		directory: relative(root, base),
+		artifact: relative(root, path.resolve(base, config.artifact))
+	}];
+	for (const [packageName, peer] of Object.entries(config.localPeers ?? {})) {
+		const directory = relative(root, path.resolve(base, peer.directory));
+		try {
+			await lstat(await contained(root, directory));
+		} catch (error) {
+			if (error.code === `ENOENT` && !manifest.peerDependencies?.[packageName]) continue;
+			throw error;
+		}
+		requests.push({
+			packageName,
+			directory,
+			artifact: relative(root, path.resolve(base, peer.artifact))
+		});
+	}
+	return requests;
+}
+async function inputDigest(root, filename, config, base) {
+	const files = /* @__PURE__ */ new Set([filename, relative(root, path.join(base, `package.json`))]);
+	const directories = await discover(config, base);
+	for (const directory of directories) for (const name of [`package.json`, config.lockfile]) files.add(relative(root, path.join(directory, name)));
+	for (const request of await archiveRequests(root, config, base)) files.add(relative(root, path.resolve(root, request.directory, `package.json`)));
+	if (`baselineFile` in config.baseline && config.baseline.baselineFile) files.add(relative(root, path.resolve(base, config.baseline.baselineFile)));
+	const exclude = [
+		`**/node_modules/**`,
+		`**/.git/**`,
+		...directories.flatMap((directory) => {
+			const stage = relative(base, path.join(directory, `test`));
+			return [stage, `${stage}/**`];
+		})
+	];
+	for (const suite of Object.values(config.suites)) for (const pattern of suite.files) {
+		portablePath(pattern);
+		let count = 0;
+		for await (const file of glob(pattern, {
+			cwd: base,
+			exclude
+		})) {
+			const absolute = path.resolve(base, file);
+			if ((await lstat(absolute)).isDirectory()) continue;
+			files.add(relative(root, absolute));
+			count++;
+		}
+		requireMatrix(count, `Suite pattern matched no files: ${pattern}.`);
+	}
+	return digest(canonical(await Promise.all([...files].sort().map(async (file) => [file, await fileDigest(await contained(root, file))]))));
+}
+/** Audit all configured packages and prepare one immutable, portable archive bundle. */
+async function npmPlan(config, options = {}) {
+	npmMatrixConfigSchema.assert(config);
+	const root = path.resolve(options.rootDirectory ?? process.cwd());
+	const output = options.bundleDirectory ?? `.breakage/npm-plan`;
+	const bundle = await contained(root, relative(root, path.resolve(root, output)));
+	await ignoredOutput(root, path.join(bundle, `plan.json`));
+	await mkdir(bundle, { recursive: true });
+	return await withDirectoryLock(path.join(bundle, `.lock`), async () => {
+		await rm(path.join(bundle, `plan.json`), { force: true });
+		const commit = await sourceIdentity(root);
+		const patterns = typeof config.configs === `string` ? [config.configs] : config.configs;
+		const files = await discoverConfigs(root, patterns);
+		const packages = [];
+		const environments = [];
+		const requests = /* @__PURE__ */ new Map();
+		for (const filename of files) {
+			const { config: npm, base, baseDirectory } = await packageConfig(root, filename);
+			const manifest = await readManifest(path.join(base, `package.json`));
+			for (const peer of Object.keys(manifest.peerDependencies ?? {})) requireMatrix(npm.suites[peer] || manifest.peerDependenciesMeta?.[peer]?.optional, `Missing relationship suite for ${manifest.name}: ${peer}.`);
+			const releases = [];
+			const audit = await npmCheck({
+				...npm,
+				...npm.release ? { release: {
+					...npm.release,
+					resolveDelta: async (context) => {
+						const transition = await resolveReleaseDelta(npm.release, context);
+						releases.push({
+							context: portableContext(root, context),
+							...transition ? { transition } : {}
+						});
+						return transition;
+					}
+				} } : {}
+			}, {
+				baseDirectory,
+				coverageOnly: true
+			});
+			requireMatrix(audit.exitCode === 0, `Cannot plan ${manifest.name}:\n${formatNpmReport(audit)}`);
+			for (const result of audit.representatives) {
+				requireMatrix(result.status === `audited` && result.suites.length, `Environment has no executable audited suites: ${manifest.name} / ${result.path}.`);
+				const environment = JSON.parse(await readFile(path.join(base, result.path, `package.json`), `utf8`));
+				const label = config.label?.({
+					packageName: manifest.name,
+					representative: result.path,
+					peers: result.peers,
+					...typeof environment.description === `string` ? { description: environment.description } : {}
+				}) ?? `${manifest.name}: ${result.path}`;
+				requireMatrix(typeof label === `string` && label.trim(), `Invalid label for ${manifest.name} / ${result.path}.`);
+				environments.push({
+					id: digest(`${filename}\0${result.path}`).slice(0, 24),
+					label,
+					packageName: manifest.name,
+					representative: result.path,
+					suites: result.suites.map((s) => s.peer).sort(),
+					peers: peerIdentities(result.peers)
+				});
+				for (const peer of Object.values(result.peers)) peer.path = `(runner-local)`;
+			}
+			packages.push({
+				config: filename,
+				directory: relative(root, base),
+				name: manifest.name,
+				configDigest: configDigest(npm, root, base),
+				inputDigest: await inputDigest(root, filename, npm, base),
+				audit,
+				releases: releases.sort((a, b) => canonical(a.context).localeCompare(canonical(b.context)))
+			});
+			for (const request of await archiveRequests(root, npm, base)) {
+				const previous = requests.get(request.artifact);
+				requireMatrix(!previous || canonical(previous) === canonical(request), `Conflicting archive requests: ${request.artifact}.`);
+				requests.set(request.artifact, request);
+			}
+		}
+		const archives = [...requests.values()].sort((a, b) => a.artifact.localeCompare(b.artifact));
+		for (const request of archives) {
+			await contained(root, request.directory);
+			await contained(root, request.artifact);
+			await ignoredOutput(root, path.resolve(root, request.artifact));
+		}
+		if (typeof config.prepare === `string`) await prepare(config.prepare, root);
+		else await config.prepare({
+			rootDirectory: root,
+			archives
+		});
+		const packed = [];
+		for (const archive of archives) {
+			const filename = await contained(root, archive.artifact);
+			const sha256 = await fileDigest(filename);
+			const file = `archives/${sha256}.tgz`;
+			await mkdir(path.join(bundle, `archives`), { recursive: true });
+			await copyFile(filename, await contained(bundle, file));
+			packed.push({
+				path: archive.artifact,
+				file,
+				sha256
+			});
+		}
+		requireMatrix(await sourceIdentity(root) === commit, `Source changed while preparing the matrix.`);
+		const payload = {
+			formatVersion: 1,
+			runId: randomUUID(),
+			commit,
+			configs: patterns,
+			packages,
+			environments,
+			archives: packed
+		};
+		const plan = validateNpmPlan({
+			...payload,
+			id: planDigest(payload)
+		});
+		await validateWorkspace(plan, {
+			rootDirectory: root,
+			bundleDirectory: bundle
+		});
+		await writeMatrixJson(path.join(bundle, `plan.json`), plan);
+		return plan;
+	});
+}
+async function validateWorkspace(plan, options) {
+	const root = path.resolve(options.rootDirectory ?? process.cwd());
+	const bundle = path.resolve(root, options.bundleDirectory ?? `.breakage/npm-plan`);
+	requireMatrix(await sourceIdentity(root) === plan.commit, `Plan belongs to a different source commit.`);
+	requireMatrix(canonical(await discoverConfigs(root, plan.configs)) === canonical(plan.packages.map((p) => p.config).sort()), `Plan no longer enumerates every configured npm package.`);
+	const configs = /* @__PURE__ */ new Map();
+	const requiredArchives = /* @__PURE__ */ new Set();
+	for (const pkg of plan.packages) {
+		const loaded = await packageConfig(root, pkg.config);
+		const { config, base } = loaded;
+		for (const request of await archiveRequests(root, config, base)) requiredArchives.add(request.artifact);
+		requireMatrix(relative(root, base) === pkg.directory && configDigest(config, root, base) === pkg.configDigest, `Configuration changed for ${pkg.name}.`);
+		requireMatrix(await inputDigest(root, pkg.config, config, base) === pkg.inputDigest, `Contract, manifest, or lockfile inputs changed for ${pkg.name}.`);
+		requireMatrix(canonical((await discover(config, base)).map((d) => relative(base, d)).sort()) === canonical(pkg.audit.representatives.map((r) => r.path).sort()), `Representative discovery changed for ${pkg.name}.`);
+		for (const release of pkg.releases) {
+			requireMatrix(config.release, `Release configuration disappeared for ${pkg.name}.`);
+			requireMatrix(canonical(await resolveReleaseDelta(config.release, {
+				...release.context,
+				packageDirectory: await contained(root, release.context.packageDirectory)
+			})) === canonical(release.transition), `Release evidence changed for ${pkg.name} / ${release.context.packageName}.`);
+		}
+		if (pkg.audit.support.release) {
+			const expected = pkg.audit.support.release;
+			requireMatrix(canonical(versionDelta(expected.previousVersion, expected.version, config.release?.policy)) === canonical(expected), `Release policy changed for ${pkg.name}.`);
+		}
+		configs.set(pkg.name, loaded);
+	}
+	requireMatrix(canonical([...requiredArchives].sort()) === canonical(plan.archives.map((a) => a.path).sort()), `Planned archives do not match the configured packages and local peers.`);
+	for (const archive of plan.archives) {
+		portablePath(archive.path);
+		requireMatrix(archive.file === `archives/${archive.sha256}.tgz`, `Invalid bundled archive path: ${archive.file}.`);
+		requireMatrix(await fileDigest(await contained(bundle, archive.file)) === archive.sha256, `Candidate archive changed: ${archive.path}.`);
+	}
+	return {
+		root,
+		bundle,
+		configs
+	};
+}
+/** Execute exactly one audited environment, producing failure evidence whenever the plan is valid. */
+async function npmExecute(value, id, options = {}) {
+	const plan = validateNpmPlan(value);
+	const receipt = {
+		formatVersion: 1,
+		planId: plan.id,
+		id,
+		exitCode: 2
+	};
+	try {
+		const env = plan.environments.find((e) => e.id === id);
+		requireMatrix(env, `Unknown planned environment: ${id}.`);
+		const { root, bundle, configs } = await validateWorkspace(plan, options);
+		const { config, baseDirectory } = configs.get(env.packageName);
+		const byPath = new Map(plan.archives.map((a) => [a.path, path.join(bundle, a.file)]));
+		const base = path.resolve(baseDirectory, config.packageDirectory ?? `.`);
+		const artifactFor = (filename) => {
+			const archive = byPath.get(relative(root, path.resolve(base, filename)));
+			requireMatrix(archive, `Plan is missing archive: ${filename}.`);
+			return archive;
+		};
+		receipt.report = await npmTestPlanned({
+			...config,
+			artifact: artifactFor(config.artifact),
+			localPeers: Object.fromEntries(Object.entries(config.localPeers ?? {}).map(([name, peer]) => [name, {
+				...peer,
+				artifact: byPath.get(relative(root, path.resolve(base, peer.artifact))) ?? peer.artifact
+			}]))
+		}, {
+			representative: env.representative,
+			suites: env.suites
+		}, { baseDirectory });
+		receipt.exitCode = receipt.report.exitCode;
+		await validateWorkspace(plan, options);
+		if (receipt.exitCode === 0) {
+			const result = receipt.report.representatives.find((r) => r.path === env.representative);
+			requireMatrix(result?.status === `passed` && canonical(result.suites.map((s) => s.peer).sort()) === canonical(env.suites) && result.suites.every((s) => s.status === `passed`) && canonical(peerIdentities(result.peers)) === canonical(env.peers), `Execution differs from the planned suites or peer identities: ${env.label}.`);
+		}
+	} catch (error) {
+		receipt.exitCode = 2;
+		receipt.error = errorMessage(error);
+	}
+	return receipt;
+}
+/** Verify source/config/archive identities and then require all planned execution receipts. */
+async function npmVerify(value, receipts, options = {}) {
+	try {
+		const plan = validateNpmPlan(value);
+		await validateWorkspace(plan, options);
+		return verifyNpmReceipts(plan, receipts);
+	} catch (error) {
+		return {
+			exitCode: 2,
+			errors: [errorMessage(error)],
+			environments: 0
+		};
+	}
+}
+function npmMatrix(value) {
+	return { include: validateNpmPlan(value).environments.map(({ id, label, packageName, representative }) => ({
+		id,
+		label,
+		packageName,
+		representative
+	})) };
+}
+async function writeMatrixJson(filename, value) {
+	await mkdir(path.dirname(filename), { recursive: true });
+	const temporary = `${filename}.${randomUUID()}.tmp`;
+	try {
+		await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: `wx` });
+		await rename(temporary, filename);
+	} finally {
+		await rm(temporary, { force: true });
+	}
+}
 // src/breakage.ts
 async function breakage(options) {
 	rejectCertificationOptions(options);
@@ -1344,6 +1967,6 @@ async function breakage(options) {
 		logMarks?.();
 	}
 }
-export { configFields as a, configSchema as c, loadConfig as d, resolveConfig as f, errorMessage as h, npmTest as i, defaultConfig as l, breakagePrelude as m, formatNpmReport as n, configOptions as o, validateConfig as p, npmCheck as r, configPath as s, breakage as t, defineConfig as u };
+export { resolveConfig as _, npmVerify as a, breakagePrelude as b, npmCheck as c, configOptions as d, configPath as f, loadConfig as g, defineConfig as h, npmPlan as i, npmTest as l, defaultConfig as m, npmExecute as n, writeMatrixJson as o, configSchema as p, npmMatrix as r, formatNpmReport as s, breakage as t, configFields as u, verifyNpmReceipts as v, errorMessage as x, validateConfig as y };
 
-//# sourceMappingURL=breakage-DIY49fzP.js.map
+//# sourceMappingURL=breakage-DJiIiLzL.js.map