@jterrazz/test 13.0.1 → 14.0.0

package/dist/index.d.ts

@@ -6,9 +6,9 @@ import { DeepMockProxy } from "vitest-mock-extended";
  * by every assertion of a single spec execution.
  *
  * Matchers are used inside `toMatchRows` rows and any structural comparison;
- * their file-side twins are the `{{placeholder}}` forms in `expected/*.http`
- * fixtures (body AND headers), `expected/*.json` files, and text snapshots
- * (`expected/*.txt`). One grammar, one vocabulary (CONVENTIONS D4).
+ * their file-side twins are the `{{placeholder}}` forms in `_expected/*.http`
+ * fixtures (body AND headers), `_expected/*.json` files, and text snapshots
+ * (`_expected/*.txt`). One grammar, one vocabulary (CONVENTIONS D4).
  */
 /** The frozen token vocabulary (CONVENTIONS D4) plus the code-only kinds. */
 type MatcherKind = 'any' | 'base64' | 'date' | 'duration' | 'email' | 'float' | 'hex' | 'includes' | 'int' | 'ip' | 'iso8601' | 'number' | 'path' | 'port' | 'ref' | 'regex' | 'semver' | 'sha' | 'string' | 'time' | 'ulid' | 'url' | 'uuid' | 'workdir';
@@ -136,7 +136,7 @@ declare class CaptureScope {
  *
  * Assertions go through `expect()` (async — they walk the disk):
  * `await expect(result.directory('out')).toMatch('scaffold/out')`
- * compares the tree against the fixture directory `expected/<name>/`.
+ * compares the tree against the fixture directory `_expected/<name>/`.
  */
 declare class DirectoryAccessor {
   /** @internal Ref-capture scope shared by the current spec execution. */
@@ -159,7 +159,7 @@ declare class DirectoryAccessor {
  *
  * Assertions go through `expect()` (async — they walk the disk):
  * `await expect(result.filesystem).toMatch('scaffolded')` compares the
- * tree against the fixture directory `expected/<name>/`.
+ * tree against the fixture directory `_expected/<name>/`.
  */
 declare class FilesystemAccessor {
   /** @internal Ref-capture scope shared by the current spec execution. */
@@ -189,7 +189,7 @@ declare class FilesystemAccessor {
  * covered by the `{{token}}` grammar.
  *
  * Assertions go through `expect()`: `expect(result.json).toMatch('name.json')`
- * (deep-equal against `expected/<name>`, with `{{placeholder}}` support).
+ * (deep-equal against `_expected/<name>`, with `{{placeholder}}` support).
  */
 declare class JsonAccessor {
   /** @internal Ref-capture scope shared by the current spec execution. */
@@ -232,7 +232,7 @@ interface ServerPort {
  *
  * Assertions go through `expect()`:
  * `expect(result.response).toMatch('created.http')` compares status,
- * a subset of headers, and the JSON body against `expected/<name>` —
+ * a subset of headers, and the JSON body against `_expected/<name>` —
  * with `{{placeholder}}` support in all three.
  */
 declare class ResponseAccessor {
@@ -302,14 +302,14 @@ declare class TableAccessor {
  * grammar.
  *
  * Text operations are **closed** over the type: `.grep(pattern)` returns a
- * `TextAccessor` (not a bare string), preserving the `expected/`-resolution
+ * `TextAccessor` (not a bare string), preserving the `_expected/`-resolution
  * context and the `transform`, so results are chainable
  * (`result.stdout.grep(a).grep(b)`) and snapshot-able
  * (`expect(result.stdout.grep('users.ts')).toMatch('block.txt')`).
  *
  * Assertions go through `expect()` matchers: `expect(result.stdout).toContain(...)`
  * and `expect(result.stdout).toMatch('name.txt')` (resolved against
- * `expected/<name>`, flat — with `{{token}}` support, CONVENTIONS D4).
+ * `_expected/<name>`, flat — with `{{token}}` support, CONVENTIONS D4).
  */
 declare class TextAccessor {
   /** @internal Ref-capture scope shared by the current spec execution. */
@@ -349,7 +349,7 @@ declare class TextAccessor {
  *
  * ```typescript
  * const message = await catchMessage(() => expect(result.response).toMatch('wrong-body.http'));
- * expect(text(message)).toMatch('wrong-body-error.txt'); // resolves to expected/
+ * expect(text(message)).toMatch('wrong-body-error.txt'); // resolves to _expected/
  * ```
  *
  * ANSI is stripped before every comparison (the raw form stays on `.text`),
@@ -1240,7 +1240,7 @@ interface ApiSpecification<DatabaseKey extends string = string> {
   headers: (headers: Record<string, string>) => ApiSpecification<DatabaseKey>;
   /** Declare outgoing calls — a contract, a list, a composite, or an inline request + response pair. */
   intercept: InterceptMethod<ApiSpecification<DatabaseKey>>;
-  /** Queue a SQL seed file from `seeds/` to run before the action. */
+  /** Queue a SQL seed file from `_seeds/` to run before the action. */
   seed: (file: string, options?: {
     database?: DatabaseKey;
   }) => ApiSpecification<DatabaseKey>;
@@ -1252,7 +1252,7 @@ interface ApiSpecification<DatabaseKey extends string = string> {
   post: (path: string, body?: unknown) => Promise<HttpResult>;
   /** Send a PUT request (optional inline JSON body) and resolve with the result. */
   put: (path: string, body?: unknown) => Promise<HttpResult>;
-  /** Send the complete request described by `requests/<file>` (.http format). */
+  /** Send the complete request described by `_requests/<file>` (.http format). */
   request: (file: string) => Promise<HttpResult>;
 }
 /**
@@ -1262,7 +1262,7 @@ interface ApiSpecification<DatabaseKey extends string = string> {
 interface JobsSpecification<DatabaseKey extends string = string> {
   /** Declare outgoing calls — a contract, a list, a composite, or an inline request + response pair. */
   intercept: InterceptMethod<JobsSpecification<DatabaseKey>>;
-  /** Queue a SQL seed file from `seeds/` to run before the action. */
+  /** Queue a SQL seed file from `_seeds/` to run before the action. */
   seed: (file: string, options?: {
     database?: DatabaseKey;
   }) => JobsSpecification<DatabaseKey>;
@@ -1285,7 +1285,7 @@ interface CliSpecification<DatabaseKey extends string = string> {
    * directory (or file) is copied under its own name. Chained calls layer.
    */
   fixture: (path: string) => CliSpecification<DatabaseKey>;
-  /** Queue a SQL seed file from `seeds/` to run against a database before the action. */
+  /** Queue a SQL seed file from `_seeds/` to run against a database before the action. */
   seed: (file: string, options?: {
     database?: DatabaseKey;
   }) => CliSpecification<DatabaseKey>;
@@ -2454,7 +2454,7 @@ declare module 'vitest' {
     toBeRunning: T extends ContainerAccessor ? () => Promise<void> : never;
     /**
      * On `@jterrazz/test` accessors: assert the subject matches a fixture
-     * file under `expected/<name>` (flat — a slash creates a subfolder;
+     * file under `_expected/<name>` (flat — a slash creates a subfolder;
      * `.http` format for `result.response`). Async for filesystem/directory
      * subjects (tree compare on disk). Other subjects keep vitest-native
      * `toMatch` semantics (string substring / regexp).

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as copyPlan, i as match, n as Matcher, t as CaptureScope } from "./match.js";
+import { a as copyPlan, c as GROUND_EXPECTED, d as GROUND_SEEDS, i as match, n as Matcher, t as CaptureScope, u as GROUND_REQUESTS } from "./match.js";
 import { C as formatResponseDiff, E as formatTableDiff, M as structuralEquals, N as structuralSubset, O as mergePreservingPlaceholders, P as textEquals, S as formatDirectoryDiff, T as formatStdoutDiff, _ as getCallerDir, a as shouldUpdateSnapshots, b as diffDirectories, c as BaseResult, d as inspectContainer, f as removeContainers, g as text, h as TextAccessor, i as UPDATE_HINT, j as renderExpected, k as mergeTextPreservingPlaceholders, l as validateDatabaseOption, m as JsonAccessor, o as ContainerAccessor, p as TableAccessor, r as ServeAdapter, s as CliResult, t as runSpecDocument, u as findContainersByLabel, v as FilesystemAccessor, w as formatStartupReport, x as walkDirectory, y as DirectoryAccessor } from "./literate.js";
 import { a as isContract, i as defineContracts, n as contractsOf, o as isContracts, r as defineContract, t as ContractQueue } from "./queue.js";
 import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
@@ -450,7 +450,7 @@ function parseHeaders(headerLines, fileName) {
 	}
 	return headers;
 }
-/** Parse a `requests/*.http` file. First line must be `METHOD /path`. */
+/** Parse a `_requests/*.http` file. First line must be `METHOD /path`. */
 function parseRequestFile(content, fileName) {
 	const { body, headerLines, startLine } = splitSections(content);
 	const start = /^(?<method>[A-Z]+)\s+(?<path>\S+)$/.exec(startLine.trim());
@@ -526,7 +526,7 @@ function isJsonLike(text) {
 *
 * Assertions go through `expect()`:
 * `expect(result.response).toMatch('created.http')` compares status,
-* a subset of headers, and the JSON body against `expected/<name>` —
+* a subset of headers, and the JSON body against `_expected/<name>` —
 * with `{{placeholder}}` support in all three.
 */
 var ResponseAccessor = class {
@@ -577,36 +577,36 @@ function formatJson(value) {
 }
 function matchStreamFile(accessor, name, frozen) {
 	requireExtension(name, "stream");
-	const filePath = resolve(accessor.testDir, "expected", name);
+	const filePath = resolve(accessor.testDir, GROUND_EXPECTED, name);
 	const actual = accessor.comparableText;
 	if (shouldUpdateSnapshots() && !frozen) {
 		const merged = mergeTextPreservingPlaceholders(existsSync(filePath) ? readFileSync(filePath, "utf8") : null, actual, accessor.captures);
 		mkdirSync(dirname(filePath), { recursive: true });
 		writeFileSync(filePath, merged);
-		return PASS(`updated expected/${name}`);
+		return PASS(`updated ${GROUND_EXPECTED}/${name}`);
 	}
 	if (!existsSync(filePath)) return FAIL(`${accessor.streamName} fixture "${name}" does not exist at ${filePath}.\n${UPDATE_HINT}`);
 	const expected = readFileSync(filePath, "utf8");
-	if (textEquals(expected, actual, accessor.captures)) return PASS(`expected ${accessor.streamName} not to match expected/${name}`);
+	if (textEquals(expected, actual, accessor.captures)) return PASS(`expected ${accessor.streamName} not to match ${GROUND_EXPECTED}/${name}`);
 	return FAIL(formatStdoutDiff(name, expected, actual, { equals: (expectedLine, actualLine) => textEquals(expectedLine, actualLine, new CaptureScope(accessor.captures.workdir)) }));
 }
 function matchJsonFile(accessor, name, frozen) {
 	requireExtension(name, "json");
-	const filePath = resolve(accessor.testDir, "expected", name);
+	const filePath = resolve(accessor.testDir, GROUND_EXPECTED, name);
 	const actual = accessor.value;
 	if (shouldUpdateSnapshots() && !frozen) {
 		const merged = existsSync(filePath) ? mergePreservingPlaceholders(JSON.parse(readFileSync(filePath, "utf8")), actual, accessor.captures.workdir) : mergePreservingPlaceholders(null, actual, accessor.captures.workdir);
 		mkdirSync(dirname(filePath), { recursive: true });
 		writeFileSync(filePath, formatJson(merged));
-		return PASS(`updated expected/${name}`);
+		return PASS(`updated ${GROUND_EXPECTED}/${name}`);
 	}
 	if (!existsSync(filePath)) return FAIL(`JSON fixture "${name}" does not exist at ${filePath}.\n${UPDATE_HINT}`);
 	const expected = JSON.parse(readFileSync(filePath, "utf8"));
-	if (structuralEquals(expected, actual, accessor.captures)) return PASS(`expected JSON not to match expected/${name}`);
+	if (structuralEquals(expected, actual, accessor.captures)) return PASS(`expected JSON not to match ${GROUND_EXPECTED}/${name}`);
 	return FAIL(formatResponseDiff(name, renderExpected(expected), actual));
 }
 /**
-* Build the updated `expected/*.http` fixture content from the previous
+* Build the updated `_expected/*.http` fixture content from the previous
 * fixture and the actual response (CONVENTIONS D5). Headers are the
 * INTERSECTION with the actual response: placeholders still matching are
 * preserved, stale values are replaced, headers absent from the actual
@@ -633,7 +633,7 @@ function buildUpdatedResponse(previous, actual, workdir) {
 	};
 }
 /**
-* Compare a parsed `expected/*.http` fixture against an actual response.
+* Compare a parsed `_expected/*.http` fixture against an actual response.
 * Returns the failure message, or null when everything matches.
 *
 * @internal Exported for unit tests.
@@ -649,19 +649,19 @@ function compareResponse(name, expected, actual, scope) {
 }
 function matchResponseFile(accessor, name, frozen) {
 	requireExtension(name, "response");
-	const filePath = resolve(accessor.testDir, "expected", name);
+	const filePath = resolve(accessor.testDir, GROUND_EXPECTED, name);
 	if (shouldUpdateSnapshots() && !frozen) {
-		const updated = buildUpdatedResponse(existsSync(filePath) ? parseResponseFile(readFileSync(filePath, "utf8"), `expected/${name}`) : null, accessor, accessor.captures.workdir);
+		const updated = buildUpdatedResponse(existsSync(filePath) ? parseResponseFile(readFileSync(filePath, "utf8"), `${GROUND_EXPECTED}/${name}`) : null, accessor, accessor.captures.workdir);
 		mkdirSync(dirname(filePath), { recursive: true });
 		writeFileSync(filePath, serializeResponseFile(updated));
-		return PASS(`updated expected/${name}`);
+		return PASS(`updated ${GROUND_EXPECTED}/${name}`);
 	}
 	if (!existsSync(filePath)) return FAIL(`Response fixture "${name}" does not exist at ${filePath}.\n${UPDATE_HINT}`);
-	const failure = compareResponse(name, parseResponseFile(readFileSync(filePath, "utf8"), `expected/${name}`), accessor, accessor.captures);
-	return failure === null ? PASS(`expected response not to match expected/${name}`) : FAIL(failure);
+	const failure = compareResponse(name, parseResponseFile(readFileSync(filePath, "utf8"), `${GROUND_EXPECTED}/${name}`), accessor, accessor.captures);
+	return failure === null ? PASS(`expected response not to match ${GROUND_EXPECTED}/${name}`) : FAIL(failure);
 }
 async function matchTreeFile(actualRoot, testDir, name, scope, frozen) {
-	const fixtureDir = resolve(testDir, "expected", name);
+	const fixtureDir = resolve(testDir, GROUND_EXPECTED, name);
 	if (shouldUpdateSnapshots() && !frozen) {
 		const previousContents = /* @__PURE__ */ new Map();
 		if (existsSync(fixtureDir)) for (const file of await walkDirectory(fixtureDir)) previousContents.set(file, readFileSync(resolve(fixtureDir, file), "utf8"));
@@ -677,11 +677,11 @@ async function matchTreeFile(actualRoot, testDir, name, scope, frozen) {
 			const merged = mergeTextPreservingPlaceholders(previous, actual, scope);
 			if (merged !== actual) writeFileSync(resolve(fixtureDir, file), merged);
 		}
-		return PASS(`updated expected/${name}/`);
+		return PASS(`updated ${GROUND_EXPECTED}/${name}/`);
 	}
 	if (!existsSync(fixtureDir)) return FAIL(`Directory fixture "${name}" does not exist at ${fixtureDir}.\n${UPDATE_HINT}`);
 	const diff = await diffDirectories(fixtureDir, actualRoot, { scope });
-	if (diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0) return PASS(`expected directory not to match expected/${name}/`);
+	if (diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0) return PASS(`expected directory not to match ${GROUND_EXPECTED}/${name}/`);
 	return FAIL(formatDirectoryDiff(name, diff, "Run with TEST_UPDATE=1 to update the fixture."));
 }
 /**
@@ -1107,7 +1107,7 @@ var SpecificationBuilder = class {
 	}
 	/**
 	* Set HTTP headers for the request. Multiple calls merge; chain headers
-	* win over headers from a `requests/*.http` file.
+	* win over headers from a `_requests/*.http` file.
 	*
 	* @example
 	*   api.headers({ 'Accept-Language': 'fr' }).get("/articles");
@@ -1137,7 +1137,7 @@ var SpecificationBuilder = class {
 		return this;
 	}
 	/**
-	* Send the complete request described by `requests/<file>` — first line
+	* Send the complete request described by `_requests/<file>` — first line
 	* `METHOD /path`, then headers until a blank line, then the body.
 	* Headers set via `.headers()` merge on top of the file's headers.
 	*
@@ -1321,7 +1321,7 @@ var SpecificationBuilder = class {
 				if (!db) throw new Error(`seed() targets database "${entry.database}" but it was not found. Available: ${[...this.config.databases.keys()].join(", ")}`);
 			} else db = this.config.database;
 			if (!db) throw new Error("seed() requires a database adapter");
-			const sql = readFileSync(resolve(this.testDir, "seeds", entry.file), "utf8");
+			const sql = readFileSync(resolve(this.testDir, GROUND_SEEDS, entry.file), "utf8");
 			await db.seed(sql);
 		}
 		if (this.fixtures.length > 0 && workDir) for (const entry of this.fixtures) {
@@ -1363,7 +1363,7 @@ var SpecificationBuilder = class {
 		let { body, method, path } = request;
 		let fileHeaders;
 		if (request.requestFile) {
-			const parsed = parseRequestFile(readFileSync(resolve(this.testDir, "requests", request.requestFile), "utf8"), `requests/${request.requestFile}`);
+			const parsed = parseRequestFile(readFileSync(resolve(this.testDir, GROUND_REQUESTS, request.requestFile), "utf8"), `${GROUND_REQUESTS}/${request.requestFile}`);
 			body = parsed.body;
 			fileHeaders = parsed.headers;
 			method = parsed.method;

package/dist/literate.js

@@ -16,8 +16,8 @@ import { createServer } from "node:net";
 * - 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`).
+* 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.
@@ -232,7 +232,7 @@ function structuralSubset(expected, actual, scope) {
 }
 /**
 * Multi-line text comparison with `{{token}}` support — used by text
-* snapshots (`expected/*.txt`). Without placeholders this is strict equality.
+* snapshots (`_expected/*.txt`). Without placeholders this is strict equality.
 */
 function textEquals(expected, actual, scope) {
 	if (!hasPlaceholders(expected)) return expected === actual;
@@ -592,7 +592,7 @@ async function diffDirectories(expectedRoot, actualRoot, options = {}) {
 *
 * Assertions go through `expect()` (async — they walk the disk):
 * `await expect(result.directory('out')).toMatch('scaffold/out')`
-* compares the tree against the fixture directory `expected/<name>/`.
+* compares the tree against the fixture directory `_expected/<name>/`.
 */
 var DirectoryAccessor = class {
 	/** @internal Ref-capture scope shared by the current spec execution. */
@@ -619,7 +619,7 @@ var DirectoryAccessor = class {
 *
 * Assertions go through `expect()` (async — they walk the disk):
 * `await expect(result.filesystem).toMatch('scaffolded')` compares the
-* tree against the fixture directory `expected/<name>/`.
+* tree against the fixture directory `_expected/<name>/`.
 */
 var FilesystemAccessor = class {
 	/** @internal Ref-capture scope shared by the current spec execution. */
@@ -691,8 +691,8 @@ function isFrameworkFrame(filePath, frameworkTree = FRAMEWORK_TREE) {
 }
 /**
 * Detect the directory of the first stack frame that lives outside this
-* package. Used to anchor fixture resolution (`seeds/`, `requests/`,
-* `expected/`, …) on the calling test / specification file.
+* package. Used to anchor fixture resolution (`_seeds/`, `_requests/`,
+* `_expected/`, …) on the calling test / specification file.
 *
 * @internal
 */
@@ -745,14 +745,14 @@ function stripAnsiCodes(value) {
 * grammar.
 *
 * Text operations are **closed** over the type: `.grep(pattern)` returns a
-* `TextAccessor` (not a bare string), preserving the `expected/`-resolution
+* `TextAccessor` (not a bare string), preserving the `_expected/`-resolution
 * context and the `transform`, so results are chainable
 * (`result.stdout.grep(a).grep(b)`) and snapshot-able
 * (`expect(result.stdout.grep('users.ts')).toMatch('block.txt')`).
 *
 * Assertions go through `expect()` matchers: `expect(result.stdout).toContain(...)`
 * and `expect(result.stdout).toMatch('name.txt')` (resolved against
-* `expected/<name>`, flat — with `{{token}}` support, CONVENTIONS D4).
+* `_expected/<name>`, flat — with `{{token}}` support, CONVENTIONS D4).
 */
 var TextAccessor = class TextAccessor {
 	/** @internal Ref-capture scope shared by the current spec execution. */
@@ -807,7 +807,7 @@ var TextAccessor = class TextAccessor {
 *
 * ```typescript
 * const message = await catchMessage(() => expect(result.response).toMatch('wrong-body.http'));
-* expect(text(message)).toMatch('wrong-body-error.txt'); // resolves to expected/
+* expect(text(message)).toMatch('wrong-body-error.txt'); // resolves to _expected/
 * ```
 *
 * ANSI is stripped before every comparison (the raw form stays on `.text`),
@@ -832,7 +832,7 @@ function text(value) {
 * covered by the `{{token}}` grammar.
 *
 * Assertions go through `expect()`: `expect(result.json).toMatch('name.json')`
-* (deep-equal against `expected/<name>`, with `{{placeholder}}` support).
+* (deep-equal against `_expected/<name>`, with `{{placeholder}}` support).
 */
 var JsonAccessor = class {
 	/** @internal Ref-capture scope shared by the current spec execution. */

package/dist/match.js

@@ -1,14 +1,51 @@
 import { basename, dirname, resolve } from "node:path";
+//#region src/core/specification/shared/ground.ts
+/**
+* The GROUND a row of specs stands on — the naming law of a spec tree.
+*
+* In a row of specs, a MEMBER is a spec: `<aspect>.test.ts`, `<case>.spec.yaml`,
+* `<name>.specification.ts`, and the facet/domain folders that hold them.
+* Everything else in that row is what the members STAND ON — inert material the
+* framework resolves BY PATH, never imported, never executed — and it carries a
+* LEADING UNDERSCORE. A spec's own folder never does.
+*
+* Four names, and only four: `_fixtures/` (file state), `_expected/` (goldens),
+* `_requests/` (inputs), `_seeds/` (database state). `contracts/` is NOT ground —
+* a contract is TypeScript a spec imports, behaviour composed with the spec's own,
+* so it stays a member. `docker/` is not ground either: it sits at the PROJECT
+* root beside `package.json`, outside any row of specs.
+*
+* This module is the single home of those names. Every resolver, matcher, lint
+* rule and checker pass reads them from here, so the runtime and the static
+* channels cannot disagree about where a spec's ground lives.
+*/
+/** Goldens: every expected fixture, flat, extension included. */
+const GROUND_EXPECTED = "_expected";
+/** File state copied into a working directory by `.fixture()`. */
+const GROUND_FIXTURES = "_fixtures";
+/** Inputs: complete `.http` request documents. */
+const GROUND_REQUESTS = "_requests";
+/** Database state: `.sql` fragments loaded by `.seed()`. */
+const GROUND_SEEDS = "_seeds";
+/** The four ground directory names, in the order they read. */
+const GROUND_DIRS = [
+	GROUND_EXPECTED,
+	GROUND_FIXTURES,
+	GROUND_REQUESTS,
+	GROUND_SEEDS
+];
+//#endregion
 //#region src/core/specification/shared/fixtures.ts
 /**
 * Fixture path resolution + copy semantics for the `cli` facet's `.fixture()`.
 *
 * A fixture path is one of two shapes:
 *
-*  - `$FIXTURES/<rest>` — the shared pool at `<specs-root>/fixtures/<rest>`,
+*  - `$FIXTURES/<rest>` — the shared pool at `<specs-root>/_fixtures/<rest>`,
 *    where `<specs-root>` is the nearest ancestor directory named `specs`.
-*  - `<path>` (no marker) — feature-local, at `<test-dir>/fixtures/<path>`.
+*  - `<path>` (no marker) — feature-local, at `<test-dir>/_fixtures/<path>`.
 *
+* The leading underscore is the ground rule of a spec tree ({@link GROUND_FIXTURES}).
 * Any other `$`-prefixed marker is a usage error (listed against the known
 * markers). Copy semantics mirror rsync's trailing-slash rule (see
 * {@link copyPlan}).
@@ -32,7 +69,7 @@ function discoverSpecsRoot(startDir) {
 		if (parent === dir) break;
 		dir = parent;
 	}
-	throw new Error(`.fixture(): the $FIXTURES marker resolves to <specs-root>/fixtures, but no directory named "specs" was found walking up from ${startDir}. Move the specification under a specs/ directory, or use a feature-local fixtures/ path (no $FIXTURES marker).`);
+	throw new Error(`.fixture(): the $FIXTURES marker resolves to <specs-root>/${GROUND_FIXTURES}, but no directory named "specs" was found walking up from ${startDir}. Move the specification under a specs/ directory, or use a feature-local ${GROUND_FIXTURES}/ path (no $FIXTURES marker).`);
 }
 /**
 * Resolve the absolute source path of a fixture, applying marker resolution.
@@ -43,13 +80,13 @@ function resolveFixtureSource(path, testDir) {
 	const clean = path.replace(/\/+$/, "");
 	if (clean === "$FIXTURES" || path.startsWith("$FIXTURES/")) {
 		const rest = clean.slice(9).replace(/^\/+/, "");
-		return resolve(discoverSpecsRoot(testDir), "fixtures", rest);
+		return resolve(discoverSpecsRoot(testDir), GROUND_FIXTURES, rest);
 	}
 	if (path.startsWith("$")) {
 		const marker = clean.split("/")[0];
-		throw new Error(`.fixture("${path}"): unknown marker "${marker}". Known markers: ${KNOWN_FIXTURE_MARKERS.join(", ")}. A path without a marker is feature-local (resolved under <test-dir>/fixtures/).`);
+		throw new Error(`.fixture("${path}"): unknown marker "${marker}". Known markers: ${KNOWN_FIXTURE_MARKERS.join(", ")}. A path without a marker is feature-local (resolved under <test-dir>/${GROUND_FIXTURES}/).`);
 	}
-	return resolve(testDir, "fixtures", clean);
+	return resolve(testDir, GROUND_FIXTURES, clean);
 }
 /**
 * Compute the source + destination for copying a fixture into the working
@@ -233,4 +270,4 @@ var CaptureScope = class {
 	}
 };
 //#endregion
-export { copyPlan as a, match as i, Matcher as n, resolveFixtureSource as o, TOKEN_KINDS as r, CaptureScope as t };
+export { copyPlan as a, GROUND_EXPECTED as c, GROUND_SEEDS as d, match as i, GROUND_FIXTURES as l, Matcher as n, resolveFixtureSource as o, TOKEN_KINDS as r, GROUND_DIRS as s, CaptureScope as t, GROUND_REQUESTS as u };