@acid-cat/cli 0.8.0 → 0.10.0

package/README.md

@@ -6,7 +6,9 @@ The AcidCat command line. npm package: `@acid-cat/cli`. It gives the `acid-cat`
 acid-cat check [--strict] <catalog.json ...>  # check catalogs
 acid-cat format [--write] <catalog.json ...>  # write catalogs in canonical form
 acid-cat view <catalog.json> <target>         # write the view of one target
-acid-cat conform --mcp <url> --http <url> --cli "<command>" --webmcp <url> [--deadline <ms>]  # test an implementation
+acid-cat conform --mcp <url> [--mcp-handshake] --mcp-stdio "<command>" --http <url> --cli "<command>" --webmcp <url> [--deadline <ms>]  # test an implementation
+  [--poll-buffer <n>] [--poll-lease-ms <ms>] [--webhook-principal <name> --webhook-cert <file> --webhook-key <file>]
+  [--webhook-other-principal <name>] [--webhook-min-ttl-ms <ms>] [--webhook-max-ttl-ms <ms>] [--webhook-max-subscriptions <n>]
 ```
 
 Install it as a development dependency, and run it with `pnpm exec acid-cat …`:
@@ -21,7 +23,7 @@ It needs Node.js 24 or later. `acid-cat conform --webmcp <url>` also needs [Play
 
 `check` tests a catalog against [`schemas/catalog.schema.json`](../../schemas/catalog.schema.json) and against the [catalog rules](../../spec/conformance.md#catalog) that the schema cannot express.
 
-- An **error** is a broken rule. Example: an audience that names an unknown target.
+- An **error** is a broken rule. Examples: an audience that names an unknown target, an event payload that is not an object, or an id that is both a capability and an event.
 - A **warning** is a broken recommendation. Examples: a file that is not in [canonical form](../../spec/catalog.md#canonical-form), or a member with no `x-` prefix.
 
 The exit code is 0 if there are no errors. It is 1 if there are errors. With `--strict`, warnings also give the exit code 1.
@@ -30,18 +32,29 @@ The exit code is 0 if there are no errors. It is 1 if there are errors. With `--
 
 `format` writes a catalog in canonical form. Use it for catalogs that a catalog library did not write: Pkl output, generated files, or files that you edit by hand.
 
+## view
+
+`view` writes the [view](../../spec/catalog.md#views) of one target: the capabilities and the events that the target can use, and the types that they use. A view with no events has no `events` member.
+
 ## conform
 
 `conform` tests a running implementation of the [conformance fixture](conformance/fixture.pkl) through its bindings (see [Conformance](../../spec/conformance.md#acid-cat-conform)):
 
-- **MCP:** the official MCP client, with revision `2026-07-28`, for tools and outcomes; raw requests for rejections.
-- **HTTP** and **CLI:** each outcome, each kind of call failure, availability, and rejections. For the CLI, also each kind of flag, including a repeated flag that gives one item of an array for each occurrence, or the whole array as JSON text, and the usage line of each command. An interrupt (`SIGINT`) during a call that holds gives exit code 130.
+- **MCP through HTTP:** `--mcp <url>`. The official MCP client, with revision `2026-07-28`, for tools and outcomes; raw requests for rejections. With `--mcp-handshake`, or `mcpHandshake: true` in code, the checks also test the [`initialize` handshake of earlier revisions](../../spec/bindings/mcp.md#earlier-revisions-through-http): the client of revision `2025-11-25` tests the tools and outcomes again, and raw requests test `initialize` with no session and a notification.
+- **MCP through stdio:** `--mcp-stdio "<command>"`, or `mcpStdio` in code. The checks start the server as a process. The official MCP client tests the tools and outcomes two times: with revision `2026-07-28`, and with the `initialize` handshake of revision `2025-11-25`. It also tests `notifications/tools/list_changed` and `notifications/cancelled`. Raw lines test the version negotiation, a line that is not JSON, a standard output with only JSON-RPC messages, and the end of standard input.
+- **HTTP** and **CLI:** each outcome, each kind of call failure, availability, and rejections. For the CLI, also each kind of flag, including a repeated flag that gives one item of an array for each occurrence, or the whole array as JSON text, and the usage line of each command and of each event, with `[--cursor <string>] [--max-age-ms <integer>]`. An interrupt (`SIGINT`) during a call that holds gives exit code 130. `watch --cursor` starts after the cursor, and a `--max-age-ms` that is not an integer gives exit code 3.
 - **WebMCP:** the checks act as the WebMCP host. `--webmcp <url>` opens a page that serves the `app` target in Chromium, through [Playwright](https://playwright.dev), with a test `modelContext`. Install Playwright to use it: `pnpm add -D playwright`, then `pnpm exec playwright install chromium`. In code, `webmcp` can also be a function that installs the implementation on a host in the same process.
-- **Properties:** with fast-check, through each remote binding: concurrent calls each get exactly their own outcome, and a cancellation changes only its own call.
+- **Events:** through HTTP, MCP with each transport, and the CLI. The checks examine the list of the events of the view, the call failures before the first occurrence (an event outside the view, and invalid input), each occurrence against `schemas/occurrence.schema.json` and the payload schema, the order of the occurrences, an occurrence with `truncated: true` (`fixture.ticks` with `gap`: `truncated` in the occurrence through HTTP and the CLI, `notifications/events/active` with `truncated: true` and the cursor before the event through MCP push, and a result with `truncated: true` through MCP poll), the cursor, each end of a subscription (complete and `internal`), and cancellation. Through MCP, they also examine `server/discover`, `events/list` with the delivery modes of the server, `notifications/events/active`, and the subscription id of each message. With `--mcp-handshake`, `initialize` must not declare the events extension. Through WebMCP, no event is a tool.
+- **Poll delivery:** through MCP with each transport, when `events/list` gives `poll`. If not, the checks give a warning, and `events/poll` must answer `Unsupported`. The checks test each row of the table of [Poll](../../spec/bindings/mcp.md#poll): no cursor with no lease and with a lease, a cursor of the lease, a cursor of another lease with and without a lease of the key, a cursor of push delivery, and a cursor of another lease that has a cursor of the provider, which resumes after it. They also test the form of each result, `maxEvents` and `hasMore`, a `maxEvents` that is not valid, the failures before the first occurrence, which start no lease, and the error `-32603` after a defect. With `--poll-buffer <n>`, or `poll.bufferLimit` in code, they test a cursor older than the buffer: `n` is the buffer size of the deployment, from 1 to 97. With `--poll-lease-ms <ms>`, or `poll.leaseMs`, they test that a lease with no poll ends, and cancels its subscription. The lease time must be shorter than the deadline. Each check uses a new key in its input, so the leases of an earlier run do not change the result.
+- **Webhook delivery:** through MCP over HTTP, with `--webhook-principal <name>`, `--webhook-cert <file>` and `--webhook-key <file>` together, or `webhook: { principal, cert, key }` in code, with the PEM text. The checks run an HTTPS receiver on `127.0.0.1` with this certificate. Configure the deployment under test for the test: it trusts the certificate, allows deliveries to private addresses, and gives the principal `<name>` to a request with the header `Authorization: Bearer <name>`. The checks test `Forbidden` with no principal, `-32602` for a URL that is not `https` and for a secret that is not valid, the verification and `challenge_failed`, the form of the result of `events/subscribe` and its subscription id, the headers, the signature and the body of each delivery, the order of the deliveries, a renewal that signs with the old and the new secret, `events/unsubscribe` and a second `events/unsubscribe`, a retry with the same `webhook-id` after a status 500, a 410 that abandons a delivery, the control message `gap` with the watermark before an occurrence with `truncated: true`, the control message `terminated`, and the lifetime that the server grants for a `ttlMs` below the minimum, above the maximum, `null` and absent.
+  - `--webhook-min-ttl-ms <ms>` and `--webhook-max-ttl-ms <ms>`, or `webhook.minTtlMs` and `webhook.maxTtlMs`, give the lifetimes of the deployment. The defaults are those of the specification: 60 000 and 3 600 000. With `--webhook-min-ttl-ms`, which must be shorter than the deadline, the checks also test that a subscription with no renewal ends at the end of its lifetime, and gets no more deliveries.
+  - `--webhook-max-subscriptions <n>`, or `webhook.maxSubscriptions`, gives the limit of subscriptions of one principal. With it, the checks subscribe until the server answers `ResourceExhausted` (`-32025`, with `data: { limit: "subscriptions", max }`), then renew one subscription.
+  - `--webhook-other-principal <name>`, or `webhook.otherPrincipal`, gives a second principal, for `Authorization: Bearer <name>`. With it, the check of the limit fills the subscriptions of this principal, which no other check uses, so it expects exactly `n` subscriptions, and then tests that the first principal can still subscribe. Without it, the check uses the first principal, which can still have subscriptions of other checks. The retry check waits for the first retry of the deployment, so the deadline must be longer than that wait. Without these options, a server that does not list `webhook` must answer `events/subscribe` and `events/unsubscribe` with `Unsupported`. Through stdio, it must always do so.
+- **Properties:** with fast-check, through MCP with each transport and through HTTP: concurrent calls each get exactly their own outcome, and a cancellation changes only its own call.
 
-The checks wait for states that they can observe, not for times. Before a check cancels a call to `fixture.hold`, it waits until `fixture.held` gives the key of the call, or, for the CLI, until the marker file of the call exists. Each check has one deadline: `--deadline`, or `deadline` in code, in milliseconds. The default is 30 000. A check that does not settle before its deadline fails with "did not settle", and the check stops what it started. This cleanup has a deadline of the same length, so `conform` always returns. The deadline never makes a check pass.
+The checks wait for states that they can observe, not for times. Before a check cancels a call to `fixture.hold`, it waits until `fixture.held` gives the key of the call, or, for the CLI, until the marker file of the call exists. In the same way, before a check signals or cancels a subscription to `fixture.watch`, it waits until `fixture.watching` gives its key, or until its marker file exists. After it cancels the subscription, it waits until the key leaves `fixture.watching`. Each check has one deadline: `--deadline`, or `deadline` in code, in milliseconds. The default is 30 000. A check that does not settle before its deadline fails with "did not settle", and the check stops what it started. This cleanup has a deadline of the same length, so `conform` always returns. The deadline never makes a check pass.
 
-The exit code is 1 if a check fails. Both AcidCat cores run `conform` in their tests. In code, use `conform()` and `serve()` from `@acid-cat/cli`. `createTestHost()` gives the WebMCP host of the checks.
+A check of a recommendation (SHOULD) that fails gives a warning, marked `!`, and passes. The exit code is 1 if a check fails. Both AcidCat cores run `conform` in their tests. In code, use `conform()` and `serve()` from `@acid-cat/cli`. This `serve()` is for tests: it listens on `127.0.0.1`, on a free port, with plain HTTP. To serve an application, use the server of its core: `serve` from `@acid-cat/core-ts/node`, or `NodeServer` from `@acid-cat/core-effect`. `createTestHost()` gives the WebMCP host of the checks.
 
 ## Implementation
 
@@ -51,9 +64,10 @@ The command line is an [Effect](https://effect.website) program that uses `effec
 | --- | --- |
 | `src/catalog.ts` | The catalog rules, views and bundling |
 | `src/main.ts` | The commands |
-| `src/conform/` | The conformance checks, and `serve`, which serves web handlers on a local port |
+| `src/conform/` | The conformance checks, and `serve`, which serves web handlers on a local port for the tests |
 | `conformance/` | The conformance fixture, in Pkl and in JSON |
 | `test/` | Tests. Run them with `moon run cli:test` |
-| `test/fixtures/` | The catalog of the tests: a bakery, in canonical form |
+| `test/fixtures/` | The catalog of the tests: a bakery, in canonical form, with capabilities and an event |
+| `test/fixtures/rejected/` | Catalogs that `check` must reject, written by hand |
 
 The canonical writer comes from [`@acid-cat/catalog`](../catalog/typescript).

package/conformance/fixture.acidcat.json

@@ -1,7 +1,7 @@
 {
   "acidcat": "0.1",
   "title": "AcidCat conformance fixture",
-  "description": "One capability for each behavior that acid-cat conform tests.",
+  "description": "One capability or event for each behavior that acid-cat conform tests.",
   "targets": {
     "api": {
       "bindings": [
@@ -268,6 +268,41 @@
         "type": "object"
       }
     },
+    "fixture.signal": {
+      "description": "Give an occurrence of fixture.watch to each subscription that watches the key. Return the number of these subscriptions.",
+      "audience": [
+        "app",
+        "mcp",
+        "cli",
+        "api"
+      ],
+      "input": {
+        "properties": {
+          "key": {
+            "type": "string"
+          },
+          "value": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "key",
+          "value"
+        ],
+        "type": "object"
+      },
+      "output": {
+        "properties": {
+          "delivered": {
+            "type": "integer"
+          }
+        },
+        "required": [
+          "delivered"
+        ],
+        "type": "object"
+      }
+    },
     "fixture.switch.set": {
       "description": "Turn the switch on or off. The switch controls the availability of fixture.toggle.",
       "audience": [
@@ -300,6 +335,137 @@
         "properties": {},
         "type": "object"
       }
+    },
+    "fixture.watching": {
+      "description": "Return the keys of the subscriptions to fixture.watch that are active now.",
+      "audience": [
+        "app",
+        "mcp",
+        "cli",
+        "api"
+      ],
+      "output": {
+        "properties": {
+          "keys": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "keys"
+        ],
+        "type": "object"
+      },
+      "readOnly": true
+    }
+  },
+  "events": {
+    "fixture.broken": {
+      "description": "Give the occurrence n = 1, then fail with a defect.",
+      "audience": [
+        "app",
+        "mcp",
+        "cli",
+        "api"
+      ],
+      "payload": {
+        "properties": {
+          "n": {
+            "type": "integer"
+          }
+        },
+        "required": [
+          "n"
+        ],
+        "type": "object"
+      }
+    },
+    "fixture.secret": {
+      "description": "Only the app target can follow this event. It never gives an occurrence.",
+      "audience": [
+        "app"
+      ]
+    },
+    "fixture.ticks": {
+      "description": "Give the occurrences n = 1 to count, with the eventId and the cursor String(n), then end. With a cursor c, start at c + 1. With a gap g, the occurrence n = g has truncated: true, as if the source skipped occurrences before it. The key changes nothing: it gives the subscriptions of each test their own input.",
+      "audience": [
+        "app",
+        "mcp",
+        "cli",
+        "api"
+      ],
+      "input": {
+        "properties": {
+          "count": {
+            "maximum": 100,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "gap": {
+            "maximum": 100,
+            "minimum": 1,
+            "type": "integer"
+          },
+          "key": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "count"
+        ],
+        "type": "object"
+      },
+      "payload": {
+        "properties": {
+          "n": {
+            "type": "integer"
+          }
+        },
+        "required": [
+          "n"
+        ],
+        "type": "object"
+      }
+    },
+    "fixture.watch": {
+      "description": "Give an occurrence each time that fixture.signal gets the key. Never end. With a marker, write a file at that path when the subscription starts.",
+      "audience": [
+        "app",
+        "mcp",
+        "cli",
+        "api"
+      ],
+      "input": {
+        "properties": {
+          "key": {
+            "type": "string"
+          },
+          "marker": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "key"
+        ],
+        "type": "object"
+      },
+      "payload": {
+        "properties": {
+          "key": {
+            "type": "string"
+          },
+          "value": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "key",
+          "value"
+        ],
+        "type": "object"
+      }
     }
   }
 }

package/dist/catalog.js

@@ -1,7 +1,7 @@
 import catalog_schema_default from "./json/catalog.schema.json.js";
 import { isObject, isRecordOf, isStringArray } from "./json.js";
 import { canonicalText } from "@acid-cat/catalog";
-import { REFERENCE, bundle, schemasOf, viewOf as viewOf$1, visitObjects } from "@acid-cat/spec-ts";
+import { REFERENCE, bundle, eventSchemasOf, schemasOf, viewOf as viewOf$1, visitObjects } from "@acid-cat/spec-ts";
 import { Result, Schema, SchemaIssue, SchemaRepresentation } from "effect";
 //#region src/catalog.ts
 /**
@@ -15,7 +15,8 @@ const KNOWN_MEMBERS = {
 		"description",
 		"targets",
 		"$defs",
-		"capabilities"
+		"capabilities",
+		"events"
 	],
 	target: [
 		"bindings",
@@ -30,6 +31,12 @@ const KNOWN_MEMBERS = {
 		"failures",
 		"readOnly",
 		"state"
+	],
+	event: [
+		"description",
+		"audience",
+		"input",
+		"payload"
 	]
 };
 /** The catalog schema (schemas/catalog.schema.json), imported as an Effect schema. */
@@ -48,11 +55,12 @@ const optional = (object, key, isMember) => !(key in object) || isMember(object[
 const isString = (value) => typeof value === "string";
 const isTarget = (value) => isObject(value) && isStringArray(value.bindings);
 const isCapability = (value) => isObject(value) && typeof value.description === "string" && optional(value, "audience", isStringArray) && optional(value, "input", isObject) && optional(value, "output", isObject) && optional(value, "state", isObject) && optional(value, "failures", (failures) => isRecordOf(failures, isObject)) && optional(value, "readOnly", (readOnly) => typeof readOnly === "boolean");
+const isEvent = (value) => isObject(value) && typeof value.description === "string" && optional(value, "audience", isStringArray) && optional(value, "input", isObject) && optional(value, "payload", isObject);
 /**
 * True if the value has the members and the member types of a catalog. It does not check the catalog rules: `check`
 * does that.
 */
-const isCatalog = (value) => isObject(value) && typeof value.acidcat === "string" && optional(value, "title", isString) && optional(value, "description", isString) && isRecordOf(value.targets, isTarget) && optional(value, "$defs", (types) => isRecordOf(types, isObject)) && isRecordOf(value.capabilities, isCapability);
+const isCatalog = (value) => isObject(value) && typeof value.acidcat === "string" && optional(value, "title", isString) && optional(value, "description", isString) && isRecordOf(value.targets, isTarget) && optional(value, "$defs", (types) => isRecordOf(types, isObject)) && isRecordOf(value.capabilities, isCapability) && optional(value, "events", (events) => isRecordOf(events, isEvent));
 const formatIssues = SchemaIssue.makeFormatterStandardSchemaV1();
 /** Check a catalog. When `text` is given, the file must also be in canonical form. */
 function check(document, text) {
@@ -79,30 +87,53 @@ function ruleErrors(catalog) {
 	const errors = [];
 	const types = catalog.$defs ?? {};
 	for (const [name, type] of Object.entries(types)) errors.push(...referenceErrors(type, types).map((error) => `type ${name} ${error}`));
-	for (const [id, capability] of Object.entries(catalog.capabilities)) {
-		for (const target of capability.audience ?? []) if (!(target in catalog.targets)) errors.push(`${id}: the audience names ${target}, which is not a target`);
-		for (const [member, schema] of schemasOf(capability)) {
+	const entries = [...Object.entries(catalog.capabilities).map(([id, capability]) => ({
+		id,
+		entry: capability,
+		schemas: schemasOf(capability)
+	})), ...Object.entries(catalog.events ?? {}).map(([id, event]) => ({
+		id,
+		entry: event,
+		schemas: eventSchemasOf(event)
+	}))];
+	for (const id of Object.keys(catalog.events ?? {})) if (id in catalog.capabilities) errors.push(`${id}: the id is both a capability and an event`);
+	for (const { id, entry, schemas } of entries) {
+		for (const target of entry.audience ?? []) if (!(target in catalog.targets)) errors.push(`${id}: the audience names ${target}, which is not a target`);
+		for (const [member, schema] of schemas) {
 			const references = referenceErrors(schema, types);
 			errors.push(...references.map((error) => `${id} ${member} ${error}`));
-			if (member === "input" && references.length === 0 && bundle(schema, types).type !== "object") errors.push(`${id}: the input is not an object`);
+			if ((member === "input" || member === "payload") && references.length === 0 && bundle(schema, types).type !== "object") errors.push(`${id}: the ${member} is not an object`);
 		}
 	}
 	return errors;
 }
+/** The schemas of each capability and each event, with the id that holds them. */
+function catalogSchemas(catalog) {
+	return [...Object.entries(catalog.capabilities).flatMap(([id, capability]) => schemasOf(capability).map(([member, schema]) => [
+		id,
+		member,
+		schema
+	])), ...Object.entries(catalog.events ?? {}).flatMap(([id, event]) => eventSchemasOf(event).map(([member, schema]) => [
+		id,
+		member,
+		schema
+	]))];
+}
 /** Members that the specification does not define and that have no `x-` prefix. */
 function unknownMembers(catalog) {
 	const unknown = (where, value, known) => Object.keys(value).filter((key) => !known.includes(key) && !key.startsWith("x-")).map((key) => `${where}: unknown member ${key}; give extensions an x- prefix`);
 	return [
 		...unknown("the catalog", catalog, KNOWN_MEMBERS.catalog),
 		...Object.entries(catalog.targets).flatMap(([name, target]) => unknown(`target ${name}`, target, KNOWN_MEMBERS.target)),
-		...Object.entries(catalog.capabilities).flatMap(([id, capability]) => unknown(id, capability, KNOWN_MEMBERS.capability))
+		...Object.entries(catalog.capabilities).flatMap(([id, capability]) => unknown(id, capability, KNOWN_MEMBERS.capability)),
+		...Object.entries(catalog.events ?? {}).flatMap(([id, event]) => unknown(id, event, KNOWN_MEMBERS.event))
 	];
 }
 /** Schemas that cannot be imported as Effect schemas. They can still be valid JSON Schema, so this is a warning. */
 function schemaWarnings(catalog) {
 	const definitions = catalog.$defs ?? {};
 	const warnings = [];
-	for (const [id, capability] of Object.entries(catalog.capabilities)) for (const [member, schema] of schemasOf(capability)) try {
+	for (const [id, member, schema] of catalogSchemas(catalog)) try {
 		SchemaRepresentation.fromJsonSchemaMultiDocument({
 			dialect: "draft-2020-12",
 			schemas: [schema],

package/dist/conform/check.d.ts

@@ -1,10 +1,12 @@
-import type { CatalogDocument, Outcome } from "@acid-cat/spec-ts";
+import type { CatalogDocument, Occurrence, Outcome } from "@acid-cat/spec-ts";
 export interface Check {
     readonly binding: string;
     readonly name: string;
     /** The part of the specification that the check tests, for example `spec/bindings/mcp.md#tools`. */
     readonly rule: string;
     readonly passed: boolean;
+    /** `true` when the check tests a recommendation (SHOULD) that the implementation does not follow. The check still passes. */
+    readonly warning?: boolean | undefined;
     readonly detail?: string | undefined;
 }
 /** The conformance fixture: the catalog that each implementation serves. */
@@ -16,6 +18,13 @@ export declare const fixture: CatalogDocument;
 export declare const isOutcome: (value: unknown) => value is Outcome<unknown, unknown>;
 /** The ids of the capabilities in the view of a target of the fixture. */
 export declare const idsOf: (target: string) => string[];
+/** The ids of the events in the view of a target of the fixture. */
+export declare const eventIdsOf: (target: string) => string[];
+/**
+ * The value as an occurrence of the event `id`: an occurrence in its JSON form (schemas/occurrence.schema.json), with
+ * the id as its name, and data that agrees with the payload schema. The check fails when the value is not one.
+ */
+export declare function expectOccurrence(value: unknown, id: string): Occurrence;
 /** The time, in milliseconds, that each check has to settle when `conform` gets no other time. */
 export declare const DEADLINE = 30000;
 /**
@@ -25,16 +34,20 @@ export declare const DEADLINE = 30000;
  * same time, so that `conform` always returns.
  */
 export declare class Checks {
+    #private;
     readonly results: Check[];
     readonly binding: string;
     readonly deadline: number;
     constructor(binding: string, deadline: number);
     run(name: string, rule: string, body: (signal: AbortSignal) => Promise<void> | void): Promise<void>;
+    /** Run a check of a recommendation (SHOULD). When it fails, the result is a warning, and the check passes. */
+    should(name: string, rule: string, body: (signal: AbortSignal) => Promise<void> | void): Promise<void>;
 }
 /**
  * Read a state until `done` is true for it, and give that value. The read and the pause between two reads stop when the
  * signal of the check aborts.
  */
+export declare function until<T, Done extends T>(what: string, read: () => Promise<T>, done: (value: T) => value is Done, signal: AbortSignal): Promise<Done>;
 export declare function until<T>(what: string, read: () => Promise<T>, done: (value: T) => boolean, signal: AbortSignal): Promise<T>;
 /** Settle as the promise does, or reject with the reason of the signal when it aborts first. */
 export declare function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>;

package/dist/conform/check.js

@@ -1,6 +1,7 @@
 import { isObject } from "../json.js";
 import fixture_acidcat_default from "../json/fixture.acidcat.json.js";
-import { CALL_FAILURE_KINDS, viewOf } from "@acid-cat/spec-ts";
+import { CALL_FAILURE_KINDS, isOccurrence, viewOf } from "@acid-cat/spec-ts";
+import { Schema, SchemaRepresentation } from "effect";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 //#region src/conform/check.ts
 /** The result of one conformance check, and helpers to write checks. */
@@ -18,6 +19,39 @@ const isOutcome = (value) => {
 };
 /** The ids of the capabilities in the view of a target of the fixture. */
 const idsOf = (target) => Object.keys(viewOf(fixture, target).capabilities).sort();
+/** The ids of the events in the view of a target of the fixture. */
+const eventIdsOf = (target) => Object.keys(viewOf(fixture, target).events ?? {}).sort();
+/** A check of a payload against the payload schema of an event of the fixture, made once for each event. */
+const payloadChecks = /* @__PURE__ */ new Map();
+/** True if the data agrees with the payload schema of the event. With no payload schema, the data is an empty object. */
+function agreesWithPayload(id, data) {
+	let agrees = payloadChecks.get(id);
+	if (agrees === void 0) {
+		const payload = fixture.events?.[id]?.payload;
+		if (payload === void 0) agrees = (value) => isObject(value) && Object.keys(value).length === 0;
+		else {
+			const definitions = fixture.$defs ?? {};
+			const schema = SchemaRepresentation.fromJsonSchemaDocument({
+				dialect: "draft-2020-12",
+				schema: payload,
+				definitions
+			}, { patterns: "apply" });
+			agrees = Schema.is(Schema.toType(schema));
+		}
+		payloadChecks.set(id, agrees);
+	}
+	return agrees(data);
+}
+/**
+* The value as an occurrence of the event `id`: an occurrence in its JSON form (schemas/occurrence.schema.json), with
+* the id as its name, and data that agrees with the payload schema. The check fails when the value is not one.
+*/
+function expectOccurrence(value, id) {
+	expect(isOccurrence(value), `expected an occurrence, got ${JSON.stringify(value)}`);
+	expectEqual(value.name, id, "the name of the occurrence");
+	expect(agreesWithPayload(id, value.data), `the data of the occurrence must agree with the payload schema of ${id}, got ${JSON.stringify(value.data)}`);
+	return value;
+}
 /** The time, in milliseconds, that each check has to settle when `conform` gets no other time. */
 const DEADLINE = 3e4;
 /**
@@ -35,35 +69,52 @@ var Checks = class {
 		this.deadline = deadline;
 	}
 	async run(name, rule, body) {
+		const failure = await this.#settle(body);
+		this.results.push(failure === void 0 ? {
+			binding: this.binding,
+			name,
+			rule,
+			passed: true
+		} : {
+			binding: this.binding,
+			name,
+			rule,
+			passed: false,
+			detail: failure
+		});
+	}
+	/** Run a check of a recommendation (SHOULD). When it fails, the result is a warning, and the check passes. */
+	async should(name, rule, body) {
+		const failure = await this.#settle(body);
+		this.results.push(failure === void 0 ? {
+			binding: this.binding,
+			name,
+			rule,
+			passed: true
+		} : {
+			binding: this.binding,
+			name,
+			rule,
+			passed: true,
+			warning: true,
+			detail: failure
+		});
+	}
+	/** Run the body of a check with its deadline. The result is the detail of the failure, or `undefined`. */
+	async #settle(body) {
 		const controller = new AbortController();
 		const timer = setTimeout(() => controller.abort(), this.deadline);
 		try {
 			await body(controller.signal);
-			this.results.push({
-				binding: this.binding,
-				name,
-				rule,
-				passed: true
-			});
+			return;
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
-			const detail = controller.signal.aborted ? `did not settle within ${this.deadline} ms: ${message}` : message;
-			this.results.push({
-				binding: this.binding,
-				name,
-				rule,
-				passed: false,
-				detail
-			});
+			return controller.signal.aborted ? `did not settle within ${this.deadline} ms: ${message}` : message;
 		} finally {
 			clearTimeout(timer);
 		}
 	}
 };
-/**
-* Read a state until `done` is true for it, and give that value. The read and the pause between two reads stop when the
-* signal of the check aborts.
-*/
 async function until(what, read, done, signal) {
 	let last;
 	try {
@@ -99,4 +150,4 @@ const sorted = (values) => [...values].sort();
 /** An origin that no deployment allows. */
 const FORBIDDEN_ORIGIN = "https://not-allowed.acid-cat.invalid";
 //#endregion
-export { Checks, DEADLINE, FORBIDDEN_ORIGIN, abortable, expect, expectEqual, fixture, idsOf, isOutcome, sorted, until };
+export { Checks, DEADLINE, FORBIDDEN_ORIGIN, abortable, eventIdsOf, expect, expectEqual, expectOccurrence, fixture, idsOf, isOutcome, sorted, until };