@classytic/arc-testkit 0.4.0 → 0.6.0

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.43.0; the guards and stories need vitest >=3.
+
+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 | /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.4.0",
+  "version": "0.6.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"
@@ -15,12 +23,22 @@
     "./mongo": {
       "types": "./dist/mongo.d.mts",
       "default": "./dist/mongo.mjs"
+    },
+    "./mongo-commands": {
+      "types": "./dist/mongo-commands.d.mts",
+      "default": "./dist/mongo-commands.mjs"
+    },
+    "./mongo-explain": {
+      "types": "./dist/mongo-explain.d.mts",
+      "default": "./dist/mongo-explain.mjs"
     }
   },
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "sideEffects": false,
   "files": [
+    "skills",
+    "llms.txt",
     "dist",
     "README.md"
   ],
@@ -33,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"
@@ -41,8 +60,17 @@
     "mongodb-memory-server": ">=10.0.0"
   },
   "peerDependencies": {
-    "@classytic/arc": ">=2.33.0",
-    "mongoose": ">=9.4.1"
+    "vitest": ">=5.0.5",
+    "@classytic/arc": ">=2.46.0",
+    "mongoose": ">=9.11.4"
+  },
+  "peerDependenciesMeta": {
+    "mongoose": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
   },
   "keywords": [
     "arc",

package/skills/arc-testkit/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: arc-testkit
+description: |
+  @classytic/arc-testkit - test harness for arc apps: boot modules on in-memory MongoDB, pool servers, count wire commands, assert index plans, conformance guards (list envelope, route schemas, naming, OpenAPI, client drift, error contract), story kit (cast, clock, steps, evidence asserts). Triggers: arc-testkit, bootModuleApp, conformance, story test.
+license: MIT
+metadata:
+  author: Classytic
+  minVersion: "0.6.0"
+---
+
+# @classytic/arc-testkit
+
+Needs `@classytic/arc >=2.43.0`; `mongoose >=9.4.1` for root, `/pool`, `/mongo*`; `/conformance` and `/story` need `vitest >=3` only. Guards are `check*` (returns problems) plus `register*` (vitest tests).
+
+## Do not hand-roll
+
+| Need | Use | Import |
+|---|---|---|
+| Boot module(s) on a real DB | `bootModuleApp(modules, options)` | `@classytic/arc-testkit` |
+| One mongod per run, one DB per file | `createTestDatabasePool`, `mongoServerProvider` | `/pool`, `/mongo` |
+| Worker cap by cores and RAM | `safeWorkerCount(envVar)` | `/mongo` |
+| Wait for index builds | `awaitIndexBuilds` | `/mongo` |
+| Count driver commands (N+1) | `countCommands`, `assertConstantCommands` | `/mongo-commands` |
+| Prove a query uses an index | `assertIndexServed`, `summarizeExplain` | `/mongo-explain` |
+| Every list answers the repo-core envelope | `checkListEnvelopes`, `registerListEnvelopeGuard` | `/conformance` |
+| Every action/write route has a schema | `checkRouteSchemas`, `registerRouteSchemaGuard` | `/conformance` |
+| Verb and route-family naming | `checkNaming`, `registerNamingGuard` | `/conformance` |
+| OpenAPI shape, security, secrets | `checkOpenApiShape`, `checkSecurity`, `checkRoutesDocumented`, `checkAnonymousRefused`, `checkNoSecrets`, `registerOpenApiGuard` | `/conformance` |
+| Client routes exist in the spec | `checkClientDrift`, `registerClientDriftGuard`, `dumpOpenApi`, `loadOpenApiDump` | `/conformance` |
+| List filters match the route | `checkFilterDeclarations` | `/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, routes | `injectCaller(app, headers)`, `fetchOpenApi(caller)`, `routeTable(app)`, `expectClean(what, problems)` | `/conformance` |
+| Numbered, clause-tagged story steps | `describeStory`, `need`, `clauseMessage` | `/story` |
+| Named 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 run twice changes nothing | `expectIdempotent`, `expectSweepsIdempotent` | `/story` |
+
+## Golden path
+
+Boot (`replset: true` only for transactions):
+
+```ts
+import { bootModuleApp } from "@classytic/arc-testkit";
+
+const t = await bootModuleApp(({ connection }) => [createThingModule({ connection, permissions })], { replset: true });
+const res = await t.app.inject({ method: "GET", url: "/things" });
+await t.close();
+```
+
+Pool (vitest `globalSetup` exports `setup`/`teardown`; suites boot through `withPool`):
+
+```ts
+import { mongoServerProvider } from "@classytic/arc-testkit/mongo";
+import { createTestDatabasePool } from "@classytic/arc-testkit/pool";
+import mongoose from "mongoose";
+
+export const dbPool = createTestDatabasePool(mongoServerProvider({ mongoose }), { envPrefix: "APP_TEST", preboot: ["transactional"] });
+export const setup = () => dbPool.globalSetup.setup();
+export const teardown = () => dbPool.globalSetup.teardown();
+// suite: const boot = dbPool.withPool(bootModuleApp);   vitest config: maxWorkers: safeWorkerCount("TEST_MAX_WORKERS")
+```
+
+Guards inside a test with the app and an admin caller:
+
+```ts
+import { checkListEnvelopes, checkSecurity, expectClean, fetchOpenApi } from "@classytic/arc-testkit/conformance";
+
+test("contract", async () => {
+  expectClean("list envelope", (await checkListEnvelopes({ app: t.app, caller: admin, prefix: "/api", notLists: { "/api/me": "one document" } })).problems);
+  expectClean("security", await checkSecurity({ spec: await fetchOpenApi(admin), publicOperations: [{ path: "/api/health", why: "probe" }] }));
+});
+```
+
+Story:
+
+```ts
+import { createCast, describeStory } from "@classytic/arc-testkit/story";
+
+describeStory("checkout", (s) => {
+  s.step("customer places an order", { clauses: ["ORD-1"] }, async (t) => {
+    const res = await cast.get("ann").post("/orders", {});
+    t.expect(res.status, "the order is accepted").toBe(201);
+  });
+});
+```
+
+## Gotchas
+
+- Exception lists (`notLists`, `customShapes`, `actionExceptions`, `routeExceptions`, `exemptVerbs`, `publicOperations`) fail when an entry matches nothing: delete the entry, never keep it "just in case".
+- `register*` runs at describe time with getters (`app: () => t.app`, app booted in `beforeAll`). Fixture-based hosts (`test.extend`) use `check*` + `expectClean` inside the test, or pass `test` and `fixtures` to `describeStory`.
+- `checkListEnvelopes` skips non-200 GETs and paths with params; set `minRoutes` and `expectLists` so an empty probe cannot pass.
+- `checkErrorContracts` needs a probe per class (`require` narrows them); its unknown-route probe also fails when the query string is echoed.
+- Fastify's own 404 body fails the contract: set a not-found handler.
+- `checkRouteSchemas` reads `app.arc.registry`: the app must be booted by arc.
+- A pool needs `globalSetup` to preboot, else every worker boots its own mongod. `countCommands` needs `monitorCommands: true`.
+- `loadOpenApiDump` throws when the dump is older than the `.ts` under `sources`: regenerate it.
+
+## Never
+
+- Hand-roll a route-table parser, OpenAPI walker or per-file `MongoMemoryServer`.
+- Import from `dist/` or `src/` paths; use the subpaths above only.
+- Assert `ErrorContract` bodies field by field; use `expectErrorContract`.
+- Put domain rules in the kit.
+
+## References
+
+- `references/fixtures.md` - read when booting apps, pooling servers, capping workers, counting commands or asserting plans.
+- `references/conformance.md` - read when adding a guard: what it enforces, every parameter, how to read its failure.
+- `references/story.md` - read when writing a story test: cast, clock, steps, ports, idempotency.
+- `references/list-filters.md` - read when a UI sends list filters, search or sorts.

package/skills/arc-testkit/references/conformance.md

@@ -0,0 +1,104 @@
+# Conformance guards (`@classytic/arc-testkit/conformance`)
+
+Common shapes. `Source<T>` is a value or `() => T | Promise<T>`. `app` is the booted Fastify instance (anything with
+`inject` and `printRoutes`). `Caller` is `{ get(path) }` returning `{ status, body }`; a host test client fits, or build
+one with `injectCaller(app, { authorization: "Bearer ..." })` (adds `post`, `put`, `patch`, `delete`, `request`).
+`Exceptions` is `string[]`, a `Set`, or `Record<key, reason>`. Each `check*` returns `string[]` (problems);
+`register*` wraps it in `it(...)`; `expectClean(what, problems)` fails with one problem per line.
+
+## List envelope
+
+`checkListEnvelopes(opts)` returns `{ problems, lists, probed }`. Calls every static GET (no `:` or `*`) as `caller`; a
+200 body must be an offset page (`method: "offset"`, numeric `page limit total pages`, boolean `hasNext hasPrev`), a
+keyset page (`limit`, boolean `hasMore`, `next` string or null) or exactly `{ data: [...] }`.
+
+| Option | Meaning |
+|---|---|
+| `app`, `caller` | required; caller must be allowed to read every list |
+| `prefix` | only GET paths starting with it |
+| `notLists` | GETs that are not lists (single documents, tables), with reason |
+| `customShapes` | GETs that answer their own shape (package routes) |
+| `skip` | RegExp of paths never probed; default `/(stream\|export\|content\|download)(/\|$)` |
+| `forbiddenKeys` | keys a list never carries; default `docs rows items pagination totalPages` |
+| `methods` | accepted `method` values; default offset and keyset |
+| `minRoutes`, `expectLists` | probe size floor; paths that must have answered a list |
+
+Failures: `PATH: a bare array`; `PATH: not a list and not in notLists (keys)`; `PATH: carries docs`; `PATH: offset page:
+\`total\` is not a number`; `stale exception PATH: no such GET route is registered`. Non-200 answers are skipped, so
+a route needing a filter is never reported: assert it separately.
+
+## Route schemas
+
+`checkRouteSchemas({ app, actionExceptions, routeExceptions, bodyMethods, minActions })` returns
+`{ problems, actions, routes }`. Reads `app.arc.registry.getAll()`. Every action needs `schema`; every custom route with
+method in `bodyMethods` (default POST PUT PATCH) needs `schema.body`. Keys: actions `resource.action`, routes
+`resource METHOD /path` (path as declared on the resource, e.g. `thing POST /import`). Failures: `action thing.archive
+declares no schema (add it to actionSchemas)`, `route thing POST /recompute declares no body schema`, `stale action
+exception KEY`, `stale route exception KEY`. Use an exception only for package-mounted routes and routes without a
+JSON body (multipart), with the reason as the record value.
+
+## Naming
+
+`checkNaming({ app, verbPattern, exemptVerbs, requiredVerbs, minVerbs, pathRules, forbiddenPaths })` returns problems.
+`verbPattern` default `/^[a-z][a-zA-Z0-9]*$/` (camelCase action verbs). `pathRules`: `[{ name, match: RegExp, allowed:
+["POST /api/x/sweep"] }]`; every route whose path matches belongs to the family and the set must equal `allowed`
+(HEAD and OPTIONS ignored). `forbiddenPaths`: RegExps no route may match. Failures: `action r.set_due does not match
+...`, `sweeps: unexpected route POST ...`, `sweeps: missing route ...`, `stale exempt verb v`.
+
+## OpenAPI
+
+Options (`OpenApiOptions`): `spec` (document or getter; `fetchOpenApi(caller, path = "/openapi.json")`), `app`,
+`anonymous` (unauthenticated caller), `prefix`, `publicOperations: [{ path: string | RegExp | fn, why }]`,
+`undocumented` (RegExp of route-table paths not required in the spec), `skipAnonymous` (default `/\{|\/stream$/`),
+`minOperations`, `secretValues` (strings of length 6 or more), `secretPatterns` (default mongodb and redis URLs).
+
+| Function | Enforces | Failure text |
+|---|---|---|
+| `checkOpenApiShape` | `openapi` 3.x, paths under `prefix` (public ones exempt), no trailing slash, `minOperations` | `PATH is outside the /api prefix` |
+| `checkRoutesDocumented` | needs `app`; every route-table method+path (shape-normalised) is in the spec | `GET /x is not in the document` |
+| `checkSecurity` | each operation has `security` (own, else document-level) unless a public rule matches; unused rule fails | `GET /x has no security requirement`, `stale public operation (why): ...` |
+| `checkAnonymousRefused(opts, 401)` | needs `anonymous`; GET of each protected, param-free path answers 401 | `GET /x -> 200, expected 401` |
+| `checkNoSecrets` | no `secretValues` entry or pattern in the serialised spec | `a configuration value is in the document` |
+
+`registerOpenApiGuard(opts)` registers all five (the two with optional input only when `app` / `anonymous` is given).
+
+## Client drift
+
+`checkClientDrift({ spec, routes, bodyFields, minRoutes })`. `routes`: `[{ method, path, source? }]` the client can emit;
+a path may be concrete (`/api/x/507f...`), a template (`/api/x/:id`, `/api/x/{id}`), with a query or trailing slash.
+`bodyFields`: `[{ method, path: "/api/x/{id}/action", fields: [...], in: "request" | "response", status: "200", name? }]`
+(path spelled as the spec does; fields resolved through `$ref`, `oneOf`, `allOf`, `anyOf`). Failures: `client route
+missing from the document: DELETE /api/x/:id/archive   (source)`, `NAME: field "f" is not in the schema`, `NAME: the
+document declares no request schema`. Carry the spec between processes: `dumpOpenApi(spec, file)` on the server,
+`loadOpenApiDump(file, { sources: [dirs], regenerate: "cd apps/server && npm run openapi:dump" })` on the client; it throws
+when the dump is missing or older than a `.ts` under `sources`. Exported helpers: `specMatcher`, `missingClientRoutes`,
+`bodyFieldProblems`, `propertyNames`, `resolveRef`. Needs the node environment (reads files).
+
+## Error contract
+
+`checkErrorContracts({ probes, caller, require, allowedKeys })`. Classes: `validation unauthorized forbidden notFound
+unknownRoute conflict duplicateKey`. A probe is `{ provoke: () => Promise<Reply>, status?, code?: string | RegExp,
+details?: "some" | "none", detailCode? }` or an array of them. Defaults: status 400/401/403/404/404/409/409, `details:
+"some"` for validation and duplicateKey, `detailCode: "duplicate_key"` for duplicateKey, `code` any non-empty string.
+`require` (default all seven) lists classes that must have a probe; `unknownRoute` has a built-in probe when `caller`
+is given. The body may carry only `code message status details correlationId meta` (details only `path code message
+meta`). Failures are prefixed with the class: `unknownRoute: foreign keys on the body: error, statusCode`, `validation:
+code "x", expected "y"`, `duplicateKey: a detail has code "z", expected "duplicate_key"`. Single replies:
+`errorContractProblems(reply, expected)` and `expectErrorContract(reply, { status, code, details })` (returns the body).
+
+## Collection routes
+
+`checkCollectionRoutes({ app, collections: [{ path: "/api/x", methods: ["GET", "POST"] }], served: { caller, paths } })`.
+The bare path must be registered with each verb; `served` GETs must answer 200. Failures: `POST /api/x is not
+registered`, `/api/x/: a collection is addressed by its bare path`, `GET /api/x answered 401`.
+
+## Refusal does no work
+
+`checkRefusalDoesNoWork({ app, anonymous, unprivileged, snapshot, routes, prefix, exclude, paramValue, refusedStatuses, settleMs, minRoutes })`.
+Calls every mutating route (default: POST PUT PATCH DELETE of the route table, `:param` filled with `paramValue`; or
+`routes: [{ method, path, body? }]`) as `anonymous` and as `unprivileged` (`InjectCaller`s). Each call must answer
+401/403 and leave `snapshot()` (host state: row counts, a phase, an outbox length) deep-equal before and after. A gate
+that only calls `reply.send` still answers 403 when 2+ async `preSerialization`/`onSend` hooks defer the write, yet the
+handler runs: only the snapshot shows it. `exclude`: `METHOD /path` keys that accept the caller, with the reason.
+Failures: `anonymous POST /x: answered 403 but the snapshot changed: the handler ran after the refusal`, `unprivileged
+PATCH /x/1: answered 200, expected a refusal (401/403)`, `stale exclusion KEY`. Fix: `return reply.send(...)` or throw.