@shivaedev/test-story 0.0.0 → 0.1.1

package/docs/north-star.md

@@ -0,0 +1,35 @@
+# North star
+
+## The problem
+
+Agents now write most of the code, tests included, and a test file an agent writes tends to be hundreds of lines long. Each test rebuilds its setup by hand, a little differently from the last, and where rebuilding a complex setup is too much work, it mocks the part that was hard to build. Nobody reads these files. A human could ask an agent what a suite actually tests, but nobody asks consistently enough for that to be a safety net, so we lose sight of what we test exactly when more code is written than ever.
+
+## The ideal
+
+A test reads like a short English story: what exists, what someone does, and what is true afterwards. Its setup is a list of traits in the domain's words, such as `ovenIsLit()` and `hasDough(3)`, its actions go through the application's real verbs, and the real engine runs between them. Everything that is not specific to this one test lives elsewhere, written once:
+
+- once per engine, a story kit that knows how to create the engine, seed it stage by stage, step it and show its state;
+- once per feature, the traits and verbs that name that feature in domain words;
+- in each test, only the story.
+
+This changes the cost and benefit of a good test for both readers. For an agent, a story test is the cheaper one to write and to read on every later visit, because it is a handful of lines that reuse what already exists. Because every story runs the whole engine, each test also checks, almost by accident, the parts its author never thought about and would have mocked. For a human, a spec that reads as English leaves no excuse not to read it. With so little noise around the signal, an agent that writes a sloppy or pointless test produces something a reviewer sees at a glance.
+
+## What good looks like
+
+- A spec is a few lines of domain words. If a spec needs a helper, a loop or hand-built state, a trait or verb is missing from the kit.
+- An impossible setup refuses loudly instead of seeding a state the application could never reach.
+- A failure is a console version of stopping in a debugger: the whole story, where it stopped and the spec line there, and the engine's state at that moment, written so an agent with no knowledge of this package can fix the test, and complete enough that a CI log alone is enough to reproduce it.
+- The kit author writes hooks and the package infers every type from them. There is one kit, built on Effect: a hook is a plain function, or a generator function when it needs a service or fails with a typed error, so no definition writes `Effect.gen` and a plain engine needs no Effect at all.
+- A spec writes only its story. The kit hands it an `it` that already knows the engine's services, so a spec never builds a test harness, and names every test after its genre, so a report shows which engine it ran and a run can pick one engine's stories.
+
+## Trade-offs
+
+- **Real engine over speed.** A story is slower than a unit test with a mock. We accept that, and keep engines fast enough to step in a test instead of faking them.
+- **Hooks over freedom.** The kit fixes the shape of an engine: create, stages, after-stage hooks, a step, a state to inspect, verbs. An engine that does not fit should change its kit's hooks, not bypass the kit.
+- **Cheap locations over complete ones.** The failure shows one spec line, where the story stopped, found by matching the spec's path in the failure's stack or in the call site of the story's last line. A failure raised deep inside an Effect verb may have none; finding one would take machinery we do not want.
+
+## What it will not do
+
+- Run without Vitest, or print a failure anywhere but the failing test's own error.
+- Own any application's traits, verbs or steps; they belong to the application's `test-support/`.
+- Mock the application's own code, or help a test reach into an engine's internals. A fake belongs only at a true external boundary, and the kit's `create` is where it is wired in.

package/docs/roadmap.md

@@ -0,0 +1,23 @@
+# Roadmap
+
+This file owns the story kit's implementation, next work and open questions. The
+[framework roadmap](https://github.com/ShivaeDev/platform/blob/main/docs/framework/roadmap.md)
+owns composed application features and host-level validation. Those roadmaps link
+to each other rather than repeating a completion checklist.
+
+## Built
+
+- [x] `storyKit(definition)`: one Effect kit per engine, with every type and the services its layer provides inferred from its hooks. Plain engines plug in with plain functions.
+- [x] Traits seeded stage by stage, with a hook after each stage, and refusal of an impossible setup.
+- [x] The kit's own `it`, built on `@shivaedev/effect-test`, which hands the body the verbs and the story and names every test after the kit's genre. Vitest tags per genre are opt-in through `genreTags(...kitNames)` in the Vitest config.
+- [x] `story.runUntil(condition)`: steps the engine until the condition holds, stops on what `run.failed` reports, and stops after a step budget with a diagnosis, keeping every hook's typed failure in its error channel.
+- [x] A failed test prints a short guide, its story, where it stopped with the spec line there, and the engine's state, inline or in a file under `node_modules/.cache/test-story/`, broken at 120 columns.
+
+## Next
+
+- [ ] Move a first application's hand-written story DSL onto the kit and let what it needs decide the next hook.
+
+## Open questions
+
+- A long story prints in full. Should a story of thousands of lines print its traits and its last lines, and write the rest to a file the way a large engine state is written?
+- `inspect` runs synchronously when the test has failed. An engine whose state lives behind an Effect service cannot be read then. Is that worth an Effect inspect, captured when the failure happens?

package/package.json

@@ -1,11 +1,75 @@
 {
   "name": "@shivaedev/test-story",
-  "version": "0.0.0",
-  "description": "Placeholder. Story DSL for tests: domain traits, a staged seed, a story log and a settle loop.",
-  "license": "MIT",
+  "version": "0.1.1",
+  "description": "Tests that read like stories over the real engine: a story kit per engine with its own it, traits per feature, and a failure that prints the story, where it stopped and the engine's state",
+  "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/test-story#readme",
+  "bugs": {
+    "url": "https://github.com/ShivaeDev/platform/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShivaeDev/platform.git",
     "directory": "packages/test-story"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "imports": {
+    "#test/*": "./src/test-support/*",
+    "#*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "exports": {
+    "./*.ts": {
+      "types": "./dist/*.d.ts",
+      "source": "./src/*.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    },
+    "./internal/*": null,
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/test-support",
+    "docs",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "dependencies": {
+    "@shivaedev/effect-test": "0.3.2"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.0-rc.112",
+    "@shivaedev/quality": "0.19.0",
+    "@types/node": "24.19.1",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "effect": "4.0.0-rc.112",
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "vitest": "4.1.11"
+  },
+  "peerDependencies": {
+    "@effect/vitest": "4.0.0-rc.112",
+    "effect": "4.0.0-rc.112",
+    "vitest": "4.1.11"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node --eval \"import('node:fs').then(({ rmSync }) => rmSync('dist', { force: true, recursive: true }))\" && tsc --project tsconfig.build.json",
+    "ready": "pnpm typecheck && pnpm test && pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
 }

package/src/genreTags.ts

@@ -0,0 +1,10 @@
+import { genreOf } from "#internal/genre.ts";
+
+export interface GenreTag {
+	readonly description: string;
+	readonly name: string;
+}
+
+export function genreTags(...kitNames: readonly string[]): GenreTag[] {
+	return kitNames.map((kitName) => genreOf(kitName).tag);
+}

package/src/internal/callSite.ts

@@ -0,0 +1,19 @@
+import { relative } from "node:path";
+import process from "node:process";
+
+const FRAMES = 50;
+
+// V8 formats a stack only when it is read, so a site costs little until a test fails.
+export function callSite(): Error {
+	const limit = Error.stackTraceLimit;
+	Error.stackTraceLimit = FRAMES;
+	const site = new Error("call site");
+	Error.stackTraceLimit = limit;
+	return site;
+}
+
+export function locate(stack: string | undefined, testFile: string): string | undefined {
+	const frame = stack?.split("\n").find((line) => line.includes(testFile));
+	const position = frame?.slice(frame.indexOf(testFile) + testFile.length).match(/^:(?<line>\d+):(?<column>\d+)/u)?.groups;
+	return position === undefined ? undefined : `${relative(process.cwd(), testFile)}:${position.line}:${position.column}`;
+}

package/src/internal/engineSnapshot.ts

@@ -0,0 +1,48 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import process from "node:process";
+import type { FailedTest } from "#internal/failureReport.ts";
+import type { Subject } from "#internal/narration.ts";
+import { describeValue, toJson } from "#internal/render.ts";
+import { WIDTH, wrap, wrapJson } from "#internal/wrap.ts";
+
+const INLINE_CHARACTERS = 2000;
+
+type Snapshot = { readonly value: unknown } | { readonly threw: unknown };
+
+function snapshot<TEngine>(subject: Subject<TEngine>): Snapshot {
+	try {
+		return { value: subject.inspect === undefined ? subject.engine : subject.inspect(subject.engine) };
+	} catch (threw) {
+		return { threw };
+	}
+}
+
+function slug(text: string): string {
+	return text
+		.toLowerCase()
+		.replaceAll(/[^a-z0-9.]+/gu, "-")
+		.slice(0, 80);
+}
+
+export function engineSnapshot<TEngine>(subject: Subject<TEngine>, test: FailedTest): string[] {
+	const heading = `The ${subject.name} when the test failed`;
+	const taken = snapshot(subject);
+	if ("threw" in taken) {
+		return wrap(`${heading} is unknown: its inspect hook threw ${describeValue(taken.threw)}`);
+	}
+	const json = toJson(taken.value);
+	if (json.length <= INLINE_CHARACTERS) {
+		return heading.length + 2 + json.length > WIDTH ? [`${heading}:`, ...wrapJson(json)] : [`${heading}: ${json}`];
+	}
+	const file = join(
+		process.cwd(),
+		"node_modules",
+		".cache",
+		"test-story",
+		`${slug(basename(test.file))}--${slug(test.name)}--${slug(subject.name)}.json`,
+	);
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, toJson(taken.value, 2));
+	return wrap(`${heading} is ${json.length} characters of JSON, too long to print here. Read it in ${relative(process.cwd(), file)}`);
+}

package/src/internal/errors.ts

@@ -0,0 +1,39 @@
+import { describeValue } from "#internal/render.ts";
+import { explained } from "#internal/wrap.ts";
+
+export function refusal(name: string, line: string, cause: unknown): Error {
+	return new Error(
+		explained(
+			`the trait "${line}" refused to set up the ${name}: ${describeValue(cause)}`,
+			`a trait throws when the ${name} it asks for cannot exist. Give the test traits that fit together, or fix the trait in the ${name} story kit if this ${name} should be possible.`,
+		),
+		{ cause },
+	);
+}
+
+export function broken(name: string, steps: number, reason: string): Error {
+	return new Error(
+		explained(
+			`the ${name} broke after ${steps} steps: ${reason}`,
+			`run.failed in the ${name} story kit reports a state the ${name} cannot recover from. The story printed with this failure shows the setup and steps that led here.`,
+		),
+	);
+}
+
+export function unfinished(name: string, steps: number, diagnosis: string | undefined): Error {
+	return new Error(
+		explained(
+			`the ${name} ran ${steps} steps and never reached what runUntil waits for${diagnosis === undefined ? "" : `: ${diagnosis}`}`,
+			`either the ${name} never gets there, so check the setup and the engine, or it needs more steps, so pass a larger maxSteps to runUntil.`,
+		),
+	);
+}
+
+export function cannotRun(name: string): Error {
+	return new Error(
+		explained(
+			`the ${name} story kit has no run hooks, so runUntil cannot step the ${name}`,
+			`give the ${name} story kit run: { maxSteps, step }, where step advances the ${name} by one step.`,
+		),
+	);
+}

package/src/internal/failureReport.ts

@@ -0,0 +1,55 @@
+import { relative } from "node:path";
+import process from "node:process";
+import { locate } from "#internal/callSite.ts";
+import { engineSnapshot } from "#internal/engineSnapshot.ts";
+import type { Narration, Subject } from "#internal/narration.ts";
+import { describeValue } from "#internal/render.ts";
+import { WIDTH, wrap } from "#internal/wrap.ts";
+
+export interface FailedTest {
+	readonly file: string;
+	readonly name: string;
+	readonly stack: string | undefined;
+}
+
+export function failureReport<TEngine>(narration: Narration, subject: Subject<TEngine>, test: FailedTest): string {
+	try {
+		return [...guide(subject.name), "", ...storyRows(narration, test), "", ...engineSnapshot(subject, test), "", rerun(test)].join("\n");
+	} catch (error) {
+		return `test-story could not print the story of this ${subject.name}: ${describeValue(error)}`;
+	}
+}
+
+function guide(name: string): string[] {
+	return [
+		"╭─ test-story: how to read the story below",
+		...wrap(
+			`"given" lines are the test's traits, the other lines were told by verbs and engine steps as they ran, and ✗ marks where the test stopped. The traits, verbs and steps live in the ${name} story kit that this test imports.`,
+			{ first: "│ ", rest: "│ " },
+		),
+		"╰─",
+	];
+}
+
+function storyRows(narration: Narration, test: FailedTest): string[] {
+	const rows = narration.lines.map(
+		(line, index) => `${narration.refused?.index === index ? "✗" : " "} ${index < narration.given ? "given" : "     "}  ${line}`,
+	);
+	if (narration.refused !== undefined) {
+		const where = locate(narration.sites[narration.refused.index]?.stack, test.file);
+		rows.splice(narration.refused.index + 1, 0, ...(where === undefined ? [] : [`         refused at ${where}`]));
+		return rows;
+	}
+	const where = locate(test.stack, test.file) ?? locate(narration.at?.stack, test.file);
+	return [
+		...rows,
+		`✗        the test failed ${rows.length === 0 ? "before the story told a line" : "after the line above"}`,
+		...(where === undefined ? [] : [`         at ${where}`]),
+	];
+}
+
+function rerun(test: FailedTest): string {
+	const run = `Rerun: vitest run ${relative(process.cwd(), test.file)}`;
+	const filter = `-t "${test.name.replaceAll(/[$()*+.?[\\\]^{|}]/gu, "\\$&")}"`;
+	return run.length + 1 + filter.length > WIDTH ? `${run} \\\n  ${filter}` : `${run} ${filter}`;
+}

package/src/internal/genre.ts

@@ -0,0 +1,14 @@
+import type { GenreTag } from "#genreTags.ts";
+
+export interface Genre {
+	readonly tag: GenreTag;
+	readonly title: string;
+}
+
+export function genreOf(kitName: string): Genre {
+	const words = kitName.trim().split(/\s+/u);
+	return {
+		tag: { description: `stories over a real ${words.join(" ")}`, name: [...words.map((word) => word.toLowerCase()), "story"].join("-") },
+		title: [...words, "story"].map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`).join(" "),
+	};
+}

package/src/internal/hooked.ts

@@ -0,0 +1,22 @@
+import { Effect } from "effect";
+
+export type AnyEffect = Effect.Effect<unknown, unknown, unknown>;
+
+export type Hook<TArguments extends readonly unknown[], TEffect extends AnyEffect, A> = (...input: TArguments) => Generator<TEffect, A, never> | A;
+
+export type ErrorOf<TEffect> = [TEffect] extends [never] ? never : [TEffect] extends [Effect.Effect<infer _A, infer E, infer _R>] ? E : never;
+
+export type ServicesOf<TEffect> = [TEffect] extends [never] ? never : [TEffect] extends [Effect.Effect<infer _A, infer _E, infer R>] ? R : never;
+
+function isGenerator<TEffect, A>(value: Generator<TEffect, A, never> | A): value is Generator<TEffect, A, never> {
+	return typeof value === "object" && value !== null && Symbol.iterator in value && "next" in value && typeof value.next === "function";
+}
+
+export function hooked<TEffect extends AnyEffect, A>(
+	call: () => Generator<TEffect, A, never> | A,
+): Effect.Effect<A, ErrorOf<TEffect>, ServicesOf<TEffect>> {
+	return Effect.suspend(() => {
+		const result = call();
+		return isGenerator(result) ? Effect.gen(() => result) : Effect.succeed(result);
+	});
+}

package/src/internal/narration.ts

@@ -0,0 +1,57 @@
+import type { TestContext } from "vitest";
+import { callSite } from "#internal/callSite.ts";
+import { failureReport } from "#internal/failureReport.ts";
+import { describeFailure } from "#internal/render.ts";
+
+export interface Refusal {
+	readonly cause: unknown;
+	readonly index: number;
+}
+
+export interface Narration {
+	at: Error | undefined;
+	given: number;
+	readonly lines: string[];
+	refused: Refusal | undefined;
+	readonly sites: Error[];
+	readonly tell: (line: string) => void;
+	readonly tellAt: (line: string, site: Error) => void;
+}
+
+export interface Subject<TEngine> {
+	readonly engine: TEngine;
+	readonly inspect: ((engine: TEngine) => unknown) | undefined;
+	readonly name: string;
+}
+
+export function narrate<TEngine>(subject: Subject<TEngine>, { onTestFailed }: Pick<TestContext, "onTestFailed">): Narration {
+	const narration: Narration = {
+		at: undefined,
+		given: 0,
+		lines: [],
+		refused: undefined,
+		sites: [],
+		tell: (line) => {
+			narration.tellAt(line, callSite());
+		},
+		tellAt: (line, site) => {
+			narration.lines.push(line);
+			narration.sites.push(site);
+			narration.at = site;
+		},
+	};
+	onTestFailed(({ task }) => {
+		const failure = task.result?.errors?.[0];
+		if (failure !== undefined) {
+			failure.message = `${failure.message === "" ? describeFailure(failure) : failure.message}\n\n${failureReport(narration, subject, { file: task.file.filepath, name: task.name, stack: failure.stack })}`;
+		}
+	});
+	return narration;
+}
+
+export function tellGiven(narration: Narration, given: readonly { readonly line: string; readonly site: Error }[]): void {
+	for (const part of given) {
+		narration.tellAt(part.line, part.site);
+	}
+	narration.given = given.length;
+}

package/src/internal/render.ts

@@ -0,0 +1,69 @@
+const OWN_ERROR_KEYS = new Set(["_tag", "cause", "message", "name", "stack"]);
+
+// Vitest serializes a failure's class into these keys.
+const SERIALIZED_KEYS = new Set(["constructor", "toString"]);
+
+export function describeValue(value: unknown): string {
+	if (typeof value === "string") {
+		return value;
+	}
+	if (value instanceof Error) {
+		return describeError(value);
+	}
+	return typeof value === "object" && value !== null ? toJson(value) : String(value);
+}
+
+function describeError(error: Error): string {
+	const tag = "_tag" in error && typeof error._tag === "string" ? error._tag : error.name;
+	return describeTagged(tag, error.message, Object.entries(error));
+}
+
+export function describeFailure(failure: { readonly _tag?: unknown; readonly message: string; readonly name?: string }): string {
+	const tag = typeof failure._tag === "string" ? failure._tag : (failure.name ?? "Error");
+	return describeTagged(
+		tag,
+		failure.message,
+		Object.entries(failure).filter(([key]) => !SERIALIZED_KEYS.has(key)),
+	);
+}
+
+function describeTagged(tag: string, message: string, entries: readonly (readonly [string, unknown])[]): string {
+	const fields = Object.fromEntries(entries.filter(([key]) => !OWN_ERROR_KEYS.has(key)));
+	const label = tag === "Error" ? "" : tag;
+	const detail = Object.keys(fields).length === 0 ? "" : toJson(fields);
+	if (message === "") {
+		return [label, detail].filter((part) => part !== "").join(" ") || "Error";
+	}
+	return [label === "" ? message : `${label}: ${message}`, detail].filter((part) => part !== "").join(" ");
+}
+
+export function toJson(value: unknown, indent?: number): string {
+	const seen = new WeakSet<object>();
+	const json = JSON.stringify(
+		value,
+		(_key, item: unknown) => {
+			if (typeof item === "bigint") {
+				return `${item}n`;
+			}
+			if (typeof item === "symbol") {
+				return item.toString();
+			}
+			if (item instanceof Error) {
+				return describeError(item);
+			}
+			if (typeof item !== "object" || item === null) {
+				return item;
+			}
+			if (seen.has(item)) {
+				return "[shown above]";
+			}
+			seen.add(item);
+			if (item instanceof Map) {
+				return Object.fromEntries([...item].map(([key, entry]: readonly [unknown, unknown]) => [describeValue(key), entry]));
+			}
+			return item instanceof Set ? [...item] : item;
+		},
+		indent,
+	);
+	return json ?? String(value);
+}

package/src/internal/runUntil.ts

@@ -0,0 +1,43 @@
+import { Effect } from "effect";
+import { broken, cannotRun, unfinished } from "#internal/errors.ts";
+import { type AnyEffect, type Hook, hooked } from "#internal/hooked.ts";
+import type { RunUntilOptions } from "#storyKit.ts";
+
+export interface LooseRunHooks<TEngine> {
+	readonly diagnose?: Hook<[engine: TEngine], AnyEffect, string>;
+	readonly failed?: Hook<[engine: TEngine], AnyEffect, string | undefined>;
+	readonly maxSteps: number;
+	readonly step: Hook<[engine: TEngine, tell: (line: string) => void], AnyEffect, void>;
+}
+
+export interface Running<TEngine> {
+	readonly engine: TEngine;
+	readonly name: string;
+	readonly run: LooseRunHooks<TEngine> | undefined;
+	readonly tell: (line: string) => void;
+}
+
+export const runUntil = Effect.fnUntraced(function* <TEngine>(
+	{ engine, name, run, tell }: Running<TEngine>,
+	until: Hook<[engine: TEngine], AnyEffect, boolean>,
+	options: RunUntilOptions | undefined,
+) {
+	if (run === undefined) {
+		return yield* Effect.die(cannotRun(name));
+	}
+	const { diagnose, failed, step } = run;
+	const maxSteps = options?.maxSteps ?? run.maxSteps;
+	for (let steps = 0; ; steps += 1) {
+		const reason = failed === undefined ? undefined : yield* hooked(() => failed(engine));
+		if (reason !== undefined) {
+			return yield* Effect.die(broken(name, steps, reason));
+		}
+		if (yield* hooked(() => until(engine))) {
+			return;
+		}
+		if (steps >= maxSteps) {
+			return yield* Effect.die(unfinished(name, steps, diagnose === undefined ? undefined : yield* hooked(() => diagnose(engine))));
+		}
+		yield* hooked(() => step(engine, tell));
+	}
+});

package/src/internal/seed.ts

@@ -0,0 +1,56 @@
+import { Cause, Effect, type Scope } from "effect";
+import type { AnyTestLayer } from "@shivaedev/effect-test/any-test-layer.ts";
+import type { EffectClock } from "@shivaedev/effect-test/types.ts";
+import { refusal } from "#internal/errors.ts";
+import { type AnyEffect, type Hook, hooked } from "#internal/hooked.ts";
+import { type Narration, tellGiven } from "#internal/narration.ts";
+import type { LooseRunHooks } from "#internal/runUntil.ts";
+import type { Parts } from "#internal/traits.ts";
+import type { RunUntilOptions } from "#storyKit.ts";
+
+export type LooseTrait = Parts<string, (engine: unknown) => Effect.Effect<void, unknown, unknown>>;
+
+export interface LooseStory {
+	readonly engine: unknown;
+	readonly lines: readonly string[];
+	readonly runUntil: (until: Hook<[engine: unknown], AnyEffect, boolean>, options?: RunUntilOptions) => Effect.Effect<void, unknown, unknown>;
+	readonly tell: (line: string) => void;
+}
+
+export interface LooseDefinition {
+	readonly after?: Readonly<Partial<Record<string, Hook<[engine: unknown], AnyEffect, void>>>>;
+	readonly around?: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, unknown, R | Scope.Scope>;
+	readonly clock?: EffectClock;
+	readonly create: Hook<[], AnyEffect, unknown>;
+	readonly inspect?: (engine: unknown) => unknown;
+	readonly layer?: AnyTestLayer;
+	readonly name: string;
+	readonly run?: LooseRunHooks<unknown>;
+	readonly stages: readonly string[];
+	readonly verbs: (engine: unknown, story: LooseStory) => object;
+}
+
+export const seed = Effect.fnUntraced(function* (definition: LooseDefinition, engine: unknown, narration: Narration, given: readonly LooseTrait[]) {
+	const parts = given.flatMap((each) => each.parts);
+	tellGiven(narration, parts);
+	for (const stage of definition.stages) {
+		for (const [index, part] of parts.entries()) {
+			if (part.stage === stage) {
+				yield* Effect.suspend(() => part.apply(engine)).pipe(
+					Effect.catchCause((cause) => {
+						if (Cause.hasInterruptsOnly(cause)) {
+							return Effect.interrupt;
+						}
+						const thrown = Cause.squash(cause);
+						narration.refused = { cause: thrown, index };
+						return Effect.die(refusal(definition.name, part.line, thrown));
+					}),
+				);
+			}
+		}
+		const after = definition.after?.[stage];
+		if (after !== undefined) {
+			yield* hooked(() => after(engine));
+		}
+	}
+});

package/src/internal/start.ts

@@ -0,0 +1,24 @@
+import { Effect } from "effect";
+import type { TestContext } from "vitest";
+import { callSite } from "#internal/callSite.ts";
+import { hooked } from "#internal/hooked.ts";
+import { narrate } from "#internal/narration.ts";
+import { runUntil } from "#internal/runUntil.ts";
+import { type LooseDefinition, type LooseStory, type LooseTrait, seed } from "#internal/seed.ts";
+
+export const start = Effect.fnUntraced(function* (definition: LooseDefinition, given: readonly LooseTrait[], context: TestContext) {
+	const engine = yield* hooked(definition.create);
+	const narration = narrate({ engine, inspect: definition.inspect, name: definition.name }, context);
+	yield* seed(definition, engine, narration, given);
+	const story: LooseStory = {
+		engine,
+		lines: narration.lines,
+		runUntil: (until, options) => {
+			const site = callSite();
+			narration.at = site;
+			return runUntil({ engine, name: definition.name, run: definition.run, tell: (line) => narration.tellAt(line, site) }, until, options);
+		},
+		tell: narration.tell,
+	};
+	return { ...definition.verbs(engine, story), story };
+});