breakage 0.8.5 → 0.9.1

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

@@ -1,15 +1,125 @@
+import { a as validateRelease, n as releaseSchema, o as versionDelta, r as resolveReleaseDelta, t as rejectCertificationOptions } from "./release-BsdIDT4g.js";
 import { createRequire } from "node:module";
-import { exec, spawn } from "node:child_process";
 import path from "node:path";
 import { minimatch } from "minimatch";
 import { simpleGit } from "simple-git";
 import logger from "takua";
-import { randomUUID } from "node:crypto";
+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 { setTimeout } from "node:timers/promises";
+import { chmod, copyFile, glob, lstat, mkdir, readFile, readdir, realpath, rename, rm, rmdir, writeFile } from "node:fs/promises";
 import semver from "semver";
-//#region src/directory-lock.ts
+import { type } from "arktype";
+import { createHash, randomUUID } from "node:crypto";
+import { setTimeout } from "node:timers/promises";
+import { existsSync } from "node:fs";
+import { cli, options } from "comline";
+// src/task.ts
+/** Capture output per environment so parallel runs cannot interleave their reports. */
+async function command(commandLine, cwd) {
+	if (typeof commandLine !== `string` || !commandLine.trim()) throw new Error(`Commands must be nonempty shell strings.`);
+	return await new Promise((resolve, reject) => {
+		const child = spawn(commandLine, {
+			cwd,
+			shell: true,
+			env: {
+				...process.env,
+				NODE_PATH: ``,
+				PATH: [
+					path.join(cwd, `node_modules/.bin`),
+					path.join(cwd, `../node_modules/.bin`),
+					process.env.PATH
+				].join(path.delimiter)
+			},
+			stdio: [
+				`ignore`,
+				`pipe`,
+				`pipe`
+			]
+		});
+		let output = ``;
+		const collect = (chunk) => {
+			output = (output + chunk.toString()).slice(-1e6);
+		};
+		child.stdout.on(`data`, collect);
+		child.stderr.on(`data`, collect);
+		child.on(`error`, reject);
+		child.on(`close`, (code, signal) => resolve({
+			code: signal ? 2 : code ?? 2,
+			output
+		}));
+	});
+}
+async function prepare(commandLine, cwd) {
+	const result = await command(commandLine, cwd);
+	if (result.code !== 0) throw new Error(`Command failed (${result.code}) in ${cwd}: ${commandLine}\n${result.output}`);
+}
+function errorMessage(error) {
+	return error instanceof Error ? `${error.message}${error.cause ? `\n${errorMessage(error.cause)}` : ``}` : String(error);
+}
+// src/npm/manifest.ts
+function record(value) {
+	return typeof value === `object` && value !== null && !Array.isArray(value);
+}
+function packageName(value) {
+	return /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/.test(value);
+}
+function parseManifest(value, label) {
+	if (!record(value) || typeof value.name !== `string` || !packageName(value.name) || typeof value.version !== `string` || !semver.valid(value.version)) throw new Error(`Invalid package identity in ${label}.`);
+	if (value.peerDependenciesMeta !== void 0 && (!record(value.peerDependenciesMeta) || Object.values(value.peerDependenciesMeta).some((entry) => !record(entry) || entry.optional !== void 0 && typeof entry.optional !== `boolean`))) throw new Error(`Invalid peerDependenciesMeta in ${label}.`);
+	for (const field of [
+		`dependencies`,
+		`optionalDependencies`,
+		`devDependencies`,
+		`peerDependencies`
+	]) {
+		const entries = value[field];
+		if (entries !== void 0 && (!record(entries) || Object.entries(entries).some(([name, spec]) => !packageName(name) || typeof spec !== `string`))) throw new Error(`Invalid ${field} in ${label}.`);
+	}
+	if (value.breakage !== void 0 && (!record(value.breakage) || value.breakage.candidates !== void 0 && (!Array.isArray(value.breakage.candidates) || value.breakage.candidates.some((name) => typeof name !== `string` || !packageName(name))))) throw new Error(`Invalid candidate peers in ${label}.`);
+	return value;
+}
+async function readManifest(filename) {
+	return parseManifest(JSON.parse(await readFile(filename, `utf8`)), filename);
+}
+/** Current support is authored explicitly; only historical shorthand is resolved. */
+async function normalizeWorkspacePeers(manifest, versionAtBaseline) {
+	if (!manifest.peerDependencies) return manifest;
+	const entries = await Promise.all(Object.entries(manifest.peerDependencies).map(async ([peer, range]) => {
+		if (!range.startsWith(`workspace:`)) return [peer, range];
+		const requested = range.slice(`workspace:`.length);
+		if ([
+			``,
+			`*`,
+			`^`,
+			`~`
+		].includes(requested)) {
+			if (!versionAtBaseline) throw new Error(`Moving workspace peer range ${peer}: ${range} in ${manifest.name}. Declare explicit support eras, for example ^1.0.0 || ^2.0.0, so local version changes cannot change the support promise.`);
+			const version = await versionAtBaseline(peer);
+			if (!semver.valid(version)) throw new Error(`Invalid historical workspace version for ${peer}: ${version}.`);
+			return [peer, `${requested === `^` || requested === `~` ? requested : ``}${version}`];
+		}
+		try {
+			eras(requested);
+		} catch {
+			throw new Error(`Unsupported workspace peer range for ${peer}: ${range}.`);
+		}
+		return [peer, requested];
+	}));
+	return {
+		...manifest,
+		peerDependencies: Object.fromEntries(entries)
+	};
+}
+function eras(range) {
+	const parts = range.split(`||`).map((part) => part.trim());
+	if (parts.some((part) => !part || semver.validRange(part) === null)) throw new Error(`Invalid peer range: ${range}.`);
+	return parts;
+}
+/** Previews only represent an explicitly enrolled exact preview. */
+function matches(version, range) {
+	return eras(range).some((era) => semver.prerelease(version) ? semver.valid(era.replace(/^=\s*/, ``)) === semver.valid(version) : semver.satisfies(version, era));
+}
+// src/directory-lock.ts
 async function withDirectoryLock(lock, action, waitForCleanup = false) {
 	const deadline = Date.now() + 6e4;
 	for (;;) try {
@@ -26,8 +136,7 @@ async function withDirectoryLock(lock, action, waitForCleanup = false) {
 		await rmdir(lock);
 	}
 }
-//#endregion
-//#region src/release-tag.ts
+// src/release-tag.ts
 function compareInteger(a, b) {
 	return a.length - b.length || (a > b ? 1 : a < b ? -1 : 0);
 }
@@ -69,8 +178,7 @@ function latestReleaseTag(remoteTags, tagPattern) {
 	}
 	return latest?.ref;
 }
-//#endregion
-//#region src/baseline.ts
+// src/baseline.ts
 const objectId = /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/;
 function isBaseline(value) {
 	if (typeof value !== `object` || value === null) return false;
@@ -149,8 +257,7 @@ async function readBaseline(git, filename, { tagPattern }) {
 		throw new Error(`Missing, invalid, or unusable baseline ${filename}. Run breakage prelude again.`, { cause });
 	}
 }
-//#endregion
-//#region src/test-file-state.ts
+// src/test-file-state.ts
 function isActiveCheck(value) {
 	if (typeof value !== `object` || value === null) return false;
 	const record = value;
@@ -293,127 +400,48 @@ async function withTestFileState(git, baseDirname, action) {
 		});
 	});
 }
-//#endregion
-//#region src/npm/command.ts
-/** Capture output per environment so parallel runs cannot interleave their reports. */
-async function command(commandLine, cwd) {
-	return await new Promise((resolve, reject) => {
-		const child = spawn(commandLine, {
-			cwd,
-			shell: true,
-			env: {
-				...process.env,
-				NODE_PATH: ``,
-				PATH: [
-					path.join(cwd, `node_modules/.bin`),
-					path.join(cwd, `../node_modules/.bin`),
-					process.env.PATH
-				].join(path.delimiter)
-			},
-			stdio: [
-				`ignore`,
-				`pipe`,
-				`pipe`
-			]
-		});
-		let output = ``;
-		const collect = (chunk) => {
-			output = (output + chunk.toString()).slice(-1e6);
-		};
-		child.stdout.on(`data`, collect);
-		child.stderr.on(`data`, collect);
-		child.on(`error`, reject);
-		child.on(`close`, (code, signal) => resolve({
-			code: signal ? 2 : code ?? 2,
-			output
-		}));
-	});
-}
-async function prepare(commandLine, cwd) {
-	const result = await command(commandLine, cwd);
-	if (result.code !== 0) throw new Error(`Command failed (${result.code}) in ${cwd}: ${commandLine}\n${result.output}`);
-}
-function errorMessage(error) {
-	return error instanceof Error ? `${error.message}${error.cause ? `\n${errorMessage(error.cause)}` : ``}` : String(error);
-}
-//#endregion
-//#region src/npm/manifest.ts
-function record(value) {
-	return typeof value === `object` && value !== null && !Array.isArray(value);
-}
-function packageName(value) {
-	return /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/.test(value);
-}
-function parseManifest(value, label) {
-	if (!record(value) || typeof value.name !== `string` || !packageName(value.name) || typeof value.version !== `string` || !semver.valid(value.version)) throw new Error(`Invalid package identity in ${label}.`);
-	if (value.peerDependenciesMeta !== void 0 && (!record(value.peerDependenciesMeta) || Object.values(value.peerDependenciesMeta).some((entry) => !record(entry) || entry.optional !== void 0 && typeof entry.optional !== `boolean`))) throw new Error(`Invalid peerDependenciesMeta in ${label}.`);
-	for (const field of [
-		`dependencies`,
-		`optionalDependencies`,
-		`devDependencies`,
-		`peerDependencies`
-	]) {
-		const entries = value[field];
-		if (entries !== void 0 && (!record(entries) || Object.entries(entries).some(([name, spec]) => !packageName(name) || typeof spec !== `string`))) throw new Error(`Invalid ${field} in ${label}.`);
-	}
-	if (value.breakage !== void 0 && (!record(value.breakage) || value.breakage.candidates !== void 0 && (!Array.isArray(value.breakage.candidates) || value.breakage.candidates.some((name) => typeof name !== `string` || !packageName(name))))) throw new Error(`Invalid candidate peers in ${label}.`);
-	return value;
-}
-async function readManifest(filename) {
-	return parseManifest(JSON.parse(await readFile(filename, `utf8`)), filename);
-}
-/** Current support is authored explicitly; only historical shorthand is resolved. */
-async function normalizeWorkspacePeers(manifest, versionAtBaseline) {
-	if (!manifest.peerDependencies) return manifest;
-	const entries = await Promise.all(Object.entries(manifest.peerDependencies).map(async ([peer, range]) => {
-		if (!range.startsWith(`workspace:`)) return [peer, range];
-		const requested = range.slice(`workspace:`.length);
-		if ([
-			``,
-			`*`,
-			`^`,
-			`~`
-		].includes(requested)) {
-			if (!versionAtBaseline) throw new Error(`Moving workspace peer range ${peer}: ${range} in ${manifest.name}. Declare explicit support eras, for example ^1.0.0 || ^2.0.0, so local version changes cannot change the support promise.`);
-			const version = await versionAtBaseline(peer);
-			if (!semver.valid(version)) throw new Error(`Invalid historical workspace version for ${peer}: ${version}.`);
-			return [peer, `${requested === `^` || requested === `~` ? requested : ``}${version}`];
-		}
-		try {
-			eras(requested);
-		} catch {
-			throw new Error(`Unsupported workspace peer range for ${peer}: ${range}.`);
-		}
-		return [peer, requested];
-	}));
-	return {
-		...manifest,
-		peerDependencies: Object.fromEntries(entries)
-	};
-}
-function eras(range) {
-	const parts = range.split(`||`).map((part) => part.trim());
-	if (parts.some((part) => !part || semver.validRange(part) === null)) throw new Error(`Invalid peer range: ${range}.`);
-	return parts;
-}
-/** Previews only represent an explicitly enrolled exact preview. */
-function matches(version, range) {
-	return eras(range).some((era) => semver.prerelease(version) ? semver.valid(era.replace(/^=\s*/, ``)) === semver.valid(version) : semver.satisfies(version, era));
-}
-//#endregion
-//#region src/npm/config.ts
+// src/npm/config.ts
+const npmSuiteSchema = type({
+	"+": `reject`,
+	files: `string[]`,
+	command: `string`
+});
+const npmConfigSchema = type({
+	"+": `reject`,
+	"release?": releaseSchema,
+	"packageDirectory?": `string`,
+	artifact: `string`,
+	representatives: `string | string[]`,
+	lockfile: `string`,
+	prepareCommand: `string`,
+	"installCommand?": `string`,
+	suites: { "[string]": npmSuiteSchema },
+	"localPeers?": { "[string]": {
+		"+": `reject`,
+		directory: `string`,
+		artifact: `string`
+	} },
+	baseline: type({
+		"+": `reject`,
+		firstRelease: `true`
+	}).or({
+		"+": `reject`,
+		"tagPattern?": `string`,
+		"baselineFile?": `string`
+	})
+});
 function nonempty(value) {
 	return typeof value === `string` && value.trim().length > 0;
 }
 function validateConfig(value) {
 	if (!record(value)) throw new Error(`Configuration must have an npm object.`);
-	for (const key of [
-		`artifact`,
-		`lockfile`,
-		`prepareCommand`
-	]) if (!nonempty(value[key])) throw new Error(`npm.${key} must be a nonempty string.`);
+	rejectCertificationOptions(value);
+	npmConfigSchema.assert(value);
+	for (const key of [`artifact`, `lockfile`]) if (!nonempty(value[key])) throw new Error(`npm.${key} must be a nonempty string.`);
 	if (path.isAbsolute(value.lockfile) || value.lockfile.split(/[\\/]/).includes(`..`)) throw new Error(`npm.lockfile must stay inside each representative.`);
-	for (const key of [`packageDirectory`, `installCommand`]) if (value[key] !== void 0 && !nonempty(value[key])) throw new Error(`Invalid npm.${key}.`);
+	if (!nonempty(value.prepareCommand)) throw new Error(`npm.prepareCommand must be a nonempty shell command string.`);
+	if (value.installCommand !== void 0 && !nonempty(value.installCommand)) throw new Error(`Invalid npm.installCommand.`);
+	for (const key of [`packageDirectory`]) if (value[key] !== void 0 && !nonempty(value[key])) throw new Error(`Invalid npm.${key}.`);
 	const globs = typeof value.representatives === `string` ? [value.representatives] : value.representatives;
 	if (!Array.isArray(globs) || !globs.length || globs.some((glob) => !nonempty(glob))) throw new Error(`npm.representatives must contain directory globs.`);
 	if (!record(value.suites) || !Object.keys(value.suites).length) throw new Error(`Configure at least one npm peer suite.`);
@@ -423,23 +451,327 @@ function validateConfig(value) {
 		if (!record(value.localPeers)) throw new Error(`Invalid npm.localPeers.`);
 		for (const [peer, local] of Object.entries(value.localPeers)) if (!packageName(peer) || !record(local) || !nonempty(local.directory) || !nonempty(local.artifact)) throw new Error(`Invalid local peer ${peer}.`);
 	}
-	for (const hook of [`releaseIntent`, `certifyBreaking`]) if (value[hook] !== void 0 && typeof value[hook] !== `function`) throw new Error(`npm.${hook} must be a function.`);
 }
 function validatePeerRanges(peers) {
 	for (const range of Object.values(peers)) eras(range);
 }
-//#endregion
-//#region src/npm/release.ts
-async function intent(config, context) {
-	if (!config.releaseIntent) return { status: `none` };
-	const result = await config.releaseIntent(context);
-	if (record(result) && result.status === `none`) return { status: `none` };
-	if (!record(result) || result.status !== `release` || typeof result.version !== `string` || !semver.valid(result.version) || semver.lt(result.version, context.currentVersion)) throw new Error(`Invalid release intent for ${context.packageName}; expected none or a current/newer exact version.`);
+// 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`),
+	baselineFile: type(`string`),
+	testPattern: type(`string`),
+	testCommand: type(`string`),
+	test: type(`string`),
+	baseDirname: type(`string`),
+	verbose: type(`boolean`),
+	out: type(`string`)
+};
+const configSchema = type({
+	"+": `reject`,
+	"tagPattern?": configFields.tagPattern.or(`undefined`),
+	"baselineFile?": configFields.baselineFile.or(`undefined`),
+	"testPattern?": configFields.testPattern,
+	"testCommand?": configFields.testCommand,
+	"test?": configFields.test,
+	"baseDirname?": configFields.baseDirname,
+	"verbose?": configFields.verbose.or(`undefined`),
+	"out?": configFields.out,
+	"release?": releaseSchema,
+	"npm?": npmConfigSchema,
+	"npmMatrix?": npmMatrixConfigSchema
+});
+/** The complete config, with no fields exposed to argv by this loader. */
+const configOptions = options(`Breakage configuration`, configSchema, {
+	tagPattern: { configOnly: true },
+	baselineFile: { configOnly: true },
+	testPattern: { configOnly: true },
+	testCommand: { configOnly: true },
+	test: { configOnly: true },
+	baseDirname: { configOnly: true },
+	verbose: { configOnly: true },
+	out: { configOnly: true },
+	release: { configOnly: true },
+	npm: { configOnly: true },
+	npmMatrix: { configOnly: true }
+});
+/** Share the root release model with npm checks unless they supply their own. */
+function defineConfig(config) {
+	if (config && typeof config === `object`) {
+		rejectCertificationOptions(config);
+		if (config.npm) rejectCertificationOptions(config.npm);
+		if (config.release !== void 0) validateRelease(config.release);
+		if (config.npm?.release !== void 0) validateRelease(config.npm.release);
+	}
+	configSchema.assert(config);
 	return {
-		status: `release`,
-		version: result.version
+		...config,
+		...config.npm ? { npm: {
+			...config.npm,
+			...config.release && config.npm.release === void 0 ? { release: config.release } : {}
+		} } : {}
 	};
 }
+function defaultConfig(directory) {
+	const filename = path.join(directory, `breakage.config.ts`);
+	if (!existsSync(filename) && existsSync(path.join(directory, `breakage.config.json`))) throw new Error(`JSON configuration was removed. Migrate breakage.config.json to breakage.config.ts.`);
+	return filename;
+}
+/** Comline ignores absent discovered files; explicit paths must exist. */
+function configPath(filename, required = true) {
+	const absolute = path.resolve(filename);
+	if (path.extname(absolute) !== `.ts`) throw new Error(`Configuration must be a .ts module with a default export; JSON configuration was removed.`);
+	if (required && !existsSync(absolute)) throw new Error(`Configuration file does not exist: ${absolute}`);
+	return absolute;
+}
+/** Apply application semantics after Comline validates and merges configuration. */
+function resolveConfig(config, filename) {
+	return {
+		...defineConfig(config),
+		baseDirname: path.resolve(filename ? path.dirname(filename) : process.cwd(), config.baseDirname ?? `.`)
+	};
+}
+/** Use Comline's module loading and full-schema validation for programmatic and npm consumers. */
+async function loadConfig(filename) {
+	const absolute = configPath(filename);
+	return resolveConfig((await cli({
+		cliName: `breakage`,
+		routeOptions: { "": configOptions },
+		discoverConfigPath: () => absolute
+	}).async([process.execPath, `breakage`])).inputs.opts, absolute);
+}
+// src/npm/release.ts
+async function releaseVersion(config, context) {
+	return config.release ? (await resolveReleaseDelta(config.release, context))?.version : void 0;
+}
 /**
 * Compare the union, including adjacent alternatives. semver.subset compares each
 * conjunction to a single conjunction and cannot prove coverage by their union.
@@ -518,8 +850,7 @@ async function previousManifest(config, directory) {
 		return historical.version;
 	});
 }
-//#endregion
-//#region src/npm/environment.ts
+// src/npm/environment.ts
 function within(parent, child) {
 	const relative = path.relative(parent, child);
 	return relative === `` || !relative.startsWith(`..${path.sep}`) && relative !== `..` && !path.isAbsolute(relative);
@@ -624,13 +955,13 @@ async function maySelectEnvironment(config, base, directory, packageManifest, se
 		const packageDirectory = path.resolve(base, local.directory);
 		const current = await readManifest(path.join(packageDirectory, `package.json`));
 		if (current.name !== peer) throw new Error(`Local peer identity mismatch for ${peer}.`);
-		const release = await intent(config, {
+		const release = await releaseVersion(config, {
 			packageName: peer,
 			packageDirectory,
 			currentVersion: current.version
 		});
-		if (release.status === `none`) throw new Error(`Candidate ${peer} has no certified release intent.`);
-		return matches(release.version, range);
+		if (release === void 0) throw new Error(`Candidate ${peer} has no release version.`);
+		return matches(release, range);
 	}
 	const declared = declarations[peer];
 	return declared !== void 0 && matches(declared, range);
@@ -652,17 +983,17 @@ async function prepareEnvironment(config, base, directory, stage, packageManifes
 		const localManifest = await normalizeWorkspacePeers(await readManifest(path.join(localDirectory, `package.json`)));
 		if (localManifest.name !== peer) throw new Error(`Local peer identity mismatch for ${peer}.`);
 		validatePeerRanges(localManifest.peerDependencies ?? {});
-		const evidence = await intent(config, {
+		const evidence = await releaseVersion(config, {
 			packageName: peer,
 			packageDirectory: localDirectory,
 			currentVersion: localManifest.version
 		});
-		if (evidence.status === `none`) throw new Error(`Candidate ${peer} has no certified release intent.`);
+		if (evidence === void 0) throw new Error(`Candidate ${peer} has no release version.`);
 		candidates[peer] = {
 			directory: localDirectory,
 			artifact: path.resolve(base, local.artifact),
 			currentVersion: localManifest.version,
-			version: evidence.version,
+			version: evidence,
 			manifest: localManifest
 		};
 	}
@@ -866,8 +1197,7 @@ async function verifyResolution(manifest, environment) {
 		} else pending.push(await resolvePackage(directory, dependency, installation));
 	}
 }
-//#endregion
-//#region src/npm/check.ts
+// src/npm/check.ts
 async function checkSupport(config, base, manifest) {
 	try {
 		const previous = await previousManifest(config, base);
@@ -882,29 +1212,20 @@ async function checkSupport(config, base, manifest) {
 			previousVersion: previous.version,
 			changes
 		};
-		const evidence = await intent(config, {
+		const evidence = config.release ? await resolveReleaseDelta(config.release, {
 			packageName: manifest.name,
 			packageDirectory: base,
-			currentVersion: manifest.version
-		});
-		if (evidence.status === `none`) return {
+			currentVersion: manifest.version,
+			baseline: { version: previous.version }
+		}) : void 0;
+		if (evidence === void 0) return {
 			status: `end-of-support`,
 			previousVersion: previous.version,
 			changes
 		};
-		if (!semver.gt(evidence.version, previous.version)) throw new Error(`The intended release must be newer than baseline ${previous.version}.`);
-		const release = {
-			version: evidence.version,
-			delta: semver.diff(previous.version, evidence.version) ?? `none`
-		};
-		const certified = config.certifyBreaking ? await config.certifyBreaking({
-			previousVersion: previous.version,
-			release,
-			changes
-		}) : false;
-		if (typeof certified !== `boolean`) throw new Error(`certifyBreaking must return a boolean.`);
+		const release = versionDelta(evidence.previousVersion, evidence.version, config.release?.policy);
 		return {
-			status: certified ? `certified` : `end-of-support`,
+			status: release.breaking ? `breaking-release` : `end-of-support`,
 			previousVersion: previous.version,
 			changes,
 			release
@@ -925,21 +1246,21 @@ async function checkLocalReleases(config, base, manifest, representatives) {
 			const directory = path.resolve(base, local.directory);
 			const current = await readManifest(path.join(directory, `package.json`));
 			if (current.name !== peer) throw new Error(`Local peer identity mismatch for ${peer}.`);
-			const release = await intent(config, {
+			const release = await releaseVersion(config, {
 				packageName: peer,
 				packageDirectory: directory,
 				currentVersion: current.version
 			});
-			if (release.status === `none`) return [];
-			if (!matches(release.version, range)) return [`Declared support for ${peer}: ${range} does not include its planned local release ${release.version}. Update the peer range to include the intended version.`];
-			if (!representatives.some((result) => result.peers[peer]?.source === `candidate` && result.peers[peer]?.version === release.version && result.suites.some((suite) => suite.peer === peer))) return [`No coordinated representative covers planned local peer ${peer}@${release.version}. Enroll ${peer} with breakage.candidates and configure its relationship suite.`];
+			if (release === void 0) return [];
+			if (!matches(release, range)) return [`Declared support for ${peer}: ${range} does not include its planned local release ${release}. Update the peer range to include the intended version.`];
+			if (!representatives.some((result) => result.peers[peer]?.source === `candidate` && result.peers[peer]?.version === release && result.suites.some((suite) => suite.peer === peer))) return [`No coordinated representative covers planned local peer ${peer}@${release}. Enroll ${peer} with breakage.candidates and configure its relationship suite.`];
 			return [];
 		} catch (error) {
 			return [`Cannot inspect planned local release for ${peer}: ${errorMessage(error)}`];
 		}
 	}))).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`,
@@ -962,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]);
@@ -996,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)`,
@@ -1028,20 +1350,28 @@ async function run(config, baseDirectory, coverageOnly, selection) {
 			eras(selection.range);
 		}
 		const releases = /* @__PURE__ */ new Map();
-		const configuredHook = config.releaseIntent;
+		const resolveDelta = (context) => {
+			const key = JSON.stringify([
+				context.packageDirectory,
+				context.currentVersion,
+				context.baseline
+			]);
+			let pending = releases.get(key);
+			if (!pending) {
+				pending = resolveReleaseDelta(config.release, context);
+				releases.set(key, pending);
+			}
+			return pending;
+		};
 		const effective = {
 			...config,
-			releaseIntent: (context) => {
-				let pending = releases.get(context.packageDirectory);
-				if (!pending) {
-					pending = Promise.resolve().then(() => configuredHook ? configuredHook(context) : { status: `none` });
-					releases.set(context.packageDirectory, pending);
-				}
-				return pending;
-			}
+			...config.release ? { release: {
+				...config.release,
+				resolveDelta
+			} } : {}
 		};
 		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) {
@@ -1070,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) {
@@ -1090,9 +1424,401 @@ function formatNpmReport(report) {
 	if (report.mode === `coverage-only`) lines.push(`Coverage audit only; compatibility assertions were not executed.`);
 	return `${lines.join(`\n`)}\n`;
 }
-//#endregion
-//#region src/breakage.ts
-async function breakage({ tagPattern, baselineFile, testPattern, testCommand, certifyCommand, baseDirname = process.cwd(), verbose = false }) {
+// 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);
+	const { tagPattern, baselineFile, testPattern, testCommand, test, release, baseDirname = process.cwd(), verbose = false } = options;
+	if (!testPattern || !test && !testCommand) throw new Error(`required arguments were not provided: testPattern and test or testCommand.`);
+	if (test !== void 0 && testCommand !== void 0) throw new Error(`Choose test or testCommand, not both.`);
+	if (typeof (test ?? testCommand) !== `string` || !(test ?? testCommand).trim()) throw new Error(`test must be a nonempty shell command string.`);
+	if (release !== void 0) validateRelease(release);
 	let mark;
 	let logMarks;
 	if (verbose) {
@@ -1163,6 +1889,24 @@ async function breakage({ tagPattern, baselineFile, testPattern, testCommand, ce
 	mark?.(`listed all files checked into git`);
 	const productionTestFiles = productionFiles.filter((file) => minimatch(file, testPattern));
 	mark?.(`filtered to public test files`);
+	let releaseEvidence;
+	if (release) {
+		const current = await readManifest(path.join(baseDirname, `package.json`));
+		const prefix = await git.revparse([`--show-prefix`]);
+		const previous = parseManifest(JSON.parse(await git.show([`${releaseCommit}:${prefix}package.json`])), `baseline`);
+		if (previous.name !== current.name) throw new Error(`Release baseline belongs to another package.`);
+		const transition = await resolveReleaseDelta(release, {
+			packageName: current.name,
+			packageDirectory: path.resolve(baseDirname),
+			currentVersion: current.version,
+			baseline: {
+				version: previous.version,
+				ref: latestReleaseTag$1,
+				commit: releaseCommit
+			}
+		});
+		if (transition !== void 0) releaseEvidence = versionDelta(transition.previousVersion, transition.version, release.policy);
+	}
 	const prepared = await withTestFileState(git, baseDirname, async (state) => {
 		if (!await state.isClean()) return {
 			summary: `The git repository must be clean to run this command.`,
@@ -1186,50 +1930,43 @@ async function breakage({ tagPattern, baselineFile, testPattern, testCommand, ce
 	if (prepared.summary !== void 0) return prepared;
 	const { restore } = prepared;
 	try {
-		const noBreakingChangesDetected = await new Promise((resolve, reject) => {
-			const result = exec(testCommand, { cwd: baseDirname }, (_, __, stderr) => {
-				if (result.exitCode === 0) resolve({
-					summary: `No breaking changes were detected.`,
-					gitWasClean: true,
-					lastReleaseFound: true,
-					lastReleaseTag: latestReleaseTag$1,
-					testsWereFound: true,
-					testsFound: productionTestFiles,
-					breakingChangesFound: false
-				});
-				else reject(stderr);
-			});
-		});
-		mark?.(`passed tests`);
-		return noBreakingChangesDetected;
-	} catch (thrown) {
-		mark?.(`failed tests`);
-		return await new Promise((resolve) => {
-			const result = exec(certifyCommand, { cwd: baseDirname }, (_, stdout, stderr) => {
-				const wereCertified = result.exitCode === 0;
-				mark?.(`${wereCertified ? `passed` : `failed`} certification`);
-				resolve({
-					summary: wereCertified ? `Breaking changes were found and certified.` : `Breaking changes were found, but not certified.`,
-					gitWasClean: true,
-					lastReleaseFound: true,
-					lastReleaseTag: latestReleaseTag$1,
-					testsWereFound: true,
-					testsFound: productionTestFiles,
-					breakingChangesFound: true,
-					testResult: thrown,
-					breakingChangesCertified: wereCertified,
-					certificationStdout: stdout,
-					certificationStderr: stderr
-				});
-			});
-		});
+		const result = await command(test ?? testCommand, baseDirname);
+		if (result.code > 1) return {
+			gitWasClean: true,
+			setupError: result.output,
+			summary: `Public test setup failed (${result.code}).`
+		};
+		const common = {
+			gitWasClean: true,
+			lastReleaseFound: true,
+			lastReleaseTag: latestReleaseTag$1,
+			testsWereFound: true,
+			testsFound: productionTestFiles,
+			...releaseEvidence ? { release: releaseEvidence } : {}
+		};
+		if (result.code === 0) return {
+			...common,
+			breakingChangesFound: false,
+			summary: `No breaking changes were detected.`
+		};
+		return {
+			...common,
+			breakingChangesFound: true,
+			testResult: result.output,
+			summary: releaseEvidence?.breaking ? `Breaking changes are covered by release ${releaseEvidence.previousVersion} → ${releaseEvidence.version}.` : `Breaking changes require a breaking release.`
+		};
+	} catch (error) {
+		return {
+			gitWasClean: true,
+			setupError: errorMessage(error),
+			summary: `Public test setup failed: ${errorMessage(error)}`
+		};
 	} finally {
 		await restore();
 		mark?.(`restored original public tests`);
 		logMarks?.();
 	}
 }
-//#endregion
-export { validateConfig as a, breakagePrelude as c, npmTest as i, formatNpmReport as n, record as o, npmCheck as r, errorMessage as s, breakage as t };
+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-B7dJsgcu.js.map
+//# sourceMappingURL=breakage-DJiIiLzL.js.map