approval-md 0.1.0 → 0.2.0

package/dist/src/adapters/agentmail.d.ts

@@ -0,0 +1,426 @@
+/**
+ * The AgentMail adapter (SPEC.md §6.1, §6.2, §10.4, §11; APRV-222).
+ *
+ * A second executor for `communicate.email.external`, over the AgentMail HTTPS
+ * API. It exists because AgentMail is becoming the way an agent holds a mailbox,
+ * and because its Drafts primitive is documented as mail that only leaves when
+ * something outside the agent says so. approval.md is that something, with a
+ * hash-chained log behind it.
+ *
+ * Like every adapter it implements exactly one method, {@link Adapter.act}, and
+ * `adapters/contract.ts` owns everything around the call: the hash
+ * recomputation, the token spend, `execution.started`, the credential window,
+ * the outcome event, and the redaction sweep. Nothing here touches a token or
+ * the log.
+ *
+ * ## The enforcement model this adapter assumes
+ *
+ * AgentMail API keys carry per-permission booleans (`draft_create`,
+ * `draft_update`, `draft_read`, `draft_send`, `message_send` are separate). The
+ * deployment this adapter is written for gives the agent a key WITHOUT the two
+ * send permissions and puts a key WITH them in the vault under
+ * {@link DEFAULT_AGENTMAIL_CREDENTIAL_NAMES}.apiKey, where it is readable only
+ * inside the verified execution window the contract opens. The agent can therefore
+ * compose all day and cannot send at all; the sending key answers to a grant.
+ *
+ * ## Two payload modes, discriminated by shape, ambiguity refused
+ *
+ * **Direct send.** The email adapter's own payload, validated by the email
+ * adapter's own {@link validateEmailPayload} rather than a second copy of it:
+ *
+ * ```ts
+ * { from, to: string[], cc?, bcc?, subject, body, content_type? }
+ * ```
+ *
+ * posted to `POST /v0/inboxes/{inbox_id}/messages/send`.
+ *
+ * **Draft send.** A snapshot of a draft the agent has already composed, taken at
+ * request time so a human approves the words rather than an id:
+ *
+ * ```ts
+ * { inbox_id, draft_id, to: string[], cc?, bcc?, subject, text }
+ * ```
+ *
+ * The adapter re-fetches the draft, canonicalizes those same fields (RFC 8785,
+ * the same `core/jcs.ts` the hash chain uses) on both sides, and refuses
+ * `agentmail-draft-drifted` on any difference before calling
+ * `POST .../drafts/{draft_id}/send`. That check is the whole point of the mode:
+ * a draft is mutable server-side state, and an approval of a draft id would
+ * otherwise be an approval of whatever the agent last wrote into it. The
+ * refusal names WHICH fields differ and never what they now hold — a drift
+ * message is written to a log and read by a human who did not approve the new
+ * text, and quoting it there would publish unapproved content through the
+ * refusal path.
+ *
+ * ## The comparison runs before the token is spent (APRV-276)
+ *
+ * It happens TWICE, through one function ({@link checkDraftBeforeSend}), and
+ * the first of the two is the one this section exists for.
+ *
+ * The first call is {@link Adapter.precheck}: the contract runs it after the
+ * declared credentials resolve and BEFORE the token is consumed, so a drifted
+ * draft refuses with nothing appended and the grant intact. Until APRV-276 the
+ * comparison ran only inside `act`, which meant a drift refused correctly and
+ * spent the single-use token doing it: the human's tap was consumed by an
+ * attempt that sent nothing, and restoring the approved text then refused
+ * `token-consumed`. That is the failure mode the whole design is against — a
+ * refusal that costs a human another tap teaches operators to stop checking.
+ *
+ * The second call is `act`'s own, inside the consumed-token window and
+ * immediately before the POST. It is not redundant: AgentMail sends a draft by
+ * id, so something must stand between the last read and the send, and this is
+ * what makes that gap as small as the transport allows. A drift caught there is
+ * `execution.started` then `execution.failed`, which is the honest record of a
+ * window that was open when the far side moved.
+ *
+ * **Which key performs the pre-spend read.** The same sending key from the
+ * vault, handed over by the credential provider the contract scopes to the
+ * precheck call. Not the agent's own `AGENTMAIL_API_KEY`, even though the demo
+ * has one in the environment: a comparison whose input the party under
+ * oversight chooses is scrutiny that party controls, and SPEC.md §11.1
+ * invariant 4 puts that the other way round. Nothing new is opened to make this
+ * possible — the contract already reads the vault before the spend, to resolve
+ * {@link Adapter.requiredCredentials} (APRV-169), inside APRV-168's
+ * `presented`-phase grant, which is minted only when the caller's token matches
+ * the digest the human's grant recorded. SPEC.md §10.4 carries the decision.
+ *
+ * A payload carrying markers of both modes, or of neither, is refused rather
+ * than guessed at (`agentmail-payload-ambiguous`, `agentmail-payload-invalid`):
+ * choosing a send mode by inference is choosing a side effect by inference.
+ *
+ * ## `from`, and why it costs one extra read
+ *
+ * AgentMail's send endpoint has no `from` field. The inbox IS the sender, so
+ * the payload cannot bind the From address the way the SMTP adapter's can, and
+ * a human who approved a message "from carter@…" would otherwise be approving a
+ * sender this adapter never checked.
+ *
+ * The resolution: `from` stays in the payload as the human-facing claim about
+ * the sender (reusing {@link validateEmailPayload} keeps it required and
+ * well-formed), it is sent to AgentMail in no field at all, and `act` performs
+ * one extra read — `GET /v0/inboxes/{inbox_id}` — before the send, refusing
+ * `agentmail-from-mismatch` (case-insensitively) when the inbox's own address is
+ * not the approved one. So `from` is informational on the wire and binding here.
+ * The read runs on every direct send because it doubles as the credential
+ * check: a key that cannot open its own inbox is a key that should not discover
+ * this by half-sending. It is a GET, it is idempotent, it puts no message
+ * anywhere, and a transport failure on it is `agentmail-unreachable` precisely
+ * because nothing was attempted.
+ *
+ * ## Failures
+ *
+ * Every HTTP refusal is a RETURNED failure ({@link ActOutcome} `ok: false`), so
+ * the contract records `execution.failed`: the far side answered, and an answer
+ * is knowledge. A throw from the SEND call is deliberately NOT caught — it
+ * propagates, the contract records `execution.indeterminate`, and a human finds
+ * out that nobody knows whether the message went (APRV-120). A throw from the
+ * pre-send GETs is returned as `agentmail-unreachable`, because those run before
+ * anything is attempted.
+ *
+ * Deterministic apart from its transport: no randomness, no clock, no
+ * environment reads. Every string this file returns has been through
+ * {@link redactSecrets} against the API key.
+ */
+import type { CredentialSpec } from "../core/credential-spec.js";
+import { type Adapter, type CredentialProvider, type JsonValue } from "./contract.js";
+/** The one class this adapter serves. The same string the email adapter serves. */
+export declare const AGENTMAIL_CLASS = "communicate.email.external";
+/** The public API. Overridable so the whole adapter can run against loopback. */
+export declare const AGENTMAIL_DEFAULT_API_BASE = "https://api.agentmail.to";
+/** Whole-request budget for one HTTP call. */
+export declare const AGENTMAIL_DEFAULT_TIMEOUT_MS = 15000;
+/**
+ * The two vault names, as an open record rather than a literal type: a
+ * deployment that stores these under other names must be able to SAY so, and a
+ * `typeof` of the defaults would type `credentialNames` as the defaults.
+ */
+export interface AgentmailCredentialNames {
+    apiKey: string;
+    inboxId: string;
+}
+/** The vault names, overridable per deployment. */
+export declare const DEFAULT_AGENTMAIL_CREDENTIAL_NAMES: AgentmailCredentialNames;
+export declare const AGENTMAIL_FAILURE_CODES: readonly ["agentmail-payload-invalid", "agentmail-payload-ambiguous", "agentmail-config-invalid", "agentmail-inbox-mismatch", "agentmail-from-mismatch", "agentmail-draft-missing", "agentmail-draft-drifted", "agentmail-unreachable", "agentmail-unauthorized", "agentmail-not-found", "agentmail-conflict", "agentmail-rate-limited", "agentmail-rejected", "agentmail-server-error", "credential-unavailable", "credential-refused", "credential-window-closed"];
+export type AgentmailFailureCode = (typeof AGENTMAIL_FAILURE_CODES)[number];
+export declare function isAgentmailFailureCode(value: string): boolean;
+/**
+ * What this adapter reads from the vault, declared rather than discovered, so
+ * `approval setup adapter agentmail` can ask for it without knowing what
+ * AgentMail is. DERIVED from {@link DEFAULT_AGENTMAIL_CREDENTIAL_NAMES} rather
+ * than restating the strings.
+ */
+export declare const AGENTMAIL_CREDENTIAL_SPECS: readonly CredentialSpec[];
+/**
+ * The names this adapter cannot act without (APRV-169), for the contract's
+ * pre-token resolution. Derived from the manifest, mapped through `names` so a
+ * deployment that renamed one gets the name it actually stored.
+ */
+export declare function requiredAgentmailCredentials(names?: AgentmailCredentialNames): readonly string[];
+/** What {@link readAgentmailConfig} resolved. */
+export interface AgentmailConfig {
+    apiKey: string;
+    inboxId: string;
+}
+/**
+ * What one configuration read produced.
+ *
+ * `secrets` is the redaction corpus and holds ONLY the secret-kind values (the
+ * API key). The inbox id is not a secret and is deliberately left scrubbable-not:
+ * it appears in refusal sentences that are useless without it. Returned on both
+ * branches, because a caller that goes on to make requests must scrub the far
+ * side's sentences with the same corpus this read built.
+ */
+export type AgentmailConfigOutcome = {
+    ok: true;
+    config: AgentmailConfig;
+    secrets: readonly string[];
+} | {
+    ok: false;
+    code: AgentmailFailureCode;
+    message: string;
+    secrets: readonly string[];
+};
+/**
+ * Read this adapter's whole configuration from a credential provider.
+ *
+ * The single place in the repository that turns a {@link CredentialProvider}
+ * into AgentMail settings — the names it asks for, the order, the shape rules —
+ * mirroring `readEmailSmtpConfig` for the same reason: `act` calls it inside the
+ * verified execution window and `approval setup adapter agentmail` calls it to probe
+ * a configuration it only partly typed, and a second reader would be a second
+ * opinion about what "configured" means.
+ */
+export declare function readAgentmailConfig(credentials: CredentialProvider, names?: AgentmailCredentialNames): AgentmailConfigOutcome;
+/**
+ * The slice of `fetch` this module uses, structurally.
+ *
+ * Declared here rather than imported so the adapter depends on a shape and not
+ * on a lib: a test hands over a stub, and the default is the global `fetch`
+ * Node ≥ 20 ships.
+ */
+export type AgentmailFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/** The one non-sending read, exported so the setup wizard can probe a key. */
+export type AgentmailProbe = {
+    ok: true;
+    address: string;
+    http_status: number;
+    /**
+     * The permissions the inbox read DISCLOSED about the calling key, or
+     * `null` when it disclosed none (APRV-223).
+     *
+     * Read from the one response this adapter already asks for, never from a
+     * second endpoint: a setup verb that probed a URL nobody has confirmed
+     * exists would report a 404 as a permissions problem, which is a worse
+     * answer than "not disclosed". `null` therefore means UNKNOWN and never
+     * "none", and every caller must treat it as the reminder it is.
+     */
+    permissions: readonly string[] | null;
+} | {
+    ok: false;
+    code: AgentmailFailureCode;
+    message: string;
+};
+/** The two permissions a key must hold to send anything for this adapter. */
+export declare const AGENTMAIL_SEND_PERMISSIONS: readonly ["draft_send", "message_send"];
+export interface AgentmailProbeOptions {
+    fetch?: AgentmailFetch;
+    apiBase?: string;
+    timeoutMs?: number;
+}
+/**
+ * `GET /v0/inboxes/{inbox_id}`: does this key open this inbox, and what address
+ * does it send as? Sends nothing, changes nothing, and is the credential check
+ * both `act` and `approval setup adapter agentmail` use.
+ */
+export declare function probeAgentmail(config: AgentmailConfig, options?: AgentmailProbeOptions): Promise<AgentmailProbe>;
+/** The snapshot of a composed draft a grant binds to. */
+export interface AgentmailDraftPayload {
+    inbox_id: string;
+    draft_id: string;
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject: string;
+    text: string;
+}
+/** The fields the drift check covers: everything a reader of the draft saw. */
+export declare const AGENTMAIL_DRAFT_FIELDS: readonly ["to", "cc", "bcc", "subject", "text"];
+export type AgentmailMode = "direct" | "draft";
+export type AgentmailDraftValidation = {
+    ok: true;
+    payload: AgentmailDraftPayload;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Structural validation of a draft payload. Never throws; returns the reason.
+ *
+ * Exported so a caller can check a payload BEFORE requesting approval for it,
+ * which is the only place a shape error can still be fixed cheaply.
+ */
+export declare function validateAgentmailDraftPayload(value: JsonValue): AgentmailDraftValidation;
+/**
+ * Which mode a payload is in, by the markers it carries.
+ *
+ * A payload with markers of both modes is ambiguous and a payload with markers
+ * of neither is not addressed to this adapter at all. Both are refused: a send
+ * mode chosen by inference is a side effect chosen by inference.
+ */
+export declare function agentmailMode(value: JsonValue): {
+    ok: true;
+    mode: AgentmailMode;
+} | {
+    ok: false;
+    code: AgentmailFailureCode;
+    message: string;
+};
+/**
+ * Which of {@link AGENTMAIL_DRAFT_FIELDS} differ between the approved snapshot
+ * and what the server now holds. Names only — never values.
+ */
+export declare function draftDrift(approved: AgentmailDraftPayload, fetched: Record<string, unknown>): string[];
+export type AgentmailDraftSnapshot = {
+    ok: true;
+    payload: AgentmailDraftPayload;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * The payload a grant should bind to, built from what the API holds RIGHT NOW
+ * (APRV-223).
+ *
+ * `approval payload agentmail-draft` prints this and nothing else, and it lives
+ * here rather than in the CLI for one reason: the bytes it prints are the bytes
+ * {@link draftDrift} will compare against the same draft at send time, so the
+ * two must be one piece of code. A second opinion in the CLI about what "the
+ * draft's cc" is would be a snapshot that drifts from a draft nobody changed.
+ *
+ * The rules follow {@link canonicalField} exactly. `cc`/`bcc` are OMITTED when
+ * the draft holds nothing for them, because absent, `null` and `[]` are one
+ * fact there; `to` is copied through as the array it is, unnormalized, because
+ * a reordered or re-shaped recipient list is a different message. Anything this
+ * function cannot turn into a well-formed snapshot is refused with the reason:
+ * a payload that fails {@link validateAgentmailDraftPayload} at send time is a
+ * refusal a human has already been asked to approve.
+ */
+export declare function draftSnapshot(inboxId: string, draftId: string, fetched: Record<string, unknown>): AgentmailDraftSnapshot;
+export type AgentmailDraftRead = {
+    ok: true;
+    draft: Record<string, unknown>;
+    http_status: number;
+} | {
+    ok: false;
+    code: AgentmailFailureCode;
+    message: string;
+};
+export interface AgentmailDraftReadOptions extends AgentmailProbeOptions {
+    /** The key that reads the draft. The AGENT's key here, not the vault's. */
+    apiKey: string;
+    inboxId: string;
+    draftId: string;
+}
+/**
+ * `GET /v0/inboxes/{inbox}/drafts/{draft}`: one draft, read and nothing else.
+ *
+ * The read half of the draft flow, exported for `approval payload
+ * agentmail-draft` (APRV-223), which runs BEFORE any approval exists and with
+ * the agent's own key rather than the vault's. It sends nothing and spends no
+ * token: what it produces is a proposal a human has yet to see.
+ */
+export declare function readAgentmailDraft(options: AgentmailDraftReadOptions): Promise<AgentmailDraftRead>;
+/**
+ * How many messages one page asks for. The API's own cap is higher; this is the
+ * page size, and {@link OBSERVE_MAX_PAGES} bounds how many pages are walked.
+ */
+export declare const AGENTMAIL_OBSERVE_PAGE_SIZE = 100;
+/**
+ * How many pages one observation walks.
+ *
+ * A bound rather than a full drain, because a reporting verb must terminate
+ * against an inbox of any size. A run that hits the bound says so, so a reader
+ * never mistakes a truncated page walk for a quiet mailbox.
+ */
+export declare const OBSERVE_MAX_PAGES = 10;
+/** One sent message, reduced to what a coverage report may say out loud. */
+export interface AgentmailObservedMessage {
+    messageId: string;
+    /** RFC 3339, as the provider reported it. */
+    at: string;
+    subject: string;
+    recipients: number;
+}
+export type AgentmailObservation = {
+    ok: true;
+    messages: AgentmailObservedMessage[];
+    /** Set when the page bound stopped the walk before the far side ran out. */
+    truncated: boolean;
+} | {
+    ok: false;
+    code: AgentmailFailureCode;
+    message: string;
+};
+export interface AgentmailObserveOptions extends AgentmailProbeOptions {
+    /** Override {@link AGENTMAIL_OBSERVE_PAGE_SIZE}. */
+    pageSize?: number;
+    /** Override {@link OBSERVE_MAX_PAGES}. */
+    maxPages?: number;
+}
+/**
+ * `GET /v0/inboxes/{inbox_id}/messages`: what this inbox actually sent.
+ *
+ * The endpoint and its fields are AgentMail's own, documented at
+ * https://docs.agentmail.to/api-reference/inboxes/messages/list — `message_id`,
+ * `labels`, `timestamp`, `to` and `subject`. The query carries `after`, `before`
+ * and `limit`, and `page_token` on every page after the first.
+ *
+ * **The sent filter is client-side, and that is a limit worth stating.** The
+ * documented list endpoint exposes no sent-only parameter, so this asks for the
+ * window's messages and keeps the ones whose `labels` include `sent`. Two
+ * consequences follow and neither is papered over: the request reads received
+ * mail as well as sent (a read, changing nothing), and a provider that stopped
+ * labelling sent mail would make this source report an empty window rather than
+ * an error. The remedy for the second is the same as for everything else here:
+ * the source reports what the provider said, and a source that says nothing is
+ * a gap a reader can see rather than a pass.
+ *
+ * Sends nothing. Spends no token. Reads no clock: the window is the caller's.
+ */
+export declare function observeAgentmail(config: AgentmailConfig, window: {
+    since: string;
+    until: string;
+}, options?: AgentmailObserveOptions): Promise<AgentmailObservation>;
+export interface AgentmailAdapterOptions {
+    /**
+     * Additional classes this adapter serves, **added** to {@link AGENTMAIL_CLASS}
+     * rather than replacing it: the class list is routing, and a list that
+     * replaced the default would make "add one class" silently stop serving the
+     * canonical one.
+     */
+    classes?: readonly string[];
+    /** Injectable `fetch`, for tests. Defaults to the global. */
+    fetch?: AgentmailFetch;
+    /** API base. Defaults to {@link AGENTMAIL_DEFAULT_API_BASE}. */
+    apiBase?: string;
+    /** Per-request budget. Defaults to {@link AGENTMAIL_DEFAULT_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Override the vault names. Partial: unnamed entries keep their default. */
+    credentialNames?: Partial<AgentmailCredentialNames>;
+}
+/**
+ * A fresh AgentMail adapter.
+ *
+ * Stateless and reusable: it holds no connection and nothing from a previous
+ * send. Two concurrent executions through the same instance share nothing.
+ */
+export declare function agentmailAdapter(options?: AgentmailAdapterOptions): Adapter;

package/dist/src/adapters/agentmail.js

@@ -20,7 +20,7 @@
  * deployment this adapter is written for gives the agent a key WITHOUT the two
  * send permissions and puts a key WITH them in the vault under
  * {@link DEFAULT_AGENTMAIL_CREDENTIAL_NAMES}.apiKey, where it is readable only
- * inside the verified-token window the contract opens. The agent can therefore
+ * inside the verified execution window the contract opens. The agent can therefore
  * compose all day and cannot send at all; the sending key answers to a grant.
  *
  * ## Two payload modes, discriminated by shape, ambiguity refused
@@ -242,7 +242,7 @@ export function requiredAgentmailCredentials(names = DEFAULT_AGENTMAIL_CREDENTIA
  * The single place in the repository that turns a {@link CredentialProvider}
  * into AgentMail settings — the names it asks for, the order, the shape rules —
  * mirroring `readEmailSmtpConfig` for the same reason: `act` calls it inside the
- * verified-token window and `approval setup adapter agentmail` calls it to probe
+ * verified execution window and `approval setup adapter agentmail` calls it to probe
  * a configuration it only partly typed, and a second reader would be a second
  * opinion about what "configured" means.
  */

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

@@ -0,0 +1,149 @@
+/**
+ * The shared adapter conformance suite (SPEC.md §10.4, §11.1).
+ *
+ * `channels/conformance.ts` exists because SPEC.md §9 names a display rule and
+ * then names its consequence: rendering claimed fields as computed "is a
+ * conformance failure for a channel". This module is the same idea one boundary
+ * further out. §10.4 says an adapter "MUST require a valid, unexpired,
+ * single-use execution token bound to the action's `idempotency_key`", and the
+ * only way to find out whether a given adapter does is to hand it a bad token
+ * and watch.
+ *
+ * What is being tested is mostly **the contract**, not the adapter: an adapter
+ * that goes through {@link executeThroughAdapter} inherits the sequence and
+ * cannot skip a step. That is the point. The suite is what turns "cannot skip"
+ * from an assertion in a module header into a thing someone has watched fail,
+ * and it is what a third-party adapter runs to learn whether it is wired into
+ * the gate or merely near it.
+ *
+ * ## What it checks
+ *
+ * 1. **Bad token, no side effect.** A garbage token refuses and `act` is never
+ *    called. The log is unchanged.
+ * 2. **Wrong bytes, no side effect.** A payload that is not the approved one
+ *    refuses `payload-mismatch`, `act` is never called, the token stays live.
+ * 3. **Wrong class, nothing appended.** An adapter that does not serve the
+ *    declared class refuses `adapter-class-mismatch` before the log is touched.
+ * 4. **`started` precedes the effect.** On the happy path `act` observes an
+ *    `execution.started` for its own key already in the verified log at the
+ *    moment it is called, and `execution.completed` lands after it returns. The
+ *    same check reads the provider reference of APRV-251 off that record: a
+ *    detail naming one is on the record under this adapter's name, and a detail
+ *    naming none leaves the record carrying none.
+ * 5. **Single use.** A second execution with the same token and key refuses
+ *    without calling `act`.
+ * 6. **Credentials are scoped and never leak.** A value handed out inside `act`
+ *    appears in no log line and in no field of the result, and the provider
+ *    refuses once `act` has returned.
+ * 7. **Failure is recorded, not swallowed.** An adapter reporting failure
+ *    produces `execution.failed` and an `adapter-failed` refusal.
+ *
+ * The chain is verified after every check.
+ *
+ * ## How it is run
+ *
+ * ```ts
+ * test("my adapter conforms", async (t) => {
+ *   await runAdapterConformance(t, () => new MyAdapter(), harness);
+ * });
+ * ```
+ *
+ * As in the channel suite, `t` is used only for `diagnostic()` labels: the
+ * checks run inline and **throw** on the first failure, so
+ * `tests/adapters-contract.test.ts` can assert the suite goes RED against
+ * deliberately broken adapters. A conformance suite nobody has watched fail is a
+ * suite that might pass anything.
+ *
+ * Several checks wrap the adapter under test in a hostile shell — one that reads
+ * a credential it was not asked to read, one that returns the secret inside its
+ * own detail, one that reports failure. The wrapper delegates to the real `act`
+ * where the check allows it. Wrapping rather than requiring cooperation is what
+ * lets the suite test properties (scoping, redaction) that a well-behaved
+ * adapter would never exercise on its own.
+ */
+import { type Adapter, type AdapterExecuteOptions, type JsonValue } 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 carrying a real grant, built
+ * through the real gate, and the token that grant printed.
+ *
+ * Everything here is a fact about the world the suite executes against. The
+ * suite never builds a grant itself and never hand-writes a log line; a
+ * conformance suite that fabricated its own authorization would be testing the
+ * fabrication.
+ */
+export interface AdapterConformanceCase {
+    /** Path to a real `events.jsonl` holding a granted, unspent manual action. */
+    logPath: string;
+    actionKey: string;
+    /** The bytes the grant bound to. Must hash to the grant's `payload_hash`. */
+    payload: JsonValue;
+    /** The raw single-use token `approval grant` printed. */
+    token: string;
+    /** The executing identity: `agent:<id>` or `human:<id>`. */
+    actor: string;
+    /** The class the action was declared under; the adapter must serve it. */
+    class: string;
+    /** Policy location, schema dir, injected clock. Merged into every call. */
+    options?: AdapterExecuteOptions;
+    /** Called when the suite is done with this case. */
+    cleanup?(): void;
+}
+/**
+ * What an adapter's test file must provide.
+ *
+ * `setup()` returns a *fresh* case each call: a token is single-use, so the
+ * suite cannot reuse one across checks. `credential` names a secret the suite
+ * will ask for from inside `act` and then hunt for in the log and the result;
+ * its value must be a distinctive string that could not occur by accident.
+ * A class the adapter does NOT serve is needed for the routing check, and
+ * `foreignClass` supplies it.
+ */
+export interface AdapterConformanceHarness {
+    setup(): AdapterConformanceCase | Promise<AdapterConformanceCase>;
+    credential: {
+        name: string;
+        value: string;
+    };
+    /**
+     * Everything else the adapter needs to reach its far side — a host, a port, a
+     * transport setting, a second half of a login.
+     *
+     * A real adapter rarely needs exactly one credential (the email adapter needs
+     * five), and the checks that must SUCCEED — the happy path, single use, the
+     * live token after a payload mismatch — cannot succeed against an adapter that
+     * cannot configure itself. `credential` stays the one the suite hunts for in
+     * the log and the result; these are merely present, and `credential` wins any
+     * collision so the hunted value cannot be shadowed. (Added APRV-69.)
+     */
+    credentials?: Readonly<Record<string, string>>;
+    /** A declared class this adapter must refuse. Defaults to a synthetic one. */
+    foreignClass?: string;
+    /**
+     * What the optional `observe` check needs (APRV-245). Ignored by an adapter
+     * that implements no `observe`.
+     *
+     * `writes` is how the fixture reports the number of WRITE requests its far
+     * side has received; the check reads it before and after and requires the
+     * number not to move. Without it the check still runs and still proves the
+     * log was untouched, but the "did not POST" claim rests on the log alone, so
+     * an adapter with a reachable fixture should supply it.
+     */
+    observeProbe?: {
+        /** The window to ask about. Defaults to one wide enough to include anything. */
+        window?: {
+            since: string;
+            until: string;
+        };
+        /** Write requests the far side has received so far. */
+        writes?(): number;
+    };
+}
+/**
+ * Run the suite. Resolves when every check passes; throws (an `AssertionError`)
+ * on the first failure.
+ */
+export declare function runAdapterConformance(t: ConformanceContext, makeAdapter: () => Adapter, harness: AdapterConformanceHarness): Promise<void>;