@trazum/core 1.65.0 → 1.67.0

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

@@ -188,6 +188,26 @@ 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 { positionReport } from './position-report.js';
+export type {
+  PositionDistance,
+  PositionDocument,
+  PositionScope,
+  PositionStanding,
+  UnmeasuredPosition,
+} from './position-report.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';
@@ -539,6 +559,7 @@ export { editDistance, nearestName } from './nearest.js';
 export {
   CONFIG_FILENAME,
   CONFIG_KEYS,
+  CONFIG_LIMITS_KEYS,
   CONFIG_USAGE_KEYS,
   ConfigError,
   DEFAULT_EXTENSIONS,
@@ -546,8 +567,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';

package/src/judgement.ts

@@ -0,0 +1,346 @@
+/**
+ * One policy, judged once — the function every door calls.
+ *
+ * The `limits` block states the policy: per-day, per-session and per-label
+ * USD ceilings. This module answers whether a proposed call fits it, and the
+ * design constraint is the 1.62 arc's lesson: **two doors to the same value
+ * agreeing by coincidence is a defect waiting for its input.** So the doors
+ * — the gateway's 402, `serve`'s cost answer, `spend_guard` over MCP — do
+ * not each read a slice of config and do their own arithmetic. They hand
+ * this function the policy, the measured position and the call, and forward
+ * its answer.
+ *
+ * Nothing here re-derives the single-ceiling semantics either. Each ceiling
+ * is judged by `answerCost`, the function that has answered "does this call
+ * fit this budget" for every door since 1.44 — including its refusals: a
+ * negative token count is rejected before it can become money, an unpriced
+ * model is a cannot-tell rather than a guess, and a verdict always names
+ * whether it rests on a measurement alone or needed the estimate. A policy
+ * judgement is those answers, one per applicable ceiling, under one verdict.
+ *
+ * Two refusals are this module's own, and both close the same loophole: a
+ * policy with per-label ceilings judging a call that names no label, or a
+ * per-session ceiling judging a call that names no session, is `cannot-tell`
+ * — not "no ceiling applies". A call that omits its label does not slip past
+ * the label's ceiling; it becomes unjudgeable, and the answer says why.
+ */
+
+import { answerCost } from './answer.js';
+import type { CostAnswer } from './answer.js';
+import type { PricingCatalogue } from './pricing.js';
+import type { LimitsConfig, WaiveEntry } from './config-schema.js';
+import { formatUsd } from './savings.js';
+
+/** Which ceiling a judgement is about. */
+export type LimitScope = 'day' | 'session' | 'label';
+
+export type LimitVerdict = 'within' | 'over' | 'cannot-tell';
+
+/** Why one ceiling could not be judged, when it could not. */
+export type CannotJudgeReason =
+  /** The scope's spend has not been measured, so the consumed half is unknown. */
+  | 'nothing-measured'
+  /** The model is not in the catalogue, so the call cannot be priced. */
+  | 'model-unpriced'
+  /** Per-label ceilings exist and the call names no label. */
+  | 'no-label-on-call'
+  /** A per-session ceiling exists and the call names no session. */
+  | 'no-session-on-call';
+
+/**
+ * One ceiling, judged. The three figures a refusal must be auditable from
+ * are all here: the limit, the measured spend, and the window the measured
+ * figure covers — the denominator, not just the number.
+ */
+export interface LimitJudgement {
+  scope: LimitScope;
+  /** Which label, when the scope is `label`. Null otherwise. */
+  label: string | null;
+  limitUsd: number;
+  verdict: LimitVerdict;
+  /**
+   * `measured` when the ceiling is already crossed without the estimate;
+   * `measured+estimated` when it takes the described call to cross — or to
+   * fit. Null when the verdict is `cannot-tell`.
+   */
+  restsOn: 'measured' | 'measured+estimated' | null;
+  reason: CannotJudgeReason | null;
+  /** Measured spend inside this scope's period. Null when not measured. */
+  measuredUsd: number | null;
+  /** The period the measured figure covers. Null when unknown. */
+  window: { fromMs: number; toMs: number } | null;
+  /** Where the scope would stand after this call. Null when unjudgeable. */
+  afterCallUsd: number | null;
+  /**
+   * The unexpired waiver silencing this ceiling, when the config carries one.
+   *
+   * The `check` mechanism, applied here unchanged: the verdict stays `over`
+   * — the measurement is the measurement — but a waived `over` does not make
+   * the policy refuse, and the waiver rides in the judgement so every answer
+   * from every door is the record of the silence. Null when nothing is
+   * waived, which is almost always.
+   */
+  waived: { reason: string; until: string } | null;
+}
+
+export interface PolicyJudgement {
+  schemaVersion: 1;
+  /**
+   * The strictest verdict wins: one `over` makes the policy `over`, else one
+   * `cannot-tell` makes it `cannot-tell`, else everything judged is `within`.
+   * The order is the only safe one — a door that read "within" off a policy
+   * with an unjudgeable ceiling would be approving a call nobody judged.
+   */
+  verdict: LimitVerdict;
+  /** Set when the verdict is `cannot-tell` and no ceiling produced it. */
+  reason: 'no-policy' | null;
+  /** One entry per applicable ceiling, in policy order: day, session, label. */
+  judgements: LimitJudgement[];
+}
+
+/**
+ * The measured side: what the store has billed inside each scope's period.
+ *
+ * Every field is a measurement or `null`, never zero-for-absence — the rule
+ * every document in this product holds. A scope the caller could not measure
+ * (no clock on the log, a session nothing recorded) is `null`, and the
+ * judgement for that ceiling is `cannot-tell` rather than "under".
+ */
+export interface MeasuredPosition {
+  /** Measured spend in the current UTC day. */
+  dayUsd: number | null;
+  dayWindow?: { fromMs: number; toMs: number } | null;
+  /** Measured spend in the call's session. */
+  sessionUsd: number | null;
+  sessionWindow?: { fromMs: number; toMs: number } | null;
+  /** Measured spend under the call's label. */
+  labelUsd: number | null;
+  labelWindow?: { fromMs: number; toMs: number } | null;
+}
+
+/** The call being asked about — the same fields every door already takes. */
+export interface ProposedCall {
+  model?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  basis?: 'token-count' | 'heuristic';
+  label?: string;
+  session?: string;
+}
+
+const judgementOf = (
+  scope: LimitScope,
+  label: string | null,
+  limitUsd: number,
+  answer: CostAnswer,
+): LimitJudgement => ({
+  scope,
+  label,
+  limitUsd,
+  verdict: answer.verdict,
+  restsOn: answer.restsOn,
+  // The single-ceiling reasons map one-to-one; the two call-shape refusals
+  // (`no-label-on-call`, `no-session-on-call`) never reach answerCost.
+  reason:
+    answer.reason === null ? null : answer.reason === 'model-unpriced' ? 'model-unpriced' : 'nothing-measured',
+  measuredUsd: answer.budget?.consumedUsd ?? null,
+  window: answer.budget?.window ?? null,
+  afterCallUsd: answer.afterCall?.usd ?? null,
+  waived: null,
+});
+
+const unjudgeable = (
+  scope: LimitScope,
+  label: string | null,
+  limitUsd: number,
+  reason: CannotJudgeReason,
+): LimitJudgement => ({
+  scope,
+  label,
+  limitUsd,
+  verdict: 'cannot-tell',
+  restsOn: null,
+  reason,
+  measuredUsd: null,
+  window: null,
+  afterCallUsd: null,
+  waived: null,
+});
+
+/** The waiver gate that names one judgement's ceiling. */
+const gateOf = (judgement: LimitJudgement): string =>
+  judgement.scope === 'day'
+    ? 'limits.dayUsd'
+    : judgement.scope === 'session'
+      ? 'limits.sessionUsd'
+      : `limits.byLabel:${judgement.label ?? ''}`;
+
+/**
+ * The unexpired waiver for one judgement, if the config carries one.
+ *
+ * Judged in UTC at run time, the same rule `check` applies: the day the
+ * waiver expires, the ceiling refuses again — nobody has to remember.
+ */
+const waiverFor = (
+  judgement: LimitJudgement,
+  waivers: readonly WaiveEntry[],
+  on: Date,
+): { reason: string; until: string } | null => {
+  const today = on.toISOString().slice(0, 10);
+  const match = waivers.find((entry) => entry.gate === gateOf(judgement) && entry.until >= today);
+  return match === undefined ? null : { reason: match.reason, until: match.until };
+};
+
+/**
+ * Judges a proposed call against the whole `limits` policy.
+ *
+ * Pure and synchronous for the same reason `answerCost` is: this runs inside
+ * a request that has not been sent yet, and a function that reads a file
+ * cannot promise single-digit milliseconds. The caller measures; this judges.
+ */
+export function judgeLimits(
+  policy: LimitsConfig | undefined,
+  position: MeasuredPosition,
+  call: ProposedCall,
+  options: { catalogue: PricingCatalogue; on?: Date; waivers?: readonly WaiveEntry[] },
+): PolicyJudgement {
+  const judgements: LimitJudgement[] = [];
+
+  const judge = (consumedUsd: number | null, limitUsd: number, window: { fromMs: number; toMs: number } | null) =>
+    answerCost(
+      {
+        model: call.model,
+        inputTokens: call.inputTokens,
+        outputTokens: call.outputTokens,
+        basis: call.basis,
+        limitUsd,
+        consumedUsd: consumedUsd ?? undefined,
+        window,
+      },
+      options,
+    );
+
+  if (policy?.dayUsd !== undefined) {
+    judgements.push(
+      judgementOf('day', null, policy.dayUsd, judge(position.dayUsd, policy.dayUsd, position.dayWindow ?? null)),
+    );
+  }
+
+  if (policy?.sessionUsd !== undefined) {
+    judgements.push(
+      call.session === undefined
+        ? unjudgeable('session', null, policy.sessionUsd, 'no-session-on-call')
+        : judgementOf(
+            'session',
+            null,
+            policy.sessionUsd,
+            judge(position.sessionUsd, policy.sessionUsd, position.sessionWindow ?? null),
+          ),
+    );
+  }
+
+  if (policy?.byLabel !== undefined && Object.keys(policy.byLabel).length > 0) {
+    if (call.label === undefined) {
+      /*
+        The loophole this closes: per-label ceilings with an unlabelled call.
+        Skipping the scope would mean the ceiling only binds calls polite
+        enough to name themselves — the same defect as the negative token
+        count, worn as an omission. One judgement, no label, cannot-tell.
+        The ceiling reported is the smallest, because that is the one the
+        call might be dodging.
+      */
+      const smallest = Math.min(...Object.values(policy.byLabel));
+      judgements.push(unjudgeable('label', null, smallest, 'no-label-on-call'));
+    } else if (policy.byLabel[call.label] !== undefined) {
+      const limitUsd = policy.byLabel[call.label]!;
+      judgements.push(
+        judgementOf(
+          'label',
+          call.label,
+          limitUsd,
+          judge(position.labelUsd, limitUsd, position.labelWindow ?? null),
+        ),
+      );
+    }
+    // A labelled call whose label has no ceiling is judged by the other
+    // scopes alone: the policy said nothing about this label, and inventing
+    // a ceiling for it would be enforcing config nobody wrote.
+  }
+
+  if (judgements.length === 0) {
+    return { schemaVersion: 1, verdict: 'cannot-tell', reason: 'no-policy', judgements: [] };
+  }
+
+  /**
+   * Waivers, applied after every ceiling is judged: the measurement stays —
+   * a waived judgement still says `over` — but the silence is attached, on
+   * the record, and the verdict below treats a waived `over` as not-refusing.
+   */
+  const { on = new Date(), waivers = [] } = options;
+  if (waivers.length > 0) {
+    for (const judgement of judgements) {
+      if (judgement.verdict === 'over') judgement.waived = waiverFor(judgement, waivers, on);
+    }
+  }
+
+  const verdict: LimitVerdict = judgements.some((entry) => entry.verdict === 'over' && entry.waived === null)
+    ? 'over'
+    : judgements.some((entry) => entry.verdict === 'cannot-tell')
+      ? 'cannot-tell'
+      : 'within';
+
+  return { schemaVersion: 1, verdict, reason: null, judgements };
+}
+
+/** The scope, as a refusal names it. Labels print; session identifiers never do. */
+export function limitScopeName(judgement: LimitJudgement): string {
+  return judgement.scope === 'day'
+    ? "the day's ceiling"
+    : judgement.scope === 'session'
+      ? "this session's ceiling"
+      : judgement.label === null
+        ? 'the per-label ceiling'
+        : `the "${judgement.label}" label's ceiling`;
+}
+
+/** The period a measured figure covers, when the judgement carries one. */
+function periodOf(judgement: LimitJudgement): string {
+  if (judgement.window === null) return '';
+  const from = new Date(judgement.window.fromMs).toISOString();
+  const to = new Date(judgement.window.toMs).toISOString();
+  return ` between ${from} and ${to}`;
+}
+
+/**
+ * The refusal, legible — chapter four's rule, written once.
+ *
+ * Every over-limit sentence names the limit, the measured position and the
+ * period, so an agent can log it and a person can audit it without
+ * re-running anything. Every door uses this builder rather than composing
+ * its own, for the same reason every door uses the same judge.
+ */
+export function limitSentence(judgement: LimitJudgement): string {
+  const limit = formatUsd(judgement.limitUsd);
+  const measured =
+    judgement.measuredUsd === null ? 'nothing measured' : `${formatUsd(judgement.measuredUsd)} measured`;
+  return judgement.restsOn === 'measured'
+    ? `${capital(limitScopeName(judgement))} of ${limit} is already spent: ${measured}${periodOf(judgement)}.`
+    : `This call would take ${limitScopeName(judgement)} of ${limit} past its limit: ${measured}${periodOf(judgement)}, plus this call's estimate.`;
+}
+
+/** Why the policy could not be judged, in one auditable sentence. */
+export function unjudgedSentence(judged: PolicyJudgement): string {
+  const first = judged.judgements.find((entry) => entry.verdict === 'cannot-tell');
+  const which = first === undefined ? 'a ceiling' : limitScopeName(first);
+  const why =
+    first?.reason === 'no-label-on-call'
+      ? 'the call names no label'
+      : first?.reason === 'no-session-on-call'
+        ? 'the call names no session'
+        : first?.reason === 'model-unpriced'
+          ? 'the model is not in the price catalogue'
+          : 'its spend has not been measured';
+  return `${capital(which)} in the limits policy cannot be judged: ${why}.`;
+}
+
+const capital = (text: string): string => `${text[0]!.toUpperCase()}${text.slice(1)}`;