@trazum/core 1.64.0 → 1.66.0

package/src/config-schema.ts

@@ -137,6 +137,34 @@ export interface SpendConfig {
   substitute?: Record<string, { to: string; reason: string }>;
 }
 
+/**
+ * The enforcement policy: USD ceilings judged at call time, at whichever door
+ * the call arrives — the gateway's 402, `serve`'s cost answer, `spend_guard`
+ * over MCP.
+ *
+ * A separate block from `spend`, and the separation is the point. `spend`
+ * gates *reports*: it is read after the fact, over a log or a store, and a
+ * crossing fails a check. This is read *before a call is made*, to refuse it.
+ * Same units, different moments — and the 1.62 arc's lesson is that two
+ * surfaces reading "the same" value from different slices of config is how
+ * they come to disagree about how much is left. One block, stated once,
+ * enforced identically at every door.
+ *
+ * Every ceiling is a **positive** dollar amount. `spend` accepts zero because
+ * a zero report-budget is a gate somebody can waive on the record; a zero
+ * enforcement ceiling is a door that refuses everything, which is an outage
+ * dressed as a policy — if the intent is "stop all calls", turning the door
+ * off is the honest spelling.
+ */
+export interface LimitsConfig {
+  /** Ceiling per UTC calendar day, in dollars, measured across the store. */
+  dayUsd?: number;
+  /** Ceiling per session — the unit an agent product actually blows up in. */
+  sessionUsd?: number;
+  /** Per-label ceilings, each judged against that label's own measured spend. */
+  byLabel?: Record<string, number>;
+}
+
 export interface TrazumConfig {
   level?: RuleLevel;
   locale?: Locale;
@@ -182,6 +210,7 @@ export interface TrazumConfig {
    */
   sources?: Record<string, string[]>;
   spend?: SpendConfig;
+  limits?: LimitsConfig;
   /**
    * Findings as policy: a gate failure the team has looked at and decided to
    * live with, on the record, for a bounded time.
@@ -298,6 +327,7 @@ export const CONFIG_KEYS = [
   'budgets',
   'labels',
   'spend',
+  'limits',
   'sources',
   'store',
   'waive',
@@ -315,6 +345,8 @@ export const CONFIG_BASELINE_KEYS = ['path', 'maxGrowthTokens', 'maxGrowthPct']
 
 export const CONFIG_SPEND_KEYS = ['maxUsd', 'monthlyUsd', 'maxDayUsd', 'maxSessionUsd', 'maxCacheLossUsd', 'byLabel', 'bySource', 'substitute'] as const;
 
+export const CONFIG_LIMITS_KEYS = ['dayUsd', 'sessionUsd', 'byLabel'] as const;
+
 export const CONFIG_WAIVE_KEYS = ['gate', 'reason', 'until'] as const;
 
 export const CONFIG_STORE_KEYS = ['keepDays'] as const;
@@ -590,6 +622,53 @@ function parseSpend(raw: unknown, source: string): SpendConfig {
   return spend;
 }
 
+/**
+ * Validates the `limits` block.
+ *
+ * Every ceiling must be a **positive** finite number of dollars — stricter
+ * than `spend`, deliberately. A report-budget of zero is a gate somebody can
+ * waive on the record; an enforcement ceiling of zero refuses every call at
+ * that door, which is an outage dressed as a policy, so the error says what
+ * to write instead. Unknown keys are named rather than ignored, because a
+ * misspelled ceiling is a policy that is never enforced while CI stays green.
+ */
+function requirePositiveUsd(value: unknown, label: string, source: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    throw new ConfigError(
+      `"${label}" must be a positive number of dollars. A ceiling of 0 would refuse every call at this door — if that is the intent, turn the door off rather than writing an outage as a policy.`,
+      source,
+    );
+  }
+  return value;
+}
+
+export function parseLimits(raw: unknown, source: string): LimitsConfig {
+  if (!isPlainObject(raw)) throw new ConfigError('"limits" must be an object', source);
+  rejectUnknownKeys(raw, CONFIG_LIMITS_KEYS, source, 'limits.');
+
+  const limits: LimitsConfig = {};
+  if (raw.dayUsd !== undefined) {
+    limits.dayUsd = requirePositiveUsd(raw.dayUsd, 'limits.dayUsd', source);
+  }
+  if (raw.sessionUsd !== undefined) {
+    limits.sessionUsd = requirePositiveUsd(raw.sessionUsd, 'limits.sessionUsd', source);
+  }
+  if (raw.byLabel !== undefined) {
+    if (!isPlainObject(raw.byLabel)) {
+      throw new ConfigError('"limits.byLabel" must be an object', source);
+    }
+    const byLabel: Record<string, number> = {};
+    for (const [label, value] of Object.entries(raw.byLabel)) {
+      if (label.trim().length === 0) {
+        throw new ConfigError('"limits.byLabel" has an empty label', source);
+      }
+      byLabel[label] = requirePositiveUsd(value, `limits.byLabel["${label}"]`, source);
+    }
+    limits.byLabel = byLabel;
+  }
+  return limits;
+}
+
 /**
  * Validates the `sources` block: named services, each a non-empty list of
  * glob patterns. Patterns are not checked against a filesystem here — a
@@ -869,7 +948,7 @@ function parseStore(raw: unknown, source: string): { keepDays?: number } {
   return out;
 }
 
-function parseWaive(raw: unknown, source: string): WaiveEntry[] {
+export function parseWaive(raw: unknown, source: string): WaiveEntry[] {
   if (!Array.isArray(raw)) throw new ConfigError('"waive" must be an array', source);
   return raw.map((entry, index) => {
     const at = `waive[${index}]`;
@@ -882,10 +961,16 @@ function parseWaive(raw: unknown, source: string): WaiveEntry[] {
     }
     const known =
       (WAIVABLE_GATES as readonly string[]).includes(gate) ||
-      (gate.startsWith('byLabel:') && gate.length > 'byLabel:'.length);
+      (gate.startsWith('byLabel:') && gate.length > 'byLabel:'.length) ||
+      // The limits policy's ceilings, waivable since the 1.66 arc: silencing
+      // a limit leaves a record, and the doors carry the waiver in every
+      // judgement rather than refusing. The forms mirror the config keys.
+      gate === 'limits.dayUsd' ||
+      gate === 'limits.sessionUsd' ||
+      (gate.startsWith('limits.byLabel:') && gate.length > 'limits.byLabel:'.length);
     if (!known) {
       throw new ConfigError(
-        `"${at}.gate" names no gate: "${gate}". Waivable: ${WAIVABLE_GATES.join(', ')}, or byLabel:<label>.`,
+        `"${at}.gate" names no gate: "${gate}". Waivable: ${WAIVABLE_GATES.join(', ')}, byLabel:<label>, limits.dayUsd, limits.sessionUsd, or limits.byLabel:<label>.`,
         source,
       );
     }
@@ -1056,6 +1141,7 @@ export function parseConfig(raw: string, source = CONFIG_FILENAME): TrazumConfig
   if (document.budgets !== undefined) config.budgets = parseBudgets(document.budgets, source);
   if (document.labels !== undefined) config.labels = parseLabels(document.labels, source);
   if (document.spend !== undefined) config.spend = parseSpend(document.spend, source);
+  if (document.limits !== undefined) config.limits = parseLimits(document.limits, source);
   if (document.sources !== undefined) config.sources = parseSources(document.sources, source);
   if (document.store !== undefined) config.store = parseStore(document.store, source);
   if (document.waive !== undefined) config.waive = parseWaive(document.waive, source);

package/src/conform.ts

@@ -37,14 +37,21 @@
 export const CONTRACT_NAMES = [
   'usage-log',
   'profile',
+  'fleet',
   'plan',
   'verification',
   'history',
   'connected',
   'cost-answer',
+  'spend-guard',
   'outcome-report',
   'annual-record',
   'roll-up',
+  'first-run',
+  'pulse',
+  'rule-yield',
+  'gateway-refusal',
+  'bench',
   'prompt-draft',
 ] as const;
 
@@ -356,6 +363,49 @@ const DOCUMENT_RULES: Record<Exclude<ContractName, 'usage-log'>, FieldRule[]> =
       (v) => v === null || isObject(v),
     ),
   ],
+
+  /*
+    The seven below existed as documented tables for releases before they had
+    names here. "All eighteen are contracts" was narrower in the product than
+    on the page — a claim `docs/format.md` made that `--contract` could not
+    honour — and the 1.65 arc exists to close exactly that gap.
+  */
+  fleet: [
+    rule('bySource', 'an array — one entry per configured source with traffic', isArray),
+    rule('rollup', 'an object — the fleet read as one thing, sums inside it', isObject),
+  ],
+  'spend-guard': [
+    rule('verdict', 'yes, no or cannot-tell — and cannot-tell never becomes yes', (v) => typeof v === 'string'),
+    rule('cost', 'the full cost answer, halves and provenance intact', isObject),
+    rule('alternatives', 'an array, dearest saving first — a refusal never arrives bare', isArray),
+    rule('because', 'one line for a human reading a log — never the only place a fact appears', (v) => typeof v === 'string'),
+  ],
+  'first-run': [
+    rule('config', 'exactly the keys init could justify, and nothing else', isObject),
+    rule('justified', 'an array — one entry per key written, with the observation behind it', isArray),
+    rule('declined', 'an array — one entry per key left out, each with a typed why', isArray),
+  ],
+  pulse: [
+    rule('beats', 'an array — one per kind', isArray),
+    rule('nowMs', 'the instant the ages were taken against', isNumber),
+    rule('stale', 'a boolean — never true for never-run', (v) => typeof v === 'boolean'),
+  ],
+  'rule-yield': [
+    rule('rules', 'an array — per rule, alone and marginal both', isArray),
+    rule('tokensBefore', 'a number', isNumber),
+    rule('tokensSaved', 'a number — the whole run minus floor', isNumber),
+    rule('floor', 'a number, named rather than folded in', isNumber),
+  ],
+  'gateway-refusal': [
+    rule('error', 'an object shaped like a provider error, typed so it cannot be mistaken for one', isObject),
+    rule('reason', 'budget-exhausted, call-would-cross or cannot-tell-and-closed', (v) => typeof v === 'string'),
+    rule('alternatives', 'an array — a refusal never arrives bare', isArray),
+  ],
+  bench: [
+    rule('workloads', 'an array — one per standard workload, in a fixed order', isArray),
+    rule('node', 'the runtime the numbers were taken on', (v) => typeof v === 'string'),
+    rule('cpus', 'a number', isNumber),
+  ],
 };
 
 /**
@@ -467,7 +517,25 @@ function contractOf(doc: Record<string, unknown>): Exclude<ContractName, 'usage-
   // first would classify every roll-up as a profile, accept it as conformant,
   // and never apply the two refusals that only a roll-up has to carry.
   if (Array.isArray(doc.contributors) && Array.isArray(doc.notMerged)) return 'roll-up';
+  // Before the profile check, same reasoning as the roll-up: a fleet document
+  // is a list of full profile reports, and any looser ordering would classify
+  // it by the shape of what it contains rather than what it is.
+  if (Array.isArray(doc.bySource) && isObject(doc.rollup)) return 'fleet';
   if (Array.isArray(doc.byLabelAndModel)) return 'profile';
+  // Before the cost answer: a spend-guard verdict *contains* a cost answer,
+  // and `verdict` is a string on both documents.
+  if (typeof doc.verdict === 'string' && isObject(doc.cost) && Array.isArray(doc.alternatives)) {
+    return 'spend-guard';
+  }
+  if (isObject(doc.config) && Array.isArray(doc.justified) && Array.isArray(doc.declined)) {
+    return 'first-run';
+  }
+  if (Array.isArray(doc.beats) && typeof doc.nowMs === 'number') return 'pulse';
+  if (Array.isArray(doc.rules) && typeof doc.floor === 'number') return 'rule-yield';
+  if (isObject(doc.error) && typeof doc.reason === 'string' && Array.isArray(doc.alternatives)) {
+    return 'gateway-refusal';
+  }
+  if (Array.isArray(doc.workloads) && typeof doc.node === 'string') return 'bench';
   if (Array.isArray(doc.missingMonths) && isObject(doc.promises)) return 'annual-record';
   if (Array.isArray(doc.undeclared) && isObject(doc.coverage)) return 'outcome-report';
   if (Array.isArray(doc.periods) && Array.isArray(doc.runs)) return 'history';
@@ -478,6 +546,17 @@ function contractOf(doc: Record<string, unknown>): Exclude<ContractName, 'usage-
   return null;
 }
 
+/**
+ * The required top-level fields of a named contract, as `conform` enforces
+ * them — the single source the JSON Schemas are held to. `schemaVersion` is
+ * checked separately by `conform` and is not in this list; the usage log's
+ * one requirement is the model, same as the line parser's.
+ */
+export function requiredFieldsOf(name: ContractName): string[] {
+  if (name === 'usage-log') return ['model'];
+  return DOCUMENT_RULES[name].map((fieldRule) => fieldRule.path);
+}
+
 export interface ConformOptions {
   /** Force a contract instead of detecting one, for an emitter under test. */
   contract?: ContractName;

package/src/gateway.ts

@@ -51,6 +51,9 @@ import type { PlanAssumption } from './plan.js';
 import { effectivePricing, multipliersFor } from './pricing.js';
 import type { PricingCatalogue } from './pricing.js';
 import type { ModelPricing } from './types.js';
+import { judgeLimits, limitSentence, unjudgedSentence } from './judgement.js';
+import type { MeasuredPosition, PolicyJudgement } from './judgement.js';
+import type { LimitsConfig, WaiveEntry } from './config-schema.js';
 
 /**
  * What the operator has decided happens when the gateway cannot judge.
@@ -80,6 +83,12 @@ export interface GatewayCall {
   maxOutputTokens: number | null;
   /** The workload, when the caller labelled it. */
   label: string | null;
+  /**
+   * The conversation, when the caller identified it — `metadata.trazum_session`,
+   * the same seam as the label. Used to judge the per-session ceiling and
+   * never recorded, printed, or forwarded anywhere by this module.
+   */
+  session: string | null;
 }
 
 /** Where the budget stands, as the gateway was told at the last refresh. */
@@ -97,10 +106,17 @@ export type RefuseReason =
   | 'budget-exhausted'
   /** This call would take it past, on an estimate of this call. */
   | 'call-would-cross'
+  /** A ceiling in the `limits` policy is over — the judgement names which. */
+  | 'limit-over'
   /** Cannot tell, and the operator chose fail-closed. */
   | 'cannot-tell-and-closed';
 
-export type CannotTellCause = 'no-budget' | 'nothing-measured' | 'model-unpriced';
+export type CannotTellCause =
+  | 'no-budget'
+  | 'nothing-measured'
+  | 'model-unpriced'
+  /** A ceiling in the `limits` policy could not be judged — see `policy`. */
+  | 'limit-unjudged';
 
 /** A cheaper way to make the same call, named on a refusal. */
 export interface GatewayAlternative {
@@ -124,6 +140,8 @@ export type GatewayDecision =
       estimatedUsd: number | null;
       /** Present when the gateway could not judge and the operator fails open. */
       unjudged: CannotTellCause | null;
+      /** The limits policy, judged for this call — same judge as every door. */
+      policy: PolicyJudgement;
     }
   | {
       kind: 'refuse';
@@ -137,6 +155,8 @@ export type GatewayDecision =
       /** A refusal never arrives bare. Dearest saving first; may be empty. */
       alternatives: GatewayAlternative[];
       because: string;
+      /** The limits policy, judged for this call — same judge as every door. */
+      policy: PolicyJudgement;
     }
   | {
       /**
@@ -154,6 +174,8 @@ export type GatewayDecision =
       configuredReason: string;
       estimatedUsd: number | null;
       markedInStore: true;
+      /** The limits policy, judged for this call — same judge as every door. */
+      policy: PolicyJudgement;
     };
 
 export interface GatewayPolicy {
@@ -172,6 +194,19 @@ export interface GatewayOptions {
   catalogue: PricingCatalogue;
   policy: GatewayPolicy;
   on?: Date;
+  /**
+   * The `limits` block and the measured position it is judged against —
+   * chapter three of the 1.66 arc. Both optional: a gateway with no limits
+   * config behaves exactly as before, and the judgement is `no-policy`.
+   *
+   * The judging is `judgeLimits`, verbatim — the same function `serve` and
+   * `spend_guard` call, which is the whole point: three doors, one judge,
+   * no door doing its own arithmetic.
+   */
+  limits?: LimitsConfig;
+  position?: MeasuredPosition;
+  /** The config's `waive` list — a silenced limit forwards, on the record. */
+  waivers?: readonly WaiveEntry[];
 }
 
 /** What this call costs at a model's rates, or null when it cannot be priced. */
@@ -258,6 +293,63 @@ export function gatewayDecision(
   const model = catalogue.byId.get(call.model);
   const estimatedUsd = priceCall(model, call, on);
 
+  /**
+   * The limits policy, judged first and by the shared judge — never by
+   * arithmetic of this module's own. An `over` here refuses regardless of
+   * where the monthly budget stands: a session ceiling exists precisely for
+   * the call that is fine by the month and ruinous by the conversation.
+   */
+  const judged = judgeLimits(
+    options.limits,
+    options.position ?? { dayUsd: null, sessionUsd: null, labelUsd: null },
+    {
+      model: call.model,
+      inputTokens: call.inputTokens ?? undefined,
+      outputTokens: call.maxOutputTokens ?? undefined,
+      label: call.label ?? undefined,
+      session: call.session ?? undefined,
+    },
+    { catalogue, on, ...(options.waivers === undefined ? {} : { waivers: options.waivers }) },
+  );
+
+  if (judged.verdict === 'over') {
+    // The unwaived crossing — a waived `over` is present in the judgement
+    // and deliberately not the one a refusal is written about.
+    const over = judged.judgements.find((entry) => entry.verdict === 'over' && entry.waived === null)!;
+    /*
+      A configured substitution is deliberately NOT consulted here. The
+      operator wrote that rule for the budget; rerouting a call because a
+      *session* ceiling crossed would spend more money in the very unit that
+      is over, under a rule written about something else.
+    */
+    return {
+      kind: 'refuse',
+      reason: 'limit-over',
+      cause: null,
+      restsOn: over.restsOn,
+      standing,
+      estimatedUsd,
+      alternatives: model === undefined ? [] : alternativesFor(model, call, catalogue, on),
+      because: limitSentence(over),
+      policy: judged,
+    };
+  }
+
+  const limitUnjudged = judged.verdict === 'cannot-tell' && judged.reason !== 'no-policy';
+  if (limitUnjudged && policy.onCannotTell === 'fail-closed') {
+    return {
+      kind: 'refuse',
+      reason: 'cannot-tell-and-closed',
+      cause: 'limit-unjudged',
+      restsOn: null,
+      standing,
+      estimatedUsd,
+      alternatives: [],
+      because: `${unjudgedSentence(judged)} This gateway is configured to fail closed.`,
+      policy: judged,
+    };
+  }
+
   const cause = whyCannotTell(standing, estimatedUsd);
   if (cause !== null) {
     /**
@@ -267,7 +359,7 @@ export function gatewayDecision(
      * nothing to do with the caller's request.
      */
     if (policy.onCannotTell === 'fail-open') {
-      return { kind: 'forward', estimatedUsd, unjudged: cause };
+      return { kind: 'forward', estimatedUsd, unjudged: cause, policy: judged };
     }
     return {
       kind: 'refuse',
@@ -278,6 +370,7 @@ export function gatewayDecision(
       estimatedUsd,
       alternatives: [],
       because: becauseCannotTell(cause),
+      policy: judged,
     };
   }
 
@@ -285,13 +378,21 @@ export function gatewayDecision(
   // it — narrowed here rather than asserted, so a change to `whyCannotTell`
   // that stopped guaranteeing them fails the build instead of the request.
   if (standing === null || estimatedUsd === null || model === undefined) {
-    return { kind: 'forward', estimatedUsd, unjudged: 'no-budget' };
+    return {
+      kind: 'forward',
+      estimatedUsd,
+      unjudged: limitUnjudged ? 'limit-unjudged' : 'no-budget',
+      policy: judged,
+    };
   }
 
   const already = standing.consumedUsd > standing.limitUsd;
   const wouldCross = standing.consumedUsd + estimatedUsd > standing.limitUsd;
   if (!already && !wouldCross) {
-    return { kind: 'forward', estimatedUsd, unjudged: null };
+    // The monthly budget holds. A limits ceiling nobody could judge still
+    // rides along as `unjudged` under fail-open, so the forward says what it
+    // did not check rather than implying everything was.
+    return { kind: 'forward', estimatedUsd, unjudged: limitUnjudged ? 'limit-unjudged' : null, policy: judged };
   }
 
   const configured = policy.substitute?.[call.model];
@@ -303,6 +404,7 @@ export function gatewayDecision(
       configuredReason: configured.reason,
       estimatedUsd: priceCall(target, call, on),
       markedInStore: true,
+      policy: judged,
     };
   }
 
@@ -319,9 +421,11 @@ export function gatewayDecision(
     because: already
       ? 'The budget for this period is already spent, measured.'
       : 'This call would take the budget past its limit, on an estimate of this call.',
+    policy: judged,
   };
 }
 
+
 function becauseCannotTell(cause: CannotTellCause): string {
   return cause === 'no-budget'
     ? 'No budget is configured, so there is nothing to judge this against, and this gateway is configured to fail closed.'

package/src/guard.ts

@@ -25,6 +25,9 @@
 
 import { answerCost } from './answer.js';
 import type { AnswerRequest, CostAnswer } from './answer.js';
+import { judgeLimits, limitSentence, unjudgedSentence } from './judgement.js';
+import type { MeasuredPosition, PolicyJudgement } from './judgement.js';
+import type { LimitsConfig, WaiveEntry } from './config-schema.js';
 import { effectivePricing, multipliersFor } from './pricing.js';
 import type { PricingCatalogue } from './pricing.js';
 import type { ModelPricing } from './types.js';
@@ -71,6 +74,14 @@ export interface GuardAnswer {
    * machine acts on; this is never the only place a fact appears.
    */
   because: string;
+  /**
+   * The `limits` policy, judged for this call by `judgeLimits` — the same
+   * function the gateway and `serve` call, which is what "one policy, three
+   * doors" means in code. Always present: with no policy it says `no-policy`
+   * rather than being absent, because a missing field and a judged absence
+   * are different answers.
+   */
+  policy: PolicyJudgement;
 }
 
 /** Models cheaper than this one, in the same family, that the prompt fits in. */
@@ -97,6 +108,16 @@ function cheaperThan(
 export interface GuardRequest extends AnswerRequest {
   /** Whether the caller says this work can wait for a batch window. */
   batchEligible?: boolean;
+  /** The `limits` block, when the caller holds one. Judged, never re-derived. */
+  limits?: LimitsConfig;
+  /** Measured spend per scope, from the caller's own log — never a guess. */
+  position?: MeasuredPosition;
+  /** The workload this call belongs to, for the per-label ceiling. */
+  label?: string;
+  /** The conversation, for the per-session ceiling. Never echoed back. */
+  session?: string;
+  /** The config's `waive` list — a silenced limit answers yes, on the record. */
+  waive?: readonly WaiveEntry[];
 }
 
 export function guardSpend(
@@ -164,25 +185,74 @@ export function guardSpend(
 
   alternatives.sort((a, b) => b.savingUsd - a.savingUsd);
 
+  /**
+   * The limits policy, judged by the same function the gateway and `serve`
+   * call. A caller that passes no policy gets `no-policy` and an answer
+   * byte-identical to what this returned before the field existed.
+   */
+  const policy = judgeLimits(
+    request.limits,
+    request.position ?? { dayUsd: null, sessionUsd: null, labelUsd: null },
+    {
+      model: request.model,
+      inputTokens: request.inputTokens,
+      outputTokens: request.outputTokens,
+      basis: request.basis,
+      label: request.label,
+      session: request.session,
+    },
+    { catalogue, on, ...(request.waive === undefined ? {} : { waivers: request.waive }) },
+  );
+
   /**
    * The verdict maps the cost answer's three outcomes onto the three an agent
    * can act on. `cannot-tell` stays `cannot-tell` rather than defaulting to
    * yes: a guard that permits whatever it cannot judge is a guard that permits
    * everything the moment its inputs go missing.
+   *
+   * A judged limits policy folds in at the same precedence the policy itself
+   * uses — no beats cannot-tell beats yes — because a guard whose headline
+   * said "yes" over a crossed session ceiling would be two doors in one
+   * answer. `no-policy` folds as nothing: the caller asked only the budget
+   * question, and gets only that answer.
    */
-  const verdict: GuardVerdict =
+  const fromCost: GuardVerdict =
     cost.verdict === 'cannot-tell' ? 'cannot-tell' : cost.verdict === 'over' ? 'no' : 'yes';
+  const verdict: GuardVerdict =
+    policy.verdict === 'over'
+      ? 'no'
+      : policy.verdict === 'cannot-tell' && policy.reason !== 'no-policy' && fromCost === 'yes'
+        ? 'cannot-tell'
+        : fromCost;
 
   return {
     schemaVersion: 1,
     verdict,
     cost,
     alternatives,
-    because: reasonFor(verdict, cost, alternatives),
+    because: reasonFor(verdict, cost, alternatives, policy),
+    policy,
   };
 }
 
-function reasonFor(verdict: GuardVerdict, cost: CostAnswer, alternatives: GuardAlternative[]): string {
+function reasonFor(
+  verdict: GuardVerdict,
+  cost: CostAnswer,
+  alternatives: GuardAlternative[],
+  policy: PolicyJudgement,
+): string {
+  // A refusal that came from the limits policy speaks the shared sentence —
+  // the limit, the measured position and the period, same words at every door.
+  const overLimit = policy.judgements.find((entry) => entry.verdict === 'over' && entry.waived === null);
+  if (verdict === 'no' && overLimit !== undefined) {
+    const lead = limitSentence(overLimit);
+    return alternatives.length === 0
+      ? `${lead} No cheaper way to make this call exists in the catalogue.`
+      : `${lead} The cheapest alternative below saves the most.`;
+  }
+  if (verdict === 'cannot-tell' && cost.verdict !== 'cannot-tell') {
+    return unjudgedSentence(policy);
+  }
   if (verdict === 'cannot-tell') {
     return cost.reason === 'no-budget-configured'
       ? 'No budget is configured, so there is nothing to judge this against.'

package/src/index.ts

@@ -166,7 +166,8 @@ export type {
   GatewayStanding,
   RefuseReason,
 } from './gateway.js';
-export { conform, CONTRACT_NAMES } from './conform.js';
+export { conform, CONTRACT_NAMES, requiredFieldsOf } from './conform.js';
+export { CONTRACT_SCHEMAS, contractSchema } from './schemas.js';
 export type {
   ConformOptions,
   ConformanceProblem,
@@ -187,6 +188,18 @@ export type {
 export { waiverHistory, waiverDay, isWaiverUse } from './waivers.js';
 export type { WaiverHabit, WaiverHistory, WaiverUse, WaiverVerdict } from './waivers.js';
 export { answerCost } from './answer.js';
+export { judgeLimits } from './judgement.js';
+export type {
+  CannotJudgeReason,
+  LimitJudgement,
+  LimitScope,
+  LimitVerdict,
+  MeasuredPosition,
+  PolicyJudgement,
+  ProposedCall,
+} from './judgement.js';
+export { indexUsage, positionAt } from './position.js';
+export type { MeasuredIndex } from './position.js';
 export { guardSpend } from './guard.js';
 export type { GuardAlternative, GuardAnswer, GuardRequest, GuardVerdict } from './guard.js';
 export { proposeInit, HEADLINE_FLOOR_SHARE, MIN_RATE_DAYS } from './init.js';
@@ -538,6 +551,7 @@ export { editDistance, nearestName } from './nearest.js';
 export {
   CONFIG_FILENAME,
   CONFIG_KEYS,
+  CONFIG_LIMITS_KEYS,
   CONFIG_USAGE_KEYS,
   ConfigError,
   DEFAULT_EXTENSIONS,
@@ -545,8 +559,10 @@ export {
   MAX_CONFIG_SEARCH_DEPTH,
   budgetFor,
   parseConfig,
+  parseLimits,
+  parseWaive,
 } from './config-schema.js';
-export type { ResolvedBudget, SpendConfig, TrazumConfig, WaiveEntry } from './config-schema.js';
+export type { LimitsConfig, ResolvedBudget, SpendConfig, TrazumConfig, WaiveEntry } from './config-schema.js';
 export { WAIVABLE_GATES } from './config-schema.js';
 
 export { RULE_LEVELS } from './types.js';