@aldus-runtime/gate-engine 0.2.0-next.2 → 0.2.0-next.21

package/src/spend.ts

@@ -11,13 +11,19 @@
  * `GateDecision` stores only digests. Carrying the limit in a record beside the decision would
  * let someone raise the ceiling without touching the approval.
  *
- * So a grant does both: it holds the values, and {@link grantLimitsDigest} is included among the
+ * So a grant does both: it holds the values, and {@link grantTermsDigest} is included among the
  * gate's bound subjects. Raising a limit changes that digest, which drifts from `subjectHashes`,
  * which voids the authorization exactly as §13.2 requires. The ceiling cannot move without an
  * operator re-approving it.
  */
 
-import type { CostRecord, Money } from "@aldus-runtime/core";
+import {
+  reservationExposureIsBounded,
+  reservationIsActive,
+  type CostRecord,
+  type Money,
+  type SpendReservation,
+} from "@aldus-runtime/core";
 
 import { digestSubjectValue } from "./binding.js";
 import {
@@ -25,6 +31,7 @@ import {
   compareMoney,
   formatMoney,
   isNegativeMoney,
+  isPositiveMoney,
   subtractMoney,
   zeroMoney,
 } from "./money.js";
@@ -53,6 +60,34 @@ export interface SpendGrant {
    * back to the approval that permitted it (§19.3 "explicit spend authorization").
    */
   decisionId: string;
+  /**
+   * What this grant authorizes spending **on** (§13.2, §4.2).
+   *
+   * Operation names are adopter-defined open strings — `"agent.execute"`, `"tts.synthesize"`.
+   * Core names none.
+   *
+   * Present so that handing the wrong grant to an execution gateway cannot authorize an unrelated
+   * operation. Without it, "a grant" is a pool of money with no statement about what it is for,
+   * and the only thing keeping agent spend out of a synthesis ledger is which `decisionId` each
+   * happened to carry.
+   */
+  scope: {
+    operations: readonly string[];
+  };
+  /**
+   * Whether an execution with no estimate may be dispatched (§13.2, §19.3; ADR-0044).
+   *
+   * Operator-approved policy, so it lives on the grant and is bound by
+   * {@link grantTermsDigest} — changing it invalidates the approval exactly as changing a ceiling
+   * or the scope does. It must never be supplied by an execution input or an adapter: a caller
+   * that could assert its own permission is the shape #107 exists to prevent.
+   *
+   * A closed pair rather than a boolean. `permitUnestimated: true` invites being flipped in a
+   * config file; naming the reservation it implies makes the consequence part of the decision.
+   *
+   * Absent reads as `"refuse"`.
+   */
+  unestimatedExecution?: "refuse" | "reserve_max_per_request";
   /** Maximum total spend authorized across the Run (§13.2 "maximum authorized cost"). */
   maxTotal: Money;
   /** Maximum spend authorized for any single request (§19.3 "per-request ... limits"). */
@@ -60,13 +95,21 @@ export interface SpendGrant {
 }
 
 /**
- * The digest a gate must bind for the grant's limits to be tamper-evident.
+ * The digest a gate must bind for the grant's **terms** to be tamper-evident (§13.2).
  *
- * Only the limits are digested, not the grant's identity: re-issuing an identical ceiling under a
- * new `grantId` should not read as the operator having approved something different.
+ * Was `grantTermsDigest`, covering the ceilings alone. Scope is now a term too: changing a grant
+ * from agent-only to TTS-capable widens what an approval permits exactly as raising its ceiling
+ * does, and an approval that survives that change did not bind what it appeared to bind.
+ *
+ * Only the terms are digested, not the grant's identity: re-issuing an identical grant under a new
+ * `grantId` should not read as the operator having approved something different.
  */
-export function grantLimitsDigest(grant: SpendGrant): string {
+export function grantTermsDigest(grant: SpendGrant): string {
   return digestSubjectValue({
+    // Sorted, because the *set* of authorized operations is the term, not the order an adopter
+    // listed them in — the same reason ADR-0033 sorts release input hashes.
+    scope: { operations: [...grant.scope.operations].sort() },
+    unestimatedExecution: grant.unestimatedExecution ?? "refuse",
     maxTotal: grant.maxTotal,
     maxPerRequest: grant.maxPerRequest ?? null,
   });
@@ -109,6 +152,36 @@ export interface SpendLedger {
   counted: CostRecord[];
   /** Cost records excluded because they were voided. */
   excluded: CostRecord[];
+  /**
+   * Charges whose amount nobody knows yet (§19.3; #150).
+   *
+   * A provider may charge a request and withhold or delay the figure. While one of these stands
+   * against a grant, **Aldus cannot prove how much authorization remains** — the charge is real
+   * and its size is not yet a fact.
+   *
+   * A record here is never treated as free, voided, or a zero draw. Zero is a numerical assertion;
+   * this is an uncertainty state, and the two are not interchangeable.
+   */
+  unresolvedUnknown: CostRecord[];
+  /**
+   * Whether {@link SpendLedger.remaining} is a number anyone may spend against.
+   *
+   * `false` while any unresolved unknown charge stands. `remaining` still reports the arithmetic
+   * over what is known, because an operator wants the figure — but presenting it as headroom
+   * would state a safe amount that nothing establishes.
+   */
+  remainingIsDeterminate: boolean;
+}
+
+/**
+ * Whether a record is a charge of unknown size (§19.3; #150).
+ *
+ * An estimate does not resolve it. An estimate is evidence about what a request was expected to
+ * cost, and the ruling on #150 is explicit that it does not confirm the final charge — so a record
+ * carrying both an estimate and `billingStatus: "unknown"` is still unresolved.
+ */
+export function isUnresolvedUnknownCharge(record: CostRecord): boolean {
+  return record.billingStatus === "unknown";
 }
 
 /**
@@ -136,12 +209,214 @@ export function computeLedger(grant: SpendGrant, costs: readonly CostRecord[]):
 
   const headroom = subtractMoney(grant.maxTotal, consumed);
   const overspent = isNegativeMoney(headroom);
+  const unresolvedUnknown = counted.filter(isUnresolvedUnknownCharge);
   return {
     consumed,
     remaining: overspent ? zeroMoney(currency) : headroom,
     overspent,
     counted,
     excluded,
+    unresolvedUnknown,
+    remainingIsDeterminate: unresolvedUnknown.length === 0,
+  };
+}
+
+/**
+ * Authorization available to commit, derived rather than maintained (ADR-0044; #155).
+ *
+ * ```text
+ * available = authorized maximum − settled charges − active reservations
+ * ```
+ *
+ * Derived on every read, never stored as a balance. A maintained counter is a second source of
+ * truth about money, reconciled by hand against the records it summarises — and every defect this
+ * repository has fixed in the cost path has been a value asserting more than what established it.
+ */
+export interface SpendAvailability {
+  /** The ceiling the operator approved. */
+  authorized: Money;
+  /** Charges already recorded against it. */
+  settled: Money;
+  /** Authorization committed to effects that have not settled. */
+  reserved: Money;
+  /**
+   * What may still be committed. Never negative.
+   *
+   * **Read {@link SpendAvailability.determinate} before spending against this.** The figure is the
+   * arithmetic over what is known, and while an unresolved charge of unknown size stands, what is
+   * known is not all there is.
+   */
+  available: Money;
+  /** Whether {@link SpendAvailability.available} is an amount anyone may commit against. */
+  determinate: boolean;
+  /**
+   * Why it is not, where it is not.
+   *
+   * Two independent sources, kept apart because they carry different evidence:
+   *
+   * - reservations in `billing_unknown` whose exposure is not bounded by an enforced ceiling;
+   * - cost records of unknown size with no reservation at all, which is every such record written
+   *   before this protocol existed (#150).
+   */
+  indeterminate: {
+    unboundedReservations: SpendReservation[];
+    unreservedUnknownCharges: CostRecord[];
+  };
+  /**
+   * Reserved-but-unsettled amounts, per **authorization** currency (ADR-0044).
+   *
+   * Not the provider's billing currency. This states what Aldus set aside; what a provider charged,
+   * and in what currency, is a separate fact that may not exist yet. A report may say "USD 2.00
+   * remains reserved because billing is unresolved"; it must never restate that as "the provider
+   * made an unknown USD charge".
+   */
+  reservedUnknownByCurrency: Record<string, string>;
+}
+
+/**
+ * Derive what a grant still authorizes (§19.3; ADR-0044).
+ *
+ * Composes with #150 rather than replacing it. A charge of unknown size still makes the grant
+ * indeterminate — what a reservation adds is the possibility of a *bound*, and only when the
+ * execution that produced the charge was actually dispatched under an enforced ceiling. A backend
+ * that declares enforcement today is not evidence about a request dispatched by an earlier version
+ * (ADR-0030).
+ */
+export function availableAuthorization(
+  grant: SpendGrant,
+  costs: readonly CostRecord[],
+  reservations: readonly SpendReservation[] = [],
+): SpendAvailability {
+  const currency = grant.maxTotal.currency;
+  const ledger = computeLedger(grant, costs);
+
+  // Per grant, never per decision. The grant is the budget pool; the decision is who authorized
+  // its terms. One decision may establish several grants — an episode-level ceiling above an agent
+  // grant and a TTS grant — and deriving availability per decision would silently aggregate them.
+  const mine = reservations.filter((reservation) => reservation.grantId === grant.grantId);
+  const active = mine.filter(reservationIsActive);
+
+  // Settled reservations are already represented by the cost records that settled them. Counting
+  // both would double-count the same money against the ceiling.
+  let reserved = zeroMoney(currency);
+  const reservedUnknownByCurrency = new Map<string, Money>();
+  for (const reservation of active) {
+    if (reservation.reserved.currency === currency) {
+      reserved = addMoney(reserved, reservation.reserved);
+    }
+    if (reservation.status === "billing_unknown") {
+      const running =
+        reservedUnknownByCurrency.get(reservation.reserved.currency) ??
+        zeroMoney(reservation.reserved.currency);
+      reservedUnknownByCurrency.set(
+        reservation.reserved.currency,
+        addMoney(running, reservation.reserved),
+      );
+    }
+  }
+
+  const unboundedReservations = active.filter(
+    (reservation) =>
+      reservation.status === "billing_unknown" && !reservationExposureIsBounded(reservation),
+  );
+  // #150's rule, narrowed by what a reservation can now establish. A record of unknown size whose
+  // reservation is bounded is accounted for; one with no reservation is not, and that is every
+  // such record written before this protocol.
+  const boundedReservationIds = new Set(
+    active
+      .filter((reservation) => reservationExposureIsBounded(reservation))
+      .map((reservation) => reservation.reservationId),
+  );
+  // `computeLedger` filters cost records by `authorizationId`, which is the legacy link and stays
+  // correct: a record written before reservations existed has no `reservationId` to reach a grant
+  // through, and its decision is the only thing tying it to an authorization (#155).
+  const unreservedUnknownCharges = ledger.counted.filter(
+    (record) =>
+      isUnresolvedUnknownCharge(record) &&
+      (record.reservationId === undefined || !boundedReservationIds.has(record.reservationId)),
+  );
+
+  const headroom = subtractMoney(subtractMoney(grant.maxTotal, ledger.consumed), reserved);
+  return {
+    authorized: grant.maxTotal,
+    settled: ledger.consumed,
+    reserved,
+    available: isNegativeMoney(headroom) ? zeroMoney(currency) : headroom,
+    determinate: unboundedReservations.length === 0 && unreservedUnknownCharges.length === 0,
+    indeterminate: { unboundedReservations, unreservedUnknownCharges },
+    reservedUnknownByCurrency: Object.fromEntries(
+      [...reservedUnknownByCurrency.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([code, money]) => [code, money.amount]),
+    ),
+  };
+}
+
+/**
+ * Whether a grant can truthfully permit an unestimated execution (ADR-0044; #155).
+ *
+ * `reserve_max_per_request` promises to reserve the per-request ceiling. A grant that permits it
+ * and states no such ceiling promises an amount it does not have — and reserving zero instead
+ * would make unestimated executions invisible to concurrency control, which is the case most
+ * likely to be dispatched in a loop.
+ *
+ * Checked at decode **and** before dispatch: a grant assembled from configuration never passes
+ * through the constructor that would have caught it.
+ */
+export function unestimatedPolicyIsSatisfiable(grant: SpendGrant): string | undefined {
+  if ((grant.unestimatedExecution ?? "refuse") !== "reserve_max_per_request") return undefined;
+  const ceiling = grant.maxPerRequest;
+  if (ceiling === undefined) {
+    return (
+      `Grant "${grant.grantId}" permits unestimated execution by reserving its per-request ` +
+      "ceiling, and states no ceiling. There is no truthful amount to reserve, so this cannot be " +
+      "dispatched (§13.2, §19.3)."
+    );
+  }
+  if (!isPositiveMoney(ceiling)) {
+    return (
+      `Grant "${grant.grantId}" permits unestimated execution by reserving its per-request ` +
+      `ceiling, and that ceiling is ${formatMoney(ceiling)}. Reserving zero would make an ` +
+      "unestimated execution invisible to concurrency control."
+    );
+  }
+  if (ceiling.currency !== grant.maxTotal.currency) {
+    return (
+      `Grant "${grant.grantId}" states a per-request ceiling in ${ceiling.currency} and a total ` +
+      `in ${grant.maxTotal.currency}. A reservation is denominated in the grant's currency, and ` +
+      "converting implicitly is not something this runtime does (ADR-0044)."
+    );
+  }
+  return undefined;
+}
+
+/** Why a grant does not authorize an operation. */
+export interface SpendScopeRefusal {
+  operation: string;
+  authorized: readonly string[];
+  explanation: string;
+}
+
+/**
+ * Whether a grant authorizes an operation (§13.2, §4.2; #155).
+ *
+ * Checked before reserving, so handing the wrong grant to an execution gateway cannot authorize
+ * unrelated work. Without it a grant is a pool of money with no statement about what it is for,
+ * and the only thing separating agent spend from a synthesis ledger is which decision each
+ * happened to name.
+ */
+export function checkSpendScope(
+  grant: SpendGrant,
+  operation: string,
+): SpendScopeRefusal | undefined {
+  if (grant.scope.operations.includes(operation)) return undefined;
+  return {
+    operation,
+    authorized: [...grant.scope.operations],
+    explanation:
+      `Grant "${grant.grantId}" authorizes ${grant.scope.operations.map((entry) => `"${entry}"`).join(", ") || "nothing"} ` +
+      `and this operation is "${operation}". A grant states what it may be spent on as well as ` +
+      "how much, so passing the wrong one to a gateway cannot authorize unrelated work (§13.2).",
   };
 }
 
@@ -155,7 +430,19 @@ export interface SpendRequest {
 
 /** Why a spend was refused. */
 export type SpendRefusalReason =
-  "per-request-limit" | "total-limit" | "already-overspent" | "negative-amount";
+  | "per-request-limit"
+  | "total-limit"
+  | "already-overspent"
+  | "negative-amount"
+  /**
+   * A charge of unknown size stands against this grant (§19.3; #150).
+   *
+   * Refused rather than allowed-with-a-warning: while the size of a real charge is unknown, the
+   * remaining headroom is not a fact, and spending against a figure nobody can establish is how a
+   * ceiling is exceeded without any single decision being wrong. Resolution is a reconciled amount
+   * or a new authorization under an explicit policy — both human acts.
+   */
+  | "billing-unconfirmed";
 
 /** The outcome of a stop-on-budget check. */
 export type SpendCheck =
@@ -197,6 +484,25 @@ export function checkSpend(
     };
   }
 
+  // Before the arithmetic, because the arithmetic is what cannot be trusted. While a charge of
+  // unknown size stands against this grant, `remaining` is the total over what is *known* — and
+  // spending against it would treat an unresolved charge as a zero draw, which is the one thing
+  // the ruling on #150 forbids (§19.3).
+  if (!ledger.remainingIsDeterminate) {
+    return {
+      allowed: false,
+      reason: "billing-unconfirmed",
+      ledger,
+      explanation:
+        `${ledger.unresolvedUnknown.length} charge(s) against this authorization have an ` +
+        "unconfirmed amount, so the remaining budget is indeterminate rather than " +
+        `${formatMoney(ledger.remaining)}. Automatic spend is refused until the amount is ` +
+        "reconciled or an operator issues a new authorization: an unknown charge is neither free " +
+        "nor zero, and drawing against a figure nobody can establish is how a ceiling is exceeded " +
+        "without any single decision being wrong (§19.3).",
+    };
+  }
+
   if (ledger.overspent) {
     return {
       allowed: false,