@jterrazz/test 16.1.0 → 17.0.0

package/dist/stream.js

@@ -1,321 +0,0 @@
-import { t as CaptureScope } from "./match.js";
-import { A as placeholderPatternSource, D as hasPlaceholders, P as textEquals } from "./literate.js";
-//#region src/model/contracts/contract.ts
-/**
-* Declare one contract. Identity function — its value is the enforced shape
-* and the naming convention:
-*
-* @example
-*   // specs/api/reports/contracts/openai/classify-article.ts
-*   import { defineContract, openai } from '@jterrazz/test';
-*
-*   export default defineContract({
-*       request: openai.responses({ user: PROMPT, tools: ['classify'] }),
-*       response: openai.reply({ categories: ['TECH'] }),
-*   });
-*
-*   // Dynamic — the response is computed from the observed request:
-*   export default defineContract({
-*       request: http.post('https://api.example.com/echo'),
-*       response: (request) => http.json({ received: request.body }),
-*   });
-*/
-function defineContract(contract) {
-	return contract;
-}
-/** Is this a {@link Contracts} composite (rather than a contract or a list)? */
-function isContracts(value) {
-	return typeof value === "object" && value !== null && Array.isArray(value.contracts) && typeof value.with === "function";
-}
-/** Is this a single {@link Contract} (rather than a bare request half)? */
-function isContract(value) {
-	return typeof value === "object" && value !== null && "request" in value && "response" in value;
-}
-/**
-* The route a contract claims — method + the DECLARED url source. Two
-* contracts share a route when they would be written on the same line of a
-* declaration: same method, same url pattern (`.source` for a RegExp).
-*/
-function routeKeyOf(contract) {
-	const { method, url } = contract.request;
-	return url instanceof RegExp ? `${method} re:${url.source}` : `${method} str:${url}`;
-}
-/** Human-readable route of a contract — used in every failure message. */
-function describeRoute(contract) {
-	const { method, url } = contract.request;
-	return `${method === "*" ? "ANY" : method} ${url instanceof RegExp ? String(url) : url}`;
-}
-/** Flatten contracts, lists, and composites into one ordered list. */
-function flatten(items) {
-	const flat = [];
-	for (const item of items) if (Array.isArray(item)) flat.push(...flatten(item));
-	else if (isContracts(item)) flat.push(...item.contracts);
-	else flat.push(item);
-	return flat;
-}
-/**
-* Compose contracts into the artifact a test imports — it's contracts all the
-* way down: a composite may extend contracts, lists, and other composites,
-* recursively, order preserved.
-*
-* `.with(...)` derives a scenario: contracts whose route the overrides claim
-* are removed from the base, and the overrides are prepended. Under
-* first-match selection a more specific override (`/articles/gone-1`) also
-* wins over a generic base route (`/articles/{{uuid}}`) it does not replace.
-*
-* @example
-*   // contracts/newsroom.contracts.ts
-*   export default defineContracts(events, articleById);
-*   export const withArticleGone = (id: string) =>
-*       newsroom.with(articleGone(id));
-*/
-function defineContracts(...items) {
-	const contracts = Object.freeze(flatten(items));
-	return {
-		contracts,
-		with(...overrides) {
-			const added = flatten(overrides);
-			const claimed = new Set(added.map(routeKeyOf));
-			const kept = contracts.filter((contract) => !claimed.has(routeKeyOf(contract)));
-			return defineContracts([...added, ...kept]);
-		}
-	};
-}
-/** Normalize any accepted input into a flat contract list. */
-function contractsOf(input) {
-	return flatten([input]);
-}
-//#endregion
-//#region src/model/contracts/types.ts
-/**
-* The marker that tells a STREAMED body from a value that happens to be an
-* object. A body reaches three different engines (msw's server, msw's worker,
-* the `node:http` stub) and each of them serialises "an object" as JSON, so a
-* stream declared as a plain value arrives as `{}`. The tag is what each
-* engine recognises before it reaches for `JSON.stringify`.
-*/
-const STREAM_BODY = "@jterrazz/test:stream";
-/** Is this body a declared stream rather than a value to serialise? */
-function isStreamBody(body) {
-	return typeof body === "object" && body !== null && "kind" in body && body.kind === "@jterrazz/test:stream";
-}
-//#endregion
-//#region src/model/timing/pause.ts
-/**
-* One answer to "wait" — the only `setTimeout` the model owns.
-*
-* Two things in the framework genuinely have to wait: the spacing between the
-* pieces of a declared stream, and the poll behind `waitUntil`. Everything
-* else that waits is a spec doing it by hand, which is what J2 refuses. Stated
-* once so there is one place to look when time stops behaving.
-*/
-async function pause(ms) {
-	await new Promise((resolve) => {
-		setTimeout(resolve, ms);
-	});
-}
-//#endregion
-//#region src/model/contracts/queue.ts
-/**
-* The ONE contract queue — pure, engine-agnostic (no MSW, no node:http).
-* Both engines consume it: the MSW integration on api/jobs chains, and the
-* declared stub backend on website/mobile chains.
-*
-* Selection: the FIRST contract in declaration order that matches the observed
-* request and is not exhausted. A contract with no `times` is unlimited (a
-* re-render or a retry replays it); `times: n` is spent after n serves, so an
-* ordered sequence is written as finite contracts before an unlimited tail:
-* `[error500 ×3, ok]`.
-*
-* Strictness (CONVENTIONS D7): when nothing matches — including "everything
-* that matches is exhausted" — the engine answers 501, records the request,
-* and the chain fails with {@link ContractQueue.unmatchedError}. A chain that
-* declared zero contracts is not guarded at all (unchanged boundary).
-*/
-/** Base used to parse origin-relative observed URLs (`/events?x=1`). */
-const RELATIVE_BASE = "http://contract.invalid";
-/** Split a declared url into its base (origin+path, or path) and query halves.
-* Never through `new URL()`, which would percent-encode `{{token}}` braces. */
-function splitDeclared(url) {
-	const separator = url.indexOf("?");
-	if (separator === -1) return {
-		base: url,
-		query: new URLSearchParams()
-	};
-	return {
-		base: url.slice(0, separator),
-		query: new URLSearchParams(url.slice(separator + 1))
-	};
-}
-/** Decode percent-escapes, falling back to the raw text on malformed input. */
-function safeDecode(text) {
-	try {
-		return decodeURIComponent(text);
-	} catch {
-		return text;
-	}
-}
-/** Token-aware comparison of one declared value against an observed one. */
-function valueMatches(declared, observed) {
-	return textEquals(declared, observed, new CaptureScope());
-}
-/**
-* Does an observed URL satisfy a declared one? A RegExp tests the full URL; a
-* PATH FORM (`/articles/{{uuid}}`) ignores the origin; an absolute string
-* compares origin+pathname. In both string forms `{{token}}` segments compare
-* structurally and declared query params are a SUBSET of the observed ones.
-*/
-function urlMatches(declared, observed) {
-	if (declared instanceof RegExp) return declared.test(observed);
-	let url;
-	try {
-		url = new URL(observed, RELATIVE_BASE);
-	} catch {
-		return false;
-	}
-	const { base, query } = splitDeclared(declared);
-	const observedBase = base.startsWith("/") ? url.pathname : `${url.origin}${url.pathname}`;
-	const decodedBase = base.startsWith("/") ? safeDecode(url.pathname) : `${url.origin}${safeDecode(url.pathname)}`;
-	if (!valueMatches(base, observedBase) && !valueMatches(base, decodedBase)) return false;
-	for (const key of new Set(query.keys())) {
-		const observedValues = url.searchParams.getAll(key);
-		if (!query.getAll(key).every((value) => observedValues.some((actual) => valueMatches(value, actual)))) return false;
-	}
-	return true;
-}
-/**
-* Does an observed request satisfy a contract? Method (`*` matches any), URL,
-* then the contract's own `match` predicate (headers/query/body filters).
-*/
-function contractMatches(contract, request) {
-	const { match, method, url } = contract.request;
-	if (method !== "*" && method.toUpperCase() !== request.method.toUpperCase()) return false;
-	if (!urlMatches(url, request.url)) return false;
-	return match ? match(request) : true;
-}
-/**
-* The URL pattern an out-of-process router (MSW) must register so the request
-* REACHES the queue. Deliberately no narrower than {@link contractMatches} —
-* the predicate above stays the authority on what actually matches.
-*/
-function routePatternOf(declared) {
-	if (declared instanceof RegExp) return declared;
-	const { base } = splitDeclared(declared);
-	if (base.startsWith("/")) return new RegExp(String.raw`^https?:\/\/[^/?#]+${placeholderPatternSource(base)}(?:\?[^#]*)?(?:#.*)?$`, "u");
-	if (hasPlaceholders(base)) return new RegExp(String.raw`^${placeholderPatternSource(base)}(?:\?[^#]*)?(?:#.*)?$`, "u");
-	return base;
-}
-/** How a declared contract reads in a failure message: spent, served, or silent. */
-function stateOf({ contract, served }) {
-	const { times } = contract;
-	if (times !== void 0 && served >= times) return ` (exhausted after ${times})`;
-	return served === 0 ? "" : ` (served ${served} time(s))`;
-}
-var ContractQueue = class {
-	entries;
-	constructor(contracts) {
-		this.entries = contracts.map((contract) => ({
-			contract,
-			served: 0
-		}));
-	}
-	/** How many contracts the chain declared. */
-	get size() {
-		return this.entries.length;
-	}
-	/**
-	* Routes to register with an out-of-process router, deduped by pattern —
-	* two contracts on the same URL share one handler and one queue.
-	*/
-	get routes() {
-		const routes = /* @__PURE__ */ new Map();
-		for (const { contract } of this.entries) {
-			const url = routePatternOf(contract.request.url);
-			const key = String(url);
-			const route = routes.get(key) ?? {
-				methods: [],
-				url
-			};
-			if (!route.methods.includes(contract.request.method)) route.methods.push(contract.request.method);
-			routes.set(key, route);
-		}
-		return [...routes.values()];
-	}
-	/** The declared routes, in order — the enumeration a 501 body carries. */
-	declaredRoutes() {
-		return this.entries.map(({ contract }) => describeRoute(contract));
-	}
-	/**
-	* Serve the first contract in declaration order that matches and is not
-	* exhausted, or null when nothing matches (including "everything that
-	* matches is spent") — the strict-violation signal.
-	*/
-	take(request) {
-		for (const entry of this.entries) {
-			const { times } = entry.contract;
-			if (times !== void 0 && entry.served >= times) continue;
-			if (!contractMatches(entry.contract, request)) continue;
-			entry.served += 1;
-			return entry.contract;
-		}
-		return null;
-	}
-	/**
-	* The chain-end failure for contracts declared `required: true` that were
-	* never requested (or not exactly `times` times), or null when every
-	* requirement held.
-	*/
-	requiredError() {
-		const unmet = [];
-		for (const { contract, served } of this.entries) {
-			if (!contract.required) continue;
-			const { times } = contract;
-			if (times === void 0) {
-				if (served === 0) unmet.push(`  - ${describeRoute(contract)} — declared and required but never requested`);
-			} else if (served !== times) unmet.push(`  - ${describeRoute(contract)} — declared required with times: ${times} but was requested ${served} time(s)`);
-		}
-		if (unmet.length === 0) return null;
-		return /* @__PURE__ */ new Error(`Required contract(s) never satisfied during the chain:\n${unmet.join("\n")}\nA required contract states the call MUST happen — either the code no longer makes it, or the contract no longer describes it.`);
-	}
-	/**
-	* The strict failure for a request that matched no contract (CONVENTIONS
-	* D7): method + URL of the offending request, plus every declared contract
-	* and how often it was served.
-	*/
-	unmatchedError(method, url) {
-		const declared = this.entries.length === 0 ? "  (no contracts declared)" : this.entries.map((entry) => `  - ${describeRoute(entry.contract)}${stateOf(entry)}`).join("\n");
-		return /* @__PURE__ */ new Error(`Unmatched outgoing HTTP request during spec: ${method} ${url}\nDeclared contracts:\n${declared}\nEvery outgoing request of a chain that declares contracts must match one — add a contract for it (or raise its \`times\` when it is exhausted).`);
-	}
-};
-//#endregion
-//#region src/model/contracts/stream.ts
-/**
-* A declared stream, made real — ONE serialisation for all three engines.
-*
-* msw's server and msw's worker take a `ReadableStream` body verbatim
-* (https://mswjs.io/docs/http/mocking-responses/streaming) and the `node:http`
-* stub pipes one into its response, so what "arriving in pieces" MEANS —
-* the order, the spacing, the close after the last chunk — is stated here and
-* nowhere else. A second copy of it would be a second answer to "what does the
-* subject read", and the facets would drift.
-*/
-/**
-* The pieces of `body`, in order, `delayBetweenChunks` milliseconds apart,
-* closing after the last one.
-*/
-function toReadableStream(body) {
-	const encoder = new TextEncoder();
-	let index = 0;
-	return new ReadableStream({ async pull(controller) {
-		const chunk = body.chunks[index];
-		if (chunk === void 0) {
-			controller.close();
-			return;
-		}
-		if (body.delayBetweenChunks > 0 && index > 0) await pause(body.delayBetweenChunks);
-		index += 1;
-		controller.enqueue(encoder.encode(chunk));
-	} });
-}
-//#endregion
-export { isStreamBody as a, defineContracts as c, STREAM_BODY as i, isContract as l, ContractQueue as n, contractsOf as o, pause as r, defineContract as s, toReadableStream as t, isContracts as u };

package/dist/substring-warning.js

@@ -1,244 +0,0 @@
-//#region src/model/elements/ambiguity.ts
-/**
-* The ambiguity refusal — CONVENTIONS W3.
-*
-* A visit descriptor must designate exactly one element. Acting on "the
-* first match" is the failure mode this module exists to prevent: the spec
-* keeps passing while the visitor clicks something else, and nothing ever
-* reports it. So when a descriptor matches several elements the framework
-* refuses, and the refusal has to carry everything needed to fix it without
-* opening a browser — the descriptor in the caller's own vocabulary, every
-* candidate, and the concrete rewrites that would resolve it.
-*
-* Pure string building: it takes captured data and returns a message, so the
-* wording is unit-testable and the browser integration stays a thin adapter.
-*/
-/** `kind` → the constructor that builds it, so errors echo the caller's source. */
-const CONSTRUCTORS = {
-	banner: "banner",
-	button: "button",
-	complementary: "complementary",
-	contentinfo: "contentinfo",
-	dialog: "dialog",
-	field: "field",
-	form: "form",
-	heading: "heading",
-	link: "link",
-	listitem: "listitem",
-	main: "main",
-	navigation: "navigation",
-	option: "option",
-	region: "region",
-	row: "row",
-	search: "search",
-	status: "status",
-	table: "table",
-	testId: "testId",
-	text: "content"
-};
-/** The landmark a context string maps back to, for a copy-pasteable suggestion. */
-const CONTEXT_LANDMARKS = {
-	aside: "complementary()",
-	banner: "banner()",
-	complementary: "complementary()",
-	contentinfo: "contentinfo()",
-	footer: "contentinfo()",
-	form: "form()",
-	header: "banner()",
-	main: "main()",
-	nav: "navigation()",
-	navigation: "navigation()",
-	search: "search()"
-};
-/**
-* Render a descriptor as the source that would build it — `link('Articles')`,
-* `within(navigation(), link('Articles', { exact: false }))`. The error speaks
-* the vocabulary the author wrote, never playwright's — so the option appears
-* only when the AUTHOR stated one, whichever way.
-*/
-function formatElement(element) {
-	const bare = formatBare(element);
-	return element.scope ? `within(${formatElement(element.scope)}, ${bare})` : bare;
-}
-function formatBare(element) {
-	const args = [];
-	if (element.name !== void 0) args.push(JSON.stringify(element.name));
-	if (element.exact !== void 0) args.push(`{ exact: ${String(element.exact)} }`);
-	return `${CONSTRUCTORS[element.kind]}(${args.join(", ")})`;
-}
-/** `1. <a href="/articles">Articles</a>  in <nav>` — one evidence line per candidate. */
-function formatMatch(match, index) {
-	const attribute = match.detail ? ` ${quoteDetail(match)}` : "";
-	const named = match.accessibleName ? `  named ${JSON.stringify(match.accessibleName)}` : "";
-	const context = match.context ? `  in <${match.context}>` : "";
-	return `  ${index + 1}. <${match.tag}${attribute}>${match.text}</${match.tag}>${named}${context}`;
-}
-function quoteDetail(match) {
-	return `${match.tag === "a" ? "href" : "name"}=${JSON.stringify(match.detail)}`;
-}
-/** Each landmark the candidates sit in, and how many of them it holds. */
-function landmarkCounts(matches) {
-	const counts = /* @__PURE__ */ new Map();
-	for (const match of matches) {
-		const landmark = match.context === void 0 ? void 0 : CONTEXT_LANDMARKS[match.context];
-		if (landmark !== void 0) counts.set(landmark, (counts.get(landmark) ?? 0) + 1);
-	}
-	return [...counts].toSorted(([, a], [, b]) => a - b);
-}
-/**
-* The rewrites worth offering, in the order they should be tried. Scoping is
-* always available; `exact` only when it would actually narrow the set, and
-* the count it would leave is stated so a still-ambiguous suggestion never
-* reads as a fix.
-*/
-function formatFixes(element, matches) {
-	const fixes = [];
-	const narrowing = landmarkCounts(matches).filter(([, count]) => count < matches.length);
-	if (!element.scope) {
-		const [first, ...rest] = narrowing;
-		const alsoHere = rest.length > 0 ? `   [also here: ${rest.map(([name]) => name).join(", ")}]` : "";
-		fixes.push(first === void 0 ? `scope it       within(<a container holding only this one>, ${formatBare(element)})` : `scope it       within(${first[0]}, ${formatBare(element)})   [leaves ${first[1]} of ${matches.length}]${alsoHere}`);
-	}
-	if (element.exact === false && element.name !== void 0) {
-		const remaining = matches.filter((match) => match.text === element.name).length;
-		if (remaining > 0 && remaining < matches.length) fixes.push(`exact name     ${formatBare({
-			...element,
-			exact: true
-		})}   [leaves ${remaining} of ${matches.length}]`);
-	}
-	fixes.push("other element  a heading(), button() or field() may name one thing where this does not");
-	return fixes;
-}
-/**
-* The W3 refusal. A distinct class so the visit wrapper can recognize an
-* already-complete message and let it through instead of nesting it inside
-* `visit scenario failed: …`, which would print the whole thing twice.
-*/
-var AmbiguousElementError = class extends Error {
-	name = "AmbiguousElementError";
-};
-/**
-* Build the refusal thrown when a descriptor matches more than one element.
-*
-* @param options.element The descriptor as the caller wrote it.
-* @param options.matches Every candidate, in DOM order (already truncated).
-* @param options.url The page the visitor was on when it happened.
-*/
-function describeAmbiguity(options) {
-	const { element, matches, url } = options;
-	const fixes = formatFixes(element, matches).map((fix) => `  • ${fix}`);
-	return [
-		`Ambiguous element: ${formatElement(element)} matched ${matches.length} elements on ${url}.`,
-		"",
-		"A spec must designate exactly one element. Acting on the first match would let",
-		"this test keep passing while the visitor interacts with something else.",
-		"",
-		"Matched:",
-		...matches.map((match, index) => formatMatch(match, index)),
-		"",
-		"Disambiguate with one of:",
-		...fixes,
-		"",
-		"Docs: docs/13-elements.md#designating-exactly-one-element (CONVENTIONS W3)"
-	].join("\n");
-}
-//#endregion
-//#region src/model/elements/substring-warning.ts
-/**
-* The transitional warning for a name that matches only as a SUBSTRING.
-*
-* Until 16.0 a descriptor's name matched any element whose accessible name
-* CONTAINED it, so `link('Articles')` also designated "Read Articles" — and a
-* test could pass for years against the wrong element without anyone noticing,
-* because the wrong element was usually next to the right one. Exact is the
-* default now.
-*
-* A lint rule cannot carry this: whether a name matched whole or in part is a
-* fact about a RUN, and a verdict fed by a previous run's artefact is not
-* deterministic. So it is a runtime warning, printed by the adapter that did
-* the looking, at the moment it has both answers in hand — nothing found under
-* exact, something found under substring.
-*
-* It is printed ONCE per descriptor per process: a scenario that clicks the
-* same link in ten tests has one thing to fix, not ten lines to read.
-*/
-/** How long the window lasts, stated in the message itself. */
-const WINDOW = "through 16.x";
-/** Descriptors already reported in this process. */
-const reported = /* @__PURE__ */ new Set();
-/** The identity a descriptor is deduplicated by — kind, name, and its scope chain. */
-function identityOf(element) {
-	const own = `${element.kind}:${element.name ?? ""}`;
-	return element.scope === void 0 ? own : `${identityOf(element.scope)}>${own}`;
-}
-/**
-* Report that `element` designated nothing as a whole name, but would have
-* designated something as a substring. Returns whether a line was printed,
-* which is what the adapters' own tests assert on.
-*/
-function warnSubstringOnly(element, where, found) {
-	const identity = identityOf(element);
-	if (reported.has(identity)) return false;
-	reported.add(identity);
-	const spelling = found === void 0 ? "" : ` The name to write is '${found.replaceAll(/\s+/gu, " ").trim()}'.`;
-	console.warn(`@jterrazz/test: ${element.kind}('${element.name ?? ""}') matched nothing as a whole accessible name, and matched only as a SUBSTRING of a longer one (${where}).${spelling} Names are exact from 16.0: write the name in full, scope it with \`within(…)\`, or state \`{ exact: false }\` to keep the old behaviour. The substring is still resolved, with this warning, ${WINDOW}; gone in 17.0, where the same descriptor is simply not found.`);
-	return true;
-}
-/**
-* The descriptor to retry with, LEVEL by level, or `undefined` when nothing
-* would change.
-*
-* Every level of the chain is asked the same question the target is asked —
-* `within(button('Proof of authorship'), content('Verified'))` against a
-* button named "Proof of authorship Verified" failed on the SCOPE, and a
-* warning that only ever widened the target printed nothing at all. The chain
-* is walked outside-in and rebuilt as it goes, since an inner level's answer
-* is meaningless under a scope that designates nothing.
-*
-* A level that states an `exact` of its own is left alone: an author who wrote
-* `{ exact: false }` chose the substring, and one who wrote `{ exact: true }`
-* was already exact.
-*
-* Asked BEFORE the action, not after it fails: a verb waits its whole
-* actionability budget, which is the test's own budget, so a retry afterwards
-* never runs — the test is already over. The probes are counts, which wait for
-* nothing, and the common case (the name matches whole) costs one per level.
-*/
-async function widenedForWindow(element, where, probe) {
-	const chain = [];
-	for (let level = element; level; level = level.scope) chain.unshift(level);
-	let rebuilt;
-	let widened = false;
-	for (const level of chain) {
-		const candidate = {
-			...level,
-			...rebuilt === void 0 ? {} : { scope: rebuilt }
-		};
-		const loose = await widenedLevel(candidate, where, probe);
-		widened ||= loose !== void 0;
-		rebuilt = loose ?? candidate;
-	}
-	return widened ? rebuilt : void 0;
-}
-/**
-* The one level, widened and warned about, or `undefined` when it designates
-* something already, states its own `exact`, carries no name, or would
-* designate nothing either way.
-*/
-async function widenedLevel(candidate, where, probe) {
-	if (candidate.exact !== void 0 || candidate.name === void 0) return;
-	try {
-		if (await probe.count(candidate) > 0) return;
-		const loose = {
-			...candidate,
-			exact: false
-		};
-		if (await probe.count(loose) !== 1) return;
-		warnSubstringOnly(candidate, where, await probe.nameOf(loose));
-		return loose;
-	} catch {
-		return;
-	}
-}
-//#endregion
-export { formatElement as a, describeAmbiguity as i, widenedForWindow as n, AmbiguousElementError as r, warnSubstringOnly as t };

package/docs/01-architecture.md

@@ -1,95 +0,0 @@
-# 01 — Architecture
-
-What this package IS: one runner model behind six constructors, one chain that needs none, five source trees with declared edges, and seven channels through which its conventions are enforced — each row of the catalogue naming exactly one. The chapters that follow explain how to USE each facet; this one draws the lines they sit inside.
-
-| The shape                  | Held below                                                                       |
-| -------------------------- | -------------------------------------------------------------------------------- |
-| The runner model           | [The runner model](#the-runner-model) — constructor, handle, chain, result       |
-| The source trees           | [The five trees](#the-five-trees) — `model`, `facets`, `seams`, `runner`, `lint` |
-| How a convention is held   | [The seven enforcement channels](#the-seven-enforcement-channels)                |
-| What ships out of the tree | [What the tree publishes](#what-the-tree-publishes)                              |
-
-The rules themselves — what each family says, what a reviewer must judge — are the constitution, [18 — Conventions](18-conventions.md); their normative sentences are the generated catalogue, [19 — Linting](19-linting.md).
-
-## The runner model
-
-Every facet is the same four steps. A **constructor** takes options and returns a **handle**; the handle opens a **chain** of zero or more setups closed by exactly one terminal action; the action executes and resolves to a **typed result**; the result is asserted through vitest's `expect()`. Nothing else is public — there is no imperative escape hatch, because a spec that can do anything proves nothing in particular.
-
-Six constructors exist and the list is closed (`src/facets/specification.ts`):
-
-| Constructor                   | Handle destructures to             | Subject under test                               |
-| ----------------------------- | ---------------------------------- | ------------------------------------------------ |
-| `specification.api()`         | `{ api, cleanup, docker }`         | An HTTP API, built and served in this process    |
-| `specification.jobs()`        | `{ jobs, cleanup }`                | A background pipeline, triggered by name         |
-| `specification.cli()`         | `{ cli, cleanup, docker }`         | A command binary in a fresh temp directory       |
-| `specification.integration()` | `{ integration, cleanup, docker }` | A module against real services, or a golden      |
-| `specification.website()`     | `{ website, cleanup, url }`        | A rendered page — fetched, or driven in chromium |
-| `specification.mobile()`      | `{ mobile, cleanup, udid }`        | A native screen on an iOS simulator              |
-
-The asymmetry in that column is the model, not an oversight: `jobs` never spawns a container, so it is handed no `docker`; `website` and `mobile` drive a browser and a simulator rather than an orchestrated stack, so they carry neither.
-
-**One facet has no constructor**, and the same reason explains it: a rendered component starts nothing. `component` ([07 — Component specs](07-component.md)) is a chain the package exports directly — `component.intercept(…).render(<X />)` — so there is no handle to destructure and no `cleanup` to pass to `afterAll`. What every render of a project shares (the providers, the Vite pipeline, the viewport) is the PROJECT's, stated once by `component()` in `vitest.config.ts`.
-
-A runner is created **once per suite**, in a `*.specification.ts` file, and imported by the test files beside it. That split is what makes the container lifecycle affordable — one Postgres per suite, not one per test — and it is why `afterAll(cleanup)` belongs in the specification file and nowhere else.
-
-### The seam under the chain
-
-`SpecificationBuilder` (`src/model/chain/builder.ts`) holds the chain for every facet; each facet contributes its own setups and its own terminal actions on top. The infrastructure a chain needs is reached through **ports** — `src/model/ports/` declares eight of them (`browser`, `cli`, `container`, `database`, `device`, `isolation`, `server`, `service`) — and an integration implements one. So the chain knows "a database exists"; it never knows Postgres.
-
-Every seam is opened lazily rather than imported, and each one is an optional peer loaded by the one module that owns it: `playwright` for `.visit()`, `appium`/`webdriverio` for `.open()`, `@vitest/browser-playwright` + `vitest-browser-react` + `react` for `component.render()`, and — since 16.0 — `better-sqlite3`, `pg`, `redis` and `testcontainers` for the services a record declares. A project that tests no page, no component and no database installs none of them; `src/seams/peer.ts` owns the one message a missing peer produces, which names the facet that asked, the command, and under pnpm the `onlyBuiltDependencies` line a native binding needs.
-
-## The five trees
-
-The source tree is five trees with declared, one-directional edges. The map is not the linter's to assume — `i1-layer-boundaries` ships inert — so this package declares its own as `FRAMEWORK_LAYERS` in `oxlint.config.ts`, and that declaration is the enforced statement of what follows.
-
-| Tree      | May import                                                                                                                              | Holds                                                                                                                                                                                                                         |
-| --------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `model/`  | itself, the docker/process/yaml seams, the msw seam through two named lazy imports, `runner/update`, and each facet's `*.result` module | What every facet is made of: the chain and the orchestrator, the results and their accessors, the element vocabulary, the contracts and `intercept()`, the `{{token}}` engine, the goldens, the clock, the doubles, the ports |
-| `facets/` | `model/`, itself, the runner's project shape, and the one seam each constructor opens                                                   | Seven folders, the SAME four files in each: `<facet>.specification.ts` (the constructor), `<facet>.chain.ts`, `<facet>.result.ts`, `<facet>.project.ts` (the vitest helper), plus what is unique to the facet                 |
-| `seams/`  | its OWN external dependency, plus `model/` and the facet vocabulary an adapter projects into                                            | One folder per dependency: `postgres`, `redis`, `sqlite`, `testcontainers`, `docker`, `hono`, `playwright`, `vitest-browser`, `appium`, `msw`, `openai`, `anthropic`, `yaml`, `process`                                       |
-| `runner/` | `vitest`, `vite`, `@vitest/browser-playwright`, `model/`, `facets/`                                                                     | The CONFIG side of the runner coupling: the preset, update mode, the `literate()` plugin, the shape a node facet's project takes, and the project index                                                                       |
-| `lint/`   | itself, plus a short list of PURE `model/` modules                                                                                      | The tool-facing channel: the oxlint plugin, the conventions checker, the catalogue manifest and generator                                                                                                                     |
-
-**Every facet folder carries the same four files, whether or not it owns all four.** The setups and terminal actions of the six node facets are ONE builder, because a second copy of "declare a contract, seed a table, run the thing" is how two facets drift — so `api.chain.ts` and its five siblings are a named re-export of that builder rather than an implementation, and `jobs.result.ts` re-exports the shape the builder states. The shape is uniform so that a reader who has opened one facet has opened all seven; the re-export says, in the folder itself, which of the four a facet does not own.
-
-Three of those edges carry their reason in the declaration itself. `model/` reaches `seams/docker`, `seams/process` and the yaml parser because none of the three has a dependency of its own to leak, and it reaches each facet's `*.result` module because the ONE builder constructs all seven results — a value edge, stated rather than hidden. `lint/` reaches exactly the pure modules the runner also uses — the token list, the ground names, the root walk, the `<case>.spec.yaml` parser — so that the file the lint accepts is the file the runner runs, from ONE parser. And the runner is named in exactly TWO places outside a test, one per side of it: `runner/` for the config side — the preset, the project shape, the plugin — and `seams/vitest-browser/` for the page side, where the locators, the visitor, the golden commands and the page's own `vitest` primitives live. Swapping the runner would be a rewrite of those two folders and of nothing else; `model/` states what a render IS and never which runner performs it, which is why the layer map exempts that seam from the prod-import ban (F2) by name.
-
-The table's May-import column is a reading of `FRAMEWORK_LAYERS`, never a second statement of it: the declaration in `oxlint.config.ts` is what the linter enforces and what a change edits.
-
-There are TWO composition roots and neither names a layer. `src/index.ts` is node's: it wires the container integrations into the registry seam and re-exports the public surface. `src/browser/index.ts` is the page's, and `src/surface.ts` is what they agree on — see [What the tree publishes](#what-the-tree-publishes).
-
-## The seven enforcement channels
-
-A convention this package states is held by a **channel**, and every row of the catalogue names exactly one of seven. The guiding aim is that most enforcement is programmatic, not review-borne.
-
-- **statique** — the `jterrazz/*` oxlint plugin: one file per rule under `src/lint/rules/model/` or `src/lint/rules/<facet>/` — the tree the rule reaches, which is also the `facet` field of its manifest row — AST analysis, one diagnostic per file.
-- **upstream** — a convention an oxlint vitest-plugin rule already holds, set as an OPTION from the `testing` fragment rather than duplicated as a rule of ours ([ADR-005](decisions/005-the-doubles-ladder-is-closed.md)).
-- **checker** — passes of the `jterrazz-test-check` binary reading what an AST cannot: the `{{token}}` grammar of `_requests/` and `_expected/` fixtures, the `<case>.spec.yaml` document family, cross-file analyses that cross a `*.specification.ts` with its tests, and the member pass that judges a package rather than a tree.
-- **runtime** — the framework refuses incorrect usage as it executes, where static analysis abstains (a non-literal argument) or cannot reach (the network, a container lifecycle).
-- **type** — what the compiler refuses with no rule at all, proven by `src/type-channel.test-d.ts`.
-- **meta** — what the framework's own suite holds about itself: the catalogue's freshness, its completeness, the reach of its rules — [03 — Testing](03-testing.md) owns the channel.
-- **process** — the judgement no single channel settles: asset-driven grouping, golden-file discipline, retro-propagation.
-
-The channel a rule sits on is not prose here: it is a field of `src/lint/manifest.ts`, the single source of truth from which the catalogue in [19 — Linting](19-linting.md) is generated. A rule and its normative sentence live together in the code, so the two cannot drift.
-
-## What the tree publishes
-
-The bundle is built by `tsdown` into `dist/` and its shape follows how each entry is consumed. `index` and `vitest`, plus the `checker`/`catalog` CLIs, are ESM-only — vitest is ESM-only and the CLIs are invoked as `node dist/*.js`. The `oxlint` plugin ships dual, because oxlint loads it from a consumer project that may itself be CommonJS.
-
-**There are FOUR entries and no more**: `@jterrazz/test` for everything a spec uses, `@jterrazz/test/vitest` for what `vitest.config.ts` needs, `@jterrazz/test/oxlint` for the lint plugin, `@jterrazz/test/schema` for an editor validating a `<case>.spec.yaml`. That is rule F1 rather than a convention of taste, and the exemption is derived from the manifest's own `exports` map (`src/lint/package-exports.ts`), so a subpath is exempt the moment it is published and stops being exempt the moment it is withdrawn.
-
-**The root entry has two runtimes.** A component test renders in a real browser, and the node entry cannot load there: it wires `pg`, `better-sqlite3`, `testcontainers` and `node:fs` at import. So `exports["."]` carries a `browser` condition resolving to `dist/browser/index.js` — the same public surface, built for a page, where every node-only name (the six constructors, the services, the docker accessors, the results that walk a disk) is a stub that throws where it was called, naming the facet and saying it runs under node. The split is the RUNTIME's and never the facets': one specifier, so no spec has to remember which entry it may import.
-
-`types` is stated once, and it is the node build's — so the two runtimes are ONE type surface and a name cannot exist on one side only. What both agree on lives in `src/surface.ts`, and the `package-exports` meta-test compares the two builds' exported names on every run.
-
-Two committed projections leave the code and land in the corpus: the API reference under `docs/reference/` (typedoc, through `typescript docs`) and the rule catalogue spliced into [19 — Linting](19-linting.md) and `skills/jterrazz-test/references/rules.md`. A third, `schema/spec.schema.json`, is generated from the document grammar's own constants. Both `docs/` and `schema/` ship in the tarball — the reference included, since the corpus links into it — so a consumer reads the manual where the messages send them, inside the install ([04 — Operating](04-operating.md#what-leaves-the-tree)). All three are regenerated by one gesture and sync-checked — see [02 — Developing](02-developing.md).
-
-## Pitfalls
-
-- **Reaching for a dependency from `model/`.** A new external package belongs in a folder of `seams/` that imports it and nothing else; `model/` importing it directly is the one boundary this package cannot afford to blur, and `i1-layer-boundaries` refuses it.
-- **Adding a seventh constructor.** The six are the closed vocabulary the conventions, the linter and the documentation are all shaped around. A new SUBJECT to specify is a design decision, and it earns a record in [`decisions/`](decisions/) before it earns a constructor — as `integration` did in [ADR-004](decisions/004-a-module-against-real-services-or-a-golden-is-the-integration-facet.md).
-- **Writing a rule's normative sentence into a chapter.** It belongs in `src/lint/manifest.ts` beside the implementation; a chapter that restates it is the second copy the whole design exists to prevent.
-
-## Related
-
-[02 — Developing](02-developing.md) · [03 — Testing](03-testing.md) · [18 — Conventions](18-conventions.md) · [19 — Linting](19-linting.md)