approval-md 0.1.0 → 0.2.0

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

@@ -0,0 +1,858 @@
+/**
+ * Execution: the events that say a side effect actually happened (SPEC.md §8,
+ * §10.1, and the human-settled execution points of 2026-08-06).
+ *
+ * `core/gate.ts` decides whether an action *may* run and appends no
+ * `execution.*` event. `core/token.ts` spends a manual action's token. This
+ * module is the single door between those two facts and the world: it is where
+ * `execution.started` is appended before a command is spawned, and where
+ * `execution.completed` / `execution.failed` are appended after it exits.
+ *
+ * ## The five properties this module exists to hold
+ *
+ * 1. **Nothing starts without authorization.** On the manual path a valid token
+ *    is REQUIRED; absent it, {@link startExecution} refuses `token-required` and
+ *    appends nothing at all. On the supervised/autonomous paths no token exists
+ *    (amended SPEC.md §6.3 gives them no grant), so authorization is proven
+ *    differently and in this order: the action must be declared in a
+ *    `task.registered` record, the policy must be attested, loop safety must not
+ *    have escalated the task, no execution may already have started for the key,
+ *    the executor's recomputed `payload_hash` must equal the one the declaration
+ *    bound to (APRV-140), and the budget must pass. Only then is
+ *    `execution.started` appended.
+ * 2. **`started` precedes the side effect.** The CLI's `approval run` appends
+ *    the start event *before* it spawns the child, never after. A log that
+ *    records an execution only once it succeeded is a log that cannot tell you
+ *    about the one that did not.
+ * 3. **A crash therefore leaves a dangling execution, and that is correct.**
+ *    Between `started` and its outcome the log honestly says "this began and we
+ *    do not know how it ended". {@link danglingExecutions} surfaces that state
+ *    distinctly — `approval status` reports it, `approval queue` does not,
+ *    because a dangling execution is not a pending decision. It is one of five
+ *    custody states {@link executionCustody} distinguishes (APRV-120), and the
+ *    other four matter for the same reason: a harness execution is terminal by
+ *    design rather than debris, and an attempt whose outcome is unknown is
+ *    neither a failure nor a thing to retry.
+ * 4. **Nothing auto-repairs.** No function here closes a dangling execution as a
+ *    side effect of anything else. A second `approval run` for the same key does
+ *    not "recover" the first; it refuses (`token-consumed` on the manual path,
+ *    `already-executed` off it). Recovery is a human calling
+ *    {@link resolveExecution} with the outcome they actually observed and a
+ *    mandatory note saying how they know — the same append path, no fabricated
+ *    exit code, `attested_by_human: true` so no reader mistakes it for a
+ *    machine's report. ({@link finishExecution} is the mechanical sibling, used
+ *    by `approval run`, which watched the child exit.) An automatic
+ *    reconciliation would have to *guess* whether the email went out, and a
+ *    guess written into an append-only log is indistinguishable from a fact.
+ *    The same rule governs an INDETERMINATE outcome, more strictly:
+ *    {@link reconcileExecution} is human-only, appends beside the record rather
+ *    than over it, and nothing anywhere converts one into completed or failed.
+ * 5. **The budgets contract is honored at the documented charge point.**
+ *    `core/budgets.ts` charges the manual path at `approval.granted` and the
+ *    supervised/autonomous paths at `execution.started`. This module is that
+ *    second charge point: it evaluates budgets at the start timestamp, appends
+ *    `budget.exceeded` and refuses when they fail, and records
+ *    `payload.class` + `payload.est_cost_usd` on every start event it writes.
+ *    The manual path is charged at grant and is deliberately NOT charged again
+ *    here — `consumeToken` writes that start event, and the evaluator already
+ *    ignores a start whose window holds a matching grant.
+ *
+ * ## Loop safety (SPEC.md §10.2), from this side
+ *
+ * Three consecutive `execution.failed` events for one task escalate it to
+ * manual. `core/loop.ts` computes that; this module enforces it on the
+ * execution side: an escalated task's supervised/autonomous action refuses with
+ * `loop-escalated`, which is not a ban but a redirection — request the action,
+ * have a human grant it, and run it with the token. `core/gate.ts` enforces the
+ * matching half at intake so the redirection is visible one step earlier.
+ *
+ * ## Time (amended SPEC.md §8, A2)
+ *
+ * `execution.*` events are gate-typed, so their timestamps are assigned by the
+ * runtime at the write boundary: no public function here takes a `ts`, each
+ * reads {@link ExecuteOptions.clock} once, and the party whose budget window
+ * and TTL are being judged does not author the clock. Replay is preserved by
+ * injection — a test hands in a fixed clock, production hands in nothing.
+ */
+import { type AttestationRefusalDetail } from "./attest.js";
+import { type BudgetVerdict } from "./budgets.js";
+import { type ClockOptions } from "./clock.js";
+import { type AppendError, type AppendOptions, type EventRecord } from "./log.js";
+import { type Autonomy } from "./policy-load.js";
+import type { SandboxState } from "./sandbox.js";
+export { isLoopEscalated, loopEscalation, LOOP_ESCALATION_THRESHOLD, type TaskLoopState, } from "./loop.js";
+/**
+ * The closed set of execution refusal codes. Frozen public API in the same sense
+ * the gate's and the token module's are: an agent branches on these to decide
+ * whether to fix itself, ask a human, or stop.
+ *
+ * The five token codes are re-exposed verbatim rather than collapsed into one:
+ * `approval run` on the manual path is a token spend, and "you presented no
+ * token" (`token-required`), "you presented the wrong one" (`token-mismatch`),
+ * and "it was already spent" (`token-consumed`) call for three different
+ * responses.
+ */
+export declare const EXECUTE_REFUSAL_CODES: readonly [
+/** Execution preflight requires a person or agent principal, never runtime identity. */
+"actor-invalid", 
+/** No `task.registered` record declares this action key (SPEC.md §7). */
+"action-not-registered", 
+/**
+ * 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.
+ *
+ * Refused on BOTH paths, before either is chosen, which is what separates it
+ * from `token-required`. That code is a redirection — get a token and come
+ * back — and this one is not: there is no token to get and no grant that
+ * could mint one, because `core/gate.ts` refuses the request that would open
+ * one under the same code. Nothing is appended on either path, and no retry
+ * of any shape changes the answer.
+ *
+ * Surfaced verbatim from `core/token.ts` as well, for a manual-path spend of
+ * a token whose class a policy amendment raised after the grant, so an
+ * executor meets one spelling of one fact.
+ */
+"class-human-only", 
+/** The class resolves manual and no token was presented. Nothing appended. */
+"token-required", 
+/** Loop safety escalated the task to manual (SPEC.md §10.2). */
+"loop-escalated", 
+/** Policy is unattested or its bytes changed (`core/attest.ts`). */
+"policy-not-attested", 
+/** The attested policy changed after supervised-live intake decided to proceed. */
+"policy-drift", 
+/** An `execution.started` already exists for this key (idempotency). */
+"already-executed", 
+/** Budgets refused the start; a `budget.exceeded` event WAS appended. */
+"budget-exceeded", 
+/** `finishExecution` found no unfinished `execution.started`. */
+"not-started", 
+/** `finishExecution` found the started execution already closed. */
+"already-finished", 
+/** No grant governs this manual action key. */
+"not-granted", 
+/** A grant exists, but the presented token is not its preimage. */
+"token-mismatch", 
+/** The token was already spent. */
+"token-consumed", 
+/** The parent request's TTL lapsed. */
+"token-expired", 
+/** A human withdrew the grant. */
+"token-revoked", 
+/**
+ * The grant was harness-executed and minted no token (APRV-106). Surfaced
+ * verbatim from `core/token.ts` so the executor's vocabulary stays that
+ * module's vocabulary: an agent that reads this has not lost a token, it is
+ * holding a grant that authorized a process which runs the command itself.
+ */
+"harness-executed", 
+/**
+ * The payload presented does not hash to the bytes the grant approved
+ * (amended SPEC.md §10, A1). Nothing was appended and the token is still live.
+ */
+"payload-mismatch", 
+/**
+ * `resolveExecution` was called without the mandatory human observation, or
+ * by an actor that is not a `human:`. Recorded here rather than reusing
+ * `not-started` because the log is unchanged for a different reason: the
+ * caller, not the state.
+ */
+"actor-not-human", 
+/**
+ * The key's latest `execution.started` is a DELEGATED record (APRV-117,
+ * APRV-120): it carries `payload.execution: "harness"`, so the harness ran the
+ * command and this runtime never observed an exit status. The record is
+ * complete as written and terminal by design, and no outcome may be placed
+ * over it.
+ *
+ * Distinct from the two refusals it sits between, and the distinctions are the
+ * point. `not-started` says nothing began; `already-finished` says something
+ * began and an outcome already exists. This one says the thing that began is
+ * not this runtime's to close: a `completed` or `failed` written here would
+ * report an exit code nobody watched, and an `execution.completed` would
+ * additionally clear the task's loop-escalation streak (SPEC.md §10.2) on the
+ * strength of it. {@link executionCustody} reports these as `delegated` and
+ * {@link danglingExecutions} deliberately leaves them out, so this code is the
+ * enforcement half of a custody state the projections already draw.
+ */
+"execution-delegated", 
+/**
+ * The key's execution ended in an unknown outcome (APRV-120) and has not been
+ * reconciled. INDETERMINATE IS A CUSTODY STATE: the token stays spent, the
+ * idempotency key stays burned, and a re-run is refused here rather than
+ * anywhere else, because "we do not know whether this happened" is a
+ * different fact from "this already happened" and calls for a different
+ * repair — a person establishing which it was, with `execution reconcile`.
+ */
+"execution-indeterminate", 
+/**
+ * `reconcileExecution` found no unreconciled `execution.indeterminate` for
+ * the key. There is nothing whose outcome is in doubt, so there is nothing to
+ * resolve; a dangling execution is closed with `execution resolve` instead.
+ */
+"not-indeterminate", 
+/**
+ * The indeterminate outcome already carries a resolution. A second one would
+ * be a second answer to a question a person already answered, and the first
+ * record is never rewritten.
+ */
+"already-reconciled", 
+/**
+ * `execution resolve --dangling` was asked to attest with no terminal to
+ * attest at, and without `--yes` (APRV-264). The bulk form writes
+ * `attested_by_human: true` on every record it appends, and a confirmation a
+ * pipe could answer is not an attestation. Distinct from `actor-not-human`,
+ * which is about WHO is attesting: this one is about whether anybody was
+ * actually asked.
+ */
+"dangling-stdin-not-tty", 
+/**
+ * The bulk confirmation was declined, or withdrawn at the prompt (APRV-264).
+ * Nothing was appended and the dangling executions stand exactly as they
+ * were. Its own code because "the operator said no" and "the operator could
+ * not be asked" are different facts about the same prompt.
+ */
+"dangling-declined", 
+/** 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; nothing may execute on an untrustworthy log. */
+"log-corrupt", 
+/**
+ * The append itself failed; `append` carries the underlying error. Its `code`
+ * is `head-moved` when a record landed between this module's read and its
+ * append, so the idempotency and budget checks that authorized the write were
+ * made against an older log. Nothing was written. Since APRV-236 this code
+ * reaches a caller of {@link startExecution} 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 re-derived rather
+ * than reported.
+ */
+"append-failed"];
+export type ExecuteRefusalCode = (typeof EXECUTE_REFUSAL_CODES)[number];
+/** Every execution failure is one of these. Nothing here throws. */
+export interface ExecuteRefusal {
+    ok: false;
+    code: ExecuteRefusalCode;
+    message: string;
+    /** Attestation discriminator, when `code` is `policy-not-attested`. */
+    detail?: AttestationRefusalDetail;
+    /** The failing verdicts, when `code` is `budget-exceeded`. */
+    verdicts?: BudgetVerdict[];
+    /** The seq of the record that produced the refusal, when there is one. */
+    seq?: number;
+    /** An event appended alongside the refusal: only ever `budget.exceeded`. */
+    record?: EventRecord;
+    /** The underlying append error, when `code` is `append-failed`. */
+    append?: AppendError;
+}
+/**
+ * Options shared by the execution verbs.
+ *
+ * No `ts`: `execution.*` events are gate-typed, so amended SPEC.md §8 (A2)
+ * assigns their timestamps at the write boundary from {@link ClockOptions}.
+ */
+export interface ExecuteOptions extends ClockOptions {
+    /**
+     * The raw single-use token printed by `approval grant`. REQUIRED for an
+     * action whose class resolves to `manual`; meaningless off that path, where no
+     * token was ever minted.
+     */
+    token?: string;
+    /**
+     * The hash of the payload about to be executed (amended SPEC.md §10, A1),
+     * forwarded to `core/token.ts` on the manual path and checked against the
+     * registered declaration off it (APRV-140). `approval run` computes it with
+     * `runPayloadHash(argv, cwd)`; an adapter with a different payload computes
+     * its own. REQUIRED on every path: under A1 every manual grant binds to
+     * bytes, and under APRV-140 so does every declaration that executes.
+     *
+     * It is never read from the log. A value read from the log would prove
+     * nothing: the point is that the executor states, independently, what it
+     * holds, and the runtime compares.
+     */
+    presentedPayloadHash?: string;
+    /** Where to find `APPROVAL.md`. Same semantics as `loadPolicy`. */
+    policy?: {
+        dir?: string;
+        file?: string;
+    };
+    /** Schema directory, passed to the append's write-boundary validation. */
+    schemaDir?: string;
+    /** Lock tuning for the append path. */
+    append?: AppendOptions;
+    /**
+     * How many credential-bearing variables the executor withheld from the child
+     * it is about to spawn (APRV-205), recorded on `execution.started` as
+     * `env_stripped`.
+     *
+     * A COUNT, never a name and never a value: a name is half of a credential,
+     * and SPEC.md §11.1's raw-secrets invariant is not satisfied by leaking the
+     * other half slowly. It is informational — nothing in the gate reads it back
+     * and no decision turns on it, which is what keeps it clear of §11.1's
+     * "self-reported fields never reduce scrutiny". No CLI flag sets it: it is
+     * computed by `core/child-env.ts` at the spawn site, in the same process that
+     * spawns.
+     */
+    envStripped?: number;
+    /**
+     * The room the child ran in (APRV-193), recorded on `execution.started` as
+     * `sandbox`.
+     *
+     * Computed at the spawn site by `core/sandbox.ts` from what the MACHINE can
+     * do and what the caller was holding, never from a claim about either: the
+     * three interesting values are the runtime's own findings, and the fourth
+     * (`opted-out`) is the operator's `--no-sandbox`, which is recorded precisely
+     * because an opt-out nobody can see afterwards is an opt-out that costs
+     * nothing to take. Informational in the same sense `envStripped` is: nothing
+     * in the gate reads it back and no decision turns on it, which is what keeps
+     * it clear of §11.1's "self-reported fields never reduce scrutiny" — the
+     * field records a decision already made rather than making one.
+     */
+    sandbox?: SandboxState;
+    /**
+     * Where per-request private keys live (APRV-105). Defaults to `.approval/keys/`
+     * beside the log. Read when no `token` is passed and a grant carries a
+     * `token_sealed`; unlinked once the token is spent.
+     */
+    keyStoreDir?: string;
+    /**
+     * How many times {@link startExecution} re-derives its verdict after a
+     * `head-moved` refusal, at most `core/head-retry.ts`'s `HEAD_MOVED_ATTEMPTS`
+     * (APRV-236).
+     *
+     * Only ever lowers the bound, on the same terms as `core/gate.ts`'s option of
+     * the same name: `1` is the unretried writer, which is what a test pins the
+     * pre-APRV-236 shape with, and a larger number, a zero or a fraction falls
+     * back to the runtime's own value. The ceiling is not a caller's to raise.
+     */
+    retryOnHeadMoved?: number;
+    /** Internal binding from an unrecorded supervised-live intake verdict. */
+    expectedPolicySha256?: string;
+}
+/** What a `task.registered` record declared about one action key. */
+export interface Declaration {
+    task: string;
+    class: string;
+    /**
+     * The declared cost as a canonical decimal USD string (APRV-121), `"0"` when
+     * the declaration named none. A `task.registered` record written before that
+     * change carries a JSON number and normalizes to the same string here.
+     */
+    est_cost_usd: string;
+    reversible: boolean | null;
+    summary: string | null;
+    /**
+     * The content binding the registration declared (amended SPEC.md §6.2,
+     * APRV-140), or `null` when it declared none. Off the manual path this is the
+     * ONLY thing an execution can be checked against: there is no grant, so the
+     * declaration is the whole of what was authorized.
+     */
+    payload_hash: string | null;
+}
+/**
+ * Find the declaration for `actionKey` across every `task.registered` record.
+ *
+ * The log — not the task file, which may have been edited since — is the
+ * authority, exactly as it is for `approval request`. The search is by action
+ * key alone because an execution names a key, not a task: SPEC.md §7 makes the
+ * `idempotency_key` the identity of a side effect, and an undeclared key is the
+ * one thing that must never execute.
+ *
+ * A key must be declared by exactly one task. If a log somehow carries the same
+ * key under two tasks, this returns the last, but callers on an enforcement path
+ * MUST first fail closed via {@link declaringTasks}: the collision is refused at
+ * registration (`core/gate.ts`, APRV-138), so a log that still holds one is
+ * untrustworthy and nothing may execute from the guess.
+ */
+export declare function findDeclaration(records: EventRecord[], actionKey: string): Declaration | null;
+/**
+ * Every declaration question the log answers, keyed once (APRV-211).
+ *
+ * The three per-key helpers above each scan the whole log, which is the right
+ * shape for the gate (one key, one decision, no bookkeeping to get wrong) and
+ * the wrong shape for a caller asking about thousands of keys: `core/audit.ts`'s
+ * candidate selection asked all three per `execution.started` and spent three
+ * full scans per candidate, which is quadratic in the log and measured at 3.3 s
+ * on a ten-thousand-record log.
+ *
+ * This is a **per-call derivation and nothing more**. It caches nothing across
+ * calls, holds no state, reads no file and no clock, and is built from the
+ * records the caller already verified. The per-key helpers remain the gate's
+ * API: an enforcement path deciding ONE action asks them, because a decision
+ * that depends on an index built somewhere else is a decision that depends on
+ * that index being fresh.
+ */
+export interface DeclarationIndex {
+    /** Per key, the distinct tasks declaring it, exactly as {@link declaringTasks}. */
+    declaringTasks: Map<string, string[]>;
+    /** Per key, the LAST declaration in log order, exactly as {@link findDeclaration}. */
+    declarations: Map<string, Declaration>;
+    /** Keys the log holds an `approval.requested` for, as {@link hasApprovalCycle}. */
+    requested: Set<string>;
+}
+export declare function indexDeclarations(records: readonly EventRecord[]): DeclarationIndex;
+/**
+ * The distinct tasks that declare `actionKey`. More than one is a cross-task
+ * collision (APRV-138): the registration boundary refuses these, so a log that
+ * still holds one cannot be trusted to say which declaration governs. Every
+ * enforcement caller of {@link findDeclaration} guards on this and fails closed
+ * rather than executing the last-registered (possibly weaker) declaration.
+ */
+export declare function declaringTasks(records: EventRecord[], actionKey: string): string[];
+/**
+ * Has a human ever been asked about this action key (amended SPEC.md §6.3,
+ * APRV-127)?
+ *
+ * True as soon as the log holds one `approval.requested` for the key, and it
+ * stays true: a rejected, expired or withdrawn cycle is still a cycle, and an
+ * action that could shed its gate by being refused would be an action that
+ * profits from a "no".
+ *
+ * Pure, and derived from the log alone — never from a payload field a requester
+ * wrote about itself. Two callers: {@link startExecution}, which requires the
+ * token of any action that went through the gate, and `core/audit.ts`, which
+ * leaves such actions out of the retrospective pool because a human already
+ * looked.
+ */
+export declare function hasApprovalCycle(records: readonly EventRecord[], actionKey: string): boolean;
+export type StartResult = {
+    ok: true;
+    /** The appended `execution.started` record. */
+    record: EventRecord;
+    /** The autonomy that admitted it — `manual` means a token was spent. */
+    autonomy: Autonomy;
+    task: string;
+    class: string;
+    /** Canonical decimal USD string (APRV-121). */
+    est_cost_usd: string;
+    /** The digest of the spent token, on the manual path only. */
+    tokenSha256?: string;
+} | ExecuteRefusal;
+/** Internal adapter preflight result. The token is never rendered or logged. */
+export type ExecutionEligibilityResult = {
+    ok: true;
+    mode: "token" | "policy";
+    autonomy: Autonomy;
+    /** Explicit or locally delivered token, present only on the token path. */
+    token?: string;
+} | ExecuteRefusal;
+/**
+ * Check whether an adapter execution may proceed to credential resolution.
+ *
+ * This is a preflight, never an execution permit. A successful result appends
+ * nothing, consumes nothing and leaves delivered-token key material in place.
+ * {@link startExecution} must still run after adapter precheck and repeats every
+ * check against a fresh verified read before compare-and-append. A budget
+ * refusal retains `startExecution`'s required `budget.exceeded` audit record.
+ */
+export declare function checkExecutionEligibility(logPath: string, actionKey: string, options: ExecuteOptions, actor: string): ExecutionEligibilityResult;
+/**
+ * Begin an execution: the single entry point for appending `execution.started`.
+ *
+ * Check order, and why it is this order:
+ *
+ * 1. **The log reads**, so a torn or unreadable log stops everything before a
+ *    policy question is asked.
+ * 2. **The declaration.** An action key no `task.registered` record declares is
+ *    `action-not-registered` — SPEC.md §7's "an action's class MUST be declared
+ *    before an execution token can be requested for it", enforced at the last
+ *    possible moment as well as the first.
+ * 3. **Policy resolution**, including SPEC.md §7's irreversibility floor (the
+ *    declared `reversible: false` forces `manual`, which forces a token). A
+ *    failed policy load resolves everything to `manual` — `policy-match.ts`'s
+ *    contract, not softened here — so an unparseable policy makes every action
+ *    require a human's token.
+ * 4. **Manual path: the token, or nothing.** No token → `token-required`, and
+ *    the log is untouched. With one, `consumeToken` verifies it and appends the
+ *    start event; a class that resolves manual but was never granted refuses
+ *    `not-granted` from that layer. Attestation is not re-checked here: the
+ *    grant that minted the token could only have happened under an attested
+ *    policy, and re-checking would refuse an execution a human already
+ *    authorized because a file changed afterwards.
+ * 5. **Non-manual path**, in order: attestation → loop escalation → idempotency
+ *    → content binding → budgets → append. Attestation first because an
+ *    unverified policy cannot answer the autonomy question it was just asked to
+ *    answer; the binding (APRV-140) after the free checks and before the
+ *    charging one; budgets last because a budget refusal *writes*
+ *    (`budget.exceeded`), and the cheaper refusals must leave the log
+ *    untouched.
+ *
+ * `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 startExecution(logPath: string, actionKey: string, options: ExecuteOptions, actor: string): StartResult;
+/**
+ * What a failure says about itself, beyond its exit status (APRV-211).
+ *
+ * Machine-readable first: `code` is the executor's own closed refusal code (for
+ * the daemon's advance, one of `cli/log-advance.ts`'s
+ * `LOG_ADVANCE_REFUSAL_CODES`), so a status surface can branch on it rather
+ * than parse prose. The message is the sentence a human reads.
+ *
+ * It is a REPORT and never an authorization: nothing in the gate reads either
+ * field back, no decision anywhere turns on them, and SPEC.md §11.1's rule that
+ * self-reported fields never reduce scrutiny is untouched — the only thing they
+ * can do is make a failure explicable. The message is written by this runtime's
+ * own code and must stay that way: a raw child stderr forwarded here could
+ * carry a credential into a permanent log.
+ */
+export interface FailureReason {
+    code: string;
+    message: string;
+}
+/**
+ * The provider's own identifier for a completed effect (APRV-251, SPEC.md §8).
+ *
+ * Two strings and no more, because the schema admits two and no more: the
+ * adapter that executed the action, and the id the provider's record files the
+ * effect under. See {@link FinishOptions.providerRef} for who may write one and
+ * what nobody may do with it.
+ */
+export interface ProviderRef {
+    adapter: string;
+    id: string;
+}
+/**
+ * The bounds SPEC.md §8 and `schema/event.schema.json` place on a reference.
+ *
+ * Printable ASCII with no spaces, and short. An identifier is short; the bound
+ * is what keeps the field from becoming somewhere to put a message. Stated here
+ * as well as in the schema so that the write path can DECLINE to record a
+ * reference that would not validate, rather than hand the schema a record it
+ * will reject and leave a completed side effect with no outcome in the log.
+ */
+export declare const PROVIDER_REF_ADAPTER_MAX = 64;
+export declare const PROVIDER_REF_ID_MAX = 256;
+/** Does `value` fit what the schema will accept for a reference member? */
+export declare function providerRefMemberOk(value: string, max: number): boolean;
+/** Is `ref` recordable, in full? A half-recordable reference is not recorded. */
+export declare function providerRefRecordable(ref: ProviderRef): boolean;
+/** {@link ExecuteOptions} plus the reason a non-zero exit carries (APRV-211). */
+export interface FinishOptions extends ExecuteOptions {
+    reason?: FailureReason;
+    /**
+     * The same shape for a SUCCESS that is worth explaining (APRV-234).
+     *
+     * `reason` covers the failure case and deliberately says nothing when the
+     * exit was zero, because a completion usually has nothing to explain.
+     * Sometimes it does: the daemon's advance rebuilds the day's records branch
+     * on the trunk when the trunk has moved under it, and a status surface
+     * reading this log a day later cannot tell that from an exit status. So the
+     * executor may state it, in the same closed `{code, message}` shape, recorded
+     * on `execution.completed` only and only when the caller supplies it.
+     *
+     * A REPORT and never an authorization, exactly as {@link FailureReason} is:
+     * nothing in the gate reads it back, no decision anywhere turns on it, and
+     * SPEC.md §11.1's rule that self-reported fields never reduce scrutiny is
+     * untouched. Like the reason, it is written by this runtime's own code — a
+     * raw child stderr forwarded here could carry a credential into a permanent
+     * log.
+     */
+    note?: FailureReason;
+    /**
+     * The identifier the provider's own record files this effect under
+     * (APRV-251), recorded on `execution.completed` and on nothing else.
+     *
+     * `approval coverage` reads a witness this project does not write (git, `gh`,
+     * an adapter's provider) and asks whether the log ever saw each effect. With
+     * no reference the strongest answer available is a record of a matching class
+     * inside the effect's window, so a gated send covers an ungated one of the
+     * same class beside it. A reference names the exact effect, which is what
+     * turns that answer into one about this action and no other.
+     *
+     * Written by the adapter contract and by nothing else in this runtime: the
+     * `adapter` half is the registered adapter's name, which the contract already
+     * holds, and the `id` half is lifted from what the adapter returned, after
+     * the redaction sweep that scans everything else it returned. The contract
+     * omits a reference whose bytes that sweep touched, because a redacted
+     * identifier matches nothing and would read like one that does.
+     *
+     * A REPORT and never an authorization, exactly as {@link FailureReason} and
+     * `note` are: nothing in the gate reads it back, no decision anywhere turns
+     * on it, and SPEC.md §11.1's rule that self-reported fields never reduce
+     * scrutiny is untouched. Recorded only when the caller states one, so an
+     * execution whose adapter names no reference records none.
+     */
+    providerRef?: ProviderRef;
+    /**
+     * A test seam and nothing else (APRV-261): called once, between the read that
+     * authorizes this outcome and the append that records it.
+     *
+     * It exists because the interleaving APRV-233 is about — a record landing in
+     * exactly that window, so the compare-and-append meets a head that is no
+     * longer the one the checks were made against — cannot be produced by timing
+     * without producing a coin flip instead. The old harness held the append
+     * lockfile, slept a flat 300 ms hoping a child process had got past its read,
+     * released the lock and raced. A seam constructs the window rather than
+     * waiting for it, which is the difference between a test that proves the
+     * retry and a test that usually does.
+     *
+     * WHAT IT CANNOT DO, which is why it is safe to have on this path. It takes
+     * nothing and returns nothing, so no check can be relaxed, no field can be
+     * supplied and no verdict can be reported by it. The refusals above it have
+     * already run; the append below it still states `open.head`, the head THAT
+     * read observed, so anything the seam does to the log is caught by the
+     * compare-and-append exactly as an external writer's record would be. The
+     * strictest thing a seam can do is move the head and make the attempt fail
+     * closed, which is precisely what the test asks it for. Nothing in the
+     * runtime sets it: `grep -rn afterRead src/` finds this declaration, the one
+     * call below it, and the one line in `daemon/advance.ts` that forwards a
+     * caller's.
+     */
+    afterRead?: () => void;
+}
+export type FinishResult = {
+    ok: true;
+    record: EventRecord;
+    event: "execution.completed" | "execution.failed";
+    exitCode: number;
+    task: string;
+} | ExecuteRefusal;
+/**
+ * Close an execution with the outcome that actually happened.
+ *
+ * Exit `0` appends `execution.completed`; anything else appends
+ * `execution.failed`. Both carry `payload.exit_code` — the number, unmapped and
+ * uninterpreted, so a reader can tell exit 1 from exit 127 from a signal death
+ * (which `approval run` records as `128 + signal`, the shell convention).
+ * Neither event consumes budget: the commitment was charged at authorization
+ * time and charging it again would double-count (`core/budgets.ts`).
+ *
+ * Refuses `not-started` when the key has no `execution.started`,
+ * `already-finished` when the most recent start already has an outcome after
+ * it, and `execution-delegated` when that start was the harness's rather than
+ * this runtime's (APRV-146). All three leave the log untouched.
+ *
+ * **This is the human recovery path for a dangling execution**, and it is
+ * deliberately the only one. Nothing in this codebase closes a dangling
+ * execution automatically: an operator who knows the email went out records
+ * `0`, an operator who knows it did not records the failure, and either way the
+ * log holds an observation rather than a runtime's guess.
+ */
+export declare function finishExecution(logPath: string, actionKey: string, exitCode: number, actor: string, options?: FinishOptions): FinishResult;
+/** What a human observed about a dangling execution. */
+export type ResolveOutcome = "completed" | "failed";
+export type ResolveResult = {
+    ok: true;
+    record: EventRecord;
+    event: "execution.completed" | "execution.failed";
+    outcome: ResolveOutcome;
+    task: string;
+} | ExecuteRefusal;
+/**
+ * Close a dangling execution with what a human actually observed.
+ *
+ * {@link finishExecution} is the mechanical path: `approval run` knows the
+ * child's exit code because it waited for it. This is the path for the case
+ * that code cannot cover — the runtime died between `execution.started` and its
+ * outcome, so the log honestly says "this began and we do not know how it
+ * ended", and only a person who went and looked can say more.
+ *
+ * Five properties, all deliberate:
+ *
+ * 1. **The note is mandatory and non-empty.** The whole value of this event is
+ *    the observation behind it; an unexplained human-attested outcome is
+ *    indistinguishable from a guess, and a guess written into an append-only
+ *    log is indistinguishable from a fact. The CLI refuses an empty note as a
+ *    usage error before reaching here, and this refuses it again.
+ * 2. **Human-only.** An agent closing its own dangling execution is the agent
+ *    reporting on itself, which is the one thing the log exists not to accept.
+ * 3. **`exit_code: null`.** Not `0`, not `127`: nobody ran anything and there
+ *    is no code to report. A fabricated exit code would read exactly like an
+ *    observed one, and `payload.attested_by_human: true` marks the difference
+ *    for every reader and every projection.
+ * 4. **A harness execution is out of reach** (APRV-146). A delegated start is
+ *    refused `execution-delegated` here as it is in {@link finishExecution}: the
+ *    record is terminal by design, and a person attesting an outcome for a
+ *    command this runtime never watched would be attesting to the one thing the
+ *    log already says nobody observed.
+ * 5. **No attestation requirement.** Resolve records a fact a human observed;
+ *    it exercises no policy authority — it authorizes nothing, spends no
+ *    budget, mints no token — so it does not require an attested policy. A
+ *    dangling execution left unclosable because a policy file was edited would
+ *    be a repair blocked by an unrelated fact.
+ */
+export declare function resolveExecution(logPath: string, actionKey: string, outcome: ResolveOutcome, note: string, actor: string, options?: ExecuteOptions): ResolveResult;
+export type IndeterminateResult = {
+    ok: true;
+    record: EventRecord;
+    reason: IndeterminateReason;
+    task: string;
+} | ExecuteRefusal;
+/**
+ * Close an execution as INDETERMINATE: the side effect was attempted and
+ * nobody knows whether it committed (APRV-120).
+ *
+ * `execution.failed` used to carry this case, and conflating the two is what
+ * made a retry look safe. An adapter that times out mid-send reads, in a log
+ * that only knows `failed`, exactly like one that never opened a socket; a
+ * caller reading the second reasonably tries again, and against the first that
+ * is a double send. So the runtime writes down which it is, and the difference
+ * is positional rather than a judgment: the adapter contract records
+ * `execution.failed` for everything that goes wrong BEFORE `act` is entered
+ * (provably not committed) and this for anything after (provably nothing).
+ *
+ * Three properties, all deliberate:
+ *
+ * 1. **The consumption is burned.** The token was spent at
+ *    `execution.started` and stays spent; the idempotency key stays used; the
+ *    budget stays charged. Refunding an attempt whose outcome is unknown would
+ *    be the runtime deciding the effect did not happen, which is the one thing
+ *    nobody here knows.
+ * 2. **No exception text.** `reason` is a closed code and nothing else is
+ *    recorded. An error message is where a credential rides into the log with
+ *    a plausible excuse, and §11.1's third invariant does not have an
+ *    exception for diagnostics. The caller still receives the message, redacted,
+ *    from the adapter contract.
+ * 3. **Nothing auto-resolves.** No function here, and nothing in the daemon,
+ *    ever converts this into completed or failed. Only
+ *    {@link reconcileExecution} does, on a person's evidence.
+ */
+export declare function indeterminateExecution(logPath: string, actionKey: string, reason: IndeterminateReason, actor: string, options?: ExecuteOptions): IndeterminateResult;
+export type ReconcileResult = {
+    ok: true;
+    record: EventRecord;
+    resolution: ReconcileResolution;
+    task: string;
+    /** The `execution.indeterminate` record this resolves. */
+    indeterminateSeq: number;
+} | ExecuteRefusal;
+/**
+ * Record what a person established about an indeterminate execution.
+ *
+ * The counterpart of {@link resolveExecution}, and deliberately a separate verb
+ * with separate refusals: `resolve` closes an execution nobody watched finish,
+ * and this resolves one whose effect may or may not have landed. The questions
+ * are different ("what did the runtime do?" against "did the far side commit?"),
+ * the evidence is different (this repo's log against the relying party's), and
+ * an operator who reached for the wrong one should be told so rather than
+ * quietly write the wrong record.
+ *
+ * Four properties:
+ *
+ * 1. **The original is never rewritten.** This appends a record that NAMES the
+ *    indeterminate one by seq. The observation "we did not know" survives its
+ *    own resolution, which is the whole reason the log is append-only, and an
+ *    auditor can see both the doubt and its answer.
+ * 2. **Human-only, and never the daemon.** An agent reconciling its own unknown
+ *    outcome is the executing party reporting on itself; a daemon doing it on a
+ *    schedule is a guess with a cron entry. The mandatory note is the evidence,
+ *    in the reconciler's own words.
+ * 3. **The two resolutions are distinct in the log.** `executed` and
+ *    `not-executed` are separate closed values, not two readings of one
+ *    sentence, because everything downstream of the record turns on which.
+ * 4. **The key stays burned either way.** Resolving `not-executed` re-opens the
+ *    possibility of the EFFECT, not of this action: an `idempotency_key` is the
+ *    global identity of one side effect (§6.2) and a used one is used. The
+ *    repair is to declare a fresh action and request it, which is a new
+ *    question with a new answer, and the reconciliation is what makes asking it
+ *    honest.
+ */
+export declare function reconcileExecution(logPath: string, actionKey: string, resolution: ReconcileResolution, note: string, actor: string, options?: ExecuteOptions): ReconcileResult;
+/**
+ * What the log knows about one started execution (APRV-120).
+ *
+ * The word is custody rather than status because the question is not "did it
+ * work" but "who is holding this, and what may still be done with it". Five
+ * states, and the two that are easy to confuse are the reason the vocabulary
+ * exists:
+ *
+ * - `settled` — an `execution.completed` or `execution.failed` closed it. The
+ *   runtime watched the outcome and wrote down what it saw.
+ * - `open` — a start with no outcome, written by a runtime that MEANT to watch
+ *   one. This is the dangling execution: a crash between `execution.started`
+ *   and its outcome, repairable by a person with `execution resolve`. It is
+ *   debris, and `approval status` says so.
+ * - `delegated` — a start carrying `payload.execution: "harness"` (APRV-117,
+ *   APRV-141). **Terminal by design, and never debris.** The harness runs the
+ *   command and this runtime never observes an exit status, so no outcome event
+ *   will ever follow; the record is complete as written. Reporting these as
+ *   dangling — which is what happened before this state existed, to every
+ *   harness execution in the reference repository's own log — trains operators
+ *   to ignore the one list that is supposed to mean something.
+ * - `indeterminate` — an `execution.indeterminate`: the side effect was
+ *   attempted and nobody knows whether it committed. The token is spent and the
+ *   key is burned, and a re-run is refused, because a retry against an unknown
+ *   outcome is a blind double-execution.
+ * - `reconciled` — a person established which it was, and said so in an
+ *   `execution.reconciled` that sits beside the indeterminate record rather
+ *   than over it.
+ */
+export declare const CUSTODY_STATES: readonly ["settled", "open", "delegated", "indeterminate", "reconciled"];
+export type CustodyState = (typeof CUSTODY_STATES)[number];
+/** Where an indeterminate outcome's unknowing began. Closed (schema §8). */
+export declare const INDETERMINATE_REASONS: readonly ["act-threw"];
+export type IndeterminateReason = (typeof INDETERMINATE_REASONS)[number];
+/** What a reconciliation established. Closed, and the two are distinct. */
+export declare const RECONCILE_RESOLUTIONS: readonly ["executed", "not-executed"];
+export type ReconcileResolution = (typeof RECONCILE_RESOLUTIONS)[number];
+export declare function isIndeterminateReason(value: unknown): value is IndeterminateReason;
+export declare function isReconcileResolution(value: unknown): value is ReconcileResolution;
+/** One action key's latest execution cycle, and what may still be done with it. */
+export interface ExecutionCustody {
+    actionKey: string;
+    task: string | null;
+    state: CustodyState;
+    /** The `execution.started` record's timestamp, position and actor. */
+    ts: string;
+    seq: number;
+    actor: string;
+    /** The closing record's position: the outcome, or the reconciliation. */
+    closedSeq: number | null;
+    /** The `execution.indeterminate` record's position, when there is one. */
+    indeterminateSeq: number | null;
+    /** Its closed reason, when there is one. */
+    reason: IndeterminateReason | null;
+    /** What a reconciliation established, when `state` is `reconciled`. */
+    resolution: ReconcileResolution | null;
+}
+/** An execution that began and whose outcome the log does not know. */
+export interface DanglingExecution {
+    actionKey: string;
+    task: string | null;
+    /** The `execution.started` record's timestamp and position. */
+    ts: string;
+    seq: number;
+    actor: string;
+}
+/**
+ * The custody state of every started execution, in log order.
+ *
+ * Pure: no I/O, no clock. Per action key, only the **latest cycle** counts — a
+ * start followed by an outcome is closed, and a later start reopens the key.
+ * (The gate refuses a second start for a key anyway; this function does not
+ * assume that, because a projection that only works on well-formed logs is a
+ * projection that goes quiet exactly when something has gone wrong.)
+ */
+export declare function executionCustody(records: EventRecord[]): ExecutionCustody[];
+/**
+ * Executions that started, were meant to be watched, and never finished.
+ *
+ * This is the state a crash between `execution.started` and its outcome leaves
+ * behind, and it is reported as itself: not as completed, not as failed, not as
+ * clean. `approval status` lists it; `approval queue` does not, because nobody
+ * is being asked to decide anything.
+ *
+ * A `delegated` start is NOT here (APRV-120). The harness ran the command and
+ * this runtime never sees an exit status, so its record was never going to gain
+ * an outcome; listing it as debris says something false about a log that is
+ * exactly right.
+ */
+export declare function danglingExecutions(records: EventRecord[]): DanglingExecution[];
+/**
+ * Executions whose side effect was attempted and whose outcome nobody knows,
+ * and which no one has reconciled yet.
+ *
+ * Distinct from {@link danglingExecutions} in what it asks of a person. A
+ * dangling execution needs someone to look at what the runtime did; an
+ * indeterminate one needs someone to establish, from the relying party's own
+ * evidence, whether the effect happened at all. Both are debris and both make
+ * `approval status` unhealthy; only one of them is repaired with
+ * `execution resolve`.
+ */
+export declare function indeterminateExecutions(records: EventRecord[]): ExecutionCustody[];