approval-md 0.3.0 → 0.4.1

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,6 +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 { PromptRendering } from "./prompt-layout.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";
@@ -131,6 +135,30 @@ import { type ValidationError } from "./validate.js";
 export { requestState, type Decision, type DeclaredAction, type ExecutionFacts, type RequestDerivation, type RequestState, WITHDRAW_REASONS, isWithdrawReason, type WithdrawReason, } from "./state.js";
 /** Actor stamped on runtime-originated expiry events (SPEC.md §8 `system:`). */
 export declare const EXPIRY_ACTOR = "system:gate";
+/**
+ * Does an `approvers` list name this actor (APRV-137, amended SPEC.md §5.2)?
+ *
+ * The spelling a valid policy uses is the bare id (`alice`), which is what
+ * `policy.schema.json` admits and what the keys of the top-level `approvers`
+ * map are: its `identifier` pattern is lowercase alphanumerics with `_` and
+ * `-`, so a `human:` prefix inside a roster is a schema violation and never
+ * reaches here. The whole actor string is compared as well, which can only ever
+ * match a loader more permissive than the shipped schema; it widens nothing for
+ * a valid policy, because `alice` and `human:alice` are the same person under
+ * either comparison.
+ *
+ * Comparison is exact and case-sensitive. An identity that matched under
+ * folding would let `human:Alice` and `human:alice` be one approver on one host
+ * and two on another, and a roster is a list of people rather than a pattern
+ * language. An empty list names nobody and therefore matches nobody;
+ * `approvers` carries `minItems: 1`, so a valid policy cannot produce one, and
+ * that branch stays a fail-closed backstop rather than a reachable path.
+ *
+ * Exported for `core/audit.ts` (APRV-483), whose review check is this one
+ * comparison applied to a reviewer, so a grant and a review can never disagree
+ * about who is on a roster.
+ */
+export declare function namesApprover(approvers: readonly string[], actor: string): boolean;
 /**
  * The closed set of gate refusal codes. Agents branch on these, so the union is
  * frozen public API in the same sense the exit codes are: adding a code is a
@@ -497,7 +525,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 {
@@ -520,7 +592,12 @@ export interface GateRefusal {
     limits?: IntakeVerdict[];
     /** Schema errors, when `code` is `envelope-invalid`. */
     errors?: ValidationError[];
-    /** The underlying append error, when `code` is `append-failed`. */
+    /**
+     * The underlying append error, when `code` is `append-failed`; and, on a
+     * `budget-exceeded` from {@link startHarnessExecution}, the error that kept
+     * its `budget.exceeded` record out (APRV-478). Never present beside a
+     * `record`.
+     */
     append?: AppendError;
     /**
      * The two policy hashes actually compared, when `code` is `policy-drift`
@@ -639,6 +716,22 @@ type ReadOutcome = {
  * underneath it.
  */
 export declare function readGateRecords(logPath: string, schemaDir?: string): ReadOutcome;
+/**
+ * The policy file the gate will hash for attestation.
+ *
+ * `file` wins; otherwise discovery walks `POLICY_FILENAMES` in `dir` exactly as
+ * `loadPolicy` does, so the attested file and the enforced file are the same
+ * file. When neither exists the first candidate is returned anyway, so
+ * `checkAttestation` reports `unreadable` and the gate refuses — a missing
+ * policy is never a pass.
+ */
+/**
+ * The policy file a gate operation reads: `policy.file`, or the first policy
+ * filename found in `policy.dir` (default: the working directory). Exported for
+ * `core/audit.ts` (APRV-483), whose roster check must read the same file a
+ * grant would and hold it to the same attestation.
+ */
+export declare function policyPathOf(options: GateOptions): string;
 /**
  * The policy as a gate operation would load it: one read through the seam of
  * {@link GateOptions.policy}, parsed, failing closed (APRV-324).
@@ -731,7 +824,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 +907,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 +971,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
@@ -1032,6 +1170,17 @@ export interface DecideOptions extends GateOptions {
      * silently mixed in with policy-attested ones.
      */
     senderSource?: "policy";
+    /**
+     * Which prompt layout the approver decided on (APRV-489), recorded as
+     * `payload.rendering` on `approval.granted` / `approval.rejected` only.
+     *
+     * Set by a decision surface that drew a non-default layout, or that was asked
+     * for one and drew the technical card instead (then `fallback` names why).
+     * Absent under a technical policy, so those records are byte-identical to
+     * every earlier build's. A record of the screen and never an input: no check
+     * here or anywhere reads it back.
+     */
+    rendering?: PromptRendering;
 }
 export type DecideResult = {
     ok: true;
@@ -1090,6 +1239,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 +1330,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 +1617,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;