@classytic/arc-testkit 0.5.0 → 0.7.0

package/skills/arc-testkit/SKILL.md

@@ -0,0 +1,112 @@
+---
+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
+
+Root needs `@classytic/arc >=2.49.0`; `mongoose >=9.11.4` for root, `/pool`, `/mongo*`; `/conformance`, `/story` need only `vitest >=4.1.11`. Guards are `check*` (returns problems) + `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` |
+| Query uses an index | `assertIndexServed`, `summarizeExplain`, `explainCaptured` | `/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,105 @@
+# 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...`) or a template (`:id`, `{id}`), with a query or trailing slash.
+`bodyFields`: `[{ method, path: "/api/x/{id}/action", fields: [...], values?: [...], in: "request" | "response", status: "200", name? }]`
+(path as the spec spells it; through `$ref`, `oneOf`, `allOf`, `anyOf`; `values`: sent `enum`/`const` literals). 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`. Across 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`. Helpers: `specMatcher`, `missingClientRoutes`,
+`bodyFieldProblems`, `propertyNames`, `schemaValues`, `resolveRef`. Node environment.
+
+## 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, actionBodies, refusedStatuses, settleMs, minRoutes, name })`.
+Calls every mutating route (default: POST PUT PATCH DELETE of the route table; or `routes: [{ method, path, body? }]`)
+as `anonymous` and `unprivileged`; each must answer 401/403 and leave `snapshot()` deep-equal. A gate that only calls
+`reply.send` answers 403 while the handler still runs: only the snapshot shows it.
+`paramValue`: id or `({ method, path, resource }) => id`. `exclude`: `METHOD /path` or `resource.verb` keys with the
+reason, one list or `{ anonymous, unprivileged }`. `actionBodies: { "resource.verb": body | (ctx) => body }`: one call
+per verb on each action route (`{}` alone is a 400); no body fails. `name` titles the test.
+Failures: `anonymous POST /x: answered 403 but the snapshot changed`, `unprivileged PATCH /x/1: answered 200, expected
+a refusal (401/403)`, `stale exclusion KEY`. Fix: `return reply.send(...)` or throw.

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

@@ -0,0 +1,104 @@
+# Fixtures: boot, pool, workers, cost and plan asserts
+
+## bootModuleApp (`@classytic/arc-testkit`)
+
+`bootModuleApp(modules, options?)` boots arc (`preset: "testing"`, `auth: false`, `sensible: false`) around module(s) on
+in-memory MongoDB and returns `{ app, uri, connection, exports(name), close() }` (`close` is idempotent).
+
+`modules` is a module, an array, or a factory `({ connection, mongoUri }) => module | module[]`.
+`options`: `replset` (single-node replica set, needed for transactions), `database` (a `TestDatabaseFactory`, e.g.
+`pool.factory`), `app` (extra `createApp` options merged over the defaults), `actor` (default actor for requests without
+an `x-test-actor` header), `ports` (host ports for the modules).
+
+```ts
+const t = await bootModuleApp(({ connection }) => [createThingModule({ connection, permissions })], { replset: true });
+const engine = t.exports<ThingEngine>("thing"); // typed module export
+await t.close();
+```
+
+Types: `TestkitContext`, `ModulesInput`, `BootModuleAppOptions`, `ModuleTestApp`.
+
+## Pool (`/pool`, `/mongo`)
+
+One server per run, one isolated database per suite. `createTestDatabasePool(provider, options?)` returns
+`{ factory, withPool, leaseNamespace, globalSetup, stats }`.
+
+```ts
+// tests/support/db-pool.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, awaitIndexes: false }), {
+  envPrefix: "APP_TEST",
+  preboot: ["transactional"],
+});
+// tests/support/global-setup.ts
+export const setup = () => dbPool.globalSetup.setup();
+export const teardown = () => dbPool.globalSetup.teardown();
+// a suite
+const boot = dbPool.withPool(bootModuleApp);
+const lease = await dbPool.leaseNamespace("transactional"); // { uri, namespace, release() }, for a host that connects itself
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `envPrefix` | `ARC_TESTKIT` | env prefix of the cross-worker handshake; use one per run kind |
+| `preboot` | `["transactional"]` | kinds `globalSetup.setup()` starts and publishes; `[]` only for a single-process run |
+| `shareTransactionalServer` | `true` | one replica set answers `standalone` and `transactional` |
+| `poolSize` | `1` | servers per kind; size with `safePoolSize(n)` (bounded by free RAM) |
+| `slotOf` | vitest worker id | which server a worker uses |
+| `stopWhenIdle` | `false` | stop servers after the last release (watch mode) |
+| `disabled` | `false` | per-suite private servers |
+
+`leaseNamespace(kind, { exact, forcePrivate, createOptions })`: `forcePrivate` gives a suite its own server (use it for
+fail points and `setParameter`); `exact` stops a `standalone` request resolving to the shared replica set.
+`mongoServerProvider({ args, awaitIndexes = true, mongoose })` builds the Mongo provider; it waits for index builds after
+the app boots (`awaitIndexBuilds(connection?)`), which is what makes unique-index assertions deterministic. Inject the
+`mongoose` instance your models register on. `publishPoolServers(servers, envPrefix)` publishes servers a custom
+`globalSetup` started.
+
+## Workers and memory (`/mongo`)
+
+- `safeWorkerCount(envVar = "ARC_TEST_WORKERS")`: explicit env value, else min(cores - 2, RAM / 6 GB), at least 2. Use in
+  `defineConfig({ test: { maxWorkers: safeWorkerCount("TEST_MAX_WORKERS") } })`.
+- `safePoolSize(requested)`: servers affordable by free RAM, at least 1.
+- `cacheSizeGB()` (env `TEST_MONGO_CACHE_GB`, floor 0.25), `mongodMemoryArgs()`, `withDbName(uri, dbName)`.
+- One heavy command at a time on a shared machine; cap workers before running a whole suite.
+
+## Wire-command counts (`/mongo-commands`)
+
+The mongoose connection must be created with `monitorCommands: true`, else `countCommands` throws.
+
+```ts
+import { assertConstantCommands, countCommands } from "@classytic/arc-testkit/mongo-commands";
+
+const { total, byCollection, byCommand, commands } = await countCommands(conn, () => placeOrder(), { collections: ["orders"], commands: ["find"], ignore: ["createIndexes"] });
+await assertConstantCommands(conn, (n) => reader.page(n), [5, 50]); // same commands at every size, at least one: a per-item read fails
+```
+
+## Plan asserts (`/mongo-explain`)
+
+```ts
+import { assertIndexServed, summarizeExplain } from "@classytic/arc-testkit/mongo-explain";
+
+const explain = await Model.find(filter).explain("executionStats");
+assertIndexServed(explain, { index: "org_state", stages: ["OR"], maxDocsExamined: 40 });
+const { stages, indexes, docsExamined } = summarizeExplain(explain);
+```
+
+`assertIndexServed` fails on COLLSCAN, on a plan scanning no index (empty or missing collection), on an index in `index`
+that is not scanned, a stage in `stages` that is absent, and on `maxDocsExamined` exceeded (needs `executionStats`).
+Rejected plans and query predicates are never read.
+
+A query built inside a repository or plugin is explained as sent, not copied into the test:
+
+```ts
+import { assertIndexServed, explainCaptured } from "@classytic/arc-testkit/mongo-explain";
+
+const { explain, command } = await explainCaptured(connection, () => service.claim(now), { collection: "timers", commands: ["findAndModify"] });
+assertIndexServed(explain, { index: "state_due", maxDocsExamined: 6 });
+```
+
+`explainCaptured(source, run, { collection, commands?, index?, verbosity? })` needs `monitorCommands: true`; it fails
+when `run` sent no matching command, or several without `index`. The explain applies no write.

package/skills/arc-testkit/references/list-filters.md

@@ -0,0 +1,3 @@
+# List filters against the route
+
+`checkFilterDeclarations({ spec, declarations })`; `declarations`: `[{ route, filters: [{ queryField, op? }], search?, sorts? }]` (op default `eq`, `between` = `gte` + `lte`). A filter must be a `field[op]` query parameter of the route's GET, or in arc's `x-arc-query` (`filterFields`, `operators`, `sortFields`); `search` needs the `search` parameter. Failure: `/api/x: filter status[contains] is not declared by the route`.

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

@@ -0,0 +1,80 @@
+# Story kit (`@classytic/arc-testkit/story`)
+
+One continuous scenario through a booted app. Steps are numbered vitest tests in one file (vitest runs them in order);
+state passes through the host's own object. The kit knows no domain: roles, routes and clause ids are yours.
+
+## Steps
+
+`describeStory(title, define, options?)`; `define` receives `s` with `s.step(title, [{ clauses, timeout }], body)`.
+`body(t, ctx)`. Test names are `N. title`.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `firstStep` | `1` | number of the first step |
+| `bail` | `true` | after a hard failure the remaining steps are skipped with "step N failed" |
+| `clauses` | none | clause tags added to every step |
+| `test`, `fixtures` | vitest `it` | an extended `test` and the fixture names steps use; they arrive as `ctx` |
+
+`t.expect(actual, what)` is `expect` with the message `[CLAUSE-1 | CLAUSE-2] what`. `t.soft(...)` is `expect.soft`: the
+failure is reported, the step continues. `t.known("DEFECT-7", actual, what)` is a soft assertion tagged
+`KNOWN DEFECT DEFECT-7`, for an open finding that must stay visible without hiding later asserts. `t.msg(what)` builds the
+tagged text for other matchers. `clauseMessage(clauses, what)` is the pure form. `need(bag, key)` reads a value an
+earlier step produced and throws "the story needs KEY from an earlier step" instead of a bare `undefined`.
+
+Reading a failure: the first line names the clauses and what was expected; the step number is in the test name; steps
+after the first hard failure show as skipped (look at the first red step, not the skipped ones).
+
+```ts
+describeStory("onboarding", (s) => {
+  s.step("a hire is captured", { clauses: ["HR-1"] }, async (t) => {
+    const res = await cast.get("hr").post("/api/people", payload);
+    t.expect(res.status, "the person is created").toBe(201);
+    t.known("D-3", res.body.tasks.length, "four onboarding tasks").toBe(4);
+  });
+}, { firstStep: 0 });
+```
+
+## Cast
+
+`createCast((roles, opts, name) => provisionedActor)`; the provisioner signs the user up on the app and returns what the
+story talks through (a client, a token). `await cast.build({ ann: ["admin"], bob: { roles: ["viewer"], opts: { mfa: false } } })`
+returns the actors by name; `cast.get(name)`, `cast.add(name, roles, opts?)`, `cast.names()`. `bearer(token)` returns
+`{ authorization: "Bearer ..." }`. Pair with `injectCaller` from `/conformance` for `get`/`post`.
+
+## Clock and civil dates
+
+`createStoryClock({ start, zone })` returns `{ now(), zone, set, advanceMs, advanceDays, travelTo(day, hour = 12), today(),
+onChange(listener) }`; `now()` returns a fresh `Date`, so it fits any `{ now(): Date }` clock port. `travelTo` jumps to
+`hour:00` of a civil date in the zone (DST-safe). Pure helpers: `civilDateOf(at, zone)`, `addCivilDays(day, n)`,
+`addCivilMonths(day, n)`, `daysBetween(a, b)`, `instantOn(day, zone, hour)`. Dates are `YYYY-MM-DD` in the operator zone.
+
+## Evidence ports
+
+`createStoryAssertions(ports)` where every port is optional and a missing one throws "no `mail` port was supplied" at the
+call: `drain` (outbox pass), `events` (rows), `feed(actor)` (items with `title`, `message`), `mail` (rows), `audit(filter)`
+(rows), `eventTypeKey` (default `type`).
+
+| Method | Behaviour |
+|---|---|
+| `drain(rounds = 3)` | drain the outbox repeatedly (a handler may emit more) |
+| `relayed(assertion, { timeout = 30000, interval = 50 })` | drain, then run the assertion, retrying until it holds |
+| `expectEvent(match, { count, min, since, clauses })` | events matching; default at least one |
+| `expectNoEvent(match, { since, clauses })` | none match |
+| `expectFeed(actor, match, spec)`, `expectNoFeed(actor, match, spec)` | feed items whose title or message match |
+| `expectMail(match, spec)` | mail rows; string matches `subject` |
+| `expectAudit(filter, match, spec)` | audit rows; string matches `action` |
+| `eventsOf(match, since)`, `feedOf(actor)` | the matching rows, for custom checks |
+
+`match` is a string or RegExp (tested on the type, title, subject or action field), a predicate, or an object matched as a
+deep subset (RegExp and function leaves are tested, arrays match when each expected element is found).
+`createEventLog()` returns `{ record, all, mark, clear, tap(subscribe, patterns) }`; `tap` subscribes your bus
+(`(pattern, handler) => ...`) and records every event; `mark()` returns a count to pass as `since` for "what happened
+next". Feed `events: () => log.all()` into the ports.
+
+## Idempotency
+
+`expectIdempotent({ run, snapshot, settle?, clauses?, label? })` runs the sweep, settles, snapshots, runs again, settles,
+snapshots, and fails unless the two snapshots are equal (`LABEL run twice on one day changes nothing the second time`).
+Returns `{ first, second, afterFirst, afterSecond }`. `expectSweepsIdempotent({ name: run, ... }, { snapshot, settle, clauses })`
+does it for several sweeps. Snapshot what must not grow: row counts, ids, mail rows, feed items. Do not advance the
+clock between the runs.