approval-md 0.3.0 → 0.4.0

package/dist/src/core/daemon-identity.js

@@ -0,0 +1,252 @@
+/**
+ * WHICH daemon wrote this record, and the check the write boundary runs on it
+ * (APRV-383).
+ *
+ * ## The fact this module is about
+ *
+ * `core/daemon-actor.ts` answers "is this process the daemon". Every record the
+ * daemon appends carried that and nothing more: a generic `system:daemon` actor,
+ * one string, identical on every machine that ever ran one. That is enough while
+ * a gate's daemon is the operator's own process in the operator's own checkout,
+ * and it stops being enough the moment one party HOSTS a daemon for another.
+ * Three properties of that arrangement already hold: authority comes from the
+ * tenant's attested policy and never from the host (§5.2, APRV-324 and 356),
+ * credentials come from the launch environment so one process holds one tenant's
+ * token, and a decision arrives only through the tenant's own sender mapping so
+ * the host cannot mint one. What was missing is the smallest of the four and the
+ * one a tenant reads first: opening their own log and seeing which daemon acted
+ * on their behalf.
+ *
+ * So a daemon-written record carries a `daemon` field naming the instance that
+ * wrote it, and an attested policy MAY list the ids permitted to write
+ * (`daemons`, read by `core/daemon-host.ts`). An id the list does not name is
+ * refused at the write boundary.
+ *
+ * ## What the id is NOT, and this is the important half
+ *
+ * It is a SELF-REPORTED field, so SPEC.md §11.1 invariant 4 governs it
+ * completely: it may raise scrutiny and may never lower it. Concretely, in this
+ * runtime:
+ *
+ * - a listed id gains NOTHING. No verdict, no autonomy, no budget, no floor, no
+ *   sampling draw, no token and no TTL reads this field or the list. Being named
+ *   in `daemons` buys a daemon exactly the ability it had before the key existed;
+ * - an unlisted id is REFUSED, which is the only direction the field moves
+ *   anything, and it moves it strictly towards writing less;
+ * - the id never enters a payload hash and never enters a token. It is a
+ *   top-level record field, so the record's own chain hash covers it the way it
+ *   covers `actor` (a record's provenance has to be part of what the chain
+ *   protects, or it could be edited without breaking the chain), and no bound
+ *   payload, no `payload_hash` and no `token_sha256` is computed over it.
+ *
+ * And it is ATTRIBUTION rather than authorization. A hostile host process holds
+ * the tenant's log handle and can call anything in this module the daemon calls,
+ * exactly as it can call {@link markDaemonProcess}; `core/daemon-actor.ts` states
+ * that boundary and this module inherits it word for word. What the allowlist
+ * catches is the likelier failure and the one nothing caught before: a daemon
+ * started against the wrong tenant's log, a second daemon nobody meant to leave
+ * running, a container rebuilt with a new id, each of which used to write records
+ * indistinguishable from the intended daemon's.
+ *
+ * ## Why the state is module state and not an argument
+ *
+ * For the reason `core/daemon-actor.ts` gives for taking no arguments: a field a
+ * caller passes is a field a caller chooses, and an `appendEvent` option naming
+ * the writing daemon would let any process in this runtime claim to be one. The
+ * daemon runtime declares its own identity once, at construction, through
+ * `core/daemon-host.ts`, and `core/log.ts` READS it. `EventInput` deliberately
+ * has no `daemon` member, and `buildRecord` composes a record field by field, so
+ * a caller that puts the property on its input object anyway is ignored rather
+ * than obeyed.
+ *
+ * ## Which processes declare, and why the stamp does not ask for the mark
+ *
+ * Three processes append on a gate's behalf without being a session, and since
+ * APRV-448 all three declare the same identity through the same two calls in
+ * `core/daemon-host.ts` (`declareDaemonIdentityFor` or
+ * `declareResolvedDaemonIdentity`, then `refreshDaemonAllowlist*`): the daemon
+ * loop (`daemon/daemon.ts`, at construction), `approval serve` (its verbs on the
+ * listener's thread and its hook calls on their worker threads), and `approval
+ * channel telegram webhook`. In a co-located deployment, where a facade, a
+ * daemon and a channel run in one process per tenant, a tenant reading their
+ * own log therefore sees one id on the sweeps and on the actions.
+ *
+ * The stamp is keyed on the DECLARATION, not on `core/daemon-actor.ts`'s mark.
+ * The two answer different questions: the mark says "this process is the daemon
+ * loop" and is what routes an advance under the autonomous
+ * `log.advance.daemon` class (APRV-382), while the declaration says "records
+ * this process writes name this instance". `approval serve` dispatches verbs an
+ * agent asked for, so marking it the daemon to get the stamp would hand its
+ * process the daemon's advance route, a widening nothing here needs. Declaring
+ * without marking stamps and restricts, and widens nothing.
+ *
+ * ## Why this module imports almost nothing
+ *
+ * `core/log.ts` imports it, and `core/log.ts` is the bottom of this codebase's
+ * import graph: `core/instance.ts` (where the derived id comes from) reaches
+ * `core/attest.ts` through `core/env-file.ts`, and `core/attest.ts` spreads
+ * `APPEND_ERROR_CODES` at module scope, so importing the
+ * derivation here would close a cycle whose evaluation order throws before any
+ * test ran. The split is also the right seam on its own terms: what the write
+ * boundary needs is a grammar, a state and one question, and everything that
+ * reads a policy or a filesystem to ANSWER that question lives in
+ * `core/daemon-host.ts`.
+ */
+/**
+ * The environment variable a launch may declare the daemon's id in.
+ *
+ * Beside `APPROVAL_HUMAN` and the credential variables, and in the launch
+ * environment for the same reason they are: SPEC.md §11.1 invariant 7 keeps this
+ * runtime from reading configuration out of the working tree, and a hosted
+ * daemon's id is configuration its OPERATOR sets, never something the tenant's
+ * repository tells the host about itself.
+ */
+export const DAEMON_ID_ENV = "APPROVAL_DAEMON_ID";
+/** The longest id this runtime writes or admits. */
+export const DAEMON_ID_MAX_LENGTH = 64;
+/**
+ * The shape an id takes: lowercase alphanumerics, dots, dashes and underscores,
+ * starting with an alphanumeric.
+ *
+ * Narrow on purpose, and for the reason `payload.harness_version` is narrow
+ * (APRV-227): the value is a string from a launch environment being written into
+ * an append-only log, so a banner, a path, a newline or a shell fragment must not
+ * be able to arrive through it. It is also a value an operator COMPARES by eye
+ * against `approval doctor` and against the `daemons` list in their policy, and
+ * two ids differing only in case are two ids nobody can tell apart on a phone.
+ */
+const DAEMON_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/u;
+/** Is `value` a well-formed daemon id? */
+export function isDaemonId(value) {
+    return value.length <= DAEMON_ID_MAX_LENGTH && DAEMON_ID_PATTERN.test(value);
+}
+/**
+ * The two ways an append can be refused for the identity of the daemon making
+ * it, spread into `APPEND_ERROR_CODES` by `core/log.ts`.
+ *
+ * Two codes rather than one, because the repairs have nothing in common and
+ * SPEC.md §11.1 invariant 6 is about a caller being able to act on the answer:
+ * one is a line to add to an attested policy, the other is a variable to fix in
+ * the launch environment of a process that should not have started.
+ *
+ * Declared here rather than in `core/log.ts`'s literal list so that the codes and
+ * the logic that emits them cannot drift apart; the union there spreads this one,
+ * exactly as `ATTEST_ERROR_CODES` spreads it.
+ */
+export const DAEMON_APPEND_REFUSAL_CODES = [
+    /**
+     * The daemon declared an id through {@link DAEMON_ID_ENV} that is not a
+     * well-formed id at all, so no record it wrote could be attributed to anything.
+     *
+     * Refused rather than silently falling back to the derived id, which is the
+     * fail-closed direction twice over: an operator who set the variable meant the
+     * value they set, and a runtime that quietly used a different one would write
+     * records under a name nobody chose, against an allowlist nobody wrote for it.
+     */
+    "daemon-id-invalid",
+    /**
+     * The attested policy lists the daemon ids that may write to this log, and this
+     * daemon's id is not among them.
+     *
+     * An ABSENT list is no restriction, not an empty one: a policy that never
+     * declares the key behaves exactly as every policy written before it existed.
+     */
+    "daemon-not-allowed",
+];
+/** The declaring process's own state. Never set on another process's behalf. */
+let identity = null;
+/**
+ * The pid that made the declaration, for the reason `core/daemon-actor.ts` keeps
+ * one: the stamp answers only while it is still this process's own. Kept beside
+ * {@link identity} rather than inside it, so the reported state is unchanged.
+ */
+let declaredPid = null;
+/**
+ * Declare the id this process's records carry. Called through
+ * `core/daemon-host.ts` by the processes the header names (the daemon loop,
+ * `approval serve` and its hook threads, the Telegram webhook listener), and by
+ * nothing else.
+ *
+ * Takes the RESOLVED values rather than resolving them, because resolution reads
+ * the environment and the filesystem and this module is the one `core/log.ts`
+ * imports (see the header). Idempotent, and a second call replaces the first: a
+ * runtime that re-resolves its identity is reporting a fact about itself, and the
+ * newest reading is the one in force.
+ */
+export function declareDaemonIdentity(state) {
+    identity = {
+        id: state.id,
+        declared: state.declared ?? null,
+        source: state.source,
+        // A fresh declaration carries no allowlist. The daemon resolves one from its
+        // attested policy and sets it separately, so an identity re-declared mid-run
+        // cannot silently drop a restriction that was in force.
+        allowed: identity === null ? null : identity.allowed,
+    };
+    declaredPid = process.pid;
+}
+/**
+ * Record which daemon ids this log's ATTESTED policy admits.
+ *
+ * Called only after a successful resolution: the daemon loaded its policy, read
+ * the verified log, and the attestation matched (`core/daemon-host.ts`). A
+ * resolution that FAILED calls nothing, so the restriction last resolved stays in
+ * force rather than lapsing — a policy that becomes unreadable must not be a way
+ * to escape the list it carried a moment ago.
+ *
+ * `null` means the attested policy declares none, which is no restriction.
+ */
+export function setDaemonAllowlist(allowed) {
+    if (identity === null)
+        return;
+    identity = { ...identity, allowed: allowed === null ? null : [...allowed] };
+}
+/** Forget the declaration. For tests, and for a runtime that stops being one. */
+export function clearDaemonIdentity() {
+    identity = null;
+    declaredPid = null;
+}
+/** What this process has declared about itself, or `null`. */
+export function daemonIdentity() {
+    return identity;
+}
+/**
+ * The write boundary's question, answered from this process's own state
+ * (APRV-383).
+ *
+ * Both halves of the answer are here rather than in two functions, because they
+ * are one decision made in one order: a process that cannot name itself is
+ * refused before anything asks whether its name is allowed.
+ *
+ * A process that declared NO identity gets `absent`, whether or not it marked
+ * itself the daemon. That is every session, every hook process and the
+ * pre-APRV-383 daemon, and the records they write are the records they always
+ * wrote; turning an undeclared mark into a dead log would make an unrelated
+ * module's `markDaemonProcess` call a stop-the-world bug. The answer is keyed on
+ * the declaration alone (APRV-448, see the header): the daemon loop marks and
+ * declares together, while `approval serve` and the webhook listener declare
+ * without marking, because the mark carries the daemon's advance route and the
+ * declaration carries nothing but a name and a restriction.
+ */
+export function daemonStampForAppend() {
+    const state = identity;
+    if (state === null || declaredPid !== process.pid)
+        return { kind: "absent" };
+    if (state.id === null) {
+        return {
+            kind: "refuse",
+            code: "daemon-id-invalid",
+            message: `this daemon declared ${DAEMON_ID_ENV}=${JSON.stringify(state.declared ?? "")}, which is not a usable daemon id (lowercase letters, digits, \`.\`, \`-\` and \`_\`, starting with a letter or digit, at most ${String(DAEMON_ID_MAX_LENGTH)} characters), so no record it wrote could name which daemon wrote it. Nothing was written: fix ${DAEMON_ID_ENV} in this process's launch environment, or unset it and let the id derive from this instance`,
+        };
+    }
+    const allowed = state.allowed;
+    if (allowed !== null && !allowed.includes(state.id)) {
+        return {
+            kind: "refuse",
+            code: "daemon-not-allowed",
+            message: `this daemon's id is ${state.id} and the attested policy's \`daemons\` list admits ${allowed.length === 0 ? "no daemon at all" : allowed.join(", ")}, so it may not write to this log. Nothing was written: add ${state.id} to \`daemons\` and re-attest the policy, or run the daemon whose id the list already names`,
+        };
+    }
+    return { kind: "stamp", id: state.id };
+}
+//# sourceMappingURL=daemon-identity.js.map

package/dist/src/core/daemon-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-identity.js","sourceRoot":"","sources":["../../../src/core/daemon-identity.ts"],"names":[],"mappings":"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"}

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

@@ -37,9 +37,12 @@
  *
  * ## 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.
+ * A request expires when `ts > requestTs + effective window`, **whether or
+ * not** an `approval.expired` event exists. The effective window is
+ * `defaults.approval_ttl`, narrowed since APRV-423 by whatever harness ceiling
+ * the requesting hook declared on `payload.harness_cap_ms` (a self-reported
+ * bound that can only shorten; see `core/harness-wait.ts`). 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.
  *
@@ -497,7 +500,51 @@ export declare const GATE_REFUSAL_CODES: readonly [
  * 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"];
+"token-delivery-unavailable", 
+/**
+ * `approval propose` named a class the policy has not opened to agents
+ * (APRV-445, amended SPEC.md §5.2): the class is not an exact key of
+ * `policy.classes`, or neither that key nor a declared `<prefix>.*` family of
+ * it sets `agent_may_request: true`. Nothing is registered and nothing is
+ * appended. The repair is the operator's, a policy edit and a re-attestation;
+ * no retry by the agent changes it.
+ */
+"class-not-agent-requestable", 
+/**
+ * `approval propose` / `approval start` carried a payload larger than
+ * {@link PROPOSE_PAYLOAD_MAX_BYTES} (APRV-445). Refused before the bytes are
+ * parsed or hashed; nothing is stored and nothing is appended.
+ */
+"payload-too-large", 
+/**
+ * `approval request` (or a task FILE's registration) named a `propose:` task
+ * (APRV-445 refutation, S1). A proposal is requested only through `propose`,
+ * which re-checks the operator's opening of its class; a plain request on the
+ * same task would skip that check, and a file-registered `propose:` id would
+ * borrow the exclusions proposals get from the harness hook.
+ */
+"task-is-proposal", 
+/**
+ * `approval start` named a task `propose` did not register (APRV-445, L9).
+ * `start` records executions of proposals and of nothing else; every other
+ * action executes through `approval run`, an adapter, or the hook.
+ */
+"task-not-proposal", 
+/**
+ * `approval propose --key` does not begin with `<class>:` (APRV-445, S4). The
+ * key names the class it was proposed under, so a key cannot be read back
+ * later as belonging to a different class than its record says.
+ */
+"key-class-mismatch", 
+/**
+ * `approval propose` found the log moving under it on every one of its
+ * bounded attempts (APRV-445 recheck 3): each re-read showed an answer the
+ * next append was refused for. Exit 1, nothing more was appended, and the
+ * proposal's standing is whatever the log now says; read it with `wait
+ * --timeout 0` or call again. Distinct from `already-decided`, which would
+ * tell a caller a proposal is answered when it may stand granted or pending.
+ */
+"contended"];
 export type GateRefusalCode = (typeof GATE_REFUSAL_CODES)[number];
 /** Every gate failure is one of these. Nothing here throws. */
 export interface GateRefusal {
@@ -731,7 +778,24 @@ export declare function register(logPath: string, source: RegisterSource, actor:
  */
 export interface RegisterOptions extends GateOptions {
     harness?: HarnessProvenance;
+    /** Set by `propose` alone: the `propose:` task namespace is its (APRV-445). */
+    proposal?: true;
 }
+/**
+ * The `task.registered` record for `task`, or the `not-registered` refusal.
+ *
+ * The one raise site for SPEC.md §11.2's `not-registered` ("no task.registered
+ * record exists for the task id"). `request` reaches it through
+ * {@link registeredAction}; `approval wait` calls it directly (APRV-428), so a
+ * wait on a task the log has never seen is refused in the same words rather
+ * than answered as a vacuous grant. The latest registration wins, as it always
+ * has for `registeredAction`; the register path refuses a second one, so a log
+ * carrying two was written by something else.
+ */
+export declare function taskRegistration(records: EventRecord[], task: string): {
+    ok: true;
+    record: EventRecord;
+} | GateRefusal;
 /**
  * The declared action for `(task, actionKey)`, as registered in the log.
  *
@@ -797,6 +861,25 @@ export interface RequestInput {
      * policy's `defaults.approval_ttl` remains the only deadline with authority.
      */
     wait_until?: string;
+    /**
+     * The ceiling the requesting harness imposes on the hook process that is
+     * asking, in milliseconds (APRV-423).
+     *
+     * Recorded as `payload.harness_cap_ms` and read back by `core/state.ts`,
+     * which judges the request against the SHORTER of this minus a fixed margin
+     * and the policy's own `defaults.approval_ttl`. It is the answer to APRV-410:
+     * a harness that kills the hook while the question is still on a phone turns
+     * the tap that follows into a grant on a call nobody holds, so the question
+     * is made to end first and both records say the same thing.
+     *
+     * Claimed, and structurally unable to reduce scrutiny (SPEC.md §11.1
+     * invariant 4): the runtime takes a MINIMUM, so an overstated cap changes
+     * nothing and an understated one only shortens the claimant's own window.
+     * The write boundary constrains it to a positive integer on a request that
+     * also declares `execution: "harness"` — a cap on a token-minting request
+     * would be a question with a shorter life than the authorization it mints.
+     */
+    harnessCapMs?: number;
     /**
      * The caller has established that loop safety floors this action to `manual`
      * for this invocation (APRV-145, amended SPEC.md §10.2).
@@ -842,6 +925,15 @@ export interface RequestInput {
      * spend a human's decision on an authorization that can never execute.
      */
     delivery?: "self";
+    /**
+     * This request was opened by `approval propose`, whose caller named the class
+     * itself (APRV-445). When set, intake re-checks `agentRequestability` against
+     * the policy bytes THIS attempt read, inside the retried read-check-append
+     * cycle, so a re-attestation between `propose`'s own check and the append
+     * cannot admit a class the policy no longer opens to agents (SPEC.md §11.1
+     * invariant 5). It only ever adds a refusal.
+     */
+    agentProposal?: true;
 }
 /**
  * Why a `supervised-live` action was, or was not, sent to the human gate
@@ -1090,6 +1182,15 @@ export type DecideResult = {
  */
 export declare function decide(logPath: string, actionKey: string, decision: Decision, actor: string, options?: DecideOptions): DecideResult;
 export interface WithdrawOptions extends GateOptions {
+    /**
+     * Withdraw only a pending request that is VOID at the moment of the append
+     * (APRV-445 recheck, SF1): pinned to a policy hash that is no longer the
+     * attested one. Judged inside the retried read-check-append cycle, so a
+     * caller acting on a stale reading cannot retract a question a concurrent
+     * caller has just re-asked under the policy in force. A live, non-void
+     * request refuses `duplicate-request`.
+     */
+    onlyIfVoid?: true;
     /** Why the requester is retracting. Defaults to `cancelled`. */
     reason?: WithdrawReason;
     /** The requester's free-text elaboration, recorded in the payload. */
@@ -1172,7 +1273,19 @@ export interface HarnessCarry {
     /** `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;
+export declare function findHarnessCarry(records: EventRecord[], payloadHash: string, cls: string, ts: string, ttlMs: number | null, 
+/**
+ * How long a question of this caller's outlives the wait that opened it
+ * (APRV-410, `core/harness-wait.ts`'s `abandonedAfterMs`), or `null` for a
+ * caller that declares no such window.
+ *
+ * Only a GRANTED candidate is bounded by it. A pending one is the question
+ * this invocation is about to adopt, and the withdrawal of an abandoned
+ * pending question is the requester's own business, not this function's:
+ * `cli/hook.ts` sweeps those through `withdraw`, which is requester-only by
+ * design (APRV-106 rule 1).
+ */
+abandonAfterMs?: number | null): HarnessCarry | null;
 /**
  * `GateOptions` plus the one thing a harness spend states about itself
  * (APRV-146).
@@ -1447,3 +1560,191 @@ export type ExpireResult = {
  * as `rejected`.
  */
 export declare function expire(logPath: string, actionKey: string, options?: GateOptions): ExpireResult;
+/**
+ * The largest payload `approval propose` and `approval start` accept, in UTF-8
+ * bytes of the JSON text as the caller sent it: 256 KiB.
+ *
+ * Well under `approval serve`'s 1 MiB body cap, so the refusal a caller meets is
+ * this named one rather than a transport's. A proposal is a sentence or a
+ * paragraph a human will read on a phone; a payload this size is not one.
+ */
+export declare const PROPOSE_PAYLOAD_MAX_BYTES: number;
+/** The longest `--key` `propose` accepts, in UTF-8 bytes (APRV-445, L6). */
+export declare const PROPOSE_KEY_MAX_BYTES = 1024;
+/** The longest `--summary` `propose` accepts, in UTF-8 bytes (APRV-445, L6). */
+export declare const PROPOSE_SUMMARY_MAX_BYTES = 4096;
+/** `origin.app` on every envelope `propose` registers. */
+export declare const PROPOSE_ORIGIN_APP = "approval-propose";
+/** The task-id prefix `propose` derives under. */
+export declare const PROPOSE_TASK_PREFIX = "propose:";
+/**
+ * Was this task registered by `propose` (APRV-445)?
+ *
+ * A proposal's request carries `execution: "harness"` like a hook's, so the two
+ * hook-side readers of that marker (the carry and the abandoned-question sweep)
+ * ask this first: a proposal waits days for a human, is spent only by `start`,
+ * and is withdrawn only by its requester's own call.
+ */
+export declare function isProposalTask(task: unknown): boolean;
+/**
+ * The task id `propose` registers under, from who is asking, the class and the
+ * key: `propose:` and the first 32 hex digits of the SHA-256 over the RFC 8785
+ * canonical JSON of `[actor, class, key]`.
+ *
+ * Deterministic, so a retry lands on the task its first attempt registered and
+ * is recognised as a retry. The ACTOR is the tenant half of the derivation: one
+ * `approval serve` process serves one store as one fixed `agent:<id>`, so within
+ * a store the actor is who the tenant's agent is, and two actors proposing the
+ * same key derive two different tasks, the second of which `register` refuses
+ * because the key is already declared under the first (`task-already-registered`).
+ * The class is in it so that the same key proposed under a second class is a
+ * different task rather than a silent re-declaration.
+ */
+export declare function proposedTaskId(actor: string, cls: string, actionKey: string): string;
+/** What an agent proposes. The payload is a parsed JSON object. */
+export interface ProposeInput {
+    cls: string;
+    actionKey: string;
+    summary: string;
+    payload: unknown;
+}
+/**
+ * How a proposal stands after the call.
+ *
+ * `decision` is what the caller branches on: `requested` means a human is (or
+ * was) asked and `state` says where that stands; `autonomous` and `supervised`
+ * mean the policy itself authorizes the action, nothing was put in front of a
+ * human, and the caller proceeds and records the execution with `approval start`.
+ *
+ * `idempotent` is true exactly when this call appended nothing: a retry of a
+ * proposal whose registration (and, on the manual path, whose request) already
+ * stands under the same class, key and payload hash.
+ */
+export type ProposeResult = {
+    ok: true;
+    task: string;
+    actionKey: string;
+    cls: string;
+    payloadHash: string;
+    decision: "requested" | "autonomous" | "supervised";
+    /**
+     * `null` off the manual path, where there is no request to be in a state;
+     * `executed` once `start` recorded the execution (APRV-445, L7).
+     */
+    state: RequestState | "executed" | null;
+    seq: number | null;
+    idempotent: boolean;
+} | GateRefusal;
+/**
+ * `approval propose` (APRV-445, amended SPEC.md §5.2): register and request one
+ * action in one call, for a requester that holds the payload inline and no file
+ * on the gate's machine.
+ *
+ * ## Why this verb may name its class when `request` may not
+ *
+ * `approval request` reads the class from the log's `task.registered` record so
+ * that an agent cannot call a `financial.spend` a `read.web`. Here the agent is
+ * also the registrant, so that rule alone would prove nothing, and the bound is
+ * the operator's instead: the class must be an EXACT key of `policy.classes`, and
+ * that key or a declared `<prefix>.*` family of it must say
+ * `agent_may_request: true`. A class reached only through a wildcard is refused,
+ * so the set of classes an agent can propose in is a set of lines the operator
+ * wrote and attested by name. What the agent chooses among them is still its own
+ * statement (SPEC.md §11.1 invariant 4 is why the choice is bounded at all), and
+ * an operator opening two classes of different autonomy to agents is trusting
+ * the agent to pick the right one; the record names the class it picked.
+ *
+ * ## Order
+ *
+ * Attestation, then the agent-requestability gate and the class's own autonomy
+ * (`human-only`, an unruled `harness.launch.*`), all BEFORE anything is
+ * registered, so a refused class leaves no registration behind. Then the
+ * registration, then {@link request} with `agentProposal: true`, which repeats
+ * the gate against the bytes its own attempt reads. `execution: "harness"` on the
+ * request: nothing ever presents a token for a proposal, the requester proceeds
+ * on the grant itself and records that with `approval start`, so a minted token
+ * would be a live credential with no spender.
+ *
+ * ## Idempotency
+ *
+ * The task id is {@link proposedTaskId}. A second call with the same actor,
+ * class, key and payload hash finds its own registration and appends nothing
+ * while the request is live or decided, answering with the request's state and
+ * `idempotent: true`. A withdrawn or expired request (a re-attestation voids
+ * pending requests as `policy-drift`) is asked again under the same registration.
+ * The same key with DIFFERENT bytes refuses: `duplicate-request` while a request
+ * is live, `payload-mismatch` otherwise, because a key is bound to the bytes it
+ * was first registered with and new bytes need a new key.
+ */
+export declare function propose(logPath: string, input: ProposeInput, actor: string, options?: GateOptions, attempt?: number, appendedEarlier?: boolean): ProposeResult;
+export type StartProposedResult = {
+    ok: true;
+    task: string;
+    actionKey: string;
+    cls: string;
+    /** `grant` when a human's harness grant was spent; `policy` when the policy authorized it. */
+    authorization: "grant" | "policy";
+    record: EventRecord;
+} | GateRefusal;
+/**
+ * `approval start <task> --action <key> --payload-json <json>` (APRV-445): record
+ * the `execution.started` for an action its requester is about to carry out
+ * itself, outside any harness hook.
+ *
+ * Until this verb an agent holding only the serve agent credential could ask and
+ * wait, and could not say that it then acted: `approval run` spawns argv on the
+ * gate's machine, and the harness hook writes starts only for tool calls it
+ * classified. A proposal the policy authorizes outright (`autonomous`,
+ * `supervised`) therefore left no record at all, and one a human granted left a
+ * grant nobody spent, so a second publication of the same key was indistinguishable
+ * from the first.
+ *
+ * It adds no authority. It writes through the two existing spenders and through
+ * nothing else: {@link consumeHarnessGrant} when the key carries a request (it
+ * refuses unless that request is granted, unexpired, harness-executed and
+ * unspent, under the policy it was asked under), and {@link startHarnessExecution}
+ * when it carries none (it refuses a `manual` or `human-only` class, an escalated
+ * loop and a spent key, and charges the budgets). Both pin the single-use rule:
+ * a second start of one key is `already-executed`.
+ *
+ * Two checks of its own, both before either spender runs. REQUESTER-ONLY: the
+ * actor must be the one that registered the task (`not-requester` otherwise), as
+ * `withdraw` is, so an agent cannot spend or exhaust a key someone else declared.
+ * And the bytes: the caller presents the payload it is about to act on, and its
+ * hash must equal the registered `payload_hash` (`payload-mismatch` otherwise),
+ * so the thing done is the thing that was approved, which the grant path checks
+ * again against the grant's own binding.
+ */
+export declare function startProposed(logPath: string, task: string, actionKey: string, payload: unknown, actor: string, options?: GateOptions): StartProposedResult;
+/**
+ * A request's state as a waiter must read it (APRV-445 refutation, B1).
+ *
+ * `requestState` answers what the log RECORDED. A waiter needs what the record
+ * still AUTHORIZES, and the two part in three ways the gate already enforces
+ * at the spend and the decision but no reader was told about:
+ *
+ * - a GRANT whose request has lapsed its window is `expired`: there is no
+ *   separate grant TTL (`grantLapsed`), so a tap at hour 71 of a 72 h window
+ *   authorizes nothing at hour 73;
+ * - a PENDING request pinned to a policy hash that is no longer the attested
+ *   one is `void` for every task, because the decision refuses `policy-drift`;
+ *   a GRANT is `void` on the same condition only where its spend enforces the
+ *   same refusal: a harness grant (`execution: "harness"`), which includes
+ *   every proposal. A token grant spent through `approval run` stays `granted`;
+ * - a request the runtime withdrew for `policy-drift` (APRV-235) is `void` too,
+ *   for the same reason, rather than an ordinary requester `withdrawn`;
+ * - a key whose execution started is `executed`.
+ *
+ * `void` and `expired` both mean "ask again": the question as asked can no
+ * longer be answered usefully. Everything else is `requestState` verbatim. An
+ * unattested policy (`attestedSha256` null) voids nothing, because that state is
+ * the human's to repair and may end in the same bytes.
+ */
+export type RequestStanding = RequestState | "void" | "executed";
+export declare function requestStanding(records: EventRecord[], actionKey: string, ts: string, ttlMs: number | null, attestedSha256: string | null): RequestStanding;
+/**
+ * The SHA-256 the live policy bytes are attested under, or `null` when they are
+ * not attested (unread, unattested, or changed since). One read of the file
+ * through the same seam every gate operation uses.
+ */
+export declare function attestedPolicySha256(records: EventRecord[], options?: GateOptions): string | null;