approval-md 0.1.0 → 0.3.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;

package/dist/src/core/channel-owner.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Which instance owns which bot (APRV-390).
+ *
+ * APRV-178 scoped the OS keystore's ITEM NAMES to an instance, which closed the
+ * half of the incident where two gates read one item. It did not close the
+ * other half: two instances can still be handed the same bot token under two
+ * perfectly distinct names. `core/instance.ts` answers its questions from names
+ * alone, on purpose, and a name cannot tell you that two different names hold
+ * one value.
+ *
+ * Observed again on 2026-09-19: the primary daemon and the demo gate in
+ * `~/demo-gate` both long-polled one bot, both printed `getUpdates` HTTP 409
+ * Conflict on every poll, and neither phone channel worked. The only thing that
+ * distinguishes those two processes is what the Bot API says the token IS, and
+ * the only call that asks is `getMe`. So this module records `getMe`'s answer
+ * and makes the second claim on one bot a refusal instead of a 409.
+ *
+ * ## The two records
+ *
+ * ```
+ * <instance>/.approval/channel-owner.json     one instance's own bots
+ * <state dir>/approval/bots.json              every instance's claims, per machine
+ * ```
+ *
+ * The per-instance file is this instance's copy of what it probed, gitignored
+ * and rebuildable by one `getMe`. The registry is the part that has to be
+ * SHARED, because the question is "does anything else on this machine hold this
+ * bot", and no file inside one instance can answer that.
+ *
+ * ## Why the registry is a plain file, and why it is not under `.approval`
+ *
+ * **Not the OS keystore.** Every reader of this registry is a diagnostic or a
+ * start-up preflight, and neither may block on an unlock dialog — that is
+ * `NON_RESOLVING_RUNNER`'s rule in `core/env-file.ts`, and `approval doctor`
+ * already answers the whole keychain-scope row from names for exactly this
+ * reason. A machine with no keystore backend at all still needs this refusal,
+ * and would get nothing from a store it does not have. And there is no secret
+ * here to justify one: a bot id, a `@username`, an instance id and a directory
+ * path are all things `.approval/env` carries in the open.
+ *
+ * **Not a `.approval` directory under the home directory**, which was the other
+ * candidate. This project's own policy reserves anything under `.approval/` to
+ * the human's ceremony (`policy.core`, human-only), and the hook classifier
+ * applies that to the name wherever it appears. A file the runtime rewrites on
+ * every listener start does not belong in the directory the policy holds shut.
+ *
+ * So it goes where this runtime already puts per-user state that is derived
+ * rather than evidence: the same platform split `cli/setup-service.ts` uses for
+ * a service's console output. {@link APPROVAL_STATE_DIR_ENV} overrides it, which
+ * is what the test suite sets — a suite that wrote the operator's real registry
+ * would be the mistake the Muse probe's suite made with its live pointer.
+ *
+ * ## What it is not
+ *
+ * Not evidence, and never consulted by an enforcement path. Nothing in here
+ * widens a permission, and losing the whole file costs one re-probe. It answers
+ * one question — "is another instance on this machine already polling this
+ * bot?" — and that answer only ever produces a REFUSAL. A registry that could
+ * be edited into granting something would be a policy file; this one can be
+ * edited into letting a 409 happen, which is the state without it.
+ */
+/** The per-instance record's filename, inside `.approval/`. Gitignored. */
+export declare const CHANNEL_OWNER_FILE = "channel-owner.json";
+/** The per-machine registry's filename, inside the state directory. */
+export declare const BOT_REGISTRY_FILE = "bots.json";
+/**
+ * Where the per-machine registry lives, overriding the platform default.
+ *
+ * Set by the test suite, and available to an operator running two gates under
+ * one account who wants them in separate state trees. An empty or unset value
+ * means the platform default.
+ */
+export declare const APPROVAL_STATE_DIR_ENV = "APPROVAL_STATE_DIR";
+/** The only format version this build writes, and the only one it reads. */
+export declare const CHANNEL_OWNER_VERSION = 1;
+/**
+ * The channels this registry knows about.
+ *
+ * One entry today. It is a union rather than a bare string because the registry
+ * is per-machine and long-lived: a second channel with a bot-like identity
+ * (APRV-383's hosted daemon id is the named candidate) has to be able to land
+ * beside Telegram's rows without either one's reader guessing what a row means.
+ */
+export type OwnedChannel = "telegram";
+/** What one `getMe` said, reduced to the fields that identify a bot. */
+export interface BotIdentity {
+    channel: OwnedChannel;
+    /** The Bot API's own numeric id, as a string. Stable for the life of a bot. */
+    botId: string;
+    /** `@name`, for the human reading the refusal. Never matched on. */
+    username: string;
+    /**
+     * The Bot API deployment that issued `botId`, normalised.
+     *
+     * Part of the identity rather than a note beside it: a bot id is unique
+     * within one Bot API, and nothing more. Two gates pointed at two different
+     * API bases — a self-hosted Bot API server and Telegram's own, or two local
+     * ones — hold two different bots however their ids compare, and refusing the
+     * second would be refusing a configuration that cannot conflict. Both of the
+     * gates in the incident this task is named after used the default base, so
+     * this narrows nothing that mattered there.
+     */
+    apiBase: string;
+}
+/**
+ * One Bot API base, reduced so two spellings of one deployment compare equal.
+ *
+ * Lowercased and stripped of trailing slashes, which are the two ways the same
+ * base is written. Nothing more is attempted: a host that resolves to the same
+ * server under two names is two names here, and that is the safe direction of
+ * the error — two identities, so the second gate is allowed to start, exactly
+ * as it was before this module existed.
+ */
+export declare function normaliseApiBase(apiBase: string): string;
+/** One instance's claim on one bot. */
+export interface BotClaim extends BotIdentity {
+    /** The claiming instance's short id, as `approval doctor` prints it. */
+    instanceId: string;
+    /** That instance's `.approval` directory, absolute. */
+    instanceHome: string;
+    /** When the claim was made or last re-proved, ISO-8601. */
+    claimedAt: string;
+}
+/**
+ * The per-user state directory for this runtime.
+ *
+ * The split is `cli/setup-service.ts`'s `defaultLogsDir`, one level up: macOS
+ * keeps user application state under `Library/Application Support` and Linux
+ * under `.local/state` (XDG's state home, which is where "state that should
+ * persist between restarts but is not config and is not a cache" belongs).
+ */
+export declare function stateDirFor(env?: NodeJS.ProcessEnv): string;
+/** The per-machine registry's path. */
+export declare function registryPathFor(env?: NodeJS.ProcessEnv): string;
+/** The per-instance record's path, for the instance owning `logPath`. */
+export declare function ownerPathFor(logPath: string): string;
+/**
+ * Every claim recorded on this machine, newest write last.
+ *
+ * An unreadable, absent or malformed registry is an EMPTY one. It is a cache of
+ * probes, so "I do not know of any claim" is the honest answer and it costs one
+ * `getMe` to rebuild — whereas failing a listener start-up because a JSON file
+ * in a state directory got truncated would take the phone channel down for a
+ * reason that has nothing to do with the gate.
+ */
+export declare function readRegistry(env?: NodeJS.ProcessEnv): BotClaim[];
+/** What this instance last recorded about its own channels. */
+export declare function readOwner(logPath: string): BotClaim[];
+/**
+ * The claim this instance holds on `channel`, or `null`.
+ *
+ * Read from the per-instance file, which is what `approval channel telegram
+ * health` and `approval doctor` report from: both are offline, and both must
+ * answer without a network call or a keystore lookup.
+ */
+export declare function ownedBot(logPath: string, channel: OwnedChannel): BotClaim | null;
+/**
+ * Every OTHER instance on this machine that has claimed `botId`.
+ *
+ * "Other" is decided by instance id, so a re-run in the same instance is never
+ * reported against itself, and two directories that reach one gate by different
+ * spellings are two instances — which is `core/instance.ts`'s deliberate choice
+ * of the safe error direction, and this module inherits it rather than adding a
+ * second rule that could disagree.
+ */
+export declare function otherOwnersOf(logPath: string, botId: string, apiBase: string, env?: NodeJS.ProcessEnv): BotClaim[];
+/** Why a claim was refused. Machine-readable and distinct (SPEC §11.1 inv. 6). */
+export type ClaimRefusalCode = "bot-owned-elsewhere";
+export type ClaimResult = {
+    ok: true;
+    claim: BotClaim;
+} | {
+    ok: false;
+    code: ClaimRefusalCode;
+    owners: BotClaim[];
+    message: string;
+};
+/**
+ * One sentence naming who else holds this bot, for a refusal or a 409 report.
+ *
+ * Exported because three surfaces print it — the listener preflight, `approval
+ * setup channel telegram`, and the runtime 409 report — and three spellings of
+ * "another instance owns this bot" is three chances for them to name different
+ * instances for one fact.
+ */
+export declare function describeOwners(owners: readonly BotClaim[]): string;
+/**
+ * Record this instance as `identity`'s owner, unless somebody else already is.
+ *
+ * Read-then-write rather than compare-and-append: this is a local cache of
+ * probes and not the log, so the property it needs is "two instances racing
+ * both see a refusal or one of them wins", which a same-machine read-then-write
+ * over a file rewritten in whole gives. It is deliberately NOT passed through
+ * the log's append path — nothing here is evidence, and putting a re-probe on
+ * every listener start into the hash chain would be writing a heartbeat into
+ * the record the project's whole argument says must stay small and meaningful.
+ *
+ * The refusal names the other instance, because "this bot is taken" without
+ * saying by what is a message that sends an operator looking through `ps`.
+ */
+export declare function claimBot(logPath: string, identity: BotIdentity, options?: {
+    now?: () => Date;
+    env?: NodeJS.ProcessEnv;
+}): ClaimResult;
+/**
+ * Drop this instance's claim on `channel`, from both records.
+ *
+ * Used by nothing on the happy path. It exists because the alternative to a way
+ * out is an operator hand-editing a JSON file in a state directory to recover
+ * from a stale claim, and a recovery step that is not a command is a recovery
+ * step that gets done wrong.
+ */
+export declare function releaseBot(logPath: string, channel: OwnedChannel, env?: NodeJS.ProcessEnv): void;