@aldus-runtime/gate-engine 0.2.0-next.4 → 0.2.0-next.41

package/src/engine.ts

@@ -35,7 +35,7 @@ import { GateEngineErrorCodes, gateEngineError } from "./errors.js";
 import type { CostReader, GateDecisionStore, GateEventSink } from "./ports.js";
 import {
   checkSpend,
-  grantLimitsDigest,
+  grantTermsDigest,
   type SpendCheck,
   type SpendGrant,
   type SpendRequest,
@@ -73,6 +73,13 @@ export const GATE_STATES = [
 export type GateState = (typeof GATE_STATES)[number];
 
 /** The evaluated state of one gate. */
+/** `"a"`, `"a and b"`, `"a, b and c"` — for a sentence an operator reads, not a log line. */
+function formatKeys(keys: readonly string[]): string {
+  const quoted = keys.map((key) => `"${key}"`);
+  if (quoted.length <= 1) return quoted[0] ?? "";
+  return `${quoted.slice(0, -1).join(", ")} and ${quoted[quoted.length - 1] as string}`;
+}
+
 export interface GateStatus {
   gateId: string;
   state: GateState;
@@ -86,6 +93,17 @@ export interface GateStatus {
   drift?: SubjectDrift;
   /** Gates that blocked this one, when `state` is `blocked_upstream`. */
   blockedBy?: string[];
+  /**
+   * Bound values nobody has supplied yet, when the gate is otherwise decidable (#91).
+   *
+   * §13.2 requires an authorization to bind every listed value, so a gate whose subjects are
+   * only partly supplied cannot be approved — `assertSubjectsCover` refuses it. Reported here so
+   * that a caller can say why before offering the decision, rather than recommending a command
+   * that will be rejected.
+   *
+   * Absent when every bound value is present, which is the ordinary case.
+   */
+  missingSubjects?: string[];
   /** Operator-facing explanation of why work may not proceed past this gate. */
   explanation?: string;
   /**
@@ -120,6 +138,15 @@ export interface DecideInput {
   comment?: string;
   /** Canonical Episode identity, for the emitted event (§6.4). */
   episodeId: string;
+  /**
+   * Present when the decider did not write this record themselves (§19.2).
+   *
+   * Supplied by the composition, which knows the acting actor. The engine's job is to refuse a
+   * transcription that names the decider as its own transcriber — that is not a transcription,
+   * it is the ordinary case wearing an extra field, and letting it through would make the field
+   * mean nothing wherever it appeared.
+   */
+  transcription?: GateDecision["transcription"];
   /** Overrides the gate's default. Defaults to the definition's `expiresOnChange`. */
   expiresOnChange?: boolean;
   /** Supplied for deterministic tests; defaults to a fresh ULID-based id. */
@@ -220,6 +247,58 @@ export class GateEngine {
       );
     }
 
+    // A transcription names someone **other** than the decider. Recording the decider as their own
+    // transcriber says nothing and would make the field unreadable wherever it did appear: a reader
+    // could no longer tell a transcribed decision from one that carried the field by habit.
+    if (
+      input.transcription !== undefined &&
+      input.transcription.recordedBy.kind === input.decidedBy.kind &&
+      input.transcription.recordedBy.id === input.decidedBy.id
+    ) {
+      throw gateEngineError(
+        GateEngineErrorCodes.GATE_TRANSCRIPTION_INVALID,
+        `The decision for gate "${gate.gateId}" records the decider as its own transcriber. A ` +
+          "transcription exists to say that someone else wrote the record down; naming the same " +
+          "actor for both says nothing and makes the field unreadable where it is real (§19.2).",
+        { category: "validation", details: { gateId: gate.gateId } },
+      );
+    }
+
+    // A waiver is not an approval, and the two refusals below are what keep it from becoming one.
+    //
+    // **It must not outlive the content it was granted against.** `expiresOnChange` is a per-
+    // decision override of the gate's default, which is defensible for an *approval* whose subject
+    // cannot drift. A non-expiring **waiver** says the check stays bypassed whatever the content
+    // becomes — that is a config flag disabling a gate, reached through the decision API instead of
+    // the config file, and it is precisely what this design exists to avoid.
+    //
+    // Closing it is also what makes the rest safe. Every gate being waivable — `release.public`
+    // included — is defensible **only** because a waiver cannot survive the subjects moving. Leave
+    // the override open and every gate needs a non-waivable declaration; close it and none does.
+    //
+    // **And it must say why.** A waiver with no reason is a blank with a timestamp: the one thing a
+    // reader of the approvals log needs from it is the part that would be missing.
+    if (input.decision === "waived") {
+      if (input.expiresOnChange === false) {
+        throw gateEngineError(
+          GateEngineErrorCodes.GATE_WAIVER_INVALID,
+          `A waiver of gate "${gate.gateId}" may not be recorded as non-expiring. A waiver says ` +
+            "the check was bypassed rather than passed, so it must not outlive the content it was " +
+            "granted against (§13.1, §13.2).",
+          { category: "policy", details: { gateId: gate.gateId } },
+        );
+      }
+      if (input.comment === undefined || input.comment.trim() === "") {
+        throw gateEngineError(
+          GateEngineErrorCodes.GATE_WAIVER_INVALID,
+          `A waiver of gate "${gate.gateId}" needs a reason. An approval records that the content ` +
+            "was judged; a waiver records that the check was bypassed, and without a reason the " +
+            "log carries a blank with a timestamp (§13.3, §19.2).",
+          { category: "validation", details: { gateId: gate.gateId } },
+        );
+      }
+    }
+
     const decision: GateDecision = {
       schemaVersion: SCHEMA_VERSION,
       decisionId: input.decisionId ?? newGateDecisionId(),
@@ -230,7 +309,10 @@ export class GateEngine {
       decidedBy: input.decidedBy,
       decidedAt: input.decidedAt,
       ...(input.comment !== undefined ? { comment: input.comment } : {}),
-      expiresOnChange: input.expiresOnChange ?? gate.expiresOnChange,
+      ...(input.transcription === undefined ? {} : { transcription: input.transcription }),
+      // Forced for a waiver, never taken from the gate default or the caller. See above.
+      expiresOnChange:
+        input.decision === "waived" ? true : (input.expiresOnChange ?? gate.expiresOnChange),
     };
 
     // Validate before persisting. A malformed decision written to the approvals log is worse
@@ -314,12 +396,24 @@ export class GateEngine {
     // machines with disagreeing clocks must not be able to reorder which approval is current.
     const latest = [...decisions].reverse().find((entry) => entry.gateId === gate.gateId);
 
+    const suppliedKeys = new Set(subjects.map((entry) => entry.key));
+    const missingSubjects = gate.binds.filter((key) => !suppliedKeys.has(key));
+
     if (latest === undefined) {
       return {
         ...base,
         state: "pending",
         blocking: blocks("pending"),
-        explanation: `Gate "${gate.gateId}" has no recorded decision.`,
+        // Naming the missing values rather than only the absence of a decision: an operator told
+        // "no recorded decision" goes looking for who forgot to approve, when the answer is that
+        // nothing has produced what the approval would bind (§13.2).
+        explanation:
+          missingSubjects.length > 0
+            ? `Gate "${gate.gateId}" has no recorded decision, and ` +
+              `${formatKeys(missingSubjects)} ${missingSubjects.length === 1 ? "has" : "have"} ` +
+              "not been supplied, so it cannot be decided yet."
+            : `Gate "${gate.gateId}" has no recorded decision.`,
+        ...(missingSubjects.length > 0 ? { missingSubjects } : {}),
       };
     }
 
@@ -521,7 +615,7 @@ export class GateEngine {
       };
     }
 
-    if (!decision.subjectHashes.includes(grantLimitsDigest(grant))) {
+    if (!decision.subjectHashes.includes(grantTermsDigest(grant))) {
       return {
         authorized: false,
         statuses: [status],

package/src/errors.ts

@@ -32,6 +32,21 @@ export const GateEngineErrorCodes = {
   GATE_ACTOR_NOT_PERMITTED: "ALDUS_GATE_ACTOR_NOT_PERMITTED",
   /** A decision was submitted that does not bind the subjects its gate requires. */
   GATE_SUBJECTS_INCOMPLETE: "ALDUS_GATE_SUBJECTS_INCOMPLETE",
+  /**
+   * A waiver was recorded without a reason, or asked not to expire when its subjects change.
+   *
+   * Both refusals exist because a waiver is not an approval. An approval says the content was
+   * judged and passed; a waiver says the check was **bypassed** — so it must say why, and it must
+   * not outlive the content it was granted against.
+   */
+  GATE_WAIVER_INVALID: "ALDUS_GATE_WAIVER_INVALID",
+  /**
+   * A decision named the decider as its own transcriber.
+   *
+   * `transcription` exists to record that someone **else** wrote the decision down. Naming the
+   * same actor for both says nothing, and it would make the field unreadable where it is real.
+   */
+  GATE_TRANSCRIPTION_INVALID: "ALDUS_GATE_TRANSCRIPTION_INVALID",
   /**
    * An operation requiring authorization was attempted without a valid one.
    *

package/src/index.ts

@@ -66,11 +66,16 @@ export {
 
 export {
   SPEND_LIMIT_SUBJECT_KEY,
+  availableAuthorization,
+  checkSpendScope,
+  unestimatedPolicyIsSatisfiable,
   checkSpend,
   computeLedger,
   consumesBudget,
   costRecordDraw,
-  grantLimitsDigest,
+  grantTermsDigest,
+  type SpendAvailability,
+  type SpendScopeRefusal,
   type SpendCheck,
   type SpendGrant,
   type SpendLedger,

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,20 +60,95 @@ export interface SpendGrant {
    * back to the approval that permitted it (§19.3 "explicit spend authorization").
    */
   decisionId: string;
-  /** Maximum total spend authorized across the Run (§13.2 "maximum authorized cost"). */
+  /**
+   * 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").
+   *
+   * **Two different things consume it**, and confusing them mis-sizes a grant in either direction:
+   *
+   * - **settled charges**, permanently — the actual `CostRecord` amounts;
+   * - **active and unresolved reservations**, at their *reserved* amount until they settle.
+   *
+   * `availableAuthorization` is `maxTotal − settled − active`, and on settlement a reservation
+   * stops being counted at what it reserved and starts being counted at what it actually cost —
+   * so **unused headroom returns**.
+   *
+   * That matters under `unestimatedExecution: "reserve_max_per_request"`, where each unestimated
+   * dispatch reserves the *whole* per-request ceiling because there is no smaller truthful number.
+   * `maxTotal ÷ maxPerRequest` bounds how many such dispatches can be **outstanding at once** — in
+   * flight, or with billing still unresolved. It does **not** bound the run: once they settle
+   * below the ceiling the difference is available again, and a $25 / $3 grant can authorize far
+   * more than eight sequential dispatches when each settles cheaply.
+   *
+   * Both readings mis-size a grant. Read as a lifetime pool it ignores that eight worst-case
+   * reservations can be outstanding before any of them settles; read as a concurrency bound alone
+   * it over-provisions a run whose charges are small. Measured by an adopter: a $3 / $3 grant
+   * permitted one dispatch and refused a case dispatching twice, with the budget almost untouched
+   * — because the first had not settled yet.
+   */
   maxTotal: Money;
-  /** Maximum spend authorized for any single request (§19.3 "per-request ... limits"). */
+  /**
+   * Maximum spend authorized for any single request (§19.3 "per-request ... limits").
+   *
+   * **What this means changed with ADR-0044 while its type did not.** It was a statement about
+   * what a *backend* enforces, so leaving it unset where the backend enforces nothing was the
+   * honest choice — binding a ceiling would have recorded a protection that did not exist.
+   *
+   * It is now what the *runtime reserves* before dispatch. Unset is still valid and still
+   * compiles, and under `unestimatedExecution: "reserve_max_per_request"` it makes every
+   * unestimated dispatch refuse, because there is no truthful amount to reserve
+   * (see {@link unestimatedPolicyIsSatisfiable}).
+   *
+   * Called out because the type system has nothing to say about a field whose meaning moved: an
+   * adopter migrating hit exactly this, and the comment in their own file argued for the choice
+   * that is now wrong.
+   */
   maxPerRequest?: Money;
 }
 
 /**
- * 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).
+ *
+ * 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 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.
+ * 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 +191,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 +248,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 +469,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 +523,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,