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

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.2",
+  "version": "0.2.0-next.21",
   "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.2"
+    "@aldus-runtime/core": "0.2.0-next.21"
   },
   "devDependencies": {
-    "@aldus-runtime/testkit": "0.2.0-next.2",
+    "@aldus-runtime/testkit": "0.2.0-next.21",
     "@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 =

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;
   /**
@@ -314,12 +332,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 +551,7 @@ export class GateEngine {
       };
     }
 
-    if (!decision.subjectHashes.includes(grantLimitsDigest(grant))) {
+    if (!decision.subjectHashes.includes(grantTermsDigest(grant))) {
       return {
         authorized: false,
         statuses: [status],

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,