approval-md 0.1.0 → 0.2.0

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

@@ -0,0 +1,238 @@
+/**
+ * Budget evaluation from the log (SPEC.md §5.2, §8).
+ *
+ * "An action must pass its class limits AND global budgets. Budget consumption
+ * is computed from the log, never from a mutable counter." This module is that
+ * computation: given the records of the append-only log, the limits the policy
+ * matcher already resolved, the action about to be admitted, and the moment of
+ * evaluation, it returns a per-limit verdict and one conjunctive answer.
+ *
+ * Pure and deterministic: no I/O, no clock, no randomness, no caching. The
+ * evaluation timestamp is a **required parameter** — a budget decision that
+ * depended on ambient time could not be replayed from the log, and replay is
+ * the whole point of computing consumption from the log in the first place.
+ * This module also does not re-run class matching: the gate hands in the
+ * already-matched limits and the pattern that produced them.
+ *
+ * ## THE CONSUMPTION CONTRACT — what APRV-16 (the gate) MUST honor
+ *
+ * Budgets meter **authorization**, not completion. An authorized action
+ * consumes budget whether or not it ultimately executes, because the human's
+ * decision is the commitment; a runtime that only charged completed actions
+ * would let a crashed or hung executor mint unlimited authorizations.
+ *
+ * The evaluator therefore reads consumption from exactly two event types, and
+ * the gate MUST write them accordingly:
+ *
+ * 1. `approval.granted` — the manual path. A human said yes; budget is spent.
+ * 2. `execution.started` — the supervised/autonomous paths. Under the amended
+ *    §6.3 those paths emit no approval events, so the record that authorizes
+ *    execution *is* the start event.
+ *
+ * To avoid charging a manual action twice (granted, then started), an
+ * `execution.started` is counted only when the window contains no
+ * `approval.granted` bearing the same `action_key`.
+ *
+ * **The gate MUST record `payload.est_cost_usd` (a decimal USD string since
+ * APRV-121, a JSON number in records written before it) and
+ * `payload.class` (the action's dotted class string) on every
+ * `approval.granted` and `execution.started` event it appends.** Those two
+ * payload fields are the entire input to USD accounting and class scoping.
+ * A consuming event with no usable `est_cost_usd` contributes **0** to USD
+ * sums but still counts as **1** action for `daily_actions` — an authorization
+ * with no declared cost is still an authorization. A consuming event with no
+ * usable `payload.class` is invisible to class-scoped limits (it cannot be
+ * shown to belong to the class) but is still counted by global budgets, which
+ * charge every authorization regardless of class.
+ *
+ * Nothing else consumes. `approval.rejected`, `approval.expired`,
+ * `approval.revoked`, and `approval.withdrawn` (APRV-106) consume nothing: an
+ * authorization that was refused, lapsed, or never asked for in the end was
+ * never a commitment. `execution.completed` and `execution.failed`
+ * consume nothing either — they report on a commitment already charged at
+ * authorization time, and charging them again would double-count.
+ *
+ * ## The rolling window (SPEC.md §5.2, rolling-window amendment)
+ *
+ * A `daily` limit is evaluated over the 24 hours preceding the evaluation
+ * moment, not over a calendar day. An event consumes iff
+ *
+ *     evaluationTs - 24h  <  event.ts  <=  evaluationTs
+ *
+ * — half-open at the bottom, closed at the top. An event exactly 24h old has
+ * aged out; an event stamped at the evaluation instant is in. The bound is
+ * half-open on exactly one side so that consecutive 24h windows tile the
+ * timeline without double-counting a boundary event. Timestamps are compared
+ * via `Date.parse` on the RFC 3339 strings the schema already guarantees.
+ *
+ * Rolling, not calendar: a burst that straddles midnight must not have its own
+ * tripwire reset underneath it.
+ *
+ * ## Fail-closed
+ *
+ * A limit the evaluator does not understand cannot be proven satisfied, so it
+ * fails: an unknown limit name yields `pass: false` with an explanatory `note`.
+ * The same applies to an unparseable evaluation timestamp (no window can be
+ * computed) and to class-scoped rolling limits offered without the class
+ * pattern that scopes their consumption. Silence is never a grant.
+ *
+ * ## What this module does NOT evaluate (APRV-173)
+ *
+ * `max_pending` and `requests_per_hour` (SPEC.md §5.2) are request-volume
+ * limits: they cap the approver's queue rather than the world's exposure, they
+ * are counted from `approval.requested` rather than from authorizations, and
+ * `core/intake-limits.ts` evaluates them at intake. They are skipped by name
+ * here rather than refused as unknown limits, and the skip is exactly the two
+ * names that module owns, read from its own exported list. Neither module's
+ * silence widens a ceiling: every limit name is evaluated by one of them, or
+ * fails closed as unknown in this one.
+ */
+import type { Policy } from "./policy-load.js";
+import type { EventRecord } from "./log.js";
+import { type UsdInput } from "./money.js";
+/** Length of the rolling `daily` window: 24 hours, in milliseconds. */
+export declare const WINDOW_MS: number;
+/** Event types that authorize execution and therefore consume budget. */
+export declare const CONSUMING_EVENTS: readonly ["approval.granted", "execution.started"];
+/**
+ * Which limits apply, as resolved by the policy matcher — this module does not
+ * re-run matching.
+ *
+ * - `classLimits` is `Resolution.limits`: the matched rule's `limits` map.
+ * - `classPattern` is the pattern of the rule those limits came from
+ *   (`Resolution.matched.pattern`). Class-scoped rolling limits count only
+ *   authorizations whose `payload.class` matches this **same rule pattern** —
+ *   not string equality with the action's class. A `financial.*` rule is one
+ *   budget shared by every class it governs, which is what a policy author
+ *   writing a single `daily_usd` under `financial.*` means; charging
+ *   `financial.spend` and `financial.transfer` to separate invisible buckets
+ *   would silently double the ceiling they wrote.
+ * - `globalBudgets` is `policy.budgets`: named scopes, each conjunctive.
+ */
+export interface BudgetScope {
+    classLimits: Record<string, number> | null;
+    classPattern: string | null;
+    globalBudgets: Policy["budgets"] | null;
+}
+/**
+ * The action being admitted. `est_cost_usd` absent means "no declared cost".
+ *
+ * The amount is a canonical decimal string (APRV-121, `core/money.ts`). A JSON
+ * number is accepted here as the historical form — records written before that
+ * change carry one, and this evaluator must read them identically to before.
+ */
+export interface BudgetAction {
+    class: string;
+    est_cost_usd?: UsdInput;
+}
+/**
+ * Which window a limit is measured over.
+ *
+ * `task-total` is the envelope cap of SPEC.md §6.2 (`budget.max_cost_usd`): not
+ * a window at all but the whole life of one task, which is what "maximum total
+ * spend across this task's actions" means.
+ */
+export type BudgetWindow = "per-action" | "rolling-24h" | "task-total";
+/**
+ * Where a limit came from: the matched class rule, `policy.budgets`, or the
+ * task's own registered envelope (SPEC.md §6.2 `budget`). All three are
+ * conjunctive with each other — "the stricter of the two binds".
+ */
+export type BudgetVerdictScope = "class" | "global" | "task";
+/**
+ * One limit's outcome.
+ *
+ * `consumed` is what the window already holds, `requested` is what this action
+ * would add (USD for money limits, `1` for action counts), and `remaining` is
+ * `limit - consumed - requested` — the headroom left *after* admitting the
+ * action, so a `pass: false` verdict shows how far over the line it is.
+ * `note` is present only when the verdict needs explaining, which at v0.1 means
+ * only fail-closed refusals.
+ *
+ * The three figures are **decimal strings** (APRV-121). A failing verdict is
+ * copied verbatim into the `budget.exceeded` payload, which is hashed material,
+ * and a float there would be exactly the cross-language serialization hazard
+ * this project removed from `est_cost_usd`. Money is reported in canonical USD
+ * (`"0.3"`), counts as integers (`"3"`); a negative `remaining` — headroom
+ * already spent — is spelled with a leading `-`, so it is a decimal string but
+ * not a canonical amount, which only ever describes money being declared.
+ */
+export interface BudgetVerdict {
+    limit: string;
+    scope: BudgetVerdictScope;
+    window: BudgetWindow;
+    consumed: string;
+    requested: string;
+    remaining: string;
+    pass: boolean;
+    note?: string;
+}
+/** Outcome of {@link evaluateBudgets}. Conjunctive: all must pass. */
+export interface BudgetVerdicts {
+    pass: boolean;
+    verdicts: BudgetVerdict[];
+}
+/** The verdict label for the envelope's own cap (SPEC.md §6.2 `budget`). */
+export declare const TASK_MAX_COST_USD = "budget.max_cost_usd";
+/**
+ * Evaluate every applicable budget limit against the log.
+ *
+ * Conjunctive (SPEC.md §5.2): `pass` is true only when every verdict passes.
+ * Verdicts are emitted class limits first (limit names ascending), then global
+ * budgets (scope name ascending, limit name ascending within a scope), so the
+ * list is byte-stable regardless of policy key order.
+ *
+ * `records` may be the whole log; only the rolling window is consulted, and the
+ * caller is never asked to pre-filter (a caller that filtered wrongly would
+ * silently widen the budget).
+ */
+export declare function evaluateBudgets(records: EventRecord[], scope: BudgetScope, action: BudgetAction, evaluationTs: string): BudgetVerdicts;
+/**
+ * The registered envelope's `budget.max_cost_usd` for `task`, or `null`.
+ *
+ * Read from the **log**, not from the task file: the file may have been edited
+ * since registration, and an agent that could raise its own cap by editing
+ * frontmatter after the fact would be authoring the ceiling it is judged by.
+ * `register` copies the envelope's `budget` block into the `task.registered`
+ * payload for exactly this read. The last registration wins, matching
+ * `findDeclaration` in `core/execute.ts`.
+ *
+ * A cap that is not a finite non-negative number is `null` — absent rather than
+ * zero. The schema already refuses those shapes at the write boundary, and
+ * inventing a $0 ceiling for a malformed one would refuse every action of the
+ * task with a message about money nobody wrote down.
+ */
+export declare function taskMaxCostUsd(records: EventRecord[], task: string): string | null;
+/**
+ * Evaluate the task's own cap: does admitting `action` keep the SUM of this
+ * task's authorized `est_cost_usd` at or under `maxCostUsd`?
+ *
+ * Commitment-based and consumption-identical to {@link evaluateBudgets}: the
+ * same two event types authorize (`approval.granted`, and `execution.started`
+ * only where no grant carries the same `action_key`), so a manual action that is
+ * granted and then started is charged once. The only differences are scope —
+ * events of *this task* — and window: there is none. A task cap is a lifetime
+ * total, so an envelope that says `max_cost_usd: 0.5` cannot be spent twice by
+ * waiting a day.
+ *
+ * `evaluationTs` is accepted for symmetry with the windowed evaluator and to
+ * keep every budget call site shaped alike; it selects no window here and the
+ * verdict does not depend on it.
+ */
+export declare function evaluateTaskBudget(records: EventRecord[], task: string, maxCostUsd: UsdInput, action: BudgetAction, _evaluationTs: string): BudgetVerdict;
+/**
+ * Every applicable budget, conjunctively: class limits, global budgets, and the
+ * task envelope's own cap.
+ *
+ * This is the function the three enforcement points call (`gate.request`,
+ * `gate.decide`'s grant path, `execute.startExecution`), so the envelope cap is
+ * checked at intake, at grant, and at execution start — the same three moments
+ * policy budgets are checked, because a cap enforced at only one of them is a
+ * cap a caller can route around by choosing a different door.
+ *
+ * Verdict order is class limits, then global budgets, then the task cap: the
+ * existing byte-stable order with one deterministic addition at the end.
+ * `task` may be `null` for a call site that has no task in hand, in which case
+ * the cap simply does not apply.
+ */
+export declare function evaluateBudgetsWithTask(records: EventRecord[], scope: BudgetScope, action: BudgetAction, evaluationTs: string, task: string | null): BudgetVerdicts;