@classytic/arc-testkit 0.5.0 → 0.6.0

package/dist/index.d.mts

@@ -1,10 +1,8 @@
 import { BootModuleAppOptions as BootModuleAppOptions$1, BootModulesInput, ModuleTestApp as ModuleTestApp$1, TestkitContext as TestkitContext$1 } from "@classytic/arc/testing";
 import { Connection } from "mongoose";
-//#region src/index.d.ts
 type TestkitContext = TestkitContext$1<Connection>;
 type ModulesInput = BootModulesInput<Connection>;
 type BootModuleAppOptions = BootModuleAppOptions$1<Connection>;
 type ModuleTestApp = ModuleTestApp$1<Connection>;
 declare function bootModuleApp(modules: ModulesInput, options?: BootModuleAppOptions): Promise<ModuleTestApp>;
-//#endregion
 export { BootModuleAppOptions, ModuleTestApp, ModulesInput, TestkitContext, bootModuleApp };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { bootModuleApp as bootModuleApp$1 } from "@classytic/arc/testing";
-//#region src/index.ts
+// src/index.ts
 /**
 * @classytic/arc-testkit — boots a REAL arc app around the module(s) under
 * test on in-memory MongoDB. The contributor contract: if your module boots
@@ -23,5 +23,4 @@ import { bootModuleApp as bootModuleApp$1 } from "@classytic/arc/testing";
 function bootModuleApp(modules, options = {}) {
 	return bootModuleApp$1(modules, options);
 }
-//#endregion
 export { bootModuleApp };

package/dist/mongo-commands.d.mts

@@ -1,5 +1,4 @@
 import { Connection } from "mongoose";
-//#region src/mongo-commands.d.ts
 type MongoClientLike = ReturnType<Connection["getClient"]>;
 interface CountCommandsOptions {
   /** Count only commands against these collections. */
@@ -25,5 +24,4 @@ interface CommandCount<T> {
 }
 declare function countCommands<T>(source: Connection | MongoClientLike, fn: () => Promise<T>, options?: CountCommandsOptions): Promise<CommandCount<T>>;
 declare function assertConstantCommands<T>(source: Connection | MongoClientLike, run: (size: number) => Promise<T>, sizes: readonly number[], options?: CountCommandsOptions): Promise<readonly CommandCount<T>[]>;
-//#endregion
 export { CommandCount, CountCommandsOptions, WireCommand, assertConstantCommands, countCommands };

package/dist/mongo-commands.mjs

@@ -1,4 +1,4 @@
-//#region src/mongo-commands.ts
+// src/mongo-commands.ts
 async function countCommands(source, fn, options = {}) {
 	const client = "getClient" in source ? source.getClient() : source;
 	if (client.options.monitorCommands !== true) throw new Error("[arc-testkit] countCommands: the client was created without `monitorCommands: true` — the driver emits no command events, so every count would read 0");
@@ -50,5 +50,4 @@ function tally(keys) {
 	for (const k of keys) out[k] = (out[k] ?? 0) + 1;
 	return out;
 }
-//#endregion
 export { assertConstantCommands, countCommands };

package/dist/mongo-explain.d.mts

@@ -1,4 +1,3 @@
-//#region src/mongo-explain.d.ts
 /**
  * Read a MongoDB `explain()` result — find, aggregate, classic or SBE — as the WINNING plan's stage
  * names, the indexes it scans, and its execution stats (`executionStats` verbosity). Rejected plans
@@ -30,5 +29,4 @@ interface IndexServedOptions {
 }
 declare function summarizeExplain(explain: unknown): ExplainSummary;
 declare function assertIndexServed(explain: unknown, options?: IndexServedOptions): ExplainSummary;
-//#endregion
 export { ExplainSummary, IndexServedOptions, assertIndexServed, summarizeExplain };

package/dist/mongo-explain.mjs

@@ -1,4 +1,4 @@
-//#region src/mongo-explain.ts
+// src/mongo-explain.ts
 /** Keys whose subtree is a rejected alternative or a query predicate — never plan structure. */
 const SKIPPED = /* @__PURE__ */ new Set([
 	"rejectedPlans",
@@ -63,5 +63,4 @@ function isRecord(value) {
 function numberOr(value) {
 	return typeof value === "number" ? value : void 0;
 }
-//#endregion
 export { assertIndexServed, summarizeExplain };

package/dist/mongo.d.mts

@@ -1,6 +1,5 @@
 import { TestServerProvider } from "./pool.mjs";
 import { Connection } from "mongoose";
-//#region src/mongo.d.ts
 /** WiredTiger cache per server, in GB. 0.25 is mongod's own floor. */
 declare function cacheSizeGB(): number;
 /** mongod CLI args that bound a test server's footprint. */
@@ -83,5 +82,4 @@ interface MongoServerProviderOptions {
  * pool serve both kinds from one process when sharing is on.
  */
 declare function mongoServerProvider(options?: MongoServerProviderOptions): TestServerProvider<Connection>;
-//#endregion
 export { MongoServerProviderOptions, MongooseLike, awaitIndexBuilds, cacheSizeGB, mongoServerProvider, mongodMemoryArgs, safePoolSize, safeWorkerCount, withDbName };

package/dist/mongo.mjs

@@ -1,5 +1,5 @@
 import { cpus, freemem, totalmem } from "node:os";
-//#region src/mongo.ts
+// src/mongo.ts
 /**
 * `@classytic/arc-testkit/mongo` — the Mongo adapter for the driver-agnostic pool.
 *
@@ -225,5 +225,4 @@ function mongoServerProvider(options = {}) {
 		}
 	};
 }
-//#endregion
 export { awaitIndexBuilds, cacheSizeGB, mongoServerProvider, mongodMemoryArgs, safePoolSize, safeWorkerCount, withDbName };

package/dist/pool.d.mts

@@ -1,5 +1,4 @@
 import { TestDatabase, TestDatabaseFactory } from "@classytic/arc/testing";
-//#region src/pool.d.ts
 /** Which server shape a suite needs. */
 type ServerKind = "standalone" | "transactional";
 /** A running server the pool may hand out namespaces on. */
@@ -186,5 +185,4 @@ declare function createTestDatabasePool<TConn>(provider: TestServerProvider<TCon
  * `globalSetup` in a run that prefers boot-cost-up-front over laziness.
  */
 declare function publishPoolServers(servers: Partial<Record<ServerKind, readonly string[]>>, envPrefix?: string): void;
-//#endregion
 export { ServerKind, TestDatabasePool, TestDatabasePoolOptions, TestServerHandle, TestServerProvider, createTestDatabasePool, publishPoolServers };

package/dist/pool.mjs

@@ -1,8 +1,8 @@
-import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
 import { join } from "node:path";
-//#region src/pool.ts
+import { randomBytes } from "node:crypto";
+import { tmpdir } from "node:os";
+// src/pool.ts
 /**
 * `@classytic/arc-testkit/pool` — a POOLED `TestDatabaseFactory`, driver-agnostic.
 *
@@ -406,5 +406,4 @@ function publishPoolServers(servers, envPrefix = "ARC_TESTKIT") {
 	}
 	writeFileSync(file, JSON.stringify(servers));
 }
-//#endregion
 export { createTestDatabasePool, publishPoolServers };

package/dist/story.d.mts

@@ -0,0 +1,202 @@
+import { expect } from "vitest";
+type Clauses = string | readonly string[];
+/** `[REQ-1 | Reminders] the reminder reached the holder`. */
+declare function clauseMessage(clauses: Clauses | undefined, what: string): string;
+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>>;
+}
+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`). */
+type StepBody<Ctx> = (t: StepContext, ctx: Ctx) => void | Promise<void>;
+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. */
+type StepRegistrar<Ctx> = (name: string, fn: (ctx: Ctx & {
+  skip(note?: string): never;
+}) => Promise<void>, timeout?: number) => unknown;
+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. */
+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`. */
+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. */
+type RowMatch = string | RegExp | ((row: never) => boolean) | Row;
+interface FeedItem {
+  title?: string;
+  message?: string;
+  [key: string]: unknown;
+}
+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;
+}
+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;
+}
+interface RelayOptions {
+  timeout?: number;
+  interval?: number;
+}
+/** True when `actual` carries every field of `expected` (RegExp and function leaves are tested, not compared). */
+declare function subsetMatches(actual: unknown, expected: unknown): boolean;
+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[]>;
+}
+declare function createStoryAssertions<TActor = unknown>(ports: StoryPorts<TActor>): StoryAssertions<TActor>;
+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. */
+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).
+ */
+interface CastSpecEntry<TOpts> {
+  roles: readonly string[];
+  opts?: TOpts;
+}
+/** `roles` shorthand, or `{ roles, opts }` when the host's provisioner takes options (e.g. `{ mfa: false }`). */
+type CastSpec<TOpts> = readonly string[] | CastSpecEntry<TOpts>;
+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[];
+}
+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. */
+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.
+ */
+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;
+}
+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. */
+declare function civilDateOf(at: Date, zone?: string): string;
+/** A civil date plus whole days. */
+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). */
+declare function addCivilMonths(day: string, months: number): string;
+/** Whole days from civil date `a` to civil date `b`. */
+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". */
+declare function instantOn(day: string, zone?: string, hour?: number): Date;
+declare function createStoryClock(options?: StoryClockOptions): StoryClock;
+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;
+}
+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. */
+declare function expectIdempotent<TResult, TSnapshot>(opts: IdempotencyOptions<TResult, TSnapshot>): Promise<IdempotencyOutcome<TResult, TSnapshot>>;
+/** {@link expectIdempotent} for several named sweeps sharing one snapshot. */
+declare function expectSweepsIdempotent<TSnapshot>(sweeps: Readonly<Record<string, () => Promise<unknown>>>, common: Pick<IdempotencyOptions<unknown, TSnapshot>, "snapshot" | "settle" | "clauses">): Promise<void>;
+export { Cast, CastSpec, CastSpecEntry, Clauses, EventLog, Expectation, FeedItem, IdempotencyOptions, IdempotencyOutcome, RelayOptions, RowMatch, StepBody, StepContext, StepOptions, StepRegistrar, Story, StoryAssertions, StoryClock, StoryClockOptions, StoryOptions, StoryPorts, addCivilDays, addCivilMonths, bearer, civilDateOf, clauseMessage, createCast, createEventLog, createStoryAssertions, createStoryClock, daysBetween, describeStory, expectIdempotent, expectSweepsIdempotent, instantOn, need, subsetMatches };

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 };