@trazum/core 1.81.0 → 1.83.0

package/dist/verdict-bridge.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/core",
-  "version": "1.81.0",
+  "version": "1.83.0",
   "description": "Trazum core: priced advisories for LLM prompts (caching, model tier, batching, schemas), plus deterministic trimming, token counting and pricing.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",

package/src/advisories.ts

@@ -2,12 +2,19 @@ import { analyzeCachePrefix } from './cache.js';
 import { getMessages } from './i18n/index.js';
 import type { Locale } from './i18n/types.js';
 import { COMPLEX_SIGNALS, SIMPLE_SIGNALS } from './phrases.js';
-import { BUNDLED_CATALOGUE, effectivePricing, modelFrom, multipliersFor } from './pricing.js';
+import {
+  BUNDLED_CATALOGUE,
+  effectivePricing,
+  isOffered,
+  modelFrom,
+  multipliersFor,
+} from './pricing.js';
 import type { PricingCatalogue } from './pricing.js';
 import { formatUsd } from './savings.js';
 import { analyzeExamples, findContradictions, findMovableSchema,
   findRestatedFormat } from './structure.js';
-import { ESTIMATE_ERROR_BAND_PCT, bandGoverns, estimateTokens } from './tokenizer.js';
+import { bandGoverns, estimateTokens } from './tokenizer.js';
+import { bandFor } from './band.js';
 import type { Advisory, ModelPricing, TokenCounter, UsageProfile } from './types.js';
 
 function countSignals(haystack: string, signals: readonly string[]): number {
@@ -16,17 +23,43 @@ function countSignals(haystack: string, signals: readonly string[]): number {
   return count;
 }
 
+/** What `recommendTierDetailed` saw, not only what it concluded. */
+export interface TierRecommendation {
+  tier: ModelPricing['tier'];
+  complexSignals: number;
+  simpleSignals: number;
+  /**
+   * True when the prompt asks for depth and for brevity at once, and the
+   * heuristic has no business preferring either.
+   *
+   * The score subtracts one side from the other, so three complex signals
+   * against three simple ones cancels to zero and returns `sonnet` — the same
+   * answer as a prompt with **no signals at all**. Those are opposite
+   * situations reported identically: one is "nothing here suggests a tier", the
+   * other is "this prompt contradicts itself about which tier it needs", and
+   * only the second is worth telling somebody about.
+   *
+   * The threshold is a lead of one signal or fewer, and it comes from the
+   * weights above rather than from taste: each signal moves the score by 2,
+   * prompt size moves it by up to 2, so a one-signal lead is inside what
+   * length alone contributes. A lead of two or more is a majority the size
+   * term cannot manufacture.
+   */
+  conflicted: boolean;
+}
+
 /**
- * Estimates the capability tier the prompt needs.
+ * Estimates the capability tier the prompt needs, and says what it saw.
  *
  * This is a keyword-and-size heuristic, not a judgement about answer quality.
  * Treat it as a hypothesis to validate with your own evaluations before
  * moving down a tier in production.
  */
-export function recommendTier(prompt: string, tokens: number): ModelPricing['tier'] {
+export function recommendTierDetailed(prompt: string, tokens: number): TierRecommendation {
   const haystack = prompt.toLowerCase();
-  let score =
-    countSignals(haystack, COMPLEX_SIGNALS) * 2 - countSignals(haystack, SIMPLE_SIGNALS) * 2;
+  const complexSignals = countSignals(haystack, COMPLEX_SIGNALS);
+  const simpleSignals = countSignals(haystack, SIMPLE_SIGNALS);
+  let score = complexSignals * 2 - simpleSignals * 2;
 
   if (tokens > 4000) score += 2;
   else if (tokens > 1500) score += 1;
@@ -34,9 +67,25 @@ export function recommendTier(prompt: string, tokens: number): ModelPricing['tie
 
   if (/```|~~~/.test(prompt)) score += 1;
 
-  if (score >= 3) return 'opus';
-  if (score >= 0) return 'sonnet';
-  return 'haiku';
+  const tier = score >= 3 ? 'opus' : score >= 0 ? 'sonnet' : 'haiku';
+  return {
+    tier,
+    complexSignals,
+    simpleSignals,
+    conflicted:
+      complexSignals > 0 && simpleSignals > 0 && Math.abs(complexSignals - simpleSignals) <= 1,
+  };
+}
+
+/**
+ * The tier alone, unchanged.
+ *
+ * Kept because it is public API and the 1.x line does not change shapes.
+ * Callers that need to know whether the answer is trustworthy reach for
+ * `recommendTierDetailed`.
+ */
+export function recommendTier(prompt: string, tokens: number): ModelPricing['tier'] {
+  return recommendTierDetailed(prompt, tokens).tier;
 }
 
 const TIER_ORDER: Record<ModelPricing['tier'], number> = {
@@ -81,9 +130,10 @@ function cheapestInTier(
     (m) =>
       m.tier === tier &&
       m.provider === provider &&
-      // Not generally available: recommending a model the reader cannot call is
-      // worse than recommending nothing.
-      m.recommendable !== false,
+      // Not generally available, or refused outright by the provider:
+      // recommending a model the reader cannot call is worse than
+      // recommending nothing. Both halves live in `isOffered`.
+      isOffered(m),
   );
   if (candidates.length === 0) return undefined;
   return candidates.reduce((best, m) =>
@@ -142,7 +192,18 @@ export function buildAdvisories(
    * outright rather than degrading, so there is no partial result to notice.
    */
   const estimated = count === estimateTokens;
-  const band = ESTIMATE_ERROR_BAND_PCT / 100;
+  /**
+   * The band of **this prompt**, not one number for all text.
+   *
+   * These three hedges — the context window, the cache minimum both ways — are
+   * the places an estimate is compared against a hard threshold and the answer
+   * stated as fact, so the width of the hedge decides whether the statement is
+   * safe. A single 10% was measured on a corpus of thirteen prose files and one
+   * each of code, numeric and punctuation, and the estimator is 25% out on a
+   * SQL migration and 33% out on a CSV ledger. Hedging a code prompt by ten
+   * points was hedging by a third of what it needed.
+   */
+  const band = bandFor(optimizedPrompt) / 100;
 
   /**
    * Whether that band describes **this** model's tokenizer.
@@ -254,15 +315,36 @@ export function buildAdvisories(
              */
             nearMinimum:
               count === estimateTokens &&
-              cache.stablePrefixTokens * (1 - ESTIMATE_ERROR_BAND_PCT / 100) < minTokens,
+              cache.stablePrefixTokens * (1 - band) < minTokens,
           }),
           estimatedMonthlyUsd: saving,
         });
       } else {
+        /**
+         * The threshold is derived from this model's own multipliers, not
+         * quoted.
+         *
+         * Break-even is where a cached token costs exactly what an uncached one
+         * does: `h*read + (1-h)*write = 1`, so `h = (1 - write) / (read -
+         * write)`. At Anthropic's 1.25 and 0.1 that is 21.74%, and the sentence
+         * this replaces said 28% for every model in the catalogue.
+         *
+         * A write multiplier of 1 has no such threshold. Writing then costs
+         * exactly what not caching costs, so caching cannot lose money at any
+         * hit rate, and `(1 - 1) / (r - 1)` is 0 rather than a small number.
+         * Eight of the eighteen models are that shape, and the fixed sentence
+         * advised all eight to consider turning caching off.
+         */
+        const write = rates.cacheWrite5m;
         advisories.push({
           id: 'prompt-caching-not-worth-it',
           severity: 'info',
-          ...t.advisories.promptCachingNotWorthIt(),
+          ...t.advisories.promptCachingNotWorthIt({
+            readPct: Math.round(rates.cacheRead * 100),
+            writePct: Math.round(write * 100),
+            breakEvenPct:
+              write <= 1 ? null : Math.round(((1 - write) / (rates.cacheRead - write)) * 1000) / 10,
+          }),
           estimatedMonthlyUsd: null,
         });
       }
@@ -287,7 +369,7 @@ export function buildAdvisories(
            */
           couldReachMinimum:
             count === estimateTokens &&
-            cache.stablePrefixTokens * (1 + ESTIMATE_ERROR_BAND_PCT / 100) >= minTokens,
+            cache.stablePrefixTokens * (1 + band) >= minTokens,
         }),
         estimatedMonthlyUsd: null,
       });
@@ -374,7 +456,34 @@ export function buildAdvisories(
   }
 
   // --- Recommended model ---
-  const suggestedTier = recommendTier(optimizedPrompt, tokensAfter);
+  const recommendation = recommendTierDetailed(optimizedPrompt, tokensAfter);
+  const suggestedTier = recommendation.tier;
+
+  /**
+   * When the prompt argues with itself about which tier it needs, say so and
+   * recommend nothing.
+   *
+   * The score subtracts one side from the other, so a prompt demanding depth
+   * and brevity in equal measure cancels to zero and lands on `sonnet` — the
+   * identical answer to a prompt with no signals at all. Reporting two opposite
+   * situations with one number is the failure; the fix is not a better score,
+   * it is declining to pretend there is one.
+   *
+   * This returns before the downgrade block rather than alongside it, because a
+   * saving computed from a tier the heuristic cannot stand behind is a figure
+   * with a dollar sign on it and nothing underneath.
+   */
+  if (recommendation.conflicted) {
+    advisories.push({
+      id: 'tier-signals-conflict',
+      severity: 'info',
+      ...t.advisories.tierSignalsConflict({
+        complexSignals: recommendation.complexSignals,
+        simpleSignals: recommendation.simpleSignals,
+      }),
+      estimatedMonthlyUsd: null,
+    });
+  }
   /**
    * A model whose capability nobody recorded is never told it is overpowered.
    *
@@ -392,15 +501,30 @@ export function buildAdvisories(
    * and a condition that forgets it both have to happen before a model of
    * unrecorded capability is told it is overpowered.
    */
-  if (model.tier !== 'unknown' && TIER_ORDER[suggestedTier] < TIER_ORDER[model.tier]) {
+  if (!recommendation.conflicted && model.tier !== 'unknown' && TIER_ORDER[suggestedTier] < TIER_ORDER[model.tier]) {
     const candidate = cheapestInTier(suggestedTier, on, pricing, model.provider);
     if (candidate) {
       const candidatePricing = effectivePricing(candidate, on);
+      /**
+       * The candidate's own batch multiplier, not a constant.
+       *
+       * This line read `usage.batchEligible ? 0.5 : 1`, while the current
+       * model's cost twenty lines above already used `rates.batch ?? 1` for
+       * exactly the reason stated there: a discount that is not per model is an
+       * invented saving rather than an imprecise one.
+       *
+       * Three models in the catalogue carry `batch: null` — kimi-k2,
+       * deepseek-v3 and grok-4 — which means no batch API at all. Halving their
+       * cost offered money that cannot be bought at any price, made the
+       * downgrade look twice as good as it is, and could turn a saving that was
+       * negative into one this advisory reports.
+       */
+      const candidateBatch = usage.batchEligible ? (multipliersFor(candidate).batch ?? 1) : 1;
       const candidateMonthly =
         ((tokensAfter / 1_000_000) * candidatePricing.inputPerMTok +
           (usage.avgOutputTokens / 1_000_000) * candidatePricing.outputPerMTok) *
         usage.callsPerMonth *
-        (usage.batchEligible ? 0.5 : 1);
+        candidateBatch;
       const saving = monthlyInputUsd + monthlyOutputUsd - candidateMonthly;
       if (saving > 0) {
         advisories.push({
@@ -522,6 +646,29 @@ export function buildAdvisories(
     });
   }
 
+  if (model.retired) {
+    /**
+     * The most severe thing this function can say about a model, and it is
+     * placed before the promotional note deliberately: a price that is about to
+     * change matters less than a model that cannot be called at all.
+     *
+     * Not suppressed when the reader asked for this model by name. They asked
+     * because something in their world still says this id, and the whole value
+     * of the answer is that it no longer works.
+     */
+    advisories.push({
+      id: 'model-retired',
+      severity: 'warning',
+      ...t.advisories.modelRetired({
+        modelName: model.displayName,
+        modelId: model.id,
+        on: model.retired.on,
+        because: model.retired.because,
+      }),
+      estimatedMonthlyUsd: null,
+    });
+  }
+
   if (promoApplied && model.promo) {
     advisories.push({
       id: 'promo-pricing',

package/src/band.ts

@@ -0,0 +1,213 @@
+/**
+ * The error band Trazum is entitled to print about a given piece of text.
+ *
+ * ## Why this exists
+ *
+ * For a long time every report said `±10%`, everywhere, about everything. That
+ * number came from a corpus of twenty-one samples that held **thirteen files of
+ * Latin prose and exactly one each of code, numeric and punctuation** — and
+ * those single files were the set the estimator's constants had been fitted to.
+ * So the published band was not a measurement of the estimator. It was a
+ * measurement of its own training set.
+ *
+ * Seven ordinary samples in the thin classes broke it. Measured against
+ * Anthropic's counting endpoint, the same estimator that is 4.6% out on prose
+ * is **24.9% out on a SQL migration** and **32.5% out on a CSV ledger**. Telling
+ * somebody `±10%` about their ledger was telling them a number that is wrong
+ * about their prompt specifically.
+ *
+ * ## Why it does not name a text type
+ *
+ * The obvious design is a classifier — prose, code, few-shot, punctuation — and
+ * a band per class. The corpus says it cannot be built. Measured by character
+ * mix, code and punctuation **overlap completely**: `code-sql` is 7.7% symbols
+ * and `code-heavy` 15.6%, while `punctuation-markup` is 17.5% and
+ * `punctuation-heavy` 29.7%. Two of the three few-shot samples are
+ * indistinguishable from prose. A classifier over those would be a guess
+ * wearing a measurement's name, and it would hand out the wrong band precisely
+ * where the band matters most.
+ *
+ * So this does not classify. It sorts text into the **buckets the evidence
+ * actually separates**, and where two classes overlap it gives the worse of
+ * their bands. An overstated uncertainty costs a reader some confidence; an
+ * understated one tells them a wrong number and lets them act on it.
+ *
+ * ## What holds it
+ *
+ * `token-band.test.js` runs every corpus sample through `bandFor` and requires
+ * the sample's own measured error to be inside the band it was given. That is
+ * the whole promise, and it cannot be satisfied by tuning the thresholds: a
+ * sample sorted into a friendlier bucket gets a smaller band and fails.
+ *
+ * The figures below are derived from the fixture by the same test, which fails
+ * when they drift. They are written here rather than imported because this file
+ * ships and the fixture does not.
+ */
+
+/**
+ * The buckets, worst measured error first.
+ *
+ * Every number is `Math.ceil` of the worst sample in that bucket, from
+ * `test/fixtures/token-ground-truth.json` — Anthropic's, because that is the
+ * tokenizer this estimator was built for and the only one whose fixture governs
+ * a published claim. A DeepSeek or Mistral prompt is further out still, and
+ * `providerBandCaveat` is what says so.
+ */
+export const BANDS = {
+  /** Digit-dominant: ledgers, tables, exports. The worst the estimator does. */
+  numeric: 33,
+  /** Symbol-rich: code, markup, anything a merge table covers badly. */
+  symbolic: 26,
+  /**
+   * CJK, all three scripts.
+   *
+   * Was 10 and is 4, and the difference is the second Korean sample rather than
+   * anything in this file. Hangul had been charged a placeholder that nothing
+   * measured; one sample moved it to within ten points and two moved it to
+   * within three. The class's worst went from 10.6% to 3.2% and its standard
+   * deviation from 4.0 to 1.0.
+   */
+  cjk: 4,
+  /**
+   * Latin prose and few-shot blocks made of it. What most prompts are.
+   *
+   * Widened from 5 by `numeric-matrix`, a confusion matrix whose class labels
+   * make letters the dominant class: composition put it here, its error came
+   * out at 5.6%, and the band follows the measurement rather than the other way
+   * round. Eighteen samples, deviation 1.4 points.
+   */
+  prose: 6,
+} as const;
+
+export type BandBucket = keyof typeof BANDS;
+
+/**
+ * Where the thresholds come from.
+ *
+ * Each is the widest gap the corpus offers between the bucket it admits and
+ * everything below it, so none of them is a round number somebody liked:
+ *
+ * - `cjk` at 0.5: the CJK samples are 90.1% to 94.5% CJK and every other sample
+ *   is 0.0%. Nothing in the corpus lies between.
+ * - `numeric` at 0.30: the two numeric samples are 47.7% and 49.7% digits; the
+ *   next highest anywhere is `few-shot-extraction` at 15.3%.
+ * - `symbolic` at 0.07: this one is thin and is stated as thin. `code-sql` is
+ *   7.7% symbols and `portuguese-prose` is 6.1%, so 1.6 points of margin decide
+ *   it. Thin in the safe direction: a prose sample that crosses it is given the
+ *   symbolic band, which is wider than it needs, and no sample is given a band
+ *   narrower than its own error.
+ */
+const CJK_SHARE = 0.5;
+const DIGIT_SHARE = 0.3;
+const SYMBOL_SHARE = 0.07;
+
+/*
+  Written as escapes rather than as the characters themselves, and CodeQL is
+  why. The last range was typed as a pair of literal ideographs meaning
+  "compatibility ideographs, U+F900 to U+FAFF" — and the opening character was
+  U+8C48, the ordinary unified ideograph that shares the glyph, not the
+  compatibility one. So the range ran from U+8C48 to U+FAFF and swallowed the
+  Yi syllables, the private-use area and both surrogate halves, which meant a
+  page of astral emoji was sorted `cjk` and handed the narrowest band in the
+  file: ±4% about text nothing has ever measured.
+
+  A literal that looks right and is not is the failure mode this release exists
+  to fix, so the ranges are numbers now and the test below plants one character
+  from each block that used to be caught.
+*/
+const CJK = /[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uac00-\ud7af\uf900-\ufaff]/;
+const LETTER = /[A-Za-zÀ-ɏͰ-ϿЀ-ӿ]/;
+const DIGIT = /[0-9]/;
+
+/** The bucket a piece of text falls in, by the composition the corpus separates on. */
+export function bucketFor(text: string): BandBucket {
+  const chars = [...text].filter((ch) => !/\s/.test(ch));
+  if (chars.length === 0) return 'prose';
+
+  let cjk = 0;
+  let digits = 0;
+  let letters = 0;
+  for (const ch of chars) {
+    if (CJK.test(ch)) cjk += 1;
+    else if (DIGIT.test(ch)) digits += 1;
+    else if (LETTER.test(ch)) letters += 1;
+  }
+  const n = chars.length;
+  const symbols = n - cjk - digits - letters;
+
+  /*
+    Order is the design. CJK first because it is the one bucket with no overlap
+    at all, then digits, then symbols — each test only runs on text the previous
+    one declined, so a Korean prompt with quotation marks is CJK and not
+    symbolic. Reversing any two would let a wide bucket swallow a narrow one and
+    hand out a band nobody measured.
+  */
+  if (cjk / n >= CJK_SHARE) return 'cjk';
+  if (digits / n >= DIGIT_SHARE) return 'numeric';
+  if (symbols / n >= SYMBOL_SHARE) return 'symbolic';
+  return 'prose';
+}
+
+/**
+ * The band, as a percentage, that may be printed about this text.
+ *
+ * Never a single number for all text again. A caller that wants one figure for
+ * a mixed report should take the widest band across the texts it covers, not an
+ * average: averaging two uncertainties produces a third that describes neither.
+ */
+export function bandFor(text: string): number {
+  return BANDS[bucketFor(text)];
+}
+
+/**
+ * Whether the published band applies to a model at all.
+ *
+ * It does not, and this is the sentence that has been missing. The estimator is
+ * calibrated on Claude's tokenizer, and the same 47 samples measured against
+ * DeepSeek's own counter came out **94.5% wrong** at worst and against
+ * Mistral's **103.1%**. Trazum prices seven providers; the band is one
+ * provider's.
+ *
+ * Returns null when the model is one the band was measured on, and the provider
+ * id otherwise, so a caller can say which foreign tokenizer it is estimating
+ * against rather than printing a figure that belongs to a different one.
+ */
+export function foreignTokenizer(provider: string | null): string | null {
+  return provider === null || provider === 'anthropic' ? null : provider;
+}
+
+/**
+ * The worst error measured against a provider's own tokenizer, where anybody
+ * has run it.
+ *
+ * Two entries, and the emptiness of the rest is the point. `foreignTokenizer`
+ * could always say *this is not Claude*; what it could not say is how far off.
+ * A hedge with no figure reads as a formality, and a reader discounts it — so
+ * where the corpus has been run against the family's own counter, the report
+ * says the number, and where it has not, it says nobody has measured rather
+ * than borrowing one of these.
+ *
+ * Every value is the worst of the 47 samples in
+ * `test/fixtures/token-ground-truth.<provider>.json`, and
+ * `token-band.test.js` recomputes both from the fixtures and fails on drift.
+ * Written here rather than imported because this file ships and the fixtures
+ * do not.
+ */
+export const MEASURED_FOREIGN_ERROR_PCT: Readonly<Record<string, number>> = {
+  /** Worst on `cjk-chinese`: the estimator's CJK charge is Claude's, not this one's. */
+  deepseek: 94.5,
+  /** Worst on `german-technical`, where even Latin prose is more than twice out. */
+  mistral: 103.1,
+};
+
+/**
+ * How far out the estimator has been measured against this provider, or null.
+ *
+ * Null means unmeasured, never zero: a family nobody has run is an open
+ * question, and answering it with a number would be the exact fault this whole
+ * file exists to undo.
+ */
+export function measuredForeignError(provider: string | null): number | null {
+  if (provider === null) return null;
+  return MEASURED_FOREIGN_ERROR_PCT[provider] ?? null;
+}

package/src/conform.ts

@@ -54,6 +54,11 @@ export const CONTRACT_NAMES = [
   'bench',
   'prompt-draft',
   'position',
+  'routing-measurement',
+  'example-pruning',
+  'store-inventory',
+  'conformance',
+  'watch-cycle',
 ] as const;
 
 export type ContractName = (typeof CONTRACT_NAMES)[number];
@@ -394,6 +399,62 @@ const DOCUMENT_RULES: Record<Exclude<ContractName, 'usage-log'>, FieldRule[]> =
     rule('cannotSay', 'an array of sentences — what is deliberately not answered', isArray),
     rule('unpricedRecords', 'a count of records the catalogue cannot price', isNumber),
   ],
+  'routing-measurement': [
+    rule('slice', 'the workload object — the calls this measured', isObject),
+    rule('evaluation', 'the measurement object — verdict and agreement rates', isObject),
+  ],
+  'store-inventory': [
+    rule('providers', 'an array — one entry per provider held', isArray),
+    rule('totalRecords', 'records the store resolves to', isNumber),
+    rule(
+      'span',
+      'an object, or null when the store holds nothing',
+      (v) => v === null || isObject(v),
+    ),
+    rule('possiblyDouble', 'records the store could not tell apart', isNumber),
+    rule('unknownVersion', 'records written by a newer schema', isNumber),
+    rule('totalUsd', 'what the held records priced to', isNumber),
+    rule('unreadable', 'an array — files the store could not parse', isArray),
+  ],
+  conformance: [
+    rule(
+      'contract',
+      'the contract the input looked like, or null when nothing did',
+      (v) => v === null || typeof v === 'string',
+    ),
+    rule(
+      'because',
+      'why nothing matched, or null when something did — never a bare refusal',
+      (v) => v === null || typeof v === 'string',
+    ),
+    rule(
+      'records',
+      'records examined for a log, or null for a single document',
+      (v) => v === null || isNumber(v),
+    ),
+    rule('problems', 'an array — one entry per fault found', isArray),
+    rule('unavailable', 'an array — findings this shape cannot support', isArray),
+    rule('conforms', 'a boolean — the verdict', (v) => typeof v === 'boolean'),
+  ],
+  'watch-cycle': [
+    rule('firedAtMs', 'the instant the cycle ran', isNumber),
+    rule('crossings', 'an array — gates over their limit, news this cycle', isArray),
+    rule('suppressed', 'an array — still over, already reported', isArray),
+    rule('abstentions', 'an array — gates that could not be judged', isArray),
+    rule(
+      'gap',
+      'an object, or null when this cycle watched the whole stretch',
+      (v) => v === null || isObject(v),
+    ),
+  ],
+  'example-pruning': [
+    rule('provider', 'the provider the calls went to', (v) => typeof v === 'string'),
+    rule('model', 'the model that answered', (v) => typeof v === 'string'),
+    rule('selfAgreement', 'the model’s agreement with itself, the yardstick every removal is judged against', isNumber),
+    rule('recoverableTokens', 'tokens held by examples whose removal changed nothing measurable', isNumber),
+    rule('callsMade', 'calls actually spent', isNumber),
+    rule('contributions', 'an array — one entry per example', isArray),
+  ],
   pulse: [
     rule('beats', 'an array — one per kind', isArray),
     rule('nowMs', 'the instant the ages were taken against', isNumber),
@@ -554,6 +615,44 @@ function contractOf(doc: Record<string, unknown>): Exclude<ContractName, 'usage-
   if (Array.isArray(doc.actions) && typeof doc.arrived === 'number') return 'verification';
   if (Array.isArray(doc.actions)) return 'plan';
   if (typeof doc.verdict === 'string' && 'restsOn' in doc) return 'cost-answer';
+  /*
+    Two the inference could never reach, found by the guard that demands every
+    contract be recognisable from a document of its own shape.
+
+    The cost answer's branch above tested `restsOn`, which its contract does
+    not require: the required set is verdict, call and budget, so a conforming
+    answer that omitted the optional field was recognised as nothing at all.
+    The prompt draft had no branch of any kind — its schema has been published
+    since 1.68 and `trazum conform draft.json` has never known what it was.
+  */
+  if (typeof doc.verdict === 'string' && 'call' in doc && 'budget' in doc) return 'cost-answer';
+  if (typeof doc.prompt === 'string' && Array.isArray(doc.sections) && Array.isArray(doc.missing)) {
+    return 'prompt-draft';
+  }
+  /*
+    The five the JSON sweep contracted, and the reason they are here.
+
+    All five arrived with rules, a schema, a row in the interchange table and
+    a parity test, and none of them arrived with a branch in this function —
+    so `trazum conform verdict.json` read a real routing measurement as a
+    usage log and answered with advice about `stop_reason`. A contract that
+    cannot be recognised is a contract only reachable by somebody who already
+    knows its name, which is the opposite of what this page is for. Found by
+    running the command against its own output; `contract-coverage.test.js`
+    now requires every name to be inferable from a document.
+
+    Conformance sits before the connected report deliberately: both carry an
+    `unavailable` array, and only the conformance verdict carries `conforms`.
+  */
+  if (Array.isArray(doc.problems) && Array.isArray(doc.unavailable) && typeof doc.conforms === 'boolean') {
+    return 'conformance';
+  }
+  if (isObject(doc.evaluation) && 'slice' in doc) return 'routing-measurement';
+  if (Array.isArray(doc.contributions) && typeof doc.recoverableTokens === 'number') {
+    return 'example-pruning';
+  }
+  if (Array.isArray(doc.providers) && typeof doc.totalRecords === 'number') return 'store-inventory';
+  if (Array.isArray(doc.crossings) && Array.isArray(doc.abstentions)) return 'watch-cycle';
   if (typeof doc.provider === 'string' && Array.isArray(doc.unavailable)) return 'connected';
   return null;
 }
@@ -650,7 +749,7 @@ export function conform(text: string, options: ConformOptions = {}): Conformance
       schemaVersion: 1,
       contract: null,
       because:
-        'no contract recognised it — a roll-up has contributors and notMerged, a profile has byLabelAndModel, a plan has actions, a verification adds arrived, a history has periods and runs, a connected report has provider and unavailable, a cost answer has verdict and restsOn',
+        'no contract recognised it — a roll-up has contributors and notMerged, a profile has byLabelAndModel, a plan has actions, a verification adds arrived, a history has periods and runs, a connected report has provider and unavailable, a cost answer has verdict with call and budget, a prompt draft has prompt, sections and missing, a routing measurement has slice and evaluation, an example pruning has contributions and recoverableTokens, a store inventory has providers and totalRecords, a conformance verdict has problems and conforms, a watch cycle has crossings and abstentions',
       problems: [],
       unavailable: [],
       records: null,