@aldus-runtime/gate-engine 0.2.0-next.5 → 0.2.0-next.50

package/dist/spend.d.ts

@@ -11,12 +11,12 @@
  * `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 { type CostRecord, type Money, type SpendReservation } from "@aldus-runtime/core";
 /**
  * The subject key under which a grant's limits are bound.
  *
@@ -40,18 +40,89 @@ 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 declare function grantLimitsDigest(grant: SpendGrant): string;
+export declare function grantTermsDigest(grant: SpendGrant): string;
 /**
  * Whether a cost record consumes budget.
  *
@@ -82,7 +153,34 @@ 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 declare function isUnresolvedUnknownCharge(record: CostRecord): boolean;
 /**
  * Total what has been drawn against a grant.
  *
@@ -91,6 +189,94 @@ export interface SpendLedger {
  * silently absorbing it would make one gate's ceiling depend on another's spending.
  */
 export declare function computeLedger(grant: SpendGrant, costs: readonly CostRecord[]): SpendLedger;
+/**
+ * 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 declare function availableAuthorization(grant: SpendGrant, costs: readonly CostRecord[], reservations?: readonly SpendReservation[]): SpendAvailability;
+/**
+ * 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 declare function unestimatedPolicyIsSatisfiable(grant: SpendGrant): string | 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 declare function checkSpendScope(grant: SpendGrant, operation: string): SpendScopeRefusal | undefined;
 /** A request to spend against a grant. */
 export interface SpendRequest {
     /** The amount about to be committed. */
@@ -99,7 +285,16 @@ export interface SpendRequest {
     operation?: string;
 }
 /** Why a spend was refused. */
-export type SpendRefusalReason = "per-request-limit" | "total-limit" | "already-overspent" | "negative-amount";
+export type SpendRefusalReason = "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 = {
     allowed: true;

package/dist/spend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spend.d.ts","sourceRoot":"","sources":["../src/spend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAY7D;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,eAAe,CAAC;AAEpD,8FAA8F;AAC9F,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,uFAAuF;IACvF,QAAQ,EAAE,KAAK,CAAC;IAChB,wFAAwF;IACxF,aAAa,CAAC,EAAE,KAAK,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAK3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAG1E;AAED,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,QAAQ,EAAE,KAAK,CAAC;IAChB,8EAA8E;IAC9E,SAAS,EAAE,KAAK,CAAC;IACjB,yDAAyD;IACzD,SAAS,EAAE,OAAO,CAAC;IACnB,mDAAmD;IACnD,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,sDAAsD;IACtD,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,WAAW,CAyB1F;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,MAAM,EAAE,KAAK,CAAC;IACd,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,+BAA+B;AAC/B,MAAM,MAAM,kBAAkB,GAC5B,mBAAmB,GAAG,aAAa,GAAG,mBAAmB,GAAG,iBAAiB,CAAC;AAEhF,6CAA6C;AAC7C,MAAM,MAAM,UAAU,GAClB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,cAAc,EAAE,KAAK,CAAA;CAAE,GAC7D;IACE,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEN;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,OAAO,EAAE,YAAY,GACpB,UAAU,CAsDZ"}
+{"version":3,"file":"spend.d.ts","sourceRoot":"","sources":["../src/spend.ts"],"names":[],"mappings":"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"}

package/dist/spend.js

@@ -11,13 +11,14 @@
  * `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 { reservationExposureIsBounded, reservationIsActive, } from "@aldus-runtime/core";
 import { digestSubjectValue } from "./binding.js";
-import { addMoney, compareMoney, formatMoney, isNegativeMoney, subtractMoney, zeroMoney, } from "./money.js";
+import { addMoney, compareMoney, formatMoney, isNegativeMoney, isPositiveMoney, subtractMoney, zeroMoney, } from "./money.js";
 /**
  * The subject key under which a grant's limits are bound.
  *
@@ -27,13 +28,21 @@ import { addMoney, compareMoney, formatMoney, isNegativeMoney, subtractMoney, ze
  */
 export const SPEND_LIMIT_SUBJECT_KEY = "spendLimit";
 /**
- * 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) {
+export function grantTermsDigest(grant) {
     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,
     });
@@ -62,6 +71,16 @@ export function costRecordDraw(record, currency) {
         return zeroMoney(currency);
     return record.actual ?? record.estimated ?? zeroMoney(currency);
 }
+/**
+ * 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) {
+    return record.billingStatus === "unknown";
+}
 /**
  * Total what has been drawn against a grant.
  *
@@ -85,12 +104,122 @@ export function computeLedger(grant, costs) {
     }
     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,
+    };
+}
+/**
+ * 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, costs, reservations = []) {
+    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();
+    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) {
+    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;
+}
+/**
+ * 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, operation) {
+    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).",
     };
 }
 /**
@@ -116,6 +245,23 @@ export function checkSpend(grant, costs, request) {
                 "cost record, not as a negative draw, so that the audit trail keeps the original charge.",
         };
     }
+    // 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,

package/dist/spend.js.map

@@ -1 +1 @@
-{"version":3,"file":"spend.js","sourceRoot":"","sources":["../src/spend.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"spend.js","sourceRoot":"","sources":["../src/spend.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aldus-runtime/gate-engine",
-  "version": "0.2.0-next.5",
+  "version": "0.2.0-next.50",
   "type": "module",
   "description": "Aldus Gate Engine — hash-bound human gates, cascading invalidation, and spend authorization.",
   "license": "Apache-2.0",
@@ -33,10 +33,10 @@
     "typecheck:test": "tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "@aldus-runtime/core": "0.2.0-next.5"
+    "@aldus-runtime/core": "0.2.0-next.50"
   },
   "devDependencies": {
-    "@aldus-runtime/testkit": "0.2.0-next.5",
+    "@aldus-runtime/testkit": "0.2.0-next.50",
     "@types/node": "^26.2.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"

package/src/definition.ts

@@ -15,6 +15,14 @@
  */
 
 import type { ActorKind } from "@aldus-runtime/core";
+import {
+  QUALITY_ENFORCEMENTS,
+  QUALITY_LEVELS,
+  validateQualityClaim,
+  type PromotionEvidence,
+  type QualityEnforcement,
+  type QualityLevel,
+} from "@aldus-runtime/core";
 
 import { GateEngineErrorCodes, gateEngineError } from "./errors.js";
 
@@ -26,32 +34,29 @@ import { GateEngineErrorCodes, gateEngineError } from "./errors.js";
  * does not, and a model-assisted review may do either depending on whether it has been
  * calibrated (§12.1).
  */
-export const GATE_LEVELS = [
-  /** Blocks on an objectively testable failure (§12 level 1). */
-  "hard_gate",
-  /** Reports a possible issue without blocking (§12 level 2). */
-  "advisory_signal",
-  /** Evaluates meaning, stance, style, or claims under uncertainty (§12 level 3). */
-  "model_assisted",
-  /** A human owns the judgement, because it is subjective or asymmetric-risk (§12 level 4). */
-  "human_oracle",
-] as const;
+/**
+ * @deprecated in name only — the concept moved to Core (#115) and this is the gate-shaped alias.
+ *
+ * §12's levels are a property of any quality mechanism, not of gates. They lived here alone until
+ * an adopter's blocking evaluator turned out to be a Stage, which could declare none of this. The
+ * canonical definition is `QUALITY_LEVELS`; this name is kept because published code consumes it.
+ */
+export const GATE_LEVELS = QUALITY_LEVELS;
 
 /** @see GATE_LEVELS */
-export type GateLevel = (typeof GATE_LEVELS)[number];
+export type GateLevel = QualityLevel;
 
 /**
- * Whether a gate stops work or merely reports.
+ * Whether a gate stops work or merely reports. The gate-shaped alias of `QUALITY_ENFORCEMENTS`.
  *
- * Deliberately a two-state enumeration rather than a boolean. Contract §12.1 permits an
- * evaluator to *become* blocking only after calibration, which makes this a promotion with
- * evidence behind it — and a field named `blocking: boolean` invites someone to flip it in a
- * config file without producing any.
+ * Still a two-state enumeration rather than a boolean, for the reason Core records: §12.1 makes
+ * blocking a promotion with evidence behind it, and `blocking: boolean` invites someone to flip it
+ * in a config file without producing any.
  */
-export const GATE_ENFORCEMENTS = ["blocking", "advisory"] as const;
+export const GATE_ENFORCEMENTS = QUALITY_ENFORCEMENTS;
 
 /** @see GATE_ENFORCEMENTS */
-export type GateEnforcement = (typeof GATE_ENFORCEMENTS)[number];
+export type GateEnforcement = QualityEnforcement;
 
 /**
  * Evidence that a model-assisted evaluator was calibrated before it was allowed to block.
@@ -65,14 +70,7 @@ export type GateEnforcement = (typeof GATE_ENFORCEMENTS)[number];
  * scope among what promotion must consider, because an evaluator calibrated on one host says
  * nothing about another. Dimensions are caller-supplied (§4.2), consistent with WP-09's packs.
  */
-export interface PromotionEvidence {
-  /** Identifier of the calibration report that justified promotion (WP-10). */
-  reportRef: string;
-  /** Scope the calibration covers, e.g. `{ host: "example-host", voice: "voice-a" }`. */
-  scope: Record<string, string>;
-  /** Known blind spots recorded at promotion time (§12.1, §9.3). */
-  knownBlindSpots?: string[];
-}
+export type { PromotionEvidence };
 
 /**
  * One configured gate.
@@ -196,15 +194,15 @@ export function validateGateDefinition(definition: GateDefinition): ResolvedGate
     fail("A gate cannot depend on itself.");
   }
 
-  if (definition.level === "model_assisted" && definition.enforcement === "blocking") {
-    if (definition.promotionEvidence === undefined) {
-      fail(
-        "A model-assisted gate may only block once it has been calibrated against human-labeled " +
-          "examples (contract §12.1). Set `promotionEvidence`, or leave the gate advisory. " +
-          "Contract §12 forbids presenting a machine pass as semantic correctness.",
-        { level: definition.level, enforcement: definition.enforcement },
-      );
-    }
+  // The shared rule, not a second copy of it (#115). A gate and an evaluator Stage making the same
+  // claim are refused for the same reasons in the same words; two implementations of one clause
+  // is how §12 came to be enforced in one place and not the other.
+  for (const problem of validateQualityClaim({
+    level: definition.level,
+    enforcement: definition.enforcement,
+    promotionEvidence: definition.promotionEvidence,
+  })) {
+    fail(problem.message, { level: definition.level, enforcement: definition.enforcement });
   }
 
   const permittedActorKinds =