@jterrazz/test 18.2.0 → 18.3.0

package/dist/index.js

@@ -1,8 +1,8 @@
 import { a as endGroup, i as SIGNALS_GROUPS, o as signalGroup, r as KILL_GRACE_MS, t as ServedProcess } from "./shared-serve.js";
 import { i as safeRealpath, r as resolveRoot } from "./shared-resolve.js";
 import { a as getCallerDir, n as deferRewritesTo, r as writeInPlace, t as callSiteOf } from "./shared-in-place.js";
-import { t as isRecord } from "./shared-json-shape.js";
 import { n as refusal$1, t as invariant } from "./shared-refusal.js";
+import { t as isRecord } from "./shared-json-shape.js";
 import { a as field$1, c as containerLogs, d as findContainersByLabel, f as inspectContainer, h as requireDockerDaemon, l as execInContainer, m as removeContainers, p as readContainerFile, r as TestcontainersAdapter, u as fieldOf } from "./shared-testcontainers.adapter.js";
 import { _ as Matcher, d as structuralEquals, g as placeholderStringMatches, h as hasPlaceholders, l as isPlainObject, m as textEquals, n as isStreamBody, p as textContains, r as declared, u as renderExpected, v as match, y as CaptureScope } from "./shared-exchange.js";
 import { a as RUN_KEYS, s as SpecSyntaxError } from "./shared-spec-grammar.js";
@@ -1207,7 +1207,7 @@ function unreachableFile(reason, more, fileName) {
 	if (more) throw new Error(refusal$1({
 		fix: "keep the one line `unreachable: <reason>`, or state the status the exchange answers",
 		found: `${fileName}: "unreachable: ${reason}" is followed by headers or a body`,
-		read: "docs/guides/deployment-specs.md#unreachable-is-a-result",
+		read: "docs/guides/api-specs.md#unreachable-is-a-result",
 		why: "An exchange that never answered carries no header and no body, so its golden is one line."
 	}));
 	return unreachableResponse(reason);
@@ -2574,1871 +2574,1925 @@ const apiDefinition = defineSpecification()({
 	locate: getCallerDir
 });
 //#endregion
-//#region src/specifications/api/server/hono.adapter.ts
-const COMPOSED_HANDLER = "__COMPOSED_HANDLER";
-function targetOf(handler) {
-	const composed = typeof handler === "function" ? Reflect.get(handler, COMPOSED_HANDLER) : void 0;
-	return composed === void 0 ? handler : targetOf(composed);
-}
-function isMiddleware(entry) {
-	const handler = targetOf(entry.handler);
-	return typeof handler === "function" && handler.length > 1;
-}
-var HonoAdapter = class {
-	app;
-	reached = [];
-	constructor(app) {
-		this.app = app;
+//#region src/specifications/api/deployed/connect.capability.ts
+/** Read by the exchange, never armed: the address is where one request is sent, not a state of the world. */
+const connect$2 = defineCapability({
+	initial: null,
+	name: "connect",
+	phase: 0,
+	reduce: (_held, [address]) => address,
+	row: {
+		group: "Setup",
+		name: ".connect()",
+		probe: ".connect("
 	}
-	/** Hono's `app.routes`, less the middleware entries; `undefined` for an app with no table. */
-	declared() {
-		return this.app.routes?.filter((entry) => !isMiddleware(entry)).map((entry) => ({
-			method: entry.method,
-			path: entry.path
-		}));
+});
+//#endregion
+//#region src/specifications/api/deployed/exchange.result.ts
+const EXCHANGE_RESULT_ROWS = [{
+	group: "Result accessor",
+	name: ".response",
+	probe: "result.response"
+}, {
+	group: "Result accessor",
+	name: ".tls",
+	probe: "result.tls"
+}];
+/** What one request to a deployed api hands back: the response, or why none came, and the certificate it came over; no table and no disk, which a deployed api keeps to itself. */
+var ExchangeResult = class {
+	answer;
+	recording;
+	scope = new CaptureScope();
+	testDir;
+	/** The certificate an https request was presented and the trust check's verdict; undefined over http, or when no handshake completed. */
+	tls;
+	constructor(options) {
+		this.answer = options.response;
+		this.recording = options.recording;
+		this.testDir = options.testDir;
+		this.tls = options.tls;
 	}
-	async request(method, path, body, { headers, template } = {}) {
-		const sent = new Headers({ "content-type": "application/json" });
-		for (const [name, value] of Object.entries(headers ?? {})) sent.set(name, value);
-		const init = {
-			body: typeof body === "string" ? body : JSON.stringify(body),
-			headers: sent,
-			method
-		};
-		this.reached.push(template === void 0 ? {
-			method,
-			path
-		} : {
-			method,
-			path,
-			template
-		});
-		const response = await this.app.request(path, init);
-		const contentType = response.headers.get("content-type") ?? void 0;
-		const responseBody = bodyKind(contentType) === "binary" ? null : readBody$1(await response.text(), contentType) ?? null;
-		const responseHeaders = Object.fromEntries(response.headers);
-		return {
-			status: response.status,
-			body: responseBody,
-			headers: responseHeaders
-		};
+	/** The whole response (status, headers, body), or `unreachable: <reason>`, compared whole: `toMatch(<.http text>)` or `toMatch(file(...))`. */
+	get response() {
+		return new ResponseAccessor(this.answer, this.testDir, this.scope, this.recording);
 	}
 };
 //#endregion
-//#region src/specifications/api/api.handle.ts
-async function startApi(options) {
-	const callerDir = getCallerDir();
-	await registerMatchers();
-	const root = resolveRoot(options.root, callerDir);
-	const services = declaredServices(options.services);
-	const databaseKeys = declaredDatabaseKeys(services);
-	const { database, databases, stop } = await startServices(services, root);
-	const server = new HonoAdapter(options.server(services));
-	const config = {
-		database,
-		databaseKeys,
-		databases,
-		server
+//#region src/specifications/api/deployed/target.ts
+const SCHEME = /^[a-z][a-z\d+.-]*:\/\//iu;
+const BRACKETED = /^\[(?<host>[^\]]+)\](?::(?<port>\d+))?$/u;
+const HOST_AND_PORT = /^(?<host>[^:[\]\s]+)(?::(?<port>\d+))?$/u;
+/** The host a URL names, an IPv6 literal without its brackets. */
+function hostOf(url) {
+	return url.hostname.startsWith("[") ? url.hostname.slice(1, -1) : url.hostname;
+}
+/** The port a URL names, or its scheme's. */
+function portOf(url) {
+	if (url.port !== "") return Number(url.port);
+	return url.protocol === "https:" ? 443 : 80;
+}
+function refusedTarget(target, found, fix) {
+	return new Error(refusal$1({
+		fix,
+		found: `${JSON.stringify(target)}, ${found}`,
+		read: "docs/guides/api-specs.md#the-target",
+		why: "A request to a deployed api goes to one absolute http(s) URL: written whole, or a path from the `url` the specification names."
+	}));
+}
+/** A path is read from the base URL as written, its own path kept: `https://site.test/app` and `/health` are `https://site.test/app/health`. */
+function targetUrl(target, base) {
+	if (SCHEME.test(target)) {
+		const url = new URL(target);
+		if (url.protocol !== "http:" && url.protocol !== "https:") throw refusedTarget(target, `a ${url.protocol.slice(0, -1)} URL`, "name an http:// or https:// URL");
+		return url;
+	}
+	if (!target.startsWith("/")) throw refusedTarget(target, "neither an absolute URL nor a path", "write the URL whole, `https://site.test/health`, or a path from the `url` option, `/health`");
+	return new URL(`${base.replace(/\/+$/u, "")}${target}`);
+}
+/** `host:port`, `[v6]:port`, or a bare host, which keeps the URL's port. */
+function connectAddress(written, url) {
+	const address = written.trim();
+	const match = BRACKETED.exec(address) ?? HOST_AND_PORT.exec(address);
+	const host = match?.groups?.host;
+	if (host === void 0 || address.startsWith("[") && isIP(host) !== 6) throw new Error(refusal$1({
+		fix: "write the address as `.connect('10.0.0.5:30443')`, `.connect('[fd7a::1]:443')` or `.connect('node.test')`",
+		found: `.connect(${JSON.stringify(written)}), no address`,
+		read: "docs/guides/api-specs.md#setup-connect",
+		why: "`.connect()` names the one address the socket opens on: a host, and a port when it is not the port of the URL."
+	}));
+	const port = match?.groups?.port;
+	return {
+		host,
+		port: port === void 0 ? portOf(url) : Number(port)
 	};
+}
+//#endregion
+//#region src/specifications/api/deployed/tls-facts.ts
+const DAY_MS = 864e5;
+function firstOf(value) {
+	return Array.isArray(value) ? value[0] : value;
+}
+function altNamesOf(certificate) {
+	return (certificate.subjectaltname ?? "").split(",").map((name) => name.trim().slice(name.trim().indexOf(":") + 1)).filter((name) => name !== "");
+}
+/** Read at the moment of the exchange, so `daysRemaining` is the margin the deployed api had when it answered. */
+function tlsFacts(certificate, verdict, now) {
+	const validTo = new Date(certificate.valid_to);
 	return {
-		api: apiDefinition.open(config),
-		cleanup: async () => {
-			const ledgers = await routesLedger();
-			if (ledgers !== void 0) writeLedger(ledgers, {
-				declared: server.declared(),
-				reached: server.reached
-			});
-			await stop();
-		},
-		docker: createDockerReader(callerDir)
+		altNames: altNamesOf(certificate),
+		authorizationError: verdict.authorizationError,
+		authorized: verdict.authorizationError === void 0,
+		covers: (host) => checkServerIdentity(host, certificate) === void 0,
+		daysRemaining: Math.floor((validTo.getTime() - now) / DAY_MS),
+		issuer: firstOf(certificate.issuer.CN) ?? firstOf(certificate.issuer.O) ?? "",
+		protocol: verdict.protocol,
+		subject: firstOf(certificate.subject.CN) ?? "",
+		validFrom: new Date(certificate.valid_from),
+		validTo
 	};
 }
 //#endregion
-//#region src/stubs/delivery/other-process/stub-backend.ts
-const CORS_METHODS = "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS";
-const PREFLIGHT_MAX_AGE = "600";
-/** A request matching no stub gets 501 and is recorded; once the chain declared a stub, the action throws naming every unmatched request. Every response carries permissive CORS headers. */
-var StubBackend = class {
-	guarded = false;
-	options;
-	queue = new StubQueue([]);
-	received = [];
-	server = null;
-	unmatchedRequests = /* @__PURE__ */ new Map();
-	constructor(options = {}) {
-		this.options = options;
-	}
-	async start() {
-		const server = createServer((request, response) => {
-			this.handle(request, response);
-		});
-		this.server = server;
-		return `http://127.0.0.1:${await listenedPort(server, {
-			host: "127.0.0.1",
-			port: this.options.port ?? 0
-		})}`;
-	}
-	async stop() {
-		const { server } = this;
-		if (!server) return;
-		this.server = null;
-		server.closeAllConnections();
-		await new Promise((resolve) => {
-			server.close(() => {
-				resolve();
-			});
+//#region src/specifications/api/deployed/unreachable.ts
+/** Why an exchange never answered, as the `unreachable: <reason>` line of its golden reads it. */
+const TIMEOUT = "timeout";
+const TLS = "tls";
+const REASONS = {
+	EAI_AGAIN: "dns",
+	EAI_FAIL: "dns",
+	EAI_NODATA: "dns",
+	EAI_NONAME: "dns",
+	ECONNABORTED: "reset",
+	ECONNREFUSED: "refused",
+	ECONNRESET: "reset",
+	EHOSTDOWN: "no route",
+	EHOSTUNREACH: "no route",
+	ENETDOWN: "no route",
+	ENETUNREACH: "no route",
+	ENODATA: "dns",
+	ENOTFOUND: "dns",
+	EPIPE: "reset"
+};
+/** The code node raised, when it raised one. */
+function codeOf(error) {
+	if (typeof error === "string") return error === "" ? void 0 : error;
+	const code = error !== null && typeof error === "object" ? Reflect.get(error, "code") : void 0;
+	return typeof code === "string" && code !== "" ? code : void 0;
+}
+/** `dns`, `refused`, `reset`, `no route`, or the code node raised; a handshake's own failure is `tls <CODE>`, its network's reads as the network's. */
+function unreachableReason(error, duringHandshake = false) {
+	const code = codeOf(error);
+	const reason = code === void 0 ? void 0 : REASONS[code];
+	if (reason !== void 0) return reason;
+	if (duringHandshake) return `${TLS} ${code ?? "handshake"}`;
+	return code ?? (error instanceof Error ? error.message : String(error));
+}
+/** A certificate the trust check refused, by the code it refused with. */
+function refusedCertificate(code) {
+	return `${TLS} ${code}`;
+}
+//#endregion
+//#region src/specifications/api/deployed/transport.ts
+const USER_AGENT = "@jterrazz/test";
+function flatHeaders(headers) {
+	return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, Array.isArray(value) ? value.join(", ") : String(value)]));
+}
+function headersOf(sent) {
+	const headers = {
+		host: sent.url.host,
+		"user-agent": USER_AGENT
+	};
+	for (const [name, value] of Object.entries(sent.headers)) headers[name.toLowerCase()] = value;
+	return headers;
+}
+async function opened(socket, event) {
+	await new Promise((resolve, reject) => {
+		socket.once(event, () => {
+			resolve();
 		});
-	}
-	/** The chain's stubs replace the previous chain's wholesale; the queue and the unmatched log restart. */
-	beginChain(stubs) {
-		this.guarded = stubs.length > 0;
-		this.queue = new StubQueue(stubs);
-		this.unmatchedRequests.clear();
-		this.received.length = 0;
-	}
-	/** Every request the backend was sent since the chain began, in arrival order, matched or not: what a binary SENT, to compare whole. A preflight is no request of the program's. */
-	requests() {
-		return this.received.map((request) => ({
-			...request,
-			headers: { ...request.headers }
-		}));
-	}
-	/** Non-null when the chain declared a stub and a request went unmatched, a never stub was reached, or a `required` stub was never met. */
-	violation() {
-		if (!this.guarded) return null;
-		if (this.unmatchedRequests.size === 0) return this.queue.verdict();
-		const unmatched = [...this.unmatchedRequests.values()].map((entry) => `  - ${entry.method} ${entry.path}${entry.count > 1 ? ` (${entry.count} times)` : ""}`).join("\n");
-		const declared = this.queue.declaredRoutes().map((route) => `  - ${route}`).join("\n");
-		const strict = new Error(refusal$1("network-strict-after-first-stub", {
-			fix: "add a stub for each to the chain's composite",
-			found: `unmatched request(s) hit the declared backend during the chain:\n${unmatched}\ndeclared stubs:\n${declared}`
-		}));
-		return this.queue.verdict(strict);
-	}
-	async handle(request, response) {
-		const method = (request.method ?? "GET").toUpperCase();
-		const cors = corsHeaders(request);
-		if (method === "OPTIONS") {
-			response.writeHead(204, cors);
-			response.end();
-			return;
-		}
-		const url = request.url ?? "/";
-		const observed = {
-			body: await readBody(request),
-			headers: stringHeaders(request),
-			method,
-			url
+		socket.once("error", reject);
+	});
+}
+async function openSecure(address, url, route, hold) {
+	const name = hostOf(url);
+	const socket = connect$1({
+		checkServerIdentity: (_host, certificate) => checkServerIdentity(name, certificate),
+		host: address.host,
+		port: address.port,
+		rejectUnauthorized: false,
+		...route.ca === void 0 ? {} : { ca: [...getCACertificates("default"), route.ca] },
+		...isIP(name) === 0 ? { servername: name } : {}
+	});
+	hold(socket);
+	try {
+		await opened(socket, "secureConnect");
+	} catch (error) {
+		return {
+			tls: void 0,
+			unreachable: unreachableReason(error, true)
 		};
-		this.received.push(observed);
-		const stub = this.queue.take(observed);
-		if (!stub) {
-			this.record(method, url);
-			const error = refusedReply(unmatchedSummary(method, url));
-			response.writeHead(501, {
-				...cors,
-				"content-type": "application/json"
-			});
-			response.end(JSON.stringify({
-				declared: this.queue.declaredRoutes(),
-				error
-			}));
-			return;
-		}
-		const reply = await replyOf(stub.response, observed);
-		if (reply.transport === "network-error") {
-			request.socket.destroy();
-			return;
-		}
-		await writeReply(response, reply, cors);
 	}
-	record(method, path) {
-		const key = `${method} ${path}`;
-		const existing = this.unmatchedRequests.get(key);
-		if (existing) existing.count += 1;
-		else this.unmatchedRequests.set(key, {
-			count: 1,
-			method,
-			path
-		});
-	}
-};
-function stringHeaders(request) {
-	return Object.fromEntries(Object.entries(request.headers).filter((entry) => typeof entry[1] === "string"));
+	const refused = socket.authorized ? void 0 : codeOf(socket.authorizationError);
+	const tls = tlsFacts(socket.getPeerCertificate(), {
+		authorizationError: refused,
+		protocol: socket.getProtocol() ?? void 0
+	}, Date.now());
+	return refused === void 0 || route.insecure ? {
+		socket,
+		tls
+	} : {
+		tls,
+		unreachable: refusedCertificate(refused)
+	};
 }
-async function writeReply(response, reply, cors) {
-	const status = reply.status ?? 200;
-	const { body } = reply;
-	if (isStreamBody(body)) {
-		response.writeHead(status, {
-			...cors,
-			"content-type": body.contentType,
-			...reply.headers
-		});
-		await toReadableStream(body).pipeTo(new WritableStream({
-			close() {
-				response.end();
-			},
-			write(chunk) {
-				response.write(chunk);
-			}
-		}));
-		return;
-	}
-	if (body === null || body === void 0) {
-		response.writeHead(status, {
-			...cors,
-			...reply.headers
+async function open$1(sent, route, hold) {
+	const address = route.connect ?? {
+		host: hostOf(sent.url),
+		port: portOf(sent.url)
+	};
+	if (sent.url.protocol === "https:") return await openSecure(address, sent.url, route, hold);
+	const socket = connect(address);
+	hold(socket);
+	await opened(socket, "connect");
+	return {
+		socket,
+		tls: void 0
+	};
+}
+async function exchanged(sent, socket) {
+	return await new Promise((resolve, reject) => {
+		const outgoing = request({
+			createConnection: () => socket,
+			headers: headersOf(sent),
+			method: sent.method,
+			path: `${sent.url.pathname}${sent.url.search}`
+		}, (response) => {
+			const chunks = [];
+			response.on("data", (chunk) => {
+				chunks.push(chunk);
+			});
+			response.once("end", () => {
+				resolve({
+					response,
+					text: Buffer.concat(chunks).toString("utf8")
+				});
+			});
+			response.once("error", reject);
 		});
-		response.end();
-		return;
-	}
-	const contentType = typeof body === "string" ? "text/plain; charset=utf-8" : "application/json";
-	response.writeHead(status, {
-		...cors,
-		"content-type": contentType,
-		...reply.headers
+		outgoing.once("error", reject);
+		outgoing.end(sent.body);
 	});
-	response.end(typeof body === "string" ? body : JSON.stringify(body));
-}
-async function readBody(request) {
-	const chunks = [];
-	for await (const chunk of request) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
-	return requestBody(Buffer.concat(chunks).toString("utf8"));
 }
-function corsHeaders(request) {
+async function answered(sent, route, hold, presented) {
+	const opening = await open$1(sent, route, hold);
+	presented(opening.tls);
+	if (!("socket" in opening)) return opening;
+	const { response, text } = await exchanged(sent, opening.socket);
 	return {
-		"access-control-allow-headers": request.headers["access-control-request-headers"] ?? "*",
-		"access-control-allow-methods": CORS_METHODS,
-		"access-control-allow-origin": "*",
-		"access-control-max-age": PREFLIGHT_MAX_AGE
+		headers: flatHeaders(response.headers),
+		status: response.statusCode ?? 0,
+		text,
+		tls: opening.tls
 	};
 }
-//#endregion
-//#region src/disk/fixture.capability.ts
-/** Judged when stated, resolved on disk when armed; a later fixture overwrites an earlier one. */
-const fixture = defineCapability({
-	arm: (targets, { workdir }, { testDir, workDir }) => {
-		if (workDir !== null) for (const target of targets) workdir.layer(target.path, testDir, workDir);
-		return {};
-	},
-	initial: [],
-	name: "fixture",
-	phase: 20,
-	reduce: (targets, [source]) => [...targets, requireDiskTarget("fixture", source)],
-	row: {
-		group: "Setup",
-		name: ".fixture()",
-		probe: ".fixture("
+/** One request and its whole response, under one deadline; a redirect is the answer, never followed. */
+async function exchange(sent, route) {
+	const sockets = [];
+	let tls;
+	let timer;
+	const deadline = new Promise((resolve) => {
+		timer = setTimeout(() => {
+			resolve({
+				tls,
+				unreachable: TIMEOUT
+			});
+		}, route.timeout);
+	});
+	try {
+		return await Promise.race([answered(sent, route, (held) => {
+			sockets.push(held);
+		}, (facts) => {
+			tls = facts;
+		}), deadline]);
+	} catch (error) {
+		return {
+			tls,
+			unreachable: unreachableReason(error)
+		};
+	} finally {
+		clearTimeout(timer);
+		for (const socket of sockets) socket.destroy();
 	}
-});
-//#endregion
-//#region src/disk/fs-fixtures.adapter.ts
-function copyPlan(path, specDir, workDir) {
-	const src = resolveSpecPath("fixture", path, specDir);
-	if (!existsSync(src)) throw new Error(refusal$1("disk-named-by-relative-path-at-runtime", {
-		fix: `create ${src}, or correct the path`,
-		found: `fixture: ${JSON.stringify(path)} names nothing: ${src} does not exist`
-	}));
-	const spread = path.endsWith("/");
-	const isDirectory = statSync(src).isDirectory();
-	if (isDirectory !== spread) throw new TypeError(refusal$1("disk-named-by-relative-path-at-runtime", isDirectory ? {
-		fix: `end its path in /: directory('${path}/'), whose contents are spread into the working directory`,
-		found: `fixture: ${JSON.stringify(path)} names a directory`
-	} : {
-		fix: `drop the /: file('${path.replace(/\/+$/u, "")}')`,
-		found: `fixture: ${JSON.stringify(path)} names a file`
-	}));
-	return {
-		dest: spread ? workDir : resolve(workDir, basename(src)),
-		src
-	};
 }
-const fsFixtures = { layer: (path, testDir, workDir) => {
-	const { dest, src } = copyPlan(path, testDir, workDir);
-	cpSync(src, dest, { recursive: true });
-} };
 //#endregion
-//#region src/disk/installed-package.ts
-/** The directory of the package `name`, found as Node finds it from `from`: in the nearest `node_modules` holding it. */
-function installedPackage(name, testDir) {
-	let dir = testDir;
-	for (;;) {
-		const candidate = resolve(dir, "node_modules", name);
-		if (existsSync(candidate) && statSync(candidate).isDirectory()) return candidate;
-		const parent = dirname(dir);
-		if (parent === dir) return null;
-		dir = parent;
-	}
+//#region src/specifications/api/deployed/request.action.ts
+const NO_WORKDIR = { workDir: null };
+function responseOf(answer) {
+	if (answer.unreachable !== void 0) return {
+		body: null,
+		headers: {},
+		status: 0,
+		unreachable: answer.unreachable
+	};
+	const contentType = answer.headers["content-type"];
+	return {
+		body: bodyKind(contentType) === "binary" ? null : readBody$1(answer.text, contentType) ?? null,
+		headers: answer.headers,
+		status: answer.status
+	};
+}
+async function send(written, read, { config, testDir }) {
+	const url = targetUrl(written.target, config.baseUrl);
+	const address = read(connect$2);
+	const answer = await exchange({
+		body: written.body,
+		headers: {
+			...written.headers,
+			...read(headers)
+		},
+		method: written.method,
+		url
+	}, {
+		ca: config.ca,
+		connect: address === null ? void 0 : connectAddress(address, url),
+		insecure: config.insecure,
+		timeout: config.timeout
+	});
+	return new ExchangeResult({
+		recording: config.recording,
+		response: responseOf(answer),
+		testDir,
+		tls: answer.tls
+	});
+}
+function writtenRequest(source, testDir) {
+	const parsed = typeof source === "string" ? parseRequestFile(dedent(source), "the request in place") : parseRequestFile(readFileSync(resolve(testDir, source.path), "utf8"), source.path);
+	return {
+		body: parsed.body,
+		headers: parsed.headers,
+		method: parsed.method,
+		target: parsed.path
+	};
 }
+/** A redirect is the answer, never followed; an exchange that never answered is the answer too, `unreachable: <reason>`. */
+const get = defineAction({
+	accessors: EXCHANGE_RESULT_ROWS,
+	name: "get",
+	perform: async ([target], read, _adapters, run) => await send({
+		headers: {},
+		method: "GET",
+		target
+	}, read, run),
+	row: {
+		group: "Terminal action",
+		name: ".get()",
+		probe: ".get('/"
+	}
+});
 //#endregion
-//#region src/disk/link-destination.ts
-/** The directory a `directory()` names for a link, refused when it names nothing or a file; `call` is the gesture as the spec wrote it. */
-function linkedDirectory(call, path, testDir) {
-	const src = resolveSpecPath("link", path, testDir);
-	if (!existsSync(src)) throw new Error(refusal$1("disk-named-by-relative-path-at-runtime", {
-		fix: `create ${src}, or correct the path`,
-		found: `${call} names nothing: ${src} does not exist`
-	}));
-	if (!statSync(src).isDirectory()) throw new Error(refusal$1("disk-named-by-relative-path-at-runtime", {
-		fix: `name the directory that holds the package's package.json: directory('${dirname(path)}/')`,
-		found: `${call} names a file`
+//#region src/specifications/api/deployed/deployed.composition.ts
+const composition$6 = {
+	actions: [defineAction({
+		accessors: EXCHANGE_RESULT_ROWS,
+		name: "request",
+		perform: async ([source], read, _adapters, run) => await send(writtenRequest(source, run.testDir), read, run),
+		prepare: ([source]) => {
+			if (typeof source !== "string") requireDiskFile("request", source, ".http");
+			return NO_WORKDIR;
+		},
+		row: {
+			group: "Terminal action",
+			name: ".request()",
+			probe: ".request(file("
+		}
+	}), get],
+	capabilities: [
+		connect$2,
+		headers,
+		sharing
+	],
+	options: {
+		ca: {
+			group: "Constructor option",
+			name: "ca",
+			probe: "ca:"
+		},
+		insecure: {
+			group: "Constructor option",
+			name: "insecure",
+			probe: "insecure:"
+		},
+		recordedHeaders: {
+			group: "Constructor option",
+			name: "recordedHeaders",
+			probe: "recordedHeaders:"
+		},
+		timeout: {
+			group: "Constructor option",
+			name: "timeout",
+			probe: "timeout:"
+		},
+		url: {
+			group: "Constructor option",
+			name: "url",
+			probe: "url:"
+		}
+	}
+};
+const apiDeployedDefinition = defineSpecification()({
+	...composition$6,
+	adapters: (_config) => ({}),
+	locate: getCallerDir
+});
+//#endregion
+//#region src/specifications/api/deployed/refused-setups.ts
+const IN_PROCESS_ONLY = /* @__PURE__ */ new Set([
+	"clock",
+	"delete",
+	"intercept",
+	"post",
+	"put",
+	"seed"
+]);
+function refusedSetup(name) {
+	return new Error(refusal$1({
+		fix: "seed, stub and pin the app with `server`, in this process; against a `url`, send the request (`.get()`, `.request()`) and compare the response",
+		found: `.${name}() on the chain of specification.api({ url })`,
+		read: "docs/guides/api-specs.md#deployed-target-url",
+		why: "A deployed api runs elsewhere: its database, its outbound network and its clock are its own, so its chain offers what a request can do, and a request other than a GET is written whole."
 	}));
-	return src;
 }
-/** Refuses a destination under the working directory whose path crosses a file or a symlink: through a symlinked folder, the delete before the lay would reach a real install outside it. */
-function refuseUnusableAncestor(name, workDir, dest) {
-	let ancestor = workDir;
-	for (const segment of relative(workDir, dirname(dest)).split(/[\\/]/u)) {
-		ancestor = resolve(ancestor, segment);
-		if (!existsSync(ancestor)) return;
-		const entry = lstatSync(ancestor);
-		if (!entry.isSymbolicLink() && !entry.isDirectory()) throw new Error(refusal$1({
-			fix: `drop the file at ${ancestor} from the fixture or the command that lays it, so the link can lay its folder there`,
-			found: `link('${name}'): ${ancestor} is a file, not a folder`,
-			read: "docs/guides/cli-specs.md#link-a-package-the-working-directory-resolves",
-			why: "A link is laid at node_modules/<name> inside the working directory, and a file on that path leaves it no folder to lay it in."
-		}));
-		if (entry.isSymbolicLink()) throw new Error(refusal$1({
-			fix: `drop the symlink at ${ancestor} from the fixture or the command that lays it, so the working directory holds its own node_modules`,
-			found: `link('${name}'): ${ancestor} is a symlink, so the link would replace ${name} wherever it points`,
-			read: "docs/guides/cli-specs.md#link-a-package-the-working-directory-resolves",
-			why: "A link is laid inside the working directory only; through a symlinked folder it would delete a real install outside it."
-		}));
-	}
+/** The type already holds it; an untyped caller is told why rather than that the method is undefined. */
+function refusingInProcessSetups(chain) {
+	return new Proxy(chain, { get: (target, name, receiver) => {
+		if (typeof name === "string" && IN_PROCESS_ONLY.has(name)) return () => {
+			throw refusedSetup(name);
+		};
+		const value = Reflect.get(target, name, receiver);
+		if (typeof value !== "function") return value;
+		return (...args) => {
+			const next = Reflect.apply(value, target, args);
+			return next !== null && typeof next === "object" && !(next instanceof Promise) ? refusingInProcessSetups(next) : next;
+		};
+	} });
 }
 //#endregion
-//#region src/disk/package-manifest.ts
-function keysOf(value) {
-	return isRecord(value) ? Object.keys(value) : [];
+//#region src/specifications/api/server/hono.adapter.ts
+const COMPOSED_HANDLER = "__COMPOSED_HANDLER";
+function targetOf(handler) {
+	const composed = typeof handler === "function" ? Reflect.get(handler, COMPOSED_HANDLER) : void 0;
+	return composed === void 0 ? handler : targetOf(composed);
 }
-const SCOPE = /^@[^/]+\//u;
-function binOf$1(name, bin) {
-	if (typeof bin === "string") return typeof name === "string" ? { [name.replace(SCOPE, "")]: bin } : {};
-	return Object.fromEntries(Object.entries(isRecord(bin) ? bin : {}).filter((entry) => typeof entry[1] === "string"));
+function isMiddleware(entry) {
+	const handler = targetOf(entry.handler);
+	return typeof handler === "function" && handler.length > 1;
 }
-function parsedManifest(directory) {
-	const path = join(directory, "package.json");
-	try {
-		return JSON.parse(readFileSync(path).toString());
-	} catch (error) {
-		throw new Error(refusal$1({
-			fix: `correct ${path}, so npm and Node read the package it describes`,
-			found: `packed(): ${path} is no JSON: ${error instanceof Error ? error.message : String(error)}`,
-			read: "docs/guides/cli-specs.md#a-package-specified-from-its-artefact",
-			why: "packed() reads the name, the bin and the runtime closure the package declares in its package.json."
-		}), { cause: error });
+var HonoAdapter = class {
+	app;
+	reached = [];
+	constructor(app) {
+		this.app = app;
 	}
-}
-/** What `packed()` reads of a package's manifest: its name, the commands its `bin` lays, and what it requires at runtime; a manifest that is no JSON is refused. */
-function manifestAt(directory) {
-	const parsed = parsedManifest(directory);
-	const field = (key) => isRecord(parsed) ? parsed[key] : void 0;
-	const name = field("name");
-	const meta = field("peerDependenciesMeta");
-	const optional = (peer) => isRecord(meta) && isRecord(meta[peer]) && meta[peer].optional === true;
-	return {
-		bin: binOf$1(name, field("bin")),
-		name: typeof name === "string" ? name : void 0,
-		runtime: [
-			...keysOf(field("dependencies")),
-			...keysOf(field("optionalDependencies")),
-			...keysOf(field("peerDependencies")).filter((peer) => !optional(peer))
-		]
-	};
-}
-//#endregion
-//#region src/disk/npm-packed.adapter.ts
-function projectOf(testDir) {
-	for (let directory = testDir;; directory = dirname(directory)) {
-		if (existsSync(join(directory, "package.json"))) return directory;
-		if (dirname(directory) === directory) throw new Error(refusal$1({
-			fix: "run the spec inside the package it specifies, or name the package: packed(directory('./<path>/'))",
-			found: `packed(): no package.json from ${testDir} up`,
-			read: "docs/guides/cli-specs.md#a-package-specified-from-its-artefact",
-			why: "packed() packs the project the spec belongs to, which its nearest package.json names."
+	/** Hono's `app.routes`, less the middleware entries; `undefined` for an app with no table. */
+	declared() {
+		return this.app.routes?.filter((entry) => !isMiddleware(entry)).map((entry) => ({
+			method: entry.method,
+			path: entry.path
 		}));
 	}
-}
-function packageDirectory(name, path, testDir) {
-	const call = `link('${name}', packed(directory(${JSON.stringify(path)})))`;
-	const directory = linkedDirectory(call, path, testDir);
-	if (!existsSync(join(directory, "package.json"))) throw new Error(refusal$1({
-		fix: `name the directory that holds the package's package.json, or give ${directory} one`,
-		found: `${call}: ${directory} holds no package.json`,
-		read: "docs/guides/cli-specs.md#a-package-specified-from-its-artefact",
-		why: "packed() packs a package, and a package is the directory its package.json describes."
-	}));
-	return directory;
-}
-const UNPACKED = /* @__PURE__ */ new Map();
-function unpackedOf(packageRoot) {
-	const known = UNPACKED.get(packageRoot);
-	if (known !== void 0) return known;
-	const into = mkdtempSync(join(tmpdir(), "jterrazz-packed-"));
-	process.once("exit", () => {
-		rmSync(into, {
-			force: true,
-			recursive: true
-		});
-	});
-	const filename = packInto(packageRoot, into);
-	execFileSync("tar", [
-		"-xzf",
-		join(into, filename),
-		"-C",
-		into
-	]);
-	const unpacked = join(into, "package");
-	UNPACKED.set(packageRoot, unpacked);
-	return unpacked;
-}
-function packInto(packageRoot, into) {
-	const packing = spawnSync("npm", [
-		"pack",
-		"--ignore-scripts",
-		"--silent",
-		"--pack-destination",
-		into
-	], {
-		cwd: packageRoot,
-		encoding: "utf8",
-		stdio: [
-			"ignore",
-			"pipe",
-			"pipe"
-		]
-	});
-	if (packing.status !== 0) throw new Error(refusal$1({
-		fix: `run \`npm pack\` in ${packageRoot} and settle what npm says, so the package packs as it would be published`,
-		found: `packed(): \`npm pack\` failed in ${packageRoot}${packing.error === void 0 ? "" : ` (${packing.error.message})`}:\n${packing.stderr.trim()}`,
-		read: "docs/guides/cli-specs.md#a-package-specified-from-its-artefact",
-		why: "packed() lays the tarball npm writes for the package, so a package npm cannot pack gives it nothing to lay."
-	}));
-	return packing.stdout.trim().split("\n").at(-1) ?? "";
-}
-function linkInto(workDir, name, source) {
-	const destination = join(workDir, "node_modules", name);
-	if (existsSync(destination)) return;
-	mkdirSync(dirname(destination), { recursive: true });
-	symlinkSync(source, destination, "dir");
-}
-function requiredPackages(name, runtime, { packageRoot, testDir }) {
-	return runtime.map((dependency) => {
-		const installed = installedPackage(dependency, packageRoot);
-		if (installed === null) throw new Error(refusal$1({
-			fix: `install ${dependency} where ${name} is developed, as its consumers' install would`,
-			found: `link('${name}', packed()): ${name} requires ${dependency}, which no node_modules above ${relative(testDir, packageRoot) || "."} holds`,
-			read: "docs/guides/cli-specs.md#a-package-specified-from-its-artefact",
-			why: "The packed package is laid beside what its manifest requires at runtime, taken from where it is developed."
-		}));
-		return {
-			dependency,
-			installed
+	async request(method, path, body, { headers, template } = {}) {
+		const sent = new Headers({ "content-type": "application/json" });
+		for (const [name, value] of Object.entries(headers ?? {})) sent.set(name, value);
+		const init = {
+			body: typeof body === "string" ? body : JSON.stringify(body),
+			headers: sent,
+			method
 		};
-	});
-}
-/** Lays the packed package at `node_modules/<name>` as a copy, beside a link to each package its manifest requires at runtime, resolved from where the package is developed. */
-function installPacked(name, path, testDir, workDir) {
-	const packageRoot = path === null ? projectOf(testDir) : packageDirectory(name, path, testDir);
-	const declared = manifestAt(packageRoot);
-	if (declared.name !== name) throw new Error(refusal$1({
-		fix: `link it under the name its package.json declares: link('${declared.name ?? "<no name>"}', packed(...))`,
-		found: `link('${name}', packed()) packs ${relative(testDir, packageRoot) || "."}, whose package.json names ${declared.name ?? "no package"}`,
-		read: "docs/guides/cli-specs.md#a-package-specified-from-its-artefact",
-		why: "A consumer imports a package by the name it is published under, so the install lays it there."
-	}));
-	const modules = join(workDir, "node_modules");
-	const destination = join(modules, name);
-	for (const written of [
-		destination,
-		...declared.runtime.map((dependency) => join(modules, dependency)),
-		...Object.keys(declared.bin).map((command) => join(modules, ".bin", command))
-	]) refuseUnusableAncestor(name, workDir, written);
-	const required = requiredPackages(name, declared.runtime, {
-		packageRoot,
-		testDir
-	});
-	const unpacked = unpackedOf(packageRoot);
-	rmSync(destination, {
-		force: true,
-		recursive: true
-	});
-	mkdirSync(dirname(destination), { recursive: true });
-	cpSync(unpacked, destination, { recursive: true });
-	const manifest = manifestAt(unpacked);
-	for (const { dependency, installed } of required) linkInto(workDir, dependency, installed);
-	mkdirSync(join(modules, ".bin"), { recursive: true });
-	for (const [command, target] of Object.entries(manifest.bin)) {
-		const link = join(modules, ".bin", command);
-		rmSync(link, { force: true });
-		symlinkSync(relative(join(modules, ".bin"), join(destination, target)), link);
-	}
-}
-//#endregion
-//#region src/disk/fs-links.adapter.ts
-function sourceOf(name, path, testDir) {
-	if (path === null) {
-		const installed = installedPackage(name, testDir);
-		if (installed === null) throw new Error(refusal$1({
-			fix: `install ${name} in the project the spec belongs to, or name the package's directory: link('${name}', directory('./__fixtures__/<package>/'))`,
-			found: `link('${name}'): no node_modules from ${testDir} up holds ${name}`,
-			read: "docs/guides/cli-specs.md#link-a-package-the-working-directory-resolves",
-			why: "A bare name links the package the spec's own project resolves, found as Node finds it."
-		}));
-		return installed;
-	}
-	return linkedDirectory(`link('${name}', directory(${JSON.stringify(path)}))`, path, testDir);
-}
-const fsLinks = {
-	packed: installPacked,
-	link: (name, path, testDir, workDir) => {
-		const src = sourceOf(name, path, testDir);
-		const dest = resolve(workDir, "node_modules", name);
-		refuseUnusableAncestor(name, workDir, dest);
-		mkdirSync(dirname(dest), { recursive: true });
-		rmSync(dest, {
-			force: true,
-			recursive: true
+		this.reached.push(template === void 0 ? {
+			method,
+			path
+		} : {
+			method,
+			path,
+			template
 		});
-		symlinkSync(src, dest, "dir");
+		const response = await this.app.request(path, init);
+		const contentType = response.headers.get("content-type") ?? void 0;
+		const responseBody = bodyKind(contentType) === "binary" ? null : readBody$1(await response.text(), contentType) ?? null;
+		const responseHeaders = Object.fromEntries(response.headers);
+		return {
+			status: response.status,
+			body: responseBody,
+			headers: responseHeaders
+		};
 	}
 };
 //#endregion
-//#region src/disk/in-process-steps.adapter.ts
-/** A step is the test's own code: it runs in the test's process, one after the other. */
-const inProcessSteps = { run: async (steps, workDir) => {
-	for (const step of steps) await step(workDir);
-} };
-//#endregion
-//#region src/disk/packed.ts
-const PACKED = Symbol.for("@jterrazz/test:packed");
-/** Name the package a consumer installs: the project the spec belongs to, or the package a directory holds, packed as `npm pack` packs it. */
-function packed(source) {
-	return Object.freeze({
-		[PACKED]: true,
-		path: isDiskDirectory(source) ? source.path : null
-	});
+//#region src/specifications/api/api.handle.ts
+const DEFAULT_TIMEOUT_MS$1 = 5e3;
+const DEFAULT_RECORDED_HEADERS = ["content-type", "location"];
+const DEPLOYED_ONLY = [
+	"ca",
+	"insecure",
+	"recordedHeaders",
+	"timeout"
+];
+function refused(found, why, fix) {
+	return new Error(refusal$1({
+		fix,
+		found,
+		read: "docs/guides/api-specs.md#options",
+		why
+	}));
 }
-function isPackedPackage(value) {
-	return value !== null && typeof value === "object" && Reflect.get(value, PACKED) === true;
+function refuseTarget(options) {
+	const hasServer = options.server !== void 0;
+	if (hasServer && options.url !== void 0) throw refused("specification.api({ server, url }), an app built here beside a deployed one", "`server` and `url` are exclusive: a request goes to the app this process builds, or to the one deployed at the url.", "keep `server` to test the app in this process, or `url` to probe the deployed one");
+	const deployedOnly = DEPLOYED_ONLY.filter((name) => options[name] !== void 0);
+	if (hasServer && deployedOnly.length > 0) throw refused(`specification.api({ server, ${deployedOnly.join(", ")} }), an option of a deployed api beside an app built here`, "`ca`, `insecure`, `recordedHeaders` and `timeout` shape requests sent over the network, which a `url` names; an app built in this process is answered without one.", "drop them, or name the deployed api with `url`");
+	if (!hasServer && (options.services !== void 0 || options.root !== void 0)) throw refused("specification.api({ url, services }), services beside a deployed url", "A deployed api is wired to its own services: services started here never reach it.", "drop `services` and `root`, or build the app with `server` to wire them");
 }
-//#endregion
-//#region src/disk/link.capability.ts
-const PACKAGE_NAME = /^(?:@[a-z0-9~-][\w.~-]*\/)?[a-z0-9~-][\w.~-]*$/u;
-function requirePackageName(name, linked) {
-	if (typeof name !== "string" || !PACKAGE_NAME.test(name) || name.toLowerCase() !== name) throw new TypeError(refusal$1({
-		fix: "name it as a package.json `dependencies` key does: link('@scope/name') or link('name')",
-		found: `link(${JSON.stringify(name)}), no package name`,
-		read: "docs/guides/cli-specs.md#link-a-package-the-working-directory-resolves",
-		why: "The name is where the package lands, `node_modules/<name>`, and what the binary imports it by."
-	}));
-	if (linked.some((entry) => entry.name === name)) throw new TypeError(refusal$1({
-		fix: `link ${name} once, from the one source the binary should resolve`,
-		found: `link(${JSON.stringify(name)}), stated twice on one chain`,
-		read: "docs/guides/cli-specs.md#link-a-package-the-working-directory-resolves",
-		why: "A name resolves to one package: a second link of it would silently replace the first."
-	}));
-	return name;
+function refuseUrl(url) {
+	if (typeof url !== "string" || url.trim() === "") throw refused(`specification.api({ url: ${JSON.stringify(url)} }), no app to specify`, "An api spec names the app it requests: a `server` it builds in this process, or a deployed `url`.", "build the app with `server`, or pass the absolute URL of the deployed api as `url`");
+	if (!/^https?:\/\/[^/\s]/u.test(url)) throw refused(`specification.api({ url: ${JSON.stringify(url)} }), no http(s) URL`, "A path is read from the base `url`, so the base is an absolute http:// or https:// URL.", "name the deployed api's base as an absolute URL, `url: 'https://site.test'`");
 }
-function requireSource(name, source) {
-	if (source === void 0) return null;
-	if (isPackedPackage(source)) return source.path;
-	if (isDiskDirectory(source)) return source.path;
-	throw new TypeError(refusal$1("disk-named-by-relative-path-at-runtime", {
-		fix: `name the package's directory: link('${name}', directory('./__fixtures__/${name.split("/").at(-1)}/'))`,
-		found: isDiskFile(source) ? `link('${name}', file(${JSON.stringify(source.path)})), a file where a package's directory is read` : `link('${name}', ${typeof source === "string" ? JSON.stringify(source) : typeof source}), a value where a package's directory is read`
-	}));
+function refuseTimeout(timeout) {
+	if (timeout !== void 0 && (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0)) throw refused(`specification.api({ url, timeout: ${typeof timeout === "number" ? String(timeout) : JSON.stringify(timeout)} }), no deadline`, "A request that never answers reads `unreachable: timeout` once its deadline passes, so the deadline is a positive number of milliseconds.", "pass the milliseconds one request may take, `timeout: 2000`, or leave the 5000 default");
 }
-const link$1 = defineCapability({
-	arm: (linked, { links }, { testDir, workDir }) => {
-		if (workDir !== null) for (const { name, packed, path } of linked) (packed ? links.packed : links.link)(name, path, testDir, workDir);
-		return {};
-	},
-	initial: [],
-	name: "link",
-	phase: 25,
-	reduce: (linked, [name, source]) => {
-		const checked = requirePackageName(name, linked);
-		return [...linked, {
-			name: checked,
-			packed: isPackedPackage(source),
-			path: requireSource(checked, source)
-		}];
-	},
-	row: {
-		group: "Setup",
-		name: ".link()",
-		probe: ".link("
+/** Refused before anything starts: a target that is neither or both, and what a deployed target cannot carry. */
+function refuseOptions$1(options) {
+	refuseTarget(options);
+	if (options.server === void 0) {
+		refuseUrl(options.url);
+		refuseTimeout(options.timeout);
 	}
-});
-//#endregion
-//#region src/disk/prepare.capability.ts
-function requireStep(step) {
-	if (typeof step === "function") return step;
-	throw new TypeError(refusal$1({
-		fix: "hand it a function of the working directory: .prepare((workdir) => { execFileSync('git', ['init'], { cwd: workdir }); })",
-		found: `prepare(${JSON.stringify(step) ?? typeof step}), no step to run`,
-		read: "docs/guides/cli-specs.md#prepare-what-no-fixture-can-carry",
-		why: "A step is run over the working directory once the fixtures are laid; only a function can be run."
-	}));
 }
-/** Armed after `.fixture()` and `.link()`: a step shapes the tree they laid, never the reverse. */
-const prepare = defineCapability({
-	arm: async (prepared, { steps }, { workDir }) => {
-		if (workDir !== null) await steps.run(prepared, workDir);
-		return {};
-	},
-	initial: [],
-	name: "prepare",
-	phase: 26,
-	reduce: (steps, [step]) => [...steps, requireStep(step)],
-	row: {
-		group: "Setup",
-		name: ".prepare()",
-		probe: ".prepare("
-	}
-});
-//#endregion
-//#region src/stubs/delivery/other-process/stub-backend.adapter.ts
-/** Each chain's stubs replace the previous chain's, even when it declares none; a runner without a backend refuses `.intercept()`. */
-function stubBackend(backend, specification) {
+function openDeployed(options) {
+	const config = {
+		baseUrl: options.url,
+		ca: options.ca,
+		insecure: options.insecure ?? false,
+		recording: {
+			bodyKeptAbsent: true,
+			headers: options.recordedHeaders ?? DEFAULT_RECORDED_HEADERS
+		},
+		timeout: options.timeout ?? DEFAULT_TIMEOUT_MS$1
+	};
 	return {
-		accepts: () => {
-			if (backend === void 0) {
-				const lesson = {
-					fix: `add \`backend\` to the specification options: specification.${specification}(${specification === "cli" ? "bin, " : ""}{ ..., backend: { env: 'API_URL' } })`,
-					found: ".intercept(), and this runner has no declared backend",
-					why: "A site, an app or a binary is served its stubs by a declared stub backend, the URL it reads in place of its API."
-				};
-				throw new Error(refusal$1(specification === "mobile" ? {
-					...lesson,
-					read: "docs/guides/mobile-specs.md#declared-backend"
-				} : specification === "cli" ? {
-					...lesson,
-					read: "docs/guides/cli-specs.md#declared-backend"
-				} : {
-					...lesson,
-					read: "docs/guides/website-specs.md#declared-backend"
-				}));
-			}
+		api: refusingInProcessSetups(apiDeployedDefinition.open(config)),
+		cleanup: async () => {}
+	};
+}
+async function startApi(options) {
+	const callerDir = getCallerDir();
+	await registerMatchers();
+	refuseOptions$1(options);
+	if (options.server === void 0) return openDeployed(options);
+	return await startServed(options, callerDir);
+}
+async function startServed(options, callerDir) {
+	const root = resolveRoot(options.root, callerDir);
+	const services = declaredServices(options.services);
+	const databaseKeys = declaredDatabaseKeys(services);
+	const { database, databases, stop } = await startServices(services, root);
+	const server = new HonoAdapter(options.server(services));
+	const config = {
+		database,
+		databaseKeys,
+		databases,
+		server
+	};
+	return {
+		api: apiDefinition.open(config),
+		cleanup: async () => {
+			const ledgers = await routesLedger();
+			if (ledgers !== void 0) writeLedger(ledgers, {
+				declared: server.declared(),
+				reached: server.reached
+			});
+			await stop();
 		},
-		arm: async (stubs) => {
-			if (backend === void 0) return {};
-			backend.beginChain(stubs);
-			return { violation: () => backend.violation() };
-		}
+		docker: createDockerReader(callerDir)
 	};
 }
 //#endregion
-//#region src/chain/paths/scratch.ts
-/** Removed after the test's `afterEach`; outside a test or under `test.concurrent` it lives until the run's root is removed. */
-function scratchDirectory(prefix) {
-	const directory = mkdtempSync(resolve(tmpdir(), prefix));
-	const current = TestRunner.getCurrentTest();
-	if (current === void 0 || current.concurrent === true) return directory;
-	onTestFinished(() => {
-		rmSync(directory, {
-			force: true,
-			recursive: true
+//#region src/stubs/delivery/other-process/stub-backend.ts
+const CORS_METHODS = "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS";
+const PREFLIGHT_MAX_AGE = "600";
+/** A request matching no stub gets 501 and is recorded; once the chain declared a stub, the action throws naming every unmatched request. Every response carries permissive CORS headers. */
+var StubBackend = class {
+	guarded = false;
+	options;
+	queue = new StubQueue([]);
+	received = [];
+	server = null;
+	unmatchedRequests = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.options = options;
+	}
+	async start() {
+		const server = createServer((request, response) => {
+			this.handle(request, response);
+		});
+		this.server = server;
+		return `http://127.0.0.1:${await listenedPort(server, {
+			host: "127.0.0.1",
+			port: this.options.port ?? 0
+		})}`;
+	}
+	async stop() {
+		const { server } = this;
+		if (!server) return;
+		this.server = null;
+		server.closeAllConnections();
+		await new Promise((resolve) => {
+			server.close(() => {
+				resolve();
+			});
+		});
+	}
+	/** The chain's stubs replace the previous chain's wholesale; the queue and the unmatched log restart. */
+	beginChain(stubs) {
+		this.guarded = stubs.length > 0;
+		this.queue = new StubQueue(stubs);
+		this.unmatchedRequests.clear();
+		this.received.length = 0;
+	}
+	/** Every request the backend was sent since the chain began, in arrival order, matched or not: what a binary SENT, to compare whole. A preflight is no request of the program's. */
+	requests() {
+		return this.received.map((request) => ({
+			...request,
+			headers: { ...request.headers }
+		}));
+	}
+	/** Non-null when the chain declared a stub and a request went unmatched, a never stub was reached, or a `required` stub was never met. */
+	violation() {
+		if (!this.guarded) return null;
+		if (this.unmatchedRequests.size === 0) return this.queue.verdict();
+		const unmatched = [...this.unmatchedRequests.values()].map((entry) => `  - ${entry.method} ${entry.path}${entry.count > 1 ? ` (${entry.count} times)` : ""}`).join("\n");
+		const declared = this.queue.declaredRoutes().map((route) => `  - ${route}`).join("\n");
+		const strict = new Error(refusal$1("network-strict-after-first-stub", {
+			fix: "add a stub for each to the chain's composite",
+			found: `unmatched request(s) hit the declared backend during the chain:\n${unmatched}\ndeclared stubs:\n${declared}`
+		}));
+		return this.queue.verdict(strict);
+	}
+	async handle(request, response) {
+		const method = (request.method ?? "GET").toUpperCase();
+		const cors = corsHeaders(request);
+		if (method === "OPTIONS") {
+			response.writeHead(204, cors);
+			response.end();
+			return;
+		}
+		const url = request.url ?? "/";
+		const observed = {
+			body: await readBody(request),
+			headers: stringHeaders(request),
+			method,
+			url
+		};
+		this.received.push(observed);
+		const stub = this.queue.take(observed);
+		if (!stub) {
+			this.record(method, url);
+			const error = refusedReply(unmatchedSummary(method, url));
+			response.writeHead(501, {
+				...cors,
+				"content-type": "application/json"
+			});
+			response.end(JSON.stringify({
+				declared: this.queue.declaredRoutes(),
+				error
+			}));
+			return;
+		}
+		const reply = await replyOf(stub.response, observed);
+		if (reply.transport === "network-error") {
+			request.socket.destroy();
+			return;
+		}
+		await writeReply(response, reply, cors);
+	}
+	record(method, path) {
+		const key = `${method} ${path}`;
+		const existing = this.unmatchedRequests.get(key);
+		if (existing) existing.count += 1;
+		else this.unmatchedRequests.set(key, {
+			count: 1,
+			method,
+			path
+		});
+	}
+};
+function stringHeaders(request) {
+	return Object.fromEntries(Object.entries(request.headers).filter((entry) => typeof entry[1] === "string"));
+}
+async function writeReply(response, reply, cors) {
+	const status = reply.status ?? 200;
+	const { body } = reply;
+	if (isStreamBody(body)) {
+		response.writeHead(status, {
+			...cors,
+			"content-type": body.contentType,
+			...reply.headers
+		});
+		await toReadableStream(body).pipeTo(new WritableStream({
+			close() {
+				response.end();
+			},
+			write(chunk) {
+				response.write(chunk);
+			}
+		}));
+		return;
+	}
+	if (body === null || body === void 0) {
+		response.writeHead(status, {
+			...cors,
+			...reply.headers
 		});
+		response.end();
+		return;
+	}
+	const contentType = typeof body === "string" ? "text/plain; charset=utf-8" : "application/json";
+	response.writeHead(status, {
+		...cors,
+		"content-type": contentType,
+		...reply.headers
 	});
-	return directory;
+	response.end(typeof body === "string" ? body : JSON.stringify(body));
+}
+async function readBody(request) {
+	const chunks = [];
+	for await (const chunk of request) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+	return requestBody(Buffer.concat(chunks).toString("utf8"));
+}
+function corsHeaders(request) {
+	return {
+		"access-control-allow-headers": request.headers["access-control-request-headers"] ?? "*",
+		"access-control-allow-methods": CORS_METHODS,
+		"access-control-allow-origin": "*",
+		"access-control-max-age": PREFLIGHT_MAX_AGE
+	};
 }
 //#endregion
-//#region src/specifications/cli/process/env.capability.ts
-/** Chained calls merge, a later one winning; nothing to arm. */
-const env = defineCapability({
-	context: "env",
-	initial: {},
-	name: "env",
-	phase: 0,
-	reduce: (merged, [added]) => ({
-		...merged,
-		...added
-	}),
+//#region src/disk/fixture.capability.ts
+/** Judged when stated, resolved on disk when armed; a later fixture overwrites an earlier one. */
+const fixture = defineCapability({
+	arm: (targets, { workdir }, { testDir, workDir }) => {
+		if (workDir !== null) for (const target of targets) workdir.layer(target.path, testDir, workDir);
+		return {};
+	},
+	initial: [],
+	name: "fixture",
+	phase: 20,
+	reduce: (targets, [source]) => [...targets, requireDiskTarget("fixture", source)],
 	row: {
 		group: "Setup",
-		name: ".env()",
-		probe: ".env("
+		name: ".fixture()",
+		probe: ".fixture("
 	}
 });
-/** The resolved directory, never the raw temp path: on macOS `/var/folders/...` would never match `{{workdir}}`'s `/private/var/folders/...`. */
-function expandWorkdir(variables, workdir) {
-	const expanded = {};
-	for (const [key, value] of Object.entries(variables)) expanded[key] = typeof value === "string" ? value.replaceAll("$WORKDIR", workdir) : value;
-	return expanded;
-}
-function onlyOf(handles) {
-	const [only, ...others] = handles;
-	return others.length === 0 ? only : void 0;
-}
-function serviceEnv(services) {
-	const injected = {};
-	const sql = [];
-	const redis = [];
-	for (const [key, handle] of Object.entries(services ?? {})) {
-		injected[`${toConstantCase(key)}_URL`] = handle.connectionString;
-		if (handle.createDatabaseAdapter() !== null) sql.push(handle);
-		if (handle.type === "redis") redis.push(handle);
-	}
-	const onlySql = onlyOf(sql);
-	if (onlySql !== void 0) injected.DATABASE_URL = onlySql.connectionString;
-	const onlyRedis = onlyOf(redis);
-	if (onlyRedis !== void 0) injected.REDIS_URL = onlyRedis.connectionString;
-	return injected;
-}
-/** Merge order: `defaults`, services' URLs, docker run id, then the chain's `.env()`; `undefined` when nothing is set. */
-function childEnv(config, chained, workdir) {
-	const declared = config.defaultEnv;
-	const services = config.services === void 0 || Object.keys(config.services).length === 0 ? void 0 : serviceEnv(config.services);
-	let merged = declared ? {
-		...expandWorkdir(declared, workdir),
-		...services
-	} : services;
-	const { dockerConfig, dockerTestRunId } = config;
-	if (dockerConfig && dockerTestRunId !== void 0 && dockerTestRunId !== "") merged = {
-		...merged,
-		[dockerConfig.envVar]: dockerTestRunId
-	};
-	if (Object.keys(chained).length > 0) merged = {
-		...merged,
-		...expandWorkdir(chained, workdir)
+//#endregion
+//#region src/disk/fs-fixtures.adapter.ts
+function copyPlan(path, specDir, workDir) {
+	const src = resolveSpecPath("fixture", path, specDir);
+	if (!existsSync(src)) throw new Error(refusal$1("disk-named-by-relative-path-at-runtime", {
+		fix: `create ${src}, or correct the path`,
+		found: `fixture: ${JSON.stringify(path)} names nothing: ${src} does not exist`
+	}));
+	const spread = path.endsWith("/");
+	const isDirectory = statSync(src).isDirectory();
+	if (isDirectory !== spread) throw new TypeError(refusal$1("disk-named-by-relative-path-at-runtime", isDirectory ? {
+		fix: `end its path in /: directory('${path}/'), whose contents are spread into the working directory`,
+		found: `fixture: ${JSON.stringify(path)} names a directory`
+	} : {
+		fix: `drop the /: file('${path.replace(/\/+$/u, "")}')`,
+		found: `fixture: ${JSON.stringify(path)} names a file`
+	}));
+	return {
+		dest: spread ? workDir : resolve(workDir, basename(src)),
+		src
 	};
-	return merged;
 }
+const fsFixtures = { layer: (path, testDir, workDir) => {
+	const { dest, src } = copyPlan(path, testDir, workDir);
+	cpSync(src, dest, { recursive: true });
+} };
 //#endregion
-//#region lint/kit/project/spec-update.ts
-function keyOf(pair) {
-	return String(isScalar(pair.key) ? pair.key.value : pair.key);
-}
-function setOrdered(map, key, value, order) {
-	const later = new Set(order.slice(order.indexOf(key) + 1));
-	const at = map.items.findIndex((pair) => later.has(keyOf(pair)));
-	const isNew = !map.has(key);
-	map.set(key, value);
-	if (isNew && at !== -1) map.items.splice(at, 0, ...map.items.splice(-1));
-}
-/** The YAML document is edited, not re-emitted, so everything but exit codes and streams comes back byte-identical. */
-function updateSpecFile(file, updates) {
-	const root = file.source.document.contents;
-	const runs = isMap(root) ? root.get("runs", true) : void 0;
-	if (!isSeq(runs)) return renderYamlSource(file.source);
-	for (const [index, update] of updates.entries()) {
-		const run = runs.items[index];
-		if (!isMap(run)) continue;
-		setOrdered(run, "exit", update.exitCode, RUN_KEYS);
-		for (const [key, text] of [["stdout", update.stdout], ["stderr", update.stderr]]) {
-			if (text.length === 0) {
-				run.delete(key);
-				continue;
-			}
-			setOrdered(run, key, blockScalar(text), RUN_KEYS);
-		}
+//#region src/disk/installed-package.ts
+/** The directory of the package `name`, found as Node finds it from `from`: in the nearest `node_modules` holding it. */
+function installedPackage(name, testDir) {
+	let dir = testDir;
+	for (;;) {
+		const candidate = resolve(dir, "node_modules", name);
+		if (existsSync(candidate) && statSync(candidate).isDirectory()) return candidate;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
 	}
-	return renderYamlSource(file.source);
 }
 //#endregion
-//#region src/specifications/cli/documents/literate-env.ts
-/** Every child gets `TEST_WORKDIR`, the resolved working directory, with the fixtures already on disk; the document's own env wins. */
-async function startServers(document, config, displayPath, workdir) {
-	const registry = config.serveRegistry ?? {};
-	const started = [];
-	const env = {};
-	const stop = async () => {
-		for (const adapter of started.toReversed()) await adapter.stop();
-	};
-	for (const entry of document.serve) {
-		const registration = registry[entry.name];
-		if (!registration) {
-			await stop();
-			const known = Object.keys(registry);
-			throw new Error(refusal$1({
-				fix: known.length === 0 ? "register it in the `serve` option of specification.cli()" : `serve a registered server: ${known.join(", ")}`,
-				found: `${displayPath}:${entry.line}: serve: "${entry.name}" is not registered`,
-				read: "docs/guides/cli-specs.md#registration-once-per-app",
-				why: "A document serves what the app registered once, in the options of specification.cli()."
-			}));
-		}
-		const adapter = new ServedProcess({
-			command: registration.command,
-			ready: registration.ready
-		}, config.root ?? process.cwd(), "cli", {
-			TEST_WORKDIR: workdir,
-			...entry.env
-		});
-		started.push(adapter);
-		try {
-			await adapter.start();
-		} catch (error) {
-			await stop();
-			throw error;
-		}
-		if (adapter.port === null) throw invariant("a served process answered its readiness without a port");
-		env[registration.env] = registration.url(adapter.port);
-	}
-	return {
-		env,
-		stop
-	};
+//#region src/disk/link-destination.ts
+/** The directory a `directory()` names for a link, refused when it names nothing or a file; `call` is the gesture as the spec wrote it. */
+function linkedDirectory(call, path, testDir) {
+	const src = resolveSpecPath("link", path, testDir);
+	if (!existsSync(src)) throw new Error(refusal$1("disk-named-by-relative-path-at-runtime", {
+		fix: `create ${src}, or correct the path`,
+		found: `${call} names nothing: ${src} does not exist`
+	}));
+	if (!statSync(src).isDirectory()) throw new Error(refusal$1("disk-named-by-relative-path-at-runtime", {
+		fix: `name the directory that holds the package's package.json: directory('${dirname(path)}/')`,
+		found: `${call} names a file`
+	}));
+	return src;
 }
-function documentEnv(document, config, displayPath) {
-	const sets = config.envSets ?? {};
-	const env = {};
-	for (const token of document.env) {
-		if (token.kind === "set") {
-			const declared = sets[token.name];
-			if (!declared) {
-				const known = Object.keys(sets);
-				throw new Error(refusal$1({
-					fix: known.length === 0 ? "register it in the `env` option of specification.cli(), or write it inline: KEY=value" : `name a registered set: ${known.join(", ")}, or write it inline: KEY=value`,
-					found: `${displayPath}:${token.line}: env: "${token.name}" is not a registered env set`,
-					read: "docs/guides/cli-specs.md#registration-once-per-app",
-					why: "A bare word under `env:` names a set the app registered once, in the options of specification.cli()."
-				}));
-			}
-			Object.assign(env, declared);
-			continue;
-		}
-		env[token.key] = token.value;
+/** Refuses a destination under the working directory whose path crosses a file or a symlink: through a symlinked folder, the delete before the lay would reach a real install outside it. */
+function refuseUnusableAncestor(name, workDir, dest) {
+	let ancestor = workDir;
+	for (const segment of relative(workDir, dirname(dest)).split(/[\\/]/u)) {
+		ancestor = resolve(ancestor, segment);
+		if (!existsSync(ancestor)) return;
+		const entry = lstatSync(ancestor);
+		if (!entry.isSymbolicLink() && !entry.isDirectory()) throw new Error(refusal$1({
+			fix: `drop the file at ${ancestor} from the fixture or the command that lays it, so the link can lay its folder there`,
+			found: `link('${name}'): ${ancestor} is a file, not a folder`,
+			read: "docs/guides/cli-specs.md#link-a-package-the-working-directory-resolves",
+			why: "A link is laid at node_modules/<name> inside the working directory, and a file on that path leaves it no folder to lay it in."
+		}));
+		if (entry.isSymbolicLink()) throw new Error(refusal$1({
+			fix: `drop the symlink at ${ancestor} from the fixture or the command that lays it, so the working directory holds its own node_modules`,
+			found: `link('${name}'): ${ancestor} is a symlink, so the link would replace ${name} wherever it points`,
+			read: "docs/guides/cli-specs.md#link-a-package-the-working-directory-resolves",
+			why: "A link is laid inside the working directory only; through a symlinked folder it would delete a real install outside it."
+		}));
 	}
-	return env;
 }
 //#endregion
-//#region src/specifications/cli/documents/literate-judge.ts
-/** ANSI stripped (`no-transform-duplicating-tokens`) and `transform` applied, nothing else: a block scalar states its own final newline. */
-function comparable(raw, transform) {
-	const stripped = stripAnsiCodes(raw);
-	return transform ? transform(stripped) : stripped;
-}
-function tokenAwareEquals(scope) {
-	return (expected, actual) => textEquals(expected, actual, new CaptureScope(scope.workdir));
-}
-function resolveUnderWorkDir(path, context) {
-	const { workDir } = context;
-	const target = resolve(workDir, path);
-	const inside = relative(workDir, target);
-	if (isAbsolute(path) || inside.startsWith("..") || isAbsolute(inside)) throw new Error(refusal$1({
-		fix: "name a relative path under the working directory",
-		found: `${context.displayPath}: files: "${path}" leaves the working directory`,
-		read: "docs/guides/spec-documents.md#files-what-the-run-left-behind",
-		why: "A `files:` key is a relative path under the working directory."
-	}));
-	return target;
+//#region src/disk/package-manifest.ts
+function keysOf(value) {
+	return isRecord(value) ? Object.keys(value) : [];
 }
-function preview(text) {
-	return JSON.stringify(text.length > 160 ? `${text.slice(0, 160)}...` : text);
+const SCOPE = /^@[^/]+\//u;
+function binOf$1(name, bin) {
+	if (typeof bin === "string") return typeof name === "string" ? { [name.replace(SCOPE, "")]: bin } : {};
+	return Object.fromEntries(Object.entries(isRecord(bin) ? bin : {}).filter((entry) => typeof entry[1] === "string"));
 }
-function readIfPresent(path) {
+function parsedManifest(directory) {
+	const path = join(directory, "package.json");
 	try {
-		return statSync(path).isFile() ? readFileSync(path, "utf8") : null;
-	} catch {
-		return null;
+		return JSON.parse(readFileSync(path).toString());
+	} catch (error) {
+		throw new Error(refusal$1({
+			fix: `correct ${path}, so npm and Node read the package it describes`,
+			found: `packed(): ${path} is no JSON: ${error instanceof Error ? error.message : String(error)}`,
+			read: "docs/guides/cli-specs.md#a-package-specified-from-its-artefact",
+			why: "packed() reads the name, the bin and the runtime closure the package declares in its package.json."
+		}), { cause: error });
 	}
 }
-function checkFile(assertion, context) {
-	const { scope } = context;
-	const target = resolveUnderWorkDir(assertion.path, context);
-	let exists;
-	try {
-		exists = statSync(target) !== void 0;
-	} catch {
-		exists = false;
-	}
-	if (assertion.kind === "absent") return exists ? `${assertion.path}: expected absent, got a file` : null;
-	if (!exists) return `${assertion.path}: expected to exist, got nothing at that path`;
-	if (assertion.kind === "exists") return null;
-	const content = readIfPresent(target);
-	if (content === null) return `${assertion.path}: expected a readable file, got a directory`;
-	for (const needle of assertion.contains) if (!textContains(needle.text, content, scope)) return `${assertion.path}: expected to contain ${preview(needle.text)}, got ${preview(content)}`;
-	if (assertion.equals !== null && !textEquals(assertion.equals.text, content, scope)) return `${assertion.path}: expected ${preview(assertion.equals.text)}, got ${preview(content)}`;
-	return null;
+/** What `packed()` reads of a package's manifest: its name, the commands its `bin` lays, and what it requires at runtime; a manifest that is no JSON is refused. */
+function manifestAt(directory) {
+	const parsed = parsedManifest(directory);
+	const field = (key) => isRecord(parsed) ? parsed[key] : void 0;
+	const name = field("name");
+	const meta = field("peerDependenciesMeta");
+	const optional = (peer) => isRecord(meta) && isRecord(meta[peer]) && meta[peer].optional === true;
+	return {
+		bin: binOf$1(name, field("bin")),
+		name: typeof name === "string" ? name : void 0,
+		runtime: [
+			...keysOf(field("dependencies")),
+			...keysOf(field("optionalDependencies")),
+			...keysOf(field("peerDependencies")).filter((peer) => !optional(peer))
+		]
+	};
 }
-function failure(run, context, details) {
-	return atLine(new Error(refusal$1({
-		fix: "correct the command, or run with TEST_UPDATE=1 to rewrite the runs: the exit code and the streams, and nothing else",
-		found: [
-			`spec mismatch: ${context.document.description}`,
-			"",
-			`$ ${run.command}`,
-			"",
-			details.join("\n\n"),
-			"",
-			`${context.displayPath}:${run.commandLine}`
-		].join("\n"),
-		read: "docs/guides/spec-documents.md#failure-and-update",
-		why: "A spec document states what its runs produce: the exit code and the streams, whole."
-	})), context.filePath, run.commandLine);
+//#endregion
+//#region src/disk/npm-packed.adapter.ts
+function projectOf(testDir) {
+	for (let directory = testDir;; directory = dirname(directory)) {
+		if (existsSync(join(directory, "package.json"))) return directory;
+		if (dirname(directory) === directory) throw new Error(refusal$1({
+			fix: "run the spec inside the package it specifies, or name the package: packed(directory('./<path>/'))",
+			found: `packed(): no package.json from ${testDir} up`,
+			read: "docs/guides/cli-specs.md#a-package-specified-from-its-artefact",
+			why: "packed() packs the project the spec belongs to, which its nearest package.json names."
+		}));
+	}
 }
-function atLine(error, filePath, line) {
-	error.stack = `${error.name}: ${error.message}\n    at ${filePath}:${line}:1`;
-	return error;
+function packageDirectory(name, path, testDir) {
+	const call = `link('${name}', packed(directory(${JSON.stringify(path)})))`;
+	const directory = linkedDirectory(call, path, testDir);
+	if (!existsSync(join(directory, "package.json"))) throw new Error(refusal$1({
+		fix: `name the directory that holds the package's package.json, or give ${directory} one`,
+		found: `${call}: ${directory} holds no package.json`,
+		read: "docs/guides/cli-specs.md#a-package-specified-from-its-artefact",
+		why: "packed() packs a package, and a package is the directory its package.json describes."
+	}));
+	return directory;
 }
-function assertRun(outcome, context) {
-	const { actual, run } = outcome;
-	const { scope } = context;
-	if (actual.exitCode !== run.exitCode) throw failure(run, context, [[
-		"exit code mismatch",
-		`  expected: ${run.exitCode}`,
-		`  received: ${actual.exitCode}`,
-		...outcome.stderr.length > 0 ? [
-			"",
-			"stderr was:",
-			outcome.stderr.replace(/\n$/u, "")
-		] : []
-	].join("\n")]);
-	const equals = tokenAwareEquals(scope);
-	const details = [];
-	for (const [name, expected, received] of [[
-		"stdout",
-		run.stdout?.text ?? "",
-		outcome.stdout
-	], [
-		"stderr",
-		run.stderr?.text ?? "",
-		outcome.stderr
-	]]) if (!textEquals(expected, received, scope)) details.push(formatStdoutDiff(name, expected, received, { equals }));
-	details.push(...filesDetail(outcome, context));
-	if (details.length > 0) throw failure(run, context, details);
+const UNPACKED = /* @__PURE__ */ new Map();
+function unpackedOf(packageRoot) {
+	const known = UNPACKED.get(packageRoot);
+	if (known !== void 0) return known;
+	const into = mkdtempSync(join(tmpdir(), "jterrazz-packed-"));
+	process.once("exit", () => {
+		rmSync(into, {
+			force: true,
+			recursive: true
+		});
+	});
+	const filename = packInto(packageRoot, into);
+	execFileSync("tar", [
+		"-xzf",
+		join(into, filename),
+		"-C",
+		into
+	]);
+	const unpacked = join(into, "package");
+	UNPACKED.set(packageRoot, unpacked);
+	return unpacked;
 }
-function filesDetail({ run }, context) {
-	const fileFailures = run.files.map((assertion) => checkFile(assertion, context)).filter((line) => line !== null);
-	return fileFailures.length === 0 ? [] : [[
-		"files mismatch",
-		"",
-		...fileFailures.map((line) => `  ${line}`)
-	].join("\n")];
+function packInto(packageRoot, into) {
+	const packing = spawnSync("npm", [
+		"pack",
+		"--ignore-scripts",
+		"--silent",
+		"--pack-destination",
+		into
+	], {
+		cwd: packageRoot,
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	if (packing.status !== 0) throw new Error(refusal$1({
+		fix: `run \`npm pack\` in ${packageRoot} and settle what npm says, so the package packs as it would be published`,
+		found: `packed(): \`npm pack\` failed in ${packageRoot}${packing.error === void 0 ? "" : ` (${packing.error.message})`}:\n${packing.stderr.trim()}`,
+		read: "docs/guides/cli-specs.md#a-package-specified-from-its-artefact",
+		why: "packed() lays the tarball npm writes for the package, so a package npm cannot pack gives it nothing to lay."
+	}));
+	return packing.stdout.trim().split("\n").at(-1) ?? "";
 }
-/** The `files:` of a run, judged alone: update mode rewrites a run's exit code and streams, never what the run was asked to leave on disk. */
-function assertFiles(outcome, context) {
-	const details = filesDetail(outcome, context);
-	if (details.length > 0) throw failure(outcome.run, context, details);
+function linkInto(workDir, name, source) {
+	const destination = join(workDir, "node_modules", name);
+	if (existsSync(destination)) return;
+	mkdirSync(dirname(destination), { recursive: true });
+	symlinkSync(source, destination, "dir");
 }
-/** Placeholders of the previous golden preserved by pattern (`no-volatile-literal`); an emptied stream loses its key. */
-function updates(outcomes, scope) {
-	return outcomes.map(({ actual, run, stderr, stdout }) => ({
-		exitCode: actual.exitCode,
-		stderr: mergeTextPreservingPlaceholders(run.stderr?.text ?? null, stderr, scope),
-		stdout: mergeTextPreservingPlaceholders(run.stdout?.text ?? null, stdout, scope)
+function requiredPackages(name, runtime, { packageRoot, testDir }) {
+	return runtime.map((dependency) => {
+		const installed = installedPackage(dependency, packageRoot);
+		if (installed === null) throw new Error(refusal$1({
+			fix: `install ${dependency} where ${name} is developed, as its consumers' install would`,
+			found: `link('${name}', packed()): ${name} requires ${dependency}, which no node_modules above ${relative(testDir, packageRoot) || "."} holds`,
+			read: "docs/guides/cli-specs.md#a-package-specified-from-its-artefact",
+			why: "The packed package is laid beside what its manifest requires at runtime, taken from where it is developed."
+		}));
+		return {
+			dependency,
+			installed
+		};
+	});
+}
+/** Lays the packed package at `node_modules/<name>` as a copy, beside a link to each package its manifest requires at runtime, resolved from where the package is developed. */
+function installPacked(name, path, testDir, workDir) {
+	const packageRoot = path === null ? projectOf(testDir) : packageDirectory(name, path, testDir);
+	const declared = manifestAt(packageRoot);
+	if (declared.name !== name) throw new Error(refusal$1({
+		fix: `link it under the name its package.json declares: link('${declared.name ?? "<no name>"}', packed(...))`,
+		found: `link('${name}', packed()) packs ${relative(testDir, packageRoot) || "."}, whose package.json names ${declared.name ?? "no package"}`,
+		read: "docs/guides/cli-specs.md#a-package-specified-from-its-artefact",
+		why: "A consumer imports a package by the name it is published under, so the install lays it there."
 	}));
+	const modules = join(workDir, "node_modules");
+	const destination = join(modules, name);
+	for (const written of [
+		destination,
+		...declared.runtime.map((dependency) => join(modules, dependency)),
+		...Object.keys(declared.bin).map((command) => join(modules, ".bin", command))
+	]) refuseUnusableAncestor(name, workDir, written);
+	const required = requiredPackages(name, declared.runtime, {
+		packageRoot,
+		testDir
+	});
+	const unpacked = unpackedOf(packageRoot);
+	rmSync(destination, {
+		force: true,
+		recursive: true
+	});
+	mkdirSync(dirname(destination), { recursive: true });
+	cpSync(unpacked, destination, { recursive: true });
+	const manifest = manifestAt(unpacked);
+	for (const { dependency, installed } of required) linkInto(workDir, dependency, installed);
+	mkdirSync(join(modules, ".bin"), { recursive: true });
+	for (const [command, target] of Object.entries(manifest.bin)) {
+		const link = join(modules, ".bin", command);
+		rmSync(link, { force: true });
+		symlinkSync(relative(join(modules, ".bin"), join(destination, target)), link);
+	}
 }
 //#endregion
-//#region src/specifications/cli/documents/literate.ts
-function readDocument(filePath, displayPath) {
-	try {
-		return readSpecFile(readFileSync(filePath, "utf8"), displayPath);
-	} catch (error) {
-		throw error instanceof SpecSyntaxError ? atLine(grammarRefusal(error, displayPath), filePath, error.line) : error;
+//#region src/disk/fs-links.adapter.ts
+function sourceOf(name, path, testDir) {
+	if (path === null) {
+		const installed = installedPackage(name, testDir);
+		if (installed === null) throw new Error(refusal$1({
+			fix: `install ${name} in the project the spec belongs to, or name the package's directory: link('${name}', directory('./__fixtures__/<package>/'))`,
+			found: `link('${name}'): no node_modules from ${testDir} up holds ${name}`,
+			read: "docs/guides/cli-specs.md#link-a-package-the-working-directory-resolves",
+			why: "A bare name links the package the spec's own project resolves, found as Node finds it."
+		}));
+		return installed;
 	}
+	return linkedDirectory(`link('${name}', directory(${JSON.stringify(path)}))`, path, testDir);
 }
-async function execute(run, session) {
-	const { command, env, transform, workDir } = session;
-	const timeout = run.timeout ?? void 0;
-	const actual = run.waitFor === null ? await command.exec(run.command, workDir, env, {
-		stdin: run.stdin ?? void 0,
-		timeout
-	}) : await command.watch(run.command, workDir, {
-		timeout,
-		waitFor: run.waitFor
-	}, env);
-	return {
-		actual,
-		run,
-		stderr: comparable(actual.stderr, transform),
-		stdout: comparable(actual.stdout, transform)
-	};
-}
-function lastResult(outcomes, options) {
-	const { config, testDir, workDir } = options;
-	const lastOutcome = outcomes.at(-1);
-	if (lastOutcome === void 0) throw invariant("a document ran no command, though its runs: holds at least one");
-	return new CliResult({
-		commandOutput: lastOutcome.actual,
-		config,
-		dockerConfig: config.dockerConfig,
-		testDir,
-		testRunId: config.dockerTestRunId,
-		transform: config.transform,
-		workDir
+const fsLinks = {
+	packed: installPacked,
+	link: (name, path, testDir, workDir) => {
+		const src = sourceOf(name, path, testDir);
+		const dest = resolve(workDir, "node_modules", name);
+		refuseUnusableAncestor(name, workDir, dest);
+		mkdirSync(dirname(dest), { recursive: true });
+		rmSync(dest, {
+			force: true,
+			recursive: true
+		});
+		symlinkSync(src, dest, "dir");
+	}
+};
+//#endregion
+//#region src/disk/in-process-steps.adapter.ts
+/** A step is the test's own code: it runs in the test's process, one after the other. */
+const inProcessSteps = { run: async (steps, workDir) => {
+	for (const step of steps) await step(workDir);
+} };
+//#endregion
+//#region src/disk/packed.ts
+const PACKED = Symbol.for("@jterrazz/test:packed");
+/** Name the package a consumer installs: the project the spec belongs to, or the package a directory holds, packed as `npm pack` packs it. */
+function packed(source) {
+	return Object.freeze({
+		[PACKED]: true,
+		path: isDiskDirectory(source) ? source.path : null
 	});
 }
-/** Resolves with the last run's result. Under `TEST_UPDATE=1` every run executes and is rewritten; its `files:` are still judged. */
-async function runSpecDocument(options) {
-	const { config, displayPath, filePath, workDir } = options;
-	const { command } = config;
-	if (!command) throw invariant(".run() reached a chain with no command adapter");
-	const file = readDocument(filePath, displayPath);
-	const { document } = file;
-	const fileDir = filePath.replace(/[/\\][^/\\]*$/u, "");
-	for (const fixture of document.fixtures) fsFixtures.layer(fixture.path, fileDir, workDir);
-	const workdir = safeRealpath(workDir);
-	const servers = await startServers(document, config, displayPath, workdir);
-	const scope = new CaptureScope(workdir);
-	const env = expandWorkdir({
-		...options.baseEnv,
-		...servers.env,
-		...documentEnv(document, config, displayPath)
-	}, workdir);
-	const judgement = {
-		displayPath,
-		document,
-		filePath,
-		scope,
-		workDir
-	};
-	const session = {
-		command,
-		env,
-		transform: config.transform,
-		workDir
-	};
-	const rewriting = shouldUpdateSnapshots() && options.frozen !== true;
-	const outcomes = [];
-	try {
-		for (const run of document.runs) {
-			const outcome = await execute(run, session);
-			outcomes.push(outcome);
-			if (rewriting) assertFiles(outcome, judgement);
-			else assertRun(outcome, judgement);
-		}
-	} finally {
-		await servers.stop();
-	}
-	if (rewriting) writeFileSync(filePath, updateSpecFile(file, updates(outcomes, scope)));
-	return lastResult(outcomes, options);
+function isPackedPackage(value) {
+	return value !== null && typeof value === "object" && Reflect.get(value, PACKED) === true;
 }
 //#endregion
-//#region src/specifications/cli/documents/run.action.ts
-/** The chain's fixture is laid first, the document's `fixture:` over it; its `env:` wins over a chained `.env()`. */
-const run$1 = defineAction({
-	accessors: CLI_RESULT_ROWS,
-	name: "run",
-	perform: async ([document, options], read, _adapters, { config, testDir, workDir }) => {
-		const cwd = workDir;
-		const filePath = resolveSpecPath("run", document.path, testDir);
-		return await runSpecDocument({
-			baseEnv: childEnv(config, read(env), safeRealpath(cwd)),
-			config,
-			displayPath: relative(process.cwd(), filePath) || document.path,
-			filePath,
-			frozen: options?.frozen,
-			testDir,
-			workDir: cwd
-		});
+//#region src/disk/link.capability.ts
+const PACKAGE_NAME = /^(?:@[a-z0-9~-][\w.~-]*\/)?[a-z0-9~-][\w.~-]*$/u;
+function requirePackageName(name, linked) {
+	if (typeof name !== "string" || !PACKAGE_NAME.test(name) || name.toLowerCase() !== name) throw new TypeError(refusal$1({
+		fix: "name it as a package.json `dependencies` key does: link('@scope/name') or link('name')",
+		found: `link(${JSON.stringify(name)}), no package name`,
+		read: "docs/guides/cli-specs.md#link-a-package-the-working-directory-resolves",
+		why: "The name is where the package lands, `node_modules/<name>`, and what the binary imports it by."
+	}));
+	if (linked.some((entry) => entry.name === name)) throw new TypeError(refusal$1({
+		fix: `link ${name} once, from the one source the binary should resolve`,
+		found: `link(${JSON.stringify(name)}), stated twice on one chain`,
+		read: "docs/guides/cli-specs.md#link-a-package-the-working-directory-resolves",
+		why: "A name resolves to one package: a second link of it would silently replace the first."
+	}));
+	return name;
+}
+function requireSource(name, source) {
+	if (source === void 0) return null;
+	if (isPackedPackage(source)) return source.path;
+	if (isDiskDirectory(source)) return source.path;
+	throw new TypeError(refusal$1("disk-named-by-relative-path-at-runtime", {
+		fix: `name the package's directory: link('${name}', directory('./__fixtures__/${name.split("/").at(-1)}/'))`,
+		found: isDiskFile(source) ? `link('${name}', file(${JSON.stringify(source.path)})), a file where a package's directory is read` : `link('${name}', ${typeof source === "string" ? JSON.stringify(source) : typeof source}), a value where a package's directory is read`
+	}));
+}
+const link$1 = defineCapability({
+	arm: (linked, { links }, { testDir, workDir }) => {
+		if (workDir !== null) for (const { name, packed, path } of linked) (packed ? links.packed : links.link)(name, path, testDir, workDir);
+		return {};
 	},
-	prepare: ([document]) => {
-		requireDiskFile("run", document, ".spec.yaml");
-		return { workDir: scratchDirectory("spec-command-") };
+	initial: [],
+	name: "link",
+	phase: 25,
+	reduce: (linked, [name, source]) => {
+		const checked = requirePackageName(name, linked);
+		return [...linked, {
+			name: checked,
+			packed: isPackedPackage(source),
+			path: requireSource(checked, source)
+		}];
 	},
 	row: {
-		group: "Terminal action",
-		name: ".run()",
-		probe: ".run("
+		group: "Setup",
+		name: ".link()",
+		probe: ".link("
 	}
 });
 //#endregion
-//#region src/specifications/cli/process/exec.action.ts
-function isLongRunning(options) {
-	return options?.waitFor !== void 0 || options?.timeout !== void 0;
-}
-function requireRelativeFolder(cwd) {
-	if (cwd === void 0) return;
-	const inside = normalize(cwd);
-	if (isAbsolute(cwd) || inside === ".." || inside.startsWith(`..${sep}`)) throw new Error(refusal$1({
-		fix: "name a folder below the working directory, relative to it: .exec('check', { cwd: 'packages/site' })",
-		found: `.exec(..., { cwd: ${JSON.stringify(cwd)} }), a folder outside the working directory`,
-		read: "docs/guides/cli-specs.md#cwd-a-folder-of-the-working-directory",
-		why: "A command runs in the working directory the chain laid, or in one of its folders: anywhere else is the machine, not the fixture."
-	}));
-}
-function runFolder(root, cwd) {
-	if (cwd === void 0) return root;
-	const folder = resolve(root, cwd);
-	if (statSync(folder, { throwIfNoEntry: false })?.isDirectory() !== true) throw new Error(refusal$1({
-		fix: "lay the folder with a fixture, or name one the fixtures laid",
-		found: `.exec(..., { cwd: ${JSON.stringify(cwd)} }), a folder the working directory does not hold`,
-		read: "docs/guides/cli-specs.md#cwd-a-folder-of-the-working-directory",
-		why: "A command runs in a folder the chain laid: one that does not exist has no files of the fixture."
+//#region src/disk/prepare.capability.ts
+function requireStep(step) {
+	if (typeof step === "function") return step;
+	throw new TypeError(refusal$1({
+		fix: "hand it a function of the working directory: .prepare((workdir) => { execFileSync('git', ['init'], { cwd: workdir }); })",
+		found: `prepare(${JSON.stringify(step) ?? typeof step}), no step to run`,
+		read: "docs/guides/cli-specs.md#prepare-what-no-fixture-can-carry",
+		why: "A step is run over the working directory once the fixtures are laid; only a function can be run."
 	}));
-	return folder;
 }
-//#endregion
-//#region src/specifications/cli/cli.composition.ts
-const composition$6 = {
-	actions: [defineAction({
-		accessors: CLI_RESULT_ROWS,
-		name: "exec",
-		perform: async ([args = "", options], read, { command }, { config, testDir, workDir }) => {
-			const root = workDir;
-			const cwd = runFolder(root, options?.cwd);
-			const env$1 = childEnv(config, read(env), safeRealpath(root));
-			let output;
-			if (isLongRunning(options)) output = await command.watch(args, cwd, options, env$1);
-			else if (Array.isArray(args)) {
-				output = {
-					exitCode: 0,
-					stderr: "",
-					stdout: ""
-				};
-				for (const one of args) {
-					output = await command.exec(one, cwd, env$1);
-					if (output.exitCode !== 0) break;
-				}
-			} else output = await command.exec(args, cwd, env$1);
-			return new CliResult({
-				commandOutput: output,
-				config,
-				dockerConfig: config.dockerConfig ?? void 0,
-				requests: config.backend?.requests(),
-				testDir,
-				testRunId: config.dockerTestRunId ?? void 0,
-				transform: config.transform,
-				workDir: root
-			});
-		},
-		prepare: ([args = "", options]) => {
-			if (Array.isArray(args) && args.length === 0) throw new Error(refusal$1({
-				fix: "name at least one command: .exec(['build', 'test'])",
-				found: ".exec([]), a sequence of no command",
-				read: "docs/guides/cli-specs.md#sequences-array-form",
-				why: "A sequence runs its commands in order, and runs at least one."
-			}));
-			if (isLongRunning(options) && Array.isArray(args)) throw new Error(refusal$1({
-				fix: "wait on one long-running command: .exec(args, { waitFor, timeout }), or drop the options",
-				found: ".exec([...], { waitFor/timeout }), options on a command sequence",
-				read: "docs/guides/cli-specs.md#long-running-processes-waitfor--timeout",
-				why: "`waitFor` and `timeout` wait on one long-running process."
-			}));
-			requireRelativeFolder(options?.cwd);
-			return { workDir: scratchDirectory("spec-command-") };
-		},
-		row: {
-			group: "Terminal action",
-			name: ".exec()",
-			probe: ".exec("
-		}
-	}), run$1],
-	capabilities: [
-		env,
-		fixture,
-		intercept,
-		link$1,
-		prepare,
-		seed,
-		sharing
-	],
-	options: {
-		backend: {
-			group: "Constructor option",
-			name: "backend",
-			probe: "backend:"
-		},
-		commands: {
-			group: "Constructor option",
-			name: "commands",
-			probe: "commands:"
-		},
-		defaults: {
-			group: "Constructor option",
-			name: "defaults",
-			probe: "defaults:"
-		},
-		docker: {
-			group: "Constructor option",
-			name: "docker",
-			probe: "docker:"
-		},
-		env: {
-			group: "Constructor option",
-			name: "env",
-			probe: "env:"
-		},
-		root: {
-			group: "Constructor option",
-			name: "root",
-			probe: "root:"
-		},
-		serve: {
-			group: "Constructor option",
-			name: "serve",
-			probe: "serve:"
-		},
-		services: {
-			group: "Constructor option",
-			name: "services",
-			probe: "services:"
-		},
-		transform: {
-			group: "Constructor option",
-			name: "transform",
-			probe: "transform:"
-		}
+/** Armed after `.fixture()` and `.link()`: a step shapes the tree they laid, never the reverse. */
+const prepare = defineCapability({
+	arm: async (prepared, { steps }, { workDir }) => {
+		if (workDir !== null) await steps.run(prepared, workDir);
+		return {};
+	},
+	initial: [],
+	name: "prepare",
+	phase: 26,
+	reduce: (steps, [step]) => [...steps, requireStep(step)],
+	row: {
+		group: "Setup",
+		name: ".prepare()",
+		probe: ".prepare("
 	}
-};
-const cliDefinition = defineSpecification()({
-	...composition$6,
-	adapters: (config) => ({
-		command: config.command,
-		databases: databaseSet(config),
-		links: fsLinks,
-		network: stubBackend(config.backend, "cli"),
-		steps: inProcessSteps,
-		workdir: fsFixtures
-	}),
-	locate: getCallerDir
 });
 //#endregion
-//#region src/specifications/cli/process/command.ts
-/** An absolute path as is; else the project's `node_modules/.bin`, then the working directory's; else the bare name. */
-function resolveCommand(command, root) {
-	return [root, process.cwd()].map((directory) => resolve(directory, "node_modules/.bin", command)).find((path) => existsSync(path)) ?? command;
-}
-//#endregion
-//#region src/specifications/cli/process/exec.adapter.ts
-const DEFAULT_WATCH_TIMEOUT = 1e4;
-const TIMED_OUT = 124;
-const COVERAGE_REPORTER = /--require="[^"]*child-coverage\.cjs"/u;
-function withCoverageReporter(extra) {
-	const stated = extra?.NODE_OPTIONS;
-	const reporter = COVERAGE_REPORTER.exec(process.env.NODE_OPTIONS ?? "")?.[0];
-	if (extra === void 0 || typeof stated !== "string" || reporter === void 0) return extra;
-	return stated.includes(reporter) ? extra : {
-		...extra,
-		NODE_OPTIONS: `${stated} ${reporter}`.trim()
-	};
-}
-/** `null` overrides delete keys (`INIT_CWD: null`); a NODE_OPTIONS a chain states keeps the mutation reporter the run asked for. */
-function buildEnv(stated) {
-	const extra = withCoverageReporter(stated);
-	const unset = new Set(Object.entries(extra ?? {}).filter(([, value]) => value === null).map(([key]) => key));
-	return Object.fromEntries(Object.entries({
-		...process.env,
-		INIT_CWD: void 0,
-		...extra
-	}).filter(([key]) => !unset.has(key)));
-}
-function terminate(child) {
-	child.kill("SIGTERM");
-	return setTimeout(() => {
-		child.kill("SIGKILL");
-	}, KILL_GRACE_MS);
-}
-/** invariant: with a pattern expected, even a clean exit is a failure; without one a clean exit is a success. */
-function exitCodeOf(code, waitFor) {
-	if (waitFor !== void 0 && code === 0) return 1;
-	return code ?? 1;
-}
-/** Resolves 0 when `waitFor` appears, the exit code when the process ends first, 124 at the timeout; the timeout timer is unref'd. */
-async function observeProcess(child, options) {
-	const { waitFor } = options;
-	return await new Promise((resolve) => {
-		const output = {
-			stderr: "",
-			stdout: ""
-		};
-		let resolved = false;
-		let exited = false;
-		let killTimer;
-		const timeoutTimer = setTimeout(() => {
-			finish(TIMED_OUT);
-		}, options.timeout ?? DEFAULT_WATCH_TIMEOUT);
-		timeoutTimer.unref();
-		function finish(exitCode) {
-			if (resolved) return;
-			resolved = true;
-			clearTimeout(timeoutTimer);
-			if (!exited) killTimer = terminate(child);
-			resolve({
-				exitCode,
-				...output
-			});
-		}
-		const collect = (stream) => (data) => {
-			output[stream] += data.toString();
-			if (waitFor !== void 0 && (output.stdout.includes(waitFor) || output.stderr.includes(waitFor))) finish(0);
-		};
-		child.stdout?.on("data", collect("stdout"));
-		child.stderr?.on("data", collect("stderr"));
-		child.on("exit", (code) => {
-			exited = true;
-			clearTimeout(killTimer);
-			finish(exitCodeOf(code, waitFor));
-		});
-	});
-}
-/** Spawned, never `spawnSync`: the test's event loop keeps running while the binary does, so a server the test started (a collector, a stub) answers it. stdout and stderr are captured whatever the exit code, and many CLIs write banners to stderr. */
-var ExecAdapter = class {
-	command;
-	constructor(command) {
-		this.command = command;
-	}
-	async exec(args, cwd, extraEnv, input) {
-		const env = buildEnv(extraEnv);
-		const child = spawn(`${this.command} ${args}`, [], {
-			cwd,
-			detached: SIGNALS_GROUPS,
-			env,
-			shell: true
-		});
-		onTestFinished(async () => {
-			await endGroup(child);
-		});
-		return await new Promise((resolve) => {
-			const output = {
-				stderr: "",
-				stdout: ""
-			};
-			let timedOut = false;
-			const timer = input?.timeout === void 0 ? void 0 : setTimeout(() => {
-				timedOut = true;
-				endGroup(child);
-			}, input.timeout);
-			child.stdout.setEncoding("utf8").on("data", (data) => {
-				output.stdout += data;
-			});
-			child.stderr.setEncoding("utf8").on("data", (data) => {
-				output.stderr += data;
-			});
-			child.on("close", (code) => {
-				clearTimeout(timer);
-				resolve({
-					exitCode: timedOut ? TIMED_OUT : code ?? 1,
-					...output
-				});
-			});
-			child.stdin.on("error", () => void 0);
-			child.stdin.end(input?.stdin);
-		});
-	}
-	async watch(args, cwd, options, extraEnv) {
-		const env = buildEnv(extraEnv);
-		const child = spawn(`${this.command} ${args}`, [], {
-			cwd,
-			detached: SIGNALS_GROUPS,
-			env,
-			shell: true,
-			stdio: [
-				"pipe",
-				"pipe",
-				"pipe"
-			]
-		});
-		const kill = (signal) => signalGroup(child, signal);
-		return await observeProcess({
-			kill,
-			on: child.on.bind(child),
-			stderr: child.stderr,
-			stdout: child.stdout
-		}, options);
-	}
-};
-//#endregion
-//#region src/specifications/cli/cli.handle.ts
-function dockerTestRunId() {
-	return `t-${Math.random().toString(36).slice(2, 10)}-${Date.now().toString(36)}`;
-}
-async function startedBackend$1(declared, defaults, started) {
-	if (declared === void 0) return {
-		backend: null,
-		defaults
-	};
-	const backend = new StubBackend({ port: declared.port });
-	try {
-		return {
-			backend,
-			defaults: {
-				[declared.env]: await backend.start(),
-				...defaults
-			}
-		};
-	} catch (error) {
-		await started?.stop();
-		throw error;
-	}
-}
-async function startCli(bin, options = {}) {
-	const callerDir = getCallerDir();
-	await registerMatchers();
-	const root = resolveRoot(options.root, callerDir);
-	const resolvedBin = resolveCommand(bin, root);
-	const services = declaredServices(options.services);
-	const databaseKeys = declaredDatabaseKeys(services);
-	if (options.docker !== void 0) requireDockerDaemon();
-	let started = null;
-	if (Object.keys(services).length > 0) started = await startServices(services, root, { type: "none" });
-	const { backend, defaults } = await startedBackend$1(options.backend, options.defaults, started);
-	const dockerTestRunIdOf = options.docker === void 0 ? void 0 : dockerTestRunId();
-	const declaredServicesOf = Object.keys(services).length > 0 ? services : void 0;
-	const config = {
-		backend: backend ?? void 0,
-		command: new ExecAdapter(resolvedBin),
-		database: started?.database,
-		databaseKeys,
-		databases: started?.databases,
-		dockerConfig: options.docker,
-		dockerTestRunId: dockerTestRunIdOf,
-		defaultEnv: defaults,
-		envSets: options.env,
-		root,
-		serveRegistry: options.serve,
-		services: declaredServicesOf,
-		transform: options.transform
-	};
+//#region src/stubs/delivery/other-process/stub-backend.adapter.ts
+/** Each chain's stubs replace the previous chain's, even when it declares none; a runner without a backend refuses `.intercept()`. */
+function stubBackend(backend, specification) {
 	return {
-		cleanup: async () => {
-			await started?.stop();
-			await backend?.stop();
-		},
-		cli: cliDefinition.open(config),
-		docker: createDockerReader(callerDir),
-		orchestrator: started?.orchestrator ?? null
+		accepts: () => {
+			if (backend === void 0) {
+				const lesson = {
+					fix: `add \`backend\` to the specification options: specification.${specification}(${specification === "cli" ? "bin, " : ""}{ ..., backend: { env: 'API_URL' } })`,
+					found: ".intercept(), and this runner has no declared backend",
+					why: "A site, an app or a binary is served its stubs by a declared stub backend, the URL it reads in place of its API."
+				};
+				throw new Error(refusal$1(specification === "mobile" ? {
+					...lesson,
+					read: "docs/guides/mobile-specs.md#declared-backend"
+				} : specification === "cli" ? {
+					...lesson,
+					read: "docs/guides/cli-specs.md#declared-backend"
+				} : {
+					...lesson,
+					read: "docs/guides/website-specs.md#declared-backend"
+				}));
+			}
+		},
+		arm: async (stubs) => {
+			if (backend === void 0) return {};
+			backend.beginChain(stubs);
+			return { violation: () => backend.violation() };
+		}
 	};
 }
 //#endregion
-//#region src/specifications/deployment/exchange/connect.capability.ts
-/** Read by the exchange, never armed: the address is where one request is sent, not a state of the world. */
-const connect$2 = defineCapability({
-	initial: null,
-	name: "connect",
+//#region src/chain/paths/scratch.ts
+/** Removed after the test's `afterEach`; outside a test or under `test.concurrent` it lives until the run's root is removed. */
+function scratchDirectory(prefix) {
+	const directory = mkdtempSync(resolve(tmpdir(), prefix));
+	const current = TestRunner.getCurrentTest();
+	if (current === void 0 || current.concurrent === true) return directory;
+	onTestFinished(() => {
+		rmSync(directory, {
+			force: true,
+			recursive: true
+		});
+	});
+	return directory;
+}
+//#endregion
+//#region src/specifications/cli/process/env.capability.ts
+/** Chained calls merge, a later one winning; nothing to arm. */
+const env = defineCapability({
+	context: "env",
+	initial: {},
+	name: "env",
 	phase: 0,
-	reduce: (_held, [address]) => address,
+	reduce: (merged, [added]) => ({
+		...merged,
+		...added
+	}),
 	row: {
 		group: "Setup",
-		name: ".connect()",
-		probe: ".connect("
+		name: ".env()",
+		probe: ".env("
 	}
 });
-//#endregion
-//#region src/specifications/deployment/exchange/exchange.result.ts
-const EXCHANGE_RESULT_ROWS = [{
-	group: "Result accessor",
-	name: ".response",
-	probe: "result.response"
-}, {
-	group: "Result accessor",
-	name: ".tls",
-	probe: "result.tls"
-}];
-/** What one exchange with a deployment hands back: the response, or why none came, and the certificate it was presented. */
-var ExchangeResult = class extends BaseResult {
-	answer;
-	recording;
-	/** The certificate an https exchange was presented and the trust check's verdict; undefined over http, or when no handshake completed. */
-	tls;
-	constructor(options) {
-		super(options);
-		this.answer = options.response;
-		this.recording = options.recording;
-		this.tls = options.tls;
-	}
-	/** The whole response (status, headers, body), or `unreachable: <reason>`, compared whole: `toMatch(<.http text>)` or `toMatch(file(...))`. */
-	get response() {
-		return new ResponseAccessor(this.answer, this.testDir, this.captures, this.recording);
-	}
-};
-//#endregion
-//#region src/specifications/deployment/exchange/target.ts
-const SCHEME = /^[a-z][a-z\d+.-]*:\/\//iu;
-const BRACKETED = /^\[(?<host>[^\]]+)\](?::(?<port>\d+))?$/u;
-const HOST_AND_PORT = /^(?<host>[^:[\]\s]+)(?::(?<port>\d+))?$/u;
-/** The host a URL names, an IPv6 literal without its brackets. */
-function hostOf(url) {
-	return url.hostname.startsWith("[") ? url.hostname.slice(1, -1) : url.hostname;
-}
-/** The port a URL names, or its scheme's. */
-function portOf(url) {
-	if (url.port !== "") return Number(url.port);
-	return url.protocol === "https:" ? 443 : 80;
+/** The resolved directory, never the raw temp path: on macOS `/var/folders/...` would never match `{{workdir}}`'s `/private/var/folders/...`. */
+function expandWorkdir(variables, workdir) {
+	const expanded = {};
+	for (const [key, value] of Object.entries(variables)) expanded[key] = typeof value === "string" ? value.replaceAll("$WORKDIR", workdir) : value;
+	return expanded;
 }
-function refusedTarget(target, found, fix) {
-	return new Error(refusal$1({
-		fix,
-		found: `${JSON.stringify(target)}, ${found}`,
-		read: "docs/guides/deployment-specs.md#the-target",
-		why: "An exchange goes to one absolute http(s) URL: written whole, or a path from the `url` the specification names."
-	}));
+function onlyOf(handles) {
+	const [only, ...others] = handles;
+	return others.length === 0 ? only : void 0;
 }
-/** A path is read from the base URL as written, its own path kept: `https://site.test/app` and `/health` are `https://site.test/app/health`. */
-function targetUrl(target, base) {
-	if (SCHEME.test(target)) {
-		const url = new URL(target);
-		if (url.protocol !== "http:" && url.protocol !== "https:") throw refusedTarget(target, `a ${url.protocol.slice(0, -1)} URL`, "name an http:// or https:// URL");
-		return url;
+function serviceEnv(services) {
+	const injected = {};
+	const sql = [];
+	const redis = [];
+	for (const [key, handle] of Object.entries(services ?? {})) {
+		injected[`${toConstantCase(key)}_URL`] = handle.connectionString;
+		if (handle.createDatabaseAdapter() !== null) sql.push(handle);
+		if (handle.type === "redis") redis.push(handle);
 	}
-	if (!target.startsWith("/")) throw refusedTarget(target, "neither an absolute URL nor a path", "write the URL whole, `https://site.test/health`, or a path from the `url` option, `/health`");
-	if (base === void 0) throw refusedTarget(target, "a path, and the specification names no `url` to read it from", "write the URL whole, or name the base with `specification.deployment({ url })`");
-	return new URL(`${base.replace(/\/+$/u, "")}${target}`);
+	const onlySql = onlyOf(sql);
+	if (onlySql !== void 0) injected.DATABASE_URL = onlySql.connectionString;
+	const onlyRedis = onlyOf(redis);
+	if (onlyRedis !== void 0) injected.REDIS_URL = onlyRedis.connectionString;
+	return injected;
 }
-/** `host:port`, `[v6]:port`, or a bare host, which keeps the URL's port. */
-function connectAddress(written, url) {
-	const address = written.trim();
-	const match = BRACKETED.exec(address) ?? HOST_AND_PORT.exec(address);
-	const host = match?.groups?.host;
-	if (host === void 0 || address.startsWith("[") && isIP(host) !== 6) throw new Error(refusal$1({
-		fix: "write the address as `.connect('10.0.0.5:30443')`, `.connect('[fd7a::1]:443')` or `.connect('node.test')`",
-		found: `.connect(${JSON.stringify(written)}), no address`,
-		read: "docs/guides/deployment-specs.md#setup-connect",
-		why: "`.connect()` names the one address the socket opens on: a host, and a port when it is not the port of the URL."
-	}));
-	const port = match?.groups?.port;
-	return {
-		host,
-		port: port === void 0 ? portOf(url) : Number(port)
+/** Merge order: `defaults`, services' URLs, docker run id, then the chain's `.env()`; `undefined` when nothing is set. */
+function childEnv(config, chained, workdir) {
+	const declared = config.defaultEnv;
+	const services = config.services === void 0 || Object.keys(config.services).length === 0 ? void 0 : serviceEnv(config.services);
+	let merged = declared ? {
+		...expandWorkdir(declared, workdir),
+		...services
+	} : services;
+	const { dockerConfig, dockerTestRunId } = config;
+	if (dockerConfig && dockerTestRunId !== void 0 && dockerTestRunId !== "") merged = {
+		...merged,
+		[dockerConfig.envVar]: dockerTestRunId
+	};
+	if (Object.keys(chained).length > 0) merged = {
+		...merged,
+		...expandWorkdir(chained, workdir)
 	};
+	return merged;
 }
 //#endregion
-//#region src/specifications/deployment/exchange/tls-facts.ts
-const DAY_MS = 864e5;
-function firstOf(value) {
-	return Array.isArray(value) ? value[0] : value;
+//#region lint/kit/project/spec-update.ts
+function keyOf(pair) {
+	return String(isScalar(pair.key) ? pair.key.value : pair.key);
 }
-function altNamesOf(certificate) {
-	return (certificate.subjectaltname ?? "").split(",").map((name) => name.trim().slice(name.trim().indexOf(":") + 1)).filter((name) => name !== "");
+function setOrdered(map, key, value, order) {
+	const later = new Set(order.slice(order.indexOf(key) + 1));
+	const at = map.items.findIndex((pair) => later.has(keyOf(pair)));
+	const isNew = !map.has(key);
+	map.set(key, value);
+	if (isNew && at !== -1) map.items.splice(at, 0, ...map.items.splice(-1));
 }
-/** Read at the moment of the exchange, so `daysRemaining` is the margin the deployment had when it answered. */
-function tlsFacts(certificate, verdict, now) {
-	const validTo = new Date(certificate.valid_to);
-	return {
-		altNames: altNamesOf(certificate),
-		authorizationError: verdict.authorizationError,
-		authorized: verdict.authorizationError === void 0,
-		covers: (host) => checkServerIdentity(host, certificate) === void 0,
-		daysRemaining: Math.floor((validTo.getTime() - now) / DAY_MS),
-		issuer: firstOf(certificate.issuer.CN) ?? firstOf(certificate.issuer.O) ?? "",
-		protocol: verdict.protocol,
-		subject: firstOf(certificate.subject.CN) ?? "",
-		validFrom: new Date(certificate.valid_from),
-		validTo
-	};
+/** The YAML document is edited, not re-emitted, so everything but exit codes and streams comes back byte-identical. */
+function updateSpecFile(file, updates) {
+	const root = file.source.document.contents;
+	const runs = isMap(root) ? root.get("runs", true) : void 0;
+	if (!isSeq(runs)) return renderYamlSource(file.source);
+	for (const [index, update] of updates.entries()) {
+		const run = runs.items[index];
+		if (!isMap(run)) continue;
+		setOrdered(run, "exit", update.exitCode, RUN_KEYS);
+		for (const [key, text] of [["stdout", update.stdout], ["stderr", update.stderr]]) {
+			if (text.length === 0) {
+				run.delete(key);
+				continue;
+			}
+			setOrdered(run, key, blockScalar(text), RUN_KEYS);
+		}
+	}
+	return renderYamlSource(file.source);
 }
 //#endregion
-//#region src/specifications/deployment/exchange/unreachable.ts
-/** Why an exchange never answered, as the `unreachable: <reason>` line of its golden reads it. */
-const TIMEOUT = "timeout";
-const TLS = "tls";
-const REASONS = {
-	EAI_AGAIN: "dns",
-	EAI_FAIL: "dns",
-	EAI_NODATA: "dns",
-	EAI_NONAME: "dns",
-	ECONNABORTED: "reset",
-	ECONNREFUSED: "refused",
-	ECONNRESET: "reset",
-	EHOSTDOWN: "no route",
-	EHOSTUNREACH: "no route",
-	ENETDOWN: "no route",
-	ENETUNREACH: "no route",
-	ENODATA: "dns",
-	ENOTFOUND: "dns",
-	EPIPE: "reset"
-};
-/** The code node raised, when it raised one. */
-function codeOf(error) {
-	if (typeof error === "string") return error === "" ? void 0 : error;
-	const code = error !== null && typeof error === "object" ? Reflect.get(error, "code") : void 0;
-	return typeof code === "string" && code !== "" ? code : void 0;
-}
-/** `dns`, `refused`, `reset`, `no route`, or the code node raised; a handshake's own failure is `tls <CODE>`, its network's reads as the network's. */
-function unreachableReason(error, duringHandshake = false) {
-	const code = codeOf(error);
-	const reason = code === void 0 ? void 0 : REASONS[code];
-	if (reason !== void 0) return reason;
-	if (duringHandshake) return `${TLS} ${code ?? "handshake"}`;
-	return code ?? (error instanceof Error ? error.message : String(error));
+//#region src/specifications/cli/documents/literate-env.ts
+/** Every child gets `TEST_WORKDIR`, the resolved working directory, with the fixtures already on disk; the document's own env wins. */
+async function startServers(document, config, displayPath, workdir) {
+	const registry = config.serveRegistry ?? {};
+	const started = [];
+	const env = {};
+	const stop = async () => {
+		for (const adapter of started.toReversed()) await adapter.stop();
+	};
+	for (const entry of document.serve) {
+		const registration = registry[entry.name];
+		if (!registration) {
+			await stop();
+			const known = Object.keys(registry);
+			throw new Error(refusal$1({
+				fix: known.length === 0 ? "register it in the `serve` option of specification.cli()" : `serve a registered server: ${known.join(", ")}`,
+				found: `${displayPath}:${entry.line}: serve: "${entry.name}" is not registered`,
+				read: "docs/guides/cli-specs.md#registration-once-per-app",
+				why: "A document serves what the app registered once, in the options of specification.cli()."
+			}));
+		}
+		const adapter = new ServedProcess({
+			command: registration.command,
+			ready: registration.ready
+		}, config.root ?? process.cwd(), "cli", {
+			TEST_WORKDIR: workdir,
+			...entry.env
+		});
+		started.push(adapter);
+		try {
+			await adapter.start();
+		} catch (error) {
+			await stop();
+			throw error;
+		}
+		if (adapter.port === null) throw invariant("a served process answered its readiness without a port");
+		env[registration.env] = registration.url(adapter.port);
+	}
+	return {
+		env,
+		stop
+	};
 }
-/** A certificate the trust check refused, by the code it refused with. */
-function refusedCertificate(code) {
-	return `${TLS} ${code}`;
+function documentEnv(document, config, displayPath) {
+	const sets = config.envSets ?? {};
+	const env = {};
+	for (const token of document.env) {
+		if (token.kind === "set") {
+			const declared = sets[token.name];
+			if (!declared) {
+				const known = Object.keys(sets);
+				throw new Error(refusal$1({
+					fix: known.length === 0 ? "register it in the `env` option of specification.cli(), or write it inline: KEY=value" : `name a registered set: ${known.join(", ")}, or write it inline: KEY=value`,
+					found: `${displayPath}:${token.line}: env: "${token.name}" is not a registered env set`,
+					read: "docs/guides/cli-specs.md#registration-once-per-app",
+					why: "A bare word under `env:` names a set the app registered once, in the options of specification.cli()."
+				}));
+			}
+			Object.assign(env, declared);
+			continue;
+		}
+		env[token.key] = token.value;
+	}
+	return env;
 }
 //#endregion
-//#region src/specifications/deployment/exchange/transport.ts
-const USER_AGENT = "@jterrazz/test";
-function flatHeaders(headers) {
-	return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, Array.isArray(value) ? value.join(", ") : String(value)]));
+//#region src/specifications/cli/documents/literate-judge.ts
+/** ANSI stripped (`no-transform-duplicating-tokens`) and `transform` applied, nothing else: a block scalar states its own final newline. */
+function comparable(raw, transform) {
+	const stripped = stripAnsiCodes(raw);
+	return transform ? transform(stripped) : stripped;
 }
-function headersOf(sent) {
-	const headers = {
-		host: sent.url.host,
-		"user-agent": USER_AGENT
-	};
-	for (const [name, value] of Object.entries(sent.headers)) headers[name.toLowerCase()] = value;
-	return headers;
+function tokenAwareEquals(scope) {
+	return (expected, actual) => textEquals(expected, actual, new CaptureScope(scope.workdir));
 }
-async function opened(socket, event) {
-	await new Promise((resolve, reject) => {
-		socket.once(event, () => {
-			resolve();
-		});
-		socket.once("error", reject);
-	});
+function resolveUnderWorkDir(path, context) {
+	const { workDir } = context;
+	const target = resolve(workDir, path);
+	const inside = relative(workDir, target);
+	if (isAbsolute(path) || inside.startsWith("..") || isAbsolute(inside)) throw new Error(refusal$1({
+		fix: "name a relative path under the working directory",
+		found: `${context.displayPath}: files: "${path}" leaves the working directory`,
+		read: "docs/guides/spec-documents.md#files-what-the-run-left-behind",
+		why: "A `files:` key is a relative path under the working directory."
+	}));
+	return target;
 }
-async function openSecure(address, url, route, hold) {
-	const name = hostOf(url);
-	const socket = connect$1({
-		checkServerIdentity: (_host, certificate) => checkServerIdentity(name, certificate),
-		host: address.host,
-		port: address.port,
-		rejectUnauthorized: false,
-		...route.ca === void 0 ? {} : { ca: [...getCACertificates("default"), route.ca] },
-		...isIP(name) === 0 ? { servername: name } : {}
-	});
-	hold(socket);
+function preview(text) {
+	return JSON.stringify(text.length > 160 ? `${text.slice(0, 160)}...` : text);
+}
+function readIfPresent(path) {
 	try {
-		await opened(socket, "secureConnect");
-	} catch (error) {
-		return {
-			tls: void 0,
-			unreachable: unreachableReason(error, true)
-		};
+		return statSync(path).isFile() ? readFileSync(path, "utf8") : null;
+	} catch {
+		return null;
 	}
-	const refused = socket.authorized ? void 0 : codeOf(socket.authorizationError);
-	const tls = tlsFacts(socket.getPeerCertificate(), {
-		authorizationError: refused,
-		protocol: socket.getProtocol() ?? void 0
-	}, Date.now());
-	return refused === void 0 || route.insecure ? {
-		socket,
-		tls
-	} : {
-		tls,
-		unreachable: refusedCertificate(refused)
-	};
 }
-async function open$1(sent, route, hold) {
-	const address = route.connect ?? {
-		host: hostOf(sent.url),
-		port: portOf(sent.url)
-	};
-	if (sent.url.protocol === "https:") return await openSecure(address, sent.url, route, hold);
-	const socket = connect(address);
-	hold(socket);
-	await opened(socket, "connect");
-	return {
-		socket,
-		tls: void 0
-	};
+function checkFile(assertion, context) {
+	const { scope } = context;
+	const target = resolveUnderWorkDir(assertion.path, context);
+	let exists;
+	try {
+		exists = statSync(target) !== void 0;
+	} catch {
+		exists = false;
+	}
+	if (assertion.kind === "absent") return exists ? `${assertion.path}: expected absent, got a file` : null;
+	if (!exists) return `${assertion.path}: expected to exist, got nothing at that path`;
+	if (assertion.kind === "exists") return null;
+	const content = readIfPresent(target);
+	if (content === null) return `${assertion.path}: expected a readable file, got a directory`;
+	for (const needle of assertion.contains) if (!textContains(needle.text, content, scope)) return `${assertion.path}: expected to contain ${preview(needle.text)}, got ${preview(content)}`;
+	if (assertion.equals !== null && !textEquals(assertion.equals.text, content, scope)) return `${assertion.path}: expected ${preview(assertion.equals.text)}, got ${preview(content)}`;
+	return null;
 }
-async function exchanged(sent, socket) {
-	return await new Promise((resolve, reject) => {
-		const outgoing = request({
-			createConnection: () => socket,
-			headers: headersOf(sent),
-			method: sent.method,
-			path: `${sent.url.pathname}${sent.url.search}`
-		}, (response) => {
-			const chunks = [];
-			response.on("data", (chunk) => {
-				chunks.push(chunk);
-			});
-			response.once("end", () => {
-				resolve({
-					response,
-					text: Buffer.concat(chunks).toString("utf8")
-				});
-			});
-			response.once("error", reject);
-		});
-		outgoing.once("error", reject);
-		outgoing.end(sent.body);
-	});
+function failure(run, context, details) {
+	return atLine(new Error(refusal$1({
+		fix: "correct the command, or run with TEST_UPDATE=1 to rewrite the runs: the exit code and the streams, and nothing else",
+		found: [
+			`spec mismatch: ${context.document.description}`,
+			"",
+			`$ ${run.command}`,
+			"",
+			details.join("\n\n"),
+			"",
+			`${context.displayPath}:${run.commandLine}`
+		].join("\n"),
+		read: "docs/guides/spec-documents.md#failure-and-update",
+		why: "A spec document states what its runs produce: the exit code and the streams, whole."
+	})), context.filePath, run.commandLine);
 }
-async function answered(sent, route, hold, presented) {
-	const opening = await open$1(sent, route, hold);
-	presented(opening.tls);
-	if (!("socket" in opening)) return opening;
-	const { response, text } = await exchanged(sent, opening.socket);
-	return {
-		headers: flatHeaders(response.headers),
-		status: response.statusCode ?? 0,
-		text,
-		tls: opening.tls
-	};
+function atLine(error, filePath, line) {
+	error.stack = `${error.name}: ${error.message}\n    at ${filePath}:${line}:1`;
+	return error;
 }
-/** One request and its whole response, under one deadline; a redirect is the answer, never followed. */
-async function exchange(sent, route) {
-	let socket;
-	let tls;
-	let timer;
-	const deadline = new Promise((resolve) => {
-		timer = setTimeout(() => {
-			resolve({
-				tls,
-				unreachable: TIMEOUT
-			});
-		}, route.timeout);
-	});
+function assertRun(outcome, context) {
+	const { actual, run } = outcome;
+	const { scope } = context;
+	if (actual.exitCode !== run.exitCode) throw failure(run, context, [[
+		"exit code mismatch",
+		`  expected: ${run.exitCode}`,
+		`  received: ${actual.exitCode}`,
+		...outcome.stderr.length > 0 ? [
+			"",
+			"stderr was:",
+			outcome.stderr.replace(/\n$/u, "")
+		] : []
+	].join("\n")]);
+	const equals = tokenAwareEquals(scope);
+	const details = [];
+	for (const [name, expected, received] of [[
+		"stdout",
+		run.stdout?.text ?? "",
+		outcome.stdout
+	], [
+		"stderr",
+		run.stderr?.text ?? "",
+		outcome.stderr
+	]]) if (!textEquals(expected, received, scope)) details.push(formatStdoutDiff(name, expected, received, { equals }));
+	details.push(...filesDetail(outcome, context));
+	if (details.length > 0) throw failure(run, context, details);
+}
+function filesDetail({ run }, context) {
+	const fileFailures = run.files.map((assertion) => checkFile(assertion, context)).filter((line) => line !== null);
+	return fileFailures.length === 0 ? [] : [[
+		"files mismatch",
+		"",
+		...fileFailures.map((line) => `  ${line}`)
+	].join("\n")];
+}
+/** The `files:` of a run, judged alone: update mode rewrites a run's exit code and streams, never what the run was asked to leave on disk. */
+function assertFiles(outcome, context) {
+	const details = filesDetail(outcome, context);
+	if (details.length > 0) throw failure(outcome.run, context, details);
+}
+/** Placeholders of the previous golden preserved by pattern (`no-volatile-literal`); an emptied stream loses its key. */
+function updates(outcomes, scope) {
+	return outcomes.map(({ actual, run, stderr, stdout }) => ({
+		exitCode: actual.exitCode,
+		stderr: mergeTextPreservingPlaceholders(run.stderr?.text ?? null, stderr, scope),
+		stdout: mergeTextPreservingPlaceholders(run.stdout?.text ?? null, stdout, scope)
+	}));
+}
+//#endregion
+//#region src/specifications/cli/documents/literate.ts
+function readDocument(filePath, displayPath) {
 	try {
-		return await Promise.race([answered(sent, route, (held) => {
-			socket = held;
-		}, (facts) => {
-			tls = facts;
-		}), deadline]);
-	} catch (error) {
-		return {
-			tls,
-			unreachable: unreachableReason(error)
-		};
-	} finally {
-		clearTimeout(timer);
-		socket?.destroy();
+		return readSpecFile(readFileSync(filePath, "utf8"), displayPath);
+	} catch (error) {
+		throw error instanceof SpecSyntaxError ? atLine(grammarRefusal(error, displayPath), filePath, error.line) : error;
 	}
 }
-//#endregion
-//#region src/specifications/deployment/exchange/request.action.ts
-const NO_WORKDIR = { workDir: null };
-function responseOf(answer) {
-	if (answer.unreachable !== void 0) return {
-		body: null,
-		headers: {},
-		status: 0,
-		unreachable: answer.unreachable
-	};
-	const contentType = answer.headers["content-type"];
+async function execute(run, session) {
+	const { command, env, transform, workDir } = session;
+	const timeout = run.timeout ?? void 0;
+	const actual = run.waitFor === null ? await command.exec(run.command, workDir, env, {
+		stdin: run.stdin ?? void 0,
+		timeout
+	}) : await command.watch(run.command, workDir, {
+		timeout,
+		waitFor: run.waitFor
+	}, env);
 	return {
-		body: bodyKind(contentType) === "binary" ? null : readBody$1(answer.text, contentType) ?? null,
-		headers: answer.headers,
-		status: answer.status
+		actual,
+		run,
+		stderr: comparable(actual.stderr, transform),
+		stdout: comparable(actual.stdout, transform)
 	};
 }
-async function send(written, read, { config, testDir }) {
-	const url = targetUrl(written.target, config.baseUrl);
-	const address = read(connect$2);
-	const answer = await exchange({
-		body: written.body,
-		headers: {
-			...written.headers,
-			...read(headers)
-		},
-		method: written.method,
-		url
-	}, {
-		ca: config.ca,
-		connect: address === null ? void 0 : connectAddress(address, url),
-		insecure: config.insecure,
-		timeout: config.timeout
-	});
-	return new ExchangeResult({
+function lastResult(outcomes, options) {
+	const { config, testDir, workDir } = options;
+	const lastOutcome = outcomes.at(-1);
+	if (lastOutcome === void 0) throw invariant("a document ran no command, though its runs: holds at least one");
+	return new CliResult({
+		commandOutput: lastOutcome.actual,
 		config,
-		recording: config.recording,
-		response: responseOf(answer),
+		dockerConfig: config.dockerConfig,
 		testDir,
-		tls: answer.tls
+		testRunId: config.dockerTestRunId,
+		transform: config.transform,
+		workDir
 	});
 }
-function writtenRequest(source, testDir) {
-	const parsed = typeof source === "string" ? parseRequestFile(dedent(source), "the request in place") : parseRequestFile(readFileSync(resolve(testDir, source.path), "utf8"), source.path);
-	return {
-		body: parsed.body,
-		headers: parsed.headers,
-		method: parsed.method,
-		target: parsed.path
+/** Resolves with the last run's result. Under `TEST_UPDATE=1` every run executes and is rewritten; its `files:` are still judged. */
+async function runSpecDocument(options) {
+	const { config, displayPath, filePath, workDir } = options;
+	const { command } = config;
+	if (!command) throw invariant(".run() reached a chain with no command adapter");
+	const file = readDocument(filePath, displayPath);
+	const { document } = file;
+	const fileDir = filePath.replace(/[/\\][^/\\]*$/u, "");
+	for (const fixture of document.fixtures) fsFixtures.layer(fixture.path, fileDir, workDir);
+	const workdir = safeRealpath(workDir);
+	const servers = await startServers(document, config, displayPath, workdir);
+	const scope = new CaptureScope(workdir);
+	const env = expandWorkdir({
+		...options.baseEnv,
+		...servers.env,
+		...documentEnv(document, config, displayPath)
+	}, workdir);
+	const judgement = {
+		displayPath,
+		document,
+		filePath,
+		scope,
+		workDir
+	};
+	const session = {
+		command,
+		env,
+		transform: config.transform,
+		workDir
 	};
+	const rewriting = shouldUpdateSnapshots() && options.frozen !== true;
+	const outcomes = [];
+	try {
+		for (const run of document.runs) {
+			const outcome = await execute(run, session);
+			outcomes.push(outcome);
+			if (rewriting) assertFiles(outcome, judgement);
+			else assertRun(outcome, judgement);
+		}
+	} finally {
+		await servers.stop();
+	}
+	if (rewriting) writeFileSync(filePath, updateSpecFile(file, updates(outcomes, scope)));
+	return lastResult(outcomes, options);
 }
-/** A redirect is the answer, never followed; an exchange that never answered is the answer too, `unreachable: <reason>`. */
-const get = defineAction({
-	accessors: EXCHANGE_RESULT_ROWS,
-	name: "get",
-	perform: async ([target], read, _adapters, run) => await send({
-		headers: {},
-		method: "GET",
-		target
-	}, read, run),
+//#endregion
+//#region src/specifications/cli/documents/run.action.ts
+/** The chain's fixture is laid first, the document's `fixture:` over it; its `env:` wins over a chained `.env()`. */
+const run$1 = defineAction({
+	accessors: CLI_RESULT_ROWS,
+	name: "run",
+	perform: async ([document, options], read, _adapters, { config, testDir, workDir }) => {
+		const cwd = workDir;
+		const filePath = resolveSpecPath("run", document.path, testDir);
+		return await runSpecDocument({
+			baseEnv: childEnv(config, read(env), safeRealpath(cwd)),
+			config,
+			displayPath: relative(process.cwd(), filePath) || document.path,
+			filePath,
+			frozen: options?.frozen,
+			testDir,
+			workDir: cwd
+		});
+	},
+	prepare: ([document]) => {
+		requireDiskFile("run", document, ".spec.yaml");
+		return { workDir: scratchDirectory("spec-command-") };
+	},
 	row: {
 		group: "Terminal action",
-		name: ".get()",
-		probe: ".get('/"
+		name: ".run()",
+		probe: ".run("
 	}
 });
 //#endregion
-//#region src/specifications/deployment/deployment.composition.ts
+//#region src/specifications/cli/process/exec.action.ts
+function isLongRunning(options) {
+	return options?.waitFor !== void 0 || options?.timeout !== void 0;
+}
+function requireRelativeFolder(cwd) {
+	if (cwd === void 0) return;
+	const inside = normalize(cwd);
+	if (isAbsolute(cwd) || inside === ".." || inside.startsWith(`..${sep}`)) throw new Error(refusal$1({
+		fix: "name a folder below the working directory, relative to it: .exec('check', { cwd: 'packages/site' })",
+		found: `.exec(..., { cwd: ${JSON.stringify(cwd)} }), a folder outside the working directory`,
+		read: "docs/guides/cli-specs.md#cwd-a-folder-of-the-working-directory",
+		why: "A command runs in the working directory the chain laid, or in one of its folders: anywhere else is the machine, not the fixture."
+	}));
+}
+function runFolder(root, cwd) {
+	if (cwd === void 0) return root;
+	const folder = resolve(root, cwd);
+	if (statSync(folder, { throwIfNoEntry: false })?.isDirectory() !== true) throw new Error(refusal$1({
+		fix: "lay the folder with a fixture, or name one the fixtures laid",
+		found: `.exec(..., { cwd: ${JSON.stringify(cwd)} }), a folder the working directory does not hold`,
+		read: "docs/guides/cli-specs.md#cwd-a-folder-of-the-working-directory",
+		why: "A command runs in a folder the chain laid: one that does not exist has no files of the fixture."
+	}));
+	return folder;
+}
+//#endregion
+//#region src/specifications/cli/cli.composition.ts
 const composition$5 = {
 	actions: [defineAction({
-		accessors: EXCHANGE_RESULT_ROWS,
-		name: "request",
-		perform: async ([source], read, _adapters, run) => await send(writtenRequest(source, run.testDir), read, run),
-		prepare: ([source]) => {
-			if (typeof source !== "string") requireDiskFile("request", source, ".http");
-			return NO_WORKDIR;
+		accessors: CLI_RESULT_ROWS,
+		name: "exec",
+		perform: async ([args = "", options], read, { command }, { config, testDir, workDir }) => {
+			const root = workDir;
+			const cwd = runFolder(root, options?.cwd);
+			const env$1 = childEnv(config, read(env), safeRealpath(root));
+			let output;
+			if (isLongRunning(options)) output = await command.watch(args, cwd, options, env$1);
+			else if (Array.isArray(args)) {
+				output = {
+					exitCode: 0,
+					stderr: "",
+					stdout: ""
+				};
+				for (const one of args) {
+					output = await command.exec(one, cwd, env$1);
+					if (output.exitCode !== 0) break;
+				}
+			} else output = await command.exec(args, cwd, env$1);
+			return new CliResult({
+				commandOutput: output,
+				config,
+				dockerConfig: config.dockerConfig ?? void 0,
+				requests: config.backend?.requests(),
+				testDir,
+				testRunId: config.dockerTestRunId ?? void 0,
+				transform: config.transform,
+				workDir: root
+			});
+		},
+		prepare: ([args = "", options]) => {
+			if (Array.isArray(args) && args.length === 0) throw new Error(refusal$1({
+				fix: "name at least one command: .exec(['build', 'test'])",
+				found: ".exec([]), a sequence of no command",
+				read: "docs/guides/cli-specs.md#sequences-array-form",
+				why: "A sequence runs its commands in order, and runs at least one."
+			}));
+			if (isLongRunning(options) && Array.isArray(args)) throw new Error(refusal$1({
+				fix: "wait on one long-running command: .exec(args, { waitFor, timeout }), or drop the options",
+				found: ".exec([...], { waitFor/timeout }), options on a command sequence",
+				read: "docs/guides/cli-specs.md#long-running-processes-waitfor--timeout",
+				why: "`waitFor` and `timeout` wait on one long-running process."
+			}));
+			requireRelativeFolder(options?.cwd);
+			return { workDir: scratchDirectory("spec-command-") };
 		},
 		row: {
 			group: "Terminal action",
-			name: ".request()",
-			probe: ".request(file("
+			name: ".exec()",
+			probe: ".exec("
 		}
-	}), get],
+	}), run$1],
 	capabilities: [
-		connect$2,
-		headers,
+		env,
+		fixture,
+		intercept,
+		link$1,
+		prepare,
+		seed,
 		sharing
 	],
 	options: {
-		ca: {
+		backend: {
+			group: "Constructor option",
+			name: "backend",
+			probe: "backend:"
+		},
+		commands: {
+			group: "Constructor option",
+			name: "commands",
+			probe: "commands:"
+		},
+		defaults: {
+			group: "Constructor option",
+			name: "defaults",
+			probe: "defaults:"
+		},
+		docker: {
+			group: "Constructor option",
+			name: "docker",
+			probe: "docker:"
+		},
+		env: {
 			group: "Constructor option",
-			name: "ca",
-			probe: "ca:"
+			name: "env",
+			probe: "env:"
 		},
-		insecure: {
+		root: {
 			group: "Constructor option",
-			name: "insecure",
-			probe: "insecure:"
+			name: "root",
+			probe: "root:"
 		},
-		recordedHeaders: {
+		serve: {
 			group: "Constructor option",
-			name: "recordedHeaders",
-			probe: "recordedHeaders:"
+			name: "serve",
+			probe: "serve:"
 		},
-		timeout: {
+		services: {
 			group: "Constructor option",
-			name: "timeout",
-			probe: "timeout:"
+			name: "services",
+			probe: "services:"
 		},
-		url: {
+		transform: {
 			group: "Constructor option",
-			name: "url",
-			probe: "url:"
+			name: "transform",
+			probe: "transform:"
 		}
 	}
 };
-const deploymentDefinition = defineSpecification()({
+const cliDefinition = defineSpecification()({
 	...composition$5,
-	adapters: (_config) => ({}),
+	adapters: (config) => ({
+		command: config.command,
+		databases: databaseSet(config),
+		links: fsLinks,
+		network: stubBackend(config.backend, "cli"),
+		steps: inProcessSteps,
+		workdir: fsFixtures
+	}),
 	locate: getCallerDir
 });
 //#endregion
-//#region src/specifications/deployment/deployment.handle.ts
-const DEFAULT_TIMEOUT_MS$1 = 5e3;
-const DEFAULT_RECORDED_HEADERS = ["content-type", "location"];
-/** Refused before the first exchange: a base that is no http(s) URL, and a deadline that is no positive number of milliseconds. */
-function refuseOptions$1(options) {
-	if (options.url !== void 0 && !/^https?:\/\/[^/\s]/u.test(options.url)) throw new Error(refusal$1({
-		fix: "name the deployment's base as an absolute URL, `url: 'https://site.test'`, or leave it out and write each URL whole",
-		found: `specification.deployment({ url: ${JSON.stringify(options.url)} }), no http(s) URL`,
-		read: "docs/guides/deployment-specs.md#options",
-		why: "A path is read from the base `url`, so the base is an absolute http:// or https:// URL."
-	}));
-	if (options.timeout !== void 0 && (!Number.isFinite(options.timeout) || options.timeout <= 0)) throw new Error(refusal$1({
-		fix: "pass the milliseconds one exchange may take, `timeout: 2000`, or leave the 5000 default",
-		found: `specification.deployment({ timeout: ${String(options.timeout)} }), no deadline`,
-		read: "docs/guides/deployment-specs.md#options",
-		why: "An exchange that never answers reads `unreachable: timeout` once its deadline passes, so the deadline is a positive number of milliseconds."
-	}));
+//#region src/specifications/cli/process/command.ts
+/** An absolute path as is; else the project's `node_modules/.bin`, then the working directory's; else the bare name. */
+function resolveCommand(command, root) {
+	return [root, process.cwd()].map((directory) => resolve(directory, "node_modules/.bin", command)).find((path) => existsSync(path)) ?? command;
+}
+//#endregion
+//#region src/specifications/cli/process/exec.adapter.ts
+const DEFAULT_WATCH_TIMEOUT = 1e4;
+const TIMED_OUT = 124;
+const COVERAGE_REPORTER = /--require="[^"]*child-coverage\.cjs"/u;
+function withCoverageReporter(extra) {
+	const stated = extra?.NODE_OPTIONS;
+	const reporter = COVERAGE_REPORTER.exec(process.env.NODE_OPTIONS ?? "")?.[0];
+	if (extra === void 0 || typeof stated !== "string" || reporter === void 0) return extra;
+	return stated.includes(reporter) ? extra : {
+		...extra,
+		NODE_OPTIONS: `${stated} ${reporter}`.trim()
+	};
+}
+/** `null` overrides delete keys (`INIT_CWD: null`); a NODE_OPTIONS a chain states keeps the mutation reporter the run asked for. */
+function buildEnv(stated) {
+	const extra = withCoverageReporter(stated);
+	const unset = new Set(Object.entries(extra ?? {}).filter(([, value]) => value === null).map(([key]) => key));
+	return Object.fromEntries(Object.entries({
+		...process.env,
+		INIT_CWD: void 0,
+		...extra
+	}).filter(([key]) => !unset.has(key)));
+}
+function terminate(child) {
+	child.kill("SIGTERM");
+	return setTimeout(() => {
+		child.kill("SIGKILL");
+	}, KILL_GRACE_MS);
+}
+/** invariant: with a pattern expected, even a clean exit is a failure; without one a clean exit is a success. */
+function exitCodeOf(code, waitFor) {
+	if (waitFor !== void 0 && code === 0) return 1;
+	return code ?? 1;
+}
+/** Resolves 0 when `waitFor` appears, the exit code when the process ends first, 124 at the timeout; the timeout timer is unref'd. */
+async function observeProcess(child, options) {
+	const { waitFor } = options;
+	return await new Promise((resolve) => {
+		const output = {
+			stderr: "",
+			stdout: ""
+		};
+		let resolved = false;
+		let exited = false;
+		let killTimer;
+		const timeoutTimer = setTimeout(() => {
+			finish(TIMED_OUT);
+		}, options.timeout ?? DEFAULT_WATCH_TIMEOUT);
+		timeoutTimer.unref();
+		function finish(exitCode) {
+			if (resolved) return;
+			resolved = true;
+			clearTimeout(timeoutTimer);
+			if (!exited) killTimer = terminate(child);
+			resolve({
+				exitCode,
+				...output
+			});
+		}
+		const collect = (stream) => (data) => {
+			output[stream] += data.toString();
+			if (waitFor !== void 0 && (output.stdout.includes(waitFor) || output.stderr.includes(waitFor))) finish(0);
+		};
+		child.stdout?.on("data", collect("stdout"));
+		child.stderr?.on("data", collect("stderr"));
+		child.on("exit", (code) => {
+			exited = true;
+			clearTimeout(killTimer);
+			finish(exitCodeOf(code, waitFor));
+		});
+	});
+}
+/** Spawned, never `spawnSync`: the test's event loop keeps running while the binary does, so a server the test started (a collector, a stub) answers it. stdout and stderr are captured whatever the exit code, and many CLIs write banners to stderr. */
+var ExecAdapter = class {
+	command;
+	constructor(command) {
+		this.command = command;
+	}
+	async exec(args, cwd, extraEnv, input) {
+		const env = buildEnv(extraEnv);
+		const child = spawn(`${this.command} ${args}`, [], {
+			cwd,
+			detached: SIGNALS_GROUPS,
+			env,
+			shell: true
+		});
+		onTestFinished(async () => {
+			await endGroup(child);
+		});
+		return await new Promise((resolve) => {
+			const output = {
+				stderr: "",
+				stdout: ""
+			};
+			let timedOut = false;
+			const timer = input?.timeout === void 0 ? void 0 : setTimeout(() => {
+				timedOut = true;
+				endGroup(child);
+			}, input.timeout);
+			child.stdout.setEncoding("utf8").on("data", (data) => {
+				output.stdout += data;
+			});
+			child.stderr.setEncoding("utf8").on("data", (data) => {
+				output.stderr += data;
+			});
+			child.on("close", (code) => {
+				clearTimeout(timer);
+				resolve({
+					exitCode: timedOut ? TIMED_OUT : code ?? 1,
+					...output
+				});
+			});
+			child.stdin.on("error", () => void 0);
+			child.stdin.end(input?.stdin);
+		});
+	}
+	async watch(args, cwd, options, extraEnv) {
+		const env = buildEnv(extraEnv);
+		const child = spawn(`${this.command} ${args}`, [], {
+			cwd,
+			detached: SIGNALS_GROUPS,
+			env,
+			shell: true,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		const kill = (signal) => signalGroup(child, signal);
+		return await observeProcess({
+			kill,
+			on: child.on.bind(child),
+			stderr: child.stderr,
+			stdout: child.stdout
+		}, options);
+	}
+};
+//#endregion
+//#region src/specifications/cli/cli.handle.ts
+function dockerTestRunId() {
+	return `t-${Math.random().toString(36).slice(2, 10)}-${Date.now().toString(36)}`;
+}
+async function startedBackend$1(declared, defaults, started) {
+	if (declared === void 0) return {
+		backend: null,
+		defaults
+	};
+	const backend = new StubBackend({ port: declared.port });
+	try {
+		return {
+			backend,
+			defaults: {
+				[declared.env]: await backend.start(),
+				...defaults
+			}
+		};
+	} catch (error) {
+		await started?.stop();
+		throw error;
+	}
 }
-async function startDeployment(options = {}) {
+async function startCli(bin, options = {}) {
+	const callerDir = getCallerDir();
 	await registerMatchers();
-	refuseOptions$1(options);
+	const root = resolveRoot(options.root, callerDir);
+	const resolvedBin = resolveCommand(bin, root);
+	const services = declaredServices(options.services);
+	const databaseKeys = declaredDatabaseKeys(services);
+	if (options.docker !== void 0) requireDockerDaemon();
+	let started = null;
+	if (Object.keys(services).length > 0) started = await startServices(services, root, { type: "none" });
+	const { backend, defaults } = await startedBackend$1(options.backend, options.defaults, started);
+	const dockerTestRunIdOf = options.docker === void 0 ? void 0 : dockerTestRunId();
+	const declaredServicesOf = Object.keys(services).length > 0 ? services : void 0;
 	const config = {
-		baseUrl: options.url,
-		ca: options.ca,
-		insecure: options.insecure ?? false,
-		recording: {
-			bodyKeptAbsent: true,
-			headers: options.recordedHeaders ?? DEFAULT_RECORDED_HEADERS
-		},
-		timeout: options.timeout ?? DEFAULT_TIMEOUT_MS$1
+		backend: backend ?? void 0,
+		command: new ExecAdapter(resolvedBin),
+		database: started?.database,
+		databaseKeys,
+		databases: started?.databases,
+		dockerConfig: options.docker,
+		dockerTestRunId: dockerTestRunIdOf,
+		defaultEnv: defaults,
+		envSets: options.env,
+		root,
+		serveRegistry: options.serve,
+		services: declaredServicesOf,
+		transform: options.transform
 	};
 	return {
-		cleanup: async () => {},
-		deployment: deploymentDefinition.open(config)
+		cleanup: async () => {
+			await started?.stop();
+			await backend?.stop();
+		},
+		cli: cliDefinition.open(config),
+		docker: createDockerReader(callerDir),
+		orchestrator: started?.orchestrator ?? null
 	};
 }
 //#endregion
@@ -5952,8 +6006,6 @@ const specification = {
 	api: startApi,
 	/** Test a command binary, each spec in a fresh temp directory. */
 	cli: startCli,
-	/** Probe a running deployment over the network: one complete HTTP exchange, no browser; `.get(url)` or `.request(...)` ends the chain. */
-	deployment: startDeployment,
 	/** Specify a module against real services, or against a golden; `.call()` ends the chain. */
 	integration: startIntegration,
 	/** Test background jobs, in this process; `.trigger(name)` ends the chain. */