@jterrazz/test 7.1.0 → 9.0.0

package/dist/index.js

@@ -1,142 +1,393 @@
-import { n as redis, r as postgres, t as sqlite } from "./sqlite.adapter.js";
-import { n as mockOfDate, t as mockOf } from "./mock-of.js";
-import { execSync, spawn } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
-import { readdir } from "node:fs/promises";
+import { i as match, n as Matcher, r as TOKEN_KINDS, t as CaptureScope } from "./match.js";
+import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { parse } from "yaml";
-//#region src/builder/cli/adapters/exec.adapter.ts
+import { execSync, spawn, spawnSync } from "node:child_process";
+import { Client } from "pg";
+import { readdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+import Database from "better-sqlite3";
+import { mockDeep } from "vitest-mock-extended";
+import MockDatePackage from "mockdate";
+//#region src/core/specification/shared/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/integrations/compose/compose-parser.ts
 /**
-* Build a child-process env from the parent env plus user overrides.
-* `null` overrides delete keys (e.g. `INIT_CWD: null`).
+* Parse a docker-compose file and extract service definitions.
 */
-function buildEnv(extra) {
-	const env = {
-		...process.env,
-		INIT_CWD: void 0
+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("=");
+			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)
 	};
-	if (extra) for (const [key, value] of Object.entries(extra)) if (value === null) delete env[key];
-	else env[key] = value;
-	return env;
 }
+//#endregion
+//#region src/integrations/compose/compose.ts
 /**
-* Executes CLI commands via Node.js child_process.
-* Uses `execSync` for one-shot commands and `spawn` for long-running processes.
-* Used by the `cli()` specification runner.
+* Start the full compose stack and stop it all on cleanup.
+* Supports per-worker project names for parallel execution.
 */
-var ExecAdapter = class {
-	command;
-	constructor(command) {
-		this.command = command;
+var ComposeStackAdapter = class {
+	composeFile;
+	projectName;
+	started = false;
+	constructor(composeFile, projectName) {
+		this.composeFile = composeFile;
+		this.projectName = projectName ?? null;
 	}
-	async exec(args, cwd, extraEnv) {
-		const env = buildEnv(extraEnv);
+	get projectFlag() {
+		return this.projectName ? `-p ${this.projectName}` : "";
+	}
+	run(command) {
 		try {
-			return {
-				exitCode: 0,
-				stdout: execSync(`${this.command} ${args}`, {
-					cwd,
-					encoding: "utf8",
-					env,
-					stdio: [
-						"pipe",
-						"pipe",
-						"pipe"
-					]
-				}),
-				stderr: ""
-			};
+			return execSync(command, {
+				cwd: dirname(this.composeFile),
+				encoding: "utf8",
+				timeout: 12e4
+			}).trim();
 		} catch (error) {
-			return {
-				exitCode: error.status ?? 1,
-				stdout: error.stdout?.toString() ?? "",
-				stderr: error.stderr?.toString() ?? ""
-			};
+			const stderr = error.stderr?.toString().trim() ?? error.message;
+			throw new Error(`docker compose failed: ${stderr}`, { cause: error });
 		}
 	}
-	async spawn(args, cwd, options, extraEnv) {
-		const env = buildEnv(extraEnv);
-		return new Promise((resolve) => {
-			let stdout = "";
-			let stderr = "";
-			let resolved = false;
-			const child = spawn(this.command, args.split(/\s+/).filter(Boolean), {
-				cwd,
-				env,
-				stdio: [
-					"pipe",
-					"pipe",
-					"pipe"
-				]
-			});
-			const finish = (exitCode) => {
-				if (resolved) return;
-				resolved = true;
-				child.kill("SIGTERM");
-				resolve({
-					exitCode,
-					stdout,
-					stderr
-				});
-			};
-			let patternMatched = false;
-			const checkPattern = () => {
-				if (!patternMatched && (stdout.includes(options.waitFor) || stderr.includes(options.waitFor))) {
-					patternMatched = true;
-					finish(0);
-				}
-			};
-			child.stdout?.on("data", (data) => {
-				stdout += data.toString();
-				checkPattern();
-			});
-			child.stderr?.on("data", (data) => {
-				stderr += data.toString();
-				checkPattern();
-			});
-			child.on("exit", (code) => {
-				if (!patternMatched) finish(code === 0 ? 1 : code ?? 1);
-			});
-			setTimeout(() => finish(124), options.timeout);
-		});
+	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;
+	}
+	getMappedPort(serviceName, containerPort) {
+		const port = this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} port ${serviceName} ${containerPort}`).split(":").pop();
+		return Number(port);
+	}
+	getHost() {
+		return "localhost";
 	}
 };
 //#endregion
-//#region src/builder/http/adapters/fetch.adapter.ts
-/**
-* 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(/\/$/, "");
+//#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
+		};
 	}
-	async request(method, path, body, headers) {
-		const init = {
-			method,
-			headers: {
-				"Content-Type": "application/json",
-				...headers
+	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 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 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 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);
+	}
+	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`);
 			}
 		};
-		if (body !== void 0) init.body = JSON.stringify(body);
-		const response = await fetch(`${this.baseUrl}${path}`, init);
-		const responseBody = await response.json().catch(() => null);
-		const responseHeaders = {};
-		response.headers.forEach((value, key) => {
-			responseHeaders[key] = value;
+	}
+};
+/**
+* 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 {
-			status: response.status,
-			body: responseBody,
-			headers: responseHeaders
+			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/, 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 new Promise((resolve) => {
+			let output = "";
+			stream.on("data", (chunk) => {
+				output += chunk.toString();
+			});
+			stream.on("end", () => {
+				resolve(output);
+			});
+			setTimeout(() => {
+				resolve(output);
+			}, 1e3);
+		});
+	}
+};
 //#endregion
-//#region src/builder/http/adapters/hono.adapter.ts
+//#region src/integrations/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.
@@ -154,7 +405,7 @@ var HonoAdapter = class {
 				...headers
 			}
 		};
-		if (body !== void 0) init.body = JSON.stringify(body);
+		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 = {};
@@ -169,76 +420,387 @@ var HonoAdapter = class {
 	}
 };
 //#endregion
-//#region src/builder/common/directory.ts
-/**
-* Default ignore patterns — paths that should never appear in a tracked snapshot.
-* Each entry is matched against any path segment OR a path prefix.
-*/
-const DEFAULT_IGNORES = [
-	".git",
-	".DS_Store",
-	"node_modules",
-	".next",
-	"dist",
-	".turbo",
-	".cache"
-];
+//#region src/core/http-files/http-file.ts
+function splitSections(content) {
+	const lines = content.split(/\r?\n/);
+	let index = 0;
+	while (index < lines.length && lines[index].trim() === "") index++;
+	const startLine = lines[index] ?? "";
+	index++;
+	const headerLines = [];
+	while (index < lines.length && lines[index].trim() !== "") {
+		headerLines.push(lines[index]);
+		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+)$/.exec(startLine.trim());
+	if (!start?.groups) 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: start.groups.method,
+		path: start.groups.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 start = /^HTTP\/1\.1\s+(?<status>\S+)(?:\s+.*)?$/.exec(startLine.trim());
+	if (!start?.groups) 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: start.groups.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("");
+		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/core/matching/structural.ts
 /**
-* Recursively walk a directory, returning sorted relative paths of files only.
-* Ignored entries (default + caller-supplied) are skipped.
+* Structural comparison engine shared by every fixture matcher.
+*
+* Handles three kinds of "expected" values:
+* - plain JSON values → strict deep equality
+* - {@link Matcher} instances (code-side `match.*`)
+* - strings containing `{{placeholder}}` forms (file-side fixtures)
+*
+* One unified `{{token}}` grammar (CONVENTIONS D4) — the same vocabulary
+* works in `expected/*.http` (body and headers), `expected/*.json`, and
+* text snapshots (`expected/*.txt`).
+*
+* Ref captures (`match.ref(name)` / `{{type#name}}`) are recorded in the
+* {@link CaptureScope} supplied by the caller.
 */
-async function walkDirectory(root, options = {}) {
-	const ignores = new Set([...DEFAULT_IGNORES, ...options.ignore ?? []]);
-	const out = [];
-	async function walk(current) {
-		let entries;
-		try {
-			entries = await readdir(current);
-		} catch {
-			return;
-		}
-		for (const entry of entries) {
-			if (ignores.has(entry)) continue;
-			const abs = resolve(current, entry);
-			const stat = statSync(abs);
-			if (stat.isDirectory()) await walk(abs);
-			else if (stat.isFile()) out.push(relative(root, abs).split(sep).join("/"));
+const UUID_SOURCE = "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}";
+const ULID_SOURCE = "[0-9A-HJKMNP-TV-Z]{26}";
+const ISO8601_SOURCE = String.raw`\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})`;
+const DATE_SOURCE = String.raw`\d{4}-\d{2}-\d{2}`;
+const TIME_SOURCE = String.raw`\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?`;
+const DURATION_SOURCE = String.raw`\d+(?:\.\d+)?(?:ms|s|m|h)`;
+const NUMBER_SOURCE = String.raw`-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?`;
+const INT_SOURCE = String.raw`-?\d+`;
+const FLOAT_SOURCE = String.raw`-?\d+\.\d+`;
+const SEMVER_SOURCE = String.raw`\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?`;
+const SHA_SOURCE = "[0-9a-f]{7,64}";
+const HEX_SOURCE = "[0-9a-fA-F]+";
+const BASE64_SOURCE = "[A-Za-z0-9+/]+={0,2}";
+const PORT_SOURCE = String.raw`(?:6553[0-5]|655[0-2]\d|65[0-4]\d{2}|6[0-4]\d{3}|[1-5]\d{4}|\d{1,4})`;
+const IP_OCTET = String.raw`(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)`;
+const IP_SOURCE = String.raw`(?:${IP_OCTET}\.){3}${IP_OCTET}`;
+const URL_SOURCE = String.raw`https?:\/\/[^\s"'<>]+`;
+const EMBEDDED_SOURCES = {
+	base64: BASE64_SOURCE,
+	date: DATE_SOURCE,
+	duration: DURATION_SOURCE,
+	email: String.raw`[^\s@"'<>]+@[^\s@"'<>]+\.[^\s@"'<>]+`,
+	float: FLOAT_SOURCE,
+	hex: HEX_SOURCE,
+	int: INT_SOURCE,
+	ip: IP_SOURCE,
+	iso8601: ISO8601_SOURCE,
+	number: NUMBER_SOURCE,
+	path: String.raw`\.{0,2}\/[^\s"'<>]*`,
+	port: PORT_SOURCE,
+	semver: SEMVER_SOURCE,
+	sha: SHA_SOURCE,
+	time: TIME_SOURCE,
+	ulid: ULID_SOURCE,
+	url: URL_SOURCE,
+	uuid: UUID_SOURCE
+};
+const wholeRe = (source) => new RegExp(`^(?:${source})$`);
+const WHOLE_RES = Object.fromEntries(Object.entries(EMBEDDED_SOURCES).map(([kind, source]) => [kind, wholeRe(source)]));
+const PLACEHOLDER_RE = new RegExp(String.raw`\{\{(?<kind>${[...TOKEN_KINDS].sort((a, b) => b.length - a.length).join("|")})(?:#(?<ref>[\w.-]+))?\}\}`, "g");
+/** Whether a fixture string contains at least one `{{placeholder}}`. */
+function hasPlaceholders(value) {
+	PLACEHOLDER_RE.lastIndex = 0;
+	return PLACEHOLDER_RE.test(value);
+}
+/** Key-order-independent stringification for captured-object comparison. */
+function stableStringify(value) {
+	if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : 1).map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`).join(",")}}`;
+	return JSON.stringify(value) ?? "undefined";
+}
+function capturedEquals(a, b) {
+	if (Object.is(a, b)) return true;
+	if (typeof a === "number" && typeof b === "string" || typeof a === "string" && typeof b === "number") return String(a) === String(b);
+	if (a !== null && b !== null && typeof a === "object" && typeof b === "object") return stableStringify(a) === stableStringify(b);
+	return false;
+}
+function recordRef(name, actual, scope) {
+	if (scope.has(name)) return capturedEquals(scope.get(name), actual);
+	scope.set(name, actual);
+	return true;
+}
+function isPortValue(value) {
+	return Number.isInteger(value) && value >= 0 && value <= 65535;
+}
+function kindMatches(kind, actual, scope) {
+	switch (kind) {
+		case "any": return true;
+		case "float":
+			if (typeof actual === "number") return Number.isFinite(actual);
+			return typeof actual === "string" && WHOLE_RES.float.test(actual);
+		case "int":
+			if (typeof actual === "number") return Number.isInteger(actual);
+			return typeof actual === "string" && WHOLE_RES.int.test(actual);
+		case "number":
+			if (typeof actual === "number") return Number.isFinite(actual);
+			return typeof actual === "string" && WHOLE_RES.number.test(actual);
+		case "port":
+			if (typeof actual === "number") return isPortValue(actual);
+			return typeof actual === "string" && WHOLE_RES.port.test(actual) && isPortValue(Number(actual));
+		case "string": return typeof actual === "string";
+		case "workdir": return typeof actual === "string" && scope.workdir !== void 0 ? actual === scope.workdir : false;
+		default: {
+			const re = WHOLE_RES[kind];
+			return re !== void 0 && typeof actual === "string" && re.test(actual);
 		}
 	}
-	await walk(root);
-	out.sort();
-	return out;
 }
-/**
-* Compare two directory trees file-by-file.
-* Binary files are compared by byte equality but reported without inline diff.
-*/
-async function diffDirectories(expectedRoot, actualRoot, options = {}) {
-	const expectedFiles = await walkDirectory(expectedRoot, options);
-	const actualFiles = await walkDirectory(actualRoot, options);
-	const expectedSet = new Set(expectedFiles);
-	const actualSet = new Set(actualFiles);
-	const added = actualFiles.filter((f) => !expectedSet.has(f));
-	const removed = expectedFiles.filter((f) => !actualSet.has(f));
-	const changed = [];
-	for (const file of expectedFiles) {
-		if (!actualSet.has(file)) continue;
-		const expected = readFileSync(resolve(expectedRoot, file), "utf8");
-		const actual = readFileSync(resolve(actualRoot, file), "utf8");
-		if (expected !== actual) changed.push({
-			actual,
-			expected,
-			path: file
+function matcherMatches(matcher, actual, scope) {
+	if (matcher.kind === "regex") return typeof actual === "string" && matcher.regex.test(actual);
+	if (matcher.kind === "ref") {
+		if (matcher.notRef && scope.has(matcher.notRef) && capturedEquals(scope.get(matcher.notRef), actual)) return false;
+		return recordRef(matcher.refName, actual, scope);
+	}
+	return kindMatches(matcher.kind, actual, scope);
+}
+function placeholderSource(kind, scope) {
+	if (kind === "workdir") return scope.workdir === void 0 ? "(?!)" : escapeRegExp(scope.workdir);
+	const source = EMBEDDED_SOURCES[kind];
+	if (source) return source;
+	return kind === "any" ? String.raw`[\s\S]*?` : String.raw`[^\n]*?`;
+}
+function escapeRegExp(text) {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+function parsePlaceholderString(expected, scope) {
+	PLACEHOLDER_RE.lastIndex = 0;
+	const refs = [];
+	let pattern = "^";
+	let lastIndex = 0;
+	let single = null;
+	let count = 0;
+	for (const found of expected.matchAll(PLACEHOLDER_RE)) {
+		const kind = found.groups.kind;
+		const ref = found.groups.ref;
+		pattern += escapeRegExp(expected.slice(lastIndex, found.index));
+		pattern += `(${placeholderSource(kind, scope)})`;
+		refs.push({
+			index: count,
+			kind,
+			ref
 		});
+		count++;
+		lastIndex = found.index + found[0].length;
+		if (found.index === 0 && found[0].length === expected.length) single = {
+			kind,
+			ref
+		};
 	}
+	pattern += `${escapeRegExp(expected.slice(lastIndex))}$`;
 	return {
-		added,
-		changed,
-		removed
+		pattern: new RegExp(pattern),
+		refs,
+		single
 	};
 }
+function placeholderStringMatches(expected, actual, scope) {
+	const parsed = parsePlaceholderString(expected, scope);
+	if (parsed.single) {
+		if (!kindMatches(parsed.single.kind, actual, scope)) return false;
+		if (parsed.single.ref) return recordRef(parsed.single.ref, actual, scope);
+		return true;
+	}
+	if (typeof actual !== "string" && typeof actual !== "number") return false;
+	const text = String(actual);
+	const found = parsed.pattern.exec(text);
+	if (!found) return false;
+	for (const entry of parsed.refs) {
+		if (!entry.ref) continue;
+		if (!recordRef(entry.ref, found[entry.index + 1], scope)) return false;
+	}
+	return true;
+}
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+* Deep structural equality with matcher / placeholder support. Ref captures
+* are recorded in `scope` in traversal order (arrays left-to-right, object
+* keys in expected-key order).
+*/
+function structuralEquals(expected, actual, scope) {
+	if (expected instanceof Matcher) return matcherMatches(expected, actual, scope);
+	if (typeof expected === "string" && hasPlaceholders(expected)) return placeholderStringMatches(expected, actual, scope);
+	if (Array.isArray(expected)) {
+		if (!Array.isArray(actual) || actual.length !== expected.length) return false;
+		return expected.every((item, i) => structuralEquals(item, actual[i], scope));
+	}
+	if (isPlainObject(expected)) {
+		if (!isPlainObject(actual)) return false;
+		const expectedKeys = Object.keys(expected);
+		const actualKeys = Object.keys(actual);
+		if (expectedKeys.length !== actualKeys.length) return false;
+		return expectedKeys.every((key) => key in actual && structuralEquals(expected[key], actual[key], scope));
+	}
+	return Object.is(expected, actual);
+}
+/**
+* Deep structural SUBSET match (toMatchObject-style) with matcher /
+* placeholder support. Plain objects match when every expected key is present
+* and recursively subset-matches — the actual value may carry extra keys.
+* Arrays require equal length with each element subset-matched. Leaves fall
+* back to {@link structuralEquals} semantics (matchers, placeholders, strict
+* equality). Used by request-body filters on intercept triggers.
+*/
+function structuralSubset(expected, actual, scope) {
+	if (expected instanceof Matcher) return matcherMatches(expected, actual, scope);
+	if (typeof expected === "string" && hasPlaceholders(expected)) return placeholderStringMatches(expected, actual, scope);
+	if (Array.isArray(expected)) {
+		if (!Array.isArray(actual) || actual.length !== expected.length) return false;
+		return expected.every((item, i) => structuralSubset(item, actual[i], scope));
+	}
+	if (isPlainObject(expected)) {
+		if (!isPlainObject(actual)) return false;
+		return Object.keys(expected).every((key) => key in actual && structuralSubset(expected[key], actual[key], scope));
+	}
+	return Object.is(expected, actual);
+}
+/**
+* Multi-line text comparison with `{{token}}` support — used by text
+* snapshots (`expected/*.txt`). Without placeholders this is strict equality.
+*/
+function textEquals(expected, actual, scope) {
+	if (!hasPlaceholders(expected)) return expected === actual;
+	return placeholderStringMatches(expected, actual, scope);
+}
+/**
+* Render an expected value for failure diffs and serialization: Matcher
+* instances become their placeholder text, everything else is untouched.
+*/
+function renderExpected(value) {
+	if (value instanceof Matcher) return value.toString();
+	if (Array.isArray(value)) return value.map((item) => renderExpected(item));
+	if (isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, renderExpected(item)]));
+	return value;
+}
+/**
+* Substitute the framework-known cwd (`workdir`) for its `{{workdir}}` token in
+* every string leaf of a structured value. The structural mirror of the text
+* path's `actual.replaceAll(workdir, '{{workdir}}')` — so a golden written under
+* `TEST_UPDATE=1` stores the token, not a run-specific temp path (CONVENTIONS
+* D5). A no-op when `workdir` is undefined (no cwd, e.g. api/jobs mode).
+*/
+function substituteWorkdirDeep(value, workdir) {
+	if (typeof value === "string") return value.replaceAll(workdir, "{{workdir}}");
+	if (Array.isArray(value)) return value.map((item) => substituteWorkdirDeep(item, workdir));
+	if (isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, substituteWorkdirDeep(item, workdir)]));
+	return value;
+}
+/**
+* Update-mode merge: rewrite a fixture from the actual output while
+* preserving every segment of the previous fixture that was covered by a
+* placeholder (and still matches the actual value).
+*
+* Token preservation is symmetric with the text path (CONVENTIONS D5): a
+* previous `{{placeholder}}` (including `{{workdir}}`) that still matches the
+* RAW actual value is kept; every other leaf is taken from the actual output
+* with the framework-known cwd substituted back to `{{workdir}}`.
+*/
+function mergePreservingPlaceholders(previous, actual, workdir) {
+	const scope = new CaptureScope(workdir);
+	const subst = (value) => workdir === void 0 ? value : substituteWorkdirDeep(value, workdir);
+	function merge(prev, act) {
+		if (typeof prev === "string" && hasPlaceholders(prev)) return placeholderStringMatches(prev, act, scope) ? prev : subst(act);
+		if (Array.isArray(prev) && Array.isArray(act)) return act.map((item, i) => i < prev.length ? merge(prev[i], item) : subst(item));
+		if (isPlainObject(prev) && isPlainObject(act)) return Object.fromEntries(Object.entries(act).map(([key, item]) => [key, key in prev ? merge(prev[key], item) : subst(item)]));
+		return subst(act);
+	}
+	return merge(previous, actual);
+}
+/**
+* Update-mode merge for text snapshots: line-by-line, a previous line whose
+* placeholders still match the actual line is preserved; every other line is
+* taken from the actual output. Values the framework knows to be dynamic
+* (`{{workdir}}`) are substituted automatically (CONVENTIONS D5).
+*/
+function mergeTextPreservingPlaceholders(previous, actual, scope) {
+	const substituted = scope.workdir === void 0 ? actual : actual.replaceAll(scope.workdir, "{{workdir}}");
+	if (previous === null) return substituted;
+	const prevLines = previous.split("\n");
+	return substituted.split("\n").map((line, i) => {
+		const prev = prevLines[i];
+		if (prev === void 0 || !hasPlaceholders(prev)) return line;
+		return textEquals(prev, line, new CaptureScope(scope.workdir)) || textEquals(prev, actual.split("\n")[i] ?? line, new CaptureScope(scope.workdir)) ? prev : line;
+	}).join("\n");
+}
 //#endregion
-//#region src/builder/common/reporter.ts
+//#region src/core/specification/shared/reporter.ts
 const GREEN = "\x1B[32m";
 const RED = "\x1B[31m";
 const DIM = "\x1B[2m";
@@ -320,6 +882,27 @@ function formatResponseDiff(file, expected, actual) {
 	}
 	return lines.join("\n");
 }
+function formatStdoutDiff(file, expected, actual) {
+	const lines = [];
+	lines.push(`Output mismatch (${file})`);
+	lines.push("");
+	lines.push(`${GREEN}- Expected${RESET}`);
+	lines.push(`${RED}+ Received${RESET}`);
+	lines.push("");
+	const expectedLines = expected.split("\n");
+	const actualLines = actual.split("\n");
+	const maxLines = Math.max(expectedLines.length, actualLines.length);
+	for (let i = 0; i < maxLines; i++) {
+		const exp = expectedLines[i];
+		const act = actualLines[i];
+		if (exp === act) lines.push(`  ${exp}`);
+		else {
+			if (exp !== void 0) lines.push(`${GREEN}- ${exp}${RESET}`);
+			if (act !== void 0) lines.push(`${RED}+ ${act}${RESET}`);
+		}
+	}
+	return lines.join("\n");
+}
 function formatDirectoryDiff(fixtureName, diff, hint) {
 	const lines = [];
 	const total = diff.added.length + diff.removed.length + diff.changed.length;
@@ -367,70 +950,155 @@ function rowLabel(n) {
 function formatRow(row) {
 	return row.map((v) => String(v ?? "null")).join("  |  ");
 }
-/** Strip ANSI escape codes from a string. */
-function stripAnsi(str) {
-	return str.replace(/\x1b\[[0-9;]*m/g, "");
-}
-/** Strip ANSI codes and replace volatile tokens (ports, durations) with placeholders. */
-function normalizeOutput(str) {
-	return stripAnsi(str).replace(/localhost:\d+/g, "localhost:PORT").replace(/\d+ms/g, "Xms").replace(/\d+\.\d+s/g, "X.Xs").trim();
-}
 //#endregion
-//#region src/builder/common/directory-accessor.ts
+//#region src/core/specification/shared/result/directory.ts
+const DEFAULT_IGNORES = [
+	".git",
+	".DS_Store",
+	"node_modules",
+	".next",
+	"dist",
+	".turbo",
+	".cache"
+];
 /**
-* Detect whether the user wants to update snapshots — `true` for any of:
-*   - vitest run with `-u` / `--update`
-*   - JTERRAZZ_TEST_UPDATE=1
-*   - UPDATE_SNAPSHOTS=1
+* Recursively walk a directory, returning sorted relative paths of files only.
 */
-function shouldUpdateSnapshots() {
-	if (process.env.JTERRAZZ_TEST_UPDATE === "1") return true;
-	if (process.env.UPDATE_SNAPSHOTS === "1") return true;
-	if (process.argv.includes("-u") || process.argv.includes("--update")) return true;
-	return false;
+async function walkDirectory(root, options = {}) {
+	const ignores = /* @__PURE__ */ new Set([...DEFAULT_IGNORES, ...options.ignore ?? []]);
+	const out = [];
+	async function walk(current) {
+		let entries;
+		try {
+			entries = await readdir(current);
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (ignores.has(entry)) continue;
+			const abs = resolve(current, entry);
+			const stat = statSync(abs);
+			if (stat.isDirectory()) await walk(abs);
+			else if (stat.isFile()) out.push(relative(root, abs).split(sep).join("/"));
+		}
+	}
+	await walk(root);
+	out.sort();
+	return out;
 }
 /**
-* Handle to a directory produced by a specification run.
-* Supports snapshot-based assertions via {@link toMatchFixture} and file listing via {@link files}.
+* Compare two directory trees file-by-file. Fixture file contents honor the
+* unified `{{token}}` grammar (CONVENTIONS D4) — captures are recorded in
+* `scope` in sorted-path order.
+*/
+async function diffDirectories(expectedRoot, actualRoot, options = {}) {
+	const expectedFiles = await walkDirectory(expectedRoot, options);
+	const actualFiles = await walkDirectory(actualRoot, options);
+	const expectedSet = new Set(expectedFiles);
+	const actualSet = new Set(actualFiles);
+	const scope = options.scope ?? new CaptureScope();
+	const added = actualFiles.filter((f) => !expectedSet.has(f));
+	const removed = expectedFiles.filter((f) => !actualSet.has(f));
+	const changed = [];
+	for (const file of expectedFiles) {
+		if (!actualSet.has(file)) continue;
+		const expected = readFileSync(resolve(expectedRoot, file), "utf8");
+		const actual = readFileSync(resolve(actualRoot, file), "utf8");
+		if (!textEquals(expected, actual, scope)) changed.push({
+			actual,
+			expected,
+			path: file
+		});
+	}
+	return {
+		added,
+		changed,
+		removed
+	};
+}
+/**
+* Read-only accessor for a directory produced by a spec action.
+*
+* Assertions go through `expect()` (async — they walk the disk):
+* `await expect(result.directory('out')).toMatch('scaffold/out')`
+* compares the tree against the fixture directory `expected/<name>/`.
 */
 var DirectoryAccessor = class {
-	absPath;
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** @internal Absolute path of the directory under assertion. */
+	root;
+	/** @internal Test-file directory — fixture resolution root for matchers. */
 	testDir;
-	constructor(absPath, testDir) {
-		this.absPath = absPath;
+	constructor(absPath, testDir, captures) {
+		this.root = absPath;
 		this.testDir = testDir;
+		this.captures = captures ?? new CaptureScope();
 	}
-	/**
-	* Compare the directory tree against `expected/{name}/` (relative to the test file).
-	* On mismatch, throws with a structured diff. With update mode enabled, the
-	* fixture is overwritten with the current contents instead.
-	*/
-	async toMatchFixture(name, options = {}) {
-		const fixtureDir = resolve(this.testDir, "expected", name);
-		if (options.update ?? shouldUpdateSnapshots()) {
-			rmSync(fixtureDir, {
-				force: true,
-				recursive: true
-			});
-			mkdirSync(fixtureDir, { recursive: true });
-			cpSync(this.absPath, fixtureDir, { recursive: true });
-			return;
-		}
-		if (!existsSync(fixtureDir)) throw new Error(`Directory fixture "${name}" does not exist at ${fixtureDir}.\nRun with JTERRAZZ_TEST_UPDATE=1 (or vitest -u) to create it.`);
-		const diff = await diffDirectories(fixtureDir, this.absPath, { ignore: options.ignore });
-		if (diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0) return;
-		throw new Error(formatDirectoryDiff(name, diff, "Run with JTERRAZZ_TEST_UPDATE=1 to update the fixture."));
+	/** List all files (recursively) under the directory, sorted. */
+	async files(options = {}) {
+		return walkDirectory(this.root, options);
 	}
-	/**
-	* List all files in the directory (recursive, sorted, ignoring defaults).
-	* Useful for ad-hoc assertions when you don't want a full snapshot.
-	*/
+};
+//#endregion
+//#region src/core/specification/shared/result/filesystem.ts
+/**
+* Read-only accessor for the whole temporary working directory used by a
+* command spec.
+*
+* Assertions go through `expect()` (async — they walk the disk):
+* `await expect(result.filesystem).toMatch('scaffolded')` compares the
+* tree against the fixture directory `expected/<name>/`.
+*/
+var FilesystemAccessor = class {
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** The absolute path of the temporary working directory. */
+	cwd;
+	/** @internal Test-file directory — fixture resolution root for matchers. */
+	testDir;
+	constructor(cwd, testDir, captures) {
+		this.cwd = cwd;
+		this.testDir = testDir;
+		this.captures = captures ?? new CaptureScope();
+	}
+	/** List all files (recursively) under the working directory, sorted. */
 	async files(options = {}) {
-		return walkDirectory(this.absPath, options);
+		return walkDirectory(this.cwd, options);
 	}
 };
 //#endregion
-//#region src/builder/common/grep.ts
+//#region src/core/specification/shared/caller.ts
+/**
+* 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 = dirname(fileURLToPath(import.meta.url));
+/**
+* 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")).stack;
+	if (!stack) throw new Error("Cannot detect caller directory: no stack trace");
+	const lines = stack.split("\n");
+	for (const line of lines) {
+		const match = line.match(/at\s+(?:.*?\()?(?:file:\/\/)?(?<filePath>[^:)]+):\d+:\d+/);
+		if (!match?.groups?.filePath) continue;
+		const filePath = match.groups.filePath;
+		if (filePath.includes("node_modules")) continue;
+		if ((filePath.includes("/src/core/") || filePath.includes("/src/integrations/") || filePath.includes("/src/vitest/") || resolve(filePath, "..") === FRAMEWORK_DIR) && !/\.test\.[cm]?[jt]s$/.test(filePath)) continue;
+		return resolve(filePath, "..");
+	}
+	throw new Error("Cannot detect caller directory from stack trace");
+}
+//#endregion
+//#region src/core/specification/shared/result/grep.ts
 /**
 * Extract text blocks from output that contain a pattern.
 * Splits by blank lines (how linter/compiler output is structured),
@@ -444,841 +1112,1461 @@ function grep(output, pattern) {
 	return output.replace(/\x1b\[[0-9;]*m/g, "").split(/\n\s*\n/).filter((block) => block.includes(pattern)).join("\n\n");
 }
 //#endregion
-//#region src/builder/common/response-accessor.ts
-/** Accessor for an HTTP response body with file-based assertion support. */
-var ResponseAccessor = class {
-	body;
+//#region src/core/specification/shared/result/text.ts
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+/** Strip ANSI escape sequences from a string. */
+function stripAnsiCodes(value) {
+	return value.replace(ANSI_RE, "");
+}
+/**
+* Read-only accessor for a captured text handle — THE universal one: stdout,
+* stderr, container logs, and file text all surface as a `TextAccessor`.
+*
+* Backed by a primitive string, exposed via {@link text}, but also provides
+* `toString()` / `valueOf()` for string coercion, so common patterns like
+* `String(result.stdout)` and template-literal interpolation still work.
+*
+* ANSI escape sequences are stripped by default before every comparison
+* (CONVENTIONS D6) — `.text` stays raw. The runner `transform` option remains
+* an escape hatch for application noise not covered by the `{{token}}`
+* grammar.
+*
+* Text operations are **closed** over the type: `.grep(pattern)` returns a
+* `TextAccessor` (not a bare string), preserving the `expected/`-resolution
+* context and the `transform`, so results are chainable
+* (`result.stdout.grep(a).grep(b)`) and snapshot-able
+* (`expect(result.stdout.grep('users.ts')).toMatch('block.txt')`).
+*
+* Assertions go through `expect()` matchers: `expect(result.stdout).toContain(...)`
+* and `expect(result.stdout).toMatch('name.txt')` (resolved against
+* `expected/<name>`, flat — with `{{token}}` support, CONVENTIONS D4).
+*/
+var TextAccessor = class TextAccessor {
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** @internal Stream label used in failure messages ("stdout" / "stderr"). */
+	streamName;
+	/** @internal Test-file directory — fixture resolution root for matchers. */
 	testDir;
-	constructor(body, testDir) {
-		this.body = body;
+	/** The raw captured text (never transformed, ANSI preserved). */
+	text;
+	/** @internal Normaliser applied before comparisons, never to fixtures. */
+	transform;
+	constructor(value, streamName, testDir, options = {}) {
+		this.text = value;
+		this.streamName = streamName;
 		this.testDir = testDir;
+		this.transform = options.transform;
+		this.captures = options.captures ?? new CaptureScope();
 	}
-	/**
-	* Assert that the response body matches the JSON in `responses/{file}`.
-	*
-	* @example
-	*   result.response.toMatchFile("expected-items.json");
-	*/
-	toMatchFile(file) {
-		const expected = JSON.parse(readFileSync(resolve(this.testDir, "responses", file), "utf8"));
-		if (JSON.stringify(this.body) !== JSON.stringify(expected)) throw new Error(formatResponseDiff(file, expected, this.body));
-	}
-};
-//#endregion
-//#region src/builder/common/table-assertion.ts
-/** Assertion helper for verifying database table contents after a specification run. */
-var TableAssertion = class {
-	tableName;
-	db;
-	constructor(tableName, db) {
-		this.tableName = tableName;
-		this.db = db;
+	/** @internal The text as compared by matchers — ANSI stripped, transform applied. */
+	get comparableText() {
+		const stripped = stripAnsiCodes(this.text);
+		return this.transform ? this.transform(stripped) : stripped;
 	}
 	/**
-	* Assert that the table contains exactly the expected rows for the given columns.
-	*
-	* @example
-	*   await result.table("users").toMatch({
-	*     columns: ["name", "email"],
-	*     rows: [["Alice", "alice@example.com"]],
-	*   });
+	* Keep only the blank-line-separated blocks of the text that contain
+	* `pattern` (how linter/compiler output is structured), returned as a new
+	* `TextAccessor` — the same subject type, so the result is chainable and
+	* snapshot-able. The scalpel for probing large tool outputs; snapshot the
+	* whole surface by default, reach for `.grep()` for targeted checks.
 	*/
-	async toMatch(expected) {
-		const actual = await this.db.query(this.tableName, expected.columns);
-		if (JSON.stringify(actual) !== JSON.stringify(expected.rows)) throw new Error(formatTableDiff(this.tableName, expected.columns, expected.rows, actual));
+	grep(pattern) {
+		return new TextAccessor(grep(this.text, pattern), this.streamName, this.testDir, {
+			captures: this.captures,
+			transform: this.transform
+		});
+	}
+	toString() {
+		return this.text;
 	}
-	/** Assert that the table has zero rows. */
-	async toBeEmpty() {
-		const actual = await this.db.query(this.tableName, ["*"]);
-		if (actual.length !== 0) throw new Error(`Expected table "${this.tableName}" to be empty, but it has ${actual.length} rows`);
+	valueOf() {
+		return this.text;
 	}
 };
+/**
+* Wrap an arbitrary string into a {@link TextAccessor} anchored on the calling
+* test's directory — the same caller-detection the builders use.
+*
+* The product surface of a test framework is its own error messages, checker
+* output, and reports; those deserve the same goldening as any other output.
+* `text()` makes an ad-hoc string a first-class snapshot subject:
+*
+* ```typescript
+* const message = await catchMessage(() => expect(result.response).toMatch('wrong-body.http'));
+* expect(text(message)).toMatch('wrong-body-error.txt'); // resolves to expected/
+* ```
+*
+* ANSI is stripped before every comparison (the raw form stays on `.text`),
+* the `{{token}}` grammar applies to the fixture, and `.grep()` composition
+* works exactly as on any stream accessor.
+*/
+function text(value) {
+	return new TextAccessor(value, "text", getCallerDir());
+}
 //#endregion
-//#region src/builder/common/result.ts
+//#region src/core/specification/shared/result/json.ts
 /**
-* The outcome of a single specification run.
-* Provides accessors for CLI output, HTTP responses, files, directories, and database tables.
+* Read-only accessor for a JSON payload parsed from a text stream (stdout).
+*
+* Lazily parses the JSON on first use; parse errors are deferred until the
+* value is read so that callers can still read the raw stream text without
+* triggering a throw.
+*
+* ANSI escape sequences are stripped by default before `JSON.parse`
+* (CONVENTIONS D6). When a `transform` is configured on the spec runner, it
+* runs on the stripped text — an escape hatch for application noise not
+* covered by the `{{token}}` grammar.
+*
+* Assertions go through `expect()`: `expect(result.json).toMatch('name.json')`
+* (deep-equal against `expected/<name>`, with `{{placeholder}}` support).
 */
-var SpecificationResult = class {
-	commandResult;
-	config;
-	requestInfo;
-	responseData;
+var JsonAccessor = class {
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** @internal */
+	rawText;
+	/** @internal Test-file directory — fixture resolution root for matchers. */
 	testDir;
-	workDir;
-	constructor(options) {
-		this.responseData = options.response;
-		this.commandResult = options.commandResult;
-		this.config = options.config;
-		this.testDir = options.testDir;
-		this.requestInfo = options.requestInfo;
-		this.workDir = options.workDir;
+	/** @internal */
+	transform;
+	constructor(rawText, testDir, transform, captures) {
+		this.rawText = rawText;
+		this.testDir = testDir;
+		this.transform = transform;
+		this.captures = captures ?? new CaptureScope();
 	}
-	/** The process exit code. Only available after a CLI action. */
-	get exitCode() {
-		if (!this.commandResult) throw new Error(".exitCode requires a CLI action (.exec())");
-		return this.commandResult.exitCode;
+	/** The parsed JSON value. Throws if the text is not valid JSON. */
+	get value() {
+		const stripped = stripAnsiCodes(this.rawText);
+		const source = this.transform ? this.transform(stripped) : stripped;
+		try {
+			return JSON.parse(source);
+		} catch {
+			const preview = source.slice(0, 200);
+			throw new Error(`stdout is not valid JSON: ${preview}`);
+		}
 	}
-	/** The HTTP response status code. Only available after an HTTP action. */
-	get status() {
-		if (!this.responseData) throw new Error(".status requires an HTTP action (.get(), .post(), etc.)");
-		return this.responseData.status;
+};
+//#endregion
+//#region src/core/specification/shared/result/response.ts
+/**
+* Read-only accessor for an HTTP response.
+*
+* Assertions go through `expect()`:
+* `expect(result.response).toMatch('created.http')` compares status,
+* a subset of headers, and the JSON body against `expected/<name>` —
+* with `{{placeholder}}` support in all three.
+*/
+var ResponseAccessor = class {
+	/** The parsed JSON response body (null when parsing failed). */
+	body;
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** Response headers as a flat, lower-cased key-value map. */
+	headers;
+	/** The HTTP response status code. */
+	status;
+	/** @internal Test-file directory — fixture resolution root for matchers. */
+	testDir;
+	constructor(response, testDir, captures) {
+		this.body = response.body;
+		this.headers = response.headers;
+		this.status = response.status;
+		this.testDir = testDir;
+		this.captures = captures ?? new CaptureScope();
 	}
-	/** The captured standard output. Only available after a CLI action. */
-	get stdout() {
-		if (!this.commandResult) throw new Error(".stdout requires a CLI action (.exec())");
-		return this.commandResult.stdout;
+};
+//#endregion
+//#region src/core/specification/shared/result/table.ts
+/**
+* Read-only accessor for a database table after a specification run.
+*
+* Assertions go through `expect()` (async — they query the database):
+*
+*     await expect(result.table('users', { database: 'db' })).toMatchRows({
+*         columns: ['name'],
+*         rows: [['Alice']],
+*     });
+*     await expect(result.table('users', { database: 'db' })).toBeEmpty();
+*/
+var TableAccessor = class {
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** @internal */
+	db;
+	/** The table name this accessor reads. */
+	name;
+	constructor(name, db, captures) {
+		this.name = name;
+		this.db = db;
+		this.captures = captures ?? new CaptureScope();
 	}
-	/** The captured standard error. Only available after a CLI action. */
-	get stderr() {
-		if (!this.commandResult) throw new Error(".stderr requires a CLI action (.exec())");
-		return this.commandResult.stderr;
+	/** @internal Query the table — used by the toMatchRows / toBeEmpty matchers. */
+	query(columns) {
+		return this.db.query(this.name, columns);
 	}
-	/**
-	* Extract text blocks from stdout that contain a pattern.
-	* Useful for parsing structured CLI output (linters, compilers).
-	*
-	* @example
-	*   expect(result.grep('error.ts')).toContain('no-unused-vars');
-	*/
-	grep(pattern) {
-		return grep(this.stdout, pattern);
+};
+//#endregion
+//#region src/integrations/docker/docker-lookup.ts
+/**
+* Thin synchronous wrappers around the `docker` CLI used by the docker() spec
+* mode. Sync is deliberate — the calls are fast, run only on the host, and
+* keep the dispose path straightforward (`Symbol.asyncDispose` can still be
+* async without needing these to be).
+*/
+const DEFAULT_TIMEOUT = 1e4;
+/** Return all container IDs (running or stopped) that carry `key=value`. */
+function findContainersByLabel(key, value) {
+	try {
+		return execSync(`docker ps -aq -f label=${key}=${value}`, {
+			encoding: "utf8",
+			timeout: DEFAULT_TIMEOUT
+		}).split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+	} catch {
+		return [];
 	}
-	/** Access the HTTP response body for assertions. Only available after an HTTP action. */
-	get response() {
-		if (!this.responseData) throw new Error(".response requires an HTTP action (.get(), .post(), etc.)");
-		return new ResponseAccessor(this.responseData.body, this.testDir);
+}
+/** Return the raw `docker inspect` payload (object, not array) for a container. */
+function inspectContainer(id) {
+	const raw = execSync(`docker inspect ${id}`, {
+		encoding: "utf8",
+		timeout: DEFAULT_TIMEOUT
+	});
+	const parsed = JSON.parse(raw);
+	return Array.isArray(parsed) ? parsed[0] : parsed;
+}
+/** Force-remove the given container IDs in a single call. Errors are swallowed. */
+function removeContainers(ids) {
+	if (ids.length === 0) return;
+	try {
+		execSync(`docker rm -f ${ids.join(" ")}`, {
+			encoding: "utf8",
+			stdio: "pipe",
+			timeout: DEFAULT_TIMEOUT
+		});
+	} catch {}
+}
+//#endregion
+//#region src/core/specification/shared/result/result.ts
+/**
+* Base result - common accessors available after any action type.
+* Extended by HttpResult, CliResult, and used directly by job results.
+*
+* Every result carries a fresh {@link CaptureScope}: `match.ref()` captures
+* and `{{type#ref}}` placeholders are scoped to one spec execution.
+*/
+var BaseResult = class {
+	/** @internal Ref-capture scope shared by every assertion on this result. */
+	captures;
+	config;
+	testDir;
+	workDir;
+	constructor(options) {
+		this.config = options.config;
+		this.testDir = options.testDir;
+		this.workDir = options.workDir;
+		this.captures = new CaptureScope(options.workDir ? safeRealpath(options.workDir) : void 0);
 	}
 	/** Access a directory (relative to the working directory) for snapshot assertions. */
 	directory(path = ".") {
-		return new DirectoryAccessor(resolve(this.workDir ?? this.testDir, path), this.testDir);
+		return new DirectoryAccessor(resolve(this.workDir ?? this.testDir, path), this.testDir, this.captures);
 	}
 	/** Access a single file (relative to the working directory) for content assertions. */
 	file(path) {
 		const resolvedPath = resolve(this.workDir ?? this.testDir, path);
 		const exists = existsSync(resolvedPath);
+		const { captures, testDir } = this;
 		return {
 			get content() {
 				if (!exists) throw new Error(`File not found: ${path}`);
 				return readFileSync(resolvedPath, "utf8");
 			},
-			exists
+			exists,
+			grep(pattern) {
+				if (!exists) throw new Error(`File not found: ${path}`);
+				return new TextAccessor(readFileSync(resolvedPath, "utf8"), path, testDir, { captures }).grep(pattern);
+			}
 		};
 	}
-	/** Access a database table for row-level assertions. */
+	/** Access a database table for row-level assertions via expect() matchers. */
 	table(tableName, options) {
-		const db = this.resolveDatabase(options?.service);
-		if (!db) throw new Error(options?.service ? `table("${tableName}") requires database "${options.service}" but it was not found` : `table("${tableName}") requires a database adapter`);
-		return new TableAssertion(tableName, db);
+		validateDatabaseOption("table", this.config, options?.database);
+		const db = this.resolveDatabase(options?.database);
+		if (!db) throw new Error(options?.database ? `table("${tableName}") requires database "${options.database}" but it was not found` : `table("${tableName}") requires a database adapter`);
+		return new TableAccessor(tableName, db, this.captures);
 	}
-	resolveDatabase(serviceName) {
-		if (serviceName && this.config.databases) return this.config.databases.get(serviceName);
+	resolveDatabase(databaseKey) {
+		if (databaseKey && this.config.databases) return this.config.databases.get(databaseKey);
 		return this.config.database;
 	}
 };
+function safeRealpath(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
+/**
+* Enforce CONVENTIONS A7: with two or more databases in the services record
+* the `database` option is mandatory on `.seed()` / `.table()`; with exactly
+* one it is forbidden (redundant).
+*
+* @internal
+*/
+function validateDatabaseOption(method, config, database) {
+	const keys = config.databaseKeys;
+	if (!keys) return;
+	if (keys.length >= 2 && !database) throw new Error(`${method}(): ${keys.length} databases are declared (${keys.map((k) => `"${k}"`).join(", ")}) — pass { database: <key> } to target one of them.`);
+	if (keys.length === 1 && database) throw new Error(`${method}(): redundant database option — "${keys[0]}" is the only declared database.`);
+}
 //#endregion
-//#region src/builder/specification-builder.ts
+//#region src/core/specification/cli/result.ts
 /**
-* Fluent builder for declaring a single test specification.
+* Result from a command action (`.exec()`).
 *
-* Chain setup methods ({@link seed}, {@link fixture}, {@link env}), an action
-* ({@link get}, {@link post}, {@link exec}), then call {@link run} to execute
-* and receive a {@link SpecificationResult} for assertions.
+* When the runner was configured with a `docker` option, the result also
+* exposes container accessors and participates in `Symbol.asyncDispose`
+* cleanup. The Docker shell-outs are **lazy**: a test that never calls
+* `.container(...)` never queries the Docker daemon, so command-only tests
+* pay zero Docker cost even when the runner is Docker-aware.
+*
+* Dispose always runs one final label-filtered `docker ps` to catch
+* containers that were spawned during `.exec` but never asserted on —
+* tests still get leak-free cleanup even if they forget to reach into
+* a container.
 */
-var SpecificationBuilder = class {
-	commandArgs = null;
-	commandEnv = {};
-	config;
-	fixtures = [];
-	intercepts = [];
-	jobName = null;
-	label;
-	mocks = [];
-	projectName = null;
-	request = null;
-	requestHeaders = {};
-	seeds = [];
-	spawnConfig = null;
-	testDir;
-	constructor(config, testDir, label) {
-		this.config = config;
-		this.testDir = testDir;
-		this.label = label;
+var CliResult = class extends BaseResult {
+	commandOutput;
+	containersCache = null;
+	dockerConfig;
+	testRunId;
+	transform;
+	constructor(options) {
+		super(options);
+		this.commandOutput = options.commandOutput;
+		this.dockerConfig = options.dockerConfig;
+		this.testRunId = options.testRunId;
+		this.transform = options.transform;
 	}
-	/**
-	* Queue a SQL seed file to run before the action.
-	*
-	* @example
-	*   spec("creates user").seed("users.sql").exec("list-users").run();
-	*/
-	seed(file, options) {
-		this.seeds.push({
-			file,
-			service: options?.service
+	/** The process exit code. */
+	get exitCode() {
+		return this.commandOutput.exitCode;
+	}
+	/** Accessor for the captured standard output with file-based assertions. */
+	get stdout() {
+		return new TextAccessor(this.commandOutput.stdout, "stdout", this.testDir, {
+			captures: this.captures,
+			transform: this.transform
 		});
-		return this;
 	}
-	/** Copy a file or directory from `fixtures/` into the working directory before execution. */
-	fixture(file) {
-		this.fixtures.push({ file });
-		return this;
+	/** Accessor for the captured standard error with file-based assertions. */
+	get stderr() {
+		return new TextAccessor(this.commandOutput.stderr, "stderr", this.testDir, {
+			captures: this.captures,
+			transform: this.transform
+		});
 	}
-	/** Copy an entire project fixture from `fixturesRoot` into the working directory. */
-	project(name) {
-		this.projectName = name;
-		return this;
+	/** Accessor for parsing stdout as JSON and asserting against JSON fixtures. */
+	get json() {
+		return new JsonAccessor(this.commandOutput.stdout, this.testDir, this.transform, this.captures);
 	}
-	/** Register an MSW mock definition file from `mock/` to intercept HTTP calls. */
-	mock(file) {
-		this.mocks.push({ file });
-		return this;
+	/** Accessor for the temporary working directory the command ran in. */
+	get filesystem() {
+		if (!this.workDir) throw new Error("CliResult.filesystem requires a working directory");
+		return new FilesystemAccessor(this.workDir, this.testDir, this.captures);
 	}
 	/**
-	* Set environment variables for the CLI process. Merged on top of process.env.
-	* Use `null` to unset a variable. Multiple calls merge.
-	*
-	* The token `$WORKDIR` (in any value) is replaced with the actual working
-	* directory at run-time — useful for tests that need a fully isolated `HOME`.
+	* Look up a container the command spawned during this run by the value of
+	* its name-label (as declared in the `docker.nameLabel` of the
+	* `specification.cli()` options).
+	* First access triggers a one-shot `docker ps` + `docker inspect`
+	* query and caches the result for the rest of the result's lifetime.
+	* Tests that don't call this never touch Docker.
 	*
-	* @example
-	*   spec("...").env({ HOME: "$WORKDIR", TZ: "UTC" }).exec("status").run();
+	* Returns an accessor with `.exists === false` when no container
+	* carries that name — callers can still assert absence without a try.
 	*/
-	env(env) {
-		this.commandEnv = {
-			...this.commandEnv,
-			...env
-		};
-		return this;
+	container(name) {
+		this.ensureDockerAware("container");
+		this.loadContainers();
+		const captured = this.containersCache.get(name);
+		if (!captured) return new ContainerAccessor(null, null, this.testDir, this.transform);
+		return new ContainerAccessor(captured.id, captured.inspect, this.testDir, this.transform);
+	}
+	/** All captured container IDs. Triggers the same lazy query as `container()`. */
+	get containerIds() {
+		this.ensureDockerAware("containerIds");
+		this.loadContainers();
+		return [...this.containersCache.values()].map((c) => c.id);
+	}
+	async [Symbol.asyncDispose]() {
+		if (!this.dockerConfig || !this.testRunId) return;
+		removeContainers(this.containersCache !== null ? [...this.containersCache.values()].map((c) => c.id) : findContainersByLabel(this.dockerConfig.testRunLabel, this.testRunId));
+	}
+	ensureDockerAware(member) {
+		if (!this.dockerConfig || !this.testRunId) throw new Error(`CliResult.${member}: runner was not configured with a docker option. Pass \`docker: { envVar, nameLabel, testRunLabel }\` in the specification.cli() options.`);
+	}
+	loadContainers() {
+		if (this.containersCache !== null) return;
+		const ids = findContainersByLabel(this.dockerConfig.testRunLabel, this.testRunId);
+		const map = /* @__PURE__ */ new Map();
+		for (const id of ids) {
+			let inspect;
+			try {
+				inspect = inspectContainer(id);
+			} catch {
+				continue;
+			}
+			const nameValue = (inspect?.Config?.Labels ?? inspect?.config?.labels ?? {})[this.dockerConfig.nameLabel];
+			const key = typeof nameValue === "string" && nameValue.length > 0 ? nameValue : id;
+			map.set(key, {
+				id,
+				inspect
+			});
+		}
+		this.containersCache = map;
 	}
+};
+//#endregion
+//#region src/integrations/docker/container-accessor.ts
+const EXEC_TIMEOUT = 1e4;
+function readInspectState(inspect) {
+	const state = inspect?.State ?? inspect?.state;
+	if (!state) return {
+		running: false,
+		status: "unknown"
+	};
+	return {
+		running: Boolean(state.Running ?? state.running ?? false),
+		status: String(state.Status ?? state.status ?? "unknown")
+	};
+}
+/**
+* Assertion accessor for a single Docker container captured by the docker()
+* spec mode. Mirrors the shape of {@link CliResult} so tests use the same
+* vocabulary (`stdout.toContain`, `file(...).content`, etc.) regardless
+* of where output came from.
+*
+* Sync state (`exists`, `running`, `status`) is derived from the `docker
+* inspect` payload captured at result-construction time. Logs are fetched
+* lazily on first access to `stdout`/`stderr`.
+*/
+var ContainerAccessor = class {
+	cachedLogs = null;
+	containerId;
+	exists;
+	inspectData;
+	running;
+	status;
+	testDir;
+	transform;
 	/**
-	* Set HTTP headers for the request. Multiple calls merge.
-	*
-	* @example
-	*   spec("french").headers({ 'Accept-Language': 'fr' }).get("/articles").run();
+	* Underlying Docker container ID, or `null` if no container was captured
+	* for this name. Useful when a follow-up CLI command needs to reference
+	* the container by id (e.g. `spwn world inspect <id>`). Prefer the other
+	* accessors for common reads — pulling the raw id is the escape hatch.
 	*/
-	headers(headers) {
-		this.requestHeaders = {
-			...this.requestHeaders,
-			...headers
-		};
-		return this;
+	get id() {
+		return this.containerId;
 	}
-	/**
-	* Intercept an outgoing HTTP request and return a controlled response.
-	* Uses MSW under the hood. Intercepts are queued — multiple calls with the
-	* same trigger fire sequentially (first match consumed first).
-	*
-	* @param trigger - What to match (use openai.agent(), http.get(), etc.)
-	* @param response - What to return: an InterceptResponse object, or a filename
-	*   from `intercepts/` (JSON loaded and auto-wrapped by the trigger).
-	*
-	* @example
-	*   // With inline response
-	*   .intercept(openai.agent({...}), openai.reply({ categories: ['TECH'] }))
-	*
-	*   // With JSON fixture file (loaded from intercepts/ directory)
-	*   .intercept(openai.agent({...}), 'ingest-tech.json')
-	*   .intercept(http.get(url), 'world-news-tech.json')
-	*/
-	intercept(trigger, response) {
-		if (typeof response === "string") {
-			const slashIndex = response.indexOf("/");
-			if (slashIndex === -1) throw new Error(`.intercept(): file path must be 'adapter/filename.json' (e.g. 'openai/ingest-tech.json'), got '${response}'`);
-			const adapterName = response.slice(0, slashIndex);
-			if (adapterName !== trigger.adapter) throw new Error(`.intercept(): adapter mismatch - trigger uses '${trigger.adapter}' but file path starts with '${adapterName}/'`);
-			const filePath = resolve(this.testDir, "intercepts", response);
-			const data = JSON.parse(readFileSync(filePath, "utf8"));
-			const resolved = trigger.wrap(data);
-			this.intercepts.push({
-				trigger,
-				response: resolved
-			});
-		} else this.intercepts.push({
-			trigger,
-			response
-		});
-		return this;
+	constructor(containerId, inspectData, testDir, transform) {
+		this.containerId = containerId;
+		this.inspectData = inspectData;
+		this.testDir = testDir;
+		this.transform = transform;
+		this.exists = containerId !== null;
+		if (this.exists) {
+			const state = readInspectState(inspectData);
+			this.running = state.running;
+			this.status = state.status;
+		} else {
+			this.running = false;
+			this.status = "absent";
+		}
 	}
 	/**
-	* Send a GET request to the server adapter.
-	*
-	* @example
-	*   spec("list items").get("/api/items").run();
+	* Raw `docker inspect` object for this container. Throws if the container
+	* was not captured (i.e. `.exists === false`).
 	*/
-	get(path) {
-		this.request = {
-			method: "GET",
-			path
-		};
-		return this;
+	get inspect() {
+		this.requireExists("inspect");
+		return new JsonAccessor(JSON.stringify(this.inspectData), this.testDir, this.transform);
+	}
+	/** Captured logs (stdout+stderr combined for v1). */
+	get stdout() {
+		this.requireExists("stdout");
+		return new TextAccessor(this.loadLogs(), "stdout", this.testDir, { transform: this.transform });
+	}
+	/** Captured logs (stdout+stderr combined for v1). */
+	get stderr() {
+		this.requireExists("stderr");
+		return new TextAccessor(this.loadLogs(), "stderr", this.testDir, { transform: this.transform });
 	}
 	/**
-	* Send a POST request to the server adapter.
-	*
-	* @param bodyFile - Optional JSON file from `requests/` to use as the request body.
-	* @example
-	*   spec("create item").post("/api/items", "new-item.json").run();
+	* Read a file from inside the container via `docker exec cat`. The
+	* returned object satisfies the same {@link FileAccessor} shape used by
+	* the host filesystem accessor, so tests do not need to learn a new API.
 	*/
-	post(path, bodyFile) {
-		this.request = {
-			bodyFile,
-			method: "POST",
-			path
-		};
-		return this;
-	}
-	/** Send a PUT request to the server adapter. */
-	put(path, bodyFile) {
-		this.request = {
-			bodyFile,
-			method: "PUT",
+	file(path) {
+		this.requireExists("file");
+		const id = this.containerId;
+		const exists = this.containerExec(id, [
+			"test",
+			"-e",
 			path
+		]).exitCode === 0;
+		const { testDir } = this;
+		const readContent = () => {
+			if (!exists) throw new Error(`File not found in container: ${path}`);
+			return execSync(`docker exec ${id} cat ${JSON.stringify(path)}`, {
+				encoding: "utf8",
+				timeout: EXEC_TIMEOUT
+			});
 		};
-		return this;
-	}
-	/** Send a DELETE request to the server adapter. */
-	delete(path) {
-		this.request = {
-			method: "DELETE",
-			path
+		return {
+			get content() {
+				return readContent();
+			},
+			exists,
+			grep(pattern) {
+				return new TextAccessor(readContent(), path, testDir).grep(pattern);
+			}
 		};
-		return this;
 	}
 	/**
-	* Execute a CLI command (or a sequence of commands) in an isolated working directory.
-	* When an array is passed, commands run sequentially and stop on the first non-zero exit code.
-	*
-	* @example
-	*   spec("init project").exec("init --name demo").run();
-	*   spec("multi-step").exec(["init", "build"]).run();
+	* Run a shell command inside the container and get back the same
+	* {@link CliResult} used for host-side executions.
 	*/
-	exec(args) {
-		this.commandArgs = args;
-		return this;
-	}
-	/** Spawn a long-running CLI process with custom spawn options (e.g. timeout, signal). */
-	spawn(args, options) {
-		this.spawnConfig = {
-			args,
-			options
-		};
-		return this;
+	async exec(cmd) {
+		this.requireExists("exec");
+		return new CliResult({
+			commandOutput: this.containerExec(this.containerId, [
+				"sh",
+				"-c",
+				cmd
+			]),
+			config: {},
+			testDir: this.testDir,
+			transform: this.transform,
+			workDir: this.testDir
+		});
 	}
-	/**
-	* Execute a named job registered via the app() factory.
-	*
-	* @param name - The job name to trigger (must match a registered JobHandle.name).
-	*
-	* @example
-	*   spec('pipeline').intercept(openai.chat(), openai.response({...})).job('report-refresh').run();
-	*/
-	job(name) {
-		this.jobName = name;
-		return this;
+	requireExists(member) {
+		if (!this.exists) throw new Error(`ContainerAccessor.${member}: container does not exist (check .exists first)`);
 	}
-	/**
-	* Execute the specification: run seeds, copy fixtures, then perform the
-	* configured action (HTTP or CLI).
-	*
-	* @returns The result object used for assertions.
-	* @example
-	*   const result = await spec("test").exec("status").run();
-	*   expect(result.exitCode).toBe(0);
-	*/
-	async run() {
-		const hasHttpAction = this.request !== null;
-		const hasCliAction = this.commandArgs !== null || this.spawnConfig !== null;
-		const hasJobAction = this.jobName !== null;
-		const actionCount = [
-			hasHttpAction,
-			hasCliAction,
-			hasJobAction
-		].filter(Boolean).length;
-		if (actionCount === 0) throw new Error(`Specification "${this.label}": no action defined. Call .get(), .post(), .exec(), .job(), etc. before .run()`);
-		if (actionCount > 1) throw new Error(`Specification "${this.label}": cannot mix action types (.get/.post, .exec/.spawn, .job)`);
-		let workDir = null;
-		if (hasCliAction) workDir = this.prepareWorkDir();
-		if (this.config.databases) for (const db of this.config.databases.values()) await db.reset();
-		else if (this.config.database) await this.config.database.reset();
-		for (const entry of this.seeds) {
-			let db;
-			if (entry.service && this.config.databases) {
-				db = this.config.databases.get(entry.service);
-				if (!db) throw new Error(`seed() targets database "${entry.service}" but it was not found. Available: ${[...this.config.databases.keys()].join(", ")}`);
-			} else db = this.config.database;
-			if (!db) throw new Error("seed() requires a database adapter");
-			const sql = readFileSync(resolve(this.testDir, "seeds", entry.file), "utf8");
-			await db.seed(sql);
-		}
-		if (this.fixtures.length > 0 && workDir) for (const entry of this.fixtures) cpSync(resolve(this.testDir, "fixtures", entry.file), resolve(workDir, entry.file), { recursive: true });
-		let cleanupIntercepts = null;
-		if (this.intercepts.length > 0) {
-			const { registerIntercepts } = await import("./intercept2.js");
-			cleanupIntercepts = await registerIntercepts(this.intercepts);
-		}
+	loadLogs() {
+		if (this.cachedLogs !== null) return this.cachedLogs;
 		try {
-			if (hasHttpAction) return await this.runHttpAction();
-			if (hasJobAction) return await this.runJobAction();
-			return await this.runCliAction(workDir);
-		} finally {
-			if (cleanupIntercepts) cleanupIntercepts();
-		}
-	}
-	resolveEnv(workDir) {
-		const keys = Object.keys(this.commandEnv);
-		if (keys.length === 0) return;
-		const resolved = {};
-		for (const key of keys) {
-			const value = this.commandEnv[key];
-			resolved[key] = typeof value === "string" ? value.replace(/\$WORKDIR/g, workDir) : value;
-		}
-		return resolved;
-	}
-	prepareWorkDir() {
-		const tempDir = mkdtempSync(resolve(tmpdir(), "spec-cli-"));
-		if (this.projectName && this.config.fixturesRoot) {
-			const projectDir = resolve(this.config.fixturesRoot, this.projectName);
-			if (!existsSync(projectDir)) throw new Error(`project("${this.projectName}"): fixture project not found at ${projectDir}`);
-			cpSync(projectDir, tempDir, { recursive: true });
-		}
-		return tempDir;
-	}
-	async runHttpAction() {
-		if (!this.config.server) throw new Error("HTTP actions require a server adapter (use integration() or e2e())");
-		let body;
-		if (this.request.bodyFile) body = JSON.parse(readFileSync(resolve(this.testDir, "requests", this.request.bodyFile), "utf8"));
-		const headers = Object.keys(this.requestHeaders).length > 0 ? this.requestHeaders : void 0;
-		const response = await this.config.server.request(this.request.method, this.request.path, body, headers);
-		return new SpecificationResult({
-			config: this.config,
-			requestInfo: {
-				body,
-				method: this.request.method,
-				path: this.request.path
-			},
-			response,
-			testDir: this.testDir
-		});
-	}
-	async runJobAction() {
-		if (!this.config.jobs?.length) throw new Error("Job actions require jobs registered via app(() => ({ server, jobs }))");
-		const job = this.config.jobs.find((j) => j.name === this.jobName);
-		if (!job) {
-			const available = this.config.jobs.map((j) => j.name).join(", ");
-			throw new Error(`job("${this.jobName}"): not found. Available: ${available}`);
+			const out = execSync(`docker logs ${this.containerId}`, {
+				encoding: "utf8",
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				],
+				timeout: EXEC_TIMEOUT
+			});
+			this.cachedLogs = out;
+		} catch (error) {
+			this.cachedLogs = typeof error?.stdout === "string" ? error.stdout : String(error?.stderr ?? "");
 		}
-		await job.execute();
-		return new SpecificationResult({
-			config: this.config,
-			testDir: this.testDir
-		});
+		return this.cachedLogs ?? "";
 	}
-	async runCliAction(workDir) {
-		if (!this.config.command) throw new Error("CLI actions require a command adapter (use cli())");
-		const env = this.resolveEnv(workDir);
-		let commandResult;
-		if (this.spawnConfig) commandResult = await this.config.command.spawn(this.spawnConfig.args, workDir, this.spawnConfig.options, env);
-		else if (Array.isArray(this.commandArgs)) {
-			commandResult = {
+	containerExec(id, argv) {
+		try {
+			return {
 				exitCode: 0,
 				stderr: "",
-				stdout: ""
+				stdout: execSync(`docker exec ${id} ${argv.map((a) => JSON.stringify(a)).join(" ")}`, {
+					encoding: "utf8",
+					stdio: [
+						"ignore",
+						"pipe",
+						"pipe"
+					],
+					timeout: EXEC_TIMEOUT
+				})
 			};
-			for (const args of this.commandArgs) {
-				commandResult = await this.config.command.exec(args, workDir, env);
-				if (commandResult.exitCode !== 0) break;
-			}
-		} else commandResult = await this.config.command.exec(this.commandArgs, workDir, env);
-		return new SpecificationResult({
-			commandResult,
-			config: this.config,
-			testDir: this.testDir,
-			workDir
-		});
+		} catch (error) {
+			return {
+				exitCode: typeof error?.status === "number" ? error.status : 1,
+				stderr: typeof error?.stderr === "string" ? error.stderr : String(error?.message ?? ""),
+				stdout: typeof error?.stdout === "string" ? error.stdout : ""
+			};
+		}
 	}
 };
-function getCallerDir() {
-	const stack = (/* @__PURE__ */ new Error("caller detection")).stack;
-	if (!stack) throw new Error("Cannot detect caller directory: no stack trace");
-	const lines = stack.split("\n");
-	for (const line of lines) {
-		const match = line.match(/at\s+(?:.*?\()?(?:file:\/\/)?([^:)]+):\d+:\d+/);
-		if (!match) continue;
-		const filePath = match[1];
-		if (filePath.includes("node_modules")) continue;
-		if (filePath.includes("/src/builder/") || filePath.includes("/src/spec/")) continue;
-		return resolve(filePath, "..");
-	}
-	throw new Error("Cannot detect caller directory from stack trace");
+//#endregion
+//#region src/vitest/update.ts
+/**
+* Snapshot update-mode detection. `TEST_UPDATE=1` (framework convention, see
+* CONVENTIONS E1) or vitest's `-u` / `--update` flag turn fixture mismatches
+* into fixture rewrites.
+*/
+function shouldUpdateSnapshots() {
+	if (process.env.TEST_UPDATE === "1") return true;
+	return process.argv.includes("-u") || process.argv.includes("--update");
 }
+/** Standard hint appended to missing-fixture errors. */
+const UPDATE_HINT = "Run with TEST_UPDATE=1 (or vitest -u) to create it.";
+//#endregion
+//#region src/vitest/matchers.ts
 /**
-* Create a {@link SpecificationRunner} bound to the given adapter configuration.
-* The test file directory is auto-detected from the call stack.
+* Vitest custom matchers for `@jterrazz/test` accessors.
+*
+* Auto-registered (idempotently) on the first `specification.api()` /
+* `specification.jobs()` / `specification.cli()` call via a dynamic
+* `import('vitest')` — the library never hard-imports vitest at module load.
+*
+* All assertions go through `expect()` (CONVENTIONS D1). Only matchers that
+* do IO are async (D2): `table` (SQL query), `filesystem`/`directory`
+* (disk walk), `container` (docker). Everything else is synchronous.
 */
-function createSpecificationRunner(config) {
-	return (label) => {
-		return new SpecificationBuilder(config, getCallerDir(), label);
+const PASS = (label) => ({
+	message: () => label,
+	pass: true
+});
+const FAIL = (message) => ({
+	message: () => message,
+	pass: false
+});
+function requireExtension(name, subject) {
+	if (!/\.[A-Za-z0-9]+$/.test(name)) throw new Error(`toMatch("${name}"): the extension is part of the name and is required for ${subject} subjects (e.g. "help.txt").`);
+}
+function formatJson(value) {
+	return `${JSON.stringify(value, null, 4)}\n`;
+}
+function matchStreamFile(accessor, name, frozen) {
+	requireExtension(name, "stream");
+	const filePath = resolve(accessor.testDir, "expected", name);
+	const actual = accessor.comparableText;
+	if (shouldUpdateSnapshots() && !frozen) {
+		const merged = mergeTextPreservingPlaceholders(existsSync(filePath) ? readFileSync(filePath, "utf8") : null, actual, accessor.captures);
+		mkdirSync(dirname(filePath), { recursive: true });
+		writeFileSync(filePath, merged);
+		return PASS(`updated expected/${name}`);
+	}
+	if (!existsSync(filePath)) return FAIL(`${accessor.streamName} fixture "${name}" does not exist at ${filePath}.\n${UPDATE_HINT}`);
+	const expected = readFileSync(filePath, "utf8");
+	if (textEquals(expected, actual, accessor.captures)) return PASS(`expected ${accessor.streamName} not to match expected/${name}`);
+	return FAIL(formatStdoutDiff(name, expected, actual));
+}
+function matchJsonFile(accessor, name, frozen) {
+	requireExtension(name, "json");
+	const filePath = resolve(accessor.testDir, "expected", name);
+	const actual = accessor.value;
+	if (shouldUpdateSnapshots() && !frozen) {
+		const merged = existsSync(filePath) ? mergePreservingPlaceholders(JSON.parse(readFileSync(filePath, "utf8")), actual, accessor.captures.workdir) : mergePreservingPlaceholders(null, actual, accessor.captures.workdir);
+		mkdirSync(dirname(filePath), { recursive: true });
+		writeFileSync(filePath, formatJson(merged));
+		return PASS(`updated expected/${name}`);
+	}
+	if (!existsSync(filePath)) return FAIL(`JSON fixture "${name}" does not exist at ${filePath}.\n${UPDATE_HINT}`);
+	const expected = JSON.parse(readFileSync(filePath, "utf8"));
+	if (structuralEquals(expected, actual, accessor.captures)) return PASS(`expected JSON not to match expected/${name}`);
+	return FAIL(formatResponseDiff(name, renderExpected(expected), actual));
+}
+/**
+* Build the updated `expected/*.http` fixture content from the previous
+* fixture and the actual response (CONVENTIONS D5). Headers are the
+* INTERSECTION with the actual response: placeholders still matching are
+* preserved, stale values are replaced, headers absent from the actual
+* response are dropped — so a freshly updated fixture passes the next run.
+*
+* @internal Exported for unit tests.
+*/
+function buildUpdatedResponse(previous, actual, workdir) {
+	const scope = new CaptureScope();
+	const status = previous && structuralEquals(previous.status, String(actual.status), scope) ? previous.status : String(actual.status);
+	const headers = {};
+	if (previous) for (const [key, value] of Object.entries(previous.headers)) {
+		const actualValue = actual.headers[key.toLowerCase()];
+		if (actualValue === void 0) continue;
+		headers[key] = structuralEquals(value, actualValue, scope) ? value : actualValue;
+	}
+	else if (actual.headers["content-type"]) headers["content-type"] = actual.headers["content-type"];
+	const hasBody = actual.body !== null && actual.body !== void 0;
+	return {
+		body: previous?.hasBody && hasBody ? mergePreservingPlaceholders(previous.body, actual.body, workdir) : mergePreservingPlaceholders(null, actual.body, workdir),
+		hasBody,
+		headers,
+		status
 	};
 }
-//#endregion
-//#region src/docker/docker-adapter.ts
 /**
-* Implements {@link DockerContainerPort} by shelling out to the Docker CLI.
-* Each instance is bound to a single container ID.
+* Compare a parsed `expected/*.http` fixture against an actual response.
+* Returns the failure message, or null when everything matches.
+*
+* @internal Exported for unit tests.
 */
-var DockerAdapter = class {
-	containerId;
-	constructor(containerId) {
-		this.containerId = containerId;
+function compareResponse(name, expected, actual, scope) {
+	if (!(/^\d+$/.test(expected.status) ? Number(expected.status) === actual.status : structuralEquals(expected.status, String(actual.status), scope))) return `Response status mismatch (${name})\n  expected: ${expected.status}\n  received: ${actual.status}`;
+	for (const [key, value] of Object.entries(expected.headers)) {
+		const actualValue = actual.headers[key.toLowerCase()];
+		if (actualValue === void 0 || !structuralEquals(value, actualValue, scope)) return `Response header mismatch (${name})\n  header: ${key}\n  expected: ${value}\n  received: ${actualValue ?? "(absent)"}`;
 	}
-	async exec(cmd) {
-		return execSync(`docker exec ${this.containerId} ${cmd.map((c) => `'${c}'`).join(" ")}`, {
-			encoding: "utf8",
-			timeout: 1e4
-		}).trim();
-	}
-	async file(path) {
-		try {
-			return {
-				exists: true,
-				content: await this.exec(["cat", path])
-			};
-		} catch {
-			return {
-				exists: false,
-				content: ""
-			};
+	if (expected.hasBody && !structuralEquals(expected.body, actual.body, scope)) return formatResponseDiff(name, renderExpected(expected.body), actual.body);
+	return null;
+}
+function matchResponseFile(accessor, name, frozen) {
+	requireExtension(name, "response");
+	const filePath = resolve(accessor.testDir, "expected", name);
+	if (shouldUpdateSnapshots() && !frozen) {
+		const updated = buildUpdatedResponse(existsSync(filePath) ? parseResponseFile(readFileSync(filePath, "utf8"), `expected/${name}`) : null, accessor, accessor.captures.workdir);
+		mkdirSync(dirname(filePath), { recursive: true });
+		writeFileSync(filePath, serializeResponseFile(updated));
+		return PASS(`updated expected/${name}`);
+	}
+	if (!existsSync(filePath)) return FAIL(`Response fixture "${name}" does not exist at ${filePath}.\n${UPDATE_HINT}`);
+	const failure = compareResponse(name, parseResponseFile(readFileSync(filePath, "utf8"), `expected/${name}`), accessor, accessor.captures);
+	return failure === null ? PASS(`expected response not to match expected/${name}`) : FAIL(failure);
+}
+async function matchTreeFile(actualRoot, testDir, name, scope, frozen) {
+	const fixtureDir = resolve(testDir, "expected", name);
+	if (shouldUpdateSnapshots() && !frozen) {
+		const previousContents = /* @__PURE__ */ new Map();
+		if (existsSync(fixtureDir)) for (const file of await walkDirectory(fixtureDir)) previousContents.set(file, readFileSync(resolve(fixtureDir, file), "utf8"));
+		rmSync(fixtureDir, {
+			force: true,
+			recursive: true
+		});
+		mkdirSync(fixtureDir, { recursive: true });
+		cpSync(actualRoot, fixtureDir, { recursive: true });
+		for (const file of await walkDirectory(fixtureDir)) {
+			const previous = previousContents.get(file) ?? null;
+			const actual = readFileSync(resolve(fixtureDir, file), "utf8");
+			const merged = mergeTextPreservingPlaceholders(previous, actual, scope);
+			if (merged !== actual) writeFileSync(resolve(fixtureDir, file), merged);
 		}
+		return PASS(`updated expected/${name}/`);
 	}
-	async isRunning() {
-		try {
-			return execSync(`docker inspect --format='{{.State.Running}}' ${this.containerId}`, {
-				encoding: "utf8",
-				timeout: 5e3
-			}).trim() === "true";
-		} catch {
-			return false;
-		}
+	if (!existsSync(fixtureDir)) return FAIL(`Directory fixture "${name}" does not exist at ${fixtureDir}.\n${UPDATE_HINT}`);
+	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 expected/${name}/`);
+	return FAIL(formatDirectoryDiff(name, diff, "Run with TEST_UPDATE=1 to update the fixture."));
+}
+/**
+* Guard the accessor `toMatch` subjects: their argument is a fixture NAME, never
+* a regex or other value. A `RegExp` (the natural instinct, since vitest-native
+* `toMatch` takes one) must fail loudly with the escape hatch, not silently trip
+* the extension check or be coerced to `"/re/"`.
+*/
+function requireFixtureName(name, subjectKind) {
+	if (typeof name !== "string") {
+		const got = name instanceof RegExp ? "a regular expression" : `a ${typeof name}`;
+		throw new TypeError(`toMatch on accessors takes a fixture name (extension included) — the ${subjectKind} subject received ${got}. For a regex, assert on the raw text instead: use expect(x.text).toMatch(/re/) for regex matching.`);
 	}
-	async logs(tail) {
-		return execSync(`docker logs ${tail ? `--tail ${tail}` : ""} ${this.containerId}`, {
-			encoding: "utf8",
-			timeout: 1e4
-		});
+}
+function toMatch(received, expected, options) {
+	const frozen = options?.frozen === true;
+	if (received instanceof TextAccessor) {
+		requireFixtureName(expected, "stream");
+		return matchStreamFile(received, expected, frozen);
+	}
+	if (received instanceof JsonAccessor) {
+		requireFixtureName(expected, "json");
+		return matchJsonFile(received, expected, frozen);
+	}
+	if (received instanceof ResponseAccessor) {
+		requireFixtureName(expected, "response");
+		return matchResponseFile(received, expected, frozen);
+	}
+	if (received instanceof FilesystemAccessor) {
+		requireFixtureName(expected, "filesystem");
+		return matchTreeFile(received.cwd, received.testDir, expected, received.captures, frozen);
+	}
+	if (received instanceof DirectoryAccessor) {
+		requireFixtureName(expected, "directory");
+		return matchTreeFile(received.root, received.testDir, expected, received.captures, frozen);
+	}
+	if (typeof received === "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
+		};
 	}
-	async inspect() {
-		const raw = execSync(`docker inspect ${this.containerId}`, {
-			encoding: "utf8",
-			timeout: 5e3
-		});
-		const data = JSON.parse(raw)[0];
+	throw new TypeError("toMatch: unsupported subject — expected a stream, json, response, filesystem, or directory accessor, or a string.");
+}
+function toContain(received, expected) {
+	if (received instanceof TextAccessor) {
+		const actual = received.comparableText;
+		const text = String(expected);
+		const pass = actual.includes(text);
 		return {
-			id: data.Id,
-			name: data.Name,
-			state: {
-				running: data.State.Running,
-				exitCode: data.State.ExitCode,
-				status: data.State.Status
-			},
-			config: {
-				image: data.Config.Image,
-				env: data.Config.Env || []
-			},
-			hostConfig: {
-				memory: data.HostConfig.Memory || 0,
-				cpuQuota: data.HostConfig.CpuQuota || 0,
-				networkMode: data.HostConfig.NetworkMode || "",
-				mounts: (data.Mounts || []).map((m) => ({
-					source: m.Source,
-					destination: m.Destination,
-					type: m.Type
-				}))
-			},
-			networkSettings: { networks: Object.fromEntries(Object.entries(data.NetworkSettings.Networks || {}).map(([name, net]) => [name, {
-				gateway: net.Gateway,
-				ipAddress: net.IPAddress
-			}])) }
+			message: () => pass ? `expected ${received.streamName} not to contain ${JSON.stringify(text)}` : `${received.streamName} does not contain expected substring.\n  expected to contain: ${JSON.stringify(text)}\n  actual: ${JSON.stringify(actual.length > 500 ? `${actual.slice(0, 500)}…` : actual)}`,
+			pass
 		};
 	}
-	async exists(path) {
-		try {
-			await this.exec([
-				"test",
-				"-e",
-				path
-			]);
-			return true;
-		} catch {
-			return false;
-		}
+	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 (received != null && typeof received[Symbol.iterator] === "function") {
+		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.`);
+}
+async function toMatchRows(received, expected) {
+	if (!(received instanceof TableAccessor)) throw new TypeError("toMatchRows: unsupported subject — expected result.table(...).");
+	const actual = await received.query(expected.columns);
+	const pass = actual.length === expected.rows.length && expected.rows.every((row, i) => row.length === actual[i].length && row.every((cell, j) => structuralEquals(cell, actual[i][j], received.captures)));
+	return {
+		message: () => pass ? `expected table "${received.name}" not to match the given rows` : formatTableDiff(received.name, expected.columns, expected.rows.map((row) => row.map((cell) => renderExpected(cell))), actual),
+		pass
+	};
+}
+async function toBeEmpty(received) {
+	if (!(received instanceof TableAccessor)) throw new TypeError("toBeEmpty: unsupported subject — expected result.table(...).");
+	const rows = await received.query(["*"]);
+	const pass = rows.length === 0;
+	return {
+		message: () => pass ? `expected table "${received.name}" not to be empty` : `Expected table "${received.name}" to be empty, but it has ${rows.length} row${rows.length === 1 ? "" : "s"}`,
+		pass
+	};
+}
+async function toBeRunning(received) {
+	if (!(received instanceof ContainerAccessor)) throw new TypeError("toBeRunning: unsupported subject — expected a container accessor (result.container(...) or spec.docker(...)).");
+	const pass = received.running;
+	return {
+		message: () => {
+			if (pass) return "expected container not to be running";
+			if (received.exists) return `Expected container to be running, but its status is "${received.status}"`;
+			return "Expected container to be running, but it does not exist";
+		},
+		pass
+	};
+}
+const REGISTERED = Symbol.for("@jterrazz/test:matchers-registered");
+/**
+* Register the custom matchers with vitest's `expect`. Idempotent — safe to
+* call from every `specification.*` constructor. A missing vitest peer is
+* tolerated (the library can be imported outside a vitest run).
+*/
+async function registerMatchers() {
+	const globals = globalThis;
+	if (globals[REGISTERED]) return;
+	globals[REGISTERED] = true;
+	try {
+		const { expect } = await import("vitest");
+		expect.extend({
+			toBeEmpty,
+			toBeRunning,
+			toContain,
+			toMatch,
+			toMatchRows
+		});
+	} catch {
+		globals[REGISTERED] = false;
+	}
+}
+//#endregion
+//#region src/core/specification/api/result.ts
+/** Result from an HTTP action (.request(), .get(), .post(), .put(), .delete()). */
+var HttpResult = class extends BaseResult {
+	responseData;
+	constructor(options) {
+		super(options);
+		this.responseData = options.response;
+	}
+	/** Access the HTTP response (status, headers, body) for assertions. */
+	get response() {
+		return new ResponseAccessor(this.responseData, this.testDir, this.captures);
+	}
+	/** The HTTP response status code. */
+	get status() {
+		return this.responseData.status;
 	}
 };
-/** Create a {@link DockerContainerPort} bound to an existing container by ID. */
-function dockerContainer(containerId) {
-	return new DockerAdapter(containerId);
+//#endregion
+//#region src/core/specification/shared/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.replace(/(?<lower>[a-z0-9])(?<upper>[A-Z])/g, "$<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.replace(/(?<lower>[a-z0-9])(?<upper>[A-Z])/g, "$<lower>_$<upper>").replace(/[^A-Za-z0-9]/g, "_").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/docker/docker-assertion.ts
+//#region src/core/specification/shared/fixtures.ts
 /**
-* Fluent assertion builder for Docker containers.
-* Chain async assertions like `toBeRunning()`, `toHaveFile()`, `toHaveMount()`.
+* Fixture path resolution + copy semantics for the `cli` facet's `.fixture()`.
+*
+* A fixture path is one of two shapes:
+*
+*  - `$FIXTURES/<rest>` — the shared pool at `<specs-root>/fixtures/<rest>`,
+*    where `<specs-root>` is the nearest ancestor directory named `specs`.
+*  - `<path>` (no marker) — feature-local, at `<test-dir>/fixtures/<path>`.
+*
+* Any other `$`-prefixed marker is a usage error (listed against the known
+* markers). Copy semantics mirror rsync's trailing-slash rule (see
+* {@link copyPlan}).
+*/
+/**
+* Markers understood in a `.fixture()` path. Extend here + in
+* {@link resolveFixtureSource}. Exported so the lint layer (rule
+* `jterrazz/b2-known-fixture-marker`) validates literals against the same list.
+*/
+const KNOWN_FIXTURE_MARKERS = ["$FIXTURES"];
+/**
+* Walk up from `startDir` to the nearest ancestor directory named `specs`.
+* Throws with guidance if none is found up to the filesystem root — the
+* `$FIXTURES` marker is meaningless without a specs root.
 */
-var DockerAssertion = class {
-	container;
-	constructor(container) {
-		this.container = container;
+function discoverSpecsRoot(startDir) {
+	let dir = startDir;
+	for (;;) {
+		if (basename(dir) === "specs") return dir;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	throw new Error(`.fixture(): the $FIXTURES marker resolves to <specs-root>/fixtures, but no directory named "specs" was found walking up from ${startDir}. Move the specification under a specs/ directory, or use a feature-local fixtures/ path (no $FIXTURES marker).`);
+}
+/**
+* Resolve the absolute source path of a fixture, applying marker resolution.
+* The trailing slash (spread semantics) is preserved by callers via
+* {@link copyPlan} — it is irrelevant to source resolution.
+*/
+function resolveFixtureSource(path, testDir) {
+	const clean = path.replace(/\/+$/, "");
+	if (clean === "$FIXTURES" || path.startsWith("$FIXTURES/")) {
+		const rest = clean.slice(9).replace(/^\/+/, "");
+		return resolve(discoverSpecsRoot(testDir), "fixtures", rest);
 	}
-	/** Assert the container is running */
-	async toBeRunning() {
-		if (!await this.container.isRunning()) throw new Error("Expected container to be running");
-		return this;
+	if (path.startsWith("$")) {
+		const marker = clean.split("/")[0];
+		throw new Error(`.fixture("${path}"): unknown marker "${marker}". Known markers: ${KNOWN_FIXTURE_MARKERS.join(", ")}. A path without a marker is feature-local (resolved under <test-dir>/fixtures/).`);
 	}
-	/** Assert the container is NOT running / doesn't exist */
-	async toNotExist() {
-		if (await this.container.isRunning()) throw new Error("Expected container to not exist or not be running");
+	return resolve(testDir, "fixtures", clean);
+}
+/**
+* Compute the source + destination for copying a fixture into the working
+* directory. Copy semantics follow rsync's trailing-slash rule:
+*
+*  - `dir/` (trailing slash) — the CONTENTS are spread into the cwd.
+*  - `dir`  (no slash, a directory) — the directory is copied as `<cwd>/<basename>`.
+*  - `file` — copied as `<cwd>/<basename>`.
+*
+* Chained `.fixture()` calls layer in order: a later fixture overwrites files
+* written by an earlier one.
+*/
+function copyPlan(path, testDir, workDir) {
+	const src = resolveFixtureSource(path, testDir);
+	return {
+		dest: /\/+$/.test(path) ? workDir : resolve(workDir, basename(src)),
+		src
+	};
+}
+//#endregion
+//#region src/core/specification/shared/builder.ts
+/**
+* Fluent builder for declaring a single test specification.
+*
+* Chain setup methods ({@link seed}, {@link fixture}, {@link env}), then call
+* an action ({@link get}, {@link post}, {@link exec}, {@link trigger}) —
+* actions are terminal: they execute the specification and resolve to a
+* typed result.
+*
+* Facets expose this class through the narrower {@link ApiSpecification} /
+* {@link JobsSpecification} / {@link CliSpecification} views so each facet
+* only surfaces the methods that make sense for it.
+*/
+var SpecificationBuilder = class {
+	commandEnv = {};
+	config;
+	fixtures = [];
+	intercepts = [];
+	requestHeaders = {};
+	seeds = [];
+	testDir;
+	constructor(config, testDir) {
+		this.config = config;
+		this.testDir = testDir;
+	}
+	/**
+	* Queue a SQL seed file to run before the action.
+	*
+	* With two or more declared databases the `database` option is mandatory;
+	* with exactly one it is forbidden (CONVENTIONS A7).
+	*
+	* @example
+	*   api.seed("users.sql", { database: "db" }).get("/users");
+	*/
+	seed(file, options) {
+		validateDatabaseOption("seed", this.config, options?.database);
+		this.seeds.push({
+			database: options?.database,
+			file
+		});
 		return this;
 	}
-	/** Assert a file exists inside the container */
-	async toHaveFile(path, opts) {
-		const file = await this.container.file(path);
-		if (!file.exists) throw new Error(`Expected file ${path} to exist in container`);
-		if (opts?.containing && !file.content.includes(opts.containing)) throw new Error(`Expected file ${path} to contain "${opts.containing}", got: ${file.content.slice(0, 200)}`);
+	/**
+	* Copy a fixture into the working directory before execution.
+	*
+	* The path is feature-local (resolved under `<test-dir>/fixtures/`) or, with
+	* a `$FIXTURES/` prefix, from the shared pool at `<specs-root>/fixtures/`.
+	* Copy semantics follow rsync's trailing-slash rule: `dir/` spreads the
+	* directory's contents into the cwd, while `dir` (or a plain file) is copied
+	* under its own basename. Chained calls layer in order — a later fixture
+	* overwrites files written by an earlier one.
+	*
+	* @example
+	*   cli.fixture('$FIXTURES/cli-app/').exec('build');   // shared project, spread
+	*   cli.fixture('config.toml').exec('migrate');        // feature-local file
+	*/
+	fixture(path) {
+		this.fixtures.push({ file: path });
 		return this;
 	}
-	/** Assert a file does NOT exist */
-	async toNotHaveFile(path) {
-		if (await this.container.exists(path)) throw new Error(`Expected ${path} to not exist in container`);
+	/**
+	* Set environment variables for the command process. Merged on top of process.env.
+	* Use `null` to unset a variable. Multiple calls merge.
+	*
+	* The token `$WORKDIR` (in any value) is replaced with the actual working
+	* directory at run-time — useful for tests that need a fully isolated `HOME`.
+	*
+	* @example
+	*   cli.env({ HOME: "$WORKDIR", TZ: "UTC" }).exec("status");
+	*/
+	env(env) {
+		this.commandEnv = {
+			...this.commandEnv,
+			...env
+		};
 		return this;
 	}
-	/** Assert a directory exists */
-	async toHaveDirectory(path) {
-		if (!await this.container.exists(path)) throw new Error(`Expected directory ${path} to exist in container`);
+	/**
+	* Set HTTP headers for the request. Multiple calls merge; chain headers
+	* win over headers from a `requests/*.http` file.
+	*
+	* @example
+	*   api.headers({ 'Accept-Language': 'fr' }).get("/articles");
+	*/
+	headers(headers) {
+		this.requestHeaders = {
+			...this.requestHeaders,
+			...headers
+		};
 		return this;
 	}
-	/** Assert a mount exists */
-	async toHaveMount(destination) {
-		const info = await this.container.inspect();
-		if (!info.hostConfig.mounts.find((m) => m.destination === destination)) {
-			const available = info.hostConfig.mounts.map((m) => m.destination).join(", ");
-			throw new Error(`Expected mount at ${destination}, found: [${available}]`);
+	intercept(triggerOrContracts, maybeResponse) {
+		if (this.config.interceptDisabledReason) throw new Error(`.intercept(): ${this.config.interceptDisabledReason}`);
+		if (Array.isArray(triggerOrContracts)) {
+			for (const contract of triggerOrContracts) this.registerIntercept(contract);
+			return this;
 		}
+		this.registerIntercept(triggerOrContracts, maybeResponse);
 		return this;
 	}
-	/** Assert network mode */
-	async toHaveNetwork(mode) {
-		const info = await this.container.inspect();
-		if (!info.hostConfig.networkMode.includes(mode)) throw new Error(`Expected network mode "${mode}", got "${info.hostConfig.networkMode}"`);
-		return this;
+	/** Register a single intercept — a contract, or a trigger + response pair. */
+	registerIntercept(triggerOrContract, maybeResponse) {
+		const isContract = "trigger" in triggerOrContract && "response" in triggerOrContract;
+		const trigger = isContract ? triggerOrContract.trigger : triggerOrContract;
+		const response = isContract ? triggerOrContract.response : maybeResponse;
+		if (typeof response === "string") {
+			const slashIndex = response.indexOf("/");
+			if (slashIndex === -1) throw new Error(`.intercept(): file path must be 'adapter/filename.json' (e.g. 'openai/ingest-tech.json'), got '${response}'`);
+			const adapterName = response.slice(0, slashIndex);
+			if (adapterName !== trigger.adapter) throw new Error(`.intercept(): adapter mismatch - trigger uses '${trigger.adapter}' but file path starts with '${adapterName}/'`);
+			const filePath = resolve(this.testDir, "intercepts", response);
+			const data = JSON.parse(readFileSync(filePath, "utf8"));
+			const resolved = trigger.wrap(data);
+			this.intercepts.push({
+				trigger,
+				response: resolved
+			});
+		} else this.intercepts.push({
+			trigger,
+			response
+		});
 	}
-	/** Assert memory limit */
-	async toHaveMemoryLimit(bytes) {
-		const info = await this.container.inspect();
-		if (info.hostConfig.memory !== bytes) throw new Error(`Expected memory limit ${bytes}, got ${info.hostConfig.memory}`);
-		return this;
+	/**
+	* Send the complete request described by `requests/<file>` — first line
+	* `METHOD /path`, then headers until a blank line, then the body.
+	* Headers set via `.headers()` merge on top of the file's headers.
+	*
+	* @example
+	*   const result = await api.request("create-user.http");
+	*/
+	request(file) {
+		return this.executeHttp({
+			method: "",
+			path: "",
+			requestFile: file
+		});
 	}
-	/** Assert CPU quota */
-	async toHaveCpuQuota(quota) {
-		const info = await this.container.inspect();
-		if (info.hostConfig.cpuQuota !== quota) throw new Error(`Expected CPU quota ${quota}, got ${info.hostConfig.cpuQuota}`);
-		return this;
+	/**
+	* Send a GET request to the server adapter and resolve with the result.
+	*
+	* @example
+	*   const result = await api.get("/api/items");
+	*/
+	get(path) {
+		return this.executeHttp({
+			method: "GET",
+			path
+		});
 	}
-	/** Execute a command and return output for custom assertions */
-	async exec(cmd) {
-		return this.container.exec(cmd);
+	/**
+	* Send a POST request to the server adapter and resolve with the result.
+	*
+	* @param body - Optional inline JSON body. Prefer `.request('name.http')`
+	*   for file-based request bodies.
+	* @example
+	*   const result = await api.post("/api/items", { name: "Widget" });
+	*/
+	post(path, body) {
+		return this.executeHttp({
+			body,
+			method: "POST",
+			path
+		});
+	}
+	/** Send a PUT request to the server adapter and resolve with the result. */
+	put(path, body) {
+		return this.executeHttp({
+			body,
+			method: "PUT",
+			path
+		});
+	}
+	/** Send a DELETE request to the server adapter and resolve with the result. */
+	delete(path) {
+		return this.executeHttp({
+			method: "DELETE",
+			path
+		});
 	}
-	/** Read a file for custom assertions */
-	async readFile(path) {
-		const file = await this.container.file(path);
-		if (!file.exists) throw new Error(`File ${path} does not exist`);
-		return file.content;
+	/**
+	* Execute a command (or a sequence of commands) in an isolated working
+	* directory and resolve with the result. When an array is passed, commands
+	* run sequentially and stop on the first non-zero exit code.
+	*
+	* With `{ waitFor, timeout }` the process is treated as long-running: it
+	* resolves (exit code 0) as soon as `waitFor` appears in stdout/stderr,
+	* and is killed at `timeout` (exit code 124). This is the single
+	* execution method — there is no `.spawn()` (CONVENTIONS B2).
+	*
+	* Invoked with no arguments, the binary runs bare (no CLI args) — clearer
+	* than the `.exec('')` idiom. An empty ARRAY stays an error: a command
+	* sequence must name at least one command.
+	*
+	* @example
+	*   const result = await cli.exec();                    // run the binary bare
+	*   const result = await cli.exec("init --name demo");
+	*   const result = await cli.exec(["init", "build"]);
+	*   const result = await cli.exec("dev --port 0", { waitFor: "Listening on", timeout: 10_000 });
+	*/
+	exec(args = "", options) {
+		if (Array.isArray(args) && args.length === 0) throw new Error("exec([]) requires at least one command");
+		if (options && Array.isArray(args)) throw new Error(".exec(): waitFor/timeout options are not supported with a command sequence");
+		return this.executeCommand({
+			args,
+			options
+		});
 	}
-	/** Get logs for custom assertions */
-	async getLogs(tail) {
-		return this.container.logs(tail);
+	/**
+	* Execute the named job registered via the `jobs` option of
+	* `specification.jobs()` and resolve with the result.
+	*
+	* @example
+	*   const result = await jobs.intercept(classifyArticle).trigger('report-refresh');
+	*/
+	async trigger(name) {
+		return this.executeSetup(null, () => this.runJobAction(name));
 	}
-};
-//#endregion
-//#region src/infra/adapters/compose.adapter.ts
-/**
-* Start the full compose stack and stop it all on cleanup.
-* Supports per-worker project names for parallel execution.
-*/
-var ComposeStackAdapter = class {
-	composeFile;
-	projectName;
-	started = false;
-	constructor(composeFile, projectName) {
-		this.composeFile = composeFile;
-		this.projectName = projectName ?? null;
+	async executeHttp(request) {
+		return this.executeSetup(null, () => this.runHttpAction(request));
 	}
-	get projectFlag() {
-		return this.projectName ? `-p ${this.projectName}` : "";
+	async executeCommand(action) {
+		const workDir = this.prepareWorkDir();
+		return this.executeSetup(workDir, () => this.runCommandAction(workDir, action));
 	}
-	run(command) {
+	/**
+	* Shared setup pipeline: reset databases, run seeds, copy fixtures,
+	* register intercepts — then run the action and clean up intercepts.
+	*/
+	async executeSetup(workDir, action) {
+		if (this.config.databases) for (const db of this.config.databases.values()) await db.reset();
+		else if (this.config.database) await this.config.database.reset();
+		for (const entry of this.seeds) {
+			let db;
+			if (entry.database && this.config.databases) {
+				db = this.config.databases.get(entry.database);
+				if (!db) throw new Error(`seed() targets database "${entry.database}" but it was not found. Available: ${[...this.config.databases.keys()].join(", ")}`);
+			} else db = this.config.database;
+			if (!db) throw new Error("seed() requires a database adapter");
+			const sql = readFileSync(resolve(this.testDir, "seeds", entry.file), "utf8");
+			await db.seed(sql);
+		}
+		if (this.fixtures.length > 0 && workDir) for (const entry of this.fixtures) {
+			const { dest, src } = copyPlan(entry.file, this.testDir, workDir);
+			cpSync(src, dest, { recursive: true });
+		}
+		let registration = null;
+		if (this.intercepts.length > 0) {
+			const { registerIntercepts } = await import("./intercept.js");
+			registration = await registerIntercepts(this.intercepts);
+		}
 		try {
-			return execSync(command, {
-				cwd: dirname(this.composeFile),
-				encoding: "utf8",
-				timeout: 12e4
-			}).trim();
+			const value = await action();
+			const violation = registration?.violation();
+			if (violation) throw violation;
+			return value;
 		} catch (error) {
-			const stderr = error.stderr?.toString().trim() ?? error.message;
-			throw new Error(`docker compose failed: ${stderr}`, { cause: error });
+			throw registration?.violation() ?? error;
+		} finally {
+			registration?.cleanup();
 		}
 	}
-	async start() {
-		if (this.started) return;
-		this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} up -d --wait`);
-		this.started = true;
-	}
-	async stop() {
-		if (!this.started) return;
-		this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} down -v`);
-		this.started = false;
-	}
-	getMappedPort(serviceName, containerPort) {
-		const port = this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} port ${serviceName} ${containerPort}`).split(":").pop();
-		return Number(port);
-	}
-	getHost() {
-		return "localhost";
-	}
-};
-//#endregion
-//#region src/infra/adapters/testcontainers.adapter.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/, 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;
+	resolveEnv(workDir) {
+		const keys = Object.keys(this.commandEnv);
+		if (keys.length === 0) return;
+		const resolved = {};
+		for (const key of keys) {
+			const value = this.commandEnv[key];
+			resolved[key] = typeof value === "string" ? value.replace(/\$WORKDIR/g, workDir) : value;
 		}
+		return resolved;
 	}
-	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();
+	prepareWorkDir() {
+		return mkdtempSync(resolve(tmpdir(), "spec-command-"));
+	}
+	async runHttpAction(request) {
+		if (!this.config.server) throw new Error("HTTP actions require a server adapter (use specification.api())");
+		let { body, method, path } = request;
+		let fileHeaders;
+		if (request.requestFile) {
+			const parsed = parseRequestFile(readFileSync(resolve(this.testDir, "requests", request.requestFile), "utf8"), `requests/${request.requestFile}`);
+			body = parsed.body;
+			fileHeaders = parsed.headers;
+			method = parsed.method;
+			path = parsed.path;
+		}
+		const headers = {
+			...fileHeaders,
+			...this.requestHeaders
+		};
+		const response = await this.config.server.request(method, path, body, Object.keys(headers).length > 0 ? headers : void 0);
+		return new HttpResult({
+			config: this.config,
+			response,
+			testDir: this.testDir
+		});
 	}
-	getConnectionString() {
-		return `${this.getHost()}:${this.getMappedPort(this.containerPort)}`;
+	async runJobAction(name) {
+		if (!this.config.jobs?.length) throw new Error("Job actions require jobs registered via the jobs option of specification.jobs()");
+		const job = this.config.jobs.find((j) => j.name === name);
+		if (!job) {
+			const available = this.config.jobs.map((j) => j.name).join(", ");
+			throw new Error(`trigger("${name}"): job not found. Available: ${available}`);
+		}
+		await job.execute();
+		return new BaseResult({
+			config: this.config,
+			testDir: this.testDir
+		});
 	}
-	async getLogs() {
-		if (!this.container) return "";
-		const stream = await this.container.logs();
-		return new Promise((resolve) => {
-			let output = "";
-			stream.on("data", (chunk) => {
-				output += chunk.toString();
-			});
-			stream.on("end", () => {
-				resolve(output);
-			});
-			setTimeout(() => {
-				resolve(output);
-			}, 1e3);
+	/**
+	* Automatic connection-URL injection (CONVENTIONS B6): `<KEY>_URL` for
+	* every declared service, plus the standard aliases when unambiguous —
+	* `DATABASE_URL` (exactly one SQL database) and `REDIS_URL` (exactly one
+	* redis). `.env()` overrides; `null` unsets.
+	*/
+	serviceEnv() {
+		const services = this.config.services;
+		if (!services || Object.keys(services).length === 0) return;
+		const env = {};
+		const sqlHandles = [];
+		const redisHandles = [];
+		for (const [key, handle] of Object.entries(services)) {
+			env[`${toConstantCase(key)}_URL`] = handle.connectionString;
+			if (handle.createDatabaseAdapter() !== null) sqlHandles.push(handle);
+			if (handle.type === "redis") redisHandles.push(handle);
+		}
+		if (sqlHandles.length === 1) env.DATABASE_URL = sqlHandles[0].connectionString;
+		if (redisHandles.length === 1) env.REDIS_URL = redisHandles[0].connectionString;
+		return env;
+	}
+	async runCommandAction(workDir, action) {
+		if (!this.config.command) throw new Error("Command actions require a command adapter");
+		const dockerConfig = this.config.dockerConfig;
+		const testRunId = this.config.dockerTestRunId;
+		let env = this.serviceEnv();
+		if (dockerConfig && testRunId) env = {
+			...env,
+			[dockerConfig.envVar]: testRunId
+		};
+		const userEnv = this.resolveEnv(workDir);
+		if (userEnv) env = {
+			...env,
+			...userEnv
+		};
+		let commandOutput;
+		if (action.options) commandOutput = await this.config.command.watch(action.args, workDir, action.options, env);
+		else if (Array.isArray(action.args)) {
+			commandOutput = {
+				exitCode: 0,
+				stderr: "",
+				stdout: ""
+			};
+			for (const args of action.args) {
+				commandOutput = await this.config.command.exec(args, workDir, env);
+				if (commandOutput.exitCode !== 0) break;
+			}
+		} else commandOutput = await this.config.command.exec(action.args, workDir, env);
+		return new CliResult({
+			commandOutput,
+			config: this.config,
+			dockerConfig: dockerConfig ?? void 0,
+			testDir: this.testDir,
+			testRunId: testRunId ?? void 0,
+			transform: this.config.transform,
+			workDir
 		});
 	}
 };
-//#endregion
-//#region src/infra/compose-parser.ts
+function withDockerTestRunId(config) {
+	if (config.dockerConfig && !config.dockerTestRunId) return {
+		...config,
+		dockerTestRunId: `t-${Math.random().toString(36).slice(2, 10)}-${Date.now().toString(36)}`
+	};
+	return config;
+}
 /**
-* Detect the service type from the image name.
+* Create the `api` facet bound to the given adapter configuration. The test
+* file directory is auto-detected from the call stack at each chain start.
 */
-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";
+function createApiFacet(config) {
+	const start = () => new SpecificationBuilder(config, getCallerDir());
+	return {
+		delete: (path) => start().delete(path),
+		get: (path) => start().get(path),
+		headers: (headers) => start().headers(headers),
+		intercept: (triggerOrContracts, response) => Array.isArray(triggerOrContracts) ? start().intercept(triggerOrContracts) : start().intercept(triggerOrContracts, response),
+		post: (path, body) => start().post(path, body),
+		put: (path, body) => start().put(path, body),
+		request: (file) => start().request(file),
+		seed: (file, options) => start().seed(file, options)
+	};
 }
 /**
-* Find the compose file in the project.
-* Looks for docker/compose.test.yaml or docker-compose.test.yaml.
+* Create the `jobs` facet bound to the given adapter configuration.
 */
-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;
+function createJobsFacet(config) {
+	const start = () => new SpecificationBuilder(config, getCallerDir());
+	return {
+		intercept: (triggerOrContracts, response) => Array.isArray(triggerOrContracts) ? start().intercept(triggerOrContracts) : start().intercept(triggerOrContracts, response),
+		seed: (file, options) => start().seed(file, options),
+		trigger: (name) => start().trigger(name)
+	};
 }
 /**
-* Parse a docker-compose file and extract service definitions.
+* Create the `cli` facet bound to the given adapter configuration.
 */
-function parseComposeFile(filePath) {
-	const doc = parse(readFileSync(filePath, "utf8"));
-	if (!doc?.services) return {
-		services: [],
-		appService: null,
-		infraServices: []
+function createCliFacet(config) {
+	const resolved = withDockerTestRunId(config);
+	const start = () => new SpecificationBuilder(resolved, getCallerDir());
+	return {
+		env: (env) => start().env(env),
+		exec: (args, options) => start().exec(args, options),
+		fixture: (path) => start().fixture(path),
+		seed: (file, options) => start().seed(file, options)
 	};
-	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("=");
-			environment[key] = rest.join("=");
+}
+//#endregion
+//#region src/core/specification/shared/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);
 		}
-		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)
 	};
 }
 //#endregion
-//#region src/infra/orchestrator.ts
+//#region src/core/specification/shared/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/core/specification/shared/orchestrator.ts
 /**
 * Orchestrator for test infrastructure.
 * Integration: starts services via testcontainers.
@@ -1300,6 +2588,17 @@ var Orchestrator = class {
 		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).
@@ -1308,10 +2607,11 @@ var Orchestrator = class {
 		if (this.started) return;
 		const composePath = findComposeFile(this.root);
 		const composeDir = composePath ? dirname(composePath) : this.root;
-		const composeConfig = composePath ? parseComposeFile(composePath) : null;
+		const composeConfig = composePath ? getContainerIntegrations().parseComposeFile(composePath) : null;
+		this.resolveBindings(composeConfig);
 		const containerServices = [];
 		const embeddedServices = [];
-		for (const handle of this.services) {
+		for (const handle of Object.values(this.services)) {
 			if (handle.defaultPort === 0) {
 				embeddedServices.push(handle);
 				continue;
@@ -1329,7 +2629,7 @@ var Orchestrator = class {
 					Object.assign(handle.environment, composeService.environment);
 				}
 			}
-			const container = new TestcontainersAdapter({
+			const container = getContainerIntegrations().createContainer({
 				image,
 				port: handle.defaultPort,
 				env
@@ -1392,395 +2692,1137 @@ var Orchestrator = class {
 		console.log(output);
 	}
 	/**
-	* Stop testcontainers (integration mode).
+	* 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);
+				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);
+			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);
+			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).appService;
+		if (!appService || appService.ports.length === 0) return null;
+		return `http://localhost:${this.composeStack.getMappedPort(appService.name, appService.ports[0].container)}`;
+	}
+};
+//#endregion
+//#region src/core/specification/shared/resolve.ts
+/**
+* Auto-discover the project root from a starting directory (CONVENTIONS A9):
+* walk up to the first directory containing `docker/compose.test.yaml`;
+* if none, walk up to the first directory containing `package.json`;
+* if none, the starting directory itself.
+*/
+function discoverRoot(startDir) {
+	for (const marker of ["docker/compose.test.yaml", "package.json"]) {
+		let dir = startDir;
+		for (;;) {
+			if (existsSync(resolve(dir, marker))) return dir;
+			const parent = dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+		}
+	}
+	return startDir;
+}
+/**
+* Resolve the project root for a specification. An explicit `root` option is
+* an override (resolved from the caller's directory when relative); when
+* absent, the root is auto-discovered by walking up from the calling
+* specification file.
+*/
+function resolveRoot(root, callerDir) {
+	if (!root) return discoverRoot(callerDir);
+	if (isAbsolute(root)) return root;
+	return resolve(callerDir, root);
+}
+/**
+* Resolve a command — checks node_modules/.bin, then treats as absolute/PATH.
+*/
+function resolveCommand(command, root) {
+	if (isAbsolute(command)) return command;
+	const binPath = resolve(root, "node_modules/.bin", command);
+	if (existsSync(binPath)) return binPath;
+	const cwdBinPath = resolve(process.cwd(), "node_modules/.bin", command);
+	if (existsSync(cwdBinPath)) return cwdBinPath;
+	return command;
+}
+//#endregion
+//#region src/core/specification/shared/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.keys(services).filter((key) => services[key].createDatabaseAdapter() !== null);
+}
+/** 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/core/specification/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 = (ms) => 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(/\/$/, "");
+	}
+	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/core/specification/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;
+}
+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();
+	return {
+		api: createApiFacet({
+			database: orchestrator.getDatabase() ?? void 0,
+			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)
+		}),
+		cleanup: () => orchestrator.stopCompose(),
+		docker: createDockerReader(callerDir),
+		orchestrator
+	};
+}
+//#endregion
+//#region src/core/specification/cli/exec.adapter.ts
+const DEFAULT_WATCH_TIMEOUT = 1e4;
+/** Grace period between SIGTERM and the SIGKILL escalation. */
+const KILL_GRACE_MS = 2e3;
+/**
+* Build a child-process env from the parent env plus user overrides.
+* `null` overrides delete keys (e.g. `INIT_CWD: null`).
+*
+* @internal Exported for unit tests.
+*/
+function buildEnv(extra) {
+	const env = {
+		...process.env,
+		INIT_CWD: void 0
+	};
+	if (extra) for (const [key, value] of Object.entries(extra)) if (value === null) delete env[key];
+	else env[key] = value;
+	return env;
+}
+/**
+* Observe a long-running child (`.exec(args, { waitFor, timeout })`):
+* resolve with exit code 0 as soon as `waitFor` appears in stdout/stderr,
+* with the process's own code when it exits first, and with 124 at the
+* timeout. On resolution the child is terminated with SIGTERM, escalating
+* to SIGKILL after a 2 s grace period; all timers are cleared on exit and
+* the timeout timer is unref'd so it never holds the runner open.
+*
+* @internal Exported for unit tests (driven with a fake child).
+*/
+function observeProcess(child, options) {
+	const timeout = options.timeout ?? DEFAULT_WATCH_TIMEOUT;
+	const waitFor = options.waitFor;
+	return new Promise((resolve) => {
+		let stdout = "";
+		let stderr = "";
+		let resolved = false;
+		let exited = false;
+		let patternMatched = false;
+		let killTimer = null;
+		const timeoutTimer = setTimeout(() => finish(124), timeout);
+		timeoutTimer.unref?.();
+		const terminate = () => {
+			if (exited) return;
+			child.kill("SIGTERM");
+			killTimer = setTimeout(() => {
+				if (!exited) child.kill("SIGKILL");
+			}, KILL_GRACE_MS);
+		};
+		const finish = (exitCode) => {
+			if (resolved) return;
+			resolved = true;
+			clearTimeout(timeoutTimer);
+			terminate();
+			resolve({
+				exitCode,
+				stderr,
+				stdout
+			});
+		};
+		const checkPattern = () => {
+			if (waitFor !== void 0 && !patternMatched && (stdout.includes(waitFor) || stderr.includes(waitFor))) {
+				patternMatched = true;
+				finish(0);
+			}
+		};
+		child.stdout?.on("data", (data) => {
+			stdout += data.toString();
+			checkPattern();
+		});
+		child.stderr?.on("data", (data) => {
+			stderr += data.toString();
+			checkPattern();
+		});
+		child.on("exit", (code) => {
+			exited = true;
+			if (killTimer) clearTimeout(killTimer);
+			if (patternMatched) return;
+			if (waitFor === void 0) {
+				finish(code ?? 1);
+				return;
+			}
+			finish(code === 0 ? 1 : code ?? 1);
+		});
+	});
+}
+/**
+* Executes commands via Node.js child_process.
+* Uses `spawnSync` for one-shot commands and `spawn` for long-running
+* processes (`.exec(args, { waitFor, timeout })`).
+*
+* Both paths run the full command line through the shell — quoting behaves
+* identically whether or not `waitFor` is used.
+*
+* `spawnSync` is used (over the simpler `execSync`) so stdout AND stderr are
+* captured regardless of exit code. Many CLIs follow the Unix convention of
+* writing status banners to stderr on success — `execSync` would silently
+* discard them, leaving snapshot tests with no output to assert on.
+*/
+var ExecAdapter = class {
+	command;
+	constructor(command) {
+		this.command = command;
+	}
+	async exec(args, cwd, extraEnv) {
+		const env = buildEnv(extraEnv);
+		const result = spawnSync(`${this.command} ${args}`, [], {
+			cwd,
+			encoding: "utf8",
+			env,
+			shell: true,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		return {
+			exitCode: result.status ?? 1,
+			stderr: result.stderr ?? "",
+			stdout: result.stdout ?? ""
+		};
+	}
+	async watch(args, cwd, options, extraEnv) {
+		const env = buildEnv(extraEnv);
+		const child = spawn(`${this.command} ${args}`, [], {
+			cwd,
+			detached: process.platform !== "win32",
+			env,
+			shell: true,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		const kill = (signal) => {
+			if (child.pid !== void 0 && process.platform !== "win32") try {
+				process.kill(-child.pid, signal ?? "SIGTERM");
+				return true;
+			} catch {}
+			return child.kill(signal);
+		};
+		return observeProcess({
+			kill,
+			on: child.on.bind(child),
+			stderr: child.stderr,
+			stdout: child.stdout
+		}, options);
+	}
+};
+//#endregion
+//#region src/core/specification/cli/start-cli.ts
+async function startCli(bin, options = {}) {
+	const callerDir = getCallerDir();
+	await registerMatchers();
+	const root = resolveRoot(options.root, callerDir);
+	const resolvedBin = resolveCommand(bin, root);
+	const services = options.services ?? {};
+	const databaseKeys = declaredDatabaseKeys(services);
+	let started = null;
+	if (Object.keys(services).length > 0) started = await startServices(services, root);
+	return {
+		cleanup: async () => {
+			await releaseIsolation(services);
+			if (started) await started.orchestrator.stop();
+		},
+		cli: createCliFacet({
+			command: new ExecAdapter(resolvedBin),
+			database: started?.database,
+			databaseKeys,
+			databases: started?.databases,
+			dockerConfig: options.docker,
+			services: Object.keys(services).length > 0 ? services : void 0,
+			transform: options.transform
+		}),
+		docker: createDockerReader(callerDir),
+		orchestrator: started?.orchestrator ?? null
+	};
+}
+//#endregion
+//#region src/core/specification/jobs/start-jobs.ts
+async function startJobs(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);
+	const jobHandles = typeof options.jobs === "function" ? options.jobs(services) : options.jobs;
+	return {
+		cleanup: async () => {
+			await releaseIsolation(services);
+			if (started) await started.orchestrator.stop();
+		},
+		jobs: createJobsFacet({
+			database: started?.database,
+			databaseKeys,
+			databases: started?.databases,
+			jobs: jobHandles
+		}),
+		orchestrator: started?.orchestrator ?? null
+	};
+}
+//#endregion
+//#region src/core/specification/shared/specification.ts
+/**
+* The three specification constructors (CONVENTIONS A2) — created in a
+* `*.specification.ts` file under `specs/`, destructured with canonical
+* names, and cleaned up via `afterAll(cleanup)` (A1/A3/A4).
+*
+* @example
+*   // specs/api/api.specification.ts
+*   export const { api, cleanup } = await specification.api({
+*       services: { db: postgres() },
+*       server: ({ db }) => createApp({ databaseUrl: db.connectionString }),
+*   });
+*   afterAll(cleanup);
+*
+*   // specs/jobs/jobs.specification.ts
+*   export const { jobs, cleanup } = await specification.jobs({
+*       services: { db: postgres() },
+*       jobs: ({ db }) => [nightlyReport(db)],
+*   });
+*   afterAll(cleanup);
+*
+*   // specs/setup/cli.specification.ts
+*   export const { cli, cleanup } = await specification.cli('my-cli');
+*   afterAll(cleanup);
+*/
+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.
 	*/
-	async stop() {
-		for (const { container } of this.running) if (container) await container.stop();
-		this.running = [];
-		this.started = false;
-	}
+	api: startApi,
 	/**
-	* Start full docker compose stack (e2e mode).
-	* Auto-detects infra services and creates handles for them.
+	* Test a command binary. Each spec runs in a fresh temp directory.
+	*
+	* @param bin - Path to the binary (resolved from node_modules/.bin or PATH).
 	*/
-	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 = parseComposeFile(composePath);
-		this.composeStack = new ComposeStackAdapter(composePath, this.projectName);
-		await this.composeStack.start();
-		for (const service of composeConfig.infraServices) {
-			const type = detectServiceType(service.image);
-			if (type === "postgres") {
-				const handle = postgres({
-					compose: service.name,
-					env: service.environment
-				});
-				const port = this.composeStack.getMappedPort(service.name, 5432);
-				handle.connectionString = handle.buildConnectionString("localhost", port);
-				await handle.initialize(composeDir);
-				handle.started = true;
-				this.composeHandles.push(handle);
-			} else if (type === "redis") {
-				const handle = redis({ compose: service.name });
-				const port = this.composeStack.getMappedPort(service.name, 6379);
-				handle.connectionString = handle.buildConnectionString("localhost", port);
-				handle.started = true;
-				this.composeHandles.push(handle);
-			}
-		}
-		const durationMs = Date.now() - startTime;
-		const output = formatStartupReport("e2e", this.composeHandles.map((h) => ({
-			name: h.composeName ?? h.type,
-			type: h.type,
-			connectionString: h.connectionString,
-			durationMs
-		})), {
-			type: "http",
-			url: this.getAppUrl() ?? void 0
-		});
-		console.log(output);
-	}
+	cli: startCli,
 	/**
-	* Stop docker compose stack (e2e mode).
+	* Test background jobs. Jobs run in-process by definition — no HTTP
+	* server, no mode. `.trigger(name)` is the terminal action.
 	*/
-	async stopCompose() {
-		if (this.composeStack) {
-			await this.composeStack.stop();
-			this.composeStack = null;
+	jobs: startJobs
+};
+//#endregion
+//#region src/integrations/sqlite/sqlite.ts
+var SqliteHandle = class {
+	type = "sqlite";
+	composeName = null;
+	defaultPort = 0;
+	defaultImage = "";
+	environment = {};
+	connectionString = "";
+	started = false;
+	db = null;
+	templatePath = "";
+	workerDbPath = "";
+	initSql;
+	prismaSchema;
+	constructor(options = {}) {
+		this.initSql = options.init ?? null;
+		this.prismaSchema = options.prismaSchema ?? null;
+	}
+	buildConnectionString() {
+		return `file:${this.workerDbPath || this.templatePath}`;
+	}
+	createDatabaseAdapter() {
+		return this;
+	}
+	async healthcheck() {}
+	async initialize() {
+		this.templatePath = resolve(tmpdir(), "jterrazz-test-sqlite-template.sqlite");
+		const lockPath = `${this.templatePath}.lock`;
+		if (existsSync(lockPath)) {
+			const start = Date.now();
+			while (existsSync(lockPath) && Date.now() - start < 3e4) await new Promise((r) => setTimeout(r, 100));
 		}
-		this.composeHandles = [];
+		if (existsSync(this.templatePath)) {
+			this.connectionString = `file:${this.templatePath}`;
+			this.started = true;
+			return;
+		}
+		const { writeFileSync } = await import("node:fs");
+		writeFileSync(lockPath, process.pid.toString());
+		if (this.prismaSchema) {
+			const { execSync } = await import("node:child_process");
+			execSync("npx prisma db push --force-reset", {
+				env: {
+					...process.env,
+					DATABASE_URL: `file:${this.templatePath}`,
+					PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION: "yes"
+				},
+				stdio: "pipe"
+			});
+			const tmpDb = new Database(this.templatePath);
+			tmpDb.pragma("wal_checkpoint(TRUNCATE)");
+			tmpDb.close();
+		} else if (this.initSql) {
+			const sql = readFileSync(this.initSql, "utf8");
+			const templateDb = new Database(this.templatePath);
+			templateDb.exec(sql);
+			templateDb.close();
+		} else new Database(this.templatePath).close();
+		try {
+			unlinkSync(lockPath);
+		} catch {}
+		this.connectionString = `file:${this.templatePath}`;
+		this.started = true;
 	}
-	/**
-	* Get a database service by compose name, or the first one if no name given.
-	*/
-	getDatabase(serviceName) {
-		for (const handle of [...this.services, ...this.composeHandles]) {
-			if (serviceName && handle.composeName !== serviceName) continue;
-			const adapter = handle.createDatabaseAdapter();
-			if (adapter) return adapter;
+	getDb() {
+		const dbPath = this.workerDbPath || this.templatePath;
+		if (!this.db) {
+			this.db = new Database(dbPath);
+			this.db.pragma("journal_mode = WAL");
 		}
-		return null;
+		return this.db;
 	}
-	/**
-	* Get all database services keyed by compose name.
-	*/
-	getDatabases() {
-		const map = /* @__PURE__ */ new Map();
-		for (const handle of [...this.services, ...this.composeHandles]) {
-			const adapter = handle.createDatabaseAdapter();
-			if (adapter && handle.composeName) map.set(handle.composeName, adapter);
+	closeDb() {
+		if (this.db) {
+			this.db.close();
+			this.db = null;
 		}
-		return map;
 	}
-	/**
-	* Get app URL from compose (e2e mode).
-	*/
-	getAppUrl() {
-		const composePath = findComposeFile(this.root);
-		if (!composePath || !this.composeStack) return null;
-		const appService = parseComposeFile(composePath).appService;
-		if (!appService || appService.ports.length === 0) return null;
-		return `http://localhost:${this.composeStack.getMappedPort(appService.name, appService.ports[0].container)}`;
+	async seed(sql) {
+		this.getDb().exec(sql);
 	}
-};
-//#endregion
-//#region src/spec/resolve.ts
-/**
-* Resolve root — if relative, resolves from the caller's directory.
-*/
-function resolveProjectRoot(root) {
-	if (!root) return process.cwd();
-	if (isAbsolute(root)) return root;
-	const stack = (/* @__PURE__ */ new Error("resolve root")).stack;
-	if (stack) {
-		const lines = stack.split("\n");
-		for (const line of lines) {
-			const match = line.match(/at\s+(?:.*?\()?(?:file:\/\/)?([^:)]+):\d+:\d+/);
-			if (!match) continue;
-			const filePath = match[1];
-			if (filePath.includes("node_modules") || filePath.includes("/src/spec/")) continue;
-			return resolve(filePath, "..", root);
-		}
+	async query(table, columns) {
+		const columnList = columns.join(", ");
+		return this.getDb().prepare(`SELECT ${columnList} FROM "${table}" ORDER BY 1`).all().map((row) => columns.map((col) => row[col]));
 	}
-	return resolve(process.cwd(), root);
-}
-/**
-* Resolve a CLI command — checks node_modules/.bin, then treats as absolute/PATH.
-*/
-function resolveCommand(command, root) {
-	if (isAbsolute(command)) return command;
-	const binPath = resolve(root, "node_modules/.bin", command);
-	if (existsSync(binPath)) return binPath;
-	const cwdBinPath = resolve(process.cwd(), "node_modules/.bin", command);
-	if (existsSync(cwdBinPath)) return cwdBinPath;
-	return command;
-}
-//#endregion
-//#region src/spec/spec.ts
+	async reset() {
+		const db = this.getDb();
+		const tables = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE '_prisma%' AND name != 'sqlite_sequence'`).all();
+		for (const { name } of tables) db.exec(`DELETE FROM "${name}"`);
+	}
+	isolation() {
+		return {
+			acquire: async (workerId) => {
+				this.closeDb();
+				this.workerDbPath = resolve(tmpdir(), `test-worker-${workerId}-${Date.now()}.sqlite`);
+				copyFileSync(this.templatePath, this.workerDbPath);
+				this.connectionString = `file:${this.workerDbPath}`;
+			},
+			reset: async () => {
+				await this.reset();
+			},
+			release: async () => {
+				this.closeDb();
+				if (this.workerDbPath && existsSync(this.workerDbPath)) unlinkSync(this.workerDbPath);
+				this.workerDbPath = "";
+				this.connectionString = `file:${this.templatePath}`;
+			}
+		};
+	}
+};
 /**
-* Create a specification runner for the given target.
-*
-* @param target - What to test against: {@link app}, {@link stack}, or {@link command}.
-* @param options - Shared options: root directory, infrastructure services.
+* Create a SQLite service handle. Uses file-copy isolation for parallel tests.
 *
 * @example
-*   // HTTP — in-process app with testcontainers
-*   const s = await spec(app(() => createApp(db)), { services: [db] });
+*   // With Prisma schema
+*   const db = sqlite({ prismaSchema: './prisma/schema' });
 *
-*   // HTTP — full docker compose stack
-*   const s = await spec(stack('../../'));
+*   // With raw SQL init
+*   const db = sqlite({ init: './schema.sql' });
 *
-*   // CLI — command binary
-*   const s = await spec(command('my-cli'), { root: '../fixtures' });
+*   // Empty database
+*   const db = sqlite();
 */
-async function spec(target, options = {}) {
-	switch (target.kind) {
-		case "app": return startApp(target, options);
-		case "stack": return startStack(target, options);
-		case "command": return startCommand(target, options);
-	}
-}
-function getWorkerId() {
-	return process.env.VITEST_POOL_ID ?? "0";
-}
-async function acquireIsolation(services) {
-	const workerId = getWorkerId();
-	for (const service of services) await service.isolation().acquire(workerId);
+function sqlite(options = {}) {
+	return new SqliteHandle(options);
 }
-async function releaseIsolation(services) {
-	for (const service of services) await service.isolation().release();
-}
-async function startApp(target, options) {
-	const services = options.services ?? [];
-	const orchestrator = new Orchestrator({
-		mode: "integration",
-		root: resolveProjectRoot(options.root),
-		services
-	});
-	await orchestrator.start();
-	await acquireIsolation(services);
-	const servicesMap = {};
-	for (const svc of services) {
-		const key = svc.composeName ?? svc.type;
-		servicesMap[key] = svc;
-	}
-	const factoryResult = target.factory(servicesMap);
-	const isComposite = Array.isArray(factoryResult.jobs);
-	const honoApp = isComposite ? factoryResult.server : factoryResult;
-	const jobs = isComposite ? factoryResult.jobs : void 0;
-	const database = orchestrator.getDatabase() ?? void 0;
-	const databases = orchestrator.getDatabases();
-	const runner = createSpecificationRunner({
-		database,
-		databases: databases.size > 0 ? databases : void 0,
-		jobs,
-		server: new HonoAdapter(honoApp)
-	});
-	runner.cleanup = async () => {
-		await releaseIsolation(services);
-		await orchestrator.stop();
-	};
-	runner.docker = (id) => new DockerAssertion(dockerContainer(id));
-	runner.orchestrator = orchestrator;
-	return runner;
+//#endregion
+//#region src/integrations/anthropic/anthropic.ts
+const ANTHROPIC_MESSAGES_URL = "https://api.anthropic.com/v1/messages";
+function matchesFilter(body, filter) {
+	if (filter.model) {
+		const model = body?.model;
+		if (typeof filter.model === "string" && model !== filter.model) return false;
+		if (filter.model instanceof RegExp && !filter.model.test(model ?? "")) return false;
+	}
+	if (filter.system) {
+		const system = typeof body?.system === "string" ? body.system : "";
+		if (typeof filter.system === "string" && !system.includes(filter.system)) return false;
+		if (filter.system instanceof RegExp && !filter.system.test(system)) return false;
+	}
+	if (filter.user) {
+		const userMsg = body?.messages?.find((m) => m.role === "user")?.content ?? "";
+		const text = typeof userMsg === "string" ? userMsg : JSON.stringify(userMsg);
+		if (typeof filter.user === "string" && !text.includes(filter.user)) return false;
+		if (filter.user instanceof RegExp && !filter.user.test(text)) return false;
+	}
+	if (filter.tools) {
+		const names = body?.tools?.map((t) => t.name).filter(Boolean) ?? [];
+		if (!filter.tools.every((t) => names.includes(t))) return false;
+	}
+	return true;
 }
-async function startStack(target, options) {
-	const root = resolveProjectRoot(target.root ?? options.root);
-	const projectName = `test-worker-${getWorkerId()}`;
-	const orchestrator = new Orchestrator({
-		mode: "e2e",
-		root,
-		services: options.services ?? [],
-		projectName
-	});
-	await orchestrator.startCompose();
-	const appUrl = orchestrator.getAppUrl();
-	if (!appUrl) throw new Error("stack(): could not detect app URL from compose. Ensure an app service with ports is defined.");
-	const database = orchestrator.getDatabase() ?? void 0;
-	const databases = orchestrator.getDatabases();
-	const runner = createSpecificationRunner({
-		database,
-		databases: databases.size > 0 ? databases : void 0,
-		server: new FetchAdapter(appUrl)
-	});
-	runner.cleanup = () => orchestrator.stopCompose();
-	runner.docker = (id) => new DockerAssertion(dockerContainer(id));
-	runner.orchestrator = orchestrator;
-	return runner;
-}
-async function startCommand(target, options) {
-	const root = resolveProjectRoot(options.root);
-	const bin = resolveCommand(target.bin, root);
-	const services = options.services ?? [];
-	let orchestrator = null;
-	let database;
-	let databases;
-	if (services.length) {
-		orchestrator = new Orchestrator({
-			mode: "integration",
-			root,
-			services
-		});
-		await orchestrator.start();
-		await acquireIsolation(services);
-		database = orchestrator.getDatabase() ?? void 0;
-		const dbMap = orchestrator.getDatabases();
-		databases = dbMap.size > 0 ? dbMap : void 0;
-	}
-	const runner = createSpecificationRunner({
-		command: new ExecAdapter(bin),
-		database,
-		databases,
-		fixturesRoot: root
-	});
-	runner.cleanup = async () => {
-		await releaseIsolation(services);
-		if (orchestrator) await orchestrator.stop();
+function buildReply(data) {
+	return {
+		status: 200,
+		body: {
+			id: "msg-test",
+			type: "message",
+			role: "assistant",
+			content: [{
+				type: "text",
+				text: typeof data === "string" ? data : JSON.stringify(data)
+			}],
+			model: "claude-sonnet-4-20250514",
+			stop_reason: "end_turn",
+			usage: {
+				input_tokens: 10,
+				output_tokens: 10
+			}
+		}
 	};
-	runner.docker = (id) => new DockerAssertion(dockerContainer(id));
-	runner.orchestrator = orchestrator;
-	return runner;
 }
-//#endregion
-//#region src/spec/targets.ts
 /**
-* Test against an in-process Hono app. The factory receives started services
-* so you can wire connection strings into your app/DI container.
-*
-* @param factory - Function that receives services and returns a Hono app instance.
-*
-* @example
-*   const db = postgres({ compose: 'db' });
-*   await spec(
-*       app((services) => createApp({ databaseUrl: services.db.connectionString })),
-*       { services: [db] },
-*   );
+* Anthropic API intercept helpers.
 */
-function app(factory) {
+const anthropic = {
+	/**
+	* Trigger: match Messages API requests, optionally routed through a
+	* custom gateway URL. When used with a JSON fixture file, the data is
+	* returned as-is (no wrapping) because Anthropic fixtures are typically
+	* already in the Messages API response shape.
+	*
+	* @example
+	*   anthropic.messages()
+	*   anthropic.messages({ system: /classify/ })
+	*   anthropic.messages({ user: /classify/ }, GATEWAY)
+	*/
+	messages(filter, url) {
+		return {
+			adapter: "anthropic",
+			method: "POST",
+			url: url ?? ANTHROPIC_MESSAGES_URL,
+			match: filter ? ({ body }) => matchesFilter(body, filter) : void 0,
+			wrap(data) {
+				if (data && typeof data === "object" && !Array.isArray(data)) return {
+					status: 200,
+					body: data
+				};
+				return buildReply(data);
+			}
+		};
+	},
+	/** Response: wrap data in Anthropic messages format. */
+	reply: buildReply,
+	/** Response: return an Anthropic error. */
+	error(status, message) {
+		return {
+			status,
+			body: {
+				type: "error",
+				error: {
+					type: status === 429 ? "rate_limit_error" : "api_error",
+					message: message ?? `Anthropic error (${status})`
+				}
+			}
+		};
+	},
+	/** Response: simulate a timeout. */
+	timeout() {
+		return {
+			status: 200,
+			body: {},
+			delay: 3e4
+		};
+	}
+};
+//#endregion
+//#region src/core/contracts/http.ts
+function wrapJson(data) {
 	return {
-		kind: "app",
-		factory
+		status: 200,
+		body: data
 	};
 }
+function matchesBody(body, expected) {
+	if (typeof expected === "string") return (typeof body === "string" ? body : JSON.stringify(body ?? "")).includes(expected);
+	if (expected instanceof RegExp) {
+		const text = typeof body === "string" ? body : JSON.stringify(body ?? "");
+		return expected.test(text);
+	}
+	return structuralSubset(expected, body, new CaptureScope());
+}
+function matchesEntries(expected, lookup) {
+	return Object.entries(expected).every(([key, value]) => {
+		const actual = lookup(key);
+		if (actual === void 0) return false;
+		return value instanceof RegExp ? value.test(actual) : actual === value;
+	});
+}
 /**
-* Test against a full docker compose stack. The stack is started with
-* `docker compose up` and real HTTP requests are sent to the app service.
-*
-* @param root - Project root containing `docker/compose.test.yaml`.
-*
-* @example
-*   await spec(stack('../../'));
+* Build the `match` predicate for an HTTP trigger filter, or `undefined` when
+* no filter is supplied (fires on any URL/method match).
 */
-function stack(root) {
-	return {
-		kind: "stack",
-		root
+function buildMatch(filter) {
+	if (!filter) return;
+	return (request) => {
+		if (filter.body !== void 0 && !matchesBody(request.body, filter.body)) return false;
+		if (filter.headers && !matchesEntries(filter.headers, (key) => request.headers[key.toLowerCase()])) return false;
+		if (filter.query) {
+			let params;
+			try {
+				params = new URL(request.url).searchParams;
+			} catch {
+				return false;
+			}
+			if (!matchesEntries(filter.query, (key) => params.get(key) ?? void 0)) return false;
+		}
+		return true;
 	};
 }
 /**
-* Test a CLI binary. Each spec runs in a fresh temp directory.
-*
-* @param bin - Path to the CLI binary or command name (resolved from node_modules/.bin or PATH).
+* Generic HTTP intercept helpers for any URL. An optional {@link
+* HttpInterceptFilter} narrows matching by request body, headers, or query —
+* a request that hits the URL/method but fails the filter counts as unmatched
+* (strict intercepts, CONVENTIONS D7).
 *
 * @example
-*   await spec(command('my-cli'), { root: '../fixtures' });
+*   .intercept(http.get('https://api.example.com/data'), 'http/response.json')
+*   .intercept(http.post(URL, { body: { user: 'alice' } }), http.json({ ok: true }))
 */
-function command(bin) {
+const http = {
+	get(url, filter) {
+		return {
+			adapter: "http",
+			match: buildMatch(filter),
+			method: "GET",
+			url,
+			wrap: wrapJson
+		};
+	},
+	post(url, filter) {
+		return {
+			adapter: "http",
+			match: buildMatch(filter),
+			method: "POST",
+			url,
+			wrap: wrapJson
+		};
+	},
+	put(url, filter) {
+		return {
+			adapter: "http",
+			match: buildMatch(filter),
+			method: "PUT",
+			url,
+			wrap: wrapJson
+		};
+	},
+	delete(url, filter) {
+		return {
+			adapter: "http",
+			match: buildMatch(filter),
+			method: "DELETE",
+			url,
+			wrap: wrapJson
+		};
+	},
+	any(url, filter) {
+		return {
+			adapter: "http",
+			match: buildMatch(filter),
+			method: "*",
+			url,
+			wrap: wrapJson
+		};
+	},
+	/** Response: simple JSON success. */
+	json(data, status = 200) {
+		return {
+			status,
+			body: data
+		};
+	},
+	/** Response: error with message. */
+	error(status, message) {
+		return {
+			status,
+			body: { error: message ?? `HTTP ${status}` }
+		};
+	}
+};
+//#endregion
+//#region src/integrations/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) {
+	if (filter.model) {
+		const model = body?.model;
+		if (typeof filter.model === "string" && model !== filter.model) return false;
+		if (filter.model instanceof RegExp && !filter.model.test(model ?? "")) return false;
+	}
+	if (filter.system) {
+		const msg = body?.messages?.find((m) => m.role === "system")?.content ?? "";
+		if (typeof filter.system === "string" && !msg.includes(filter.system)) return false;
+		if (filter.system instanceof RegExp && !filter.system.test(msg)) return false;
+	}
+	if (filter.user) {
+		const msg = body?.messages?.find((m) => m.role === "user")?.content ?? "";
+		if (typeof filter.user === "string" && !msg.includes(filter.user)) return false;
+		if (filter.user instanceof RegExp && !filter.user.test(msg)) return false;
+	}
+	if (filter.tools) {
+		const names = body?.tools?.map((t) => t.function?.name).filter(Boolean) ?? [];
+		if (!filter.tools.every((t) => names.includes(t))) return false;
+	}
+	if (filter.temperature !== void 0 && body?.temperature !== filter.temperature) return false;
+	return true;
+}
+function matchesResponsesFilter(body, filter) {
+	if (filter.model) {
+		const model = body?.model;
+		if (typeof filter.model === "string" && model !== filter.model) return false;
+		if (filter.model instanceof RegExp && !filter.model.test(model ?? "")) return false;
+	}
+	if (filter.system) {
+		const instructions = body?.instructions ?? "";
+		const systemInput = body?.input?.find?.((m) => m.role === "system")?.content ?? "";
+		const text = instructions || systemInput;
+		if (typeof filter.system === "string" && !text.includes(filter.system)) return false;
+		if (filter.system instanceof RegExp && !filter.system.test(text)) return false;
+	}
+	if (filter.user) {
+		const msgs = (body?.input ?? []).filter((m) => m.role === "user").map((m) => typeof m.content === "string" ? m.content : JSON.stringify(m.content)).join(" ");
+		if (typeof filter.user === "string" && !msgs.includes(filter.user)) return false;
+		if (filter.user instanceof RegExp && !filter.user.test(msgs)) return false;
+	}
+	if (filter.tools) {
+		const names = body?.tools?.map((t) => t.name ?? t.function?.name).filter(Boolean) ?? [];
+		if (!filter.tools.every((t) => names.includes(t))) return false;
+	}
+	return true;
+}
+function buildChatReply(data) {
+	const content = typeof data === "string" ? data : JSON.stringify(data);
 	return {
-		kind: "command",
-		bin
+		status: 200,
+		body: {
+			id: "chatcmpl-test",
+			object: "chat.completion",
+			created: Math.floor(Date.now() / 1e3),
+			model: "gpt-4o-test",
+			choices: [{
+				index: 0,
+				message: {
+					role: "assistant",
+					content
+				},
+				finish_reason: "stop"
+			}],
+			usage: {
+				prompt_tokens: 10,
+				completion_tokens: 10,
+				total_tokens: 20
+			}
+		}
 	};
 }
-//#endregion
-//#region src/spec/legacy-cli.ts
-/**
-* Create a CLI specification runner.
-* Runs CLI commands against fixture projects. Optionally starts infrastructure.
-*/
-async function cli(options) {
-	const root = resolveProjectRoot(options.root);
-	const command = resolveCommand(options.command, root);
-	let orchestrator = null;
-	let database;
-	let databases;
-	if (options.services?.length) {
-		orchestrator = new Orchestrator({
-			mode: "integration",
-			root,
-			services: options.services
-		});
-		await orchestrator.start();
-		database = orchestrator.getDatabase() ?? void 0;
-		const dbMap = orchestrator.getDatabases();
-		databases = dbMap.size > 0 ? dbMap : void 0;
-	}
-	const runner = createSpecificationRunner({
-		command: new ExecAdapter(command),
-		database,
-		databases,
-		fixturesRoot: root
-	});
-	runner.cleanup = async () => {
-		if (orchestrator) await orchestrator.stop();
+function buildResponsesReply(data) {
+	const text = typeof data === "string" ? data : JSON.stringify(data);
+	return {
+		status: 200,
+		body: {
+			id: "resp-test",
+			object: "response",
+			created_at: Math.floor(Date.now() / 1e3),
+			model: "gpt-4o-test",
+			output: [{
+				type: "message",
+				id: "msg-test",
+				role: "assistant",
+				content: [{
+					type: "output_text",
+					text,
+					annotations: []
+				}]
+			}],
+			usage: {
+				input_tokens: 10,
+				output_tokens: 10,
+				total_tokens: 20
+			}
+		}
 	};
-	runner.orchestrator = orchestrator;
-	return runner;
 }
+/**
+* OpenAI API intercept helpers.
+*/
+const openai = {
+	/**
+	* Trigger: match Chat Completions API requests.
+	*
+	* @example
+	*   openai.chat()                         // any chat call
+	*   openai.chat({ model: 'gpt-4o' })      // specific model
+	*   openai.chat({ system: /classify/ })    // system prompt match
+	*/
+	chat(filter) {
+		return {
+			adapter: "openai",
+			method: "POST",
+			url: OPENAI_CHAT_URL,
+			match: filter ? ({ body }) => matchesChatFilter(body, filter) : void 0,
+			wrap: buildChatReply
+		};
+	},
+	/**
+	* Trigger: match Responses API requests (AI SDK v5+) with auto-wrapping.
+	* When used with a JSON file, the data is automatically wrapped in the
+	* Responses API envelope.
+	*
+	* @param filter - Optional body filters.
+	* @param url - Custom gateway URL (default: api.openai.com).
+	*
+	* @example
+	*   openai.responses({ user: /Report Ingestion/ }, GATEWAY)
+	*/
+	responses(filter, url) {
+		return {
+			adapter: "openai",
+			method: "POST",
+			url: url ?? OPENAI_RESPONSES_URL,
+			match: filter ? ({ body }) => matchesResponsesFilter(body, filter) : void 0,
+			wrap: buildResponsesReply
+		};
+	},
+	/**
+	* Response: wrap data in Chat Completions format.
+	*
+	* @example
+	*   openai.reply({ categories: ['TECH'] })
+	*/
+	reply: buildChatReply,
+	/** Response: return an OpenAI error. */
+	error(status, message) {
+		return {
+			status,
+			body: { error: {
+				message: message ?? `OpenAI error (${status})`,
+				type: status === 429 ? "rate_limit_error" : "api_error",
+				code: status === 429 ? "rate_limit_exceeded" : null
+			} }
+		};
+	},
+	/** Response: return malformed content. */
+	malformed(content) {
+		return buildChatReply(content);
+	},
+	/** Response: simulate a timeout. */
+	timeout() {
+		return {
+			status: 200,
+			body: {},
+			delay: 3e4
+		};
+	}
+};
 //#endregion
-//#region src/spec/legacy-e2e.ts
+//#region src/core/contracts/contract.ts
 /**
-* Create an E2E specification runner.
-* Starts full docker compose stack. App URL and database auto-detected.
+* Declare an intercept contract. Identity function — its value is the
+* enforced shape and the naming convention:
+*
+* @example
+*   // specs/api/reports/contracts/classify-article.openai.ts
+*   import { defineContract, openai } from '@jterrazz/test';
+*
+*   export default defineContract({
+*       trigger: openai.responses({ user: /Report Ingestion/, tools: ['classify'] }),
+*       response: openai.reply({ categories: ['TECH'] }),
+*   });
+*
+*   // Dynamic — the response is computed from the observed request:
+*   export default defineContract({
+*       trigger: http.post('https://api.example.com/echo'),
+*       response: (request) => http.json({ received: request.body }),
+*   });
+*
+*   // specs/api/reports/reports.test.ts
+*   import classifyArticle from '../../spec/intercept/contracts/classify-article.openai.js';
+*
+*   const result = await jobs.intercept(classifyArticle).trigger('report-ingestion');
 */
-async function e2e(options = {}) {
-	const orchestrator = new Orchestrator({
-		mode: "e2e",
-		root: resolveProjectRoot(options.root),
-		services: []
-	});
-	await orchestrator.startCompose();
-	const appUrl = orchestrator.getAppUrl();
-	if (!appUrl) throw new Error("E2E: could not detect app URL from compose. Ensure an app service with ports is defined.");
-	const database = orchestrator.getDatabase() ?? void 0;
-	const databases = orchestrator.getDatabases();
-	const runner = createSpecificationRunner({
-		database,
-		databases: databases.size > 0 ? databases : void 0,
-		server: new FetchAdapter(appUrl)
-	});
-	runner.cleanup = () => orchestrator.stopCompose();
-	runner.orchestrator = orchestrator;
-	return runner;
+function defineContract(contract) {
+	return contract;
 }
 //#endregion
-//#region src/spec/legacy-integration.ts
+//#region src/vitest/mock-of.ts
 /**
-* Create an integration specification runner.
-* Starts infra containers via testcontainers, app runs in-process.
+* Create a deep mock proxy for a given type.
+* Wraps `vitest-mock-extended`'s `mockDeep` for convenient port mocking.
 */
-async function integration(options) {
-	const orchestrator = new Orchestrator({
-		mode: "integration",
-		root: resolveProjectRoot(options.root),
-		services: options.services
-	});
-	await orchestrator.start();
-	const app = options.app();
-	const database = orchestrator.getDatabase() ?? void 0;
-	const databases = orchestrator.getDatabases();
-	const runner = createSpecificationRunner({
-		database,
-		databases: databases.size > 0 ? databases : void 0,
-		server: new HonoAdapter(app)
-	});
-	runner.cleanup = () => orchestrator.stop();
-	runner.orchestrator = orchestrator;
-	return runner;
-}
+const mockOf = mockDeep;
+//#endregion
+//#region src/vitest/mock-of-date.ts
+/**
+* Freeze or reset the global Date for deterministic time-dependent tests.
+* Wraps the `mockdate` package.
+*/
+const mockOfDate = MockDatePackage;
+//#endregion
+//#region src/index.ts
+registerContainerIntegrations({
+	createComposeStack: (composeFile, projectName) => new ComposeStackAdapter(composeFile, projectName),
+	createContainer: (options) => new TestcontainersAdapter(options),
+	parseComposeFile
+});
+registerComposeServiceFactory("postgres", (service) => postgres({
+	composeService: service.name,
+	env: service.environment
+}));
+registerComposeServiceFactory("redis", (service) => redis({ composeService: service.name }));
 //#endregion
-export { DirectoryAccessor, DockerAssertion, ExecAdapter, FetchAdapter, HonoAdapter, Orchestrator, ResponseAccessor, SpecificationBuilder, SpecificationResult, TableAssertion, app, cli, command, createSpecificationRunner, dockerContainer, e2e, grep, integration, mockOf, mockOfDate, normalizeOutput, postgres, redis, spec, sqlite, stack, stripAnsi };
-
-//# sourceMappingURL=index.js.map
+export { BaseResult, CliResult, ContainerAccessor, DirectoryAccessor, FilesystemAccessor, HttpResult, JsonAccessor, Matcher, Orchestrator, ResponseAccessor, TableAccessor, TextAccessor, anthropic, defineContract, findContainersByLabel, http, inspectContainer, match, mockOf, mockOfDate, openai, postgres, redis, removeContainers, specification, sqlite, text };