approval-md 0.1.0 → 0.2.0

package/dist/src/channels/conformance.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The shared channel conformance suite (SPEC.md §9, §10.3, §10.4).
+ *
+ * SPEC.md §9 states the display rule and then names its consequence in the same
+ * breath: rendering claimed fields with the visual authority of computed fields
+ * "is a conformance failure for a channel". This module is what that sentence
+ * points at. It ships with the contract rather than with any one channel, so
+ * `cli`, `web` and `telegram` (APRV-23/25/26) are held to one standard written
+ * once, and a fourth channel written by someone else can import it and find out
+ * in a single test whether it is a channel or merely a message sender.
+ *
+ * ## What it checks
+ *
+ * 1. **Tagging.** Every member of the request handed to the channel is a
+ *    {@link TaggedField} ({@link assertTagged}), and every field the channel
+ *    reports rendering carries the *same* kind the request gave it. A channel
+ *    that presents a claimed summary as computed fails here.
+ * 2. **The full payload** (§10.4). A manual request's rendering contains the
+ *    payload text verbatim, in a region distinct from the claimed summary.
+ * 3. **Decision round-trip.** A gesture driven through the harness lands
+ *    exactly one correctly-shaped event in a real log, through the real gate.
+ * 4. **Batch semantics** (§10.3, B7). A batch notify plus two decisions lands
+ *    two events, each carrying the batch delivery id; and the forbidden mix is
+ *    refused at {@link assembleBatch} before anything is delivered.
+ * 5. **Terminal requests are neither pending nor armed** (APRV-113). A request
+ *    the log has settled is absent from the derivation every channel builds its
+ *    queue from, and a second gesture on it is refused and appends nothing.
+ *
+ * ## How it is run
+ *
+ * ```ts
+ * test("my channel conforms", async (t) => {
+ *   await runChannelConformance(t, () => new MyChannel(), harness);
+ * });
+ * ```
+ *
+ * `t` is a `node:test` context and is used only for `diagnostic()` labels: the
+ * checks run inline and **throw** on the first failure rather than being split
+ * into subtests. That is deliberate. A subtest's promise resolves even when the
+ * subtest fails, so a suite built from `t.test()` could not itself be tested —
+ * and a conformance suite nobody has watched fail is a suite that might pass
+ * anything. Throwing means `tests/channels-contract.test.ts` can assert the
+ * suite goes RED against deliberately broken channels.
+ *
+ * The suite writes to whatever log the harness gives it, through the real gate.
+ * It never hand-writes a log line.
+ */
+import { type DecideOptions } from "../core/gate.js";
+import { type Channel, type ChannelActorOptions, type ChannelDecision, type ChannelRequest, type DecisionOutcome } from "./contract.js";
+/** Anything with a `diagnostic` method — `node:test`'s `TestContext` qualifies. */
+export interface ConformanceContext {
+    diagnostic?(message: string): void;
+}
+/**
+ * One scenario the harness prepares: a real log with `count` live manual
+ * requests, and the identity that will decide them.
+ */
+export interface ConformanceCase {
+    /** Path to a real `events.jsonl`, built through the gate. */
+    logPath: string;
+    /** The pending requests, as `channels/tagging.ts` built them. */
+    requests: ChannelRequest[];
+    /** The approver. Must be `human:…`; the gate refuses anything else. */
+    actor: ChannelActorOptions;
+    /** Gate options for recording (policy location, injected clock). */
+    gateOptions?: DecideOptions;
+    /** Called when the suite is done with this case. */
+    cleanup?(): void;
+}
+/**
+ * What a channel's test file must provide.
+ *
+ * `setup(count)` returns a *fresh* case each call — the suite decides requests,
+ * and a decided request cannot be decided again. `setup(2)` MUST return two
+ * requests with **distinct** payload hashes; the batch checks assert that and
+ * would otherwise be vacuous.
+ *
+ * `decide` is the harness's simulation of the human gesture: press the button,
+ * answer the prompt, POST the webhook — whatever makes the channel invoke the
+ * handler it was given. It is optional; without it the suite calls the
+ * registered handler directly, which still exercises the runtime path but not
+ * the channel's own callback wiring, so a real channel should provide it.
+ */
+export interface ConformanceHarness {
+    setup(count: number): ConformanceCase | Promise<ConformanceCase>;
+    decide?(channel: Channel, decision: ChannelDecision): DecisionOutcome | Promise<DecisionOutcome>;
+}
+/**
+ * Run the suite. Resolves when every check passes; throws (an `AssertionError`)
+ * on the first failure.
+ */
+export declare function runChannelConformance(t: ConformanceContext, makeChannel: () => Channel, harness: ConformanceHarness): Promise<void>;