@jterrazz/test 15.2.0 → 16.0.0

package/dist/index.js

@@ -1,401 +1,335 @@
-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 { i as match, n as Matcher, t as CaptureScope } from "./match.js";
+import { i as GROUND_EXPECTED, o as GROUND_REQUESTS, s as GROUND_SEEDS, t as copyPlan } from "./fixtures.js";
+import { a as SQLITE_TEMPLATE_DIR } from "./artifacts.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 { C as FilesystemAccessor, E as walkDirectory, M as structuralEquals, N as structuralSubset, O as mergePreservingPlaceholders, P as textEquals, S as TextAccessor, T as diffDirectories, _ as discoverRoot, a as ServeAdapter, b as resolveRoot, c as formatStartupReport, d as ContainerAccessor, f as CliResult, g as TableAccessor, h as validateDatabaseOption, i as shouldUpdateSnapshots, j as renderExpected, k as mergeTextPreservingPlaceholders, l as formatStdoutDiff, m as BaseResult, o as formatDirectoryDiff, p as inspectContainer, r as missingHint, s as formatResponseDiff, t as runSpecDocument, u as formatTableDiff, v as expandWorkdir, w as DirectoryAccessor, x as JsonAccessor, y as resolveCommand } from "./literate.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 MockDatePackage from "mockdate";
-import { tmpdir } from "node:os";
+import { execFile, spawn, spawnSync } from "node:child_process";
+import { mock, mockDeep } from "vitest-mock-extended";
+import { vi } from "vitest";
 import "node:url";
+import { createHash, randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
 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.
-*/
-function parseComposeFile(filePath) {
-	const doc = parse(readFileSync(filePath, "utf8"));
-	if (!doc?.services) return {
-		services: [],
-		appService: null,
-		infraServices: []
-	};
-	const services = Object.entries(doc.services).map(([name, def]) => {
-		const ports = [];
-		if (def.ports) for (const port of def.ports) {
-			const str = String(port);
-			if (str.includes(":")) {
-				const [host, container] = str.split(":");
-				ports.push({
-					container: Number(container),
-					host: Number(host)
-				});
-			} else ports.push({ container: Number(str) });
-		}
-		const environment = {};
-		if (def.environment) if (Array.isArray(def.environment)) for (const env of def.environment) {
-			const [key, ...rest] = String(env).split("=");
-			if (key !== void 0) environment[key] = rest.join("=");
-		}
-		else Object.assign(environment, def.environment);
-		const volumes = def.volumes ? def.volumes.map((v) => String(v)) : [];
-		let dependsOn = [];
-		if (def.depends_on) dependsOn = Array.isArray(def.depends_on) ? def.depends_on : Object.keys(def.depends_on);
-		return {
-			name,
-			image: def.image,
-			build: def.build,
-			ports,
-			environment,
-			volumes,
-			dependsOn
-		};
-	});
-	return {
-		services,
-		appService: services.find((s) => s.build !== void 0) ?? null,
-		infraServices: services.filter((s) => s.build === void 0)
-	};
+//#region src/model/chain/registry.ts
+let containerIntegrations = null;
+/** Wire the container runtime. Called by the package entry point. */
+function registerContainerIntegrations(integrations) {
+	containerIntegrations = integrations;
+}
+function getContainerIntegrations() {
+	if (!containerIntegrations) throw new Error("@jterrazz/test: container integrations are not registered — import from '@jterrazz/test' (the package entry point wires them).");
+	return containerIntegrations;
 }
 //#endregion
-//#region src/integrations/compose/compose.ts
+//#region src/model/contracts/intercept.ts
 /**
-* Start the full compose stack and stop it all on cleanup.
-* Supports per-worker project names for parallel execution.
+* 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.
 */
-var ComposeStackAdapter = class {
-	composeFile;
-	projectName;
-	started = false;
-	constructor(composeFile, projectName) {
-		this.composeFile = composeFile;
-		this.projectName = projectName ?? null;
-	}
-	get projectFlag() {
-		return this.projectName ? `-p ${this.projectName}` : "";
+/**
+* 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
+	}];
+}
+/** Is this argument the options object rather than a response? */
+function isOptions(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && "origin" in value;
+}
+/**
+* Resolve every relative request against `origin` for the life of the scope.
+*
+* The framework owns the seam so a test never has to: this is the one place
+* `fetch` is wrapped, it is put back when the scope ends, and what it does is
+* the one thing a page would have done for free — turn `/api/posts` into a URL.
+*/
+function resolveRelativeAgainst(origin) {
+	let base;
+	try {
+		base = new URL(origin);
+	} catch {
+		throw new Error(`intercept(): \`origin\` states where a relative request resolves — \`${origin}\` is not an absolute URL (e.g. 'http://console.test').`);
 	}
-	run(command) {
+	const original = globalThis.fetch;
+	globalThis.fetch = async (input, init) => typeof input === "string" && input.startsWith("/") ? await original(new URL(input, base).toString(), init) : await original(input, init);
+	return () => {
+		globalThis.fetch = original;
+	};
+}
+/**
+* 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, maybeResponseOrOptions, maybeOptions) {
+		const options = isOptions(maybeOptions) ? maybeOptions : isOptions(maybeResponseOrOptions) ? maybeResponseOrOptions : void 0;
+		const contracts = declared(requestOrContracts, options === maybeResponseOrOptions ? void 0 : maybeResponseOrOptions);
+		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 restoreOrigin = options?.origin === void 0 ? void 0 : resolveRelativeAgainst(options.origin);
+		let registration;
 		try {
-			return execSync(command, {
-				cwd: dirname(this.composeFile),
-				encoding: "utf8",
-				timeout: 12e4
-			}).trim();
+			registration = await register(contracts);
 		} catch (error) {
-			const stderr = error.stderr?.toString().trim() ?? error.message;
-			throw new Error(`docker compose failed: ${stderr}`, { cause: error });
+			restoreOrigin?.();
+			throw error;
 		}
+		return { [Symbol.asyncDispose]: async () => {
+			const violation = registration.violation();
+			registration.cleanup();
+			restoreOrigin?.();
+			await Promise.resolve();
+			if (violation) throw violation;
+		} };
 	}
-	async start() {
-		if (this.started) return;
-		this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} up -d --wait --build`);
-		this.started = true;
-	}
-	async stop() {
-		if (!this.started) return;
-		this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} down -v`);
-		this.started = false;
+	return intercept;
+}
+//#endregion
+//#region src/seams/peer.ts
+/**
+* Loading an OPTIONAL peer, and saying the right thing when it is not there.
+*
+* Four native seams — `better-sqlite3`, `pg`, `redis`, `testcontainers` — are
+* peers rather than dependencies: a consumer that specifies a CLI has no
+* business compiling a SQLite binding, and a package carrying all four would
+* make every install pay for the services one repository happens to use.
+*
+* A peer being absent is then an ordinary state, and the message is what turns
+* it into a one-line fix. Two things make it actionable:
+*
+* - it names the FACET that asked, so the reader knows which line to look at,
+*   and the peer to install, with the command of the package manager the
+*   project's own lockfile names — `npm install -D` in a Bun workspace is a
+*   line the reader has to translate before they can use it;
+* - under pnpm it names `only-built-dependencies` as well. pnpm does not run a
+*   dependency's install script unless the manifest lists it, so a native
+*   binding installs and then fails to LOAD — the one failure where "install
+*   the package" is advice the reader has already followed.
+*/
+/**
+* The lockfile each package manager leaves at the project root, and the
+* command a reader of this message types.
+*
+* A message that says `npm install` in a Bun workspace is a message the reader
+* has to translate before they can use it — and the translation is the only
+* part of the fix they did not already know.
+*/
+const INSTALLERS = [
+	{
+		command: "bun add -d",
+		lockfile: "bun.lock",
+		name: "bun"
+	},
+	{
+		command: "bun add -d",
+		lockfile: "bun.lockb",
+		name: "bun"
+	},
+	{
+		command: "pnpm add -D",
+		lockfile: "pnpm-lock.yaml",
+		name: "pnpm"
+	},
+	{
+		command: "yarn add -D",
+		lockfile: "yarn.lock",
+		name: "yarn"
+	},
+	{
+		command: "npm install -D",
+		lockfile: "package-lock.json",
+		name: "npm"
+	}
+];
+/** What npm's absence of a lockfile still answers. */
+const DEFAULT_INSTALLER = {
+	command: "npm install -D",
+	name: "npm"
+};
+/**
+* How each package manager is told to run the install script it withheld.
+*
+* Every one of them now withholds it by default — npm since 11, pnpm since 10,
+* bun since 1.2 — so "install the package" is advice the reader has already
+* followed and the binding is still not there.
+*/
+const BUILDERS = {
+	bun: (peer) => `bun pm trust ${peer}`,
+	npm: (peer) => `npm install-scripts approve ${peer} && npm rebuild ${peer}`,
+	pnpm: (peer) => `add "${peer}" to \`onlyBuiltDependencies\` in package.json (or \`only-built-dependencies\` in .npmrc), then \`pnpm rebuild ${peer}\``,
+	yarn: (peer) => `yarn rebuild ${peer}`
+};
+/**
+* What a native module that is INSTALLED but not BUILT says when it is first
+* used. Node's own message for a missing `.node`, and the `bindings` package's
+* for the same thing, plus the two shapes a binding built elsewhere produces.
+*/
+const UNBUILT = /could not locate the bindings file|\.node['"]?$|invalid elf header|was compiled against a different node/iu;
+/** Is this failure a binding that was never built, rather than a bug in the seam? */
+function isUnbuilt(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return UNBUILT.test(message);
+}
+/** The peers whose install script has to run for the package to load at all. */
+const NATIVE_PEERS = /* @__PURE__ */ new Set(["better-sqlite3"]);
+/** The nearest ancestor of `from` carrying a `package.json`, or undefined. */
+function projectRoot(from) {
+	let directory = from;
+	for (;;) {
+		if (existsSync(resolve(directory, "package.json"))) return directory;
+		const parent = dirname(directory);
+		if (parent === directory) return;
+		directory = parent;
 	}
-	getMappedPort(serviceName, containerPort) {
-		const port = this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} port ${serviceName} ${containerPort}`).split(":").pop();
-		return Number(port);
+}
+/**
+* The package manager a project is installed by, read from its lockfile.
+*
+* Exported for its own module test: the answer depends on the filesystem
+* around the caller, which a test states by building one.
+*
+* @internal
+*/
+function installerAt(from) {
+	const root = projectRoot(from);
+	if (root === void 0) return DEFAULT_INSTALLER;
+	return INSTALLERS.find((candidate) => existsSync(resolve(root, candidate.lockfile))) ?? DEFAULT_INSTALLER;
+}
+/** The line a reader has to add, when the package manager needs one. */
+function buildNote(peer, manager) {
+	if (!NATIVE_PEERS.has(peer) || manager !== "pnpm") return "";
+	return ` Under pnpm the binding is not built unless the package is listed: add "${peer}" to \`onlyBuiltDependencies\` in package.json (or \`only-built-dependencies\` in .npmrc) and reinstall.`;
+}
+/**
+* Use a native peer that is already loaded, and say the right thing when its
+* BINDING was never built.
+*
+* A native peer has two ways of not being there, and only one of them is
+* "install it". The other is the package present on disk with no compiled
+* `.node` beside it, because the package manager withheld the install script —
+* which every one of them now does by default. Left alone that surfaces as a
+* `bindings` stack trace from whichever spec opened a database first: no peer
+* name, no facet, no command. This turns it into the same shaped refusal a
+* missing peer gets.
+*/
+function requireBuiltPeer(peer, what, use) {
+	try {
+		use();
+	} catch (error) {
+		if (!isUnbuilt(error)) throw error;
+		const { name } = installerAt(process.cwd());
+		const build = (BUILDERS[name] ?? BUILDERS.npm)?.(peer) ?? `rebuild ${peer}`;
+		throw new Error(`${what} found \`${peer}\` but its native binding is not built — ${name} does not run a dependency's install script unless it is told to: ${build}.`, { cause: error });
 	}
-	getHost() {
-		return "localhost";
+}
+/**
+* Import an optional peer, or throw a message that names the facet, the peer
+* and the command.
+*
+* `load` is the caller's own `import('<peer>')`: a bare specifier is what the
+* bundler and the resolver both need to see, so the import stays at the call
+* site and this function owns only the failure.
+*/
+async function loadPeer(peer, what, load) {
+	try {
+		return await load();
+	} catch (error) {
+		const { command, name } = installerAt(process.cwd());
+		throw new Error(`${what} requires \`${peer}\`, an optional peer dependency of @jterrazz/test: ${command} ${peer}.${buildNote(peer, name)}`, { cause: error });
 	}
-};
+}
 //#endregion
-//#region src/integrations/postgres/postgres.ts
-var PostgresHandle = class {
-	type = "postgres";
-	composeName;
-	defaultPort = 5432;
-	defaultImage;
-	environment;
-	connectionString = "";
-	started = false;
-	client = null;
-	originalConnectionString = "";
-	schema = "public";
-	constructor(options = {}) {
-		this.composeName = options.composeService ?? null;
-		this.defaultImage = options.image ?? "postgres:17";
-		this.environment = {
-			POSTGRES_DB: "test",
-			POSTGRES_PASSWORD: "test",
-			POSTGRES_USER: "test",
-			...options.env
-		};
-	}
-	buildConnectionString(host, port) {
-		return `postgresql://${this.environment.POSTGRES_USER ?? "test"}:${this.environment.POSTGRES_PASSWORD ?? "test"}@${host}:${port}/${this.environment.POSTGRES_DB ?? "test"}`;
-	}
-	createDatabaseAdapter() {
-		return this;
+//#region src/seams/testcontainers/testcontainers.ts
+/**
+* Container adapter using testcontainers.
+* Wraps a GenericContainer for programmatic container lifecycle.
+*/
+var TestcontainersAdapter = class {
+	image;
+	containerPort;
+	env;
+	reuse;
+	container = null;
+	constructor(options) {
+		this.image = options.image;
+		this.containerPort = options.port;
+		this.env = options.env ?? {};
+		this.reuse = options.reuse ?? false;
 	}
-	async healthcheck() {
-		if (!this.connectionString) throw new Error("postgres: cannot healthcheck — no connection string");
-		try {
-			const client = new Client({ connectionString: this.connectionString });
-			await client.connect();
-			await client.query("SELECT 1");
-			await client.end();
-		} catch (error) {
-			throw new Error(`postgres healthcheck failed: ${error.message || error.code || String(error)}`, { cause: error });
-		}
+	async start() {
+		const { GenericContainer, Wait } = await loadPeer("testcontainers", "a declared service", async () => await import("testcontainers"));
+		let builder = new GenericContainer(this.image).withExposedPorts(this.containerPort);
+		for (const [key, value] of Object.entries(this.env)) builder = builder.withEnvironment({ [key]: value });
+		if (this.image.startsWith("postgres")) builder = builder.withWaitStrategy(Wait.forLogMessage(/database system is ready to accept connections/u, 2));
+		if (this.reuse) builder = builder.withReuse();
+		this.container = await builder.start();
 	}
-	async initialize(composeDir) {
-		if (!this.composeName) return;
-		const initPaths = [resolve(composeDir, `${this.composeName}/init.sql`), resolve(composeDir, "postgres/init.sql")];
-		for (const initPath of initPaths) if (existsSync(initPath)) {
-			const sql = readFileSync(initPath, "utf8");
-			try {
-				await this.seed(sql);
-			} catch (error) {
-				throw new Error(`postgres init script failed (${initPath}):\n${error.message}`, { cause: error });
-			}
-			return;
+	async stop() {
+		if (this.container && !this.reuse) {
+			await this.container.stop();
+			this.container = null;
 		}
 	}
-	async getClient() {
-		if (this.client) return this.client;
-		const client = new Client({ connectionString: this.connectionString });
-		client.on("error", () => {
-			this.client = null;
-		});
-		await client.connect();
-		this.client = client;
-		return client;
-	}
-	async seed(sql) {
-		await (await this.getClient()).query(sql);
+	getMappedPort(containerPort) {
+		if (!this.container) throw new Error("Container not started");
+		return this.container.getMappedPort(containerPort);
 	}
-	async reset() {
-		const client = await this.getClient();
-		const result = await client.query(`
-            SELECT tablename FROM pg_tables
-            WHERE schemaname = '${this.schema}'
-            AND tablename NOT LIKE '_prisma%'
-        `);
-		for (const row of result.rows) await client.query(`TRUNCATE "${this.schema}"."${row.tablename}" CASCADE`);
+	getHost() {
+		if (!this.container) throw new Error("Container not started");
+		return this.container.getHost();
 	}
-	async query(table, columns) {
-		const client = await this.getClient();
-		const columnList = columns.join(", ");
-		return (await client.query(`SELECT ${columnList} FROM "${this.schema}"."${table}" ORDER BY 1`)).rows.map((row) => columns.map((col) => row[col]));
+	getConnectionString() {
+		return `${this.getHost()}:${this.getMappedPort(this.containerPort)}`;
 	}
-	isolation() {
-		return {
-			acquire: async (workerId) => {
-				const workerSchema = `worker_${workerId}`;
-				this.originalConnectionString = this.connectionString;
-				const client = await this.getClient();
-				await client.query(`DROP SCHEMA IF EXISTS "${workerSchema}" CASCADE`);
-				await client.query(`CREATE SCHEMA "${workerSchema}"`);
-				const tables = await client.query(`
-                    SELECT tablename FROM pg_tables
-                    WHERE schemaname = 'public'
-                    AND tablename NOT LIKE '_prisma%'
-                `);
-				for (const row of tables.rows) await client.query(`CREATE TABLE "${workerSchema}"."${row.tablename}" (LIKE "public"."${row.tablename}" INCLUDING ALL)`);
-				this.schema = workerSchema;
-				await client.query(`SET search_path TO "${workerSchema}", public`);
-				const url = new URL(this.connectionString);
-				url.searchParams.set("options", `-c search_path=${workerSchema},public`);
-				this.connectionString = url.toString();
-			},
-			reset: async () => {
-				await this.reset();
-			},
-			release: async () => {
-				const client = await this.getClient();
-				const workerSchema = this.schema;
-				this.schema = "public";
-				this.connectionString = this.originalConnectionString;
-				await client.query(`SET search_path TO public`);
-				await client.query(`DROP SCHEMA IF EXISTS "${workerSchema}" CASCADE`);
-			}
-		};
+	async getLogs() {
+		if (!this.container) return "";
+		const stream = await this.container.logs();
+		return await new Promise((resolve) => {
+			let output = "";
+			stream.on("data", (chunk) => {
+				output += chunk.toString();
+			});
+			stream.on("end", () => {
+				resolve(output);
+			});
+			setTimeout(() => {
+				resolve(output);
+			}, 1e3);
+		});
 	}
 };
-/**
-* Create a PostgreSQL service handle.
-*
-* @example
-* // Key derives the compose service (exact name or kebab-case):
-* //   { db: postgres() }          → compose service "db"
-* //   { analyticsDb: postgres() } → compose service "analytics-db"
-* // Escape hatch for names the key cannot derive:
-* const events = postgres({ composeService: "legacy_event_store" });
-* // After start: events.connectionString is populated
-*/
-function postgres(options = {}) {
-	return new PostgresHandle(options);
-}
 //#endregion
-//#region src/integrations/redis/redis.ts
-var RedisHandle = class {
-	type = "redis";
-	composeName;
-	defaultPort = 6379;
-	defaultImage;
-	environment = {};
-	connectionString = "";
-	started = false;
-	dbIndex = 0;
-	constructor(options = {}) {
-		this.composeName = options.composeService ?? null;
-		this.defaultImage = options.image ?? "redis:7";
-	}
-	buildConnectionString(host, port) {
-		return `redis://${host}:${port}`;
-	}
-	createDatabaseAdapter() {
-		return null;
-	}
-	async healthcheck() {
-		if (!this.connectionString) throw new Error("redis: cannot healthcheck — no connection string");
-		try {
-			const { createClient } = await import("redis");
-			const client = createClient({ url: this.connectionString });
-			await client.connect();
-			await client.ping();
-			await client.disconnect();
-		} catch (error) {
-			throw new Error(`redis healthcheck failed: ${error.message || error.code || String(error)}`, { cause: error });
-		}
-	}
-	async initialize() {}
-	async reset() {
-		const { createClient } = await import("redis");
-		const client = createClient({
-			url: this.connectionString,
-			database: this.dbIndex
-		});
-		await client.connect();
-		try {
-			await client.flushDb();
-		} finally {
-			await client.disconnect();
-		}
-	}
-	isolation() {
-		return {
-			acquire: async (workerId) => {
-				const numericId = Number.parseInt(workerId, 10) || 0;
-				this.dbIndex = numericId % 15 + 1;
-			},
-			reset: async () => {
-				await this.reset();
-			},
-			release: async () => {
-				await this.reset();
-				this.dbIndex = 0;
-			}
-		};
-	}
-};
-/**
-* Create a Redis service handle.
-*
-* @example
-* // The record key derives the compose service: { cache: redis() } → "cache".
-* const cache = redis();
-* // After start: cache.connectionString is populated
-*/
-function redis(options = {}) {
-	return new RedisHandle(options);
-}
-//#endregion
-//#region src/integrations/testcontainers/testcontainers.ts
-/**
-* Container adapter using testcontainers.
-* Wraps a GenericContainer for programmatic container lifecycle.
-*/
-var TestcontainersAdapter = class {
-	image;
-	containerPort;
-	env;
-	reuse;
-	container = null;
-	constructor(options) {
-		this.image = options.image;
-		this.containerPort = options.port;
-		this.env = options.env ?? {};
-		this.reuse = options.reuse ?? false;
-	}
-	async start() {
-		const { GenericContainer, Wait } = await import("testcontainers");
-		let builder = new GenericContainer(this.image).withExposedPorts(this.containerPort);
-		for (const [key, value] of Object.entries(this.env)) builder = builder.withEnvironment({ [key]: value });
-		if (this.image.startsWith("postgres")) builder = builder.withWaitStrategy(Wait.forLogMessage(/database system is ready to accept connections/u, 2));
-		if (this.reuse) builder = builder.withReuse();
-		this.container = await builder.start();
-	}
-	async stop() {
-		if (this.container && !this.reuse) {
-			await this.container.stop();
-			this.container = null;
-		}
-	}
-	getMappedPort(containerPort) {
-		if (!this.container) throw new Error("Container not started");
-		return this.container.getMappedPort(containerPort);
-	}
-	getHost() {
-		if (!this.container) throw new Error("Container not started");
-		return this.container.getHost();
-	}
-	getConnectionString() {
-		return `${this.getHost()}:${this.getMappedPort(this.containerPort)}`;
-	}
-	async getLogs() {
-		if (!this.container) return "";
-		const stream = await this.container.logs();
-		return await new Promise((resolve) => {
-			let output = "";
-			stream.on("data", (chunk) => {
-				output += chunk.toString();
-			});
-			stream.on("end", () => {
-				resolve(output);
-			});
-			setTimeout(() => {
-				resolve(output);
-			}, 1e3);
-		});
-	}
-};
-//#endregion
-//#region src/specification/facets/_common/registry.ts
-let containerIntegrations = null;
-const composeServiceFactories = /* @__PURE__ */ new Map();
-/** Wire the container runtimes. Called by the package entry point. */
-function registerContainerIntegrations(integrations) {
-	containerIntegrations = integrations;
-}
-/** Wire a service auto-detection factory (e.g. `'postgres'`, `'redis'`). */
-function registerComposeServiceFactory(type, factory) {
-	composeServiceFactories.set(type, factory);
-}
-function getContainerIntegrations() {
-	if (!containerIntegrations) throw new Error("@jterrazz/test: container integrations are not registered — import from '@jterrazz/test' (the package entry point wires them).");
-	return containerIntegrations;
-}
-function getComposeServiceFactory(type) {
-	return composeServiceFactories.get(type);
-}
-//#endregion
-//#region src/specification/facets/website/elements.ts
+//#region src/model/elements/elements.ts
 const named = (kind) => (name, options) => ({
 	kind,
 	name,
-	...options?.exact ? { exact: true } : {}
+	...options?.exact === void 0 ? {} : { exact: options.exact }
 });
 /** A button (or element with the button role), by accessible name. */
 const button = named("button");
@@ -415,7 +349,7 @@ const testId = (id) => ({
 const landmark = (kind) => (name, options) => ({
 	kind,
 	...name === void 0 ? {} : { name },
-	...options?.exact ? { exact: true } : {}
+	...options?.exact === void 0 ? {} : { exact: options.exact }
 });
 /** The `banner` landmark — the page header. */
 const banner = landmark("banner");
@@ -533,7 +467,7 @@ const valued = (element, value) => ({
 	value
 });
 //#endregion
-//#region src/specification/contracts/filters.ts
+//#region src/model/contracts/filters.ts
 /** Does an observed text satisfy a declared {@link TextFilter}? */
 function matchesText(filter, actual) {
 	if (filter === void 0) return true;
@@ -542,7 +476,7 @@ function matchesText(filter, actual) {
 	return structuralEquals(filter, actual, new CaptureScope());
 }
 //#endregion
-//#region src/integrations/anthropic/anthropic.ts
+//#region src/seams/anthropic/anthropic.ts
 const ANTHROPIC_MESSAGES_URL = "https://api.anthropic.com/v1/messages";
 function matchesFilter(body, filter) {
 	if (!matchesText(filter.model, body?.model ?? "")) return false;
@@ -633,7 +567,7 @@ const anthropic = {
 	}
 };
 //#endregion
-//#region src/specification/contracts/http.ts
+//#region src/model/contracts/http.ts
 function wrapJson(data) {
 	return {
 		status: 200,
@@ -641,6 +575,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 +696,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 {
@@ -764,7 +756,7 @@ const http = {
 	}
 };
 //#endregion
-//#region src/integrations/openai/openai.ts
+//#region src/seams/openai/openai.ts
 const OPENAI_CHAT_URL = "https://api.openai.com/v1/chat/completions";
 const OPENAI_RESPONSES_URL = "https://api.openai.com/v1/responses";
 function matchesChatFilter(body, filter) {
@@ -920,55 +912,671 @@ const openai = {
 		};
 	}
 };
-//#endregion
-//#region src/vitest/mock-of.ts
+//#endregion
+//#region src/model/doubles/mock-of.ts
+function mockOf(options) {
+	return options?.deep === false ? mock() : mockDeep();
+}
+//#endregion
+//#region src/model/clock/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/model/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/model/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/model/chain/caller.ts
+/** Sibling module tests are callers, not internals (CONVENTIONS I2). */
+const TEST_FILE = /\.test\.[cm]?[jt]s$/u;
+/** Where this very module sits inside the framework's SOURCE tree. */
+const SOURCE_LOCATION = join("model", "chain");
+/** The real path of `path`, or `path` itself when it cannot be resolved. */
+function realPath(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
+/**
+* Directory of the running framework module itself. From the built package
+* this is `<package root>/dist`, whatever the resolution path — including a
+* `file:` link, where the real path carries neither `node_modules` nor
+* `/src/…` and would otherwise be mistaken for a caller frame.
+*/
+const FRAMEWORK_DIR = realPath(import.meta.dirname);
+/**
+* The directory holding the framework's OWN modules: `<package>/dist` for a
+* built install (everything is bundled there), `<repo>/src` when the framework
+* runs from source — this module's known location inside that tree is what
+* tells the two apart.
+*/
+const FRAMEWORK_TREE = FRAMEWORK_DIR.endsWith(`${sep}${SOURCE_LOCATION}`) ? resolve(FRAMEWORK_DIR, "../..") : FRAMEWORK_DIR;
+/** Is `path` inside `directory` (strictly — a directory is not inside itself)? */
+function isInside(directory, path) {
+	const rest = relative(directory, path);
+	return rest !== "" && !rest.startsWith("..") && !isAbsolute(rest);
+}
+/**
+* Is this stack frame a module of the framework itself, rather than of the code
+* calling it?
+*
+* Answered by IDENTITY — the frame is inside the framework's own directory —
+* and never by substring: a consumer's own `src/model/` is not this package's,
+* and reading it as one would skip the consumer's files as internals and
+* anchor fixture resolution on the wrong directory.
+*
+* @internal
+*/
+function isFrameworkFrame(filePath, frameworkTree = FRAMEWORK_TREE) {
+	if (TEST_FILE.test(filePath)) return false;
+	return isInside(realPath(frameworkTree), realPath(filePath));
+}
+/**
+* Detect the directory of the first stack frame that lives outside this
+* package. Used to anchor fixture resolution (`_seeds/`, `_requests/`,
+* `_expected/`, …) on the calling test / specification file.
+*
+* @internal
+*/
+function getCallerDir() {
+	const { stack } = /* @__PURE__ */ new Error("caller detection");
+	if (!stack) throw new Error("Cannot detect caller directory: no stack trace");
+	const lines = stack.split("\n");
+	for (const line of lines) {
+		const match = /at\s+(?:.*?\()?(?:file:\/\/)?(?<filePath>[^:)]+):\d+:\d+/u.exec(line);
+		if (!match?.groups?.filePath) continue;
+		const { filePath } = match.groups;
+		if (filePath.includes("node_modules")) continue;
+		if (isFrameworkFrame(filePath)) continue;
+		return resolve(filePath, "..");
+	}
+	return process.cwd();
+}
+//#endregion
+//#region src/model/chain/docker-reader.ts
+/**
+* Build the `docker(containerId)` reader handed out by `specification.api()`
+* and `specification.cli()` — a lazy accessor over `docker inspect`.
+*/
+function createDockerReader(testDir) {
+	return (containerId) => {
+		try {
+			const inspect = inspectContainer(containerId);
+			return new ContainerAccessor(containerId, inspect, testDir);
+		} catch {
+			return new ContainerAccessor(null, null, testDir);
+		}
+	};
+}
+//#endregion
+//#region src/model/chain/binding.ts
+/**
+* The case conversions a services-record key goes through.
+*
+* A record key is written in the natural TypeScript style (`analyticsDb`),
+* while the two vocabularies it feeds are not: a service DIRECTORY under
+* `docker/` is kebab-case (`analytics-db`), and an injected environment
+* variable is CONSTANT_CASE (`ANALYTICS_DB_URL`). These two helpers bridge
+* them deterministically, so the record key stays the single source of truth
+* and no handle carries a second name of its own.
+*/
+/**
+* Convert a record key to its kebab-case form: camelCase boundaries become
+* `-`, everything is lowercased. `analyticsDb` → `analytics-db`, `db` → `db`.
+*/
+function toKebabCase(key) {
+	return key.replaceAll(/(?<lower>[a-z0-9])(?<upper>[A-Z])/gu, "$<lower>-$<upper>").toLowerCase();
+}
+/**
+* Convert a record key to CONSTANT_CASE for env injection: insert `_` at
+* camelCase boundaries, map any remaining non-alphanumeric run to `_`, then
+* uppercase. `analyticsDb` → `ANALYTICS_DB`, `db-main` → `DB_MAIN`, `db` → `DB`.
+*/
+function toConstantCase(key) {
+	return key.replaceAll(/(?<lower>[a-z0-9])(?<upper>[A-Z])/gu, "$<lower>_$<upper>").replaceAll(/[^A-Za-z0-9]/gu, "_").toUpperCase();
+}
+//#endregion
+//#region src/model/chain/orchestrator.ts
+/** Where a service reads its init script from — `<root>/docker/<service>/`. */
+const DOCKER_DIR = "docker";
+/**
+* The infrastructure a specification declares, started and stopped as a unit.
+*
+* Every declared handle becomes a real thing: a container through
+* testcontainers, or an embedded service (SQLite) that needs no container. The
+* record KEY is the only name in play — it is the spec's database vocabulary,
+* the name the startup report prints, and, kebab-cased, the directory the
+* service reads its init script from.
+*
+* It is internal wiring: the constructors drive it, and no consumer names it.
+*/
+var Orchestrator = class {
+	services;
+	root;
+	subject;
+	running = [];
+	started = false;
+	constructor(options) {
+		this.services = options.services;
+		this.root = options.root;
+		this.subject = options.subject ?? { type: "in-process" };
+	}
+	/**
+	* Start every declared service.
+	* Phase 1: start all containers in parallel (the slow part).
+	* Phase 2: wire connections, healthcheck, and init sequentially (fast).
+	*/
+	async start() {
+		if (this.started) return;
+		const dockerDir = resolve(this.root, DOCKER_DIR);
+		for (const [key, handle] of Object.entries(this.services)) handle.serviceName = toKebabCase(key);
+		const containerServices = [];
+		const embeddedServices = [];
+		for (const handle of Object.values(this.services)) {
+			if (handle.defaultPort === 0) {
+				embeddedServices.push(handle);
+				continue;
+			}
+			const container = getContainerIntegrations().createContainer({
+				image: handle.defaultImage,
+				port: handle.defaultPort,
+				env: { ...handle.environment }
+			});
+			containerServices.push({
+				container,
+				handle
+			});
+		}
+		await Promise.all([...containerServices.map(async ({ container }) => {
+			await container.start();
+		}), ...embeddedServices.map(async (handle) => {
+			await handle.initialize(dockerDir, this.root);
+			handle.started = true;
+			this.running.push({
+				handle,
+				container: null
+			});
+		})]);
+		const reports = [];
+		for (const { container, handle } of containerServices) {
+			const serviceStartTime = Date.now();
+			try {
+				const host = container.getHost();
+				const port = container.getMappedPort(handle.defaultPort);
+				handle.connectionString = handle.buildConnectionString(host, port);
+				await handle.healthcheck();
+				await handle.initialize(dockerDir, this.root);
+				handle.started = true;
+				reports.push({
+					name: handle.serviceName ?? handle.type,
+					type: handle.type,
+					connectionString: handle.connectionString,
+					durationMs: Date.now() - serviceStartTime
+				});
+				this.running.push({
+					handle,
+					container
+				});
+			} catch (error) {
+				let logs = "";
+				try {
+					logs = await container.getLogs();
+				} catch {}
+				try {
+					await container.stop();
+				} catch {}
+				reports.push({
+					name: handle.serviceName ?? handle.type,
+					type: handle.type,
+					durationMs: Date.now() - serviceStartTime,
+					error: error.message,
+					logs
+				});
+				const output = formatStartupReport(reports, this.subject);
+				console.error(output);
+				throw error;
+			}
+		}
+		this.started = true;
+		const output = formatStartupReport(reports, this.subject);
+		console.log(output);
+	}
+	/** Stop every container this stack started. */
+	async stop() {
+		for (const { container } of this.running) if (container) await container.stop();
+		this.running = [];
+		this.started = false;
+	}
+	/** The default database — the first declared handle that is one. */
+	getDatabase() {
+		for (const handle of Object.values(this.services)) {
+			const adapter = handle.createDatabaseAdapter();
+			if (adapter) return adapter;
+		}
+		return null;
+	}
+	/** Every database service, keyed by its record key. */
+	getDatabases() {
+		const map = /* @__PURE__ */ new Map();
+		for (const [key, handle] of Object.entries(this.services)) {
+			const adapter = handle.createDatabaseAdapter();
+			if (adapter) map.set(key, adapter);
+		}
+		return map;
+	}
+};
+//#endregion
+//#region src/model/chain/process.ts
+/**
+* An external process, declared like any other service.
+*
+* One shape for every one of them: a site's dev server, an API behind the
+* site, the bundler a simulator loads from. Without it each is declared
+* somewhere else — a facet option, a document's `serve:` entry, a `beforeAll`
+* spawning a child and an `afterAll` that sometimes forgets to kill it — and
+* the lifetime belongs to whoever remembered. Here it is the framework's.
+*
+* 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";
+	serviceName = 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;
+	}
+};
 /**
-* Create a deep mock proxy for a given type.
-* Wraps `vitest-mock-extended`'s `mockDeep` for convenient port mocking.
+* 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 },
+*       }),
+*   });
 */
-const mockOf = mockDeep;
+function processService(options) {
+	return new ProcessHandle(options);
+}
 //#endregion
-//#region src/vitest/mock-of-date.ts
+//#region src/model/chain/services.ts
+function getWorkerId() {
+	return process.env.VITEST_POOL_ID ?? "0";
+}
+async function acquireIsolation(services) {
+	const workerId = getWorkerId();
+	for (const service of Object.values(services)) await service.isolation().acquire(workerId);
+}
+async function releaseIsolation(services) {
+	for (const service of Object.values(services)) await service.isolation().release();
+}
+function declaredDatabaseKeys(services) {
+	return Object.entries(services).filter(([, service]) => service.createDatabaseAdapter() !== null).map(([key]) => key);
+}
 /**
-* Freeze or reset the global Date for deterministic time-dependent tests.
-* Wraps the `mockdate` package.
+* 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.
 */
-const mockOfDate = MockDatePackage;
-//#endregion
-//#region src/integrations/hono/hono.adapter.ts
+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
+	};
+}
 /**
-* Server adapter that dispatches requests in-process through a Hono app instance.
-* Used by the `integration()` specification runner -- no network overhead.
+* 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
 */
-var HonoAdapter = class {
-	app;
-	constructor(app) {
-		this.app = app;
+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;
 	}
-	async request(method, path, body, headers) {
-		const init = {
-			method,
-			headers: {
-				"Content-Type": "application/json",
-				...headers
-			}
-		};
-		if (body !== void 0) init.body = typeof body === "string" ? body : JSON.stringify(body);
-		const response = await this.app.request(path, init);
-		const responseBody = await response.json().catch(() => null);
-		const responseHeaders = {};
-		response.headers.forEach((value, key) => {
-			responseHeaders[key] = value;
-		});
-		return {
-			status: response.status,
-			body: responseBody,
-			headers: responseHeaders
-		};
+	return stop;
+}
+/** Start a services record via testcontainers and acquire worker isolation. */
+async function startServices(services, root, subject) {
+	const { infrastructure } = splitProcesses(services);
+	const orchestrator = new Orchestrator({
+		root,
+		services: infrastructure,
+		subject
+	});
+	await orchestrator.start();
+	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,
+		runId,
+		stopProcesses
+	};
+}
+//#endregion
+//#region src/model/http-files/http-file.ts
+function splitSections(content) {
+	const lines = content.split(/\r?\n/u);
+	let index = 0;
+	while (lines[index]?.trim() === "") index++;
+	const startLine = lines[index] ?? "";
+	index++;
+	const headerLines = [];
+	let header = lines[index];
+	while (header !== void 0 && header.trim() !== "") {
+		headerLines.push(header);
+		index++;
+		header = lines[index];
+	}
+	return {
+		body: lines.slice(index + 1).join("\n").trim(),
+		headerLines,
+		startLine
+	};
+}
+function parseHeaders(headerLines, fileName) {
+	const headers = {};
+	for (const line of headerLines) {
+		const separator = line.indexOf(":");
+		if (separator === -1) throw new Error(`${fileName}: invalid header line "${line}" (expected "Name: value")`);
+		headers[line.slice(0, separator).trim()] = line.slice(separator + 1).trim();
+	}
+	return headers;
+}
+/** Parse a `_requests/*.http` file. First line must be `METHOD /path`. */
+function parseRequestFile(content, fileName) {
+	const { body, headerLines, startLine } = splitSections(content);
+	const start = /^(?<method>[A-Z]+)\s+(?<path>\S+)$/u.exec(startLine.trim());
+	const method = start?.groups?.method;
+	const path = start?.groups?.path;
+	if (method === void 0 || path === void 0) throw new Error(`${fileName}: first line must be "METHOD /path" (e.g. "POST /users"), got "${startLine}"`);
+	return {
+		body: body.length > 0 ? body : void 0,
+		headers: parseHeaders(headerLines, fileName),
+		method,
+		path
+	};
+}
+/** Parse a response `.http` file. First line must be `HTTP/1.1 <status>`. */
+function parseResponseFile(content, fileName) {
+	const { body, headerLines, startLine } = splitSections(content);
+	const status = /^HTTP\/1\.1\s+(?<status>\S+)(?:\s+.*)?$/u.exec(startLine.trim())?.groups?.status;
+	if (status === void 0) throw new Error(`${fileName}: first line must be "HTTP/1.1 <status>" (e.g. "HTTP/1.1 200 OK"), got "${startLine}"`);
+	let parsedBody;
+	if (body.length > 0) try {
+		parsedBody = JSON.parse(body);
+	} catch {
+		parsedBody = body;
 	}
+	return {
+		body: parsedBody,
+		hasBody: body.length > 0,
+		headers: parseHeaders(headerLines, fileName),
+		status
+	};
+}
+const STATUS_TEXT = {
+	200: "OK",
+	201: "Created",
+	202: "Accepted",
+	204: "No Content",
+	301: "Moved Permanently",
+	302: "Found",
+	304: "Not Modified",
+	400: "Bad Request",
+	401: "Unauthorized",
+	403: "Forbidden",
+	404: "Not Found",
+	409: "Conflict",
+	422: "Unprocessable Entity",
+	429: "Too Many Requests",
+	500: "Internal Server Error",
+	502: "Bad Gateway",
+	503: "Service Unavailable"
 };
+/** Serialize a response fixture (used by update mode). */
+function serializeResponseFile(response) {
+	const statusNumber = Number(response.status);
+	const statusText = STATUS_TEXT[statusNumber];
+	const lines = [`HTTP/1.1 ${response.status}${statusText ? ` ${statusText}` : ""}`];
+	for (const [name, value] of Object.entries(response.headers)) lines.push(`${name}: ${value}`);
+	if (response.hasBody) lines.push("", typeof response.body === "string" && !isJsonLike(response.body) ? response.body : JSON.stringify(response.body, null, 4));
+	return `${lines.join("\n")}\n`;
+}
+function isJsonLike(text) {
+	try {
+		JSON.parse(text);
+		return true;
+	} catch {
+		return false;
+	}
+}
 //#endregion
-//#region src/specification/facets/_common/result/response.ts
+//#region src/model/result/response.ts
 /**
 * Read-only accessor for an HTTP response.
 *
@@ -997,7 +1605,7 @@ var ResponseAccessor = class {
 	}
 };
 //#endregion
-//#region src/specification/facets/_common/result/text-assertions.ts
+//#region src/model/result/text-assertions.ts
 /** The fixture name carries its extension — the name IS the file. */
 function requireExtension(name, subject) {
 	if (!/\.[A-Za-z0-9]+$/u.test(name)) throw new Error(`toMatch("${name}"): the extension is part of the name and is required for ${subject} subjects (e.g. "help.txt").`);
@@ -1026,158 +1634,60 @@ function textIsEmpty(accessor) {
 	const pass = content === "";
 	return {
 		message: () => pass ? `expected ${accessor.streamName} not to be empty` : `Expected ${accessor.streamName} to be empty, but it contains:\n${content}`,
-		pass
-	};
-}
-/** `expect(stream).toContain('…')` — the scalpel, never the default (D11). */
-function textContains(accessor, expected) {
-	const actual = accessor.comparableText;
-	const pass = actual.includes(expected);
-	return {
-		message: () => pass ? `expected ${accessor.streamName} not to contain ${JSON.stringify(expected)}` : `${accessor.streamName} does not contain expected substring.\n  expected to contain: ${JSON.stringify(expected)}\n  actual: ${JSON.stringify(actual.length > 500 ? `${actual.slice(0, 500)}…` : actual)}`,
-		pass
-	};
-}
-/**
-* `toMatch` and `toContain` on a subject that is NOT an accessor.
-*
-* Both matchers are overridden globally, for every subject in the project, so
-* whatever the framework does not own has to keep meaning what vitest's own
-* matcher meant. Stated once here because the two builds register two different
-* `expect.extend` calls: a copy in the page is how `expect(['ab']).toContain('b')`
-* ends up passing on one side of the seam and failing on the other.
-*/
-/** vitest's `toMatch` for a plain string: a substring, or a regular expression. */
-function nativeMatch(received, expected) {
-	if (typeof received !== "string") throw new TypeError("toMatch: unsupported subject — expected a stream, json, response, filesystem, or directory accessor, or a string.");
-	const pass = expected instanceof RegExp ? expected.test(received) : received.includes(String(expected));
-	return {
-		message: () => `expected ${JSON.stringify(received)} ${pass ? "not " : ""}to match ${String(expected)}`,
-		pass
-	};
-}
-/** vitest's `toContain` for a plain string (substring) or an iterable (membership). */
-function nativeContain(received, expected) {
-	if (typeof received === "string") {
-		const pass = received.includes(String(expected));
-		return {
-			message: () => `expected ${JSON.stringify(received)} ${pass ? "not " : ""}to contain ${JSON.stringify(expected)}`,
-			pass
-		};
-	}
-	if (isIterable(received)) {
-		const pass = [...received].includes(expected);
-		return {
-			message: () => `expected iterable ${pass ? "not " : ""}to contain ${JSON.stringify(expected)}`,
-			pass
-		};
-	}
-	throw new TypeError(`toContain: unsupported subject of type ${typeof received} — expected a stream accessor, string, or iterable.`);
-}
-/** Does this value hand out its members? A Set and an array both do; a DOM node does not. */
-function isIterable(value) {
-	return value !== null && value !== void 0 && typeof value[Symbol.iterator] === "function";
-}
-//#endregion
-//#region src/specification/http-files/http-file.ts
-function splitSections(content) {
-	const lines = content.split(/\r?\n/u);
-	let index = 0;
-	while (lines[index]?.trim() === "") index++;
-	const startLine = lines[index] ?? "";
-	index++;
-	const headerLines = [];
-	let header = lines[index];
-	while (header !== void 0 && header.trim() !== "") {
-		headerLines.push(header);
-		index++;
-		header = lines[index];
-	}
-	return {
-		body: lines.slice(index + 1).join("\n").trim(),
-		headerLines,
-		startLine
-	};
-}
-function parseHeaders(headerLines, fileName) {
-	const headers = {};
-	for (const line of headerLines) {
-		const separator = line.indexOf(":");
-		if (separator === -1) throw new Error(`${fileName}: invalid header line "${line}" (expected "Name: value")`);
-		headers[line.slice(0, separator).trim()] = line.slice(separator + 1).trim();
-	}
-	return headers;
-}
-/** Parse a `_requests/*.http` file. First line must be `METHOD /path`. */
-function parseRequestFile(content, fileName) {
-	const { body, headerLines, startLine } = splitSections(content);
-	const start = /^(?<method>[A-Z]+)\s+(?<path>\S+)$/u.exec(startLine.trim());
-	const method = start?.groups?.method;
-	const path = start?.groups?.path;
-	if (method === void 0 || path === void 0) throw new Error(`${fileName}: first line must be "METHOD /path" (e.g. "POST /users"), got "${startLine}"`);
-	return {
-		body: body.length > 0 ? body : void 0,
-		headers: parseHeaders(headerLines, fileName),
-		method,
-		path
+		pass
 	};
 }
-/** Parse a response `.http` file. First line must be `HTTP/1.1 <status>`. */
-function parseResponseFile(content, fileName) {
-	const { body, headerLines, startLine } = splitSections(content);
-	const status = /^HTTP\/1\.1\s+(?<status>\S+)(?:\s+.*)?$/u.exec(startLine.trim())?.groups?.status;
-	if (status === void 0) throw new Error(`${fileName}: first line must be "HTTP/1.1 <status>" (e.g. "HTTP/1.1 200 OK"), got "${startLine}"`);
-	let parsedBody;
-	if (body.length > 0) try {
-		parsedBody = JSON.parse(body);
-	} catch {
-		parsedBody = body;
-	}
+/** `expect(stream).toContain('…')` — the scalpel, never the default (D11). */
+function textContains(accessor, expected) {
+	const actual = accessor.comparableText;
+	const pass = actual.includes(expected);
 	return {
-		body: parsedBody,
-		hasBody: body.length > 0,
-		headers: parseHeaders(headerLines, fileName),
-		status
+		message: () => pass ? `expected ${accessor.streamName} not to contain ${JSON.stringify(expected)}` : `${accessor.streamName} does not contain expected substring.\n  expected to contain: ${JSON.stringify(expected)}\n  actual: ${JSON.stringify(actual.length > 500 ? `${actual.slice(0, 500)}…` : actual)}`,
+		pass
 	};
 }
-const STATUS_TEXT = {
-	200: "OK",
-	201: "Created",
-	202: "Accepted",
-	204: "No Content",
-	301: "Moved Permanently",
-	302: "Found",
-	304: "Not Modified",
-	400: "Bad Request",
-	401: "Unauthorized",
-	403: "Forbidden",
-	404: "Not Found",
-	409: "Conflict",
-	422: "Unprocessable Entity",
-	429: "Too Many Requests",
-	500: "Internal Server Error",
-	502: "Bad Gateway",
-	503: "Service Unavailable"
-};
-/** Serialize a response fixture (used by update mode). */
-function serializeResponseFile(response) {
-	const statusNumber = Number(response.status);
-	const statusText = STATUS_TEXT[statusNumber];
-	const lines = [`HTTP/1.1 ${response.status}${statusText ? ` ${statusText}` : ""}`];
-	for (const [name, value] of Object.entries(response.headers)) lines.push(`${name}: ${value}`);
-	if (response.hasBody) lines.push("", typeof response.body === "string" && !isJsonLike(response.body) ? response.body : JSON.stringify(response.body, null, 4));
-	return `${lines.join("\n")}\n`;
+/**
+* `toMatch` and `toContain` on a subject that is NOT an accessor.
+*
+* Both matchers are overridden globally, for every subject in the project, so
+* whatever the framework does not own has to keep meaning what vitest's own
+* matcher meant. Stated once here because the two builds register two different
+* `expect.extend` calls: a copy in the page is how `expect(['ab']).toContain('b')`
+* ends up passing on one side of the seam and failing on the other.
+*/
+/** vitest's `toMatch` for a plain string: a substring, or a regular expression. */
+function nativeMatch(received, expected) {
+	if (typeof received !== "string") throw new TypeError("toMatch: unsupported subject — expected a stream, json, response, filesystem, or directory accessor, or a string.");
+	const pass = expected instanceof RegExp ? expected.test(received) : received.includes(String(expected));
+	return {
+		message: () => `expected ${JSON.stringify(received)} ${pass ? "not " : ""}to match ${String(expected)}`,
+		pass
+	};
 }
-function isJsonLike(text) {
-	try {
-		JSON.parse(text);
-		return true;
-	} catch {
-		return false;
+/** vitest's `toContain` for a plain string (substring) or an iterable (membership). */
+function nativeContain(received, expected) {
+	if (typeof received === "string") {
+		const pass = received.includes(String(expected));
+		return {
+			message: () => `expected ${JSON.stringify(received)} ${pass ? "not " : ""}to contain ${JSON.stringify(expected)}`,
+			pass
+		};
 	}
+	if (isIterable(received)) {
+		const pass = [...received].includes(expected);
+		return {
+			message: () => `expected iterable ${pass ? "not " : ""}to contain ${JSON.stringify(expected)}`,
+			pass
+		};
+	}
+	throw new TypeError(`toContain: unsupported subject of type ${typeof received} — expected a stream accessor, string, or iterable.`);
+}
+/** Does this value hand out its members? A Set and an array both do; a DOM node does not. */
+function isIterable(value) {
+	return value !== null && value !== void 0 && typeof value[Symbol.iterator] === "function";
 }
 //#endregion
-//#region src/vitest/matchers.ts
+//#region src/model/goldens/matchers.ts
 /**
 * Vitest custom matchers for `@jterrazz/test` accessors.
 *
@@ -1205,12 +1715,13 @@ function matchStreamFile(accessor, name, frozen) {
 	const filePath = resolve(accessor.testDir, GROUND_EXPECTED, name);
 	const actual = accessor.comparableText;
 	if (shouldUpdateSnapshots() && !frozen) {
-		const merged = mergeTextPreservingPlaceholders(existsSync(filePath) ? readFileSync(filePath, "utf8") : null, actual, accessor.captures);
+		const previous = existsSync(filePath) ? readFileSync(filePath, "utf8") : null;
+		const merged = mergeTextPreservingPlaceholders(previous, actual, accessor.captures);
 		mkdirSync(dirname(filePath), { recursive: true });
 		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 +1734,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 +1790,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 +1813,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 +1858,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];
@@ -1405,7 +1923,40 @@ async function registerMatchers() {
 	}
 }
 //#endregion
-//#region src/specification/facets/api/result.ts
+//#region src/seams/hono/hono.adapter.ts
+/**
+* Server adapter that dispatches requests in-process through a Hono app instance.
+* Used by the `integration()` specification runner -- no network overhead.
+*/
+var HonoAdapter = class {
+	app;
+	constructor(app) {
+		this.app = app;
+	}
+	async request(method, path, body, headers) {
+		const init = {
+			method,
+			headers: {
+				"Content-Type": "application/json",
+				...headers
+			}
+		};
+		if (body !== void 0) init.body = typeof body === "string" ? body : JSON.stringify(body);
+		const response = await this.app.request(path, init);
+		const responseBody = await response.json().catch(() => null);
+		const responseHeaders = {};
+		response.headers.forEach((value, key) => {
+			responseHeaders[key] = value;
+		});
+		return {
+			status: response.status,
+			body: responseBody,
+			headers: responseHeaders
+		};
+	}
+};
+//#endregion
+//#region src/facets/api/api.result.ts
 /** Result from an HTTP action (.request(), .get(), .post(), .put(), .delete()). */
 var HttpResult = class extends BaseResult {
 	responseData;
@@ -1423,7 +1974,62 @@ var HttpResult = class extends BaseResult {
 	}
 };
 //#endregion
-//#region src/specification/facets/mobile/result.ts
+//#region src/facets/integration/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 — a shape
+* that costs a refusal spec three times the size of the happy one, and 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/facets/mobile/mobile.result.ts
 /** Result from a `.open()` action — the screen as the device saw it, final state. */
 var ScreenResult = class extends BaseResult {
 	capturedScreen;
@@ -1447,7 +2053,7 @@ var ScreenResult = class extends BaseResult {
 	}
 };
 //#endregion
-//#region src/specification/facets/website/result.ts
+//#region src/facets/website/website.result.ts
 /** Result from a raw `.fetch()` action (robots.txt, sitemaps, redirects). */
 var FetchResult = class extends BaseResult {
 	exchange;
@@ -1499,7 +2105,8 @@ var PageResult = class extends BaseResult {
 	* with `toBeEmpty()`, or snapshot with `toMatch('home.console.txt')`.
 	*/
 	get console() {
-		return new TextAccessor(this.page.consoleMessages.map((m) => `[${m.type}] ${m.text}`).join("\n"), "console", this.testDir, { captures: this.captures });
+		const lines = this.page.consoleMessages.map((m) => `[${m.type}] ${m.text}`).join("\n");
+		return new TextAccessor(lines, "console", this.testDir, { captures: this.captures });
 	}
 	/**
 	* Console messages of type `error` only — the stream you usually want
@@ -1507,7 +2114,8 @@ var PageResult = class extends BaseResult {
 	* a cli result.
 	*/
 	get errors() {
-		return new TextAccessor(this.page.consoleMessages.filter((m) => m.type === "error").map((m) => m.text).join("\n"), "errors", this.testDir, { captures: this.captures });
+		const lines = this.page.consoleMessages.filter((m) => m.type === "error").map((m) => m.text).join("\n");
+		return new TextAccessor(lines, "errors", this.testDir, { captures: this.captures });
 	}
 	/**
 	* The document-head projection as a JSON accessor — title, canonical,
@@ -1532,7 +2140,8 @@ var PageResult = class extends BaseResult {
 	* array — `expect(result.jsonLd).toMatch('article.jsonld.json')`.
 	*/
 	get jsonLd() {
-		return new JsonAccessor(`[${this.page.jsonLdBlocks.join(",")}]`, this.testDir, void 0, this.captures);
+		const combined = `[${this.page.jsonLdBlocks.join(",")}]`;
+		return new JsonAccessor(combined, this.testDir, void 0, this.captures);
 	}
 	/** `<link>` elements of the head, in DOM order. */
 	get links() {
@@ -1578,128 +2187,7 @@ function namedMetas(metas) {
 	return named;
 }
 //#endregion
-//#region src/specification/facets/_common/binding.ts
-/**
-* Compose-binding resolution and the case conversions it shares with the
-* automatic env injection (CONVENTIONS A6 / B6).
-*
-* A services-record key is written in the natural TypeScript style
-* (`analyticsDb`), while a compose service name is kebab-case
-* (`analytics-db`). These helpers bridge the two vocabularies deterministically
-* so the record key stays the single source of truth and `composeService`
-* remains a rare escape hatch.
-*/
-/**
-* Convert a record key to its kebab-case form: camelCase boundaries become
-* `-`, everything is lowercased. `analyticsDb` → `analytics-db`, `db` → `db`.
-*/
-function toKebabCase(key) {
-	return key.replaceAll(/(?<lower>[a-z0-9])(?<upper>[A-Z])/gu, "$<lower>-$<upper>").toLowerCase();
-}
-/**
-* Convert a record key to CONSTANT_CASE for env injection: insert `_` at
-* camelCase boundaries, map any remaining non-alphanumeric run to `_`, then
-* uppercase. `analyticsDb` → `ANALYTICS_DB`, `db-main` → `DB_MAIN`, `db` → `DB`.
-*/
-function toConstantCase(key) {
-	return key.replaceAll(/(?<lower>[a-z0-9])(?<upper>[A-Z])/gu, "$<lower>_$<upper>").replaceAll(/[^A-Za-z0-9]/gu, "_").toUpperCase();
-}
-/**
-* Resolve the compose service a record key binds to (CONVENTIONS A6).
-*
-* Order:
-*   1. An explicit `composeService` (`explicitComposeName`) always wins — the
-*      escape hatch for non-derivable names.
-*   2. Otherwise the key binds to the compose service named exactly like it,
-*      else to the kebab-case conversion of the key.
-*   3. If BOTH the exact key and its kebab-case form name a service in the
-*      compose file, the binding is ambiguous → throw (Lint runtime).
-*   4. If neither is present, fall back to the key itself (single-word keys and
-*      runs without a compose file stay unchanged).
-*/
-function resolveComposeBinding(key, explicitComposeName, serviceNames) {
-	if (explicitComposeName !== null) return explicitComposeName;
-	const kebab = toKebabCase(key);
-	const exactExists = serviceNames.includes(key);
-	const kebabExists = kebab !== key && serviceNames.includes(kebab);
-	if (exactExists && kebabExists) throw new Error(`Ambiguous compose binding for service key "${key}": the compose file declares both "${key}" and "${kebab}". Rename one service, or set composeService explicitly on the handle to pick the intended one.`);
-	if (kebabExists) return kebab;
-	return key;
-}
-//#endregion
-//#region src/specification/facets/_common/caller.ts
-/** Sibling module tests are callers, not internals (CONVENTIONS I2). */
-const TEST_FILE = /\.test\.[cm]?[jt]s$/u;
-/** Where this very module sits inside the framework's SOURCE tree. */
-const SOURCE_LOCATION = join("specification", "facets", "_common");
-/** The real path of `path`, or `path` itself when it cannot be resolved. */
-function realPath(path) {
-	try {
-		return realpathSync(path);
-	} catch {
-		return path;
-	}
-}
-/**
-* Directory of the running framework module itself. From the built package
-* this is `<package root>/dist`, whatever the resolution path — including a
-* `file:` link, where the real path carries neither `node_modules` nor
-* `/src/…` and would otherwise be mistaken for a caller frame.
-*/
-const FRAMEWORK_DIR = realPath(import.meta.dirname);
-/**
-* The directory holding the framework's OWN modules: `<package>/dist` for a
-* built install (everything is bundled there), `<repo>/src` when the framework
-* runs from source — this module's known location inside that tree is what
-* tells the two apart.
-*/
-const FRAMEWORK_TREE = FRAMEWORK_DIR.endsWith(`${sep}${SOURCE_LOCATION}`) ? resolve(FRAMEWORK_DIR, "../../..") : FRAMEWORK_DIR;
-/** Is `path` inside `directory` (strictly — a directory is not inside itself)? */
-function isInside(directory, path) {
-	const rest = relative(directory, path);
-	return rest !== "" && !rest.startsWith("..") && !isAbsolute(rest);
-}
-/**
-* Is this stack frame a module of the framework itself, rather than of the code
-* calling it?
-*
-* Answered by IDENTITY: the frame is inside the framework's own directory.
-* Answering it by substring — `/src/core/`, `/src/integrations/`, `/src/vitest/`
-* — was answering a different question, "does this path look like the framework's
-* layout", and a consumer that happens to have its own `src/core/` matched it.
-* Its files were then skipped as framework internals, and fixture resolution
-* anchored on the wrong directory (or fell through to the cwd) with nothing
-* reported.
-*
-* @internal
-*/
-function isFrameworkFrame(filePath, frameworkTree = FRAMEWORK_TREE) {
-	if (TEST_FILE.test(filePath)) return false;
-	return isInside(realPath(frameworkTree), realPath(filePath));
-}
-/**
-* Detect the directory of the first stack frame that lives outside this
-* package. Used to anchor fixture resolution (`_seeds/`, `_requests/`,
-* `_expected/`, …) on the calling test / specification file.
-*
-* @internal
-*/
-function getCallerDir() {
-	const { stack } = /* @__PURE__ */ new Error("caller detection");
-	if (!stack) throw new Error("Cannot detect caller directory: no stack trace");
-	const lines = stack.split("\n");
-	for (const line of lines) {
-		const match = /at\s+(?:.*?\()?(?:file:\/\/)?(?<filePath>[^:)]+):\d+:\d+/u.exec(line);
-		if (!match?.groups?.filePath) continue;
-		const { filePath } = match.groups;
-		if (filePath.includes("node_modules")) continue;
-		if (isFrameworkFrame(filePath)) continue;
-		return resolve(filePath, "..");
-	}
-	return process.cwd();
-}
-//#endregion
-//#region src/specification/facets/_common/builder.ts
+//#region src/model/chain/builder.ts
 /**
 * Fluent builder for declaring a single test specification.
 *
@@ -1713,6 +2201,7 @@ function getCallerDir() {
 * only surfaces the methods that make sense for it.
 */
 var SpecificationBuilder = class {
+	pinnedClock = null;
 	commandEnv = {};
 	config;
 	contracts = [];
@@ -1725,6 +2214,21 @@ 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) {
+		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;
@@ -1793,7 +2297,6 @@ var SpecificationBuilder = class {
 		return this;
 	}
 	intercept(requestOrContracts, maybeResponse) {
-		if (this.config.interceptDisabledReason) throw new Error(`.intercept(): ${this.config.interceptDisabledReason}`);
 		if ((this.config.baseUrl !== void 0 || this.config.device !== void 0) && !this.config.backend) {
 			const facet = this.config.device === void 0 ? "website" : "mobile";
 			throw new Error(`.intercept(): this runner has no declared backend — add \`backend\` to the specification options (specification.${facet}({ …, backend: { … } })) so the chain's contracts have a stub to serve them.`);
@@ -1925,6 +2428,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 +2468,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.
 	*
@@ -2004,9 +2524,11 @@ var SpecificationBuilder = class {
 		let registration = null;
 		if (this.config.backend) this.config.backend.beginChain(this.contracts);
 		else if (this.contracts.length > 0) {
-			const { registerContracts } = await import("./intercept.js");
+			const { registerContracts } = await import("./server.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 +2537,7 @@ var SpecificationBuilder = class {
 		} catch (error) {
 			throw registration?.violation() ?? this.config.backend?.violation() ?? error;
 		} finally {
+			pinned?.[Symbol.dispose]();
 			registration?.cleanup();
 		}
 	}
@@ -2025,6 +2548,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 +2621,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 +2691,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 +2771,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 +2788,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),
@@ -2279,448 +2844,31 @@ function createCliFacet(config) {
 	};
 }
 //#endregion
-//#region src/specification/facets/_common/docker-reader.ts
-/**
-* Build the `docker(containerId)` reader handed out by `specification.api()`
-* and `specification.cli()` — a lazy accessor over `docker inspect`.
-*/
-function createDockerReader(testDir) {
-	return (containerId) => {
-		try {
-			return new ContainerAccessor(containerId, inspectContainer(containerId), testDir);
-		} catch {
-			return new ContainerAccessor(null, null, testDir);
-		}
-	};
-}
-//#endregion
-//#region src/specification/facets/_common/compose-file.ts
-/**
-* Detect the service type from the image name.
-*/
-function detectServiceType(image) {
-	if (!image) return "app";
-	const lower = image.toLowerCase();
-	if (lower.startsWith("postgres")) return "postgres";
-	if (lower.startsWith("redis")) return "redis";
-	return "unknown";
-}
-/**
-* Find the compose file in the project.
-* Looks for docker/compose.test.yaml or docker-compose.test.yaml.
-*/
-function findComposeFile(projectRoot) {
-	const candidates = [
-		resolve(projectRoot, "docker/compose.test.yaml"),
-		resolve(projectRoot, "docker/compose.test.yml"),
-		resolve(projectRoot, "docker-compose.test.yaml"),
-		resolve(projectRoot, "docker-compose.test.yml")
-	];
-	for (const candidate of candidates) if (existsSync(candidate)) return candidate;
-	return null;
-}
-//#endregion
-//#region src/specification/facets/_common/orchestrator.ts
-/**
-* Orchestrator for test infrastructure.
-* Integration: starts services via testcontainers.
-* E2E: runs full docker compose up.
-*/
-var Orchestrator = class {
-	services;
-	mode;
-	root;
-	projectName;
-	running = [];
-	composeStack = null;
-	composeHandles = [];
-	started = false;
-	constructor(options) {
-		this.services = options.services;
-		this.mode = options.mode;
-		this.root = options.root;
-		this.projectName = options.projectName;
-	}
-	/**
-	* Bind each declared handle to a compose service (CONVENTIONS A6): a record
-	* key resolves to the service named exactly like it, else the kebab-case
-	* conversion of the key; an explicit `composeService` wins. Throws on an
-	* ambiguous binding (both names present). Runs once compose config is known
-	* so the two-step resolution can consult the real service list.
-	*/
-	resolveBindings(composeConfig) {
-		const serviceNames = composeConfig?.services.map((s) => s.name) ?? [];
-		for (const [key, handle] of Object.entries(this.services)) handle.composeName = resolveComposeBinding(key, handle.composeName, serviceNames);
-	}
-	/**
-	* Start declared services via testcontainers (integration mode).
-	* Phase 1: start all containers in parallel (the slow part).
-	* Phase 2: wire connections, healthcheck, and init sequentially (fast).
-	*/
-	async start() {
-		if (this.started) return;
-		const composePath = findComposeFile(this.root);
-		const composeDir = composePath ? dirname(composePath) : this.root;
-		const composeConfig = composePath ? getContainerIntegrations().parseComposeFile(composePath) : null;
-		this.resolveBindings(composeConfig);
-		const containerServices = [];
-		const embeddedServices = [];
-		for (const handle of Object.values(this.services)) {
-			if (handle.defaultPort === 0) {
-				embeddedServices.push(handle);
-				continue;
-			}
-			let image = handle.defaultImage;
-			let env = { ...handle.environment };
-			if (handle.composeName && composeConfig) {
-				const composeService = composeConfig.services.find((s) => s.name === handle.composeName);
-				if (composeService) {
-					image = composeService.image ?? image;
-					env = {
-						...env,
-						...composeService.environment
-					};
-					Object.assign(handle.environment, composeService.environment);
-				}
-			}
-			const container = getContainerIntegrations().createContainer({
-				image,
-				port: handle.defaultPort,
-				env
-			});
-			containerServices.push({
-				container,
-				handle
-			});
-		}
-		await Promise.all([...containerServices.map(async ({ container }) => {
-			await container.start();
-		}), ...embeddedServices.map(async (handle) => {
-			await handle.initialize(composeDir, this.root);
-			handle.started = true;
-			this.running.push({
-				handle,
-				container: null
-			});
-		})]);
-		const reports = [];
-		for (const { container, handle } of containerServices) {
-			const serviceStartTime = Date.now();
-			try {
-				const host = container.getHost();
-				const port = container.getMappedPort(handle.defaultPort);
-				handle.connectionString = handle.buildConnectionString(host, port);
-				await handle.healthcheck();
-				await handle.initialize(composeDir, this.root);
-				handle.started = true;
-				reports.push({
-					name: handle.composeName ?? handle.type,
-					type: handle.type,
-					connectionString: handle.connectionString,
-					durationMs: Date.now() - serviceStartTime
-				});
-				this.running.push({
-					handle,
-					container
-				});
-			} catch (error) {
-				let logs = "";
-				try {
-					logs = await container.getLogs();
-				} catch {}
-				try {
-					await container.stop();
-				} catch {}
-				reports.push({
-					name: handle.composeName ?? handle.type,
-					type: handle.type,
-					durationMs: Date.now() - serviceStartTime,
-					error: error.message,
-					logs
-				});
-				const output = formatStartupReport("integration", reports, { type: "in-process" });
-				console.error(output);
-				throw error;
-			}
-		}
-		this.started = true;
-		const output = formatStartupReport("integration", reports, { type: "in-process" });
-		console.log(output);
-	}
-	/**
-	* Stop testcontainers (integration mode).
-	*/
-	async stop() {
-		for (const { container } of this.running) if (container) await container.stop();
-		this.running = [];
-		this.started = false;
-	}
-	/**
-	* Start full docker compose stack (e2e mode).
-	* Auto-detects infra services and creates handles for them.
-	*/
-	async startCompose() {
-		const composePath = findComposeFile(this.root);
-		if (!composePath) throw new Error(`E2E: no compose file found in ${this.root}`);
-		const startTime = Date.now();
-		const composeDir = dirname(composePath);
-		const composeConfig = getContainerIntegrations().parseComposeFile(composePath);
-		this.resolveBindings(composeConfig);
-		this.composeStack = getContainerIntegrations().createComposeStack(composePath, this.projectName);
-		await this.composeStack.start();
-		const declaredComposeNames = /* @__PURE__ */ new Set();
-		for (const handle of Object.values(this.services)) {
-			if (handle.defaultPort === 0) {
-				await handle.initialize(composeDir, this.root);
-				handle.started = true;
-				continue;
-			}
-			const composeService = composeConfig.services.find((s) => s.name === handle.composeName);
-			if (!composeService || !handle.composeName) continue;
-			declaredComposeNames.add(handle.composeName);
-			Object.assign(handle.environment, composeService.environment);
-			const port = this.composeStack.getMappedPort(handle.composeName, handle.defaultPort);
-			handle.connectionString = handle.buildConnectionString("localhost", port);
-			await handle.healthcheck();
-			await handle.initialize(composeDir, this.root);
-			handle.started = true;
-		}
-		for (const service of composeConfig.infraServices) {
-			if (declaredComposeNames.has(service.name)) continue;
-			const factory = getComposeServiceFactory(detectServiceType(service.image));
-			if (!factory) continue;
-			const handle = factory(service);
-			const port = this.composeStack.getMappedPort(service.name, handle.defaultPort);
-			handle.connectionString = handle.buildConnectionString("localhost", port);
-			await handle.initialize(composeDir, this.root);
-			handle.started = true;
-			this.composeHandles.push(handle);
-		}
-		const durationMs = Date.now() - startTime;
-		const output = formatStartupReport("e2e", [...this.allHandles().values()].filter((h) => h.started).map((h) => ({
-			name: h.composeName ?? h.type,
-			type: h.type,
-			connectionString: h.connectionString,
-			durationMs
-		})), {
-			type: "http",
-			url: this.getAppUrl() ?? void 0
-		});
-		console.log(output);
-	}
-	/**
-	* Stop docker compose stack (e2e mode).
-	*/
-	async stopCompose() {
-		if (this.composeStack) {
-			await this.composeStack.stop();
-			this.composeStack = null;
-		}
-		this.composeHandles = [];
-	}
-	/**
-	* Get the default database — the first declared handle that is one.
-	*/
-	getDatabase() {
-		for (const handle of this.allHandles().values()) {
-			const adapter = handle.createDatabaseAdapter();
-			if (adapter) return adapter;
-		}
-		return null;
-	}
-	/**
-	* Get all database services keyed by their record key (declared services)
-	* or compose service name (stack-detected services).
-	*/
-	getDatabases() {
-		const map = /* @__PURE__ */ new Map();
-		for (const [key, handle] of this.allHandles()) {
-			const adapter = handle.createDatabaseAdapter();
-			if (adapter) map.set(key, adapter);
-		}
-		return map;
-	}
-	allHandles() {
-		const map = new Map(Object.entries(this.services));
-		for (const handle of this.composeHandles) {
-			const key = handle.composeName ?? handle.type;
-			if (!map.has(key)) map.set(key, handle);
-		}
-		return map;
-	}
-	/**
-	* Get app URL from compose (e2e mode).
-	*/
-	getAppUrl() {
-		const composePath = findComposeFile(this.root);
-		if (!composePath || !this.composeStack) return null;
-		const { appService } = getContainerIntegrations().parseComposeFile(composePath);
-		const [firstPort] = appService?.ports ?? [];
-		if (!appService || firstPort === void 0) return null;
-		return `http://localhost:${this.composeStack.getMappedPort(appService.name, firstPort.container)}`;
-	}
-};
-//#endregion
-//#region src/specification/facets/_common/services.ts
-function getWorkerId() {
-	return process.env.VITEST_POOL_ID ?? "0";
-}
-async function acquireIsolation(services) {
-	const workerId = getWorkerId();
-	for (const service of Object.values(services)) await service.isolation().acquire(workerId);
-}
-async function releaseIsolation(services) {
-	for (const service of Object.values(services)) await service.isolation().release();
-}
-function declaredDatabaseKeys(services) {
-	return Object.entries(services).filter(([, service]) => service.createDatabaseAdapter() !== null).map(([key]) => key);
-}
-/** Start a services record via testcontainers and acquire worker isolation. */
-async function startServices(services, root) {
-	const orchestrator = new Orchestrator({
-		mode: "integration",
-		root,
-		services
-	});
-	await orchestrator.start();
-	await acquireIsolation(services);
-	const databases = orchestrator.getDatabases();
-	return {
-		database: orchestrator.getDatabase() ?? void 0,
-		databases: databases.size > 0 ? databases : void 0,
-		orchestrator
-	};
-}
-//#endregion
-//#region src/specification/facets/api/fetch.adapter.ts
-/**
-* Transient connection-level failures against a live compose app. Under
-* parallel load (every `api-stack` worker hammering its own compose project)
-* `fetch` intermittently rejects before the app's keep-alive socket is ready —
-* `undici` surfaces these as `UND_ERR_SOCKET` / `ECONNRESET` / `ECONNREFUSED`.
-* They are races, not real failures, so the request path retries them; an HTTP
-* *response* (any status) is never retried — it is a real answer.
-*/
-const TRANSIENT_CONNECTION_CODES = /* @__PURE__ */ new Set([
-	"ECONNREFUSED",
-	"ECONNRESET",
-	"UND_ERR_CONNECT_TIMEOUT",
-	"UND_ERR_SOCKET"
-]);
-/** Bounded retry budget: attempts and the base backoff (doubled each retry). */
-const MAX_ATTEMPTS = 5;
-const BASE_BACKOFF_MS = 50;
-function isTransientConnectionError(error) {
-	if (!(error instanceof Error)) return false;
-	const cause = error.cause;
-	return cause?.code !== void 0 && TRANSIENT_CONNECTION_CODES.has(cause.code) || error.message.includes("fetch failed");
-}
-const delay = async (ms) => {
-	await new Promise((resolve) => setTimeout(resolve, ms));
-};
-/**
-* Server adapter that sends real HTTP requests via the Fetch API.
-* Used by the `e2e()` specification runner to hit a live server.
-*/
-var FetchAdapter = class {
-	baseUrl;
-	constructor(url) {
-		this.baseUrl = url.replace(/\/$/u, "");
-	}
-	async request(method, path, body, headers) {
-		const init = {
-			method,
-			headers: {
-				"Content-Type": "application/json",
-				...headers
-			}
-		};
-		if (body !== void 0) init.body = typeof body === "string" ? body : JSON.stringify(body);
-		const response = await this.fetchWithRetry(`${this.baseUrl}${path}`, init);
-		const responseBody = await response.json().catch(() => null);
-		const responseHeaders = {};
-		response.headers.forEach((value, key) => {
-			responseHeaders[key] = value;
-		});
-		return {
-			status: response.status,
-			body: responseBody,
-			headers: responseHeaders
-		};
-	}
-	/**
-	* `fetch` with a bounded, backing-off retry over transient connection
-	* races (see {@link isTransientConnectionError}). The last error is rethrown
-	* once the budget is spent so a genuinely-down server still surfaces.
-	*/
-	async fetchWithRetry(url, init) {
-		for (let attempt = 1;; attempt += 1) try {
-			return await fetch(url, init);
-		} catch (error) {
-			if (attempt >= MAX_ATTEMPTS || !isTransientConnectionError(error)) throw error;
-			await delay(BASE_BACKOFF_MS * 2 ** (attempt - 1));
-		}
-	}
-};
-//#endregion
-//#region src/specification/facets/api/start-api.ts
-function resolveMode(explicit) {
-	const value = explicit ?? process.env.TEST_MODE ?? "node";
-	if (value !== "compose" && value !== "node") throw new Error(`Invalid test mode "${value}" — expected 'node' or 'compose' (options.mode or TEST_MODE).`);
-	return value;
-}
+//#region src/facets/api/api.specification.ts
 async function startApi(options) {
 	const callerDir = getCallerDir();
 	await registerMatchers();
 	const root = resolveRoot(options.root, callerDir);
-	const mode = resolveMode(options.mode);
 	const services = options.services ?? {};
 	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);
-		return {
-			api: createApiFacet({
-				database,
-				databaseKeys,
-				databases,
-				server: new HonoAdapter(options.server(services))
-			}),
-			cleanup: async () => {
-				await releaseIsolation(services);
-				await orchestrator.stop();
-			},
-			docker: createDockerReader(callerDir),
-			orchestrator
-		};
-	}
-	const orchestrator = new Orchestrator({
-		mode: "e2e",
-		projectName: `test-worker-${getWorkerId()}`,
-		root,
-		services
-	});
-	await orchestrator.startCompose();
-	const appUrl = orchestrator.getAppUrl();
-	if (!appUrl) throw new Error("specification.api(): could not detect app URL from compose. Ensure an app service with ports is defined.");
-	const databases = orchestrator.getDatabases();
+	const { database, databases, orchestrator, stopProcesses } = await startServices(services, root);
 	return {
 		api: createApiFacet({
-			database: orchestrator.getDatabase() ?? void 0,
+			database,
 			databaseKeys,
-			databases: databases.size > 0 ? databases : void 0,
-			interceptDisabledReason: "intercepts are in-process (MSW) and not available in compose mode — keep intercept specs in node-only vitest projects.",
-			server: new FetchAdapter(appUrl)
+			databases,
+			server: new HonoAdapter(options.server(services))
 		}),
 		cleanup: async () => {
-			await orchestrator.stopCompose();
+			await stopProcesses();
+			await releaseIsolation(services);
+			await orchestrator.stop();
 		},
-		docker: createDockerReader(callerDir),
-		orchestrator
+		docker: createDockerReader(callerDir)
 	};
 }
 //#endregion
-//#region src/specification/facets/cli/exec.adapter.ts
+//#region src/facets/cli/exec.adapter.ts
 const DEFAULT_WATCH_TIMEOUT = 1e4;
 /** Grace period between SIGTERM and the SIGKILL escalation. */
 const KILL_GRACE_MS = 2e3;
@@ -2875,7 +3023,7 @@ var ExecAdapter = class {
 	}
 };
 //#endregion
-//#region src/specification/facets/cli/start-cli.ts
+//#region src/facets/cli/cli.specification.ts
 async function startCli(bin, options = {}) {
 	const callerDir = getCallerDir();
 	await registerMatchers();
@@ -2884,9 +3032,10 @@ async function startCli(bin, options = {}) {
 	const services = options.services ?? {};
 	const databaseKeys = declaredDatabaseKeys(services);
 	let started = null;
-	if (Object.keys(services).length > 0) started = await startServices(services, root);
+	if (Object.keys(services).length > 0) started = await startServices(services, root, { type: "none" });
 	return {
 		cleanup: async () => {
+			await started?.stopProcesses();
 			await releaseIsolation(services);
 			if (started) await started.orchestrator.stop();
 		},
@@ -2896,6 +3045,7 @@ async function startCli(bin, options = {}) {
 			databaseKeys,
 			databases: started?.databases,
 			dockerConfig: options.docker,
+			defaultEnv: options.defaults,
 			envSets: options.env,
 			root,
 			serveRegistry: options.serve,
@@ -2907,7 +3057,44 @@ async function startCli(bin, options = {}) {
 	};
 }
 //#endregion
-//#region src/specification/facets/jobs/start-jobs.ts
+//#region src/facets/integration/integration.specification.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 one — which is what spares it the shape it would
+* otherwise take: plain vitest under a `specs/` folder, a hand-built sqlite
+* template, a `beforeAll` starting a container, and a `toMatchSnapshot` beside
+* a framework that owns 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, { type: "none" });
+	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/facets/jobs/jobs.specification.ts
 async function startJobs(options) {
 	const callerDir = getCallerDir();
 	await registerMatchers();
@@ -2915,10 +3102,11 @@ async function startJobs(options) {
 	const services = options.services ?? {};
 	const databaseKeys = declaredDatabaseKeys(services);
 	let started = null;
-	if (Object.keys(services).length > 0) started = await startServices(services, root);
+	if (Object.keys(services).length > 0) started = await startServices(services, root, { type: "none" });
 	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();
 		},
@@ -2932,7 +3120,7 @@ async function startJobs(options) {
 	};
 }
 //#endregion
-//#region src/specification/facets/_common/stub-backend.ts
+//#region src/model/chain/stub-backend.ts
 /**
 * The declared stub backend — a small `node:http` server the website and
 * mobile runners start when their `backend` option is present. It serves the
@@ -3067,6 +3255,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,
@@ -3108,7 +3312,7 @@ async function readBody(request) {
 	}
 }
 //#endregion
-//#region src/specification/facets/mobile/appium-server.ts
+//#region src/facets/mobile/appium-server.ts
 const APPIUM_READY_TIMEOUT_MS = 6e4;
 /**
 * The guidance thrown when the optional peers are missing — the exact fix,
@@ -3139,7 +3343,7 @@ async function startAppiumServer(root) {
 	};
 }
 //#endregion
-//#region src/specification/facets/mobile/simulator.ts
+//#region src/facets/mobile/simulator.ts
 /**
 * Simulator resolution — `device: { name, os? }` → one booted UDID.
 *
@@ -3196,7 +3400,7 @@ async function resolveSimulatorUdid(criteria) {
 		"list",
 		"devices",
 		"--json"
-	], { maxBuffer: 16 * 1024 * 1024 });
+	], { maxBuffer: 16777216 });
 	return selectSimulator(stdout, criteria).udid;
 }
 /**
@@ -3223,7 +3427,7 @@ async function ensureBooted(udid) {
 	], { timeout: BOOT_TIMEOUT_MS });
 }
 //#endregion
-//#region src/specification/facets/mobile/start-mobile.ts
+//#region src/facets/mobile/mobile.specification.ts
 async function startMobile(options) {
 	const callerDir = getCallerDir();
 	await registerMatchers();
@@ -3231,6 +3435,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, { type: "none" });
+	} catch (error) {
+		await appium.stop();
+		throw error;
+	}
 	let backend = null;
 	let backendUrl;
 	if (options.backend) {
@@ -3262,6 +3474,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();
 		},
@@ -3270,7 +3487,77 @@ async function startMobile(options) {
 	};
 }
 //#endregion
-//#region src/specification/facets/website/start-website.ts
+//#region src/facets/website/website.specification.ts
+/**
+* The command a `server` states, where it states one.
+*
+* A factory is a function of services that have not started yet, so calling it
+* to read a command would start the world twice. The SHAPE is known either
+* way, and the shape is the part the startup report was getting wrong.
+*/
+function commandOf(server) {
+	return typeof server === "object" && server !== null && "command" in server ? String(server.command) : void 0;
+}
+/**
+* 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, subject) {
+	if (Object.keys(services).length === 0) return null;
+	try {
+		return await startServices(services, root, subject);
+	} 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 +3568,23 @@ 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 subject = options.server ? {
+		command: commandOf(options.server),
+		type: "process"
+	} : {
+		type: "http",
+		url: options.url
+	};
+	const started = await startDeclared(services, root, backend, subject);
+	const { baseUrl, serve } = await startSite(options, {
+		backend,
+		backendUrl,
+		root,
+		services,
+		started
+	});
 	let browser = null;
 	const getBrowser = async () => {
 		if (!browser) {
@@ -3301,13 +3593,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,21 +3600,31 @@ 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
-//#region src/specification/facets/_common/specification.ts
+//#region src/facets/specification.ts
 const specification = {
 	/**
-	* Test an HTTP app. Mode `'node'` (default) starts the declared services
-	* via testcontainers and runs the app in-process; mode `'compose'` runs
-	* `docker compose up` on `docker/compose.test.yaml` and sends real HTTP
-	* requests to the app service. Resolution: `options.mode` > `TEST_MODE`
-	* env var > `'node'`. Only `.api()` has a mode.
+	* Test an HTTP app. The declared `services` are started via testcontainers
+	* and the app `server` builds runs in-process, so an outgoing call passes
+	* through this process and `.intercept()` can answer it. There is one
+	* shape of world — the record key is the service's only name.
 	*/
 	api: startApi,
 	/**
@@ -3339,6 +3634,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.
 	*/
@@ -3360,7 +3662,7 @@ const specification = {
 	website: startWebsite
 };
 //#endregion
-//#region src/specification/facets/component/component.node.ts
+//#region src/facets/component/component.specification.ts
 /**
 * `component`, as node sees it.
 *
@@ -3382,7 +3684,7 @@ const component = {
 	wrap: refuse
 };
 //#endregion
-//#region src/specification/facets/_common/result/text-subject.ts
+//#region src/model/result/text-subject.ts
 /**
 * Wrap an arbitrary string into a {@link TextAccessor} anchored on the calling
 * test's directory — the same caller-detection the builders use.
@@ -3410,7 +3712,218 @@ function text(value) {
 	return new TextAccessor(value, "text", getCallerDir());
 }
 //#endregion
-//#region src/integrations/sqlite/sqlite.ts
+//#region src/seams/postgres/postgres.ts
+/**
+* `pg`'s client constructor, loaded on the first connection.
+*
+* The driver is an OPTIONAL peer: a repository that specifies a CLI never
+* reaches this line, and never pays for the import.
+*/
+async function clientConstructor() {
+	return await loadPeer("pg", "postgres()", async () => {
+		return (await import("pg")).Client;
+	});
+}
+var PostgresHandle = class {
+	type = "postgres";
+	serviceName = null;
+	defaultPort = 5432;
+	defaultImage;
+	environment;
+	connectionString = "";
+	started = false;
+	client = null;
+	originalConnectionString = "";
+	schema = "public";
+	constructor(options = {}) {
+		this.defaultImage = options.image ?? "postgres:17";
+		this.environment = {
+			POSTGRES_DB: "test",
+			POSTGRES_PASSWORD: "test",
+			POSTGRES_USER: "test",
+			...options.env
+		};
+	}
+	buildConnectionString(host, port) {
+		return `postgresql://${this.environment.POSTGRES_USER ?? "test"}:${this.environment.POSTGRES_PASSWORD ?? "test"}@${host}:${port}/${this.environment.POSTGRES_DB ?? "test"}`;
+	}
+	createDatabaseAdapter() {
+		return this;
+	}
+	async healthcheck() {
+		if (!this.connectionString) throw new Error("postgres: cannot healthcheck — no connection string");
+		try {
+			const client = new (await (clientConstructor()))({ connectionString: this.connectionString });
+			await client.connect();
+			await client.query("SELECT 1");
+			await client.end();
+		} catch (error) {
+			throw new Error(`postgres healthcheck failed: ${error.message || error.code || String(error)}`, { cause: error });
+		}
+	}
+	async initialize(dockerDir) {
+		if (!this.serviceName) return;
+		const initPaths = [resolve(dockerDir, `${this.serviceName}/init.sql`), resolve(dockerDir, "postgres/init.sql")];
+		for (const initPath of initPaths) if (existsSync(initPath)) {
+			const sql = readFileSync(initPath, "utf8");
+			try {
+				await this.seed(sql);
+			} catch (error) {
+				throw new Error(`postgres init script failed (${initPath}):\n${error.message}`, { cause: error });
+			}
+			return;
+		}
+	}
+	async getClient() {
+		if (this.client) return this.client;
+		const client = new (await (clientConstructor()))({ connectionString: this.connectionString });
+		client.on("error", () => {
+			this.client = null;
+		});
+		await client.connect();
+		this.client = client;
+		return client;
+	}
+	async seed(sql) {
+		await (await this.getClient()).query(sql);
+	}
+	async reset() {
+		const client = await this.getClient();
+		const result = await client.query(`
+            SELECT tablename FROM pg_tables
+            WHERE schemaname = '${this.schema}'
+            AND tablename NOT LIKE '_prisma%'
+        `);
+		for (const row of result.rows) await client.query(`TRUNCATE "${this.schema}"."${row.tablename}" CASCADE`);
+	}
+	async query(table, columns) {
+		const client = await this.getClient();
+		const columnList = columns.join(", ");
+		return (await client.query(`SELECT ${columnList} FROM "${this.schema}"."${table}" ORDER BY 1`)).rows.map((row) => columns.map((col) => row[col]));
+	}
+	isolation() {
+		return {
+			acquire: async (workerId) => {
+				const workerSchema = `worker_${workerId}`;
+				this.originalConnectionString = this.connectionString;
+				const client = await this.getClient();
+				await client.query(`DROP SCHEMA IF EXISTS "${workerSchema}" CASCADE`);
+				await client.query(`CREATE SCHEMA "${workerSchema}"`);
+				const tables = await client.query(`
+                    SELECT tablename FROM pg_tables
+                    WHERE schemaname = 'public'
+                    AND tablename NOT LIKE '_prisma%'
+                `);
+				for (const row of tables.rows) await client.query(`CREATE TABLE "${workerSchema}"."${row.tablename}" (LIKE "public"."${row.tablename}" INCLUDING ALL)`);
+				this.schema = workerSchema;
+				await client.query(`SET search_path TO "${workerSchema}", public`);
+				const url = new URL(this.connectionString);
+				url.searchParams.set("options", `-c search_path=${workerSchema},public`);
+				this.connectionString = url.toString();
+			},
+			reset: async () => {
+				await this.reset();
+			},
+			release: async () => {
+				const client = await this.getClient();
+				const workerSchema = this.schema;
+				this.schema = "public";
+				this.connectionString = this.originalConnectionString;
+				await client.query(`SET search_path TO public`);
+				await client.query(`DROP SCHEMA IF EXISTS "${workerSchema}" CASCADE`);
+			}
+		};
+	}
+};
+/**
+* Create a PostgreSQL service handle.
+*
+* @example
+* // The record key is the name: it is the spec's `database` vocabulary, and
+* // Kebab-cased it is the folder the init script is read from.
+* //   { db: postgres() }          → docker/db/init.sql, then docker/postgres/init.sql
+* //   { analyticsDb: postgres() } → docker/analytics-db/init.sql
+* const events = postgres();
+* // After start: events.connectionString is populated
+*/
+function postgres(options = {}) {
+	return new PostgresHandle(options);
+}
+//#endregion
+//#region src/seams/redis/redis.ts
+var RedisHandle = class {
+	type = "redis";
+	serviceName = null;
+	defaultPort = 6379;
+	defaultImage;
+	environment = {};
+	connectionString = "";
+	started = false;
+	dbIndex = 0;
+	constructor(options = {}) {
+		this.defaultImage = options.image ?? "redis:7";
+	}
+	buildConnectionString(host, port) {
+		return `redis://${host}:${port}`;
+	}
+	createDatabaseAdapter() {
+		return null;
+	}
+	async healthcheck() {
+		if (!this.connectionString) throw new Error("redis: cannot healthcheck — no connection string");
+		try {
+			const { createClient } = await loadPeer("redis", "redis()", async () => await import("redis"));
+			const client = createClient({ url: this.connectionString });
+			await client.connect();
+			await client.ping();
+			await client.disconnect();
+		} catch (error) {
+			throw new Error(`redis healthcheck failed: ${error.message || error.code || String(error)}`, { cause: error });
+		}
+	}
+	async initialize() {}
+	async reset() {
+		const { createClient } = await loadPeer("redis", "redis()", async () => await import("redis"));
+		const client = createClient({
+			url: this.connectionString,
+			database: this.dbIndex
+		});
+		await client.connect();
+		try {
+			await client.flushDb();
+		} finally {
+			await client.disconnect();
+		}
+	}
+	isolation() {
+		return {
+			acquire: async (workerId) => {
+				const numericId = Number.parseInt(workerId, 10) || 0;
+				this.dbIndex = numericId % 15 + 1;
+			},
+			reset: async () => {
+				await this.reset();
+			},
+			release: async () => {
+				await this.reset();
+				this.dbIndex = 0;
+			}
+		};
+	}
+};
+/**
+* Create a Redis service handle.
+*
+* @example
+* // The record key is the name it reports under: { cache: redis() } → "cache".
+* const cache = redis();
+* // After start: cache.connectionString is populated
+*/
+function redis(options = {}) {
+	return new RedisHandle(options);
+}
+//#endregion
+//#region src/seams/sqlite/sqlite.ts
 const SQLITE_FILE_HEADER = Buffer.from("SQLite format 3\0");
 /**
 * Whether `path` looks like a usable SQLite database file: it exists, is at
@@ -3418,6 +3931,35 @@ const SQLITE_FILE_HEADER = Buffer.from("SQLite format 3\0");
 * bytes. Does not validate anything beyond the header — good enough to
 * reject a 0-byte or truncated leftover without opening the file.
 */
+/**
+* `better-sqlite3`'s constructor, loaded the first time a database is opened.
+*
+* The binding is an OPTIONAL peer: it is a native module to compile, and a
+* repository that never declares `sqlite()` has no use for one. Loading it
+* here also puts the pnpm build note where the failure happens.
+*/
+let databaseConstructor = null;
+async function loadDatabase() {
+	if (databaseConstructor === null) {
+		const constructor = await loadPeer("better-sqlite3", "sqlite()", async () => {
+			return (await import("better-sqlite3")).default;
+		});
+		requireBuiltPeer("better-sqlite3", "sqlite()", () => {
+			new constructor(":memory:").close();
+		});
+		databaseConstructor = constructor;
+	}
+	return databaseConstructor;
+}
+/**
+* The constructor, once loaded. The read accessors (`seed`, `query`, `reset`)
+* are reached only AFTER `initialize()` has opened a database, so by the time
+* one of them runs the peer is in hand — which is what lets them stay sync.
+*/
+function database() {
+	if (databaseConstructor === null) throw new Error("sqlite(): the database is not open yet — `initialize()` loads the driver before any read.");
+	return databaseConstructor;
+}
 function isValidSqliteTemplate(path) {
 	if (!existsSync(path)) return false;
 	let fd;
@@ -3506,7 +4048,7 @@ function sqliteTemplateName(options = {}) {
 * The directory a project caches its schema templates in —
 * `<root>/.artifacts/vitest/sqlite/`, created on demand.
 *
-* A project, not a machine. The template used to live in the OS tmpdir, where
+* A project, not a machine. A template in the OS tmpdir is shared, where
 * two checkouts of the same repository shared one file: whichever ran first
 * built it, the other silently inherited that schema, and a branch that changed
 * the schema poisoned the branch beside it. A path under the project root
@@ -3574,7 +4116,7 @@ function removeDatabaseFiles(path) {
 }
 var SqliteHandle = class {
 	type = "sqlite";
-	composeName = null;
+	serviceName = null;
 	defaultPort = 0;
 	defaultImage = "";
 	environment = {};
@@ -3612,7 +4154,8 @@ var SqliteHandle = class {
 	* rather than proceeding into a second concurrent `prisma db push` on the
 	* same file (which is what `database is locked` was).
 	*/
-	async initialize(_composeDir, root) {
+	async initialize(_dockerDir, root) {
+		await loadDatabase();
 		const projectRoot = root ?? discoverRoot(process.cwd());
 		this.templatePath = resolve(sqliteTemplateDir(projectRoot), sqliteTemplateName(this.options));
 		const lockPath = `${this.templatePath}.lock`;
@@ -3656,15 +4199,15 @@ var SqliteHandle = class {
 					},
 					stdio: "pipe"
 				});
-				const tmpDb = new Database(buildPath);
+				const tmpDb = new (database())(buildPath);
 				tmpDb.pragma("wal_checkpoint(TRUNCATE)");
 				tmpDb.close();
 			} else if (this.initSql) {
 				const sql = readFileSync(this.initSql, "utf8");
-				const templateDb = new Database(buildPath);
+				const templateDb = new (database())(buildPath);
 				templateDb.exec(sql);
 				templateDb.close();
-			} else new Database(buildPath).close();
+			} else new (database())(buildPath).close();
 			renameSync(buildPath, this.templatePath);
 		} finally {
 			removeDatabaseFiles(buildPath);
@@ -3673,7 +4216,7 @@ var SqliteHandle = class {
 	getDb() {
 		const dbPath = this.workerDbPath || this.templatePath;
 		if (!this.db) {
-			this.db = new Database(dbPath);
+			this.db = new (database())(dbPath);
 			this.db.pragma("journal_mode = WAL");
 		}
 		return this.db;
@@ -3734,15 +4277,14 @@ function sqlite(options = {}) {
 }
 //#endregion
 //#region src/index.ts
-registerContainerIntegrations({
-	createComposeStack: (composeFile, projectName) => new ComposeStackAdapter(composeFile, projectName),
-	createContainer: (options) => new TestcontainersAdapter(options),
-	parseComposeFile
+/**
+* The module-scope network double, on msw's node server — what a test with no
+* chain to hang contracts on reaches for (chapter 16).
+*/
+const intercept = interceptThrough(async (contracts) => {
+	const { registerContracts } = await import("./server.js");
+	return await registerContracts(contracts);
 });
-registerComposeServiceFactory("postgres", (service) => postgres({
-	composeService: service.name,
-	env: service.environment
-}));
-registerComposeServiceFactory("redis", (service) => redis({ composeService: service.name }));
+registerContainerIntegrations({ createContainer: (options) => new TestcontainersAdapter(options) });
 //#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 { Matcher, ProcessHandle, anthropic, banner, button, clock, complementary, component, content, contentinfo, defineContract, defineContracts, dialog, disabled, enabled, field, focused, form, heading, http, intercept, link, listitem, main, match, mockOf, navigation, openai, option, postgres, processService as process, redis, region, required, row, search, selected, specification, sqlite, status, table, testId, text, valued, waitUntil, within };