@classytic/arc-testkit 0.5.0 → 0.7.0

package/dist/story.d.mts

@@ -0,0 +1,202 @@
+import { expect } from "vitest";
+export type Clauses = string | readonly string[];
+/** `[REQ-1 | Reminders] the reminder reached the holder`. */
+export declare function clauseMessage(clauses: Clauses | undefined, what: string): string;
+export interface StepContext {
+  /** The step's number in the story. */
+  readonly n: number;
+  readonly title: string;
+  readonly clauses: readonly string[];
+  /** The tagged message for an assertion in this step: `[clauses] what`. */
+  msg(what: string, clauses?: Clauses): string;
+  /** `expect(actual, "[clauses] what")`. */
+  expect<T>(actual: T, what: string, clauses?: Clauses): ReturnType<typeof expect<T>>;
+  /** `expect.soft`: a failure is reported at the end of the step, the step keeps running. */
+  soft<T>(actual: T, what: string, clauses?: Clauses): ReturnType<typeof expect.soft<T>>;
+  /** A known defect: soft, tagged `KNOWN DEFECT <id>` so the report names the open finding. */
+  known<T>(defect: string, actual: T, what: string, clauses?: Clauses): ReturnType<typeof expect.soft<T>>;
+}
+export interface StepOptions {
+  clauses?: Clauses;
+  /** Per-step timeout in ms. */
+  timeout?: number;
+}
+/** What a step body is: the step context, then the vitest test context (fixtures of an extended `test`). */
+export type StepBody<Ctx> = (t: StepContext, ctx: Ctx) => void | Promise<void>;
+export interface Story<Ctx = unknown> {
+  /** Register the next numbered step. */
+  step(title: string, run: StepBody<Ctx>): void;
+  step(title: string, options: StepOptions, run: StepBody<Ctx>): void;
+  /** Number the next step will have. */
+  readonly next: number;
+}
+/** The registration function of an extended `test` (`test.extend(...)`), so steps receive its fixtures. */
+export type StepRegistrar<Ctx> = (name: string, fn: (ctx: Ctx & {
+  skip(note?: string): never;
+}) => Promise<void>, timeout?: number) => unknown;
+export interface StoryOptions<Ctx = unknown> {
+  /** An extended `test`: steps then get its fixtures as their second argument. Default: vitest's `it`. */
+  test?: StepRegistrar<Ctx>;
+  /** Names of the extended test's fixtures the steps use; they arrive in the second argument. */
+  fixtures?: readonly (keyof Ctx & string)[];
+  /** Number of the first step. Default: 1. */
+  firstStep?: number;
+  /** Skip the remaining steps once one fails. Default: true. */
+  bail?: boolean;
+  /** Clauses added to every step. */
+  clauses?: Clauses;
+}
+/** Registers a `describe` holding the story's numbered steps. */
+export declare function describeStory<Ctx = unknown>(title: string, define: (story: Story<Ctx>) => void, options?: StoryOptions<Ctx>): void;
+/** Read a handed-over value, with an error that names the missing step instead of a bare `undefined`. */
+export declare function need<T>(bag: Readonly<Record<string, T | undefined>>, key: string): T;
+type Row = Record<string, unknown>;
+type Awaitable<T> = T | PromiseLike<T>;
+/** A string / RegExp (tested on the row's key field), a function, or an object matched as a deep subset. */
+export type RowMatch = string | RegExp | ((row: never) => boolean) | Row;
+export interface FeedItem {
+  title?: string;
+  message?: string;
+  [key: string]: unknown;
+}
+export interface StoryPorts<TActor = unknown> {
+  /** Deliver everything pending in the transactional outbox (one pass). */
+  drain?: () => Awaitable<unknown>;
+  /** The domain events seen so far (see {@link createEventLog}). */
+  events?: () => Awaitable<readonly Row[]>;
+  /** A user's in-app feed, newest first or not: order is never asserted. */
+  feed?: (actor: TActor) => Awaitable<readonly FeedItem[]>;
+  /** Mails the dev outbox holds. */
+  mail?: () => Awaitable<readonly Row[]>;
+  /** Audit rows, optionally narrowed by the host-defined filter. */
+  audit?: (filter?: Row) => Awaitable<readonly Row[]>;
+  /** Field holding an event's type. Default: `type`. */
+  eventTypeKey?: string;
+}
+export interface Expectation {
+  clauses?: Clauses;
+  /** Exact number of matching rows. */
+  count?: number;
+  /** At least this many (default 1 unless `count` is given). */
+  min?: number;
+  /** Ignore the first `since` events (a mark from {@link EventLog.mark}). */
+  since?: number;
+}
+export interface RelayOptions {
+  timeout?: number;
+  interval?: number;
+}
+/** True when `actual` carries every field of `expected` (RegExp and function leaves are tested, not compared). */
+export declare function subsetMatches(actual: unknown, expected: unknown): boolean;
+export interface StoryAssertions<TActor> {
+  /** Drain the outbox `rounds` times (a handler may write further events). */
+  drain(rounds?: number): Promise<void>;
+  /** Drain, then assert; repeat until the assertion holds (events are relayed asynchronously). */
+  relayed<T>(assertion: () => T | Promise<T>, options?: RelayOptions): Promise<T>;
+  /** Events matching `match` (after `since`). */
+  eventsOf(match: RowMatch, since?: number): Promise<Row[]>;
+  expectEvent(match: RowMatch, spec?: Expectation): Promise<Row[]>;
+  expectNoEvent(match: RowMatch, spec?: Pick<Expectation, "clauses" | "since">): Promise<void>;
+  /** Feed items of `actor` whose title / message match. */
+  feedOf(actor: TActor): Promise<readonly FeedItem[]>;
+  expectFeed(actor: TActor, match: RowMatch, spec?: Expectation): Promise<readonly FeedItem[]>;
+  expectNoFeed(actor: TActor, match: RowMatch, spec?: Pick<Expectation, "clauses">): Promise<void>;
+  expectMail(match: RowMatch, spec?: Expectation): Promise<Row[]>;
+  expectAudit(filter: Row | undefined, match: RowMatch, spec?: Expectation): Promise<Row[]>;
+}
+export declare function createStoryAssertions<TActor = unknown>(ports: StoryPorts<TActor>): StoryAssertions<TActor>;
+export interface EventLog<E extends Row = Row> {
+  record(event: E): void;
+  all(): readonly E[];
+  /** The number of events so far: pass it as `since` to look only at what happens next. */
+  mark(): number;
+  clear(): void;
+  /**
+   * Subscribe `patterns` through the host's bus (`subscribe(pattern, handler)`, e.g. `app.events.subscribe`)
+   * so every matching event is recorded.
+   */
+  tap(subscribe: (pattern: string, handler: (event: E) => unknown) => unknown, patterns: readonly string[]): void;
+}
+/** An in-memory event log fed by a tap on the host's event bus; the `events` port reads it. */
+export declare function createEventLog<E extends Row = Row>(): EventLog<E>;
+/**
+ * A cast: the named users of a story, each provisioned with roles by a host function that signs the
+ * user up on the booted app and returns whatever the story talks through (a client, a token).
+ */
+export interface CastSpecEntry<TOpts> {
+  roles: readonly string[];
+  opts?: TOpts;
+}
+/** `roles` shorthand, or `{ roles, opts }` when the host's provisioner takes options (e.g. `{ mfa: false }`). */
+export type CastSpec<TOpts> = readonly string[] | CastSpecEntry<TOpts>;
+export interface Cast<TActor, TOpts> {
+  /** Provision every member of `spec` (in order) and remember them by name. */
+  build<const S extends Record<string, CastSpec<TOpts>>>(spec: S): Promise<{ [K in keyof S]: TActor; }>;
+  /** Provision one member. */
+  add(name: string, roles: readonly string[], opts?: TOpts): Promise<TActor>;
+  /** A provisioned member; throws a story-readable error when the name was never added. */
+  get(name: string): TActor;
+  names(): string[];
+}
+export declare function createCast<TActor, TOpts = undefined>(provision: (roles: readonly string[], opts: TOpts | undefined, name: string) => Promise<TActor>): Cast<TActor, TOpts>;
+/** `Authorization` headers for a bearer token. */
+export declare const bearer: (token: string) => Record<string, string>;
+/**
+ * A controllable clock with time-travel helpers, and the civil-date arithmetic a story needs to say
+ * "thirty days later" without drifting across a zone's day boundary. The clock satisfies
+ * `{ now(): Date }`, the shape hosts inject into their app; the story moves it, the app reads it.
+ */
+export interface StoryClock {
+  /** The `{ now }` the app reads. */
+  now(): Date;
+  /** The IANA zone civil dates are read in. */
+  readonly zone: string;
+  /** Jump to an instant. */
+  set(at: Date | string | number): void;
+  advanceMs(ms: number): void;
+  advanceDays(days: number): void;
+  /** Move to `hour:00` (default noon) in the zone on a civil date (`YYYY-MM-DD`). */
+  travelTo(day: string, hour?: number): Date;
+  /** The civil date now. */
+  today(): string;
+  /** Called after every move with the new instant. */
+  onChange(listener: (at: Date) => void): () => void;
+}
+export interface StoryClockOptions {
+  start?: Date | string | number;
+  /** IANA zone for civil dates. Default: UTC. */
+  zone?: string;
+}
+/** The civil date (`YYYY-MM-DD`) of an instant in a zone. */
+export declare function civilDateOf(at: Date, zone?: string): string;
+/** A civil date plus whole days. */
+export declare function addCivilDays(day: string, days: number): string;
+/** A civil date plus whole months (same day of month; keep stories off the 29th to 31st). */
+export declare function addCivilMonths(day: string, months: number): string;
+/** Whole days from civil date `a` to civil date `b`. */
+export declare function daysBetween(a: string, b: string): number;
+/** The instant at `hour:00` (default noon) on a civil date in a zone: a stable "that day". */
+export declare function instantOn(day: string, zone?: string, hour?: number): Date;
+export declare function createStoryClock(options?: StoryClockOptions): StoryClock;
+export interface IdempotencyOptions<TResult, TSnapshot> {
+  /** The sweep. */
+  run: () => Promise<TResult>;
+  /** What must be identical after run 1 and after run 2 (counts, ids, rows). */
+  snapshot: () => Promise<TSnapshot>;
+  /** Deliver asynchronous effects (outbox drain) before each snapshot. */
+  settle?: () => Promise<unknown>;
+  clauses?: Clauses;
+  /** Names the sweep in the failure. */
+  label?: string;
+}
+export interface IdempotencyOutcome<TResult, TSnapshot> {
+  first: TResult;
+  second: TResult;
+  afterFirst: TSnapshot;
+  afterSecond: TSnapshot;
+}
+/** Run twice; fail unless the snapshot after the second run equals the one after the first. */
+export declare function expectIdempotent<TResult, TSnapshot>(opts: IdempotencyOptions<TResult, TSnapshot>): Promise<IdempotencyOutcome<TResult, TSnapshot>>;
+/** {@link expectIdempotent} for several named sweeps sharing one snapshot. */
+export declare function expectSweepsIdempotent<TSnapshot>(sweeps: Readonly<Record<string, () => Promise<unknown>>>, common: Pick<IdempotencyOptions<unknown, TSnapshot>, "snapshot" | "settle" | "clauses">): Promise<void>;
+export {};

package/dist/story.mjs

@@ -0,0 +1,330 @@
+import { describe, expect, it, vi } from "vitest";
+// src/story/runner.ts
+/**
+* The step runner of an end-to-end story: one continuous scenario through a booted app, each step a
+* numbered vitest test whose failures name the clauses (requirements, contract lines) it proves.
+*
+*   describeStory("checkout", (s) => {
+*     s.step("customer places an order", { clauses: ["ORD-1"] }, async (t) => {
+*       t.expect(res.status, "the order is accepted").toBe(201);      // "[ORD-1] the order is accepted"
+*       t.known("DEF-7", rows.length, "one row per line").toBe(2);    // soft: reported, the step goes on
+*     });
+*   });
+*
+* Tests inside a file run in order, so a story's steps hand state to each other through the host's
+* own bag (`need` reads it with a clear error); once a step fails, later steps are skipped by
+* default rather than failing in confusing ways.
+*/
+/** `[REQ-1 | Reminders] the reminder reached the holder`. */
+function clauseMessage(clauses, what) {
+	const list = clauses === void 0 ? [] : typeof clauses === "string" ? [clauses] : [...clauses];
+	return list.length === 0 ? what : `[${list.join(" | ")}] ${what}`;
+}
+/**
+* A test function whose first parameter destructures `skip` and `fixtures`. Vitest reads that pattern
+* from the function's source to decide which fixtures to build, and it supports neither a rest element
+* nor a plain `ctx`, so the pattern is spelled out for the names the host lists.
+*/
+function withFixtures(fixtures, run) {
+	for (const name of fixtures) if (!/^[A-Za-z_$][\w$]*$/.test(name)) throw new Error(`"${name}" is not a fixture name`);
+	const names = ["skip", ...fixtures.filter((n) => n !== "skip")];
+	return new Function("run", `return async ({ ${names.join(", ")} }) => run({ ${names.join(", ")} });`)(run);
+}
+function listOf(clauses) {
+	return clauses === void 0 ? [] : typeof clauses === "string" ? [clauses] : [...clauses];
+}
+/** Registers a `describe` holding the story's numbered steps. */
+function describeStory(title, define, options = {}) {
+	const bail = options.bail ?? true;
+	let number = options.firstStep ?? 1;
+	let failedAt;
+	describe(title, () => {
+		define({
+			get next() {
+				return number;
+			},
+			step(stepTitle, a, b) {
+				const run = typeof a === "function" ? a : b;
+				const stepOptions = typeof a === "function" ? {} : a;
+				if (run === void 0) throw new Error(`step "${stepTitle}" has no body`);
+				const n = number++;
+				const clauses = [...listOf(options.clauses), ...listOf(stepOptions.clauses)];
+				const t = {
+					n,
+					title: stepTitle,
+					clauses,
+					msg: (what, extra) => clauseMessage([...clauses, ...listOf(extra)], what),
+					expect: (actual, what, extra) => expect(actual, clauseMessage([...clauses, ...listOf(extra)], what)),
+					soft: (actual, what, extra) => expect.soft(actual, clauseMessage([...clauses, ...listOf(extra)], what)),
+					known: (defect, actual, what, extra) => expect.soft(actual, clauseMessage([
+						`KNOWN DEFECT ${defect}`,
+						...clauses,
+						...listOf(extra)
+					], what))
+				};
+				(options.test ?? it)(`${n}. ${stepTitle}`, withFixtures(options.fixtures ?? [], async (ctx) => {
+					if (bail && failedAt !== void 0) ctx.skip(`step ${failedAt} failed; the story cannot continue`);
+					try {
+						await run(t, ctx);
+					} catch (error) {
+						failedAt ??= n;
+						throw error;
+					}
+				}), stepOptions.timeout);
+			}
+		});
+	});
+}
+/** Read a handed-over value, with an error that names the missing step instead of a bare `undefined`. */
+function need(bag, key) {
+	const value = bag[key];
+	if (value === void 0) throw new Error(`the story needs "${key}" from an earlier step (that step failed or did not run)`);
+	return value;
+}
+// src/story/assertions.ts
+/**
+* Story assertions against the places an app leaves evidence: the outbox / event log, a user's
+* in-app feed, the dev mail outbox and the audit rows. The kit knows none of them: the host injects
+* a reader per place (`StoryPorts`) and the assertions read through it. A missing port is an error
+* at the call, not a silent pass.
+*/
+/** True when `actual` carries every field of `expected` (RegExp and function leaves are tested, not compared). */
+function subsetMatches(actual, expected) {
+	if (expected instanceof RegExp) return typeof actual === "string" && expected.test(actual);
+	if (typeof expected === "function") return Boolean(expected(actual));
+	if (expected === null || typeof expected !== "object") return Object.is(actual, expected);
+	if (Array.isArray(expected)) return Array.isArray(actual) && expected.every((e) => actual.some((a) => subsetMatches(a, e)));
+	if (actual === null || typeof actual !== "object") return false;
+	return Object.entries(expected).every(([k, v]) => subsetMatches(actual[k], v));
+}
+function matches(row, match, keyField) {
+	if (typeof match === "string") return row[keyField] === match;
+	if (match instanceof RegExp) return typeof row[keyField] === "string" && match.test(row[keyField]);
+	if (typeof match === "function") return Boolean(match(row));
+	return subsetMatches(row, match);
+}
+function check(count, spec, what) {
+	const message = clauseMessage(spec.clauses, what);
+	if (spec.count !== void 0) expect(count, `${message} (expected exactly ${spec.count})`).toBe(spec.count);
+	else expect(count, `${message} (expected at least ${spec.min ?? 1})`).toBeGreaterThanOrEqual(spec.min ?? 1);
+}
+function port(value, name) {
+	if (value === void 0) throw new Error(`this story asserts on ${name}, but no \`${name}\` port was supplied`);
+	return value;
+}
+function createStoryAssertions(ports) {
+	const typeKey = ports.eventTypeKey ?? "type";
+	const eventsAfter = async (since = 0) => [...await port(ports.events, "events")()].slice(since);
+	const matching = async (rows, match, key) => [...await rows].filter((r) => matches(r, match, key));
+	const feedKey = () => "title";
+	const self = {
+		async drain(rounds = 3) {
+			const drain = port(ports.drain, "drain");
+			for (let i = 0; i < rounds; i += 1) await drain();
+		},
+		relayed(assertion, options = {}) {
+			return vi.waitFor(async () => {
+				await self.drain();
+				return assertion();
+			}, {
+				timeout: options.timeout ?? 3e4,
+				interval: options.interval ?? 50
+			});
+		},
+		async eventsOf(match, since) {
+			return matching(await eventsAfter(since), match, typeKey);
+		},
+		async expectEvent(match, spec = {}) {
+			const found = await self.eventsOf(match, spec.since);
+			check(found.length, spec, `event ${describeMatch(match)} was recorded`);
+			return found;
+		},
+		async expectNoEvent(match, spec = {}) {
+			const found = await self.eventsOf(match, spec.since);
+			expect(found.length, clauseMessage(spec.clauses, `no event ${describeMatch(match)} was recorded`)).toBe(0);
+		},
+		async feedOf(actor) {
+			return port(ports.feed, "feed")(actor);
+		},
+		async expectFeed(actor, match, spec = {}) {
+			const found = (await self.feedOf(actor)).filter((i) => matchesFeed(i, match, feedKey()));
+			check(found.length, spec, `the feed holds ${describeMatch(match)}`);
+			return found;
+		},
+		async expectNoFeed(actor, match, spec = {}) {
+			const found = (await self.feedOf(actor)).filter((i) => matchesFeed(i, match, feedKey()));
+			expect(found.length, clauseMessage(spec.clauses, `the feed holds no ${describeMatch(match)}`)).toBe(0);
+		},
+		async expectMail(match, spec = {}) {
+			const found = await matching(port(ports.mail, "mail")(), match, "subject");
+			check(found.length, spec, `a mail ${describeMatch(match)} was sent`);
+			return found;
+		},
+		async expectAudit(filter, match, spec = {}) {
+			const found = await matching(port(ports.audit, "audit")(filter), match, "action");
+			check(found.length, spec, `an audit row ${describeMatch(match)} exists`);
+			return found;
+		}
+	};
+	return self;
+}
+/** A feed item matches a string / RegExp on its title or message. */
+function matchesFeed(item, match, key) {
+	if (typeof match === "string" || match instanceof RegExp) return matches(item, match, key) || matches(item, match, "message");
+	return matches(item, match, key);
+}
+function describeMatch(match) {
+	if (typeof match === "string") return `"${match}"`;
+	if (match instanceof RegExp) return String(match);
+	if (typeof match === "function") return "(predicate)";
+	return JSON.stringify(match);
+}
+/** An in-memory event log fed by a tap on the host's event bus; the `events` port reads it. */
+function createEventLog() {
+	const events = [];
+	return {
+		record: (event) => void events.push(event),
+		all: () => events,
+		mark: () => events.length,
+		clear: () => {
+			events.length = 0;
+		},
+		tap(subscribe, patterns) {
+			for (const pattern of patterns) subscribe(pattern, (event) => void events.push(event));
+		}
+	};
+}
+// src/story/cast.ts
+function createCast(provision) {
+	const members = /* @__PURE__ */ new Map();
+	const add = async (name, roles, opts) => {
+		if (members.has(name)) throw new Error(`cast member "${name}" is already provisioned`);
+		const actor = await provision(roles, opts, name);
+		members.set(name, actor);
+		return actor;
+	};
+	return {
+		add,
+		async build(spec) {
+			const out = {};
+			for (const [name, entry] of Object.entries(spec)) {
+				const roles = Array.isArray(entry) ? entry : entry.roles;
+				const opts = Array.isArray(entry) ? void 0 : entry.opts;
+				out[name] = await add(name, roles, opts);
+			}
+			return out;
+		},
+		get(name) {
+			const actor = members.get(name);
+			if (actor === void 0) throw new Error(`the story needs cast member "${name}" (never provisioned)`);
+			return actor;
+		},
+		names: () => [...members.keys()]
+	};
+}
+/** `Authorization` headers for a bearer token. */
+const bearer = (token) => ({ authorization: `Bearer ${token}` });
+// src/story/clock.ts
+const MS_PER_DAY = 864e5;
+/** The civil date (`YYYY-MM-DD`) of an instant in a zone. */
+function civilDateOf(at, zone = "UTC") {
+	const parts = new Intl.DateTimeFormat("en-CA", {
+		timeZone: zone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit"
+	}).formatToParts(at);
+	const get = (type) => parts.find((p) => p.type === type)?.value ?? "";
+	return `${get("year")}-${get("month")}-${get("day")}`;
+}
+/** A civil date plus whole days. */
+function addCivilDays(day, days) {
+	return new Date(Date.parse(`${day}T00:00:00Z`) + days * MS_PER_DAY).toISOString().slice(0, 10);
+}
+/** A civil date plus whole months (same day of month; keep stories off the 29th to 31st). */
+function addCivilMonths(day, months) {
+	const [y, m, d] = day.split("-").map(Number);
+	return new Date(Date.UTC(y, m - 1 + months, d)).toISOString().slice(0, 10);
+}
+/** Whole days from civil date `a` to civil date `b`. */
+function daysBetween(a, b) {
+	return Math.round((Date.parse(`${b}T00:00:00Z`) - Date.parse(`${a}T00:00:00Z`)) / MS_PER_DAY);
+}
+function offsetMs(at, zone) {
+	const parts = new Intl.DateTimeFormat("en-US", {
+		timeZone: zone,
+		hourCycle: "h23",
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit"
+	}).formatToParts(new Date(at));
+	const get = (type) => Number(parts.find((p) => p.type === type)?.value);
+	return Date.UTC(get("year"), get("month") - 1, get("day"), get("hour"), get("minute"), get("second")) - Math.floor(at / 1e3) * 1e3;
+}
+/** The instant at `hour:00` (default noon) on a civil date in a zone: a stable "that day". */
+function instantOn(day, zone = "UTC", hour = 12) {
+	const guess = Date.parse(`${day}T00:00:00Z`) + hour * 36e5;
+	const first = guess - offsetMs(guess, zone);
+	return new Date(guess - offsetMs(first, zone));
+}
+function createStoryClock(options = {}) {
+	const zone = options.zone ?? "UTC";
+	let current = new Date(options.start ?? Date.now());
+	const listeners = /* @__PURE__ */ new Set();
+	const move = (to) => {
+		current = to;
+		for (const listener of listeners) listener(new Date(current));
+	};
+	return {
+		zone,
+		now: () => new Date(current),
+		set: (at) => move(new Date(at)),
+		advanceMs: (ms) => move(new Date(current.getTime() + ms)),
+		advanceDays: (days) => move(new Date(current.getTime() + days * MS_PER_DAY)),
+		travelTo: (day, hour = 12) => {
+			const at = instantOn(day, zone, hour);
+			move(at);
+			return new Date(at);
+		},
+		today: () => civilDateOf(current, zone),
+		onChange: (listener) => {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		}
+	};
+}
+// src/story/idempotency.ts
+/**
+* Run-twice idempotency for sweeps: run a scheduled job twice on the same clock day and prove the
+* second run changed nothing (no duplicate assignments, notifications, mails). The host supplies the
+* job and a `snapshot` of whatever must not grow; the kit compares.
+*/
+/** Run twice; fail unless the snapshot after the second run equals the one after the first. */
+async function expectIdempotent(opts) {
+	const first = await opts.run();
+	await opts.settle?.();
+	const afterFirst = await opts.snapshot();
+	const second = await opts.run();
+	await opts.settle?.();
+	const afterSecond = await opts.snapshot();
+	const label = opts.label ?? "the sweep";
+	expect(afterSecond, clauseMessage(opts.clauses, `${label} run twice on one day changes nothing the second time`)).toEqual(afterFirst);
+	return {
+		first,
+		second,
+		afterFirst,
+		afterSecond
+	};
+}
+/** {@link expectIdempotent} for several named sweeps sharing one snapshot. */
+async function expectSweepsIdempotent(sweeps, common) {
+	for (const [label, run] of Object.entries(sweeps)) await expectIdempotent({
+		...common,
+		run,
+		label
+	});
+}
+export { addCivilDays, addCivilMonths, bearer, civilDateOf, clauseMessage, createCast, createEventLog, createStoryAssertions, createStoryClock, daysBetween, describeStory, expectIdempotent, expectSweepsIdempotent, instantOn, need, subsetMatches };

package/llms.txt

@@ -0,0 +1,33 @@
+# @classytic/arc-testkit
+
+> Test harness for arc apps: boot modules on in-memory MongoDB, pool servers, cost and plan asserts,
+> conformance guards and a story kit. Needs @classytic/arc >=2.49.0 for the root entry (an optional peer); the guards and stories need vitest >=4.1.11.
+
+Hand-rolling any row below is a bug. Skill: skills/arc-testkit/SKILL.md (+ references/).
+
+| Need | Use | Import |
+|---|---|---|
+| Boot module(s) on a real DB | bootModuleApp | @classytic/arc-testkit |
+| One mongod per run, DB per file | createTestDatabasePool, mongoServerProvider | /pool, /mongo |
+| Worker cap by cores and RAM | safeWorkerCount | /mongo |
+| Wait for index builds | awaitIndexBuilds | /mongo |
+| N+1 detection | countCommands, assertConstantCommands | /mongo-commands |
+| Index plan proof | assertIndexServed, summarizeExplain, explainCaptured | /mongo-explain |
+| List routes answer the repo-core envelope | checkListEnvelopes, registerListEnvelopeGuard | /conformance |
+| Actions and write routes have schemas | checkRouteSchemas, registerRouteSchemaGuard | /conformance |
+| Verb and route-family naming | checkNaming, registerNamingGuard | /conformance |
+| OpenAPI shape, security, secrets | checkOpenApiShape, checkSecurity, checkRoutesDocumented, checkAnonymousRefused, checkNoSecrets, registerOpenApiGuard | /conformance |
+| List filters match the route | checkFilterDeclarations | /conformance |
+| Client routes exist in the spec | checkClientDrift, registerClientDriftGuard, dumpOpenApi, loadOpenApiDump | /conformance |
+| Error bodies are ErrorContract | checkErrorContracts, expectErrorContract, registerErrorContractGuard | /conformance |
+| Bare collection paths | checkCollectionRoutes, registerCollectionRoutesGuard | /conformance |
+| Refusal leaves no side effect | registerRefusalDoesNoWorkGuard | /conformance |
+| App as caller, spec, route table | injectCaller, fetchOpenApi, routeTable, expectClean | /conformance |
+| Numbered, clause-tagged steps | describeStory, need, clauseMessage | /story |
+| Users with roles | createCast, bearer | /story |
+| Time travel, civil dates | createStoryClock, civilDateOf, addCivilDays, addCivilMonths, daysBetween, instantOn | /story |
+| Outbox, events, feed, mail, audit asserts | createStoryAssertions, createEventLog | /story |
+| Sweep twice changes nothing | expectIdempotent, expectSweepsIdempotent | /story |
+
+Rules: every guard is check* (returns problems) + register* (vitest tests); exception lists fail when stale;
+fixture-based hosts call check* then expectClean inside the test; pass getters, not values, for an app booted in beforeAll.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-testkit",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Boot a real @classytic/arc app around the module(s) under test on in-memory MongoDB — the ecosystem test harness. Thin Mongo-typed wrapper over @classytic/arc/testing (arc 2.22+). If your arc module boots green here, it composes into any arc host.",
   "type": "module",
   "exports": {
@@ -8,6 +8,14 @@
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
     },
+    "./conformance": {
+      "types": "./dist/conformance.d.mts",
+      "default": "./dist/conformance.mjs"
+    },
+    "./story": {
+      "types": "./dist/story.d.mts",
+      "default": "./dist/story.mjs"
+    },
     "./pool": {
       "types": "./dist/pool.d.mts",
       "default": "./dist/pool.mjs"
@@ -29,6 +37,8 @@
   "types": "./dist/index.d.mts",
   "sideEffects": false,
   "files": [
+    "skills",
+    "llms.txt",
     "dist",
     "README.md"
   ],
@@ -41,6 +51,7 @@
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc --noEmit",
+    "check:skills": "vitest run --root ../.. packages/arc-testkit/tests/skills.test.ts",
     "test": "vitest run --root ../.. packages/arc-testkit/tests",
     "lint": "biome check src/",
     "prepublishOnly": "node ../../scripts/prepublish-gate.mjs"
@@ -49,8 +60,20 @@
     "mongodb-memory-server": ">=10.0.0"
   },
   "peerDependencies": {
-    "@classytic/arc": ">=2.43.0",
-    "mongoose": ">=9.4.1"
+    "vitest": ">=4.1.11",
+    "@classytic/arc": ">=2.49.0",
+    "mongoose": ">=9.11.4"
+  },
+  "peerDependenciesMeta": {
+    "@classytic/arc": {
+      "optional": true
+    },
+    "mongoose": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
   },
   "keywords": [
     "arc",