approval-md 0.0.1 → 0.2.0

package/dist/src/adapters/contract.js

@@ -0,0 +1,1035 @@
+/**
+ * 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 { EXECUTE_REFUSAL_CODES, checkExecutionEligibility, declaringTasks, finishExecution, findDeclaration, indeterminateExecution, providerRefRecordable, startExecution, hasApprovalCycle, } from "../core/execute.js";
+import { request as requestApproval } from "../core/gate.js";
+import { payloadHash } from "../core/payload.js";
+import { loadPolicy } from "../core/policy-load.js";
+import { resolve } from "../core/policy-match.js";
+import { payloadOf, readVerifiedRecords } from "../core/state.js";
+import { PAYLOAD_HASH_FIELD, TOKEN_HASH_FIELD, digestsEqual, tokenHash } from "../core/token.js";
+// ---------------------------------------------------------------------------
+// Credentials
+// ---------------------------------------------------------------------------
+/**
+ * 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 const CREDENTIAL_REFUSAL_CODES = [
+    /** 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",
+];
+/** The default: no vault is wired, so nothing is handed out. Fails closed. */
+export const NO_CREDENTIALS = {
+    get(name) {
+        return {
+            ok: false,
+            code: "credential-unavailable",
+            message: `no credential provider is configured, so ${JSON.stringify(name)} cannot be supplied. SPEC.md §10.4 puts the credentials behind the adapter boundary; wire a provider explicitly rather than reading the environment from inside an adapter.`,
+        };
+    },
+};
+/**
+ * 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 function inMemoryCredentials(entries) {
+    return {
+        get(name) {
+            const value = Object.prototype.hasOwnProperty.call(entries, name)
+                ? entries[name]
+                : undefined;
+            if (typeof value !== "string") {
+                return {
+                    ok: false,
+                    code: "credential-unavailable",
+                    message: `no credential named ${JSON.stringify(name)} is configured`,
+                };
+            }
+            return { ok: true, value };
+        },
+    };
+}
+/**
+ * Wrap `inner` in a window that closes.
+ *
+ * The mechanism is a closure over a boolean, not a revoked reference: the
+ * adapter may keep the object it was handed for as long as it likes, and the
+ * object will refuse. Values handed out are remembered so the contract can scan
+ * its own output for them; the *names* are not interesting and the values never
+ * leave this set.
+ */
+function scopeCredentials(inner) {
+    let open = true;
+    const issued = new Set();
+    return {
+        provider: {
+            get(name) {
+                if (!open) {
+                    return {
+                        ok: false,
+                        code: "credential-window-closed",
+                        message: `credential ${JSON.stringify(name)} was requested after act() returned. Credentials are reachable only inside the verified execution window: the execution has already been recorded, so a secret handed over now would be outside the authority that opened the call.`,
+                    };
+                }
+                const result = inner.get(name);
+                if (result.ok && result.value.length > 0)
+                    issued.add(result.value);
+                return result;
+            },
+        },
+        issued,
+        close() {
+            open = false;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Redaction (SPEC.md §11.1 invariant 3, mechanically)
+// ---------------------------------------------------------------------------
+/** What a redacted credential value is replaced with. */
+export const REDACTION_PLACEHOLDER = "[redacted]";
+/**
+ * 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 function redactSecrets(text, secrets) {
+    let out = text;
+    let hits = 0;
+    for (const secret of secrets) {
+        if (secret.length === 0)
+            continue;
+        let index = out.indexOf(secret);
+        while (index !== -1) {
+            hits += 1;
+            out = out.slice(0, index) + REDACTION_PLACEHOLDER + out.slice(index + secret.length);
+            index = out.indexOf(secret, index + REDACTION_PLACEHOLDER.length);
+        }
+    }
+    return { text: out, hits };
+}
+/** Does `text` contain any of `secrets`? The assertion form of the guard. */
+export function containsSecret(text, secrets) {
+    for (const secret of secrets) {
+        if (secret.length === 0)
+            continue;
+        if (text.includes(secret))
+            return true;
+    }
+    return false;
+}
+/**
+ * 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 function redactJson(value, secrets) {
+    const list = [...secrets].filter((secret) => secret.length > 0);
+    if (list.length === 0)
+        return { value, hits: 0 };
+    let hits = 0;
+    const walk = (node) => {
+        if (typeof node === "string") {
+            const redacted = redactSecrets(node, list);
+            hits += redacted.hits;
+            return redacted.text;
+        }
+        if (Array.isArray(node))
+            return node.map(walk);
+        if (typeof node === "object" && node !== null) {
+            const out = {};
+            for (const [key, member] of Object.entries(node)) {
+                const redactedKey = redactSecrets(key, list);
+                hits += redactedKey.hits;
+                out[redactedKey.text] = walk(member);
+            }
+            return out;
+        }
+        return node;
+    };
+    return { value: walk(value), hits };
+}
+/**
+ * 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 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 function providerRefFor(adapterName, rawDetail, redactedDetail) {
+    const read = (node) => {
+        if (typeof node !== "object" || node === null || Array.isArray(node))
+            return null;
+        const named = node[PROVIDER_REF_DETAIL_KEY];
+        return typeof named === "string" ? named : null;
+    };
+    const raw = read(rawDetail);
+    if (raw === null)
+        return null;
+    // The redacted copy is what a reader would get, so it is what is compared.
+    if (read(redactedDetail) !== raw)
+        return null;
+    const ref = { adapter: adapterName, id: raw };
+    return providerRefRecordable(ref) ? ref : null;
+}
+// ---------------------------------------------------------------------------
+// Refusals
+// ---------------------------------------------------------------------------
+/**
+ * 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 const ADAPTER_REFUSAL_CODES = [
+    ...EXECUTE_REFUSAL_CODES,
+    /** Request intake could not find the task registration. */
+    "not-registered",
+    /** A concurrent caller opened the live-selected request first. */
+    "duplicate-request",
+    /** Live-selected intake reached the approver queue ceiling. */
+    "queue-full",
+    /** Live-selected intake reached the origin's request rate limit. */
+    "rate-limited",
+    /** A selected live action had no declaration hash to bind. */
+    "payload-hash-required",
+    /** A selected live self-delivery address could not be created. */
+    "token-delivery-unavailable",
+    /** Live intake could not retain the exact payload for human display or audit. */
+    "payload-store-failed",
+    /**
+     * The adapter does not serve the class this action was declared under.
+     * Refused before anything is appended: routing an action to the wrong
+     * executor is a wiring mistake, and a wiring mistake must not consume a
+     * single-use token or leave a dangling execution behind.
+     */
+    "adapter-class-mismatch",
+    /**
+     * The payload has no RFC 8785 canonical form, so there is no hash to check
+     * against the grant. Nothing is appended and no token is spent.
+     */
+    "payload-unhashable",
+    /**
+     * `act` ran and reported failure. `execution.failed` WAS appended: the side
+     * effect was attempted, and the log says so. `adapter_code` carries the
+     * adapter's own reason.
+     */
+    "adapter-failed",
+    /**
+     * A throw on the way to `act`, before it was entered: assembling the
+     * credential window, or reading the adapter's own method. Nothing was
+     * attempted, so `execution.failed` is the honest record and the caller may
+     * fix its wiring and try again.
+     *
+     * A throw from INSIDE `act` is a different code (`execution-indeterminate`)
+     * and a different event, because the outcome is then unknown (APRV-120).
+     *
+     * Only the error's `message` is kept — never the stack, which routinely
+     * quotes arguments and would be a credential-shaped leak with a plausible
+     * excuse — and even that message passes the redaction guard.
+     */
+    "adapter-act-threw",
+    /**
+     * A credential the adapter declared in {@link Adapter.requiredCredentials}
+     * could not be resolved (APRV-169). Refused BEFORE the token is consumed and
+     * before `execution.started` is appended, so the grant survives: the log is
+     * left exactly as it was found and the same token is spendable once the
+     * credential appears.
+     *
+     * The provider's own reason (`credential-unavailable`, `credential-refused`)
+     * rides in `adapter_code`, because "nobody stored an SMTP password" and "the
+     * vault would not open" are two different repairs.
+     */
+    "credential-unavailable",
+    /**
+     * The adapter's own {@link Adapter.precheck} answered no (APRV-276). Refused
+     * BEFORE the token is consumed and before `execution.started` is appended, so
+     * the grant survives exactly as it does for `credential-unavailable`: the log
+     * is left as it was found and the same token is spendable once the condition
+     * the precheck named is repaired.
+     *
+     * The adapter's own reason rides in `adapter_code`
+     * (`agentmail-draft-drifted`, say), because the repair belongs to the far
+     * side's vocabulary and this union cannot enumerate it.
+     *
+     * A precheck that throws lands here too, under `adapter_code`
+     * `precheck-threw`: a check that could not be performed is not a check that
+     * passed, and the fail-closed answer costs nothing, since nothing was
+     * attempted.
+     */
+    "adapter-precheck-refused",
+];
+/** The exit code recorded for an execution the adapter did not complete. */
+const ADAPTER_FAILURE_EXIT_CODE = 1;
+/**
+ * Does `token` match the digest the log's grant for `actionKey` recorded?
+ *
+ * A pure comparison over records this path has already read and verified, and
+ * deliberately NOT a second opinion about whether the token may be spent:
+ * `core/token.ts` owns TTL, revocation and the single-use check, and
+ * `startExecution` runs all three before anything is appended. What this answers
+ * is the narrower question the pre-token phase needs: does the caller hold the
+ * token a human's grant minted for this action?
+ *
+ * Constant-time, through `digestsEqual`. `false` for everything else: no grant,
+ * no recorded digest, no token.
+ */
+function tokenMatchesGrant(records, actionKey, token) {
+    if (token === undefined || token.length === 0)
+        return false;
+    let recorded;
+    for (const record of records) {
+        if (record.event !== "approval.granted")
+            continue;
+        if (record.action_key !== actionKey)
+            continue;
+        recorded = payloadOf(record)[TOKEN_HASH_FIELD];
+    }
+    if (typeof recorded !== "string" || recorded.length === 0)
+        return false;
+    return digestsEqual(tokenHash(token), recorded);
+}
+/**
+ * Does the log bind this action to exactly the bytes the caller presented?
+ *
+ * Read for one purpose (APRV-276): deciding whether {@link Adapter.precheck}
+ * may run at all. A precheck is handed the payload, and every word of its
+ * contract assumes those bytes are the approved ones — AgentMail compares the
+ * live draft against them and calls a difference drift. Handed bytes no human
+ * approved, the same comparison is a question about the wrong snapshot, and its
+ * answer is noise at best: a refusal naming the caller's own edit as the far
+ * side's drift, or a pass that says a tampered payload matches the draft.
+ *
+ * So this is a precondition and never a verdict. It answers no and the precheck
+ * is SKIPPED, not refused: `startExecution` is the authority on content binding
+ * and refuses `payload-mismatch` in its own words a few lines later, with
+ * nothing appended and the token still live. Two modules refusing the same fact
+ * is two places for the reason to drift.
+ *
+ * The binding it compares against is the one that path's authorization actually
+ * uses, which is why both are read here: the grant's recorded `payload_hash` on
+ * the manual path (`core/token.ts`), and the registered declaration's off it
+ * (`core/execute.ts`), with the declaration standing in for a grant that
+ * recorded none, exactly as `verifyToken` lets it. A binding that exists
+ * nowhere answers no, so the strict path is the default: an action whose bytes
+ * nothing in the log states is one no precheck may reason about.
+ */
+function logBindsPayload(records, actionKey, declared, hash) {
+    let bound = declared.payload_hash;
+    for (const record of records) {
+        if (record.event !== "approval.granted")
+            continue;
+        if (record.action_key !== actionKey)
+            continue;
+        const recorded = payloadOf(record)[PAYLOAD_HASH_FIELD];
+        bound = typeof recorded === "string" && recorded.length > 0 ? recorded : declared.payload_hash;
+    }
+    if (bound === null)
+        return false;
+    return digestsEqual(bound, hash);
+}
+/**
+ * Hand `grant` to a provider that asked to be told, and swallow whatever it does
+ * about it.
+ *
+ * A provider is not required to implement `grant`, and one that implements it
+ * badly must not be able to fail an execution: this call carries no secret, no
+ * decision, and nothing the contract needs back. Every path that leaves the
+ * execution passes `null` through here, so a capability opened for a window is
+ * closed on every exit, refusals included.
+ */
+function tell(provider, grant) {
+    try {
+        provider.grant?.(grant);
+    }
+    catch {
+        // Nothing to report and nothing to repair: the contract asked, not asked for.
+    }
+}
+/**
+ * Resolve every credential the adapter declared it cannot act without, before
+ * the token is consumed (APRV-169).
+ *
+ * The ordering this exists to establish, stated once: a credential the runtime
+ * cannot reach is a configuration fault, and a configuration fault must not
+ * spend a human's single-use grant. Resolving here means a
+ * `credential-unavailable` refusal costs no authority: nothing is appended, the
+ * token stays spendable, and the same token executes once the credential
+ * appears.
+ *
+ * What this does NOT reorder is the consume-then-execute sequence for the side
+ * effect itself. `startExecution` still consumes the token and appends
+ * `execution.started` before `act` is called, because that ordering is what
+ * makes a crash between the two an ambiguity the log can SEE rather than one it
+ * is silent about (APRV-120). Credentials move ahead of the token; the side
+ * effect does not.
+ *
+ * The reads happen in a window of their own that closes immediately, so a
+ * provider handed here is never left live outside a scope, and every value it
+ * hands over joins the redaction corpus of the refusal this may return. Nothing
+ * read here is kept or returned: what comes back is whether the name resolved,
+ * and `act` asks for the values itself inside the verified execution window.
+ *
+ * Note what an unauthorized caller learns by invoking this path: whether the
+ * names THIS ADAPTER statically declared are present in a provider the caller
+ * supplied in the first place. It is not a channel for asking about arbitrary
+ * names, and a caller holding the provider could ask it directly anyway.
+ */
+function resolveRequiredCredentials(adapter, actionKey, inner) {
+    const names = adapter.requiredCredentials ?? [];
+    if (names.length === 0)
+        return { ok: true, issued: new Set() };
+    const scope = scopeCredentials(inner);
+    try {
+        for (const name of names) {
+            let got;
+            try {
+                got = scope.provider.get(name);
+            }
+            catch (error) {
+                // A provider is required to be total. One that throws anyway is a
+                // configuration this runtime cannot use, and it is reported as one
+                // rather than allowed to escape: nothing here throws.
+                got = {
+                    ok: false,
+                    code: "credential-unavailable",
+                    message: `the credential provider raised instead of answering: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+            if (got.ok)
+                continue;
+            const redacted = redactSecrets(`the ${adapter.name} adapter declares that it cannot act without the credential ${JSON.stringify(name)}, and it did not resolve (${got.code}): ${got.message}. Nothing was appended and no token was spent: credentials resolve before the token is consumed (SPEC.md §10.4, APRV-169), so this refusal costs no authority and the same token executes once the credential is reachable.`, scope.issued);
+            return {
+                ok: false,
+                credentialCode: got.code,
+                message: redacted.text,
+                redactions: redacted.hits,
+            };
+        }
+        return { ok: true, issued: scope.issued };
+    }
+    finally {
+        scope.close();
+    }
+}
+/**
+ * Ask the adapter what it can find out before the token is spent (APRV-276).
+ *
+ * The ordering this exists to establish, stated once and alongside
+ * {@link resolveRequiredCredentials}'s: a condition that makes the side effect
+ * impossible, and that this runtime can learn without attempting it, must not
+ * cost a human's single-use grant. A credential nobody stored was the first
+ * such condition (APRV-169); a draft the agent edited after the human read it
+ * is the second, and the difference between them is only whose fault it is.
+ * Both refuse with the log untouched and the token spendable.
+ *
+ * What this does NOT reorder is the consume-then-execute sequence for the side
+ * effect itself, for the reason APRV-120 gives: `startExecution` still consumes
+ * the token and appends `execution.started` before `act` is called, so a crash
+ * between the two is an ambiguity the log can SEE. Nor does it move a check OUT
+ * of `act`: an adapter that prechecks a condition checks it again inside the
+ * window, because the far side can move in between and the check that binds the
+ * bytes actually sent is the later one.
+ *
+ * The window is its own and closes immediately, exactly as the credential
+ * resolution's does, and every value the provider handed over joins the
+ * redaction corpus of whatever this returns. So does `inherited`, everything
+ * the resolution above already handed this adapter, and it has to: a precheck
+ * that throws typically throws holding a secret it was given a step earlier and
+ * never asked this window for, so scanning only what THIS window issued would
+ * scan an empty set and print the credential. An adapter that implements no
+ * precheck pays nothing: the function returns at its first line.
+ *
+ * Total: a precheck that throws is reported as a refusal rather than allowed to
+ * escape. A check that could not be performed is not a check that passed, and
+ * failing closed here is free, since nothing has been attempted.
+ */
+async function runPrecheck(adapter, actionKey, payload, inner, inherited, signal) {
+    const precheck = adapter.precheck;
+    if (precheck === undefined)
+        return { ok: true, issued: new Set() };
+    const scope = scopeCredentials(inner);
+    try {
+        let outcome;
+        try {
+            const input = {
+                actionKey,
+                payload,
+                credentials: scope.provider,
+                ...(signal === undefined ? {} : { signal }),
+            };
+            outcome = await precheck.call(adapter, input);
+        }
+        catch (error) {
+            // The message and nothing else, for `act`'s reason: a stack trace quotes
+            // call arguments, and a credential passed as one would ride out inside an
+            // error report.
+            outcome = {
+                ok: false,
+                code: "precheck-threw",
+                message: `the ${adapter.name} adapter's pre-token check raised instead of answering: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        if (outcome.ok)
+            return { ok: true, issued: scope.issued };
+        // Everything this window issued, plus everything the resolution above
+        // already handed over. A refusal is printed, and both sets are secrets it
+        // could be printing.
+        const secrets = new Set(inherited);
+        for (const secret of scope.issued)
+            secrets.add(secret);
+        const code = redactSecrets(outcome.code, secrets);
+        const message = redactSecrets(`${adapter.name} refused action ${actionKey} before the token was spent (${outcome.code}): ${outcome.message}. Nothing was appended and no token was spent: an adapter's pre-token check runs before the token is consumed (SPEC.md §10.4, APRV-276), so this refusal costs no authority and the same token executes once the condition it names is repaired.`, secrets);
+        return {
+            ok: false,
+            adapterCode: code.text,
+            message: message.text,
+            redactions: code.hits + message.hits,
+        };
+    }
+    finally {
+        scope.close();
+    }
+}
+/**
+ * Copy the core-relevant options across, and bind the hash the contract
+ * computed. Built explicitly rather than spread so that a future field added to
+ * {@link AdapterExecuteOptions} (a credential provider, a transport handle) is
+ * not silently forwarded into core.
+ */
+function executeOptionsFrom(options, presentedPayloadHash) {
+    return {
+        ...(options.token === undefined ? {} : { token: options.token }),
+        ...(options.policy === undefined ? {} : { policy: options.policy }),
+        ...(options.schemaDir === undefined ? {} : { schemaDir: options.schemaDir }),
+        ...(options.append === undefined ? {} : { append: options.append }),
+        ...(options.clock === undefined ? {} : { clock: options.clock }),
+        ...(options.keyStoreDir === undefined ? {} : { keyStoreDir: options.keyStoreDir }),
+        ...(options.retryOnHeadMoved === undefined
+            ? {}
+            : { retryOnHeadMoved: options.retryOnHeadMoved }),
+        presentedPayloadHash,
+    };
+}
+function liveIntakeOptionsFrom(options) {
+    return {
+        ...(options.policy === undefined ? {} : { policy: options.policy }),
+        ...(options.schemaDir === undefined ? {} : { schemaDir: options.schemaDir }),
+        ...(options.append === undefined ? {} : { append: options.append }),
+        ...(options.clock === undefined ? {} : { clock: options.clock }),
+        ...(options.keyStoreDir === undefined ? {} : { keyStoreDir: options.keyStoreDir }),
+        ...(options.retryOnHeadMoved === undefined
+            ? {}
+            : { retryOnHeadMoved: options.retryOnHeadMoved }),
+        ...(options.liveIntake?.env === undefined ? {} : { env: options.liveIntake.env }),
+        ...(options.liveIntake?.drawAsk === undefined
+            ? {}
+            : { drawAsk: options.liveIntake.drawAsk }),
+    };
+}
+function refuse(adapter, actionKey, code, message, extra = {}) {
+    return {
+        ok: false,
+        code,
+        message,
+        adapter: adapter.name,
+        action_key: actionKey,
+        acted: false,
+        redactions: 0,
+        ...extra,
+    };
+}
+/**
+ * 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 async function executeThroughAdapter(adapter, request, options = {}) {
+    const { logPath, actionKey, payload, actor } = request;
+    // (a) The hash, computed here from the bytes, never accepted from a caller.
+    let hash;
+    try {
+        hash = payloadHash(payload);
+    }
+    catch (error) {
+        return refuse(adapter, actionKey, "payload-unhashable", `the payload for ${actionKey} has no RFC 8785 canonical serialization (${error instanceof Error ? error.message : String(error)}), so it cannot be hashed and cannot be shown to be the bytes the grant or registered declaration bound. Nothing was appended.`);
+    }
+    // (b) The declared class, from the verified log.
+    const read = readVerifiedRecords(logPath, options.schemaDir === undefined ? {} : { schemaDir: options.schemaDir });
+    if (!read.ok)
+        return refuse(adapter, actionKey, read.code, read.message);
+    const declaring = declaringTasks(read.records, actionKey);
+    if (declaring.length > 1) {
+        return refuse(adapter, actionKey, "action-not-registered", `action key ${JSON.stringify(actionKey)} is declared by more than one task (${declaring.join(", ")}); the runtime refuses an ambiguous declaration rather than route the later one. Registration refuses such collisions (APRV-138).`);
+    }
+    const declared = findDeclaration(read.records, actionKey);
+    if (declared === null) {
+        return refuse(adapter, actionKey, "action-not-registered", `no task.registered record declares an action with idempotency_key ${JSON.stringify(actionKey)}; SPEC.md §7 requires a class to be declared before the action can execute, and an adapter cannot supply the declaration on the action's behalf.`);
+    }
+    if (!adapter.classes.includes(declared.class)) {
+        return refuse(adapter, actionKey, "adapter-class-mismatch", `adapter ${JSON.stringify(adapter.name)} serves ${adapter.classes.length === 0 ? "no classes" : adapter.classes.map((cls) => JSON.stringify(cls)).join(", ")}, and action ${actionKey} is declared under class ${JSON.stringify(declared.class)}. The action was routed to the wrong executor; nothing was appended and no token was spent.`);
+    }
+    // Supervised-live selection belongs to gate intake. Its unselected result is
+    // intentionally absent from the log, so an adapter cannot infer that intake
+    // happened merely because no approval.requested exists. On a genuinely
+    // no-token, no-cycle call, invoke the existing request path from fields read
+    // exclusively from the verified declaration. Selected or unavailable draws
+    // create the ordinary pending cycle; an unselected draw appends no approval
+    // event and continues. A prior cycle, including a rejected or expired one,
+    // is never redrawn here.
+    const policyOptions = options.policy ?? {};
+    const load = loadPolicy({
+        ...(policyOptions.file === undefined
+            ? { dir: policyOptions.dir ?? process.cwd() }
+            : { file: policyOptions.file }),
+        ...(options.schemaDir === undefined ? {} : { schemaDir: options.schemaDir }),
+    });
+    const initialResolution = resolve(load, declared.class, declared.reversible === null ? {} : { reversible: declared.reversible });
+    let livePolicySha256;
+    if ((options.token === undefined || options.token.length === 0) &&
+        initialResolution.supervision === "live" &&
+        !hasApprovalCycle(read.records, actionKey)) {
+        const intake = requestApproval(logPath, {
+            task: declared.task,
+            actionKey,
+            cls: declared.class,
+            est_cost_usd: declared.est_cost_usd,
+            ...(declared.reversible === null ? {} : { reversible: declared.reversible }),
+            ...(declared.summary === null ? {} : { summary: declared.summary }),
+            ...(declared.payload_hash === null ? {} : { payload_hash: declared.payload_hash }),
+            payload: { value: payload },
+            delivery: "self",
+        }, actor, liveIntakeOptionsFrom(options));
+        if (!intake.ok) {
+            return refuse(adapter, actionKey, intake.code, intake.message);
+        }
+        if (intake.proceed && intake.live !== undefined) {
+            livePolicySha256 = intake.policySha256;
+        }
+    }
+    // A no-token path must prove that core would admit this exact execution
+    // before credentials or a provider-backed precheck are touched. This result
+    // is only a preflight: startExecution repeats every check after precheck and
+    // remains the sole writer of execution.started.
+    const eligibilityOptions = {
+        ...executeOptionsFrom(options, hash),
+        ...(livePolicySha256 === undefined
+            ? {}
+            : { expectedPolicySha256: livePolicySha256 }),
+    };
+    const eligibility = checkExecutionEligibility(logPath, actionKey, eligibilityOptions, actor);
+    if (!eligibility.ok) {
+        return refuse(adapter, actionKey, eligibility.code, eligibility.message, {
+            execute: eligibility,
+        });
+    }
+    const effectiveToken = eligibility.mode === "token" ? eligibility.token : undefined;
+    // (c) The credentials the adapter declared it cannot act without, resolved
+    //     BEFORE the token is consumed (APRV-169). See
+    //     {@link resolveRequiredCredentials} for why this sits here and why the
+    //     consume-then-execute ordering below is untouched.
+    const provider = options.credentials ?? NO_CREDENTIALS;
+    // The presented-phase grant (APRV-168). Minted only when the caller's token
+    // matches the digest a human's grant recorded for this action, so a provider
+    // may offer a capability here on the strength of that decision. Everything
+    // that decides whether the token may actually be SPENT still happens below,
+    // in `startExecution`, and nothing here appends or consumes.
+    const presented = tokenMatchesGrant(read.records, actionKey, effectiveToken)
+        ? { phase: "presented", actionKey, startedSeq: null, autonomy: null }
+        : null;
+    tell(provider, presented);
+    const resolved = resolveRequiredCredentials(adapter, actionKey, provider);
+    if (!resolved.ok) {
+        tell(provider, null);
+        return refuse(adapter, actionKey, "credential-unavailable", resolved.message, {
+            adapter_code: resolved.credentialCode,
+            redactions: resolved.redactions,
+        });
+    }
+    // (c2) The adapter's own pre-token check (APRV-276), in a window of its own,
+    //      still on the presented-phase grant. A refusal here appends nothing and
+    //      spends nothing, for the same reason (c) does.
+    //
+    //      Skipped outright unless the log binds this action to the bytes in
+    //      hand: a precheck asked about a payload no human approved is being
+    //      asked the wrong question, and answering it would let an adapter's own
+    //      vocabulary describe what is really a `payload-mismatch`. Those bytes
+    //      get no precheck and no far-side request; `startExecution` refuses them
+    //      below, in core's words, with the log untouched and the token live.
+    const prechecked = logBindsPayload(read.records, actionKey, declared, hash)
+        ? await runPrecheck(adapter, actionKey, payload, provider, resolved.issued, options.signal)
+        : { ok: true, issued: new Set() };
+    if (!prechecked.ok) {
+        tell(provider, null);
+        return refuse(adapter, actionKey, "adapter-precheck-refused", prechecked.message, {
+            adapter_code: prechecked.adapterCode,
+            redactions: prechecked.redactions,
+        });
+    }
+    // (d) Authorization and the start event. Refused here means act never runs.
+    const executeOptions = {
+        ...eligibilityOptions,
+        ...(effectiveToken === undefined ? {} : { token: effectiveToken }),
+    };
+    const started = startExecution(logPath, actionKey, executeOptions, actor);
+    if (!started.ok) {
+        tell(provider, null);
+        return refuse(adapter, actionKey, started.code, started.message, { execute: started });
+    }
+    const startedSeq = started.record.seq;
+    // (e) The adapter's own step, inside the credential window.
+    //
+    // `entered` is the custody boundary of APRV-120, and it is positional rather
+    // than a judgment: everything up to and including the read of `adapter.act`
+    // is preparation this runtime performed and can speak for, and the instant
+    // after it the call is the far side's. A throw on the near side is
+    // `execution.failed` — nothing was attempted. A throw on the far side is
+    // `execution.indeterminate` — the provider may or may not have committed, and
+    // saying "failed" about it is the assertion that produces double sends.
+    const scope = scopeCredentials(provider);
+    // Everything the pre-token resolution was handed is already a secret this
+    // path may be about to print, so it joins the corpus before `act` runs rather
+    // than only if `act` happens to ask for the same names again. The precheck's
+    // window is closed by now and its values join for the same reason.
+    for (const secret of resolved.issued)
+        scope.issued.add(secret);
+    for (const secret of prechecked.issued)
+        scope.issued.add(secret);
+    // The window is now a GRANTED one, and the provider is told so (APRV-168).
+    // Minted here because this is the only place that can: the brand on
+    // `ExecutionGrant` is a symbol no other module can name. It is dropped in the
+    // same `finally` that closes the window, so the capability it carries lives
+    // exactly as long as `act` does.
+    // The brand is a type-level marker with no runtime member (a `declare const
+    // unique symbol` emits nothing), so the cast is what mints it. That is the
+    // point: the cast compiles here and refuses to compile anywhere the brand
+    // cannot be named, which is everywhere else.
+    tell(provider, {
+        phase: "consumed",
+        actionKey,
+        startedSeq,
+        autonomy: started.autonomy,
+        ...(started.tokenSha256 === undefined ? {} : { tokenSha256: started.tokenSha256 }),
+    });
+    let entered = false;
+    let outcome;
+    let threw = null;
+    try {
+        const input = {
+            actionKey,
+            payload,
+            credentials: scope.provider,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        };
+        const act = adapter.act.bind(adapter);
+        entered = true;
+        outcome = await act(input);
+    }
+    catch (error) {
+        // The message and nothing else: a stack trace quotes call arguments, and a
+        // credential passed as one would ride out of here inside an error report.
+        threw = error instanceof Error ? error.message : String(error);
+        outcome = { ok: false, code: "adapter-act-threw", message: threw };
+    }
+    finally {
+        scope.close();
+        // The window and the grant end together. A provider that kept the grant is
+        // holding a value the contract no longer honours, and it was told so.
+        tell(provider, null);
+    }
+    // (f) The redaction sweep, THEN the outcome event, then the redacted result.
+    //
+    // The sweep runs first because one thing it produces now goes into the record
+    // rather than only into the result: the provider reference of APRV-251, which
+    // the adapter names inside its own detail and which therefore passes exactly
+    // the scan every other returned string passes before anything writes it down.
+    // Nothing else about the ordering matters — the sweep reads the outcome and
+    // the issued secrets, both settled the moment `act` returned.
+    const secrets = scope.issued;
+    const unknown = threw !== null && entered;
+    const exitCode = outcome.ok ? 0 : ADAPTER_FAILURE_EXIT_CODE;
+    const failureCode = threw === null ? "adapter-failed" : "adapter-act-threw";
+    const rawMessage = outcome.ok ? "" : outcome.message;
+    const message = redactSecrets(rawMessage, secrets);
+    const adapterCode = redactSecrets(outcome.ok ? "" : outcome.code, secrets);
+    const detail = outcome.ok && outcome.detail !== undefined
+        ? redactJson(outcome.detail, secrets)
+        : { value: null, hits: 0 };
+    const redactions = message.hits + adapterCode.hits + detail.hits;
+    // Only a completion has an effect for a provider to have filed, and only the
+    // adapter can say what its receipt called it. The `adapter` half is this
+    // runtime's own knowledge of which adapter it called, never a claim the
+    // detail makes about itself.
+    const providerRef = outcome.ok
+        ? providerRefFor(adapter.name, outcome.detail, detail.value)
+        : null;
+    const finished = unknown
+        ? indeterminateExecution(logPath, actionKey, "act-threw", actor, executeOptions)
+        : finishExecution(logPath, actionKey, exitCode, actor, {
+            ...executeOptions,
+            ...(providerRef === null ? {} : { providerRef }),
+        });
+    if (!finished.ok) {
+        return {
+            ok: false,
+            code: finished.code,
+            message: `${adapter.name} ${outcome.ok ? "completed" : "did not complete"} action ${actionKey}, and the outcome could not be recorded: ${finished.message}. The side effect was attempted and the log now holds a dangling execution; close it with \`approval execution resolve\`.`,
+            adapter: adapter.name,
+            action_key: actionKey,
+            acted: entered,
+            started_seq: startedSeq,
+            execute: finished,
+            redactions,
+        };
+    }
+    if (unknown) {
+        // The message is the adapter's, redacted, and it reaches the CALLER only:
+        // the record carries the closed reason and nothing else (APRV-120 #3).
+        return {
+            ok: false,
+            code: "execution-indeterminate",
+            message: `${adapter.name} entered act for ${actionKey} and raised, so the log records execution.indeterminate at seq ${finished.record.seq}: the side effect was attempted and nobody knows whether it committed. The token is spent and the idempotency key is burned; a retry is refused. Establish what happened and record it with \`approval execution reconcile\`. The adapter reported: ${message.text}`,
+            adapter: adapter.name,
+            action_key: actionKey,
+            acted: true,
+            started_seq: startedSeq,
+            outcome: "execution.indeterminate",
+            outcome_seq: finished.record.seq,
+            adapter_code: adapterCode.text,
+            redactions,
+        };
+    }
+    if (!outcome.ok) {
+        return {
+            ok: false,
+            code: failureCode,
+            message: message.text,
+            adapter: adapter.name,
+            action_key: actionKey,
+            // A throw BEFORE act was entered attempted nothing: the credential window
+            // or the adapter's own method raised, and no side effect was reached.
+            acted: entered,
+            started_seq: startedSeq,
+            outcome: "execution.failed",
+            outcome_seq: finished.record.seq,
+            exit_code: exitCode,
+            adapter_code: adapterCode.text,
+            redactions,
+        };
+    }
+    return {
+        ok: true,
+        adapter: adapter.name,
+        action_key: actionKey,
+        task: started.task,
+        class: started.class,
+        autonomy: started.autonomy,
+        payload_hash: hash,
+        started_seq: startedSeq,
+        outcome: "execution.completed",
+        outcome_seq: finished.record.seq,
+        exit_code: 0,
+        ...(outcome.detail === undefined ? {} : { detail: detail.value }),
+        // What the log now says this effect is called on the provider's side, so a
+        // caller reads the recorded reference rather than re-deriving it from the
+        // detail and reaching a different answer (APRV-251).
+        ...(providerRef === null ? {} : { provider_ref: providerRef }),
+        redactions,
+    };
+}
+//# sourceMappingURL=contract.js.map