@jterrazz/test 10.1.0 → 12.0.0

package/dist/index.js

@@ -1,6 +1,7 @@
-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 { i as match, n as Matcher, t as CaptureScope } from "./match.js";
+import { a as isContract, c as mergeTextPreservingPlaceholders, d as structuralSubset, f as textEquals, i as defineContracts, l as renderExpected, n as contractsOf, o as isContracts, r as defineContract, s as mergePreservingPlaceholders, t as ContractQueue, u as structuralEquals } from "./queue.js";
+import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parse } from "yaml";
 import { execFile, execSync, spawn, spawnSync } from "node:child_process";
 import { Client } from "pg";
@@ -11,6 +12,7 @@ import { createServer } from "node:http";
 import { createServer as createServer$1 } from "node:net";
 import { promisify } from "node:util";
 import Database from "better-sqlite3";
+import { createHash } from "node:crypto";
 import { mockDeep } from "vitest-mock-extended";
 import MockDatePackage from "mockdate";
 //#region src/core/specification/shared/registry.ts
@@ -520,298 +522,6 @@ function isJsonLike(text) {
 	}
 }
 //#endregion
-//#region src/core/matching/structural.ts
-/**
-* 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.
-*/
-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);
-		}
-	}
-}
-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 source = "";
-	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;
-		source += escapeRegExp(expected.slice(lastIndex, found.index));
-		source += `(${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
-		};
-	}
-	source += escapeRegExp(expected.slice(lastIndex));
-	return {
-		pattern: new RegExp(`^${source}$`),
-		refs,
-		single,
-		source
-	};
-}
-/**
-* Unanchored regex source matching a fixture string — plain text escaped
-* verbatim, each `{{token}}` expanded to its embedded grammar. Used to route
-* declared `.http` intercept paths (`/articles/{{uuid}}`) as URL patterns.
-*/
-function placeholderPatternSource(expected) {
-	return parsePlaceholderString(expected, new CaptureScope()).source;
-}
-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/core/specification/shared/reporter.ts
 const GREEN = "\x1B[32m";
 const RED = "\x1B[31m";
@@ -1081,13 +791,55 @@ var FilesystemAccessor = class {
 };
 //#endregion
 //#region src/core/specification/shared/caller.ts
+/** Sibling module tests are callers, not internals (CONVENTIONS I2). */
+const TEST_FILE = /\.test\.[cm]?[jt]s$/;
+/** Where this very module sits inside the framework's SOURCE tree. */
+const SOURCE_LOCATION = join("core", "specification", "shared");
+/** The real path of `path`, or `path` itself when it cannot be resolved. */
+function realPath(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
 /**
 * Directory of the running framework module itself. From the built package
 * this is `<package root>/dist`, whatever the resolution path — including a
 * `file:` link, where the real path carries neither `node_modules` nor
 * `/src/…` and would otherwise be mistaken for a caller frame.
 */
-const FRAMEWORK_DIR = dirname(fileURLToPath(import.meta.url));
+const FRAMEWORK_DIR = realPath(dirname(fileURLToPath(import.meta.url)));
+/**
+* The directory holding the framework's OWN modules: `<package>/dist` for a
+* built install (everything is bundled there), `<repo>/src` when the framework
+* runs from source — this module's known location inside that tree is what
+* tells the two apart.
+*/
+const FRAMEWORK_TREE = FRAMEWORK_DIR.endsWith(`${sep}${SOURCE_LOCATION}`) ? resolve(FRAMEWORK_DIR, "../../..") : FRAMEWORK_DIR;
+/** Is `path` inside `directory` (strictly — a directory is not inside itself)? */
+function isInside(directory, path) {
+	const rest = relative(directory, path);
+	return rest !== "" && !rest.startsWith("..") && !isAbsolute(rest);
+}
+/**
+* Is this stack frame a module of the framework itself, rather than of the code
+* calling it?
+*
+* Answered by IDENTITY: the frame is inside the framework's own directory.
+* Answering it by substring — `/src/core/`, `/src/integrations/`, `/src/vitest/`
+* — was answering a different question, "does this path look like the framework's
+* layout", and a consumer that happens to have its own `src/core/` matched it.
+* Its files were then skipped as framework internals, and fixture resolution
+* anchored on the wrong directory (or fell through to the cwd) with nothing
+* reported.
+*
+* @internal
+*/
+function isFrameworkFrame(filePath, frameworkTree = FRAMEWORK_TREE) {
+	if (TEST_FILE.test(filePath)) return false;
+	return isInside(realPath(frameworkTree), realPath(filePath));
+}
 /**
 * Detect the directory of the first stack frame that lives outside this
 * package. Used to anchor fixture resolution (`seeds/`, `requests/`,
@@ -1104,7 +856,7 @@ function getCallerDir() {
 		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;
+		if (isFrameworkFrame(filePath)) continue;
 		return resolve(filePath, "..");
 	}
 	return process.cwd();
@@ -1990,128 +1742,6 @@ async function registerMatchers() {
 	}
 }
 //#endregion
-//#region src/core/http-files/intercept-file.ts
-/** Split a declared path into its pathname and query halves — never through
-* `new URL()`, which would percent-encode `{{token}}` braces away. */
-function splitPath(path) {
-	const separator = path.indexOf("?");
-	if (separator === -1) return {
-		pathname: path,
-		query: new URLSearchParams()
-	};
-	return {
-		pathname: path.slice(0, separator),
-		query: new URLSearchParams(path.slice(separator + 1))
-	};
-}
-/**
-* Parse an `intercepts/*.http` file into its declared exchanges. Malformed
-* files refuse with the exchange number and the expected shape.
-*/
-function parseInterceptFile(content, fileName) {
-	const segments = content.split(/^###.*$/m).map((segment) => segment.trim()).filter((segment) => segment.length > 0);
-	if (segments.length === 0) throw new Error(`${fileName}: no exchanges found — expected "###"-separated request/response pairs`);
-	return segments.map((segment, index) => {
-		const ordinal = index + 1;
-		const lines = segment.split(/\r?\n/);
-		const statusIndex = lines.findIndex((line) => /^HTTP\/1\.1\s/.test(line.trim()));
-		if (statusIndex === -1) throw new Error(`${fileName}: exchange ${ordinal} has no response block — expected an "HTTP/1.1 <status>" line after the request`);
-		const request = parseRequestFile(lines.slice(0, statusIndex).join("\n"), fileName);
-		if (request.body !== void 0) throw new Error(`${fileName}: exchange ${ordinal} declares a request body — matching is method + path + headers only`);
-		const response = parseResponseFile(lines.slice(statusIndex).join("\n"), fileName);
-		const status = Number(response.status);
-		if (!Number.isInteger(status)) throw new Error(`${fileName}: exchange ${ordinal} has a non-numeric status "${response.status}" — an intercept file states the stubbed reply, not an expectation`);
-		return {
-			request: {
-				headers: request.headers,
-				method: request.method,
-				path: request.path
-			},
-			response: {
-				body: response.body,
-				hasBody: response.hasBody,
-				headers: response.headers,
-				status
-			}
-		};
-	});
-}
-/** Token-aware comparison of one declared value against an observed one. */
-function valueMatches(declared, observed) {
-	return textEquals(declared, observed, new CaptureScope());
-}
-/**
-* Does an observed request satisfy a declared exchange request? Method exact,
-* pathname exact (`{{token}}` segments match structurally), declared query
-* params and headers subset-match — extras on the observed side are ignored.
-*/
-function exchangeMatches(declared, observed) {
-	if (declared.method !== observed.method.toUpperCase()) return false;
-	const { pathname, query } = splitPath(declared.path);
-	let observedUrl;
-	try {
-		observedUrl = new URL(observed.url, "http://stub.invalid");
-	} catch {
-		return false;
-	}
-	if (!valueMatches(pathname, observedUrl.pathname) && !valueMatches(pathname, safeDecode(observedUrl.pathname))) return false;
-	for (const key of new Set(query.keys())) {
-		const observedValues = observedUrl.searchParams.getAll(key);
-		if (!query.getAll(key).every((value) => observedValues.some((actual) => valueMatches(value, actual)))) return false;
-	}
-	return Object.entries(declared.headers).every(([name, value]) => {
-		const actual = observed.headers[name.toLowerCase()];
-		return actual !== void 0 && valueMatches(value, actual);
-	});
-}
-/** Decode percent-escapes, falling back to the raw text on malformed input. */
-function safeDecode(text) {
-	try {
-		return decodeURIComponent(text);
-	} catch {
-		return text;
-	}
-}
-/**
-* A URL pattern routing any-origin requests whose pathname is the declared
-* one — `{{token}}` segments expanded to their grammars. Deliberately no
-* wider than {@link exchangeMatches}: the predicate stays the authority.
-*/
-function urlPatternOf(path) {
-	const { pathname } = splitPath(path);
-	return new RegExp(String.raw`^https?:\/\/[^/?#]+${placeholderPatternSource(pathname)}(?:\?[^#]*)?(?:#.*)?$`);
-}
-/**
-* Convert parsed exchanges into generic-http intercept entries for the MSW
-* engine — each exchange becomes one FIFO-consumed contract (CONVENTIONS D7
-* strictness applies unchanged on api/jobs chains).
-*/
-function interceptEntriesOf(exchanges) {
-	return exchanges.map((exchange) => {
-		return {
-			response: {
-				body: exchange.response.hasBody ? exchange.response.body : null,
-				headers: Object.keys(exchange.response.headers).length > 0 ? exchange.response.headers : void 0,
-				status: exchange.response.status
-			},
-			trigger: {
-				adapter: "http",
-				match: (request) => exchangeMatches(exchange.request, {
-					headers: request.headers,
-					method: exchange.request.method,
-					url: request.url
-				}),
-				method: exchange.request.method,
-				url: urlPatternOf(exchange.request.path),
-				wrap: (data) => ({
-					body: data,
-					status: 200
-				})
-			}
-		};
-	});
-}
-//#endregion
 //#region src/core/specification/api/result.ts
 /** Result from an HTTP action (.request(), .get(), .post(), .put(), .delete()). */
 var HttpResult = class extends BaseResult {
@@ -2410,11 +2040,10 @@ function copyPlan(path, testDir, workDir) {
 * only surfaces the methods that make sense for it.
 */
 var SpecificationBuilder = class {
-	backendExchanges = [];
 	commandEnv = {};
 	config;
+	contracts = [];
 	fixtures = [];
-	intercepts = [];
 	requestHeaders = {};
 	seeds = [];
 	testDir;
@@ -2488,57 +2117,21 @@ var SpecificationBuilder = class {
 		};
 		return this;
 	}
-	intercept(triggerOrContracts, maybeResponse) {
+	intercept(requestOrContracts, maybeResponse) {
 		if (this.config.interceptDisabledReason) throw new Error(`.intercept(): ${this.config.interceptDisabledReason}`);
-		if (typeof triggerOrContracts === "string") return this.interceptFile(triggerOrContracts);
-		if (Array.isArray(triggerOrContracts)) {
-			for (const contract of triggerOrContracts) this.registerIntercept(contract);
-			return this;
-		}
-		this.registerIntercept(triggerOrContracts, maybeResponse);
-		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
-		});
-	}
-	/**
-	* Register the exchanges of an `intercepts/<name>.http` file — flat in
-	* the calling test's `intercepts/` directory, the same resolution
-	* `.seed()` / `.request()` use. Website/mobile chains feed the declared
-	* stub backend; api/jobs chains feed the MSW engine (same contract list).
-	*/
-	interceptFile(file) {
-		if (!file.endsWith(".http")) throw new Error(`.intercept(): a single string argument must name an intercepts/*.http file (e.g. 'two-events.http'), got '${file}'`);
-		const stubFacet = this.config.baseUrl !== void 0 || this.config.device !== void 0;
-		if (stubFacet && !this.config.backend) {
+		if ((this.config.baseUrl !== void 0 || this.config.device !== void 0) && !this.config.backend) {
 			const facet = this.config.device === void 0 ? "website" : "mobile";
-			throw new Error(`.intercept(): this runner has no declared backend — add \`backend\` to the specification options (specification.${facet}({ …, backend: { … } })) so the chain's .http intercepts have a stub to serve them.`);
+			throw new Error(`.intercept(): this runner has no declared backend — add \`backend\` to the specification options (specification.${facet}({ …, backend: { … } })) so the chain's contracts have a stub to serve them.`);
 		}
-		const exchanges = parseInterceptFile(readFileSync(resolve(this.testDir, "intercepts", file), "utf8"), `intercepts/${file}`);
-		if (stubFacet) {
-			this.backendExchanges.push(...exchanges);
+		if (Array.isArray(requestOrContracts) || isContracts(requestOrContracts) || isContract(requestOrContracts)) {
+			this.contracts.push(...contractsOf(requestOrContracts));
 			return this;
 		}
-		this.intercepts.push(...interceptEntriesOf(exchanges));
+		if (maybeResponse === void 0) throw new Error(".intercept(): a bare request needs its response — pass a contract (defineContract({ request, response })) or the inline pair .intercept(request, response).");
+		this.contracts.push({
+			request: requestOrContracts,
+			response: maybeResponse
+		});
 		return this;
 	}
 	/**
@@ -2715,11 +2308,11 @@ var SpecificationBuilder = class {
 			cpSync(src, dest, { recursive: true });
 		}
 		let registration = null;
-		if (this.intercepts.length > 0) {
-			const { registerIntercepts } = await import("./intercept.js");
-			registration = await registerIntercepts(this.intercepts);
+		if (this.config.backend) this.config.backend.beginChain(this.contracts);
+		else if (this.contracts.length > 0) {
+			const { registerContracts } = await import("./intercept.js");
+			registration = await registerContracts(this.contracts);
 		}
-		this.config.backend?.beginChain(this.backendExchanges);
 		try {
 			const value = await action();
 			const violation = registration?.violation() ?? this.config.backend?.violation();
@@ -2895,6 +2488,14 @@ var SpecificationBuilder = class {
 		});
 	}
 };
+/**
+* The facet-level `.intercept()`: both overloads forwarded to a fresh chain.
+* The pair form is recognised by its second argument — a bare
+* {@link ContractRequest} never arrives alone.
+*/
+function interceptOn(start) {
+	return (contractsOrRequest, response) => response === void 0 ? start().intercept(contractsOrRequest) : start().intercept(contractsOrRequest, response);
+}
 function withDockerTestRunId(config) {
 	if (config.dockerConfig && !config.dockerTestRunId) return {
 		...config,
@@ -2912,7 +2513,7 @@ function createApiFacet(config) {
 		delete: (path) => start().delete(path),
 		get: (path) => start().get(path),
 		headers: (headers) => start().headers(headers),
-		intercept: (triggerOrContracts, response) => Array.isArray(triggerOrContracts) || typeof triggerOrContracts === "string" ? start().intercept(triggerOrContracts) : start().intercept(triggerOrContracts, response),
+		intercept: interceptOn(start),
 		post: (path, body) => start().post(path, body),
 		put: (path, body) => start().put(path, body),
 		request: (file) => start().request(file),
@@ -2925,7 +2526,7 @@ function createApiFacet(config) {
 function createJobsFacet(config) {
 	const start = () => new SpecificationBuilder(config, getCallerDir());
 	return {
-		intercept: (triggerOrContracts, response) => Array.isArray(triggerOrContracts) || typeof triggerOrContracts === "string" ? start().intercept(triggerOrContracts) : start().intercept(triggerOrContracts, response),
+		intercept: interceptOn(start),
 		seed: (file, options) => start().seed(file, options),
 		trigger: (name) => start().trigger(name)
 	};
@@ -2938,7 +2539,7 @@ function createWebsiteFacet(config) {
 	return {
 		fetch: (path) => start().fetch(path),
 		headers: (headers) => start().headers(headers),
-		intercept: (file) => start().intercept(file),
+		intercept: interceptOn(start),
 		visit: (path, scenario) => start().visit(path, scenario)
 	};
 }
@@ -2948,7 +2549,7 @@ function createWebsiteFacet(config) {
 function createMobileFacet(config) {
 	const start = () => new SpecificationBuilder(config, getCallerDir());
 	return {
-		intercept: (file) => start().intercept(file),
+		intercept: interceptOn(start),
 		open: (deepLink, scenario) => start().open(deepLink, scenario)
 	};
 }
@@ -3025,7 +2626,7 @@ var Orchestrator = class {
 	constructor(options) {
 		this.services = options.services;
 		this.mode = options.mode;
-		this.root = options.root ?? process.cwd();
+		this.root = options.root;
 		this.projectName = options.projectName;
 	}
 	/**
@@ -3246,23 +2847,39 @@ var Orchestrator = class {
 };
 //#endregion
 //#region src/core/specification/shared/resolve.ts
+/** What makes a directory a project root — a manifest, or a test stack. */
+const ROOT_MARKERS = ["package.json", "docker/compose.test.yaml"];
+/**
+* The NEAREST ancestor of `startDir` (itself included) carrying a root marker,
+* `undefined` when none does.
+*
+* Both markers are probed at each ancestor, in ONE walk. Two walks — the
+* compose file all the way up, then `package.json` all the way up — made the
+* further directory win: in a workspace, a `docker/compose.test.yaml` at the
+* repository root outranked the `package.json` of the very package being
+* tested, and every path the runner resolved was measured from the wrong unit.
+* The unit is the nearest thing that declares itself a project.
+*
+* The existence probe is injected so the lint layer can pass its cached one
+* (A9's `a9w-redundant-root` derives the same root, and must derive it the
+* same way).
+*/
+function findRoot(startDir, exists) {
+	let dir = startDir;
+	for (;;) {
+		if (ROOT_MARKERS.some((marker) => exists(resolve(dir, marker)))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return;
+		dir = parent;
+	}
+}
 /**
 * 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.
+* walk up to the first directory that carries `package.json` or
+* `docker/compose.test.yaml`; if none does, 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;
+	return findRoot(startDir, existsSync) ?? startDir;
 }
 /**
 * Resolve the project root for a specification. An explicit `root` option is
@@ -3651,21 +3268,20 @@ async function startJobs(options) {
 /**
 * The declared stub backend — a small `node:http` server the website and
 * mobile runners start when their `backend` option is present. It serves the
-* exchanges the CURRENT chain declared via `.intercept('<name>.http')`:
-* one chain = one terminal action, and the stub resets between chains the
-* way databases do.
+* contracts the CURRENT chain declared via `.intercept(...)`: one chain = one
+* terminal action, and the stub resets between chains the way databases do.
 *
-* Matching is the `intercepts/*.http` grammar (`exchangeMatches`), with the
-* queue semantics a rendered app needs: same-route entries consume FIFO, and
-* once a route's queue is exhausted its LAST entry stays sticky — a page
-* re-fetching the same endpoint (re-render, retry) replays the final reply
-* instead of failing an honest screen.
+* Selection is the shared {@link ContractQueue} — the same first-matching,
+* `times`-aware queue the MSW engine runs on api/jobs chains. A contract
+* without `times` keeps replying (re-render, retry); `times: n` is spent after
+* n serves.
 *
 * Strictness is the `external: 'block'` analog (CONVENTIONS D7 in spirit): a
-* request matching no declared exchange is answered 501 and RECORDED; once
-* the chain declared at least one intercept, the terminal action throws an
-* error enumerating every unmatched request. Chains with zero intercepts
-* leave the stub unguarded — mirroring how MSW stays off without them.
+* request matching no contract is answered 501 and RECORDED; once the chain
+* declared at least one contract, the terminal action throws an error
+* enumerating every unmatched request — and every `required` contract that was
+* never requested. Chains with zero contracts leave the stub unguarded —
+* mirroring how MSW stays off without them.
 *
 * Every response (including the 501 and the OPTIONS preflight) carries
 * permissive CORS headers — a website's client-side fetches are cross-origin
@@ -3674,11 +3290,10 @@ async function startJobs(options) {
 const CORS_METHODS = "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS";
 const PREFLIGHT_MAX_AGE = "600";
 var StubBackend = class {
-	consumed = [];
-	entries = [];
-	/** Guarded once the current chain declared at least one intercept. */
+	/** Guarded once the current chain declared at least one contract. */
 	guarded = false;
 	options;
+	queue = new ContractQueue([]);
 	server = null;
 	unmatchedRequests = /* @__PURE__ */ new Map();
 	url = "";
@@ -3711,26 +3326,27 @@ var StubBackend = class {
 		});
 	}
 	/**
-	* Arm the stub for one chain: the declared exchanges replace the previous
-	* chain's wholesale, consumption restarts, and the unmatched log clears —
+	* Arm the stub for one chain: the declared contracts replace the previous
+	* chain's wholesale, the queue restarts, and the unmatched log clears —
 	* the reset-between-chains databases already follow.
 	*/
-	beginChain(exchanges) {
-		this.consumed = exchanges.map(() => false);
-		this.entries = exchanges;
-		this.guarded = exchanges.length > 0;
+	beginChain(contracts) {
+		this.guarded = contracts.length > 0;
+		this.queue = new ContractQueue(contracts);
 		this.unmatchedRequests.clear();
 	}
 	/**
-	* The strict failure for the chain, or null — non-null when the chain
-	* declared at least one intercept AND an unmatched request was recorded.
-	* Enumerates every unmatched request (method, path, count) plus the
-	* declared routes, so the missing exchange writes itself.
+	* The strict failure for the chain, or null. Non-null when the chain
+	* declared at least one contract AND either an unmatched request was
+	* recorded, or a `required` contract was never satisfied. Enumerates every
+	* unmatched request (method, path, count) plus the declared routes, so the
+	* missing contract writes itself.
 	*/
 	violation() {
-		if (!this.guarded || this.unmatchedRequests.size === 0) return null;
+		if (!this.guarded) return null;
+		if (this.unmatchedRequests.size === 0) return this.queue.requiredError();
 		const unmatched = [...this.unmatchedRequests.values()].map((entry) => `  - ${entry.method} ${entry.path}${entry.count > 1 ? ` (${entry.count} times)` : ""}`).join("\n");
-		return /* @__PURE__ */ new Error(`Unmatched request(s) hit the declared backend during the chain:\n${unmatched}\nDeclared exchanges:\n${this.describeRoutes()}\nEvery backend request of a chain that declares intercepts must match one — add an exchange for it to the chain's intercepts/*.http file.`);
+		return /* @__PURE__ */ new Error(`Unmatched request(s) hit the declared backend during the chain:\n${unmatched}\nDeclared contracts:\n${this.describeRoutes()}\nEvery backend request of a chain that declares contracts must match one — add a contract for it to the chain's composite.`);
 	}
 	corsHeaders(request) {
 		return {
@@ -3741,10 +3357,11 @@ var StubBackend = class {
 		};
 	}
 	describeRoutes() {
-		if (this.entries.length === 0) return "  (no exchanges declared)";
-		return this.entries.map((entry, i) => `  - ${entry.request.method} ${entry.request.path}${this.consumed[i] ? " (consumed)" : ""}`).join("\n");
+		const routes = this.queue.declaredRoutes();
+		if (routes.length === 0) return "  (no contracts declared)";
+		return routes.map((route) => `  - ${route}`).join("\n");
 	}
-	handle(request, response) {
+	async handle(request, response) {
 		const method = (request.method ?? "GET").toUpperCase();
 		const cors = this.corsHeaders(request);
 		if (method === "OPTIONS") {
@@ -3755,28 +3372,33 @@ var StubBackend = class {
 		const headers = {};
 		for (const [name, value] of Object.entries(request.headers)) if (typeof value === "string") headers[name.toLowerCase()] = value;
 		const url = request.url ?? "/";
-		const entry = this.take({
+		const observed = {
+			body: await readBody(request),
 			headers,
 			method,
 			url
-		});
-		if (!entry) {
+		};
+		const contract = this.queue.take(observed);
+		if (!contract) {
 			this.record(method, url);
 			response.writeHead(501, {
 				...cors,
 				"content-type": "application/json"
 			});
 			response.end(JSON.stringify({
-				declared: this.entries.map((declared) => `${declared.request.method} ${declared.request.path}`),
-				error: `@jterrazz/test declared backend: no exchange matches ${method} ${url}`
+				declared: this.queue.declaredRoutes(),
+				error: `@jterrazz/test declared backend: no contract matches ${method} ${url}`
 			}));
 			return;
 		}
-		const { body, hasBody, status } = entry.response;
-		if (!hasBody) {
+		const reply = typeof contract.response === "function" ? contract.response(observed) : contract.response;
+		if (reply.delay) await new Promise((resolve) => setTimeout(resolve, reply.delay));
+		const status = reply.status ?? 200;
+		const { body } = reply;
+		if (body === null || body === void 0) {
 			response.writeHead(status, {
 				...cors,
-				...entry.response.headers
+				...reply.headers
 			});
 			response.end();
 			return;
@@ -3786,7 +3408,7 @@ var StubBackend = class {
 		response.writeHead(status, {
 			...cors,
 			"content-type": contentType,
-			...entry.response.headers
+			...reply.headers
 		});
 		response.end(payload);
 	}
@@ -3800,25 +3422,19 @@ var StubBackend = class {
 			path
 		});
 	}
-	/**
-	* FIFO with a sticky tail: the first unconsumed matching exchange is
-	* consumed; when every matching exchange is spent, the LAST one keeps
-	* replying.
-	*/
-	take(observed) {
-		let sticky = null;
-		for (let i = 0; i < this.entries.length; i++) {
-			const entry = this.entries[i];
-			if (!exchangeMatches(entry.request, observed)) continue;
-			if (!this.consumed[i]) {
-				this.consumed[i] = true;
-				return entry;
-			}
-			sticky = entry;
-		}
-		return sticky;
-	}
 };
+/** Read the request body — parsed JSON when it is JSON, raw text otherwise. */
+async function readBody(request) {
+	const chunks = [];
+	for await (const chunk of request) chunks.push(chunk);
+	const raw = Buffer.concat(chunks).toString("utf8");
+	if (raw.length === 0) return null;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return raw;
+	}
+}
 //#endregion
 //#region src/core/specification/website/serve.adapter.ts
 /** Grace period between SIGTERM and the SIGKILL escalation. */
@@ -4280,6 +3896,88 @@ const within = (scope, target) => ({
 });
 //#endregion
 //#region src/integrations/sqlite/sqlite.ts
+const SQLITE_FILE_HEADER = Buffer.from("SQLite format 3\0");
+/**
+* Whether `path` looks like a usable SQLite database file: it exists, is at
+* least as long as the format header, and begins with the SQLite magic
+* bytes. Does not validate anything beyond the header — good enough to
+* reject a 0-byte or truncated leftover without opening the file.
+*/
+function isValidSqliteTemplate(path) {
+	if (!existsSync(path)) return false;
+	let fd;
+	try {
+		fd = openSync(path, "r");
+	} catch {
+		return false;
+	}
+	try {
+		const header = Buffer.alloc(SQLITE_FILE_HEADER.length);
+		return readSync(fd, header, 0, header.length, 0) === SQLITE_FILE_HEADER.length && header.equals(SQLITE_FILE_HEADER);
+	} catch {
+		return false;
+	} finally {
+		closeSync(fd);
+	}
+}
+/** The invocation used when no `prismaSchema` is declared — Prisma discovers its own schema. */
+const PRISMA_PUSH = "npx prisma db push --force-reset";
+/**
+* The `prisma db push` command line for a `prismaSchema` option.
+*
+* The declared path is resolved against `process.cwd()` and handed to the CLI
+* as `--schema`. Without the flag Prisma falls back to its own discovery
+* (`prisma.config.ts` / `package.json#prisma` at the cwd), which silently
+* ignores the option: a repo whose config does not sit at the cwd then fails
+* with "Could not find Prisma Schema that is required for this command" — but
+* only on a machine without a cached template, so the divergence hides until CI.
+*
+* `null` (no option) keeps the bare invocation, discovery and all.
+*/
+function prismaPushCommand(prismaSchema) {
+	if (!prismaSchema) return PRISMA_PUSH;
+	return `${PRISMA_PUSH} --schema ${JSON.stringify(resolve(prismaSchema))}`;
+}
+/** Every template file this package writes carries that prefix, then its key. */
+const TEMPLATE_PREFIX = "jterrazz-test-sqlite-template";
+/**
+* The schema source as bytes: a file's content, or every file under a
+* directory in a stable order (a Prisma `schema/` folder is a directory). Each
+* entry carries its own path, so moving a schema changes the fingerprint.
+* Anything unreadable degrades to a marker rather than throwing — the path is
+* already in the key, so two projects still never collide.
+*/
+function schemaBytes(path) {
+	try {
+		if (statSync(path).isDirectory()) return readdirSync(path).sort().map((entry) => schemaBytes(join(path, entry))).join("\0");
+		return `${path}\0${readFileSync(path, "utf8")}`;
+	} catch {
+		return `${path}\0<unreadable>`;
+	}
+}
+/**
+* The name of the template database for a set of options — `<prefix>-<sha8>`,
+* the digest taken over the schema KIND, its resolved path and its content.
+*
+* The template lives in the machine-global OS tmpdir, so the name is the only
+* thing keeping two projects apart. A single fixed name meant the first project
+* to run on a machine built the template and every other project that day
+* silently inherited its tables — the file is header-valid, so the staleness
+* check accepts it and the schema never gets built. Keying on the schema makes
+* reuse mean "the same schema", which is what the cache was ever for.
+*/
+function sqliteTemplateName(options = {}) {
+	let fingerprint;
+	if (options.prismaSchema) {
+		const path = resolve(options.prismaSchema);
+		fingerprint = `prisma\0${path}\0${schemaBytes(path)}`;
+	} else if (options.init) {
+		const path = resolve(options.init);
+		fingerprint = `init\0${path}\0${schemaBytes(path)}`;
+	} else fingerprint = "empty";
+	const key = createHash("sha256").update(fingerprint).digest("hex").slice(0, 8);
+	return `${TEMPLATE_PREFIX}-${key}.sqlite`;
+}
 var SqliteHandle = class {
 	type = "sqlite";
 	composeName = null;
@@ -4293,7 +3991,9 @@ var SqliteHandle = class {
 	workerDbPath = "";
 	initSql;
 	prismaSchema;
+	options;
 	constructor(options = {}) {
+		this.options = options;
 		this.initSql = options.init ?? null;
 		this.prismaSchema = options.prismaSchema ?? null;
 	}
@@ -4305,22 +4005,27 @@ var SqliteHandle = class {
 	}
 	async healthcheck() {}
 	async initialize() {
-		this.templatePath = resolve(tmpdir(), "jterrazz-test-sqlite-template.sqlite");
+		this.templatePath = resolve(tmpdir(), sqliteTemplateName(this.options));
 		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));
 		}
 		if (existsSync(this.templatePath)) {
-			this.connectionString = `file:${this.templatePath}`;
-			this.started = true;
-			return;
+			if (isValidSqliteTemplate(this.templatePath)) {
+				this.connectionString = `file:${this.templatePath}`;
+				this.started = true;
+				return;
+			}
+			try {
+				unlinkSync(this.templatePath);
+			} catch {}
 		}
 		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", {
+			execSync(prismaPushCommand(this.prismaSchema), {
 				env: {
 					...process.env,
 					DATABASE_URL: `file:${this.templatePath}`,
@@ -4406,25 +4111,22 @@ function sqlite(options = {}) {
 	return new SqliteHandle(options);
 }
 //#endregion
+//#region src/core/contracts/filters.ts
+/** Does an observed text satisfy a declared {@link TextFilter}? */
+function matchesText(filter, actual) {
+	if (filter === void 0) return true;
+	if (typeof filter === "string") return actual === filter;
+	if (filter instanceof RegExp) return filter.test(actual);
+	return structuralEquals(filter, actual, new CaptureScope());
+}
+//#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 (!matchesText(filter.model, body?.model ?? "")) return false;
+	if (!matchesText(filter.system, typeof body?.system === "string" ? body.system : "")) return false;
+	const userMsg = body?.messages?.find((m) => m.role === "user")?.content ?? "";
+	if (!matchesText(filter.user, typeof userMsg === "string" ? userMsg : JSON.stringify(userMsg))) 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;
@@ -4456,7 +4158,7 @@ function buildReply(data) {
 */
 const anthropic = {
 	/**
-	* Trigger: match Messages API requests, optionally routed through a
+	* Request: match Messages API calls, 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.
@@ -4464,6 +4166,7 @@ const anthropic = {
 	* @example
 	*   anthropic.messages()
 	*   anthropic.messages({ system: /classify/ })
+	*   anthropic.messages({ user: buildPrompt() })   // string = EXACT equality
 	*   anthropic.messages({ user: /classify/ }, GATEWAY)
 	*/
 	messages(filter, url) {
@@ -4513,6 +4216,7 @@ function wrapJson(data) {
 		body: data
 	};
 }
+const TEXT_CONTENT_TYPE = "text/plain; charset=utf-8";
 function matchesBody(body, expected) {
 	if (typeof expected === "string") return (typeof body === "string" ? body : JSON.stringify(body ?? "")).includes(expected);
 	if (expected instanceof RegExp) {
@@ -4529,7 +4233,7 @@ function matchesEntries(expected, lookup) {
 	});
 }
 /**
-* Build the `match` predicate for an HTTP trigger filter, or `undefined` when
+* Build the `match` predicate for an HTTP request filter, or `undefined` when
 * no filter is supplied (fires on any URL/method match).
 */
 function buildMatch(filter) {
@@ -4540,7 +4244,7 @@ function buildMatch(filter) {
 		if (filter.query) {
 			let params;
 			try {
-				params = new URL(request.url).searchParams;
+				params = new URL(request.url, "http://contract.invalid").searchParams;
 			} catch {
 				return false;
 			}
@@ -4549,74 +4253,79 @@ function buildMatch(filter) {
 		return true;
 	};
 }
+function declare(method, url, filter) {
+	return {
+		adapter: "http",
+		match: buildMatch(filter),
+		method,
+		url,
+		wrap: wrapJson
+	};
+}
 /**
-* 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).
+* Generic HTTP contract helpers for any URL. The url is absolute (string or
+* RegExp), or a PATH FORM starting with `/` — `http.get('/articles/{{uuid}}')`
+* matches that path on ANY origin, which is what an app calling its own
+* backend needs. An optional {@link HttpContractFilter} narrows matching by
+* body, headers, or query — a request that hits the URL/method but fails the
+* filter counts as unmatched (strict contracts, CONVENTIONS D7).
 *
 * @example
-*   .intercept(http.get('https://api.example.com/data'), 'http/response.json')
-*   .intercept(http.post(URL, { body: { user: 'alice' } }), http.json({ ok: true }))
+*   defineContract({ request: http.get('/articles/{{uuid}}'), response: http.json(article) })
+*   defineContract({ request: http.post(URL, { body: { user: 'alice' } }), response: http.empty() })
 */
 const http = {
+	any(url, filter) {
+		return declare("*", url, filter);
+	},
+	delete(url, filter) {
+		return declare("DELETE", url, filter);
+	},
 	get(url, filter) {
-		return {
-			adapter: "http",
-			match: buildMatch(filter),
-			method: "GET",
-			url,
-			wrap: wrapJson
-		};
+		return declare("GET", url, filter);
+	},
+	patch(url, filter) {
+		return declare("PATCH", url, filter);
 	},
 	post(url, filter) {
-		return {
-			adapter: "http",
-			match: buildMatch(filter),
-			method: "POST",
-			url,
-			wrap: wrapJson
-		};
+		return declare("POST", url, filter);
 	},
 	put(url, filter) {
-		return {
-			adapter: "http",
-			match: buildMatch(filter),
-			method: "PUT",
-			url,
-			wrap: wrapJson
-		};
+		return declare("PUT", url, filter);
 	},
-	delete(url, filter) {
+	/** Response: a body-less reply (204 by default). */
+	empty(status = 204) {
 		return {
-			adapter: "http",
-			match: buildMatch(filter),
-			method: "DELETE",
-			url,
-			wrap: wrapJson
+			status,
+			body: null
 		};
 	},
-	any(url, filter) {
+	/** Response: an error status. Without a body, `{ error: 'HTTP <status>' }`. */
+	error(status, body) {
 		return {
-			adapter: "http",
-			match: buildMatch(filter),
-			method: "*",
-			url,
-			wrap: wrapJson
+			status,
+			body: body === void 0 ? { error: `HTTP ${status}` } : body
 		};
 	},
-	/** Response: simple JSON success. */
-	json(data, status = 200) {
+	/** Response: a JSON body (200 by default). */
+	json(body, init) {
 		return {
-			status,
-			body: data
+			status: init?.status ?? 200,
+			body,
+			delay: init?.delay,
+			headers: init?.headers
 		};
 	},
-	/** Response: error with message. */
-	error(status, message) {
+	/** Response: a text body, served as `text/plain` (200 by default). */
+	text(body, init) {
 		return {
-			status,
-			body: { error: message ?? `HTTP ${status}` }
+			status: init?.status ?? 200,
+			body,
+			delay: init?.delay,
+			headers: {
+				"content-type": TEXT_CONTENT_TYPE,
+				...init?.headers
+			}
 		};
 	}
 };
@@ -4625,21 +4334,9 @@ const http = {
 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 (!matchesText(filter.model, body?.model ?? "")) return false;
+	if (!matchesText(filter.system, body?.messages?.find((m) => m.role === "system")?.content ?? "")) return false;
+	if (!matchesText(filter.user, body?.messages?.find((m) => m.role === "user")?.content ?? "")) 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;
@@ -4648,23 +4345,11 @@ function matchesChatFilter(body, filter) {
 	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 (!matchesText(filter.model, body?.model ?? "")) return false;
+	const systemInput = body?.input?.find?.((m) => m.role === "system")?.content ?? "";
+	if (!matchesText(filter.system, body?.instructions || systemInput)) return false;
+	const userText = (body?.input ?? []).filter((m) => m.role === "user").map((m) => typeof m.content === "string" ? m.content : JSON.stringify(m.content)).join(" ");
+	if (!matchesText(filter.user, userText)) 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;
@@ -4728,12 +4413,15 @@ function buildResponsesReply(data) {
 */
 const openai = {
 	/**
-	* Trigger: match Chat Completions API requests.
+	* Request: match Chat Completions API calls. STRING filters mean EXACT
+	* equality (pass the app's own prompt builder); loosen deliberately with a
+	* RegExp or `match.includes(...)`.
 	*
 	* @example
-	*   openai.chat()                         // any chat call
-	*   openai.chat({ model: 'gpt-4o' })      // specific model
-	*   openai.chat({ system: /classify/ })    // system prompt match
+	*   openai.chat()                            // any chat call
+	*   openai.chat({ model: 'gpt-4o' })         // exact model
+	*   openai.chat({ system: buildPrompt() })   // exact system prompt
+	*   openai.chat({ system: /classify/ })      // pattern
 	*/
 	chat(filter) {
 		return {
@@ -4745,7 +4433,8 @@ const openai = {
 		};
 	},
 	/**
-	* Trigger: match Responses API requests (AI SDK v5+) with auto-wrapping.
+	* Request: match Responses API calls (AI SDK v5+) with auto-wrapping.
+	* String filters mean EXACT equality (see {@link openai.chat}).
 	* When used with a JSON file, the data is automatically wrapped in the
 	* Responses API envelope.
 	*
@@ -4796,35 +4485,6 @@ const openai = {
 	}
 };
 //#endregion
-//#region src/core/contracts/contract.ts
-/**
-* 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');
-*/
-function defineContract(contract) {
-	return contract;
-}
-//#endregion
 //#region src/vitest/mock-of.ts
 /**
 * Create a deep mock proxy for a given type.
@@ -4851,4 +4511,4 @@ registerComposeServiceFactory("postgres", (service) => postgres({
 }));
 registerComposeServiceFactory("redis", (service) => redis({ composeService: service.name }));
 //#endregion
-export { BaseResult, CliResult, ContainerAccessor, DirectoryAccessor, FetchResult, FilesystemAccessor, HttpResult, JsonAccessor, Matcher, Orchestrator, PageResult, ResponseAccessor, ScreenResult, TableAccessor, TextAccessor, anthropic, banner, button, complementary, content, contentinfo, defineContract, field, findContainersByLabel, form, heading, http, inspectContainer, link, main, match, mockOf, mockOfDate, navigation, openai, postgres, redis, region, removeContainers, search, specification, sqlite, testId, text, within };
+export { BaseResult, CliResult, ContainerAccessor, DirectoryAccessor, FetchResult, FilesystemAccessor, HttpResult, JsonAccessor, Matcher, Orchestrator, PageResult, ResponseAccessor, ScreenResult, TableAccessor, TextAccessor, anthropic, banner, button, complementary, content, contentinfo, defineContract, defineContracts, field, findContainersByLabel, form, heading, http, inspectContainer, link, main, match, mockOf, mockOfDate, navigation, openai, postgres, redis, region, removeContainers, search, specification, sqlite, testId, text, within };