@gethelio/proxy 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { Hono } from 'hono';
 import { ServerType } from '@hono/node-server';
+import { Database } from 'better-sqlite3';
 import { KnownBlock } from '@slack/web-api';
 
 declare const VERSION: string;
@@ -123,6 +124,32 @@ declare const policiesSchema: z.ZodObject<{
     }>>;
     hot_reload: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
+declare const budgetSchema: z.ZodObject<{
+    name: z.ZodString;
+    limit: z.ZodNumber;
+    currency: z.ZodString;
+    window: z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"session">]>;
+    key: z.ZodDefault<z.ZodEnum<{
+        session: "session";
+        sender_id: "sender_id";
+        global: "global";
+    }>>;
+    on_exceed: z.ZodDefault<z.ZodEnum<{
+        deny: "deny";
+        require_approval: "require_approval";
+    }>>;
+    approval: z.ZodOptional<z.ZodObject<{
+        channel: z.ZodString;
+        timeout: z.ZodOptional<z.ZodString>;
+        delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        escalation_after: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    idle_ttl: z.ZodOptional<z.ZodString>;
+    contributors: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        field: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 declare const approvalChannelSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"slack">;
     name: z.ZodOptional<z.ZodString>;
@@ -286,6 +313,32 @@ declare const helioConfigSchema: z.ZodObject<{
         }>>;
         hot_reload: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
+    budgets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        limit: z.ZodNumber;
+        currency: z.ZodString;
+        window: z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"session">]>;
+        key: z.ZodDefault<z.ZodEnum<{
+            session: "session";
+            sender_id: "sender_id";
+            global: "global";
+        }>>;
+        on_exceed: z.ZodDefault<z.ZodEnum<{
+            deny: "deny";
+            require_approval: "require_approval";
+        }>>;
+        approval: z.ZodOptional<z.ZodObject<{
+            channel: z.ZodString;
+            timeout: z.ZodOptional<z.ZodString>;
+            delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            escalation_after: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        idle_ttl: z.ZodOptional<z.ZodString>;
+        contributors: z.ZodArray<z.ZodObject<{
+            tool: z.ZodString;
+            field: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
     approval: z.ZodPrefault<z.ZodObject<{
         timeout: z.ZodDefault<z.ZodString>;
         default_on_timeout: z.ZodDefault<z.ZodEnum<{
@@ -329,6 +382,10 @@ type HelioConfig = z.infer<typeof helioConfigSchema>;
 type ApprovalChannel$1 = z.infer<typeof approvalChannelSchema>;
 /** The policies section of the config. */
 type PoliciesConfig = z.infer<typeof policiesSchema>;
+/** A single named budget from the `budgets` array (issue #14). */
+type BudgetConfig = z.infer<typeof budgetSchema>;
+/** The `budgets` section of the config. */
+type BudgetsConfig = readonly BudgetConfig[];
 
 /** Structured error for configuration loading failures. */
 declare class ConfigError extends Error {
@@ -546,6 +603,47 @@ interface MatchContext {
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
 
+/** One compiled contributor: which tools feed the budget, and from which field. */
+interface CompiledBudgetContributor {
+    readonly tool: ToolMatcher;
+    /** Dot-path into the tool arguments (e.g. "$.amount"), resolved per call. */
+    readonly field: string;
+}
+/**
+ * A budget's replenishment semantics.
+ *
+ * - `duration`: sliding window; spend ages out after `windowMs`.
+ * - `session`: a depleting pot per session key that never replenishes on a
+ *   timer; idle pots are garbage-collected after `idleTtlMs` because neither
+ *   door has an authoritative session-end signal.
+ */
+type CompiledBudgetWindow = {
+    readonly kind: 'duration';
+    readonly windowMs: number;
+} | {
+    readonly kind: 'session';
+    readonly idleTtlMs: number;
+};
+/** A fully compiled named budget, ready for the engine. */
+interface CompiledBudget {
+    readonly name: string;
+    readonly limit: number;
+    readonly currency: string;
+    readonly window: CompiledBudgetWindow;
+    /** The raw config window string ("1h" | "session") for wire/docs surfaces. */
+    readonly windowRaw: string;
+    readonly key: 'global' | 'session' | 'sender_id';
+    /** What a breach does: deny the call, or raise a break-glass ticket. */
+    readonly onExceed: 'deny' | 'require_approval';
+    /**
+     * Break-glass ticket routing (`on_exceed: require_approval` only). Absent
+     * means the dashboard channel and the router's default timeout. Budget
+     * tickets never consult `default_on_timeout` — timeout fails closed.
+     */
+    readonly approval?: CompiledApproval;
+    readonly contributors: readonly CompiledBudgetContributor[];
+}
+
 /** A JSON-RPC 2.0 request object. */
 interface JsonRpcRequest {
     jsonrpc: '2.0';
@@ -997,6 +1095,15 @@ declare const EXPORT_MAX_RECORDS = 10000;
  * audit route schema for the same reason as {@link EXPORT_MAX_RECORDS}.
  */
 declare const LIST_MAX_PAGE_SIZE = 1000;
+/**
+ * The retention cutoff of one sweep, computed once and shared with every
+ * registered hook: `iso` for `created_at`-style string comparisons, `ms`
+ * for epoch-millisecond columns.
+ */
+interface RetentionSweepCutoff {
+    readonly iso: string;
+    readonly ms: number;
+}
 /**
  * SQLite-backed audit record store.
  *
@@ -1008,8 +1115,33 @@ declare class AuditStore {
     private readonly insertStmt;
     private readonly retentionMs;
     private readonly includeResponses;
+    private readonly retentionSweepHooks;
     private cleanupTimer;
     constructor(options: AuditStoreOptions);
+    /**
+     * Register a hook to run on every retention sweep, receiving the sweep's
+     * cutoff. This is how co-resident tables (the budget ledger) join the
+     * store's single sweep schedule instead of running their own timers.
+     * Hooks registered after construction miss the constructor's initial
+     * purge — call {@link runRetentionSweep} once after registering to cover
+     * rows that aged out while the process was down.
+     */
+    onRetentionSweep(fn: (cutoff: RetentionSweepCutoff) => void): void;
+    /**
+     * One full retention sweep: purge expired audit records, then fire every
+     * registered hook with the sweep's cutoff. Hook failures degrade to a
+     * logged error — a broken co-resident purge must not stop the audit
+     * table's own retention.
+     */
+    runRetentionSweep(): void;
+    /**
+     * Package-internal: the store's open database handle, for components that
+     * co-locate their tables in the audit db (the budget ledger). Sharing the
+     * handle keeps one connection, one WAL domain, and one file-permission
+     * hardening pass. Not part of the public embedding API — do not re-export
+     * anything built on this from the package root.
+     */
+    get database(): Database;
     /**
      * Validate that the on-disk audit schema contains all required canonical columns.
      *
@@ -1059,6 +1191,7 @@ declare class AuditStore {
     aggregate(from?: string, to?: string): AuditAggregateStats;
     /** Delete records older than the retention period. Returns the count of deleted records. */
     purgeExpired(): number;
+    private purgeBefore;
     /** Close the database and stop the cleanup timer. */
     close(): void;
 }
@@ -1304,6 +1437,21 @@ type ApprovalStatus = 'pending' | 'approved' | 'denied' | 'timeout' | 'break_gla
  * aborting the held MCP request. Sideband (native) approvals only. (#12.)
  */
  | 'cancelled';
+/**
+ * One breached budget's context on a break-glass approval ticket (issue #14).
+ *
+ * DTO: snake_case because it rides {@link ApprovalTicket}, which is emitted
+ * verbatim over REST and webhooks. `spent` is the accrued spend BEFORE the
+ * attempted charge; `window` is the raw config string ("1h" | "session").
+ */
+interface BudgetBreachContext {
+    readonly name: string;
+    readonly limit: number;
+    readonly spent: number;
+    readonly attempted_amount: number;
+    readonly currency: string;
+    readonly window: string;
+}
 /** A failed attempt to deliver an approval notification. */
 interface ApprovalNotificationFailure {
     readonly channel: string;
@@ -1331,6 +1479,14 @@ interface ApprovalTicket {
     readonly requested_at: string;
     readonly timeout_at: string;
     readonly timeout_ms: number;
+    /**
+     * Every budget the call breached, when this is a break-glass (budget) or
+     * merged rule+budget ticket (issue #14). Its presence marks the ticket as
+     * budget-context: one approval covers every listed overage, the approval is
+     * scope-once by definition (issue #127 interlock — a `scope: "always"`
+     * resolution grants nothing beyond this call), and timeout fails closed.
+     */
+    readonly breached_budgets?: readonly BudgetBreachContext[];
     status: ApprovalStatus;
     resolved_at?: string;
     resolved_by?: string;
@@ -1413,6 +1569,8 @@ declare class ApprovalQueue {
         channel_name: string;
         session_id: string | null;
         timeout_ms: number;
+        /** Breached budget context on break-glass / merged tickets (issue #14). */
+        breached_budgets?: readonly BudgetBreachContext[];
     }): ApprovalTicket;
     /** Get a ticket by ID. Returns undefined if not found. */
     get(id: string): ApprovalTicket | undefined;
@@ -1468,6 +1626,17 @@ interface ApprovalSubmitParams {
     readonly tool_input: Record<string, unknown>;
     readonly matched_rule: CompiledPolicyRule | undefined;
     readonly session_id: string | null;
+    /** Breached budget context; marks the ticket as break-glass (issue #14). */
+    readonly breached_budgets?: readonly BudgetBreachContext[];
+    /**
+     * Total approval-config override. When set, channel/timeout/delegates/
+     * escalation come from HERE and the matched rule's approval config is
+     * ignored entirely — budget tickets are routed by the breached BUDGET's
+     * config (the matched rule may be an allow rule whose approval block, if
+     * any, has no authority over the money gate). Fields the override omits
+     * fall back to the router defaults, never to the rule.
+     */
+    readonly approval?: CompiledApproval;
 }
 /** Resolution statuses a native (sideband) ticket can be moved to. */
 type NativeResolution = 'approved' | 'denied' | 'timeout' | 'cancelled';
@@ -1481,6 +1650,8 @@ interface NativeTicketParams {
     readonly origin: string;
     /** Ticket timeout in ms (rule timeout, else the router default). */
     readonly timeout_ms?: number;
+    /** Breached budget context; marks the ticket as break-glass (issue #14). */
+    readonly breached_budgets?: readonly BudgetBreachContext[];
 }
 declare class ApprovalRouter {
     private readonly defaultTimeoutMs;
@@ -1677,6 +1848,13 @@ declare class RateLimiter {
         windowMs: number;
     }>): void;
     /** Stop the cleanup timer and mark as closed. */
+    /**
+     * Invoke the warning callback without letting a subscriber throw into the
+     * limiter's caller: a warning fires after state has already mutated, and a
+     * governed call must not be blocked (or double-charged on retry) by an
+     * observability bug.
+     */
+    private safeWarn;
     close(): void;
 }
 
@@ -1796,6 +1974,13 @@ declare class SpendLimiter {
      * whose config is gone (rule changed or removed) are evicted so the next
      * check lazy-creates a fresh bucket under the new config.
      *
+     * Keys built by {@link spendBucketKey} carry the owning rule's index, and
+     * for those the tuple must match at THAT index (`config.ruleIndex`): a
+     * reorder that shifts a spend rule's index evicts its old-index bucket
+     * instead of leaving an orphan no rule reads again — or worse, letting
+     * whatever rule now sits at that index adopt another rule's accrued spend.
+     * Un-suffixed keys keep the tuple-anywhere match.
+     *
      * Currency is part of the tuple because a USD→EUR switch is a meaningful
      * policy change — the same numeric limit buys a different amount of real
      * spend, so the bucket must reset. This replaces the old `reset()` call
@@ -1806,11 +1991,312 @@ declare class SpendLimiter {
         limit: number;
         currency: string;
         windowMs: number;
+        ruleIndex?: number;
     }>): void;
     /** Stop the cleanup timer and mark as closed. */
+    /**
+     * Invoke the warning callback without letting a subscriber throw into the
+     * limiter's caller: a warning fires after state has already mutated, and a
+     * governed call must not be blocked (or double-charged on retry) by an
+     * observability bug.
+     */
+    private safeWarn;
     close(): void;
 }
 
+/** Everything the engine needs about one tool call to resolve its charges. */
+interface BudgetChargeContext {
+    readonly toolName: string;
+    readonly toolArguments: Record<string, unknown> | undefined;
+    readonly sessionId: string | null;
+    /** Adapter-supplied sender id (sideband only); null on the MCP path. */
+    readonly senderId: string | null;
+}
+/** One budget's share of a call: which bucket, how much. */
+interface BudgetCharge {
+    readonly budget: CompiledBudget;
+    readonly bucketKey: string;
+    readonly amount: number;
+    /**
+     * The budget's config generation at peek time. A tuple-changing reload
+     * bumps the generation and resets the pot; a charge frozen before the bump
+     * (sideband /evaluate → /audit, or an MCP approval wait) is stale and MUST
+     * NOT repopulate the new pot with old-config spend — recordAll skips it.
+     */
+    readonly generation: number;
+}
+/** A budget whose contributor matched but whose amount was unusable. */
+interface BudgetChargeFailure {
+    readonly budget: CompiledBudget;
+    readonly bucketKey: string;
+    readonly reason: 'invalid_amount';
+    /** REAL accrued spend on the bucket the charge would have hit. */
+    readonly spent: number;
+    readonly remaining: number;
+    /** Epoch ms when the oldest entry ages out (duration); null for session pots. */
+    readonly resetAtMs: number | null;
+}
+/** Snapshot of one budget's state relative to a charge. */
+interface BudgetPeekEntry {
+    readonly budget: CompiledBudget;
+    readonly bucketKey: string;
+    readonly amount: number;
+    readonly allowed: boolean;
+    /** Spend accrued before this charge. */
+    readonly spent: number;
+    /** Headroom before this charge: max(0, limit - spent). */
+    readonly remaining: number;
+    /** Epoch ms when the oldest entry ages out (duration); null for session pots. */
+    readonly resetAtMs: number | null;
+    /**
+     * Set on recordAll snapshots for charges frozen before a tuple-changing
+     * reload: the executed spend was ledgered under its evaluate-time
+     * generation, but the reset pot was not touched.
+     */
+    readonly stale?: true;
+}
+/** Metadata recorded with every committed charge of one call. */
+interface BudgetCommitMeta {
+    /** Default kind for every charge of the call. */
+    readonly kind: 'spend' | 'approved_overage';
+    /**
+     * Per-budget overrides by budget name (break-glass): one approved call can
+     * mix kinds — breached budgets commit as `approved_overage` while
+     * unbreached ones stay `spend` — and all rows must still land in ONE
+     * ledger transaction, so the split is expressed here, not via two calls.
+     */
+    readonly kinds?: ReadonlyMap<string, 'spend' | 'approved_overage'>;
+    readonly auditRecordId: string;
+    readonly origin: string;
+    readonly toolName: string;
+    readonly timestampIso: string;
+}
+/**
+ * One durable ledger row. DTO: snake_case, matching the `budget_events`
+ * table columns the persistence layer writes.
+ */
+interface BudgetLedgerRow {
+    readonly budget_name: string;
+    readonly bucket_key: string;
+    readonly kind: 'spend' | 'approved_overage';
+    readonly amount: number;
+    readonly currency: string;
+    readonly tool_name: string;
+    readonly origin: string;
+    readonly audit_record_id: string;
+    readonly timestamp: string;
+    readonly timestamp_ms: number;
+    /**
+     * The charge's config generation at evaluate time. Rows from a stale
+     * generation are historical accounting for money that really moved; live
+     * replay only ever reads the current generation (the epoch of PR 2).
+     */
+    readonly generation: number;
+}
+/**
+ * Durable sink for committed charges. `commitAll` MUST be transactional:
+ * either every row of the batch persists or none does (a throw means none).
+ * The in-memory default is a no-op; the SQLite ledger implements this.
+ */
+interface BudgetLedgerSink {
+    commitAll(rows: readonly BudgetLedgerRow[]): void;
+}
+/** Payload for the per-charge commit callback (dashboard event bus). */
+interface BudgetCommitEvent {
+    readonly name: string;
+    readonly bucket_key: string;
+    readonly kind: 'spend' | 'approved_overage';
+    readonly amount: number;
+    readonly spent: number;
+    readonly remaining: number;
+    readonly limit: number;
+    readonly currency: string;
+    readonly utilization: number;
+}
+/**
+ * Payload for the per-budget breach callback (dashboard event bus). Fired
+ * via {@link BudgetEngine.reportBreaches} by the DOORS at the moment a peek
+ * actually denies a call or raises the composite break-glass ticket — never
+ * by `peekAll` itself, which is pure and also runs for dry-run.
+ */
+interface BudgetBreachEvent {
+    readonly name: string;
+    readonly bucket_key: string;
+    /** The budget's configured posture, even when the outcome was a deny. */
+    readonly on_exceed: 'deny' | 'require_approval';
+    readonly attempted_amount: number;
+    readonly spent: number;
+    readonly limit: number;
+    readonly currency: string;
+}
+/** Wire-ready bucket state for `GET /api/budgets` (snake_case DTO). */
+interface BudgetBucketState {
+    readonly bucket_key: string;
+    readonly spent: number;
+    readonly remaining: number;
+    readonly reset_at_ms: number | null;
+    readonly last_activity_ms: number;
+}
+/** Wire-ready budget state for `GET /api/budgets` (snake_case DTO). */
+interface BudgetState {
+    readonly name: string;
+    readonly limit: number;
+    readonly currency: string;
+    readonly window: string;
+    readonly key: 'global' | 'session' | 'sender_id';
+    readonly on_exceed: 'deny' | 'require_approval';
+    readonly buckets: readonly BudgetBucketState[];
+}
+interface BudgetEngineOptions {
+    readonly budgets?: readonly CompiledBudget[];
+    /** Clock function for testable time. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** Interval (ms) between GC sweeps. 0 disables the timer. Default: 60000. */
+    readonly cleanupIntervalMs?: number;
+    /** Durable sink; defaults to a no-op (state resets on restart). */
+    readonly ledger?: BudgetLedgerSink;
+    /** Fired once per committed charge with post-record numbers. */
+    readonly onCommit?: (event: BudgetCommitEvent) => void;
+    /** Fired once per breached budget when a door denies or raises a ticket. */
+    readonly onBreach?: (event: BudgetBreachEvent) => void;
+}
+declare class BudgetEngine {
+    private budgets;
+    /** budget name → bucket key → bucket. */
+    private readonly state;
+    /** budget name → config generation; bumped whenever the pot resets. */
+    private readonly generations;
+    private readonly now;
+    private readonly ledger;
+    /** The sink again, when it carries the full persistence contract. */
+    private readonly persistence;
+    private readonly onCommit;
+    private readonly onBreach;
+    private timer;
+    private closed;
+    private hydrated;
+    constructor(options?: BudgetEngineOptions);
+    /**
+     * Resolve which budgets a call feeds and how much it charges each.
+     *
+     * A budget participates when any contributor glob matches the tool name;
+     * the FIRST matching contributor (config order) supplies the amount field.
+     * A missing, non-numeric, negative, or non-finite amount fails closed as a
+     * `failures` entry — the caller must deny the call.
+     */
+    resolveCharges(ctx: BudgetChargeContext): {
+        charges: BudgetCharge[];
+        failures: BudgetChargeFailure[];
+    };
+    /** Check every charge without mutating. All-or-nothing: one deny flips `allowed`. */
+    peekAll(charges: readonly BudgetCharge[]): {
+        allowed: boolean;
+        entries: BudgetPeekEntry[];
+    };
+    /**
+     * Commit every charge of one call: ledger first (one atomic batch), then
+     * in-memory state, then the commit events. A sink throw propagates and
+     * leaves ALL in-memory buckets untouched — no partial commit, ever.
+     * Recording is unconditional past the sink (an approved overage
+     * legitimately pushes a bucket past its limit).
+     */
+    recordAll(charges: readonly BudgetCharge[], meta: BudgetCommitMeta): BudgetPeekEntry[];
+    /**
+     * Fire one `onBreach` event per breached entry. Called by the doors at the
+     * moment a peek outcome actually denies the call or raises the composite
+     * break-glass ticket (never for dry-run peeks, never for invalid-amount
+     * failures — those are input errors, not breaches). Subscriber throws are
+     * isolated: a dashboard bug must never affect a gate outcome.
+     */
+    reportBreaches(entries: readonly BudgetPeekEntry[]): void;
+    /**
+     * Rebuild in-memory state from the ledger. Call once at startup, after
+     * construction and before serving traffic; a no-op when the configured
+     * sink does not carry the persistence contract (in-memory mode).
+     *
+     * Per configured budget, `budget_meta` decides:
+     * - no row → first boot for this name: mint epoch 1, nothing to replay;
+     * - a different `{limit, currency, window, key}` tuple → the config
+     *   changed while down: bump the epoch, replay nothing (the same reset a
+     *   live tuple-changing reload performs, extended across restarts). Old
+     *   rows keep their epoch — history stays queryable, replay ignores it;
+     * - a matching tuple → replay at the meta epoch: duration windows rebuild
+     *   entry lists from a window lookback (bit-equivalent to never having
+     *   restarted), session windows rebuild still-live pots (idle-TTL bound)
+     *   from their post-GC-watermark lifetime sums.
+     *
+     * Meta writes here propagate failures: a ledger that cannot record epochs
+     * at startup must fail the boot loudly, the same posture as the audit
+     * store's schema assertion.
+     */
+    hydrate(): void;
+    /**
+     * Swap budget configs on hot-reload. Identity is the NAME: removed names
+     * drop their live buckets; a changed `{limit, currency, window, key}` tuple
+     * resets the budget's buckets (a different pool or scope structure);
+     * everything else — contributors, on_exceed — applies to the accrued state
+     * as-is, because those edits do not change what was already spent.
+     *
+     * Persist-before-swap: every epoch this reload mints lands in
+     * `budget_meta` in ONE transaction BEFORE any memory changes. A throw
+     * rejects the whole reload — the caller keeps the previous config — so
+     * disk and memory can never diverge; a failed reload simply never
+     * happened, and no later restart can misread it. (A swallow-and-continue
+     * posture here would let an A→B reload with a failed flush resurrect the
+     * retired A pot after a revert-and-restart.)
+     *
+     * Removed names mint too: an in-flight charge frozen before the removal
+     * must go stale, or its commit would recreate hidden bucket state for a
+     * budget that no longer exists — and without the on-disk tombstone, a
+     * restart with the budget back in the config would resurrect the
+     * pre-removal pot that the removal had reset. Generations for removed
+     * names are kept (not deleted) so a later re-add keeps counting up.
+     *
+     * @throws When the epoch flush fails; the engine is unchanged.
+     */
+    reconcile(next: readonly CompiledBudget[]): void;
+    /** Sweep: collect idle session pots, evict expired duration entries. */
+    gc(): void;
+    /**
+     * Wire-ready state for `GET /api/budgets`. Configured budgets appear even
+     * with zero live buckets, so the dashboard shows every pot at headroom.
+     */
+    listStates(): BudgetState[];
+    /** Whether any budget holds a live bucket under `key` (cardinality probes). */
+    hasBucket(key: string): boolean;
+    close(): void;
+    /**
+     * The next epoch for a name: one past the highest that memory, the meta
+     * row, or the rows themselves have seen. Pure — the caller applies it to
+     * `generations` only after the mint is durable. The meta consult matters
+     * for names this process has no memory of (a hot-reload re-add after a
+     * restart); the rows consult is a backstop against historical divergence
+     * (rows at an epoch no meta row records) — minting from memory or meta
+     * alone could collide into an epoch that already has rows and replay them
+     * into a different pot.
+     */
+    private nextEpoch;
+    /**
+     * The key format is part of the ON-DISK contract: hydrate rebuilds buckets
+     * from `budget_events.bucket_key` verbatim, so renaming any segment here
+     * would strand every persisted bucket of an unchanged tuple as an
+     * unreachable ghost (displayed, never charged). Changing the format
+     * requires folding a format version into the epoch decision.
+     */
+    private bucketKey;
+    private bucketFor;
+    private evictExpired;
+    /**
+     * Fetch a bucket for reading, evicting expired duration entries first and
+     * pruning the bucket if nothing is left. Reads must never see (or keep
+     * alive, via `hasBucket`-driven capacity slots) state the window has
+     * already expired — expiry is lazy on read, not just on the sweep timer.
+     */
+    private liveBucket;
+    private spentOf;
+    private snapshot;
+}
+
 /** Options for constructing a GovernedForwarder. */
 interface GovernedForwarderOptions {
     /** The current environment label (e.g. "production", "staging"). */
@@ -1825,6 +2311,8 @@ interface GovernedForwarderOptions {
     rateLimiter?: RateLimiter;
     /** Spend limiter for handling spend_limit decisions. */
     spendLimiter?: SpendLimiter;
+    /** Budget engine for named cross-tool budgets (issue #14). */
+    budgetEngine?: BudgetEngine;
 }
 /** Result of attempting to prime the tool annotation cache. */
 interface AnnotationCachePrimeResult {
@@ -1852,6 +2340,7 @@ declare class GovernedForwarder implements McpForwarder {
     private readonly approvalRouter;
     private readonly rateLimiter;
     private readonly spendLimiter;
+    private readonly budgetEngine;
     private readonly annotationCache;
     private agentKeyWarned;
     private senderKeyWarned;
@@ -1895,6 +2384,51 @@ declare class GovernedForwarder implements McpForwarder {
     /** Write an immediate audit record for a drift event (not a tool call). */
     private writeDriftAuditRecord;
     private handleToolsCall;
+    /**
+     * Await the composite break-glass ticket for a budget overage (issue #14).
+     *
+     * The ticket is routed by the BUDGET's approval config (first breached
+     * budget in config order), never the matched rule's. Deviation from rule
+     * approvals, by design: timeout ALWAYS fails closed — `default_on_timeout:
+     * allow` would forward an unapproved overage, and recording it as
+     * `approved_overage` would be a lie while not recording it would corrupt
+     * the pot. Money gates do not fail open.
+     */
+    private handleBudgetApproval;
+    /** writeAuditRecord, isolated: an audit-writer bug must not reject the response. */
+    private writeAuditRecordSafely;
+    /**
+     * Everything the non-approval action branches decide, minus the forward
+     * itself. Deliberately SYNCHRONOUS: the caller must reach the phase-3
+     * commits without yielding to the microtask queue, or concurrent calls
+     * could double-spend a peeked limiter slot. The approval branch (the only
+     * one that genuinely waits) is dispatched by the caller directly.
+     */
+    private resolveActionGate;
+    /**
+     * Phase 2: check every budget the call feeds, all-or-nothing (issue #14).
+     *
+     * Any `on_exceed: deny` breach (or invalid amount) denies and records
+     * NOTHING on any budget — rejected calls never consume budget anywhere.
+     * Breaches that are all `on_exceed: require_approval` yield the `approval`
+     * variant: one composite break-glass ticket per call, and only an explicit
+     * approval commits (breached budgets as `approved_overage`). On proceed,
+     * the returned `commit` records every charge together (ledger rows first,
+     * atomically, referencing the pre-generated audit id).
+     */
+    private gateBudgets;
+    /**
+     * Reject a `tools/call` that carries no usable tool name and record it.
+     *
+     * The rejection is its own audit shape, not a governed decision: no rule was
+     * evaluated, so it is written directly (like {@link writeDriftAuditRecord})
+     * rather than threaded through {@link writeAuditRecord}, whose
+     * `PolicyDecision.action` union has no `rejected` member and whose
+     * forwarded-upstream logic does not apply. The raw `params` are preserved in
+     * `tool_input` so an investigator can see exactly what a lenient upstream
+     * could have keyed off.
+     */
+    private rejectNamelessToolsCall;
     private handleApproval;
     private handleRateLimit;
     private handleSpendLimit;
@@ -1905,8 +2439,12 @@ declare class GovernedForwarder implements McpForwarder {
     private handleDryRun;
     /** Construct a limit bucket key based on the configured key type. */
     private buildLimitKey;
-    /** Determine if the request was actually forwarded to the upstream MCP server. */
-    private wasForwardedUpstream;
+    /**
+     * Construct a spend bucket key via the shared {@link spendBucketKey}
+     * composer — see its doc for why spend buckets are rule-discriminated.
+     * Rate buckets keep the undiscriminated keys.
+     */
+    private buildSpendLimitKey;
     private writeAuditRecord;
     private makeDriftBlockResult;
     private makeDenyResult;
@@ -1918,8 +2456,48 @@ declare class GovernedForwarder implements McpForwarder {
     private makeClientDisconnectedBlockResult;
 }
 
+/** A budget failed to compile (invalid contributor glob). */
+declare class BudgetParseError extends Error {
+    readonly budgetName: string;
+    constructor(message: string, budgetName: string);
+}
+/**
+ * Compile validated budget configs into engine-ready form.
+ *
+ * Contributor globs use the same picomatch engine as `match.tool` so a
+ * pattern behaves identically whether it gates a rule or feeds a budget.
+ *
+ * @throws {BudgetParseError} On an invalid contributor glob.
+ */
+declare function compileBudgets(budgets: BudgetsConfig): CompiledBudget[];
+
+/**
+ * One `budget_events` row as listed by `GET /api/budgets/:name/events` —
+ * the table columns minus `epoch` (internal replay bookkeeping), snake_case
+ * verbatim. `budget_name` stays in the row so a page is self-describing.
+ */
+interface BudgetEventRecord {
+    readonly id: string;
+    readonly budget_name: string;
+    readonly bucket_key: string;
+    readonly kind: 'spend' | 'approved_overage';
+    readonly amount: number;
+    readonly currency: string;
+    readonly tool_name: string;
+    readonly origin: string;
+    readonly audit_record_id: string | null;
+    readonly timestamp: string;
+    readonly timestamp_ms: number;
+    readonly created_at: string;
+}
+/** One page of a budget's event history plus the unpaginated total. */
+interface BudgetEventsPage {
+    readonly events: readonly BudgetEventRecord[];
+    readonly total: number;
+}
+
 /** The outcome vocabulary adapters branch on — never internal rule actions. */
-type WireDecision = 'allow' | 'deny' | 'require_approval' | 'rate_limited' | 'spend_limited' | 'dry_run';
+type WireDecision = 'allow' | 'deny' | 'require_approval' | 'rate_limited' | 'spend_limited' | 'budget_exceeded' | 'dry_run';
 /** Tool definition carried by /evaluate (optional; enables the drift guard). */
 interface WireToolDefinition {
     readonly name: string;
@@ -1999,6 +2577,8 @@ interface GovernanceServiceOptions {
     readonly approvalRouter?: ApprovalRouter;
     readonly rateLimiter?: RateLimiter;
     readonly spendLimiter?: SpendLimiter;
+    /** Budget engine for named cross-tool budgets (issue #14). */
+    readonly budgetEngine?: BudgetEngine;
     readonly auditWriter?: AuditWriter;
     /** Default approval timeout (ms) when a rule sets none. */
     readonly approvalTimeoutMs?: number;
@@ -2022,6 +2602,7 @@ declare class GovernanceService {
     private readonly approvalRouter;
     private readonly rateLimiter;
     private readonly spendLimiter;
+    private readonly budgetEngine;
     private readonly auditWriter;
     private readonly approvalTimeoutMs;
     private readonly ttlMs;
@@ -2107,10 +2688,12 @@ declare class GovernanceService {
     private cacheFor;
     private discardPending;
     private getTicketStatus;
+    /** Latch the entry's ticket resolution while the ticket still exists. */
+    private snapshotTicketResolution;
     private planRate;
     private planSpend;
-    /** Commit a limit plan at /audit time and return the evidence_chain block. */
-    private commitLimit;
+    /** Commit every plan of one call at /audit time; returns the chain blocks. */
+    private commitPlans;
     private writeAudit;
     private assertApprovalRouter;
 }
@@ -2342,6 +2925,19 @@ interface ApprovalNotificationFailedEvent {
     readonly phase: 'initial' | 'escalation';
     readonly error: string;
 }
+/**
+ * Payload for a budget_update event: one committed charge with post-record
+ * numbers (issue #14). The engine's commit-event DTO is already snake_case
+ * wire shape, so it is emitted verbatim. `utilization` drives dashboard
+ * thresholds — there is no separate budget warning event.
+ */
+type BudgetUpdateEvent = BudgetCommitEvent;
+/**
+ * Payload for a budget_breached event: a peek denied the call or raised the
+ * composite break-glass ticket (issue #14). Emitted verbatim from the
+ * engine's breach-event DTO.
+ */
+type BudgetBreachedEvent = BudgetBreachEvent;
 /** Map of event type names to their payload types. */
 interface DashboardEvents {
     action: ActionEvent;
@@ -2349,6 +2945,8 @@ interface DashboardEvents {
     approval_resolved: ApprovalResolvedEvent;
     limit_warning: LimitWarningEvent;
     approval_notification_failed: ApprovalNotificationFailedEvent;
+    budget_update: BudgetUpdateEvent;
+    budget_breached: BudgetBreachedEvent;
 }
 /** Union of all dashboard event type names. */
 type DashboardEventType = keyof DashboardEvents;
@@ -2396,6 +2994,20 @@ interface DashboardAppDeps {
     readonly adapterLiveness?: {
         listAdapters(): AdapterLivenessEntry[];
     };
+    /**
+     * Budget read surface for `GET /api/budgets` and
+     * `GET /api/budgets/:name/events` (issue #14) — narrow views of the
+     * BudgetEngine (live pot states) and BudgetLedger (spend history).
+     * Optional on the adapterLiveness pattern: absent (direct embedders),
+     * both endpoints serve empty lists with 200.
+     */
+    readonly budgets?: {
+        listStates(): BudgetState[];
+        listEvents(name: string, page: {
+            limit: number;
+            offset: number;
+        }): BudgetEventsPage;
+    };
 }
 /** Options for the dashboard API. */
 interface DashboardAppOptions {
@@ -2414,4 +3026,4 @@ interface DashboardAppOptions {
  */
 declare function createDashboardApp(deps: DashboardAppDeps, options?: DashboardAppOptions): Hono;
 
-export { type AdapterLivenessEntry, type ApprovalAppOptions, type ApprovalChannel, type ApprovalOutcome, ApprovalQueue, type ApprovalQueueOptions, ApprovalRouter, type ApprovalRouterOptions, type ApprovalStatus, type ApprovalTicket, type AuditAggregateStats, type AuditInput, type AuditListResult, type AuditPaginationOptions, type AuditQueryFilters, type AuditRecord, AuditStore, type AuditStoreOptions, type AuditTimeBucket, AuditWriter, type AuditWriterOptions, type CompilePoliciesResult, type CompiledPolicy, type CompiledPolicyRule, ConfigError, type CreateAppOptions, type DashboardAppDeps, type DashboardAppOptions, DashboardEventBus, type DashboardEventType, type DashboardEvents, EXPORT_MAX_RECORDS, type EvaluateInput, type EvidenceEntry, EvidenceStore, type EvidenceStoreOptions, GovernanceConfigError, GovernanceService, type GovernanceServiceOptions, GovernedForwarder, type GovernedForwarderOptions, type HelioConfig, type InstallScanInput, LIST_MAX_PAGE_SIZE, type MatchContext, type PolicyDecision, PolicyParseError, QueueChannel, type RateLimitCheckParams, type RateLimitKeyState, type RateLimitResult, RateLimiter, type RateLimiterOptions, type ResolveApprovalInput, type ServerHandle, type SessionState, type SlackActionAppOptions, SlackChannel, type SlackChannelOptions, type SpendLimitCheckParams, type SpendLimitKeyState, type SpendLimitResult, SpendLimiter, type SpendLimiterOptions, SseUpstreamForwarder, type SseUpstreamForwarderOptions, StdioForwarder, type StdioForwarderOptions, StreamableHttpForwarder, type StreamableHttpForwarderOptions, UpstreamForwarder, type UpstreamForwarderOptions, VERSION, WebhookChannel, type WebhookChannelOptions, type WireDecision, compilePolicies, createApp, createApprovalApp, createChannels, createDashboardApp, createSidebandApp, createSlackActionApp, evaluatePolicy, loadConfig, matchRule, startServer, startSidebandServer };
+export { type AdapterLivenessEntry, type ApprovalAppOptions, type ApprovalChannel, type ApprovalOutcome, ApprovalQueue, type ApprovalQueueOptions, ApprovalRouter, type ApprovalRouterOptions, type ApprovalStatus, type ApprovalTicket, type AuditAggregateStats, type AuditInput, type AuditListResult, type AuditPaginationOptions, type AuditQueryFilters, type AuditRecord, AuditStore, type AuditStoreOptions, type AuditTimeBucket, AuditWriter, type AuditWriterOptions, type BudgetBreachContext, type BudgetBreachEvent, type BudgetBucketState, type BudgetCommitEvent, BudgetEngine, type BudgetEventRecord, type BudgetEventsPage, type BudgetLedgerRow, type BudgetLedgerSink, BudgetParseError, type BudgetState, type CompilePoliciesResult, type CompiledBudget, type CompiledBudgetContributor, type CompiledBudgetWindow, type CompiledPolicy, type CompiledPolicyRule, ConfigError, type CreateAppOptions, type DashboardAppDeps, type DashboardAppOptions, DashboardEventBus, type DashboardEventType, type DashboardEvents, EXPORT_MAX_RECORDS, type EvaluateInput, type EvidenceEntry, EvidenceStore, type EvidenceStoreOptions, GovernanceConfigError, GovernanceService, type GovernanceServiceOptions, GovernedForwarder, type GovernedForwarderOptions, type HelioConfig, type InstallScanInput, LIST_MAX_PAGE_SIZE, type MatchContext, type PolicyDecision, PolicyParseError, QueueChannel, type RateLimitCheckParams, type RateLimitKeyState, type RateLimitResult, RateLimiter, type RateLimiterOptions, type ResolveApprovalInput, type ServerHandle, type SessionState, type SlackActionAppOptions, SlackChannel, type SlackChannelOptions, type SpendLimitCheckParams, type SpendLimitKeyState, type SpendLimitResult, SpendLimiter, type SpendLimiterOptions, SseUpstreamForwarder, type SseUpstreamForwarderOptions, StdioForwarder, type StdioForwarderOptions, StreamableHttpForwarder, type StreamableHttpForwarderOptions, UpstreamForwarder, type UpstreamForwarderOptions, VERSION, WebhookChannel, type WebhookChannelOptions, type WireDecision, compileBudgets, compilePolicies, createApp, createApprovalApp, createChannels, createDashboardApp, createSidebandApp, createSlackActionApp, evaluatePolicy, loadConfig, matchRule, startServer, startSidebandServer };