approval-md 0.2.0 → 0.4.0

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.
  *
@@ -116,7 +119,7 @@ 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 } from "./policy-load.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";
@@ -312,6 +315,27 @@ export declare const GATE_REFUSAL_CODES: readonly [
  * 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
@@ -476,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 {
@@ -618,6 +686,26 @@ type ReadOutcome = {
  * 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;
@@ -690,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.
  *
@@ -756,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).
@@ -801,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
@@ -947,6 +1080,50 @@ export interface DecideOptions extends GateOptions {
      * 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;
@@ -1005,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. */
@@ -1087,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).
@@ -1362,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;