approval-md 0.4.0 → 0.4.2

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

@@ -119,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";
@@ -134,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
@@ -567,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`
@@ -686,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).
@@ -780,6 +826,13 @@ export interface RegisterOptions extends GateOptions {
     harness?: HarnessProvenance;
     /** Set by `propose` alone: the `propose:` task namespace is its (APRV-445). */
     proposal?: true;
+    /**
+     * Set by the harness hook alone (APRV-499, claude-edge ruling): the one
+     * caller that may declare {@link UNMAPPED_TOOL_CLASS}. A CALL option for the
+     * reason `harness` is one: an envelope is authored by the party under
+     * oversight, and no CLI flag, task file or HTTP route sets this.
+     */
+    toolMapHook?: true;
 }
 /**
  * The `task.registered` record for `task`, or the `not-registered` refusal.
@@ -1124,6 +1177,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;
@@ -1318,6 +1382,16 @@ export interface ConsumeHarnessOptions extends GateOptions {
      * else, absence included, records `carried`.
      */
     spendingTask?: string;
+    /**
+     * The harness tool NAME of the call doing the spending, when its class came
+     * from the policy's tool mapping (APRV-499, refutation S3): written to the
+     * start as `harness_tool`, exactly as the policy-authorized start writes it,
+     * so every start a mapped or unmapped harness call produces names its tool.
+     * It authorizes nothing: the spend is bound by `presentedPayloadHash`, whose
+     * payload already carries the name, so a name that disagreed with the
+     * approved bytes would have been refused `payload-mismatch` first.
+     */
+    harnessTool?: string;
 }
 /**
  * How the authorization reached the process that spent it (APRV-200).
@@ -1452,53 +1526,20 @@ export interface HarnessStartInput {
     payload_hash?: string;
     /** Canonical decimal USD string (APRV-121); a JSON number is read as the historical form. */
     est_cost_usd?: UsdInput;
+    /**
+     * The harness tool NAME the start records, when the class came from the
+     * policy's tool mapping rather than from what the call does (APRV-499):
+     * a `tools` entry, or `harness.tool.unmapped`. Several tools share one
+     * such class, so the class alone cannot say which ran. The name and never the
+     * arguments: those are bound by `payload_hash` and stay out of the log.
+     * Shape-checked by the event schema at the write boundary.
+     */
+    harness_tool?: string;
 }
 export type HarnessStartResult = {
     ok: true;
     record: EventRecord;
 } | GateRefusal;
-/**
- * Charge and record a harness execution that no human was asked about
- * (APRV-141).
- *
- * ## The blind spot this closes
- *
- * `core/budgets.ts` computes consumption from `approval.granted` and
- * `execution.started`, and `core/audit.ts` draws its retrospective sample from
- * `execution.started` alone. The harness hook wrote neither for a supervised or
- * autonomous verdict — the comment said, correctly, that writing one per agent
- * action fills the log — so under Claude Code the majority of real activity
- * consumed no budget, `daily_actions` included, and was invisible to the
- * overseer that exists to read a sample of it. A budget that the busiest
- * execution path does not charge is not a budget, and the decision recorded on
- * APRV-141 is that the log volume is the lesser cost.
- *
- * ## Why this record and not a new event type
- *
- * It is the same `execution.started` {@link consumeHarnessGrant} appends, with
- * the same `execution: "harness"` marker saying why no `execution.completed` or
- * `execution.failed` will ever follow: the harness runs the command and this
- * runtime never observes an exit status. Reusing the shape means budgets and
- * audit count these without learning a second vocabulary, and the gate's
- * existing single-use rule (a key with an `execution.started` is
- * `already-executed`) applies unchanged. What differs is only the authorization
- * being recorded: there, a human's grant; here, the policy itself.
- *
- * ## What it refuses
- *
- * The same two facts the hook's own guard checks and `core/execute.ts` checks
- * before an unattended start — attestation and loop-escalation — re-checked at
- * the write boundary against the records this append is authorized by, plus the
- * budget verdict this record is the charge for. A class that resolves `manual`
- * is refused outright: a manual action is authorized by a grant and spent
- * through {@link consumeHarnessGrant} or a token, and admitting one here would
- * be a second, unapproved spender.
- *
- * Since APRV-146 the content binding is refused here too. `payload-hash-required`
- * says the caller named no bytes, and it is a refusal rather than an omitted
- * field because a start event with no `payload_hash` is a record that says
- * something ran without saying what — the state APRV-140 closed everywhere else.
- */
 export declare function startHarnessExecution(logPath: string, input: HarnessStartInput, actor: string, options?: GateOptions): HarnessStartResult;
 /**
  * Which untrusted reporter asserted a harness outcome. CLOSED, and extended only

package/dist/src/core/gate.js

@@ -116,6 +116,7 @@ import { basename, join } from "node:path";
 import { isPrincipalActor } from "./actor.js";
 import { ATTESTATION_REFUSAL, attestationRefusal, checkAttestationOfBytes, isPolicySha256, POLICY_HASH_FIELD, unreadablePolicyStatus, } from "./attest.js";
 import { evaluateBudgetsWithTask } from "./budgets.js";
+import { toolMapVerdict, UNMAPPED_TOOL_CLASS } from "./tool-map.js";
 import { evaluateIntakeLimits, intakeRefusalOf, } from "./intake-limits.js";
 import { tick } from "./clock.js";
 import { readTaskFile } from "./frontmatter.js";
@@ -135,6 +136,7 @@ import { payloadOf, readVerifiedRecords, requestState, } from "./state.js";
 import { mintToken, tokenHash, TOKEN_HASH_FIELD } from "./token.js";
 import { validate } from "./validate.js";
 import { displayHashOf, DISPLAY_HASH_FIELD } from "./wysiwys.js";
+import { HUMAN_ACTOR_RULE, reservedKindNote } from "./identity.js";
 /**
  * The approval-state derivation moved to `core/state.ts` in APRV-20 (finding
  * S4: `gate.ts` and `token.ts` imported each other). It is re-exported here, its
@@ -145,7 +147,7 @@ export { requestState, WITHDRAW_REASONS, isWithdrawReason, } from "./state.js";
 /** Actor stamped on runtime-originated expiry events (SPEC.md §8 `system:`). */
 export const EXPIRY_ACTOR = "system:gate";
 /** Actors permitted to decide. Human-only, in code (SPEC.md §10.1). */
-const HUMAN_ACTOR = /^human:.+/u;
+const HUMAN_ACTOR = HUMAN_ACTOR_RULE;
 /**
  * Does an `approvers` list name this actor (APRV-137, amended SPEC.md §5.2)?
  *
@@ -164,8 +166,12 @@ const HUMAN_ACTOR = /^human:.+/u;
  * 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.
  */
-function namesApprover(approvers, actor) {
+export function namesApprover(approvers, actor) {
     const bare = actor.startsWith("human:") ? actor.slice("human:".length) : actor;
     return approvers.some((name) => name === actor || name === bare);
 }
@@ -618,7 +624,13 @@ export function readGateRecords(logPath, schemaDir) {
  * `checkAttestation` reports `unreadable` and the gate refuses — a missing
  * policy is never a pass.
  */
-function policyPathOf(options) {
+/**
+ * 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 function policyPathOf(options) {
     const policy = options.policy ?? {};
     if (policy.file !== undefined)
         return policy.file;
@@ -985,6 +997,19 @@ function attemptRegister(logPath, source, actor, options) {
     if (!validation.ok) {
         return refuse("envelope-invalid", `the envelope failed schema validation; nothing was appended`, { errors: validation.errors });
     }
+    // APRV-499 (claude-edge ruling): `harness.tool.unmapped` is reserved to the
+    // harness hook, the way `harness.launch.*` is reserved to a rule. It names
+    // "a tool call no `tools` entry claimed", a fact only the hook establishes,
+    // and under `unmapped_tool: record` it resolves autonomous, so a task
+    // envelope, `approval propose` or an HTTP registration declaring it would be
+    // borrowing that autonomy for an action nobody classified. Refused before
+    // the log is read; nothing is appended.
+    if (options.toolMapHook !== true) {
+        const reserved = actionsOf(resolved.envelope).find((action) => action.class === UNMAPPED_TOOL_CLASS);
+        if (reserved !== undefined) {
+            return refuse("envelope-invalid", `action ${JSON.stringify(reserved.idempotency_key)} declares class ${UNMAPPED_TOOL_CLASS}, which is reserved to the harness hook: it names a tool call that no \`tools\` entry of the attested policy claimed, and only the hook observes that. Declare the action under the class that describes what it does. Nothing was appended.`);
+        }
+    }
     const read = readGateRecords(logPath);
     if (!read.ok)
         return read;
@@ -1418,6 +1443,17 @@ function attemptRequest(logPath, input, actor, options) {
     if (!isPrincipalActor(actor)) {
         return refuse("actor-invalid", `request requires a human: or agent: actor, got ${JSON.stringify(actor)}`);
     }
+    // APRV-499 fix round 2 (recheck SF2), the request-time half of the
+    // registration refusal above: `harness.tool.unmapped` is asked about only by
+    // the harness hook, and always as a harness request (`execution: "harness"`,
+    // which mints no token). A token-minting request on the class, which is what
+    // `approval request` makes after the hook's own question was withdrawn, would
+    // put a credential in front of a human that only `approval consume` could
+    // spend, and that path refuses it (`harness-executed`). Refused before the
+    // log is read; nothing is appended.
+    if (input.cls === UNMAPPED_TOOL_CLASS && input.execution !== "harness") {
+        return refuse("envelope-invalid", `action ${JSON.stringify(input.actionKey)} is declared under ${UNMAPPED_TOOL_CLASS}, which is reserved to the harness hook: only the hook asks about it, as a harness request that mints no token, and nothing else may request it. Nothing was appended.`);
+    }
     const read = readGateRecords(logPath);
     if (!read.ok)
         return read;
@@ -1944,7 +1980,7 @@ export function decide(logPath, actionKey, decision, actor, options = {}) {
 function attemptDecide(logPath, actionKey, decision, actor, options) {
     const ts = tick(options);
     if (!HUMAN_ACTOR.test(actor)) {
-        return refuse("actor-not-human", `${decision} is a human-only verb; the actor must match human:<id>, got ${JSON.stringify(actor)}`);
+        return refuse("actor-not-human", `${decision} is a human-only verb; the actor must match human:<id>, got ${JSON.stringify(actor)}${reservedKindNote(actor)}`);
     }
     // APRV-239, beside the actor check and before anything is read: whether a
     // grade came with words is a property of these arguments alone, so it is
@@ -2123,6 +2159,16 @@ function attemptDecide(logPath, actionKey, decision, actor, options) {
         if (options.senderSource !== undefined)
             payload["sender_source"] = options.senderSource;
     }
+    // APRV-489. Grant and reject only, the two answers a prompt collects, and only
+    // when the surface drew (or was asked for) a non-default layout. Copied in a
+    // fixed shape so nothing else a caller hangs on the object reaches the log.
+    if (decision !== "revoke" && options.rendering !== undefined) {
+        payload["rendering"] = {
+            style: options.rendering.style,
+            ...(options.rendering.fallback === undefined ? {} : { fallback: options.rendering.fallback }),
+            ...(options.rendering.say_does_ignored === true ? { say_does_ignored: true } : {}),
+        };
+    }
     if (decision === "grant") {
         const cls = derivation.declared.class ?? "";
         const resolution = resolve(load, cls, derivation.declared.reversible === null ? {} : { reversible: derivation.declared.reversible });
@@ -2873,6 +2919,9 @@ function attemptHarnessConsume(logPath, actionKey, actor, options) {
     }
     if (derivation.decisionSeq !== null)
         payload["grant_seq"] = derivation.decisionSeq;
+    // APRV-499 (refutation S3): which tool a mapped or unmapped spend was.
+    if (options.harnessTool !== undefined)
+        payload["harness_tool"] = options.harnessTool;
     const appended = append(logPath, {
         ts,
         event: "execution.started",
@@ -2931,6 +2980,40 @@ function attemptHarnessConsume(logPath, actionKey, actor, options) {
  * field because a start event with no `payload_hash` is a record that says
  * something ran without saying what — the state APRV-140 closed everywhere else.
  */
+/**
+ * Is the class this harness start names the one the ATTESTED policy's tool
+ * mapping gives its tool? (APRV-499, fix round 1.)
+ *
+ * The hook classifies an unclaimed tool call from a policy read of its own,
+ * and this function attests the bytes it reads itself, so between the two a
+ * file swap could have the hook classify under one mapping while the start is
+ * recorded under another. For every class that is a belt to braces (the
+ * resolution here is the attested one), but the class `harness.tool.unmapped`
+ * also decides whether `daily_actions` and the loop floor count the start
+ * (ruling H1), so the name and the class are checked against the attested
+ * mapping here, where the append happens: a start naming `harness_tool` must
+ * carry exactly the class that mapping gives that name, and a start of
+ * `harness.tool.unmapped` written without a name is an ordinary declared
+ * action, budgeted and counted like any other.
+ */
+function toolMapStartRefusal(load, input) {
+    if (input.harness_tool === undefined) {
+        // APRV-499 (claude-edge ruling): only the hook's record of a tool it names
+        // may use the reserved class.
+        if (input.cls !== UNMAPPED_TOOL_CLASS)
+            return null;
+        return refuse("not-granted", `class ${UNMAPPED_TOOL_CLASS} is reserved to the harness hook's record of a tool call it names (harness_tool), and the start of ${input.actionKey} names none; nothing authorizes it here and nothing was appended.`);
+    }
+    const verdict = load.ok ? toolMapVerdict(load.policy, input.harness_tool) : null;
+    const expected = verdict === null || verdict.kind === "not-gated"
+        ? null
+        : verdict.kind === "mapped"
+            ? verdict.cls
+            : UNMAPPED_TOOL_CLASS;
+    if (expected === input.cls)
+        return null;
+    return refuse(ATTESTATION_REFUSAL, `the start of ${input.actionKey} names harness tool ${JSON.stringify(input.harness_tool)} under class ${input.cls}, and the attested policy's tool mapping ${expected === null ? "does not gate that tool at all" : `gives it class ${expected}`}; the call was classified against policy bytes other than the attested ones, so nothing was appended. Retry once the policy file is the attested one (\`approval policy attest\` after an intended edit).`);
+}
 export function startHarnessExecution(logPath, input, actor, options = {}) {
     // APRV-150, and the writer the incident was reported against. This is the
     // busiest append in the system — one per class per gated tool call, most of
@@ -3021,8 +3104,24 @@ function attemptHarnessStart(logPath, input, actor, options) {
         if (refusal !== null)
             return refusal;
     }
+    // APRV-499 fix round 1: a start that names a harness tool is re-judged
+    // against the ATTESTED mapping, inside the attempt that appends. Before the
+    // budget verdict, which writes.
+    const mapped = toolMapStartRefusal(load, input);
+    if (mapped !== null)
+        return mapped;
     const cost = costOf(input.est_cost_usd);
-    const budget = evaluateBudgetsWithTask(read.records, budgetScopeOf(load, resolution), { class: input.cls, est_cost_usd: cost }, ts, input.task);
+    const budget = evaluateBudgetsWithTask(read.records, budgetScopeOf(load, resolution), {
+        class: input.cls,
+        est_cost_usd: cost,
+        // Ruling H1 (APRV-499): every start this function writes is authorized by
+        // the policy alone, so one of `harness.tool.unmapped` naming its tool
+        // (checked against the attested mapping above) is a record of
+        // unclassified tool use and is not charged to `daily_actions`.
+        ...(input.cls === UNMAPPED_TOOL_CLASS && input.harness_tool !== undefined
+            ? { recordOnly: true }
+            : {}),
+    }, ts, input.task);
     if (!budget.pass) {
         const failed = budget.verdicts.filter((verdict) => !verdict.pass);
         const logged = append(logPath, {
@@ -3043,7 +3142,14 @@ function attemptHarnessStart(logPath, input, actor, options) {
             .join(", ")}`;
         return logged.ok
             ? refuse("budget-exceeded", message, { verdicts: failed, record: logged.record })
-            : refuse("budget-exceeded", `${message}; the budget.exceeded event could not be appended: ${logged.message}`, { verdicts: failed });
+            : refuse("budget-exceeded", `${message}; the budget.exceeded event could not be appended: ${logged.message}`, 
+            // APRV-478: the writer's own error rides along, so a caller that
+            // waits for the log's lock on its event loop (the harness hook's
+            // `spendUnderLock`) can see that the evidence lost a lock race,
+            // re-run the whole attempt and give the record the same chance to
+            // land that a synchronous lock wait gave it. The verdict is the
+            // budget refusal either way.
+            logged.append === undefined ? { verdicts: failed } : { verdicts: failed, append: logged.append });
     }
     const payload = {
         // The budgets contract: class and est_cost_usd on every start event.
@@ -3059,6 +3165,8 @@ function attemptHarnessStart(logPath, input, actor, options) {
         // Without it a reader of a policy-authorized start had to reconstruct the
         // rules in force from the latest `policy.updated` before this seq.
         ...harnessStartPolicyStamp(attested.sha256),
+        // APRV-499: which tool a mapped or unmapped start was, by name only.
+        ...(input.harness_tool === undefined ? {} : { harness_tool: input.harness_tool }),
     };
     const appended = append(logPath, {
         ts,