approval-md 0.0.1 → 0.2.0

package/dist/src/core/telegram-config.js

@@ -0,0 +1,114 @@
+/**
+ * Telegram configuration NAMES (SPEC.md §5.1 `channels.telegram.token_env` /
+ * `chat_id_env`, amended §5.2 by APRV-72).
+ *
+ * Constants and resolvers live in core, not in `channels/`, because more than
+ * one layer needs them: the Telegram CLI, doctor, and `approval env` (APRV-73)
+ * all ask "which variable holds the token?" and none of them may answer it
+ * differently. Placing them here also keeps `core/` free of any import from
+ * `channels/`, in the spirit of `tests/layering.test.ts`.
+ *
+ * NAMES only, in both directions: a policy that carried the token would be a
+ * bot credential in a file agents may read, which is exactly what §5.1's
+ * name-indirection exists to prevent. A policy that failed to load names
+ * nothing, so the default applies: a variable name is not a permission, and
+ * treating it as one would mean an unrelated policy typo locked the operator
+ * out of their own channel. This is `passphraseEnvFor`'s argument, verbatim,
+ * for the same reason: these are the same kind of key.
+ *
+ * Nothing here reads `process.env`. The CLI layer takes the name and looks
+ * the value up.
+ */
+/**
+ * The environment variable the bot token is read from when the policy declares
+ * no `channels.telegram.token_env`. A DEFAULT, not a fixed name: see
+ * {@link telegramTokenEnvFor}.
+ */
+export const TELEGRAM_TOKEN_ENV = "APPROVAL_TG_TOKEN";
+/**
+ * The environment variable the approver chat id is read from when the policy
+ * declares no `channels.telegram.chat_id_env`. Also a default.
+ */
+export const TELEGRAM_CHAT_ENV = "APPROVAL_TG_CHAT";
+/** The NAME of the variable this policy says the bot token lives in. */
+export function telegramTokenEnvFor(load) {
+    return declaredEnvName(load, "token_env") ?? TELEGRAM_TOKEN_ENV;
+}
+/** The NAME of the variable this policy says the approver chat id lives in. */
+export function telegramChatEnvFor(load) {
+    return declaredEnvName(load, "chat_id_env") ?? TELEGRAM_CHAT_ENV;
+}
+/**
+ * What an absent `channels.telegram.delivery` means.
+ *
+ * Paced, since APRV-216. The incident behind it is the one APRV-196 softened
+ * rather than closed: a restart with six pending policy edits put six prompts
+ * on a phone at once, and an approver reading a wall of near-identical
+ * questions is an approver who taps rather than reads. A default is a claim
+ * about which failure is worse, and the worse one here is inattentive approval
+ * rather than a slower queue: pacing withholds nothing, because every request
+ * stays pending in the log whether or not it has been shown, and `/queue`
+ * lists the whole set on demand.
+ */
+export const TELEGRAM_DEFAULT_DELIVERY = "paced";
+/**
+ * The delivery mode this policy declares, or the default.
+ *
+ * Fail-soft in the same direction as the two name resolvers above: a policy
+ * that did not load declares nothing, and a delivery mode is not a permission,
+ * so an unrelated policy typo must not decide how requests are shown. The
+ * schema closes the enum, so a policy that LOADED can only carry one of the
+ * two; anything else reaching here (a hand-built load result, a key from a
+ * later version) falls back rather than being guessed at.
+ */
+export function telegramDeliveryFor(load) {
+    if (!load.ok)
+        return TELEGRAM_DEFAULT_DELIVERY;
+    const declared = load.policy.channels?.["telegram"]?.["delivery"];
+    if (declared === "paced" || declared === "burst")
+        return declared;
+    return TELEGRAM_DEFAULT_DELIVERY;
+}
+/**
+ * The Telegram channel's credential manifest (APRV-79).
+ *
+ * The same shape an adapter declares (`core/credential-spec.ts`), for the same
+ * reason: `approval setup channel telegram` runs the shared conversation in
+ * `cli/setup-flow.ts`, and that conversation is DERIVED from a manifest. What
+ * differs from an adapter's is the destination and not the vocabulary — a
+ * channel's two values go to the OS keystore and `.approval/env`, because a
+ * channel holds no state and its token is what unlocks the machine, while an
+ * adapter's go to the vault (SPEC.md §4, §10.3, §10.4).
+ *
+ * The NAMES are the policy's, resolved through the two functions above, so the
+ * checklist an operator reads names the variables their own policy declares.
+ * A spec carries no value and no default on either entry: the token is the
+ * operator's and the chat id is discovered.
+ */
+export function telegramCredentialSpecs(load) {
+    return [
+        {
+            name: telegramTokenEnvFor(load),
+            kind: "secret",
+            label: "bot token from @BotFather",
+            describe: "the bot credential, stored in the OS keystore; this file records only where it lives",
+            required: true,
+        },
+        {
+            name: telegramChatEnvFor(load),
+            kind: "config",
+            label: "approver chat id",
+            describe: "discovered from the bot's updates, written as a literal: a chat id is not a secret",
+            required: true,
+        },
+    ];
+}
+/** A non-empty string under `channels.telegram.<key>`, or `null`. */
+function declaredEnvName(load, key) {
+    if (!load.ok)
+        return null;
+    const telegram = load.policy.channels?.["telegram"];
+    const declared = telegram === undefined ? undefined : telegram[key];
+    return typeof declared === "string" && declared.length > 0 ? declared : null;
+}
+//# sourceMappingURL=telegram-config.js.map

package/dist/src/core/telegram-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram-config.js","sourceRoot":"","sources":["../../../src/core/telegram-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAEtD;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAEpD,wEAAwE;AACxE,MAAM,UAAU,mBAAmB,CAAC,IAAsB;IACxD,OAAO,eAAe,CAAC,IAAI,EAAE,WAAW,CAAC,IAAI,kBAAkB,CAAC;AAClE,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,kBAAkB,CAAC,IAAsB;IACvD,OAAO,eAAe,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,iBAAiB,CAAC;AACnE,CAAC;AAiBD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAqB,OAAO,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAsB;IACxD,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,yBAAyB,CAAC;IAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC;IAClE,IAAI,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,QAAQ,CAAC;IAClE,OAAO,yBAAyB,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAsB;IAC5D,OAAO;QACL;YACE,IAAI,EAAE,mBAAmB,CAAC,IAAI,CAAC;YAC/B,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,2BAA2B;YAClC,QAAQ,EACN,sFAAsF;YACxF,QAAQ,EAAE,IAAI;SACf;QACD;YACE,IAAI,EAAE,kBAAkB,CAAC,IAAI,CAAC;YAC9B,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,kBAAkB;YACzB,QAAQ,EACN,oFAAoF;YACtF,QAAQ,EAAE,IAAI;SACf;KACF,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,SAAS,eAAe,CAAC,IAAsB,EAAE,GAAW;IAC1D,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,UAAU,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACpE,OAAO,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/E,CAAC"}

package/dist/src/core/token.d.ts

@@ -0,0 +1,409 @@
+/**
+ * Execution tokens (SPEC.md §10.4, §11) — the hard-enforcement primitive.
+ *
+ * An adapter holds credentials and "MUST require a valid, unexpired, single-use
+ * execution token bound to the action's `idempotency_key`" (SPEC.md §10.4).
+ * This module mints those tokens, decides whether a presented one is still good,
+ * and spends it. Everything it knows it derives from the append-only log.
+ *
+ * ## The five settled properties (human decision, 2026-08-06)
+ *
+ * 1. **Minted at grant.** There is exactly one mint site: the grant path of
+ *    `core/gate.ts`'s {@link import("./gate.js").decide}. No other code path
+ *    creates a token, so a token's existence *is* a human's yes.
+ * 2. **Single-use.** Consumption is an `execution.started` event, so the second
+ *    attempt is refused by reading the log rather than by remembering anything.
+ *    Double-spend detection is chain-native: it survives a process restart, a
+ *    different machine, and a lost in-memory cache, because the evidence is the
+ *    log itself.
+ * 3. **Bound to the request, its `idempotency_key`, and its `payload_hash`**
+ *    (amended SPEC.md §10, A1). A token is looked up by `action_key` — the
+ *    envelope's `idempotency_key` — and is compared against the hash on *that*
+ *    action's grant. A token minted for action A therefore cannot be presented
+ *    for action B: B's grant carries a different hash (or no grant at all), and
+ *    the comparison fails. The third binding is to the bytes: a consumer states
+ *    the hash of the payload it is about to execute, and anything but the hash
+ *    the grant recorded is refused `payload-mismatch`. A grant approves specific
+ *    bytes; changing them after grant requires a new request. A grant that
+ *    recorded *no* bytes is refused too — see {@link consumeToken}.
+ * 4. **Hash-only in the log.** `approval.granted` carries
+ *    `payload.token_sha256`; the raw token is returned to the caller of `decide`
+ *    and to nothing else. Possession is proven by presenting a preimage. An
+ *    attacker with a copy of the log — the one artifact this system deliberately
+ *    makes durable, copyable, and auditable — gains no ability to execute.
+ * 5. **No separate token TTL in v0.1.** A token dies exactly three ways:
+ *    execution ({@link consumeToken}), revocation (`approval.revoked`), and the
+ *    lapse of the *parent request's* TTL (`defaults.approval_ttl`, measured from
+ *    the `approval.requested` timestamp). Inventing a second, independent clock
+ *    would create a state where a request is live and its token is not, which no
+ *    operator could explain from the log.
+ *
+ * ## Why the parent TTL bounds a *granted* request
+ *
+ * `requestState` deliberately stops applying the TTL once a decision lands: an
+ * answered request is answered. Token liveness is a stricter question than
+ * request state, and the settled design gives an approval a shelf life. So
+ * {@link tokenStatus} re-applies `requestTs + approval_ttl` to a *granted*
+ * request and refuses with `token-expired` past it. This never mutates the
+ * derived request state and never writes anything — an aged-out token is simply
+ * not spendable, and re-requesting the action is the repair. (Contrast
+ * `core/gate.ts`, which materialises `approval.expired` when it discovers a
+ * lapse on an *undecided* request. That branch belongs to the gate and this
+ * module does not duplicate it: a granted request's `approval.expired` would
+ * claim the human never answered.)
+ *
+ * ## Where this module sits between APRV-16 and APRV-18
+ *
+ * `core/gate.ts` deliberately appends no `execution.*` event. {@link
+ * consumeToken} is the **only sanctioned appender of `execution.started` on the
+ * manual path**, and it appends one only after a live token verifies — closing
+ * the gap APRV-16 flagged, where a manual action's start event had no guard at
+ * all.
+ *
+ * The supervised/autonomous paths are **not** this function's business. Under
+ * the amended SPEC.md §6.3 they produce no approval events and therefore no
+ * token; their `execution.started` is appended by APRV-18's `approval run`
+ * wrapper, which is also where their budget is charged (see the consumption
+ * contract in `core/budgets.ts`). One rule, stated once: *manual actions spend a
+ * token here; non-manual actions start there.*
+ *
+ * ## The budgets contract
+ *
+ * The appended `execution.started` carries `payload.class` and
+ * `payload.est_cost_usd`, **copied from the grant's payload** rather than
+ * re-derived. `core/budgets.ts` counts an `execution.started` only when the
+ * window holds no `approval.granted` with the same `action_key`, so a manual
+ * action that is granted and then consumed is charged exactly once — the grant.
+ * Copying rather than re-deriving keeps the two records agreeing about what was
+ * authorized even if the task file changed in between.
+ *
+ * ## Time
+ *
+ * {@link tokenStatus} and {@link verifyToken} are pure and take `now` as a
+ * parameter: they answer a question and write nothing, so a caller asking "was
+ * this token live at time T?" is asking something legitimate. {@link
+ * consumeToken} *writes*, and `execution.started` is a gate-typed event, so
+ * amended SPEC.md §8 (A2) gives its timestamp to the runtime: no `ts`
+ * parameter, one read of {@link TokenOptions.clock} at the top, and a spender
+ * that cannot choose the moment its own TTL is judged at.
+ */
+import { type ClockOptions } from "./clock.js";
+import { type AppendError, type AppendOptions, type EventRecord } from "./log.js";
+import { type PolicyLoadResult } from "./policy-load.js";
+import type { SandboxState } from "./sandbox.js";
+import { type RequestState } from "./state.js";
+/** Token entropy. 32 bytes = 256 bits, rendered as 64 lowercase hex chars. */
+export declare const TOKEN_BYTES = 32;
+/** The payload key carrying the token's digest, on both grant and start. */
+export declare const TOKEN_HASH_FIELD = "token_sha256";
+/** The payload key carrying the content binding (amended SPEC.md §6.2, §10). */
+export declare const PAYLOAD_HASH_FIELD = "payload_hash";
+/**
+ * Mint a token: 32 cryptographically random bytes as lowercase hex.
+ *
+ * `randomBytes` (CSPRNG), never `Math.random`. The value is a bearer credential
+ * for a real-world side effect; 256 bits makes guessing irrelevant next to every
+ * other attack in SPEC.md §11's "not defended" list.
+ */
+export declare function mintToken(): string;
+/** The token's SHA-256, lowercase hex — the only form that ever reaches the log. */
+export declare function tokenHash(token: string): string;
+/**
+ * Constant-time comparison of two 64-hex digests.
+ *
+ * Both operands are digests, so a timing leak reveals a prefix of a *hash*, not
+ * of a token — but this CLI runs on a shared developer machine beside the very
+ * agents it polices, and an oracle that says "your first N hex digits were
+ * right" is the kind of affordance that should not exist at all. `timingSafeEqual`
+ * costs nothing here and removes the question.
+ *
+ * Digests are compared as decoded bytes: a malformed stored digest decodes to a
+ * different length, which `timingSafeEqual` rejects by throwing, so the length
+ * guard comes first and a malformed digest simply fails to match.
+ */
+export declare function digestsEqual(a: string, b: string): boolean;
+/**
+ * The token refusals proper — the closed set an agent branches on to learn *why*
+ * a token will not execute. Frozen public API, in the same sense the gate's
+ * codes and the exit codes are.
+ *
+ * The four death conditions are distinguishable on purpose: "you presented the
+ * wrong string", "this token was already spent", "a human took it back", and
+ * "it aged out" call for four different responses (fix the caller, stop
+ * retrying, escalate to the human, re-request).
+ */
+export declare const TOKEN_VERIFY_REFUSAL_CODES: readonly [
+/** No grant governs this action key: never requested, awaiting, or rejected. */
+"not-granted", 
+/** A grant exists, but the presented token is not its preimage. */
+"token-mismatch", 
+/** The token was already spent: an `execution.started` exists for this key. */
+"token-consumed", 
+/** The parent request's TTL lapsed. There is no separate token TTL. */
+"token-expired", 
+/** A human withdrew the grant (`approval.revoked`). */
+"token-revoked", 
+/**
+ * The bytes do not match (amended SPEC.md §10, A1). The grant recorded a
+ * `payload_hash` and the consumer presented a different one — or none at all,
+ * which is the same fact stated by omission: an executor that cannot say what
+ * it is about to run has not shown that it is running what was approved.
+ *
+ * Distinct from `token-mismatch` on purpose. That one says "you are not the
+ * party who was approved"; this one says "you are, but that is not what was
+ * approved", and the repair is different: request the new payload rather than
+ * hunt for a lost token.
+ */
+"payload-mismatch", 
+/**
+ * The grant was for a harness-executed request and minted no token
+ * (APRV-106). Nothing is wrong: the requesting process runs the command
+ * itself and never had a token to spend, so there is nothing to present here
+ * and nothing to recover. Distinct from `token-mismatch`, which says a
+ * digest exists and does not match, and from `not-granted`, which says no
+ * authorization exists at all — this one says the authorization exists, is
+ * complete, and is not the kind that is spent.
+ */
+"harness-executed"];
+export type TokenVerifyRefusalCode = (typeof TOKEN_VERIFY_REFUSAL_CODES)[number];
+/**
+ * Everything {@link consumeToken} can refuse: the verification codes plus the
+ * three log/append failures, whose names and meanings are borrowed verbatim from
+ * `core/gate.ts` so the CLI can map them onto the frozen exit table identically.
+ */
+export declare const TOKEN_REFUSAL_CODES: readonly ["not-granted", "token-mismatch", "token-consumed", "token-expired", "token-revoked", "payload-mismatch", "harness-executed", "class-human-only", "log-unreadable", "log-torn-tail", "log-corrupt", "append-failed"];
+export type TokenRefusalCode = (typeof TOKEN_REFUSAL_CODES)[number];
+/** Every token failure is one of these. Nothing here throws. */
+export interface TokenRefusal {
+    ok: false;
+    code: TokenRefusalCode;
+    message: string;
+    /** The derived request state at refusal time, when one could be derived. */
+    state?: RequestState;
+    /** The seq of the record that produced the refusal (grant, start, revoke). */
+    seq?: number;
+    /** The underlying append error, when `code` is `append-failed`. */
+    append?: AppendError;
+}
+/** A live, unspent grant and everything a consumer needs to spend it. */
+export interface TokenStatus {
+    ok: true;
+    actionKey: string;
+    /** The task id the grant names; `execution.started` requires it. */
+    task: string | null;
+    /** The `approval.granted` record's seq — the mint site, for audit. */
+    grantSeq: number;
+    /** The digest recorded at mint. The raw token is not stored anywhere. */
+    tokenSha256: string;
+    /** Copied from the grant payload, per the budgets consumption contract. */
+    class: string;
+    /**
+     * Canonical decimal USD string (APRV-121), copied from the grant and written
+     * verbatim onto `execution.started`. The value is hashed material at both
+     * ends, so it is carried as the string the grant recorded rather than parsed
+     * into a number and reserialized.
+     */
+    est_cost_usd: string;
+    /**
+     * The bytes this grant approved (amended SPEC.md §10), or `null` for a grant
+     * that recorded none. Unreachable through the gate for a manual action —
+     * `request` refuses `payload-hash-required` — so `null` here means a log
+     * written by something other than this runtime, or one predating A1.
+     *
+     * `null` does not mean "unbound and therefore free": {@link consumeToken}
+     * refuses such a grant `payload-mismatch` and it can never be spent. This
+     * field is `string | null` so a *reader* (`approval token`, a channel) can
+     * report the fact; it is never a permission.
+     */
+    payloadHash: string | null;
+    /** The `approval.requested` timestamp the TTL is measured from. */
+    requestTs: string | null;
+}
+export type TokenStatusResult = TokenStatus | TokenRefusal;
+/**
+ * Is there a live, unspent token for `actionKey` — and what is its digest?
+ *
+ * Pure: no I/O, no clock. `now` is the moment the question is asked; `ttlMs` is
+ * `defaults.approval_ttl` as the policy loader parsed it, or `null` for a policy
+ * that declares no lapse (in which case a granted token stays spendable until it
+ * is used or revoked, exactly as an undecided request stays live).
+ *
+ * Check order, and why:
+ *
+ * 1. **Revoked**, then **expired-by-derivation**, then **anything not granted**.
+ *    A withdrawn authorization and a lapsed one are different facts and get
+ *    different codes; everything else — never requested, still awaiting,
+ *    rejected — is `not-granted`, because from a token's point of view they are
+ *    the same absence.
+ * 2. **The parent TTL, re-applied to the grant.** See the module header.
+ * 3. **The recorded digest.** A grant with no usable `token_sha256` is a grant
+ *    minted before this module existed (or by something else); it cannot
+ *    authenticate anything, so it fails closed as `token-mismatch`.
+ * 4. **Consumption.** Any `execution.started` for this action key spends it —
+ *    matching digest or not. The narrow rule (same digest) is what makes
+ *    double-spend detection chain-native; the broader rule (same action key)
+ *    enforces SPEC.md §7's single-use idempotency key even against a start event
+ *    that named no token, and both answer `token-consumed`.
+ */
+export declare function tokenStatus(records: EventRecord[], actionKey: string, now: string, ttlMs?: number | null): TokenStatusResult;
+/**
+ * The raw token for `actionKey`, recovered from the log's `token_sealed` with
+ * the private key this machine holds — or `null`.
+ *
+ * `null` means "no token was delivered here", and it means it for every reason
+ * at once: the policy is `manual` and nothing was sealed, this is a different
+ * machine from the one that requested, the key file has already been unlinked
+ * because the token was spent, or the ciphertext does not authenticate. The
+ * caller's response is identical in all four cases — fall back to the raw token
+ * the granting surface printed — and distinguishing them would be an oracle for
+ * a decryption capability nobody should be probing.
+ *
+ * Recovering a minted token is not minting one. The token still exists only
+ * because a human granted it, still binds to the payload, and is still spendable
+ * exactly once; what this function replaces is the human carrying it in a
+ * clipboard. Nothing here consults, relaxes, or substitutes for
+ * {@link verifyToken}: the value returned goes on to be verified against the
+ * log's digest like any pasted one.
+ *
+ * Pure with respect to the LOG (it appends nothing) and reads exactly one file.
+ * Never throws.
+ */
+export declare function deliveredToken(records: readonly EventRecord[], actionKey: string, keyDir: string): string | null;
+/**
+ * Does `presentedToken` authorize `actionKey` right now?
+ *
+ * Accepts **iff** all five hold: the latest cycle for the key derives as
+ * `granted`; the parent request's TTL has not lapsed; the grant has not been
+ * revoked; no `execution.started` has spent it; and `sha256(presentedToken)`
+ * equals the digest recorded on the grant, compared in constant time.
+ *
+ * `ttlMs` is the parsed `defaults.approval_ttl`. It is a parameter rather than a
+ * policy read because this function is pure — {@link consumeToken} and the CLI
+ * load the policy and hand it in, so a verification can be replayed from the log
+ * plus the policy that was in force.
+ */
+export declare function verifyToken(records: EventRecord[], actionKey: string, presentedToken: string, now: string, ttlMs?: number | null): TokenStatusResult;
+/**
+ * Where to find the policy whose `approval_ttl` bounds the token — plus the two
+ * things a spend now carries that a status read does not.
+ *
+ * `ts` is not among them, and no longer a parameter of {@link consumeToken}:
+ * `execution.started` is a gate-typed event, so amended SPEC.md §8 gives its
+ * timestamp to the runtime at the write boundary ({@link ClockOptions}).
+ */
+export interface TokenOptions extends ClockOptions {
+    /** Schema directory, passed to the append's write-boundary validation. */
+    schemaDir?: string;
+    /** Directory to discover `APPROVAL.md` in. Ignored when `policyFile` is set. */
+    policyDir?: string;
+    /** An explicit policy file, overriding discovery. */
+    policyFile?: string;
+    /** Lock tuning for the append path. */
+    append?: AppendOptions;
+    /**
+     * The hash of the payload the caller is **about to execute** (amended
+     * SPEC.md §10, A1).
+     *
+     * "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." That is this field: it is not read from the log, because a value
+     * read from the log would prove nothing — the point is that the executor
+     * states, independently, what it holds, and the runtime compares.
+     *
+     * REQUIRED for every spend. Under A1 every manual grant this runtime mints
+     * records a `payload_hash`, and a grant that somehow records none is refused
+     * outright rather than treated as unbound — so there is no case in which
+     * omitting this field succeeds. Omitting it is a mismatch.
+     */
+    presentedPayloadHash?: string;
+    /**
+     * How many credential-bearing variables the executor withheld from the child
+     * it is about to spawn (APRV-205), recorded on the `execution.started` this
+     * spend appends.
+     *
+     * The manual path's copy of `ExecuteOptions.envStripped`, and it exists
+     * because the manual path's `execution.started` is written HERE rather than
+     * in `core/execute.ts`. A count recorded on one of the two start events and
+     * not the other would be a field an auditor could not rely on. A count, never
+     * a name and never a value.
+     */
+    envStripped?: number;
+    /**
+     * The room the child ran in (APRV-193), recorded on the `execution.started`
+     * this spend appends. The manual path's copy of `ExecuteOptions.sandbox`, for
+     * the same reason the count above is: a field recorded on one of the two
+     * start events and not the other is a field an auditor cannot rely on.
+     */
+    sandbox?: SandboxState;
+}
+export type ConsumeResult = {
+    ok: true;
+    record: EventRecord;
+    tokenSha256: string;
+    grantSeq: number;
+} | TokenRefusal;
+/** The parsed TTL, or `null` when the policy declares (or can declare) none. */
+export declare function tokenTtlMs(options: TokenOptions): number | null;
+/** The policy this module reads, loaded once per operation. */
+export declare function tokenPolicy(options: TokenOptions): PolicyLoadResult;
+/**
+ * Is `actionClass` reserved to human hands under `load` (APRV-185)?
+ *
+ * Returns the refusal to emit, or `null`. Shared by {@link consumeToken} and by
+ * the `approval token` verb, which report the same fact about the same class
+ * and must not word it two ways.
+ *
+ * The §7 irreversibility floor is deliberately not consulted: it raises to
+ * `manual` at most and can neither produce `human-only` nor remove it, so the
+ * grant's declared `reversible` — which this module does not carry anyway —
+ * cannot change this answer.
+ */
+export declare function humanOnlyClassRefusal(load: PolicyLoadResult, actionClass: string | null, whatWasRefused: string): TokenRefusal | null;
+/**
+ * Verify every read-only condition of a token spend.
+ *
+ * Shared by {@link consumeToken} and adapter execution preflight. It appends
+ * nothing and grants no authority to act; `consumeToken` re-reads and repeats
+ * this check immediately before its compare-and-append.
+ */
+export type TokenSpendStatus = TokenStatus & {
+    task: string;
+    payloadHash: string;
+};
+export declare function verifyTokenSpend(records: EventRecord[], actionKey: string, presentedToken: string, now: string, load: PolicyLoadResult, presentedPayloadHash?: string): TokenSpendStatus | TokenRefusal;
+/**
+ * Spend a token: verify it, then append `execution.started`.
+ *
+ * **This is the only sanctioned way to append `execution.started` for a manual
+ * action.** APRV-16 left that gap open deliberately — the gate appends no
+ * execution events — and this function closes it: on the manual path a start
+ * event now requires a live, verified, unspent token, so an agent cannot record
+ * an execution the human never authorized. Supervised and autonomous actions
+ * have no grant and therefore no token; their start event is APRV-18's `approval
+ * run` wrapper's job, and calling this for them correctly refuses `not-granted`.
+ *
+ * The payload is exactly `{class, est_cost_usd, token_sha256, payload_hash}`:
+ * the first two because `core/budgets.ts` meters authorization from them, the
+ * third because it is what makes the second consumption attempt refusable from
+ * the log alone, and the fourth because an auditor should be able to see from
+ * the log that what ran is what was approved. All four are copied from the
+ * grant, never re-derived. `payload_hash` is unconditional because a grant
+ * carrying none is refused (see below) rather than spent.
+ *
+ * Verification and append are made atomic by compare-and-append (APRV-20 finding
+ * B1): this function reads the log itself — never records handed in by a caller —
+ * and passes the head it read as `appendEvent`'s `expectedHead`. Two genuinely
+ * concurrent consumers of one token therefore cannot both start. Whichever takes
+ * the lockfile first appends `execution.started`; the loser finds the head moved
+ * under the lock and is refused `append-failed`/`head-moved` with nothing
+ * written. The loser is **not** retried here: re-reading would report
+ * `token-consumed`, but deciding to look again is the caller's call, and a core
+ * that silently retried would hide a double-spend attempt behind a tidy error.
+ *
+ * `actor` is not pre-validated: the event schema is the authority on actor
+ * shape, and a malformed one is refused at the write boundary as
+ * `append-failed`, with the schema's own error attached. One rule about actors,
+ * enforced in one place.
+ */
+export declare function consumeToken(logPath: string, actionKey: string, presentedToken: string, actor: string, options?: TokenOptions): ConsumeResult;