@jterrazz/test 15.2.0 → 15.3.0

package/dist/index.js

@@ -1,19 +1,20 @@
 import { a as copyPlan, c as GROUND_EXPECTED, d as GROUND_SEEDS, i as match, n as Matcher, t as CaptureScope, u as GROUND_REQUESTS } from "./match.js";
-import { A as mergePreservingPlaceholders, C as DirectoryAccessor, D as inspectContainer, E as findContainersByLabel, F as structuralSubset, I as textEquals, L as TableAccessor, N as renderExpected, O as removeContainers, P as structuralEquals, R as JsonAccessor, S as FilesystemAccessor, T as walkDirectory, _ as validateDatabaseOption, b as resolveCommand, c as shouldUpdateSnapshots, d as formatStartupReport, f as formatStdoutDiff, g as BaseResult, h as CliResult, i as runSpecDocument, j as mergeTextPreservingPlaceholders, l as formatDirectoryDiff, m as ContainerAccessor, n as SQLITE_TEMPLATE_DIR, o as ServeAdapter, p as formatTableDiff, s as UPDATE_HINT, u as formatResponseDiff, v as discoverRoot, w as diffDirectories, x as resolveRoot, y as expandWorkdir, z as TextAccessor } from "./artifacts.js";
-import { a as isContract, i as defineContracts, n as contractsOf, o as isContracts, r as defineContract, t as ContractQueue } from "./queue.js";
+import { a as isStreamBody, c as defineContracts, i as STREAM_BODY, l as isContract, n as ContractQueue, o as contractsOf, r as pause, s as defineContract, t as toReadableStream, u as isContracts } from "./stream.js";
+import { A as mergePreservingPlaceholders, C as DirectoryAccessor, D as inspectContainer, E as findContainersByLabel, F as structuralSubset, I as textEquals, L as TableAccessor, N as renderExpected, O as removeContainers, P as structuralEquals, R as JsonAccessor, S as FilesystemAccessor, T as walkDirectory, _ as validateDatabaseOption, b as resolveCommand, c as shouldUpdateSnapshots, d as formatStartupReport, f as formatStdoutDiff, g as BaseResult, h as CliResult, i as runSpecDocument, j as mergeTextPreservingPlaceholders, l as formatDirectoryDiff, m as ContainerAccessor, n as SQLITE_TEMPLATE_DIR, o as ServeAdapter, p as formatTableDiff, s as missingHint, u as formatResponseDiff, v as discoverRoot, w as diffDirectories, x as resolveRoot, y as expandWorkdir, z as TextAccessor } from "./artifacts.js";
 import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parse } from "yaml";
 import { execFile, execSync, spawn, spawnSync } from "node:child_process";
 import { Client } from "pg";
-import { mockDeep } from "vitest-mock-extended";
+import { mock, mockDeep } from "vitest-mock-extended";
 import MockDatePackage from "mockdate";
+import { vi } from "vitest";
 import { tmpdir } from "node:os";
 import "node:url";
+import { createHash, randomUUID } from "node:crypto";
 import { createServer } from "node:http";
 import { promisify } from "node:util";
 import Database from "better-sqlite3";
-import { createHash } from "node:crypto";
 //#region src/integrations/compose/compose-parser.ts
 /**
 * Parse a docker-compose file and extract service definitions.
@@ -110,6 +111,60 @@ var ComposeStackAdapter = class {
 	}
 };
 //#endregion
+//#region src/integrations/msw/scope.ts
+/**
+* The network double in MODULE scope — the same contracts, the same queue and
+* the same strictness as a chain's `.intercept()`, for the one kind of test
+* that has no chain to hang them on.
+*
+* A module test whose subject reaches the network had exactly two ways out
+* before this: `vi.stubGlobal('fetch')`, which replaces the platform with a
+* hand-written stand-in, or `msw/node` imported directly, which F6 refuses a
+* test and F8 refuses a consumer to declare. Both answer "what did the outside
+* world reply" in a dialect nothing else in the repository speaks.
+*
+* The scope is an `AsyncDisposable`, so the handlers come off at the end of
+* the block however the block ends — and the strict violation (an outgoing
+* request no contract accepted) is raised THERE, which is what makes the
+* double a guard rather than a convenience.
+*/
+/**
+* The contracts a call declared, whichever of the two forms it used. Exported
+* for its own module test: the bare-request refusal is a runtime guard the
+* compiler already states, so no typed call site can reach it.
+*
+* @internal
+*/
+function declared(requestOrContracts, maybeResponse) {
+	if (Array.isArray(requestOrContracts) || isContracts(requestOrContracts) || isContract(requestOrContracts)) return contractsOf(requestOrContracts);
+	if (maybeResponse === void 0) throw new Error("intercept(): a bare request needs its response — pass a contract (defineContract({ request, response })) or the inline pair intercept(request, response).");
+	return [{
+		request: requestOrContracts,
+		response: maybeResponse
+	}];
+}
+/**
+* Build the module-scope double on one engine. The node entry hands it msw's
+* server, the page's entry hands it msw's worker: one shape, two transports,
+* exactly as a chain's `.intercept()` already has it.
+*
+* @internal
+*/
+function interceptThrough(register) {
+	async function intercept(requestOrContracts, maybeResponse) {
+		const contracts = declared(requestOrContracts, maybeResponse);
+		if (contracts.length === 0) throw new Error("intercept(): declare at least one contract — an empty list guards nothing, and a subject with no network needs no intercept at all.");
+		const registration = await register(contracts);
+		return { [Symbol.asyncDispose]: async () => {
+			const violation = registration.violation();
+			registration.cleanup();
+			await Promise.resolve();
+			if (violation) throw violation;
+		} };
+	}
+	return intercept;
+}
+//#endregion
 //#region src/integrations/postgres/postgres.ts
 var PostgresHandle = class {
 	type = "postgres";
@@ -641,6 +696,18 @@ function wrapJson(data) {
 	};
 }
 const TEXT_CONTENT_TYPE = "text/plain; charset=utf-8";
+const STREAM_CONTENT_TYPE = "application/octet-stream";
+const SSE_CONTENT_TYPE = "text/event-stream";
+/** The wire form of one event — the frame an `EventSource` parses. */
+function frameEvent(event) {
+	const lines = [];
+	if (event.event !== void 0) lines.push(`event: ${event.event}`);
+	if (event.id !== void 0) lines.push(`id: ${event.id}`);
+	if (event.retry !== void 0) lines.push(`retry: ${event.retry}`);
+	const payload = typeof event.data === "string" ? event.data : JSON.stringify(event.data);
+	for (const line of payload.split("\n")) lines.push(`data: ${line}`);
+	return `${lines.join("\n")}\n\n`;
+}
 function matchesBody(body, expected) {
 	if (typeof expected === "string") return (typeof body === "string" ? body : JSON.stringify(body ?? "")).includes(expected);
 	if (expected instanceof RegExp) {
@@ -750,6 +817,52 @@ const http = {
 			transport: "network-error"
 		};
 	},
+	/**
+	* Response: a body that arrives in PIECES, written in order.
+	*
+	* A subject that reads a response as it lands — a token-by-token render, a
+	* progress bar, a reconnect on a half-read body — is specified by the
+	* chunks and their order, which a single serialised body cannot state.
+	* Honoured by all three engines: msw's server, msw's worker, and the
+	* `node:http` stub the website and mobile facets serve from.
+	*
+	* @example
+	*   http.stream(['Hel', 'lo, ', 'world'], { contentType: 'text/plain', delay: 10 })
+	*/
+	stream(chunks, init) {
+		return {
+			status: init?.status ?? 200,
+			body: {
+				chunks: [...chunks],
+				contentType: init?.contentType ?? STREAM_CONTENT_TYPE,
+				delayBetweenChunks: init?.delay ?? 0,
+				kind: STREAM_BODY
+			},
+			headers: init?.headers
+		};
+	},
+	/**
+	* Response: a server-sent event stream — one chunk per event, framed the
+	* way an `EventSource` reads them, served as `text/event-stream`.
+	*
+	* @example
+	*   http.sse([{ data: { token: 'Hel' } }, { data: { token: 'lo' } }, { event: 'done', data: '' }])
+	*/
+	sse(events, init) {
+		return {
+			status: init?.status ?? 200,
+			body: {
+				chunks: events.map(frameEvent),
+				contentType: SSE_CONTENT_TYPE,
+				delayBetweenChunks: init?.delay ?? 0,
+				kind: STREAM_BODY
+			},
+			headers: {
+				"cache-control": "no-cache",
+				...init?.headers
+			}
+		};
+	},
 	/** Response: a text body, served as `text/plain` (200 by default). */
 	text(body, init) {
 		return {
@@ -922,11 +1035,9 @@ const openai = {
 };
 //#endregion
 //#region src/vitest/mock-of.ts
-/**
-* Create a deep mock proxy for a given type.
-* Wraps `vitest-mock-extended`'s `mockDeep` for convenient port mocking.
-*/
-const mockOf = mockDeep;
+function mockOf(options) {
+	return options?.deep === false ? mock() : mockDeep();
+}
 //#endregion
 //#region src/vitest/mock-of-date.ts
 /**
@@ -935,6 +1046,132 @@ const mockOf = mockDeep;
 */
 const mockOfDate = MockDatePackage;
 //#endregion
+//#region src/vitest/clock.ts
+/** The instant `iso` names, or a refusal that says what an instant looks like. */
+function instantOf(method, iso) {
+	const at = new Date(iso);
+	if (Number.isNaN(at.getTime())) throw new TypeError(`clock.${method}(): "${iso}" is not an instant — pass an ISO-8601 string (e.g. '2026-03-04T09:30:00Z').`);
+	return at;
+}
+/**
+* One clock per test — a second one taken inside the first is refused rather
+* than nested.
+*
+* Disposing gives the REAL clock back, which is the only thing vitest's fake
+* timers can restore: the instant, the `toFake` set and the queue a previous
+* scope held are not readable, so an inner scope that ended would silently end
+* the outer one too. A refusal says which of the two the test meant.
+*/
+function take(method, options) {
+	if (vi.isFakeTimers()) throw new Error(`clock.${method}(): a clock is already pinned — one scope per test. End the first scope before taking another, or state the instant on the chain (\`.clock(iso)\`) rather than around it.`);
+	vi.useFakeTimers(options);
+	return { [Symbol.dispose]: () => {
+		vi.useRealTimers();
+	} };
+}
+const clock = {
+	/**
+	* Move the pinned clock forward by `ms` — and, under {@link clock.run},
+	* fire every callback that came due, awaiting what each of them started.
+	*
+	* Only a pinned clock moves: called with no clock taken, it says so rather
+	* than silently doing nothing to the real one.
+	*/
+	async advance(ms) {
+		if (!vi.isFakeTimers()) throw new Error("clock.advance(): no clock is pinned — take one first with `using _ = clock.at('<iso>')` (the calendar) or `using _ = clock.run()` (the scheduler).");
+		await vi.advanceTimersByTimeAsync(ms);
+	},
+	/**
+	* Pin `Date` at `iso` for the current scope. `Date` ONLY: the scheduler
+	* stays real, so a subject that awaits, renders or polls keeps running.
+	*
+	* @example
+	*   using _ = clock.at('2026-03-04T09:30:00Z');
+	*   expect(stampedAt()).toBe('2026-03-04T09:30:00.000Z');
+	*/
+	at(iso) {
+		return take("at", {
+			now: instantOf("at", iso),
+			toFake: ["Date"]
+		});
+	},
+	/**
+	* Take the scheduler as well as the calendar: `setTimeout`, `setInterval`
+	* and their friends queue instead of firing, and {@link clock.advance} is
+	* what makes them due. For a subject whose behaviour IS elapsed time — a
+	* debounce, a retry backoff, a poll — where waiting for real would be the
+	* arbitrary sleep J2 forbids.
+	*
+	* @example
+	*   using _ = clock.run('2026-03-04T09:30:00Z');
+	*   const pending = retrying(failsTwice);
+	*   await clock.advance(5_000);
+	*   await expect(pending).resolves.toBe('ok');
+	*/
+	run(iso) {
+		return take("run", iso === void 0 ? {} : { now: instantOf("run", iso) });
+	}
+};
+//#endregion
+//#region src/specification/assertions/required.ts
+/**
+* The value, or a failure that says what was missing and why it mattered.
+*
+* A test reaching into a captured structure — a row, a header, the third
+* element of a list — meets `T | undefined` and has to do something about it.
+* The two things it usually does are both wrong: `!` erases the question, and
+* an `if (!x) throw new Error('missing')` re-states the same three lines in
+* every repository (the estate had two hand-written copies of exactly this).
+* `required` is that gesture with the reason attached, so the failure reads as
+* a sentence rather than as a `TypeError` two frames further down.
+*
+* @example
+*   const id = required(result.response.body.id, 'the creation reply carries the new id');
+*/
+function required(value, why) {
+	if (value === null || value === void 0) throw new Error(`required(): ${why} — got ${value === null ? "null" : "undefined"}. State it in the Given, or assert on what the subject actually produced.`);
+	return value;
+}
+//#endregion
+//#region src/specification/assertions/wait-until.ts
+const DEFAULT_TIMEOUT_MS = 5e3;
+const DEFAULT_INTERVAL_MS = 50;
+/**
+* Wait until a condition holds — the sanctioned answer to "the thing I am
+* specifying is not ready yet".
+*
+* A spec that sleeps for a guessed duration is a spec that is slow on a fast
+* machine and flaky on a slow one, which is why J2 refuses `setTimeout` under
+* `specs/`. Every facet that drives something already waits on a CONDITION —
+* a served page, a banner on stdout, an element the visitor can see — and this
+* is that primitive where no facet owns the waiting: a background write to
+* land, a queue to drain, a file to appear.
+*
+* The failure names the condition and how long it was given, so a timeout is a
+* sentence rather than "expected true, got false".
+*
+* The budget is measured on `performance.now()`, not on `Date` — `clock.at()`
+* freezes the calendar, and a deadline read off a frozen calendar never
+* arrives: the poll would run until vitest killed the test with a sentence
+* about the file rather than about the condition.
+*
+* Not for a subject under `clock.run()`: there the scheduler is the test's, and
+* `clock.advance(ms)` is what makes time pass.
+*
+* @example
+*   await waitUntil(() => outbox.length === 1, { why: 'the job wrote its one message' });
+*/
+async function waitUntil(predicate, options = {}) {
+	const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+	const interval = options.interval ?? DEFAULT_INTERVAL_MS;
+	const deadline = performance.now() + timeout;
+	for (;;) {
+		if (await predicate()) return;
+		if (performance.now() >= deadline) throw new Error(`waitUntil(): ${options.why ?? "the condition"} did not hold within ${timeout}ms. Raise the budget if the wait is legitimate, or wait on what actually changes.`);
+		await pause(interval);
+	}
+}
+//#endregion
 //#region src/integrations/hono/hono.adapter.ts
 /**
 * Server adapter that dispatches requests in-process through a Hono app instance.
@@ -1210,7 +1447,7 @@ function matchStreamFile(accessor, name, frozen) {
 		writeFileSync(filePath, merged);
 		return PASS(`updated ${GROUND_EXPECTED}/${name}`);
 	}
-	if (!existsSync(filePath)) return FAIL(`${accessor.streamName} fixture "${name}" does not exist at ${filePath}.\n${UPDATE_HINT}`);
+	if (!existsSync(filePath)) return FAIL(`${accessor.streamName} fixture "${name}" does not exist at ${filePath}.\n${missingHint(frozen)}`);
 	return compareStreamText(accessor, name, readFileSync(filePath, "utf8"));
 }
 function matchJsonFile(accessor, name, frozen) {
@@ -1223,7 +1460,7 @@ function matchJsonFile(accessor, name, frozen) {
 		writeFileSync(filePath, formatJson(merged));
 		return PASS(`updated ${GROUND_EXPECTED}/${name}`);
 	}
-	if (!existsSync(filePath)) return FAIL(`JSON fixture "${name}" does not exist at ${filePath}.\n${UPDATE_HINT}`);
+	if (!existsSync(filePath)) return FAIL(`JSON fixture "${name}" does not exist at ${filePath}.\n${missingHint(frozen)}`);
 	const expected = JSON.parse(readFileSync(filePath, "utf8"));
 	if (structuralEquals(expected, actual, accessor.captures)) return PASS(`expected JSON not to match ${GROUND_EXPECTED}/${name}`);
 	return FAIL(formatResponseDiff(name, renderExpected(expected), actual));
@@ -1279,7 +1516,7 @@ function matchResponseFile(accessor, name, frozen) {
 		writeFileSync(filePath, serializeResponseFile(updated));
 		return PASS(`updated ${GROUND_EXPECTED}/${name}`);
 	}
-	if (!existsSync(filePath)) return FAIL(`Response fixture "${name}" does not exist at ${filePath}.\n${UPDATE_HINT}`);
+	if (!existsSync(filePath)) return FAIL(`Response fixture "${name}" does not exist at ${filePath}.\n${missingHint(frozen)}`);
 	const failure = compareResponse(name, parseResponseFile(readFileSync(filePath, "utf8"), `${GROUND_EXPECTED}/${name}`), accessor, accessor.captures);
 	return failure === null ? PASS(`expected response not to match ${GROUND_EXPECTED}/${name}`) : FAIL(failure);
 }
@@ -1302,7 +1539,7 @@ async function matchTreeFile(actualRoot, testDir, name, scope, frozen) {
 		}
 		return PASS(`updated ${GROUND_EXPECTED}/${name}/`);
 	}
-	if (!existsSync(fixtureDir)) return FAIL(`Directory fixture "${name}" does not exist at ${fixtureDir}.\n${UPDATE_HINT}`);
+	if (!existsSync(fixtureDir)) return FAIL(`Directory fixture "${name}" does not exist at ${fixtureDir}.\n${missingHint(frozen)}`);
 	const diff = await diffDirectories(fixtureDir, actualRoot, { scope });
 	if (diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0) return PASS(`expected directory not to match ${GROUND_EXPECTED}/${name}/`);
 	return FAIL(formatDirectoryDiff(name, diff, "Run with TEST_UPDATE=1 to update the fixture."));
@@ -1347,8 +1584,15 @@ function toContain(received, expected) {
 	if (received instanceof TextAccessor) return textContains(received, String(expected));
 	return nativeContain(received, expected);
 }
+/** Is this the shape, before the adapter is asked to build SQL from it? */
+function isRowsExpectation(expected) {
+	if (expected === null || typeof expected !== "object") return false;
+	const { columns, rows } = expected;
+	return Array.isArray(columns) && Array.isArray(rows);
+}
 async function toMatchRows(received, expected) {
 	if (!(received instanceof TableAccessor)) throw new TypeError("toMatchRows: unsupported subject — expected result.table(...).");
+	if (!isRowsExpectation(expected)) throw new TypeError(`toMatchRows takes { columns, rows } — a column list and one array of cells per row (received ${Array.isArray(expected) ? "an array" : `a ${typeof expected}`}).`);
 	const actual = await received.query(expected.columns);
 	const pass = actual.length === expected.rows.length && expected.rows.every((row, i) => {
 		const actualRow = actual[i];
@@ -1423,6 +1667,61 @@ var HttpResult = class extends BaseResult {
 	}
 };
 //#endregion
+//#region src/specification/facets/integration/result.ts
+/**
+* The result of an in-process call — the integration facet's whole surface.
+*
+* Two readings, never both: `value` is what the call RETURNED, `error` is
+* what it THREW. A module that refuses is specified the same way a module
+* that answers is, and neither needs a `try`/`catch` in the test — which is
+* the shape that used to make a refusal spec three times the size of the
+* happy one, and the shape that quietly passes when nothing throws at all.
+*
+* Both are the package's ordinary accessors, so the golden mechanism reaches
+* them, and `Returned` is what `.call<T>()` returned — `result.value.value` is
+* that type, not `unknown`, so a one-field reading needs no golden file: `toMatch('<name>.json'|'<name>.txt')`, the `{{token}}` grammar,
+* `{ frozen }` and `TEST_UPDATE=1` all work here exactly as on an HTTP
+* response or a command's stdout.
+*/
+var CallResult = class extends BaseResult {
+	outcome;
+	constructor(options) {
+		super(options);
+		this.outcome = options.outcome;
+	}
+	/**
+	* What the call THREW, as text — the message of an `Error`, the value
+	* itself when something else was thrown, and empty when it returned.
+	*
+	* Empty rather than absent on purpose: `await expect(result.error).toBeEmpty()`
+	* is how a spec says "and it did not refuse" — awaited, because the
+	* matcher answers a promise on every subject it takes, and a dropped one
+	* passes the test while the failure surfaces as an unhandled rejection
+	* (D2 refuses the bare form).
+	*/
+	get error() {
+		return new TextAccessor(describeError(this.outcome), "error", this.testDir, { captures: this.captures });
+	}
+	/**
+	* What the call RETURNED. A string reads as a stream (`<name>.txt`),
+	* anything else as JSON (`<name>.json`) — the same two subjects every
+	* other facet's results are built from.
+	*
+	* A call that threw returns the empty value: what it produced is
+	* {@link CallResult.error}.
+	*/
+	get value() {
+		const produced = this.outcome.threw ? null : this.outcome.value;
+		return typeof produced === "string" ? new TextAccessor(produced, "value", this.testDir, { captures: this.captures }) : new JsonAccessor(JSON.stringify(produced ?? null), this.testDir, void 0, this.captures);
+	}
+};
+/** The thrown thing, as the text a golden compares. */
+function describeError(outcome) {
+	if (!outcome.threw) return "";
+	const { error } = outcome;
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
 //#region src/specification/facets/mobile/result.ts
 /** Result from a `.open()` action — the screen as the device saw it, final state. */
 var ScreenResult = class extends BaseResult {
@@ -1713,6 +2012,7 @@ function getCallerDir() {
 * only surfaces the methods that make sense for it.
 */
 var SpecificationBuilder = class {
+	pinnedClock = null;
 	commandEnv = {};
 	config;
 	contracts = [];
@@ -1725,6 +2025,22 @@ var SpecificationBuilder = class {
 		this.testDir = testDir;
 	}
 	/**
+	* Pin the clock at `iso` for this chain.
+	*
+	* In-process facets (api, jobs, integration) pin the runner's own `Date`,
+	* which is the app's; a website visit pins the PAGE's, through the browser.
+	* Either way the clock is released when the action resolves, so a chain
+	* never leaks its instant into the next one (CONVENTIONS D16).
+	*
+	* @example
+	*   const result = await api.clock('2026-03-04T09:30:00Z').get('/now');
+	*/
+	clock(iso) {
+		if (this.config.clockDisabledReason !== void 0) throw new Error(`.clock(): ${this.config.clockDisabledReason}`);
+		this.pinnedClock = iso;
+		return this;
+	}
+	/**
 	* Queue a SQL seed file to run before the action.
 	*
 	* With two or more declared databases the `database` option is mandatory;
@@ -1925,6 +2241,7 @@ var SpecificationBuilder = class {
 	*   expect(result.body).toMatch('robots.txt');
 	*/
 	async fetch(path) {
+		if (this.pinnedClock !== null) throw new Error(".clock() pins the clock of a PAGE, and .fetch() opens none — it is one raw HTTP exchange. Assert the moment with a token ({{iso8601}}) in the golden, or visit the page.");
 		return await this.executeSetup(null, async () => await this.runFetchAction(path));
 	}
 	/**
@@ -1964,6 +2281,22 @@ var SpecificationBuilder = class {
 		return await this.executeSetup(null, async () => await this.runOpenAction(deepLink, scenario));
 	}
 	/**
+	* Call the module under test and resolve with what it produced — the
+	* value it returned, or the error it threw.
+	*
+	* A refusal is a reading, never a `try`/`catch`: `result.error` carries
+	* what was thrown, and `result.value` what was returned. That is what
+	* keeps a spec of a refusal the same size as a spec of a success, and
+	* what stops a "it should throw" spec from passing when nothing does.
+	*
+	* @example
+	*   const result = await integration.seed('rows.sql').call(({ db }) => find(db.connectionString, id));
+	*   expect(result.value).toMatch('found.json');
+	*/
+	async call(subject) {
+		return await this.executeSetup(null, async () => await this.runCallAction(subject));
+	}
+	/**
 	* Execute the named job registered via the `jobs` option of
 	* `specification.jobs()` and resolve with the result.
 	*
@@ -2007,6 +2340,8 @@ var SpecificationBuilder = class {
 			const { registerContracts } = await import("./intercept.js");
 			registration = await registerContracts(this.contracts);
 		}
+		const instant = this.pinnedClock;
+		const pinned = instant !== null && this.config.baseUrl === void 0 ? clock.at(instant) : null;
 		try {
 			const value = await action();
 			const violation = registration?.violation() ?? this.config.backend?.violation();
@@ -2015,6 +2350,7 @@ var SpecificationBuilder = class {
 		} catch (error) {
 			throw registration?.violation() ?? this.config.backend?.violation() ?? error;
 		} finally {
+			pinned?.[Symbol.dispose]();
 			registration?.cleanup();
 		}
 	}
@@ -2025,6 +2361,28 @@ var SpecificationBuilder = class {
 	prepareWorkDir() {
 		return mkdtempSync(resolve(tmpdir(), "spec-command-"));
 	}
+	async runCallAction(subject) {
+		const services = this.config.services ?? {};
+		let outcome;
+		try {
+			outcome = {
+				error: null,
+				threw: false,
+				value: await subject(services)
+			};
+		} catch (error) {
+			outcome = {
+				error,
+				threw: true,
+				value: null
+			};
+		}
+		return new CallResult({
+			config: this.config,
+			outcome,
+			testDir: this.testDir
+		});
+	}
 	async runHttpAction(request) {
 		if (!this.config.server) throw new Error("HTTP actions require a server adapter (use specification.api())");
 		let { body, method, path } = request;
@@ -2076,6 +2434,7 @@ var SpecificationBuilder = class {
 		const page = await browser.open(`${baseUrl}${path}`, {
 			allowedOrigins: this.config.backendUrl ? [new URL(this.config.backendUrl).origin] : void 0,
 			baseUrl,
+			...this.pinnedClock === null ? {} : { clock: this.pinnedClock },
 			external: this.config.external ?? "allow",
 			headers,
 			scenario
@@ -2145,7 +2504,11 @@ var SpecificationBuilder = class {
 	* the chain's own `.env()` — which always wins, `null` unsetting.
 	*/
 	childEnv(workDir) {
-		let env = this.serviceEnv();
+		const declared = this.config.defaultEnv;
+		let env = declared ? {
+			...expandWorkdir(declared, workDir),
+			...this.serviceEnv()
+		} : this.serviceEnv();
 		const { dockerConfig } = this.config;
 		if (dockerConfig && this.config.dockerTestRunId) env = {
 			...env,
@@ -2221,6 +2584,7 @@ function withDockerTestRunId(config) {
 function createApiFacet(config) {
 	const start = () => new SpecificationBuilder(config, getCallerDir());
 	return {
+		clock: (iso) => start().clock(iso),
 		delete: async (path) => await start().delete(path),
 		get: async (path) => await start().get(path),
 		headers: (headers) => start().headers(headers),
@@ -2237,17 +2601,31 @@ function createApiFacet(config) {
 function createJobsFacet(config) {
 	const start = () => new SpecificationBuilder(config, getCallerDir());
 	return {
+		clock: (iso) => start().clock(iso),
 		intercept: interceptOn(start),
 		seed: (file, options) => start().seed(file, options),
 		trigger: async (name) => await start().trigger(name)
 	};
 }
 /**
+* Create the `integration` facet bound to the given adapter configuration.
+*/
+function createIntegrationFacet(config) {
+	const start = () => new SpecificationBuilder(config, getCallerDir());
+	return {
+		call: async (subject) => await start().call(subject),
+		clock: (iso) => start().clock(iso),
+		intercept: interceptOn(start),
+		seed: (file, options) => start().seed(file, options)
+	};
+}
+/**
 * Create the `website` facet bound to the given adapter configuration.
 */
 function createWebsiteFacet(config) {
 	const start = () => new SpecificationBuilder(config, getCallerDir());
 	return {
+		clock: (iso) => start().clock(iso),
 		fetch: async (path) => await start().fetch(path),
 		headers: (headers) => start().headers(headers),
 		intercept: interceptOn(start),
@@ -2561,6 +2939,124 @@ var Orchestrator = class {
 	}
 };
 //#endregion
+//#region src/specification/facets/_common/process.ts
+/**
+* An external process, declared like any other service.
+*
+* Before this there were three shapes for the same thing: `website({ server })`
+* took a `ServeOptions`, a literate document took a `serve:` entry, and a
+* project that needed a second process — an API behind the site, Metro behind
+* the simulator — started one by hand in a `beforeAll` and killed it in an
+* `afterAll` it sometimes forgot. `process()` is the one shape, and the
+* framework owns the lifetime.
+*
+* It sits in a `services` record beside `postgres()`, `redis()` and
+* `sqlite()`, so it starts after them and can be handed their connection
+* strings through `env`, and it is stopped with the specification.
+*/
+var ProcessHandle = class {
+	/** Embedded: nothing to pull, nothing to run in a container. */
+	defaultImage = "";
+	defaultPort = 0;
+	environment = {};
+	type = "process";
+	composeName = null;
+	connectionString = "";
+	started = false;
+	adapter = null;
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	buildConnectionString(host, port) {
+		return `http://${host}:${port}`;
+	}
+	createDatabaseAdapter() {
+		return null;
+	}
+	async healthcheck() {
+		await Promise.resolve();
+	}
+	/**
+	* A process is not a container, so the orchestrator never starts it: the
+	* facet does, once its siblings are up and their connection strings are
+	* readable ({@link startProcessServices}).
+	*/
+	async initialize() {
+		await Promise.resolve();
+	}
+	/**
+	* Isolation is the RUN's, not the worker's — and a run here is one
+	* EVALUATION of the specification module. Under vitest's default
+	* isolation that is once per test file, so two files that import the same
+	* specification get a child each, with the id the facet minted for it.
+	* Nothing is acquired or reset between tests: the id is what tells two
+	* runs apart, never a label a spec samples.
+	*/
+	isolation() {
+		return {
+			acquire: async () => {
+				await Promise.resolve();
+			},
+			release: async () => {
+				await Promise.resolve();
+			},
+			reset: async () => {
+				await Promise.resolve();
+			}
+		};
+	}
+	async reset() {
+		await Promise.resolve();
+	}
+	/**
+	* Spawn it and wait until it answers. `services` is every handle declared
+	* beside this one, already started — what an `env` function reads.
+	*
+	* @internal
+	*/
+	async spawnWith(root, services, runId) {
+		const stated = typeof this.options.env === "function" ? this.options.env(services) : this.options.env;
+		this.adapter = new ServeAdapter(this.options, root, "process", {
+			...stated,
+			TEST_RUN_ID: runId
+		});
+		this.connectionString = await this.adapter.start();
+		this.started = true;
+	}
+	/** Terminate the process group. Idempotent. */
+	async shutdown() {
+		await this.adapter?.stop();
+		this.adapter = null;
+		this.started = false;
+	}
+	/** What it was declared as — what a facet reads to start it in a slot of its own. */
+	get spec() {
+		return this.options;
+	}
+	/** The base URL it came up on — known only once it is started. */
+	get url() {
+		if (!this.started) throw new Error("process(): the URL is known once the process is ready — read it from the started services record, never at declaration time.");
+		return this.connectionString;
+	}
+};
+/**
+* Declare an external process the framework owns for the life of the
+* specification.
+*
+* @example
+*   const { website, cleanup } = await specification.website({
+*       services: { api: process({ command: 'bin/server web', ready: '/health' }) },
+*       server: ({ api }) => process({
+*           command: 'next dev',
+*           env: { NEXT_PUBLIC_API_URL: api.connectionString },
+*       }),
+*   });
+*/
+function processService(options) {
+	return new ProcessHandle(options);
+}
+//#endregion
 //#region src/specification/facets/_common/services.ts
 function getWorkerId() {
 	return process.env.VITEST_POOL_ID ?? "0";
@@ -2575,20 +3071,64 @@ async function releaseIsolation(services) {
 function declaredDatabaseKeys(services) {
 	return Object.entries(services).filter(([, service]) => service.createDatabaseAdapter() !== null).map(([key]) => key);
 }
+/**
+* A process is not a container: the orchestrator never sees one, and the
+* facet starts it AFTER the rest, so an `env` function reads connection
+* strings that are already there.
+*/
+function splitProcesses(services) {
+	const infrastructure = {};
+	const processes = [];
+	for (const [key, handle] of Object.entries(services)) if (handle instanceof ProcessHandle) processes.push([key, handle]);
+	else infrastructure[key] = handle;
+	return {
+		infrastructure,
+		processes
+	};
+}
+/**
+* Start every declared process, in declaration order, once the infrastructure
+* is up — so `env: ({ db }) => …` reads a connection string that exists. Each
+* carries the run's id, minted here: a label a spec would otherwise sample
+* from `Date.now()` and put under an oracle (CONVENTIONS D16, P7).
+*
+* @internal
+*/
+async function startProcessServices(services, root, runId) {
+	const { processes } = splitProcesses(services);
+	const started = [];
+	const stop = async () => {
+		for (const handle of started.toReversed()) await handle.shutdown();
+		started.length = 0;
+	};
+	for (const [, handle] of processes) try {
+		await handle.spawnWith(root, services, runId);
+		started.push(handle);
+	} catch (error) {
+		await stop();
+		throw error;
+	}
+	return stop;
+}
 /** Start a services record via testcontainers and acquire worker isolation. */
 async function startServices(services, root) {
+	const { infrastructure } = splitProcesses(services);
 	const orchestrator = new Orchestrator({
 		mode: "integration",
 		root,
-		services
+		services: infrastructure
 	});
 	await orchestrator.start();
-	await acquireIsolation(services);
+	await acquireIsolation(infrastructure);
+	const runId = randomUUID();
+	const stopProcesses = await startProcessServices(services, root, runId);
 	const databases = orchestrator.getDatabases();
 	return {
 		database: orchestrator.getDatabase() ?? void 0,
 		databases: databases.size > 0 ? databases : void 0,
-		orchestrator
+		orchestrator,
+		runId,
+		stopProcesses
 	};
 }
 //#endregion
@@ -2678,7 +3218,7 @@ async function startApi(options) {
 	const databaseKeys = declaredDatabaseKeys(services);
 	if (mode === "node") {
 		if (!options.server) throw new Error("specification.api(): 'server' is required in node mode — provide server: (services) => app, or run in compose mode (TEST_MODE=compose).");
-		const { database, databases, orchestrator } = await startServices(services, root);
+		const { database, databases, orchestrator, stopProcesses } = await startServices(services, root);
 		return {
 			api: createApiFacet({
 				database,
@@ -2687,6 +3227,7 @@ async function startApi(options) {
 				server: new HonoAdapter(options.server(services))
 			}),
 			cleanup: async () => {
+				await stopProcesses();
 				await releaseIsolation(services);
 				await orchestrator.stop();
 			},
@@ -2709,6 +3250,7 @@ async function startApi(options) {
 			database: orchestrator.getDatabase() ?? void 0,
 			databaseKeys,
 			databases: databases.size > 0 ? databases : void 0,
+			clockDisabledReason: "the calendar it pins is this runner's, and compose mode runs the app in a container — assert the stamp with a `{{iso8601}}` token instead.",
 			interceptDisabledReason: "intercepts are in-process (MSW) and not available in compose mode — keep intercept specs in node-only vitest projects.",
 			server: new FetchAdapter(appUrl)
 		}),
@@ -2887,6 +3429,7 @@ async function startCli(bin, options = {}) {
 	if (Object.keys(services).length > 0) started = await startServices(services, root);
 	return {
 		cleanup: async () => {
+			await started?.stopProcesses();
 			await releaseIsolation(services);
 			if (started) await started.orchestrator.stop();
 		},
@@ -2896,6 +3439,7 @@ async function startCli(bin, options = {}) {
 			databaseKeys,
 			databases: started?.databases,
 			dockerConfig: options.docker,
+			defaultEnv: options.defaults,
 			envSets: options.env,
 			root,
 			serveRegistry: options.serve,
@@ -2907,6 +3451,42 @@ async function startCli(bin, options = {}) {
 	};
 }
 //#endregion
+//#region src/specification/facets/integration/start-integration.ts
+/**
+* Specify a module the way the assembled product is specified: against real
+* services and declared contracts, with the golden mechanism on what it
+* produces.
+*
+* The fork is the SUBJECT. A module alone is a module test, beside its code,
+* with no runner at all. A module that needs a real database, or whose oracle
+* is a golden file, is this — and it used to be neither: a `specs/` folder
+* with plain vitest, a hand-built sqlite template, a `beforeAll` that started
+* a container, and a `toMatchSnapshot` where the package has a golden engine.
+*/
+async function startIntegration(options = {}) {
+	const callerDir = getCallerDir();
+	await registerMatchers();
+	const root = resolveRoot(options.root, callerDir);
+	const services = options.services ?? {};
+	const databaseKeys = declaredDatabaseKeys(services);
+	let started = null;
+	if (Object.keys(services).length > 0) started = await startServices(services, root);
+	return {
+		cleanup: async () => {
+			await started?.stopProcesses();
+			await releaseIsolation(services);
+			if (started) await started.orchestrator.stop();
+		},
+		integration: createIntegrationFacet({
+			database: started?.database,
+			databaseKeys,
+			databases: started?.databases,
+			root,
+			services
+		})
+	};
+}
+//#endregion
 //#region src/specification/facets/jobs/start-jobs.ts
 async function startJobs(options) {
 	const callerDir = getCallerDir();
@@ -2919,6 +3499,7 @@ async function startJobs(options) {
 	const jobHandles = typeof options.jobs === "function" ? options.jobs(services) : options.jobs;
 	return {
 		cleanup: async () => {
+			await started?.stopProcesses();
 			await releaseIsolation(services);
 			if (started) await started.orchestrator.stop();
 		},
@@ -3067,6 +3648,22 @@ var StubBackend = class {
 		if (reply.delay) await new Promise((resolve) => setTimeout(resolve, reply.delay));
 		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,
@@ -3231,6 +3828,14 @@ async function startMobile(options) {
 	const udid = options.device.udid ?? await resolveSimulatorUdid(options.device);
 	await ensureBooted(udid);
 	const appium = await startAppiumServer(root);
+	const services = options.services ?? {};
+	let started = null;
+	if (Object.keys(services).length > 0) try {
+		started = await startServices(services, root);
+	} catch (error) {
+		await appium.stop();
+		throw error;
+	}
 	let backend = null;
 	let backendUrl;
 	if (options.backend) {
@@ -3262,6 +3867,11 @@ async function startMobile(options) {
 				await device.close();
 				device = null;
 			}
+			if (started) {
+				await started.stopProcesses();
+				await releaseIsolation(services);
+				await started.orchestrator.stop();
+			}
 			await appium.stop();
 			if (backend) await backend.stop();
 		},
@@ -3271,6 +3881,66 @@ async function startMobile(options) {
 }
 //#endregion
 //#region src/specification/facets/website/start-website.ts
+/**
+* The declared shape, whichever of the three forms stated it — with an `env`
+* function resolved against the services that are already up, so the site is
+* handed the URL of the API it was started beside.
+*/
+function resolveServer(server, services) {
+	const stated = typeof server === "function" ? server(services) : server;
+	const spec = stated instanceof ProcessHandle ? stated.spec : stated;
+	if (typeof spec.env !== "function") return spec;
+	return {
+		...spec,
+		env: spec.env(services)
+	};
+}
+/**
+* Start the declared record, if there is one. A record that fails to come up
+* must not orphan the stub that was started before it.
+*/
+async function startDeclared(services, root, backend) {
+	if (Object.keys(services).length === 0) return null;
+	try {
+		return await startServices(services, root);
+	} catch (error) {
+		await backend?.stop();
+		throw error;
+	}
+}
+/**
+* Start the site, or take the URL of a deployed one. A server that never came
+* up must not orphan the stub, nor the services it was started beside.
+*/
+async function startSite(options, context) {
+	if (!options.server) return {
+		baseUrl: (options.url ?? "").replace(/\/$/u, ""),
+		serve: null
+	};
+	const serve = new ServeAdapter(resolveServer(options.server, context.services), context.root, "website", {
+		TEST_RUN_ID: context.started?.runId ?? randomUUID(),
+		...serverBackendEnv(options.backend, context.backendUrl)
+	});
+	try {
+		return {
+			baseUrl: await serve.start(),
+			serve
+		};
+	} catch (error) {
+		await context.started?.stopProcesses();
+		await context.started?.orchestrator.stop();
+		await context.backend?.stop();
+		throw error;
+	}
+}
+/** The stub's URL in the child's environment, under the name the caller chose. */
+function serverBackendEnv(backend, backendUrl) {
+	return backend && backendUrl !== void 0 ? { [backend.env]: backendUrl } : {};
+}
+/** The declared record, or the empty one — a website may have no services. */
+function servicesOf(options) {
+	return options.services ?? {};
+}
 async function startWebsite(options) {
 	const callerDir = getCallerDir();
 	await registerMatchers();
@@ -3281,18 +3951,16 @@ async function startWebsite(options) {
 		backend = new StubBackend({ port: options.backend.port });
 		backendUrl = await backend.start();
 	}
-	let serve = null;
-	let baseUrl;
-	if (options.server) {
-		const root = resolveRoot(options.root, callerDir);
-		serve = new ServeAdapter(options.server, root, "website", options.backend && backendUrl !== void 0 ? { [options.backend.env]: backendUrl } : {});
-		try {
-			baseUrl = await serve.start();
-		} catch (error) {
-			await backend?.stop();
-			throw error;
-		}
-	} else baseUrl = options.url.replace(/\/$/u, "");
+	const services = servicesOf(options);
+	const root = resolveRoot(options.root, callerDir);
+	const started = await startDeclared(services, root, backend);
+	const { baseUrl, serve } = await startSite(options, {
+		backend,
+		backendUrl,
+		root,
+		services,
+		started
+	});
 	let browser = null;
 	const getBrowser = async () => {
 		if (!browser) {
@@ -3301,13 +3969,6 @@ async function startWebsite(options) {
 		}
 		return browser;
 	};
-	const config = {
-		backend: backend ?? void 0,
-		backendUrl,
-		baseUrl,
-		browser: getBrowser,
-		external: options.external ?? (options.server ? "block" : "allow")
-	};
 	return {
 		cleanup: async () => {
 			if (browser) {
@@ -3315,10 +3976,21 @@ async function startWebsite(options) {
 				browser = null;
 			}
 			if (serve) await serve.stop();
+			if (started) {
+				await started.stopProcesses();
+				await releaseIsolation(services);
+				await started.orchestrator.stop();
+			}
 			if (backend) await backend.stop();
 		},
 		url: baseUrl,
-		website: createWebsiteFacet(config)
+		website: createWebsiteFacet({
+			backend: backend ?? void 0,
+			backendUrl,
+			baseUrl,
+			browser: getBrowser,
+			external: options.external ?? (options.server ? "block" : "allow")
+		})
 	};
 }
 //#endregion
@@ -3339,6 +4011,13 @@ const specification = {
 	*/
 	cli: startCli,
 	/**
+	* Specify a module against the real thing: a database, a cache, a
+	* `process()` it talks to — or nothing at all, when its oracle is a
+	* golden. `.call((services) => …)` is the terminal action, and what it
+	* produced is read as `result.value` or, when it refused, `result.error`.
+	*/
+	integration: startIntegration,
+	/**
 	* Test background jobs. Jobs run in-process by definition — no HTTP
 	* server, no mode. `.trigger(name)` is the terminal action.
 	*/
@@ -3734,6 +4413,14 @@ function sqlite(options = {}) {
 }
 //#endregion
 //#region src/index.ts
+/**
+* The module-scope network double, on msw's node server — what a test with no
+* chain to hang contracts on reaches for (chapter 10).
+*/
+const intercept = interceptThrough(async (contracts) => {
+	const { registerContracts } = await import("./intercept.js");
+	return await registerContracts(contracts);
+});
 registerContainerIntegrations({
 	createComposeStack: (composeFile, projectName) => new ComposeStackAdapter(composeFile, projectName),
 	createContainer: (options) => new TestcontainersAdapter(options),
@@ -3745,4 +4432,4 @@ registerComposeServiceFactory("postgres", (service) => postgres({
 }));
 registerComposeServiceFactory("redis", (service) => redis({ composeService: service.name }));
 //#endregion
-export { BaseResult, CliResult, ContainerAccessor, DirectoryAccessor, FetchResult, FilesystemAccessor, HttpResult, JsonAccessor, Matcher, Orchestrator, PageResult, ResponseAccessor, ScreenResult, TableAccessor, TextAccessor, anthropic, banner, button, complementary, component, content, contentinfo, defineContract, defineContracts, dialog, disabled, enabled, field, findContainersByLabel, focused, form, heading, http, inspectContainer, link, listitem, main, match, mockOf, mockOfDate, navigation, openai, option, postgres, redis, region, removeContainers, row, search, selected, specification, sqlite, status, table, testId, text, valued, within };
+export { BaseResult, CallResult, CliResult, ContainerAccessor, DirectoryAccessor, FetchResult, FilesystemAccessor, HttpResult, JsonAccessor, Matcher, Orchestrator, PageResult, ProcessHandle, ResponseAccessor, ScreenResult, TableAccessor, TextAccessor, anthropic, banner, button, clock, complementary, component, content, contentinfo, defineContract, defineContracts, dialog, disabled, enabled, field, findContainersByLabel, focused, form, heading, http, inspectContainer, intercept, link, listitem, main, match, mockOf, mockOfDate, navigation, openai, option, postgres, processService as process, redis, region, removeContainers, required, row, search, selected, specification, sqlite, status, table, testId, text, valued, waitUntil, within };