approval-md 0.1.0 → 0.2.0

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

@@ -0,0 +1,628 @@
+/**
+ * The adapter contract (SPEC.md §4, §6.2, §10.4, §11).
+ *
+ * An **adapter** is a side-effect executor: the thing that actually sends the
+ * email, writes the calendar entry, moves the file. SPEC.md §10.4 makes it the
+ * hard boundary of the whole system: credentials reach an adapter only inside
+ * a runtime-authorized execution window.
+ *
+ * That boundary describes a *sequence*, not a property of any one function:
+ * recompute the payload hash, verify the applicable authority and consume a
+ * token where required, record that the execution started, act, record how it
+ * ended. An adapter that owned that
+ * sequence could skip a step — and the step it would skip is whichever one was
+ * inconvenient the week the adapter was written. So the sequence lives here,
+ * once, and an adapter implements exactly one method:
+ *
+ * ```ts
+ * act(input: ActInput): Promise<ActOutcome> | ActOutcome
+ * ```
+ *
+ * {@link executeThroughAdapter} owns everything around that call. It is not a
+ * helper an adapter may choose; it is the only door, in the same sense that
+ * `core/token.ts`'s `consumeToken` is the only sanctioned way to append a
+ * manual `execution.started`.
+ *
+ * ## The five things the contract does that an adapter therefore cannot skip
+ *
+ * 1. **Recompute the hash.** Amended §10.4: "Adapters and `approval run` MUST
+ *    recompute the hash of the payload they are about to execute and MUST
+ *    refuse, with a distinct machine-readable reason (`payload-mismatch`), when
+ *    it differs from the hash the grant recorded." The contract hashes
+ *    `request.payload` with `core/payload.ts` — the same canonicalizer the log
+ *    uses — and hands the digest to the token spend. An adapter is never asked
+ *    what its payload hashes to, because an executor that could *state* its
+ *    hash could state the approved one while holding different bytes.
+ * 2. **Check the class before touching the log.** An adapter declares the
+ *    classes it serves. An adapter asked to execute an action declared under
+ *    some other class is refused `adapter-class-mismatch` with the log
+ *    untouched: the declaration is read from `task.registered` (the log, not the
+ *    caller's claim), and nothing is appended, because nothing happened.
+ * 3. **Start before acting.** {@link startExecution} appends `execution.started`
+ *    *before* `act` is called, and a refusal there means `act` is never called
+ *    at all. A log that recorded an execution only once it succeeded could not
+ *    tell you about the one that did not.
+ * 3b. **Resolve declared credentials before spending the token** (APRV-169). An
+ *    adapter names the credentials it cannot act without, and the contract
+ *    resolves them before `startExecution`. A missing one refuses
+ *    `credential-unavailable` with the log untouched and the grant intact,
+ *    because a configuration fault must not consume a human's single-use
+ *    authority. The side effect's own ordering is unchanged: the token is still
+ *    consumed and `execution.started` still appended before `act` runs.
+ * 3c. **Ask the adapter what it can learn before the spend** (APRV-276). An
+ *    adapter MAY implement {@link Adapter.precheck}, and the contract calls it
+ *    after the credentials resolve and before the token is consumed. It is the
+ *    home of one specific refusal: the condition that makes the side effect
+ *    impossible, that this runtime can learn without attempting it, and that
+ *    would otherwise cost a human's single-use grant to discover. AgentMail's
+ *    drift check is the worked case. A refusal appends nothing, spends nothing,
+ *    and returns `adapter-precheck-refused`. It does not replace the same check
+ *    inside `act`: the far side can move in between, and the check that binds
+ *    the bytes actually sent is the later one.
+ * 4. **Scope the credentials.** The provider handed to `act` is a wrapper that
+ *    closes when `act` returns. Inside the verified execution window it answers;
+ *    outside it, every `get` refuses `credential-window-closed`. An adapter that
+ *    stashes the provider and reads it later gets a refusal rather than a
+ *    secret, so the execution window is a mechanism instead of an intention.
+ * 5. **Redact.** Every string the contract is about to return is scanned for
+ *    each credential value the provider handed out during the window, and hits
+ *    are replaced with {@link REDACTION_PLACEHOLDER} and counted. SPEC.md §11.1
+ *    invariant 3 ("raw secrets never appear in the log") is the reason adapters
+ *    exist; here it is a mechanical check rather than a convention. Note what
+ *    reaches the log from an adapter: one bounded field. Since APRV-251 a
+ *    completion may carry `provider_ref`, the identifier the provider files the
+ *    effect under, and the sweep runs BEFORE that record is appended so the id
+ *    is scanned exactly as the rest of the detail is. Everything else in the
+ *    adapter's own vocabulary rides in the returned result, which is scanned
+ *    before it is handed back.
+ *
+ * ## What is deliberately not here
+ *
+ * No vault. {@link CredentialProvider} is the seam a real vault implements
+ * (APRV-68); this module ships {@link inMemoryCredentials} for tests and
+ * {@link NO_CREDENTIALS}, which refuses everything, as the default. A runtime
+ * that wires no provider therefore fails closed: an adapter that needs a secret
+ * to act cannot act.
+ *
+ * No token verification, consumption, or append logic. Those are
+ * `core/token.ts` and `core/execute.ts`, called here and reimplemented nowhere.
+ *
+ * ## Two callers, one core path
+ *
+ * `approval run` (`src/cli/execute.ts`) is the other caller of the same core
+ * path: a command is an adapter whose `act` is `spawnSync`, whose payload is
+ * §6.2's `{argv, cwd}`, and whose credentials are the ambient environment. It
+ * calls `startExecution` and `finishExecution` directly rather than through this
+ * module, because its stdio, exit-code transparency, and `--` argv split are CLI
+ * concerns with nothing to do with adapters. The two callers share the core
+ * verbs, not this wrapper; anything that must hold for both belongs in
+ * `core/execute.ts`, and a rule added here alone protects adapters only.
+ *
+ * Deterministic and total: no clock of its own (it forwards
+ * {@link ExecuteOptions.clock}), no randomness, and nothing here throws — an
+ * adapter that throws is caught and recorded as a failed execution.
+ */
+import { type ExecuteOptions, type ExecuteRefusal, type ProviderRef } from "../core/execute.js";
+import { type GateOptions } from "../core/gate.js";
+import type { ObservationWindow, ObservedEffect } from "../core/coverage.js";
+import { type Autonomy } from "../core/policy-load.js";
+/**
+ * A value RFC 8785 can canonicalize, which is exactly what a payload may be.
+ *
+ * The bound bytes are the ones a human saw in a channel and the ones
+ * `core/payload.ts` hashed, so the payload type is the JSON type: a payload
+ * carrying a function, a cycle, or a `NaN` has no canonical serialization and
+ * therefore no binding. Such a value is refused {@link "payload-unhashable"}
+ * rather than executed against a digest nobody can reproduce.
+ */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Why a credential was not handed over. Frozen union, per SPEC.md §11.1(6).
+ *
+ * The three are distinguished because they call for three different responses:
+ * fix the configuration, ask a human, or fix the adapter.
+ */
+export declare const CREDENTIAL_REFUSAL_CODES: readonly [
+/** No such credential is configured. The repair is configuration. */
+"credential-unavailable", 
+/** The provider knows it and declined: policy, a locked vault, a human's no. */
+"credential-refused", 
+/**
+ * The verified execution window has closed: `act` has already returned, and the
+ * provider it was handed is no longer live. Distinct from the two above
+ * because nothing is wrong with the credential or the configuration — the
+ * adapter asked at the wrong time, which is a defect in the adapter and is
+ * reported as one.
+ */
+"credential-window-closed"];
+export type CredentialRefusalCode = (typeof CREDENTIAL_REFUSAL_CODES)[number];
+export type CredentialResult = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    code: CredentialRefusalCode;
+    message: string;
+};
+/**
+ * The seam between an adapter and the secrets it needs (SPEC.md §10.4: adapters
+ * "hold the actual credentials in an encrypted vault").
+ *
+ * Synchronous and total: `get` never throws and never blocks, because it is
+ * called from inside a window the contract holds open and an adapter awaiting a
+ * human inside that window would hold an execution open with no outcome. A
+ * provider that must prompt should prompt before the execution starts and
+ * answer from what it learned.
+ */
+export interface CredentialProvider {
+    get(name: string): CredentialResult;
+    /**
+     * Told, by the contract and by nothing else, that a token has been consumed
+     * for this action and that the credential window is open (APRV-168). Called
+     * with `null` when the window closes.
+     *
+     * Optional, and a provider that ignores it behaves exactly as it always did.
+     * It exists so a provider can offer a capability that is only defensible
+     * inside a granted window, and it is safe to publish as a method because the
+     * argument cannot be forged: see {@link ExecutionGrant}.
+     */
+    grant?(grant: ExecutionGrant | null): void;
+}
+/**
+ * The brand that makes {@link ExecutionGrant} unforgeable outside this module.
+ *
+ * NOT exported. A `unique symbol` that no other module can name is a property
+ * no other module can write, so an object satisfying {@link ExecutionGrant} can
+ * be constructed here and nowhere else. This is the structural half of
+ * APRV-168's boundary: a capability keyed to a value only the contract can mint
+ * is reachable only from the contract's own execution path.
+ */
+declare const EXECUTION_GRANT_BRAND: unique symbol;
+/**
+ * Evidence, handed to a {@link CredentialProvider}, that this execution is
+ * inside a verified window (APRV-168).
+ *
+ * The contract mints one after {@link startExecution} returns, and drops it the
+ * moment `act` does. It carries no secret and grants no read by itself; what it
+ * asserts is WHEN, and on the manual path also WHAT: `tokenSha256` is the digest
+ * of the single-use token that was actually spent, present only when a token was
+ * actually spent, so a provider can insist on a human's grant rather than merely
+ * on being inside some execution.
+ */
+export interface ExecutionGrant {
+    readonly [EXECUTION_GRANT_BRAND]: true;
+    /**
+     * Where in the sequence this window is.
+     *
+     * - **`presented`** — the caller holds a token whose digest matches the one
+     *   the log's `approval.granted` recorded for this action, and the contract is
+     *   about to resolve the adapter's declared credentials (APRV-169). Minted
+     *   only on that digest match, so it is proof a human granted THIS action and
+     *   the caller has the token that grant minted. It is not full verification:
+     *   TTL, revocation and the single-use check are `core/token.ts`'s, and they
+     *   run in `startExecution` before anything is spent.
+     * - **`consumed`** — the token has been spent, `execution.started` is on the
+     *   log, and `act` is running.
+     *
+     * A capability that must not exist before a human decided may look at this;
+     * one that must not exist before the token is BURNED reads `tokenSha256`.
+     */
+    readonly phase: "presented" | "consumed";
+    /** The action this window belongs to. */
+    readonly actionKey: string;
+    /** The seq of the `execution.started` that opened it. `null` before it. */
+    readonly startedSeq: number | null;
+    /** How the action was admitted. `null` until `startExecution` has answered. */
+    readonly autonomy: Autonomy | null;
+    /**
+     * The digest of the token that was consumed, on the manual path only. Absent
+     * before the spend, and absent after it for a `supervised` or `autonomous`
+     * execution, which no human was asked about.
+     */
+    readonly tokenSha256?: string;
+}
+/** The default: no vault is wired, so nothing is handed out. Fails closed. */
+export declare const NO_CREDENTIALS: CredentialProvider;
+/**
+ * A provider over a literal map. **Tests and fixtures only** — it holds secrets
+ * in process memory in the clear, which is precisely what the vault (APRV-68)
+ * exists to stop doing.
+ */
+export declare function inMemoryCredentials(entries: Readonly<Record<string, string>>): CredentialProvider;
+/** What a redacted credential value is replaced with. */
+export declare const REDACTION_PLACEHOLDER = "[redacted]";
+/** A string with every known secret replaced, and how many replacements ran. */
+export interface Redaction {
+    text: string;
+    hits: number;
+}
+/**
+ * Replace every occurrence of every secret in `text`.
+ *
+ * Empty secrets are skipped, because "replace every occurrence of the empty
+ * string" redacts a document into nothing and would hide the very message a
+ * reader needs. Everything else is replaced literally (no regex, no escaping
+ * question), including a secret that appears as a substring of a longer word:
+ * over-redaction is the safe direction, and a credential that happens to be a
+ * common word is a credential problem, not a scanner problem.
+ */
+export declare function redactSecrets(text: string, secrets: Iterable<string>): Redaction;
+/** Does `text` contain any of `secrets`? The assertion form of the guard. */
+export declare function containsSecret(text: string, secrets: Iterable<string>): boolean;
+/** A JSON value with every string (key or value) redacted. */
+export interface RedactedJson {
+    value: JsonValue;
+    hits: number;
+}
+/**
+ * Walk `value` and redact every string in it, keys included.
+ *
+ * Keys are scanned as well as values because a leak does not care which side of
+ * the colon it lands on: `{"sk-live-…": "used"}` publishes the secret exactly as
+ * effectively as the other arrangement.
+ */
+export declare function redactJson(value: JsonValue, secrets: Iterable<string>): RedactedJson;
+/** Everything an adapter is given, and nothing else. */
+export interface ActInput {
+    /** The action's idempotency key (SPEC.md §7), for the adapter's own logging. */
+    actionKey: string;
+    /**
+     * The bytes the grant or registered declaration bound. The contract has
+     * already hashed this value and checked that digest against the applicable
+     * authority, so an adapter acting on exactly this value is acting on bound bytes. An
+     * adapter that reaches past it for "the current version" of anything has left
+     * the binding behind.
+     */
+    payload: JsonValue;
+    /** Live only until `act` returns. See {@link scopeCredentials}. */
+    credentials: CredentialProvider;
+    /** Cancellation, when the caller supplied one. */
+    signal?: AbortSignal;
+}
+/**
+ * What the adapter reports.
+ *
+ * The failure vocabulary is the adapter's own: `code` is a free string, because
+ * this repository cannot enumerate the ways an SMTP server, a calendar API, or
+ * a payments processor says no, and forcing those into a fixed union would
+ * either lie about them or freeze on the first adapter written. What is NOT
+ * negotiable is that neither `code`, `message`, nor `detail` may carry a
+ * credential; the contract scans all three before returning them.
+ */
+export type ActOutcome = {
+    ok: true;
+    detail?: JsonValue;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * The one key by which a success `detail` NAMES the provider's own identifier
+ * for the effect (APRV-251, SPEC.md §8).
+ *
+ * An adapter that wants its effect joinable by id puts a short printable string
+ * at the top level of its detail under this key, beside whatever else its
+ * receipt says. Everything after that is the contract's: the value passes the
+ * redaction sweep with the rest of the detail, the adapter half of the record
+ * is this runtime's own knowledge of which adapter it called, and the record is
+ * written by {@link finishExecution}.
+ *
+ * ONE conventional key rather than a guess across `message_id`, `sid`, `id` and
+ * whatever the next provider calls it. A contract that guessed would sooner or
+ * later lift the wrong field of some receipt onto a permanent log, and an
+ * adapter that says nothing under this key is treated as naming no reference,
+ * which is the pre-amendment behaviour and always valid.
+ */
+export declare const PROVIDER_REF_DETAIL_KEY = "provider_ref";
+/**
+ * The reference to record for this call, or `null` for none.
+ *
+ * Given BOTH the raw detail the adapter returned and the redacted copy about to
+ * be handed back, because the interesting case is the one where they differ. A
+ * lifted id whose bytes the redaction sweep touched is dropped rather than
+ * recorded: `[redacted]` matches no provider's record, and writing it would put
+ * a value in the join column that reads exactly like one that means something.
+ * The credential itself never reaches the log either way, since what would be
+ * written is the redacted copy.
+ *
+ * Everything else it declines is declined for the same reason the schema would
+ * reject it (an absent key, a value that is not a string, a string that is
+ * empty, too long, or carries a space or a control character). Declining here
+ * rather than at the append is deliberate: a record the write boundary rejects
+ * would leave a side effect that already happened with no outcome in the log,
+ * and a completion carrying no reference is the better failure.
+ */
+export declare function providerRefFor(adapterName: string, rawDetail: JsonValue | undefined, redactedDetail: JsonValue): ProviderRef | null;
+/**
+ * Everything an adapter is given for {@link Adapter.precheck}, and nothing else
+ * (APRV-276).
+ *
+ * Shaped like {@link ActInput} and deliberately a separate type, because one
+ * sentence of `ActInput`'s contract does not hold here: the token has NOT been
+ * spent. What has happened is narrower and is exactly what a pre-spend check
+ * may rely on — the payload has been hashed and IS the one the log binds this
+ * action to (the grant's `payload_hash` on the manual path, the registered
+ * declaration's off it; bytes that are anything else never reach a precheck,
+ * see {@link logBindsPayload}), the class has been read from the verified log,
+ * and the declared credentials have resolved inside APRV-168's
+ * `presented`-phase grant, minted only when the caller's token matches the
+ * digest the human's grant recorded. Whether that token may still be SPENT is
+ * `core/token.ts`'s question and is asked after this returns.
+ */
+export interface PrecheckInput {
+    /** The action's idempotency key (SPEC.md §7), for the adapter's own logging. */
+    actionKey: string;
+    /**
+     * The bytes the grant or registered declaration bound, hashed by the contract already. The same
+     * value `act` will be handed: a precheck that read some other version of the
+     * payload would be checking bytes nobody is about to execute.
+     */
+    payload: JsonValue;
+    /** Live only until `precheck` returns, exactly as `act`'s is. */
+    credentials: CredentialProvider;
+    /** Cancellation, when the caller supplied one. */
+    signal?: AbortSignal;
+}
+/**
+ * What a precheck reports: may this execution be attempted at all?
+ *
+ * `ok: true` says nothing more than "I found no reason to refuse before the
+ * spend". It is never a promise about the send, and it authorizes nothing:
+ * every check an adapter performs here it still performs inside `act`, where
+ * the window is the binding one.
+ *
+ * The failure vocabulary is the adapter's own, for {@link ActOutcome}'s reason,
+ * and `code` and `message` are scanned for credentials exactly as `act`'s are.
+ */
+export type PrecheckOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * A side-effect executor (SPEC.md §4: "an email sender, calendar writer … that
+ * holds credentials and refuses to act without a valid token").
+ *
+ * The refusal in that sentence is structural here: an adapter has no way to act
+ * *except* by being handed an {@link ActInput}, and only
+ * {@link executeThroughAdapter} builds one, only after the token was verified
+ * and consumed.
+ *
+ * `classes` lists the side-effect classes (SPEC.md §7) this adapter serves,
+ * matched exactly against the class the `task.registered` record declared.
+ * Exactly, not by glob: patterns are the policy's language for deciding
+ * autonomy, and an adapter that claimed `communicate.*` would be asserting
+ * competence over classes that do not exist yet.
+ */
+export interface Adapter {
+    /** Stable identifier: `email`, `gcal`, `mock-email`. Recorded in results. */
+    name: string;
+    /** The declared classes this adapter serves, matched exactly. */
+    classes: readonly string[];
+    /**
+     * The credential names without which `act` cannot even be attempted (APRV-169).
+     *
+     * Declared here rather than discovered inside `act`, because the contract
+     * resolves them BEFORE it consumes the token: a credential this runtime cannot
+     * reach is a configuration fault, and a configuration fault must not spend the
+     * single-use authority a human granted. An adapter that names nothing keeps
+     * exactly the behaviour it had, and one that names an OPTIONAL credential here
+     * turns an optional value into a required one, so the list holds only the
+     * values whose absence makes the action impossible.
+     *
+     * Names, never values: the contract asks the provider for each of them and
+     * keeps none of what comes back.
+     */
+    requiredCredentials?: readonly string[];
+    /**
+     * Everything this adapter can find out BEFORE the token is spent (APRV-276).
+     *
+     * Optional, and an adapter that omits it behaves exactly as it always did.
+     * It exists for one class of refusal: the condition that makes a send
+     * impossible is knowable before the spend, is not the caller's fault, and
+     * costs a human another tap when a spent token is the price of discovering
+     * it. The worked case is AgentMail's drift check. A draft is server-side
+     * mutable state, so a grant binds the bytes fetched at request time and the
+     * adapter compares them against the live draft before it sends; performing
+     * that comparison after the spend meant an edited draft refused correctly and
+     * burned the grant, and restoring the approved text could not send under the
+     * token the human had already given (the APRV-224 e2e, 2026-09-06).
+     *
+     * Three rules bind an implementation:
+     *
+     * - **Read-only.** It performs no write of any kind against the far side. It
+     *   runs on the strength of a token that has not been verified for spending,
+     *   so a precheck that could send would be a side effect outside the window.
+     * - **It never stands in for a check inside `act`.** Whatever it verifies,
+     *   `act` verifies again inside the consumed-token window. The far side can
+     *   move between the two, and the check that binds the bytes actually sent is
+     *   the later one; this one exists to protect the grant, not to license
+     *   skipping it.
+     * - **Refusing is free and passing is not a promise.** A refusal appends
+     *   nothing and spends nothing ({@link "adapter-precheck-refused"}), so an
+     *   adapter should refuse here whenever it can, and a `true` says only that
+     *   nothing was found — never that the send will succeed.
+     *
+     * The credential window is the pre-token one APRV-169 opens for
+     * {@link requiredCredentials}, with APRV-168's `presented`-phase grant live:
+     * on the manual path it is minted only when the caller's token matches the
+     * digest the human's grant recorded, so a vault read here answers to a
+     * human's decision like every other.
+     */
+    precheck?(input: PrecheckInput): Promise<PrecheckOutcome> | PrecheckOutcome;
+    act(input: ActInput): Promise<ActOutcome> | ActOutcome;
+    /**
+     * What this adapter's PROVIDER recorded happening in `window` (APRV-245).
+     *
+     * Optional, and an adapter that omits it behaves exactly as it always did.
+     * It exists because MCP use is voluntary: an agent can route an action through
+     * the gate, or it can act. What keeps the arrangement honest is that a side
+     * effect leaves a witness this project does not write, and for an adapter-
+     * backed class the witness is the provider's own record of what it did.
+     * `approval coverage` reads that record back and joins it against the verified
+     * log, so an effect with no matching record is visible as a gap.
+     *
+     * Four rules bind an implementation, and they are the mirror of {@link grant}'s:
+     *
+     * - **Read-only.** It performs no write of any kind against the far side. A
+     *   coverage report that could send is a report nobody dares to run.
+     * - **No token.** It is called OUTSIDE any grant window, by a reporting verb,
+     *   with a provider the caller built for the purpose. There is no
+     *   {@link ExecutionGrant} in scope and none is needed: reading what already
+     *   happened authorizes nothing.
+     * - **The caller redacts.** Whatever the far side says may be quoted back, so
+     *   the caller runs every returned `detail` through {@link redactSecrets} with
+     *   the secrets the adapter's own configuration reader reported. An
+     *   implementation scrubs its strings as well; two passes are cheap and a leak
+     *   is not (SPEC.md §11.1 invariant 3).
+     * - **No message content.** A detail line names an effect for a person to
+     *   recognize (a subject, a recipient count, an id) and never a body: the
+     *   report is read by somebody who did not approve the message.
+     *
+     * Every returned effect carries a class this adapter serves, so a class the
+     * adapter never handles cannot arrive dressed as an effect it observed.
+     */
+    observe?(window: ObservationWindow, credentials: CredentialProvider): Promise<readonly ObservedEffect[]>;
+}
+/**
+ * Everything {@link executeThroughAdapter} can refuse. Frozen public API, per
+ * SPEC.md §11.1(6), and a strict superset of {@link EXECUTE_REFUSAL_CODES}:
+ * every core refusal surfaces verbatim rather than being collapsed into an
+ * adapter-flavoured one, because `token-consumed`, `payload-mismatch` and
+ * `budget-exceeded` call for three different responses whether the caller is an
+ * adapter or `approval run`.
+ */
+export declare const ADAPTER_REFUSAL_CODES: readonly ["actor-invalid", "action-not-registered", "class-human-only", "token-required", "loop-escalated", "policy-not-attested", "policy-drift", "already-executed", "budget-exceeded", "not-started", "already-finished", "not-granted", "token-mismatch", "token-consumed", "token-expired", "token-revoked", "harness-executed", "payload-mismatch", "actor-not-human", "execution-delegated", "execution-indeterminate", "not-indeterminate", "already-reconciled", "dangling-stdin-not-tty", "dangling-declined", "log-unreadable", "log-torn-tail", "log-corrupt", "append-failed", "not-registered", "duplicate-request", "queue-full", "rate-limited", "payload-hash-required", "token-delivery-unavailable", "payload-store-failed", "adapter-class-mismatch", "payload-unhashable", "adapter-failed", "adapter-act-threw", "credential-unavailable", "adapter-precheck-refused"];
+export type AdapterRefusalCode = (typeof ADAPTER_REFUSAL_CODES)[number];
+/** Every adapter-path failure is one of these. Nothing here throws. */
+export interface AdapterRefusal {
+    ok: false;
+    code: AdapterRefusalCode;
+    message: string;
+    /** The adapter this was routed to. */
+    adapter: string;
+    action_key: string;
+    /** Did `act` actually run? `false` means no side effect was attempted. */
+    acted: boolean;
+    /** The `execution.started` seq, when one was appended before the failure. */
+    started_seq?: number;
+    /**
+     * The outcome event appended, when one was: `execution.failed` for an
+     * attempt that provably did not commit, `execution.indeterminate` for one
+     * whose outcome nobody knows (APRV-120).
+     */
+    outcome?: "execution.failed" | "execution.indeterminate";
+    outcome_seq?: number;
+    exit_code?: number;
+    /** The adapter's own failure code, when `code` is `adapter-failed`. */
+    adapter_code?: string;
+    /** The underlying core refusal, verbatim, when the refusal came from core. */
+    execute?: ExecuteRefusal;
+    /** How many credential values the redaction guard replaced on this path. */
+    redactions: number;
+}
+/** A completed execution: `act` reported success and the log says so. */
+export interface AdapterExecuteSuccess {
+    ok: true;
+    adapter: string;
+    action_key: string;
+    task: string;
+    class: string;
+    autonomy: Autonomy;
+    /** The digest the contract recomputed and the token spend checked. */
+    payload_hash: string;
+    started_seq: number;
+    outcome: "execution.completed";
+    outcome_seq: number;
+    /** Always 0 here; present so success and failure read alike to a consumer. */
+    exit_code: number;
+    /** The adapter's own detail, after redaction. */
+    detail?: JsonValue;
+    /**
+     * The reference the log now carries for this effect, when one was recorded
+     * (APRV-251). Absent when the adapter's detail named none, or named one the
+     * contract declined to write; see {@link providerRefFor}.
+     */
+    provider_ref?: ProviderRef;
+    redactions: number;
+}
+export type AdapterExecuteResult = AdapterExecuteSuccess | AdapterRefusal;
+/** What the contract asks an adapter to execute. */
+export interface AdapterExecuteRequest {
+    logPath: string;
+    actionKey: string;
+    /** The concrete bytes. The contract hashes these; nobody states the hash. */
+    payload: JsonValue;
+    /** `human:<id>` or `agent:<id>`; the event schema is the authority on shape. */
+    actor: string;
+}
+/**
+ * {@link ExecuteOptions} plus the two things only the adapter path has.
+ *
+ * `presentedPayloadHash` is inherited and deliberately ignored: the contract
+ * computes it from {@link AdapterExecuteRequest.payload}, and honoring a
+ * caller-supplied digest would reintroduce exactly the "tell me what you are
+ * running" hole that content binding closes.
+ */
+export interface AdapterExecuteOptions extends ExecuteOptions {
+    /** The vault seam. Absent means {@link NO_CREDENTIALS}: nothing is handed out. */
+    credentials?: CredentialProvider;
+    /** Forwarded to `act` for cancellation. */
+    signal?: AbortSignal;
+    /** Test/embedded seams for supervised-live request intake. CLI callers omit it. */
+    liveIntake?: Pick<GateOptions, "env" | "drawAsk">;
+}
+/**
+ * Execute one approved action through `adapter`, and own every step around the
+ * adapter's own.
+ *
+ * The order, and why it is this order:
+ *
+ * 1. **Hash the payload.** Before any log read, because a payload with no
+ *    canonical form has nothing to check and nothing to execute.
+ * 2. **Read the declaration** from the verified log and check the class. Both
+ *    before `startExecution`, so a misrouted action leaves the log exactly as it
+ *    found it. (The log is read twice on this path — once here, once inside
+ *    `startExecution`, which reads for itself and compare-and-appends against
+ *    the head it read. That is not redundancy to remove: a routing check that
+ *    handed its records to core would be core trusting a caller's snapshot.)
+ * 3. **Resolve the declared credentials** (APRV-169), in a window of their own
+ *    that closes at once. A name the provider cannot answer refuses
+ *    `credential-unavailable` here, with the log untouched and the token
+ *    unspent, so a missing secret costs no authority and the same token works
+ *    once the secret appears. An adapter declaring none skips this entirely.
+ * 3b. **The adapter's own pre-token check** (APRV-276), in a window of its own,
+ *    on the same presented-phase grant. Whatever it refuses is refused with the
+ *    log untouched and the token unspent, so a condition the runtime could
+ *    learn without attempting the side effect costs no authority to discover.
+ *    An adapter implementing none skips this entirely, and so does a payload
+ *    the log does not bind this action to: step 4 owns that refusal.
+ * 4. **`startExecution`**, which on the manual path verifies and consumes the
+ *    token, refuses `payload-mismatch` against the digest from step 1, and
+ *    appends `execution.started`. Any refusal here returns with `acted: false`;
+ *    `act` is not called, so no side effect was attempted.
+ * 5. **`act`**, inside a credential window that closes the moment it returns.
+ * 6. **The outcome event**, and WHICH one depends on where things went wrong
+ *    (APRV-120). `act` returning success is `execution.completed`; `act`
+ *    returning a failure is `execution.failed`, because the provider answered
+ *    and the answer was no; a throw on the way INTO `act` is `execution.failed`
+ *    too, because nothing was attempted; and a throw from inside `act` is
+ *    `execution.indeterminate`, because the provider may or may not have
+ *    committed and this runtime cannot tell. The boundary is the invocation
+ *    itself, not a judgment about the error.
+ *
+ * A refusal from step 6 is returned with `started_seq` set and the log left
+ * holding a dangling execution — which is the honest state, since the side
+ * effect did happen and its outcome could not be recorded. `approval status`
+ * reports it and `approval execution resolve` is how a human closes it. An
+ * indeterminate outcome is not that: it IS recorded, the consumption stays
+ * burned, a retry is refused, and `approval execution reconcile` is how a
+ * person resolves it from the relying party's own evidence.
+ */
+export declare function executeThroughAdapter(adapter: Adapter, request: AdapterExecuteRequest, options?: AdapterExecuteOptions): Promise<AdapterExecuteResult>;
+export {};