approval-md 0.1.0 → 0.3.0

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

@@ -0,0 +1,1449 @@
+/**
+ * The gate: request lifecycle and write-boundary transition enforcement
+ * (SPEC.md §6.3, §7, §10.1).
+ *
+ * This is the module that decides whether a side effect may be authorized, and
+ * it is the only module that appends approval lifecycle events. Everything it
+ * knows it derives from the append-only log; everything it decides it decides
+ * before a byte is written.
+ *
+ * ## Four rules this module exists to enforce
+ *
+ * 1. **State is derived, never stored.** {@link requestState} rebuilds one
+ *    action's approval state from the log alone. There is no status field, no
+ *    cache, no in-memory session. The envelope's `state:` key is a projection
+ *    written by the daemon *after* the event lands (SPEC.md §6.3), never a
+ *    source this module reads.
+ * 2. **Illegal transitions are refused before append.** A second grant, a grant
+ *    on a rejected request, a revoke of an executed action, a decision after the
+ *    TTL — each is refused with its own machine-readable code and **nothing is
+ *    appended**. The one deliberate exception is a failed budget check, which
+ *    appends `budget.exceeded` *and then* refuses: a budget refusal is a fact
+ *    about the world that an operator must be able to see afterwards, and a
+ *    refusal nobody can audit is how quiet budget creep starts.
+ * 3. **No approval events off the manual path** (amended SPEC.md §6.3). An
+ *    action whose class resolves to `supervised` or `autonomous` produces *no*
+ *    `approval.*` record at all — {@link request} returns `proceed: true` and
+ *    appends nothing. Its authorization is recorded by `execution.started`,
+ *    which APRV-18 appends, and which is also where its budget is charged (see
+ *    the consumption contract in `core/budgets.ts`).
+ * 4. **Time is assigned by the runtime, not by the caller** (amended SPEC.md
+ *    §8, A2). No public function here takes a `ts`. TTL lapse, budget windows,
+ *    and the timestamp stamped on every append all come from one read of
+ *    {@link GateOptions.clock} — the real clock unless a caller injects one —
+ *    made once per operation, so a gate decision is still replayable from its
+ *    inputs while the party being judged no longer authors the clock it is
+ *    judged by. Tests inject a fixed clock; production passes none.
+ *
+ * ## Lazy expiry — the named requirement
+ *
+ * A request expires when `ts > requestTs + defaults.approval_ttl`, **whether or
+ * not** an `approval.expired` event exists. Nothing may depend on a daemon
+ * having run: if the expiry sweep is asleep, a late grant must still be refused.
+ * {@link requestState} therefore computes expiry two ways — from the event, and
+ * lazily from the arithmetic — and treats them as equivalent.
+ *
+ * When {@link decide} refuses a decision because the TTL has lapsed and no
+ * `approval.expired` event exists yet, it **first appends that event** (actor
+ * {@link EXPIRY_ACTOR}) and then refuses. The alternative — refuse silently and
+ * leave the log claiming the request is still live — was rejected: the log is
+ * the truth, and a state every reader can derive but no reader can see recorded
+ * makes the log disagree with itself. The append is the same one
+ * {@link expire} would have made, so a later sweep is a no-op rather than a
+ * duplicate.
+ *
+ * ## `defaults.on_expiry`
+ *
+ * SPEC.md §5 defines exactly one value, `reject`. An expired request is
+ * terminal here under either setting: no grant, no reject, no revoke ever
+ * follows it. `on_expiry` is recorded in the `approval.expired` payload so the
+ * projection layer (M5) can render the envelope's `state:` as `rejected` rather
+ * than `expired` when the policy asks for it. Re-requesting the same action key
+ * after expiry is a *new* request and is allowed — the key has not executed, and
+ * refusing forever would make a lapsed TTL more punishing than a human's "no".
+ *
+ * ## The budgets contract (`core/budgets.ts`)
+ *
+ * That module obligates this one: every `approval.granted` this module appends
+ * carries `payload.est_cost_usd` (number, USD) and `payload.class` (the dotted
+ * class). `approval.requested` carries them too, so the grant can copy them from
+ * the request rather than re-derive them from a file that may have changed. An
+ * action that declared no cost is recorded as `0` — an authorization with no
+ * declared cost is still an authorization, and still counts as one action.
+ *
+ * ## Reads are verified, writes are compare-and-append (APRV-20)
+ *
+ * The gate no longer trusts the bytes it reads. {@link readGateRecords}
+ * delegates to `core/state.ts`, which runs the *same* chain verification
+ * `approval log verify` runs — one walk, one vocabulary — and refuses
+ * `log-corrupt` on anything that does not verify. The gate still does not
+ * *diagnose* corruption: it reports that the log is untrustworthy and points at
+ * `approval log verify` for the detail, because two modules with two opinions
+ * about what "corrupt" means is worse than one.
+ *
+ * Every append this module makes is authorized by something it read, so every
+ * append passes `expectedHead` — the `(seq, hash)` observed at that read. If any
+ * record landed in between, `appendEvent` refuses `head-moved` under its lock
+ * and nothing is written.
+ *
+ * Every writer of this module then re-derives and tries again, bounded
+ * (APRV-150 for the two harness writers, APRV-236 for {@link register},
+ * {@link request}, {@link decide}, {@link withdraw} and
+ * {@link finishHarnessExecution}): see {@link withHeadMovedRetry} and
+ * `core/head-retry.ts` for why a lost race is not a verdict, and why the retry
+ * is a new read plus new checks plus a new compare-and-append rather than a
+ * second attempt at the same write. {@link expire} is the one exception, and it
+ * needs none: it is materialisation the daemon's next tick performs again.
+ *
+ * It does not define execution tokens — `core/token.ts` does. {@link decide}'s
+ * grant path calls that module's `mintToken` at the seam APRV-17 documented,
+ * records only the digest in the `approval.granted` payload, and returns the raw
+ * token to its caller. {@link decide} still appends no `execution.*` event:
+ * spending a token is `core/token.ts`'s `consumeToken`.
+ *
+ * The one place this module writes an execution event is
+ * {@link consumeHarnessGrant} (APRV-117), and it is the exception that proves
+ * the rule: a harness grant mints no token, so nothing else in the system could
+ * record that it had been spent, and an authorization with no record of its
+ * spending is an authorization that never runs out. See that function for why
+ * the marker is `execution.started` and why no completion ever follows it.
+ */
+import { type AttestationRefusalDetail } from "./attest.js";
+import type { Reaction } from "./audit.js";
+import { type BudgetVerdict } from "./budgets.js";
+import { type IntakeVerdict } from "./intake-limits.js";
+import { type ClockOptions } from "./clock.js";
+import { type HarnessProvenance } from "./harness-version.js";
+import { type AppendError, type AppendOptions, type EventRecord, type LogHead } from "./log.js";
+import { type UsdInput } from "./money.js";
+import { type Autonomy, type PolicyLoadResult } from "./policy-load.js";
+import { type Resolution } from "./policy-match.js";
+import { type DrawAsker, type DrawRefusalReason, type LiveDrawRecord } from "./live-draw.js";
+import { LIVE_SELECTION, type LiveSelectorUnavailableReason } from "./sampler.js";
+import { type Decision, type RequestState, type WithdrawReason } from "./state.js";
+import { type ValidationError } from "./validate.js";
+/**
+ * The approval-state derivation moved to `core/state.ts` in APRV-20 (finding
+ * S4: `gate.ts` and `token.ts` imported each other). It is re-exported here, its
+ * documented home, so every existing importer — the CLI, the tests — is
+ * unaffected by the move.
+ */
+export { requestState, type Decision, type DeclaredAction, type ExecutionFacts, type RequestDerivation, type RequestState, WITHDRAW_REASONS, isWithdrawReason, type WithdrawReason, } from "./state.js";
+/** Actor stamped on runtime-originated expiry events (SPEC.md §8 `system:`). */
+export declare const EXPIRY_ACTOR = "system:gate";
+/**
+ * The closed set of gate refusal codes. Agents branch on these, so the union is
+ * frozen public API in the same sense the exit codes are: adding a code is a
+ * spec change, redefining one is a breaking change.
+ */
+export declare const GATE_REFUSAL_CODES: readonly [
+/** Policy is unattested or its bytes changed (`core/attest.ts`). */
+"policy-not-attested", 
+/**
+ * The policy attested now is not the policy the request was routed under
+ * (APRV-118, amended SPEC.md §5.2): the hash pinned on `approval.requested`
+ * differs from the hash in force at the moment of the grant.
+ *
+ * Distinct from `policy-not-attested`, and the distinction is the whole point.
+ * That code says the live file is unverified; this one says the file is
+ * perfectly verified and is a DIFFERENT file from the one that decided this
+ * action's autonomy, its limits, and its TTL. A human re-attested in between,
+ * so the routing that put the question in front of an approver was computed
+ * from rules nobody is enforcing any more, and a grant recorded here would
+ * claim a decision under rules the approver never saw. The pending request is
+ * void: nothing is appended, and the action is requested again so that it is
+ * routed, budgeted, and displayed under the policy actually in force.
+ */
+"policy-drift", 
+/** The envelope failed `envelope.schema.json`, or the task file has none. */
+"envelope-invalid", 
+/** The task file could not be read. */
+"task-file-unreadable", 
+/** This task id already has a `task.registered` record. */
+"task-already-registered", 
+/**
+ * The task has log history and the file no longer carries an envelope
+ * (APRV-63).
+ *
+ * Observed live in APRV-60: a third-party rewrite of a task file dropped the
+ * `approval:` key it did not recognize. Without this code the file reads as an
+ * ordinary envelope-less task, and a re-registration from a stripped file
+ * would narrow the record silently — declaring fewer actions, or none, for a
+ * task the log already says declared them. The loss is named instead, and the
+ * envelope is restored by a human from the log; nothing here repairs a file.
+ */
+"envelope-missing", 
+/** No `task.registered` record for this task id. */
+"not-registered", 
+/** The task is registered but declares no action with this key (SPEC.md §7). */
+"action-not-registered", 
+/** A live `approval.requested` for this action key already exists. */
+"duplicate-request", 
+/** The action key already has an `execution.*` record (idempotency). */
+"already-executed", 
+/**
+ * APRV-14 verdicts failed; a `budget.exceeded` event was appended. Covers
+ * class limits, `policy.budgets`, and — since S2 — the registered envelope's
+ * own `budget.max_cost_usd`, which appears as a `task`-scoped verdict in
+ * `verdicts` and in the appended event's payload.
+ */
+"budget-exceeded", 
+/**
+ * The approver's queue is at the ceiling the policy declared (SPEC.md §5.2's
+ * `limits.max_pending`, per class or on a `budgets` scope; APRV-173).
+ *
+ * A limit on ATTENTION rather than on money, which is why it is its own code
+ * and why it fires where it does: after the legality checks that say whether
+ * this request may exist at all, and before budgets, which are about the
+ * world's exposure rather than the human's. An agent that floods the queue
+ * with cheap in-budget requests spends nothing and still defeats the gate,
+ * because an approver facing two hundred prompts stops reading them and
+ * starts clearing them.
+ *
+ * Nothing is appended, deliberately, and this is the one refusal shaped
+ * differently from `budget-exceeded` on purpose (Carter's approved reading,
+ * 2026-08-31). A `budget.exceeded` record exists because a budget refusal is
+ * a fact about a commitment audit must be able to reconstruct; a record per
+ * refused flood request would hand the flooder the log growth it was refused
+ * the queue for. `error.limits` carries the failing verdicts, and the
+ * requests that WERE admitted are all in the log to count from.
+ *
+ * Transient in the sense that matters to a caller: the queue drains when a
+ * human decides, a requester withdraws, or a TTL lapses. Retrying at once
+ * gets the same answer.
+ */
+"queue-full", 
+/**
+ * This origin created more requests in the last hour than the policy's
+ * `limits.requests_per_hour` allows (SPEC.md §5.2, APRV-173).
+ *
+ * Distinct from `queue-full`, and the distinction is the repair. That code
+ * says the queue is full whoever is asking, so the caller waits for an
+ * approver; this one says the caller's own recent volume is the problem, so
+ * it slows down. Origin is the requesting actor at v0.1, which the runtime
+ * assigns rather than the caller (see `core/intake-limits.ts`), so a
+ * requester cannot re-label itself into a fresh hour.
+ *
+ * Counted over request CREATION, not over live requests: a request that was
+ * answered a minute after it was made still spent the origin's share of the
+ * hour. A ceiling that forgot each request as it was answered could be
+ * cleared by withdrawing every request as fast as it was made.
+ *
+ * Nothing is appended, for the same reason `queue-full` appends nothing.
+ */
+"rate-limited", 
+/**
+ * The action resolves to `manual` and its registered declaration carries no
+ * `payload_hash` (amended SPEC.md §6.2: MUST for `manual` actions).
+ *
+ * Enforced here rather than in `envelope.schema.json` because the schema
+ * cannot know an action's resolved autonomy — that answer depends on the
+ * policy, the irreversibility floor, and the class, none of which the
+ * envelope alone determines. A manual action with nothing to bind to would
+ * give a human a decision about bytes nobody committed to, so intake refuses
+ * and nothing is appended.
+ *
+ * Since APRV-146 the same code answers the same fact at the harness write
+ * boundary: {@link startHarnessExecution} refuses a start that names no
+ * payload hash, and {@link consumeHarnessGrant} refuses a spend that presents
+ * none (or a grant whose request recorded none). The fact is identical at both
+ * ends — a binding is required here and there is none — and the repair is the
+ * same shape: state the bytes, or request the action again so the record does.
+ * `payload-mismatch` stays the code for bytes that are stated and wrong.
+ */
+"payload-hash-required", 
+/**
+ * Payload material was supplied at intake and does not hash to the
+ * `payload_hash` the registration declared (APRV-28).
+ *
+ * The same code, and the same reason, as `core/token.ts`'s refusal at spend
+ * time: a grant approves specific bytes, so material that hashes to something
+ * else is not the payload this request is about. Refused before anything is
+ * stored and before anything is appended.
+ */
+"payload-mismatch", 
+/**
+ * The declared payload material could not be stored (APRV-28): it cannot be
+ * canonicalized, or the store directory could not be written.
+ *
+ * Fails closed rather than requesting anyway. A manual request whose bytes no
+ * channel can display is a request no human can answer — SPEC.md §10.4 —
+ * so intake refuses and the log is left untouched.
+ */
+"payload-store-failed", 
+/**
+ * A grant was attempted on a request whose payload carries no usable `class`.
+ *
+ * Its own code since APRV-20 pass two: the previous behavior substituted the
+ * empty string and granted anyway, which recorded an authorization that no
+ * class-scoped budget could ever charge and no policy rule could ever match.
+ * Fail closed and say which fact was missing.
+ */
+"grant-classless-request", 
+/**
+ * The action's class resolves to `human-only` (APRV-185, amended SPEC.md
+ * §5.2): the policy reserves it to human hands, and a person performs it
+ * outside agent execution entirely.
+ *
+ * Its own code, and distinct from every rejection, because nobody decided
+ * anything. A `reject` is a human's answer to a question that was legitimately
+ * asked; this is the policy answering that the question does not arise — there
+ * is no approval to seek, no approver to ask, and no grant that could be
+ * recorded. An agent that read a rejection would sensibly try again with a
+ * better summary; an agent that reads this must stop asking and hand the
+ * action to a person.
+ *
+ * Every verb of this module that could mint or withdraw authority returns it:
+ * {@link request}, {@link decide} in all three of its decisions, and
+ * {@link consumeHarnessGrant}. Grant is the obvious one. Reject and revoke are
+ * refused too, and the reason is stated plainly rather than assumed: those
+ * verbs WITHDRAW authority, and withdrawing authority that cannot exist would
+ * write a decision record about a human-only class into the log, which reads
+ * afterwards as a class the gate transacts in. A pending request that a policy
+ * amendment has since raised to `human-only` is not stranded by that: it
+ * authorizes nothing, no token can be minted for it and no run can spend it,
+ * and its requester withdraws it (`withdraw`) or its TTL lapses (`expire`).
+ * Neither of those verbs is refused here, deliberately — they are the exits
+ * from a question nobody may answer.
+ *
+ * Evaluated immediately after the check that establishes a request exists at
+ * all, and before every other check on the path, on all three verbs. A class
+ * that cannot be transacted in is answered before any question about who may
+ * decide it, under which policy hash, or against which budget.
+ */
+"class-human-only", 
+/**
+ * A `harness.launch.*` class that no rule of this policy names (APRV-354).
+ *
+ * The gate's half of the hook's `hook-harness-launch-unruled`, and it exists
+ * so there is no second door. The hook refuses a harness launch it classified
+ * from a command line; this refuses one a caller DECLARES, through
+ * `approval register` and `approval request`, which is the other way an
+ * action class reaches the gate.
+ *
+ * SPEC.md §7: the family resolves only under an explicit rule, never under
+ * `defaults.autonomy`. What a grant of it covers is the launch and nothing
+ * the launched session then does, so a class arriving by upgrade rather than
+ * by an operator's decision would be a capability nobody chose.
+ *
+ * Evaluated in the same position as `class-human-only` and immediately above
+ * it: both are the policy answering before any question about registration,
+ * budget or approver, and this one is the narrower statement of the two — not
+ * "reserved to human hands" but "not spoken about at all". Nothing is
+ * appended, so no `approval.requested` exists for a class no rule governs.
+ */
+"harness-launch-unruled", 
+/**
+ * Loop safety escalated the task to manual (SPEC.md §10.2, APRV-18): three
+ * consecutive `execution.failed` events. Only the non-manual paths are
+ * refused — see {@link request}.
+ */
+"loop-escalated", 
+/**
+ * A harness outcome was reported for an action key whose `execution.started`
+ * carries no `execution: "harness"` marker (APRV-145).
+ *
+ * The mirror image of `core/execute.ts`'s `execution-delegated`, and the pair
+ * is what keeps the two write surfaces from overlapping by one record. That
+ * code refuses a HUMAN recovery verb over a harness start; this one refuses a
+ * HARNESS report over a start this runtime is watching itself. An untrusted
+ * report that could close an `approval run` execution would be reporting an
+ * exit code the runtime was about to observe for itself, and the outcome the
+ * log kept would be whichever one landed first.
+ */
+"not-delegated", 
+/**
+ * Every harness-marked start the reported tool call opened already carries an
+ * outcome (APRV-145). An execution has exactly one, and a second report would
+ * be a second answer about one command — including a `completed` written over
+ * a `failed`, which is a streak cleared by repetition rather than by recovery.
+ *
+ * Named for the fact rather than for the reporter, and spelled exactly as
+ * `core/execute.ts` spells the same fact, so a reader who has met one has met
+ * both.
+ */
+"already-finished", 
+/** No request to decide. */
+"not-requested", 
+/** The request already has a terminal decision. */
+"already-decided", 
+/** Revoke was attempted on a request that is not granted. */
+"not-granted", 
+/**
+ * A decision was attempted on a request the requester had already withdrawn
+ * (APRV-106, amended SPEC.md §6.3).
+ *
+ * Distinct from `already-decided` because the facts and the repairs are
+ * distinct. `already-decided` says a human answered and the answer stands;
+ * this one says nobody answered and nobody can — the party that asked has
+ * stopped listening, so a grant here would authorize an action no process is
+ * waiting to perform. The repair is to request the action again, which is a
+ * new request with a new decision, not to try the decision a second time.
+ */
+"request-withdrawn", 
+/**
+ * A withdrawal was attempted by an actor other than the one that appended the
+ * matching `approval.requested` (APRV-106).
+ *
+ * Withdrawal is the requester's own retraction, and nothing more. If any
+ * actor could withdraw, then any actor could clear an approver's queue — the
+ * queue would become deniable by whoever reached the log first, which is the
+ * one property the gate exists to deny. A human who wants a pending request
+ * gone rejects it, on the record, as themselves.
+ */
+"not-requester", 
+/** The TTL lapsed — judged from the request's own ts, event or no event. */
+"expired", 
+/** `expire` was called on a request whose TTL has not lapsed. */
+"not-expired", 
+/** The actor is not a well-formed `human:`/`agent:` identity. */
+"actor-invalid", 
+/** A human-only verb was attempted by a non-human actor. */
+"actor-not-human", 
+/**
+ * A grant was recorded by a person the resolved rule's `approvers` list does
+ * not name (APRV-137, amended SPEC.md §5.2).
+ *
+ * Distinct from `actor-not-human`, and the distinction is the repair. That
+ * code says the actor is not a person at all, and the fix is to run the verb
+ * as one. This one says the actor IS a person and is not one the policy
+ * named for this class, so the fix is to ask a named approver. Before this
+ * code the list was parsed, surfaced by `policy explain`, and enforced
+ * nowhere: a policy writing `approvers: [alice]` on `financial.spend` bound
+ * nothing while its author believed it bound the class.
+ *
+ * Scope, and its limits. The check is defense in depth inside the trust
+ * boundary §11 states plainly: human identity in v0.1 is config-declared, so
+ * anyone who can set that configuration can present any name on this list.
+ * What it defends is the honest mistake and the wrong-approver routing, not
+ * an actor choosing whose name to wear. The check binds `grant` alone;
+ * reject and revoke withdraw authority rather than confer it, and
+ * restricting them would leave a request standing, or an authorization live,
+ * because the wrong person tried to end it.
+ */
+"actor-not-approver", 
+/** The log could not be read, or holds a line that is not a record. */
+"log-unreadable", 
+/** The log's final line is unterminated (a crashed write). */
+"log-torn-tail", 
+/**
+ * The chain does not verify (APRV-20 finding S1). Distinct from
+ * `log-unreadable`, which is a filesystem fact: this one says the log's own
+ * contents contradict each other, so nothing may be authorized from it.
+ */
+"log-corrupt", 
+/**
+ * The rendered semantic diff of a proposed policy is larger than a channel
+ * prompt can show whole (APRV-109, amended SPEC.md §10.3).
+ *
+ * A refusal rather than a truncation, and its own code so a caller can tell
+ * "this amendment is too big for a phone" from every other reason a proposal
+ * fails. A prompt that showed two thirds of a policy change would collect a
+ * signature for the third it did not show; the repair is to read the diff at
+ * a terminal and attest there, which the message names.
+ */
+"diff-too-large", 
+/** No `policy.proposed` record at the named seq (APRV-109). */
+"proposal-not-found", 
+/**
+ * The policy bytes changed after the attestation prompt was rendered
+ * (APRV-109).
+ *
+ * Distinct from `policy-drift`, which is about a pending approval routed
+ * under superseded rules. This one says the human is looking at a hash the
+ * file no longer has, so attesting would name bytes the approver was never
+ * shown. Nothing is appended and the amendment is proposed again.
+ */
+"proposal-stale", 
+/**
+ * An attestation was proposed for a policy file that already matches its
+ * attestation (APRV-109). There is no amendment to sign, and a prompt for one
+ * would ask a human to re-attest bytes already in force.
+ */
+"policy-already-attested", 
+/**
+ * A grant carrying `reaction: loved` or `reaction: disliked` and no non-blank
+ * note (APRV-239, amended SPEC.md §5.2).
+ *
+ * Grant only. Evaluated with the other checks that read nothing, and nothing
+ * is appended. `reject` and `revoke` accept no reaction at all, which is a
+ * usage error at the verb rather than a member of this union: their reason IS
+ * their note, and there is no second field for a grade to sit in.
+ *
+ * Its own code rather than the audit path's `note-required` because a caller
+ * branching on a gate refusal is branching on this union, and the two verbs
+ * are answered by two different modules. The message names `--note`, which is
+ * the whole of the fix.
+ */
+"reaction-note-required", 
+/**
+ * The append itself failed; `append` carries the underlying error. Its
+ * `code` is `head-moved` when the log grew between this module's read and its
+ * append: every check that authorized the write was made against an older log,
+ * so nothing was written. Since APRV-236 this code reaches a caller only after
+ * the bounded read-check-append retry is spent (`core/head-retry.ts`), and its
+ * message says how many attempts were made. A single lost race is no longer
+ * reported at all: it is re-derived, and the answer the fresh log supports is
+ * what the caller receives.
+ */
+"append-failed", 
+/**
+ * A `delivery: "self"` request could not publish a delivery address (APRV-211):
+ * the ephemeral private key could not be written beside the log.
+ *
+ * Fail closed, and unlike APRV-105's ordinary sealed path, which drops the
+ * convenience and leaves the paste path standing. There is no paste path
+ * here — the requester is a process, not a terminal — so a request admitted
+ * without an address would spend a human's decision on an authorization
+ * nothing can ever open. Nothing is appended; the next attempt asks again.
+ */
+"token-delivery-unavailable"];
+export type GateRefusalCode = (typeof GATE_REFUSAL_CODES)[number];
+/** Every gate failure is one of these. Nothing here throws. */
+export interface GateRefusal {
+    ok: false;
+    code: GateRefusalCode;
+    message: string;
+    /** Attestation discriminator, when `code` is `policy-not-attested`. */
+    detail?: AttestationRefusalDetail;
+    /** The derived state at refusal time, for transition refusals. */
+    state?: RequestState;
+    /** The failing verdicts, when `code` is `budget-exceeded`. */
+    verdicts?: BudgetVerdict[];
+    /**
+     * The failing request-volume verdicts, when `code` is `queue-full` or
+     * `rate-limited` (APRV-173). Separate from `verdicts` because they are a
+     * different measurement with a different shape, and because a caller that
+     * branched on `verdicts` to read money out of a budget refusal must not find
+     * queue counts there.
+     */
+    limits?: IntakeVerdict[];
+    /** Schema errors, when `code` is `envelope-invalid`. */
+    errors?: ValidationError[];
+    /** The underlying append error, when `code` is `append-failed`. */
+    append?: AppendError;
+    /**
+     * The two policy hashes actually compared, when `code` is `policy-drift`
+     * (APRV-235): the hash the request (or the grant) pinned, and the hash
+     * attested at the moment of the refusal.
+     *
+     * Carried on the refusal so that whatever RECORDS the refusal records the
+     * comparison that was made. Re-deriving the pair afterwards would be a second
+     * comparison, at a second instant, against a file that may have moved again,
+     * and a record describing a comparison nobody performed is worse than no
+     * record at all. `core/decision-refusal.ts` copies these verbatim.
+     */
+    drift?: {
+        requested: string;
+        attested: string;
+    };
+    /**
+     * An event appended *alongside* the refusal: the `budget.exceeded` record, or
+     * the lazily-materialised `approval.expired` record. Never an authorization.
+     */
+    record?: EventRecord;
+}
+/**
+ * Options shared by every gate operation.
+ *
+ * Note what is **not** here and no longer a parameter anywhere in this module:
+ * `ts`. Under amended SPEC.md §8 a gate-typed event's timestamp is assigned by
+ * the runtime at the write boundary, so it is read from {@link ClockOptions
+ * clock} (defaulting to the real clock) rather than accepted from the caller.
+ * The refusal the spec asks for is structural: there is no parameter to pass.
+ */
+export interface GateOptions extends ClockOptions {
+    /** Schema directory, passed to both envelope validation and the append. */
+    schemaDir?: string;
+    /**
+     * Where to find `APPROVAL.md`. `dir`/`file` have the same semantics as
+     * `loadPolicy`.
+     *
+     * `read` is the one read seam a gate operation uses to fetch the policy bytes
+     * (APRV-142), defaulting to `readFileSync`. It exists so a test can simulate
+     * a file swapped mid-operation and prove the swap cannot land: the seam is
+     * called exactly once per gate operation, so a reader that returns different
+     * bytes on its second call has no second call to return them to. It is not a
+     * widening of anything — a caller holding `GateOptions` can already name any
+     * file through `file`.
+     */
+    policy?: {
+        dir?: string;
+        file?: string;
+        read?: (path: string) => Uint8Array;
+    };
+    /** Lock tuning for the append path. */
+    append?: AppendOptions;
+    /**
+     * How many times a writer of this module re-derives its verdict after a
+     * `head-moved` refusal, at most `head-retry.ts`'s `HEAD_MOVED_ATTEMPTS`
+     * (APRV-150, APRV-236, {@link withHeadMovedRetry}).
+     *
+     * Only ever lowers the bound. `1` is the pre-APRV-150 behaviour — one read,
+     * one set of checks, one append, and a lost race is reported as a refusal —
+     * which is what a test pins the old shape with. A larger number, a zero or a
+     * fraction is ignored in favour of the runtime's own value: the ceiling is not
+     * a caller's to raise.
+     */
+    retryOnHeadMoved?: number;
+    /**
+     * Where payload material is stored (APRV-28). Defaults to the convention
+     * `core/payload-store.ts` defines: `.approval/payloads/`, beside the log.
+     */
+    payloadStoreDir?: string;
+    /**
+     * Where per-request private keys live (APRV-105). Defaults to the convention
+     * `core/seal.ts` defines: `.approval/keys/`, beside the log. Under the default
+     * `token_delivery: manual` nothing here is ever written or read.
+     */
+    keyStoreDir?: string;
+    /**
+     * The environment the operator's sampling secret is read from (APRV-127).
+     * Injected by tests; defaults to `process.env`. The secret is never read from
+     * the policy file or from anywhere else inside the repository.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * How a process with no sampling secret asks the daemon for a live draw
+     * (APRV-208). Defaults to `core/live-draw.ts`'s `askDaemonDraw`, which
+     * `spawnSync`s a relay against the owner-only socket under the approval home.
+     *
+     * A seam for tests, and stated plainly rather than defended: an in-process
+     * caller that supplies a lying asker can wave a live action through, and so
+     * can one that points `policy.file` at a policy of its own. Both are the same
+     * trust boundary, which is the process holding `GateOptions` — SPEC.md §11's
+     * "the trust boundary is the local machine". The property this seam does NOT
+     * weaken is the one that matters across processes: a HOOK never sets it, the
+     * default asker talks only to the socket under the approval home, and the
+     * verdict it brings back is recorded with the MAC an operator recomputes.
+     */
+    drawAsk?: DrawAsker;
+}
+type ReadOutcome = {
+    ok: true;
+    records: EventRecord[];
+    head: LogHead | null;
+} | GateRefusal;
+/**
+ * Read the log's records, refusing unless the whole chain verifies.
+ *
+ * Delegates to `core/state.ts`'s {@link readVerifiedRecords}: since APRV-20
+ * (finding S1) the gate does not merely parse the log, it verifies it. A
+ * corrupt log refuses `log-corrupt` and authorizes nothing; a torn tail refuses
+ * `log-torn-tail`, unchanged, because the repair is a human decision and never a
+ * gate's; an unopenable file refuses `log-unreadable`, an I/O fact rather than an
+ * accusation.
+ *
+ * The returned `head` is what every append site here passes as `expectedHead`,
+ * so a decision derived from these records cannot land on a log that moved
+ * underneath it.
+ */
+export declare function readGateRecords(logPath: string, schemaDir?: string): ReadOutcome;
+/**
+ * The policy as a gate operation would load it: one read through the seam of
+ * {@link GateOptions.policy}, parsed, failing closed (APRV-324).
+ *
+ * Exported for one caller, `channels/contract.ts`, which resolves an
+ * authenticated sender to an approver identity BEFORE it calls {@link decide}
+ * and must do so against the same file, discovered the same way, through the
+ * same injectable reader. Writing a second `loadPolicy` call there would have
+ * been a second discovery path that could find a different file.
+ *
+ * It is still a SECOND read of the bytes, one operation earlier, and that is
+ * deliberate rather than overlooked: `decide` reads once per attempt on purpose
+ * (see {@link PolicyRead}), and pinning bytes across its bounded retry would
+ * make a re-attestation inside the retry window invisible to the drift check.
+ * What closes the gap is the check itself — a policy that changes between the
+ * two reads is either unattested or a different hash from the one the request
+ * pinned, and `decide` refuses `policy-not-attested` or `policy-drift` rather
+ * than authorizing under bytes the resolution never saw.
+ */
+export declare function readGatePolicy(options: GateOptions): PolicyLoadResult;
+/** One declared action of an envelope (SPEC.md §6.2 `actions[]`). */
+export interface RegisteredAction {
+    class: string;
+    idempotency_key: string;
+    summary?: string;
+    reversible?: boolean;
+    /** Canonical decimal USD string (APRV-121); see `core/money.ts`. */
+    est_cost_usd?: string;
+    /**
+     * The content binding of amended SPEC.md §6.2. MUST be present for an action
+     * that resolves to `manual`; the enforcement point is {@link request}, not
+     * registration, because autonomy is not known until policy is consulted and
+     * refusing at registration would make an envelope unregisterable for a
+     * property of a policy file it never mentions.
+     */
+    payload_hash?: string;
+}
+/**
+ * What to register: a task file to read, or an already-in-hand envelope.
+ *
+ * The task **id** is not part of the envelope — `envelope.schema.json` governs
+ * the value of the `approval:` key only, and `id:` is a sibling board key owned
+ * by Backlog.md (SPEC.md §6). So the file form reads it from the frontmatter's
+ * `id`, and the in-memory form takes it explicitly.
+ */
+export type RegisterSource = {
+    file: string;
+} | {
+    task: string;
+    envelope: unknown;
+};
+export type RegisterResult = {
+    ok: true;
+    record: EventRecord;
+    task: string;
+    actions: RegisteredAction[];
+} | GateRefusal;
+/**
+ * Validate an envelope and append `task.registered`.
+ *
+ * Fail closed: the envelope is validated against `envelope.schema.json` **before
+ * anything is read from it and before any byte is written**. A schema-invalid
+ * envelope leaves the log untouched.
+ *
+ * Double registration is refused. Re-registering a task id would give the same
+ * id two different declared action sets in one log, and every later lookup
+ * ("what class is this key?") would have to pick one — silently. Envelope
+ * *changes* are `envelope.drift` (SPEC.md §6.3, M5), not a second registration.
+ *
+ * `actor` is a `human:` or `agent:` identity; registration is an ordinary
+ * proposal, not a privileged act, so an agent may perform it. `system:` is
+ * refused: the runtime does not author tasks.
+ *
+ * The registration payload carries the envelope's `actions` and — since S2 —
+ * its `budget` block, so the task's own `max_cost_usd` cap is enforced from the
+ * log rather than from a task file that may be edited afterwards.
+ */
+export declare function register(logPath: string, source: RegisterSource, actor: string, options?: RegisterOptions): RegisterResult;
+/**
+ * {@link register}'s options, plus the one field only a harness hook passes.
+ *
+ * `harness` is APRV-227's provenance pair, and where it comes from is the whole
+ * of its safety. It is a CALL option: the hook process derives it from its own
+ * event and its own PATH and hands it in. It is NOT read from the envelope, the
+ * task file, or anything else on disk — an envelope field would be a value an
+ * agent authors about the binary that is supposed to be watching it, and a task
+ * file is a file an agent edits. Copied into the payload verbatim when present
+ * and omitted entirely when absent; nothing downstream reads it back (SPEC.md
+ * §11.1 invariant 4 — see `core/harness-version.ts`).
+ */
+export interface RegisterOptions extends GateOptions {
+    harness?: HarnessProvenance;
+}
+/**
+ * The declared action for `(task, actionKey)`, as registered in the log.
+ *
+ * SPEC.md §7: "an action's class MUST be declared before an execution token can
+ * be requested for it". The declaration lives in `task.registered`, so the log —
+ * not the file, which may have been edited since — is what the gate reads back.
+ */
+export declare function registeredAction(records: EventRecord[], task: string, actionKey: string): {
+    ok: true;
+    action: RegisteredAction;
+} | GateRefusal;
+/** The action being submitted to the gate. */
+export interface RequestInput {
+    task: string;
+    actionKey: string;
+    /** The dotted side-effect class (SPEC.md §7). */
+    cls: string;
+    /** Canonical decimal USD string (APRV-121); a JSON number is read as the historical form. */
+    est_cost_usd?: UsdInput;
+    reversible?: boolean;
+    summary?: string;
+    /**
+     * The content binding (amended SPEC.md §6.2). A fallback only: {@link request}
+     * prefers the value on the `task.registered` record, because the log is what
+     * the human's policy was attested against and a caller-supplied hash could
+     * name bytes the registration never declared.
+     */
+    payload_hash?: string;
+    /**
+     * The concrete payload material, to be filed in the payload store (APRV-28).
+     *
+     * Wrapped in an object so that "supplied, and the material happens to be
+     * `undefined`" is distinguishable from "not supplied at all" — the first is a
+     * payload that cannot be bound to and is refused, the second is the ordinary
+     * case of a caller that stored the bytes some other way (or holds none).
+     *
+     * Its hash MUST equal the declared `payload_hash`; a difference refuses
+     * `payload-mismatch` and stores nothing. Material supplied for an action that
+     * resolves to `supervised` or `autonomous` is ignored: that path records no
+     * request, so there is no binding a stored payload could belong to.
+     */
+    payload?: {
+        value: unknown;
+    };
+    /**
+     * `"harness"` when this request will never be executed through
+     * `approval run` (APRV-106).
+     *
+     * The Claude Code hook is the case it exists for: the hook asks the gate a
+     * permission question and the *harness* runs the command, so a grant here has
+     * nothing to hand a token to. Recorded on `approval.requested` and copied by
+     * {@link decide} onto the grant, where it suppresses the mint. See
+     * `DeclaredAction.execution` in `core/state.ts` for why a false claim can
+     * only remove the claimant's own capability.
+     */
+    execution?: "harness";
+    /**
+     * ISO-8601 instant after which the requester stops waiting (APRV-106).
+     *
+     * Recorded for CHANNELS TO DISPLAY and for nothing else: an approver seeing
+     * "requester waits until 09:23 UTC" knows that an answer at 09:40 reaches
+     * nobody. It bounds no TTL, charges no budget, and gates nothing — the
+     * policy's `defaults.approval_ttl` remains the only deadline with authority.
+     */
+    wait_until?: string;
+    /**
+     * The caller has established that loop safety floors this action to `manual`
+     * for this invocation (APRV-145, amended SPEC.md §10.2).
+     *
+     * The THIRD way into the manual path, beside a class that resolves manual and
+     * an action the APRV-127 live draw selected, and it works exactly as that
+     * second one does: the non-manual branch is skipped and everything below it
+     * runs unchanged, so nothing in the manual path knows or asks how the action
+     * got here. The flag is a fact the caller computed from the log
+     * (`core/loop.ts`'s `harnessLoopFloor`) and it can only ever ADD scrutiny: a
+     * caller that sets it wrongly asks a human about a command that did not need
+     * one, and a caller that omits it is refused at the write boundary by
+     * {@link startHarnessExecution}, which re-checks the same streaks.
+     */
+    loopFloor?: boolean;
+    /**
+     * `"self"` when the requesting process will consume its own grant, in its own
+     * process, and no other principal needs the raw token (APRV-211).
+     *
+     * The daemon's cadence advance is the case it exists for. The daemon is the
+     * requester AND the executor: it asks the gate, a human answers on the phone,
+     * and the same process spends the answer through {@link startExecution}'s
+     * APRV-105 sealed path. Before this field, the grant handed its raw token back
+     * to the GRANTING surface — the Telegram listener's terminal — which printed
+     * it under "single-use · stored nowhere · copy it now", the APRV-166 relay
+     * path meant for a requester in another process. Nobody was ever going to
+     * carry that value anywhere; it was a live credential rendered for a principal
+     * that was not the requester, which SPEC.md §11.1's raw-secrets invariant
+     * exists to prevent.
+     *
+     * So it does two things and nothing else. {@link request} mints the sealed
+     * delivery address for this action REGARDLESS of `defaults.token_delivery`,
+     * because there is no terminal on the other end of the paste path and a
+     * request with no address would be an authorization nobody could open; and
+     * {@link decide} withholds the raw token from its own return value, so no
+     * granting surface has one to print. The token still exists, still binds to
+     * the payload bytes, is still single-use, and is still minted only by a
+     * human's grant. Nothing here reduces scrutiny: it removes a reader, not a
+     * check.
+     *
+     * Refused when the key cannot be written (`token-delivery-unavailable`), which
+     * is the fail-closed direction: a self-delivered grant nobody can open would
+     * spend a human's decision on an authorization that can never execute.
+     */
+    delivery?: "self";
+}
+/**
+ * Why a `supervised-live` action was, or was not, sent to the human gate
+ * (amended SPEC.md §5.2/§6.3, APRV-127).
+ *
+ * Returned to the caller and **never written to the log**. See
+ * {@link liveVerdict} for why the log carries no trace of the selection.
+ */
+export interface LiveVerdict {
+    /** The class's declared `live_rate`, as `policy-match.ts` resolved it. */
+    rate: number;
+    /** True when this action must stop for a human before it may execute. */
+    gated: boolean;
+    /**
+     * Machine-readable and closed, because a supervisor branches on it:
+     *
+     * - `selected` — the HMAC fell under the rate. This is the fraction working.
+     * - `not-selected` — it did not. The action proceeds, and still enters the
+     *   retrospective pool.
+     * - `payload-hash-absent` — the registration declared no `payload_hash`, so
+     *   there is nothing to select over. Gated: an action whose bytes nobody
+     *   named cannot be shown to have been fairly sampled, and the manual path
+     *   refuses it by name a moment later.
+     * - the three {@link LiveSelectorUnavailableReason}s — no usable secret.
+     *   Gated. See `core/sampler.ts` on why live selection fails closed where
+     *   retrospective sampling fails open.
+     */
+    reason: "selected" | "not-selected" | "payload-hash-absent" | LiveSelectorUnavailableReason | DrawRefusalReason;
+    /** The algorithm an operator holding the secret recomputes to check this. */
+    selection: typeof LIVE_SELECTION;
+    /** The NAME of the secret's environment variable. Never the secret. */
+    secretEnv: string | null;
+    /**
+     * The delegation, when this verdict was not computed in this process
+     * (APRV-208). Absent for an in-process draw, which is why a sampled
+     * supervised-live request in an operator's own terminal is still byte-for-byte
+     * a manual one. See {@link LiveDrawRecord} for why a DELEGATED verdict is
+     * recorded and an in-process one is not.
+     */
+    draw?: LiveDrawRecord;
+}
+export type RequestResult = {
+    ok: true;
+    autonomy: Autonomy;
+    /** True when execution may start now: the supervised/autonomous path. */
+    proceed: boolean;
+    resolution: Resolution;
+    /** The `approval.requested` record, or `null` off the manual path. */
+    record: EventRecord | null;
+    /** Digest of the attested policy bytes that produced this intake verdict. */
+    policySha256: string;
+    /**
+     * The live-selection verdict, for a `supervised-live` class only
+     * (APRV-127). Absent for every other class: there was no fraction to fall
+     * inside or outside of.
+     */
+    live?: LiveVerdict;
+} | GateRefusal;
+/**
+ * Gate intake.
+ *
+ * Check order, and why it is this order:
+ *
+ * 1. **Actor.** A malformed identity is a bad call, not a policy question.
+ * 2. **Attestation.** An unverified policy cannot answer anything, so it is
+ *    checked before the policy is consulted rather than after.
+ * 3. **Policy resolution** (`loadPolicy` + `resolve`, including the §7
+ *    irreversibility floor). A failed load resolves everything to `manual` —
+ *    that is `policy-match.ts`'s contract, and this module does not soften it.
+ * 3b. **Declaration** (SPEC.md §7, APRV-147), for a `manual` resolution and for
+ *    a `supervised-live` one. The log must carry a `task.registered` for the
+ *    task and an action with this idempotency key, or the request is refused
+ *    `not-registered` / `action-not-registered` and nothing is appended. Before
+ *    the live draw and before the binding below, so an undeclared action never
+ *    reaches a human's queue, never has the live fraction drawn over a hash it
+ *    chose for itself, and hears the real reason rather than
+ *    `payload-hash-required`.
+ * 4. **Off the manual path, retain supplied bound material, then stop — unless
+ *    the live fraction says otherwise.** `supervised`/`autonomous` append **no
+ *    event** (amended SPEC.md §6.3) and return `proceed: true`. When the caller
+ *    supplies payload material, it is checked against the registered declaration
+ *    and retained for the later execution evidence. Their budget is charged at `execution.started`,
+ *    which APRV-18 appends — checking budgets here as well would charge them
+ *    twice or, worse, pass here and fail there. A `supervised-live` class
+ *    (APRV-127) draws its declared fraction here: an action the draw selects
+ *    falls through into everything below and is treated as `manual` from this
+ *    line on, and an action it does not proceeds exactly as before.
+ * 5. **Content binding** (amended SPEC.md §6.2, A1). A manual action whose
+ *    registered declaration carries no `payload_hash` is refused
+ *    `payload-hash-required` and nothing is appended. This is the first check
+ *    after the manual path is known, because a request with nothing to bind to
+ *    should never reach a human's queue at all.
+ * 5b. **Payload material**, when the caller supplied any (APRV-28). Its hash is
+ *    checked against the declaration here — before legality, before budgets,
+ *    before any file — and the bytes are written to the payload store in the
+ *    step immediately before the append, so a refused request stores nothing.
+ *    See the two comments in the body for the ordering and the one orphan it
+ *    permits.
+ * 6. **Request legality**, then **budgets**, then the append. Legality first
+ *    because a duplicate request is a caller bug that no budget outcome should
+ *    obscure, and because refusing it must leave the log untouched.
+ *
+ * The `approval.requested` payload carries `class`, `est_cost_usd`, and (on the
+ * manual path, always) `payload_hash` — the budgets contract requires the first
+ * two on the grant and the token binding requires the third, and the grant
+ * copies all of them from here rather than re-deriving them from a file that
+ * may have changed.
+ */
+export declare function request(logPath: string, input: RequestInput, actor: string, options?: GateOptions): RequestResult;
+export interface DecideOptions extends GateOptions {
+    /** Free-text note recorded in the event payload (SPEC.md §8's example). */
+    note?: string;
+    /**
+     * The channel delivery id of the batch this decision answered (amended
+     * SPEC.md §10.3, APRV-38), recorded as `payload.batch_delivery_id` on
+     * `approval.granted` / `approval.rejected`.
+     *
+     * The log never batches: one gesture over five requests is five events, and
+     * this is the only thing tying them back together for audit. It is recorded
+     * on grant and reject alone, the two decisions a channel can collect;
+     * `revoke` is a considered act performed against the log through the CLI and
+     * never arrives as part of a batch gesture, so a value supplied with it is
+     * ignored rather than written.
+     *
+     * Empty strings are ignored for the same reason the schema requires
+     * `minLength: 1`: a batch id that identifies no batch is worse than none,
+     * since audit would read it as a grouping that never existed.
+     */
+    batchDeliveryId?: string;
+    /**
+     * The graded reaction the approver gave, on `grant` only (APRV-239, amended
+     * SPEC.md §5.2), recorded as `payload.reaction` on `approval.granted`.
+     *
+     * A human answering the gate is already saying what they think of the action;
+     * this is where they can say it in one word rather than in prose nothing can
+     * read back. It is GUIDANCE and never enforcement: the grant record itself is
+     * the authorization, and no routing, matching, sampling, budget, token or
+     * execution decision reads this field (SPEC.md §11.1 invariant 10). It cannot
+     * widen or narrow what the grant authorizes, and a `disliked` grant is exactly
+     * as much of a grant as a `loved` one.
+     *
+     * Ignored on `reject` and `revoke` — the CLI refuses the flag outright there,
+     * as a usage error naming `--note` — because their reason is their note and a
+     * grade beside a refusal is a second answer to a question with one.
+     */
+    reaction?: Reaction;
+    /**
+     * The surface that collected the decision (amended SPEC.md §8, APRV-324),
+     * recorded as the record's top-level `channel`.
+     *
+     * The base event schema has defined the field since v0.1 and the decision
+     * events never set it, so a reader of a grant could not tell a tap on a phone
+     * from a line typed into a terminal. Set by the decision surface, from its own
+     * name, exactly as `audit.decision_refused` has always set it.
+     */
+    channel?: string;
+    /**
+     * The authenticated sender the `actor` was resolved from (amended SPEC.md
+     * §6.3, APRV-324), recorded as `payload.sender`.
+     *
+     * ABSENT is meaningful and is the common case: it says the attribution came
+     * from the surface's configuration rather than from anything the transport
+     * authenticated, which is how every decision before this key existed was
+     * made. Present, it is the transport's own attribution — never a name, handle
+     * or id a message claimed about itself (§11.1 invariant 4).
+     *
+     * This is a RECORD of how the actor was chosen, and it is not the choosing:
+     * `channels/contract.ts` resolves the sender against the attested policy
+     * before calling this verb, and no check here reads this field. There is no
+     * CLI flag that supplies it, so no agent-reachable surface mints one.
+     *
+     * `hashed` (APRV-370) says the `id` is the operator's keyed digest of the
+     * account rather than the account, which is what a policy mapping senders in
+     * the keyed form records. Present-and-`true` or absent, never `false`: a raw
+     * record is the record this runtime already wrote, and it is written
+     * unchanged.
+     */
+    sender?: {
+        channel: string;
+        id: string;
+        hashed?: true;
+    };
+    /**
+     * How {@link DecideOptions.sender} became the actor (APRV-324), recorded as
+     * `payload.sender_source`. `policy` is the attested `approvers[id].senders`
+     * mapping, and it is the only member today — a closed vocabulary so a future
+     * source (a signed receipt, APRV-249) is distinguishable in a log rather than
+     * silently mixed in with policy-attested ones.
+     */
+    senderSource?: "policy";
+}
+export type DecideResult = {
+    ok: true;
+    decision: Decision;
+    state: RequestState;
+    record: EventRecord;
+    /**
+     * The raw single-use execution token, on `grant` only (APRV-17). Returned
+     * here and nowhere else: the log carries only its SHA-256, so this value
+     * is unrecoverable once the caller drops it.
+     *
+     * Absent — on a grant that DID mint one — when the request declared
+     * self-delivery and the token was sealed to its address (APRV-211). The
+     * authorization is complete; the granting surface simply has no copy to
+     * print, because the requester is a process that opens the seal itself.
+     * See {@link RequestInput.delivery}.
+     */
+    token?: string;
+} | GateRefusal;
+/**
+ * Record a human decision on a request.
+ *
+ * **Human-only**, enforced here in code and again by the event schema for
+ * grant/reject. `revoke` is human-only too: withdrawing an authorization is a
+ * decision about an authorization, and an agent that could revoke could also
+ * churn the queue.
+ *
+ * Attestation is required **for `grant` only**. Grant is the authorizing
+ * decision, so an unverified policy must not be able to produce one. Reject and
+ * revoke *withdraw* authority, and refusing them on an unattested policy would
+ * leave a live grant standing because a file changed — the strict direction and
+ * the safe direction point the same way, and it is not "refuse everything".
+ *
+ * Attestation also answers a question it could not answer before APRV-118:
+ * *which* policy. The hash the live file matched is compared against the hash
+ * `approval.requested` pinned, and a difference refuses `policy-drift` with
+ * nothing appended. Attestation alone catches an unattested edit; this catches
+ * an attested one, which is the case where every check still passes and the
+ * rules have nonetheless changed underneath a pending question. The hash in
+ * force is then recorded on the grant, so the log states the rules the approver
+ * decided under rather than leaving a reader to assume they were the
+ * requester's.
+ *
+ * Budgets are re-evaluated at grant time. A request may have sat in the queue
+ * while other actions consumed the window, and the moment that matters for a
+ * commitment is the moment the human commits.
+ *
+ * On `grant` a single-use execution token is minted (`core/token.ts`) and its
+ * SHA-256 recorded in the payload as `token_sha256`, **alongside the request's
+ * `payload_hash`** (amended SPEC.md §10, A1). The token is therefore bound to
+ * three things — the request, its `idempotency_key`, and the bytes — and
+ * `core/token.ts` refuses `payload-mismatch` for anything else. The raw token
+ * is returned in `token` and is written nowhere: whoever calls this is the only
+ * party that will ever hold it, and a lost token is unrecoverable by design —
+ * revoke and request again.
+ */
+export declare function decide(logPath: string, actionKey: string, decision: Decision, actor: string, options?: DecideOptions): DecideResult;
+export interface WithdrawOptions extends GateOptions {
+    /** Why the requester is retracting. Defaults to `cancelled`. */
+    reason?: WithdrawReason;
+    /** The requester's free-text elaboration, recorded in the payload. */
+    note?: string;
+}
+export type WithdrawResult = {
+    ok: true;
+    state: RequestState;
+    record: EventRecord;
+} | GateRefusal;
+/**
+ * Retract a pending request, as the party that opened it (amended SPEC.md §6.3,
+ * APRV-106).
+ *
+ * ## Why the verb exists
+ *
+ * Observed live on 2026-08-19. A builder's `git commit --amend` went through the
+ * Claude Code hook, which classified it manual and appended
+ * `approval.requested`. The hook waited nine minutes, got nothing, denied the
+ * tool call and moved on — but the request stayed pending for the policy's 24h
+ * TTL. Half an hour later the human was pinged on their phone and approved it,
+ * and the grant authorized nothing at all: the hook had long since answered,
+ * and a retried tool call is a new request with a new key. A person spent
+ * attention on a question whose asker had left. SPEC.md §11 makes human
+ * attention the audit budget, and a decision nobody can consume must not be
+ * solicited; so the asker takes the question back.
+ *
+ * ## The four rules
+ *
+ * 1. **Requester-only.** The actor MUST equal the actor of the
+ *    `approval.requested` that opened the current cycle, else `not-requester`.
+ *    Anything looser would make the approver's queue clearable by whoever
+ *    reached the log first. A human who wants a pending request gone rejects
+ *    it, on the record, as themselves.
+ * 2. **Pending-only.** `not-requested` when there is nothing to withdraw,
+ *    `already-decided` when a human has answered, `request-withdrawn` for a
+ *    second withdrawal, `expired` when the TTL has lapsed — and expiry is
+ *    judged here exactly as {@link decide} judges it, from the request's own
+ *    timestamp, with the same lazy materialisation of the `approval.expired`
+ *    record. A lapse is a lapse whether or not an event says so, and a
+ *    withdrawal that pretended otherwise would rewrite the reason a request
+ *    ended.
+ * 3. **No attestation, no budget.** Withdrawal removes a question; it authorizes
+ *    nothing and commits nothing. Refusing it on an unattested policy would
+ *    leave requests standing in a human's queue because a file changed, which
+ *    is the strict direction pointing the wrong way.
+ * 4. **Compare-and-append, like everything else here.** The legality check and
+ *    the write are made against the same head (SPEC.md §11.1(5)), so a grant
+ *    that lands in between wins and this withdrawal never overwrites it. Since
+ *    APRV-236 the loser of that race re-reads and re-checks rather than
+ *    reporting the lost race: the human's answer is on the fresh head, so the
+ *    refusal the requester receives is `already-decided`, which is the fact they
+ *    need. `tests/concurrency.test.ts` races the two.
+ *
+ * `ts` is assigned at the write boundary from the injected clock, like every
+ * other gate-typed event (SPEC.md §8, A2): there is no parameter to pass one.
+ */
+export declare function withdraw(logPath: string, actionKey: string, actor: string, options?: WithdrawOptions): WithdrawResult;
+/**
+ * What a harness invocation may do with a request some earlier invocation
+ * opened for the very same bytes.
+ *
+ * `pending` — the question is still in front of a human. A retry ADOPTS it and
+ * waits out the remainder, rather than opening a second one: two prompts for
+ * one command spend a human's attention twice on a single question, and
+ * attention is the audit budget (SPEC.md §11).
+ *
+ * `granted` — a human answered, the TTL has not lapsed, and nothing has spent
+ * the grant yet. A retry proceeds on it, once, through
+ * {@link consumeHarnessGrant}.
+ */
+export type HarnessCarryKind = "pending" | "granted";
+/** A request an identical harness invocation may adopt or spend (APRV-117). */
+export interface HarnessCarry {
+    actionKey: string;
+    task: string | null;
+    kind: HarnessCarryKind;
+    /** `seq` of the `approval.requested` that opened the current cycle. */
+    requestSeq: number | null;
+    /** `seq` of the `approval.granted`, on `granted` only. */
+    decisionSeq: number | null;
+}
+export declare function findHarnessCarry(records: EventRecord[], payloadHash: string, cls: string, ts: string, ttlMs: number | null): HarnessCarry | null;
+/**
+ * `GateOptions` plus the one thing a harness spend states about itself
+ * (APRV-146).
+ */
+export interface ConsumeHarnessOptions extends GateOptions {
+    /**
+     * The hash of the payload the harness is about to run (amended SPEC.md §10.4).
+     *
+     * REQUIRED for every spend. It is never read from the log: a value read from
+     * the log would prove nothing, and the whole point is that the process about
+     * to run the command states, independently, what it holds so the runtime can
+     * compare it against what the human approved. Optional in the type and
+     * enforced at the write boundary, exactly as `core/execute.ts` enforces
+     * `presentedPayloadHash`, so omitting it is a machine-readable refusal rather
+     * than a compile error a caller could silence with a placeholder.
+     */
+    presentedPayloadHash?: string;
+    /**
+     * The task id of the invocation doing the spending (APRV-200).
+     *
+     * Used for one thing and nothing else: to decide whether the recorded
+     * {@link HARNESS_GRANT_ORIGIN} is `direct` or `carried`. It never gates the
+     * spend, never changes a refusal, and never appears on the record itself.
+     *
+     * It is a CLAIM, in §9's computed-versus-claimed vocabulary, and it is bounded
+     * the way §11.1 invariant 4 bounds every claim: the only value it can produce
+     * unaided is the one that ADDS scrutiny. `direct` is reachable solely by
+     * presenting the task the request record already carries, which is a fact the
+     * gate reads out of the verified log rather than out of the caller; anything
+     * else, absence included, records `carried`.
+     */
+    spendingTask?: string;
+}
+/**
+ * How the authorization reached the process that spent it (APRV-200).
+ *
+ * `direct` — the tool call that spent this grant is the tool call that asked for
+ * it. One process opened the request, waited, saw the decision and proceeded, so
+ * the gate observed the whole ordering: nothing this runtime authorized could
+ * have run before the human answered.
+ *
+ * `carried` — a LATER tool call spent it, under APRV-117's carryover or its
+ * adoption sibling. The asking invocation had already returned a verdict (a
+ * `hook-timeout` deny, which leaves the request open), and whether the harness
+ * honoured that verdict is a fact this runtime never observes: it decides, and
+ * the harness executes. So the ordering the record implies — grant, then
+ * execution — is only guaranteed for `direct`, and this marker is what lets an
+ * auditor tell the two apart from the committed log alone. See
+ * `docs/claude-code-hook.md`, "When the grant can follow the write".
+ *
+ * Absent on an `execution.started` that names no `grant_seq`: an unattended
+ * execution has no grant, so it has no origin to report (SPEC.md §6.3).
+ */
+export type HarnessGrantOrigin = "direct" | "carried";
+/** The payload field {@link HarnessGrantOrigin} is recorded under. */
+export declare const HARNESS_GRANT_ORIGIN = "grant_origin";
+/**
+ * The payload field naming the TOOL CALL that spent a carried grant (APRV-287).
+ *
+ * A carried grant's `execution.started` names the task of the request, because
+ * that is the task the log holds the approval lifecycle under. The tool call
+ * that actually ran the command is a different one, and until this field the
+ * runtime had no way back to it: the completion counterpart rebuilds a task id
+ * from the reporting event's session and tool-use id, found no start under it,
+ * and refused `not-delegated`. The consequence was the one an operator saw on
+ * 2026-09-06 — a granted commit-and-push completed, no `execution.completed`
+ * was ever written, and the loop floor the refusal text promises would clear on
+ * a completion stayed shut over the rest of the session.
+ *
+ * DERIVED, never declared: the value is the task id the runtime minted for the
+ * spending invocation from the harness's session and tool-use ids, the same one
+ * {@link HARNESS_GRANT_ORIGIN} is computed against. A reporter cannot name a
+ * bucket with it, because the only thing it can reach is a start this runtime
+ * wrote for that same tool call.
+ *
+ * Absent where the spend is `direct` (the record's own `task` already names the
+ * tool call) and on every record written before this field existed, which is why
+ * every reader treats absence as "no second name" rather than as a fault.
+ */
+export declare const HARNESS_SPENDING_TASK = "spent_by_task";
+export type ConsumeHarnessResult = {
+    ok: true;
+    record: EventRecord;
+} | GateRefusal;
+/**
+ * Spend a harness grant, exactly once (APRV-117).
+ *
+ * ## Why this is `execution.started`, and why it is alone
+ *
+ * A harness grant mints no token (APRV-106), so nothing in `core/token.ts`
+ * records that it was used, and without such a record a grant could authorize
+ * an unbounded number of identical retries for the whole TTL. The consumption
+ * marker has to be a real event through compare-and-append (SPEC.md §11.1(5)),
+ * and it has to be one the gate already reads as terminal for an idempotency
+ * key. `execution.started` is exactly that: {@link request} refuses a key that
+ * has one as `already-executed`, and {@link decide} refuses to revoke past it.
+ * Reusing it means the single-use rule is the gate's existing rule rather than
+ * a second one written next to it.
+ *
+ * **No `execution.completed` or `execution.failed` follows, ever.** The harness
+ * runs the command; this runtime hands over permission and never observes an
+ * exit status. Appending a completion would fabricate an outcome, and in this
+ * vocabulary it would also assert something with consequences — an
+ * `execution.completed` clears a task's loop-escalation streak (SPEC.md §10.2).
+ * A harness execution is therefore recorded as begun and never as finished,
+ * which is precisely what the runtime knows. The `execution: "harness"` marker
+ * on the payload says so on the record itself, so a reader of the start event
+ * alone can see why no outcome ever lands.
+ *
+ * ## What it refuses
+ *
+ * Attestation is checked here, and not as a formality: this is the one
+ * enforcement path that reaches a harness `allow` without passing through
+ * {@link request} (that happened in an earlier process, possibly against
+ * earlier policy bytes). A policy that changed since the human attested it
+ * cannot answer anything, so it answers nothing. `policy-drift` is the second
+ * half of the same idea and is APRV-134: attested is not enough when what is
+ * attested is a DIFFERENT policy from the one the approver decided under, and
+ * the gap between a tap and a retry's spend is exactly where a re-attestation
+ * fits.
+ *
+ * Everything else follows the derivation: `not-requested` when the key has no
+ * request, `expired` when the TTL lapsed (judged from the request's own `ts`,
+ * event or no event, exactly as {@link decide} judges it), `already-executed`
+ * when something already spent it, `not-granted` for every other state and for
+ * a grant that is not harness-executed. The content binding is checked last and
+ * refuses twice over (APRV-146): `payload-hash-required` when the grant records
+ * no bytes or the consumer states none, `payload-mismatch` when the bytes stated
+ * are not the bytes approved. Budgets are not re-evaluated: the
+ * authorization was charged at `approval.granted`, and `core/budgets.ts`'s
+ * consumption contract already dedupes a start event against a grant carrying
+ * the same `action_key`.
+ *
+ * ## What the record says about ORDER (APRV-200)
+ *
+ * The start carries `grant_origin`, which answers a question the log could not
+ * previously be asked: was the tool call that spent this grant the tool call
+ * that asked for it? `direct` says yes, and the gate observed the whole ordering
+ * in one process. `carried` says a LATER invocation spent it — APRV-117's
+ * carryover, or its adoption sibling — which means the asking invocation had
+ * already returned a verdict, and this runtime never sees whether the harness
+ * honoured it. A grant that arrives after the effect it names is a ratification
+ * and not an approval, and `carried` is the window in which that is possible.
+ * See {@link HarnessGrantOrigin} and `docs/claude-code-hook.md`.
+ */
+export declare function consumeHarnessGrant(logPath: string, actionKey: string, actor: string, options?: ConsumeHarnessOptions): ConsumeHarnessResult;
+/** What the harness is about to run, as one class of one command. */
+export interface HarnessStartInput {
+    task: string;
+    actionKey: string;
+    cls: string;
+    /**
+     * The hash of the bytes the verdict was computed over, and which are about to
+     * run (amended SPEC.md §6.2/§10.4, APRV-140).
+     *
+     * REQUIRED. A start event that cannot say WHAT ran records only that something
+     * did, which is the whole of what APRV-140 set out to fix and is exactly the
+     * state the harness path was left in. Optional in the type and enforced at the
+     * write boundary, on the reading `core/execute.ts` gives
+     * `presentedPayloadHash`: a caller that omits it is refused
+     * `payload-hash-required` and told what to compute, rather than turned away by
+     * the compiler and left to satisfy it with a placeholder.
+     */
+    payload_hash?: string;
+    /** Canonical decimal USD string (APRV-121); a JSON number is read as the historical form. */
+    est_cost_usd?: UsdInput;
+}
+export type HarnessStartResult = {
+    ok: true;
+    record: EventRecord;
+} | GateRefusal;
+/**
+ * Charge and record a harness execution that no human was asked about
+ * (APRV-141).
+ *
+ * ## The blind spot this closes
+ *
+ * `core/budgets.ts` computes consumption from `approval.granted` and
+ * `execution.started`, and `core/audit.ts` draws its retrospective sample from
+ * `execution.started` alone. The harness hook wrote neither for a supervised or
+ * autonomous verdict — the comment said, correctly, that writing one per agent
+ * action fills the log — so under Claude Code the majority of real activity
+ * consumed no budget, `daily_actions` included, and was invisible to the
+ * overseer that exists to read a sample of it. A budget that the busiest
+ * execution path does not charge is not a budget, and the decision recorded on
+ * APRV-141 is that the log volume is the lesser cost.
+ *
+ * ## Why this record and not a new event type
+ *
+ * It is the same `execution.started` {@link consumeHarnessGrant} appends, with
+ * the same `execution: "harness"` marker saying why no `execution.completed` or
+ * `execution.failed` will ever follow: the harness runs the command and this
+ * runtime never observes an exit status. Reusing the shape means budgets and
+ * audit count these without learning a second vocabulary, and the gate's
+ * existing single-use rule (a key with an `execution.started` is
+ * `already-executed`) applies unchanged. What differs is only the authorization
+ * being recorded: there, a human's grant; here, the policy itself.
+ *
+ * ## What it refuses
+ *
+ * The same two facts the hook's own guard checks and `core/execute.ts` checks
+ * before an unattended start — attestation and loop-escalation — re-checked at
+ * the write boundary against the records this append is authorized by, plus the
+ * budget verdict this record is the charge for. A class that resolves `manual`
+ * is refused outright: a manual action is authorized by a grant and spent
+ * through {@link consumeHarnessGrant} or a token, and admitting one here would
+ * be a second, unapproved spender.
+ *
+ * Since APRV-146 the content binding is refused here too. `payload-hash-required`
+ * says the caller named no bytes, and it is a refusal rather than an omitted
+ * field because a start event with no `payload_hash` is a record that says
+ * something ran without saying what — the state APRV-140 closed everywhere else.
+ */
+export declare function startHarnessExecution(logPath: string, input: HarnessStartInput, actor: string, options?: GateOptions): HarnessStartResult;
+/**
+ * Which untrusted reporter asserted a harness outcome. CLOSED, and extended only
+ * by a task that adds the case.
+ *
+ * It names the reporter and reduces nothing: it is a CLAIMED field in the
+ * computed-versus-claimed vocabulary of SPEC.md §9, recorded so a reader can
+ * tell a report from an observation without reading the record's provenance out
+ * of its shape.
+ */
+export declare const HARNESS_REPORTERS: readonly ["post-tool-use"];
+export type HarnessReporter = (typeof HARNESS_REPORTERS)[number];
+export declare function isHarnessReporter(value: unknown): value is HarnessReporter;
+/** What a harness says happened to one tool call. */
+export interface HarnessFinishInput {
+    /** The harness's identifier for the run of tool calls. */
+    sessionId: string;
+    /** The harness's identifier for this tool call. */
+    toolUseId: string;
+    /** Read from the reporting event by a CLOSED set of readings; never guessed. */
+    outcome: "completed" | "failed";
+    reportedBy: HarnessReporter;
+    /**
+     * The exit code, when the harness stated one, and `null` otherwise.
+     *
+     * Claude Code's post-execution event carries none (`docs/claude-code-hook.md`),
+     * so in practice this is `null` on that adapter. It is `null` rather than
+     * omitted-and-inferred for the reason `execution.indeterminate` carries a null
+     * one: a fabricated number reads exactly like a measured one.
+     */
+    exitCode?: number | null;
+}
+export type HarnessFinishResult = {
+    ok: true;
+    task: string;
+    records: EventRecord[];
+} | GateRefusal;
+export declare function finishHarnessExecution(logPath: string, input: HarnessFinishInput, actor: string, options?: GateOptions): HarnessFinishResult;
+export type ExpireResult = {
+    ok: true;
+    record: EventRecord;
+} | GateRefusal;
+/**
+ * Append `approval.expired` for a live request whose TTL has lapsed.
+ *
+ * The system verb: no human decides an expiry, so the actor is
+ * {@link EXPIRY_ACTOR} and there is no identity to resolve. Used by the daemon's
+ * sweep (M5) and by tests; `decide` performs the same append itself when it
+ * discovers a lapse first.
+ *
+ * Refuses when the request is not live (`not-requested`, `already-decided`) or
+ * when the TTL has not lapsed (`not-expired`, which also covers a policy that
+ * declares no `defaults.approval_ttl` — no TTL means no lapse, and expiring a
+ * request the policy never bounded would be the runtime inventing a deadline).
+ *
+ * `defaults.on_expiry` is recorded in the payload. Its only v0.1 value,
+ * `reject`, does not change the mechanics here — an expired request is terminal
+ * either way — it tells the projection layer to render the envelope's `state:`
+ * as `rejected`.
+ */
+export declare function expire(logPath: string, actionKey: string, options?: GateOptions): ExpireResult;