@trazum/core 1.80.1 → 1.82.0

package/dist/verdict-bridge.js

@@ -0,0 +1,127 @@
+/**
+ * Reading a dropped `route --json` verdict, so quality can stand beside cost.
+ *
+ * The bill is arithmetic: every figure in it comes from records already on
+ * disk, and it can say exactly what a cheaper model would have saved. It can
+ * say nothing at all about whether that model still does the job. That answer
+ * costs provider calls and a credential, which is why `trazum route` exists
+ * and why no surface that only reads a log will ever produce it.
+ *
+ * This is the bridge between the two, and it is deliberately one-directional:
+ * the measurement is made where the credential is, written out as the
+ * `routing-measurement` contract, and read back here by a pure function that
+ * touches no network and holds no key. A reader who has run `route` once can
+ * carry the verdict to any surface that prices the same workload.
+ *
+ * It was not possible to write until the document was worth reading. Before
+ * the JSON-text sweep, `route --json` printed the whole `EvalReport` — every
+ * case input and three model answers per case — so a bridge would have been a
+ * feature for carrying prompt text into a browser. The document carries the
+ * measurement and nothing else now, and `conform` is what says so rather than
+ * this file's own reading: the contract validates, the bridge only maps.
+ */
+import { conform } from './conform.js';
+import { UNLABELLED } from './usage.js';
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Whether this file is even claiming to be a routing measurement.
+ *
+ * Shape only, and deliberately narrow: an `evaluation` object carrying a
+ * `verdict`. Anything looser would swallow a usage log or a profile and
+ * refuse it in this file's words instead of letting the caller price it.
+ */
+function claimsToBeOne(parsed) {
+    if (!isObject(parsed))
+        return false;
+    const evaluation = parsed.evaluation;
+    return isObject(evaluation) && typeof evaluation.verdict === 'string';
+}
+/**
+ * Reads a dropped `trazum route --json` document.
+ *
+ * Returns null when the text is something else entirely. Validation is
+ * `conform`'s, against the published `routing-measurement` contract, so this
+ * function cannot drift from the schema a connector author builds against —
+ * and a document that fails carries the contract's own sentences back to the
+ * reader rather than a second opinion written here.
+ */
+export function readDroppedVerdict(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!claimsToBeOne(parsed))
+        return null;
+    const report = conform(text, { contract: 'routing-measurement' });
+    if (!report.conforms) {
+        const detail = report.problems.length > 0
+            ? report.problems.map((problem) => `${problem.at}: ${problem.detail}`).join('; ')
+            : (report.because ?? 'it does not match the routing-measurement contract');
+        return { kind: 'refusal', because: detail };
+    }
+    const document = parsed;
+    const slice = isObject(document.slice) ? document.slice : {};
+    const evaluation = document.evaluation;
+    /**
+     * Every field below is read defensively even though `conform` has passed,
+     * because the contract requires `slice` and `evaluation` to be objects and
+     * says nothing about what is inside them. A document from a future version
+     * with a thinner slice is a document this reads what it can from, not one
+     * it crashes on.
+     */
+    const answered = typeof evaluation.model === 'string' ? evaluation.model : null;
+    // The slice's model first: that is the fact the bill can be matched against.
+    const model = typeof slice.model === 'string' ? slice.model : answered;
+    const candidateModel = typeof evaluation.candidateModel === 'string' ? evaluation.candidateModel : null;
+    const verdict = typeof evaluation.verdict === 'string' ? evaluation.verdict : null;
+    if (model === null || candidateModel === null || verdict === null) {
+        return {
+            kind: 'refusal',
+            because: 'the evaluation names no model, candidate model or verdict, so there is nothing to set beside a bill',
+        };
+    }
+    const number = (value) => (typeof value === 'number' ? value : 0);
+    const route = isObject(slice.route) ? slice.route : null;
+    const rawLabel = typeof slice.label === 'string' ? slice.label : null;
+    return {
+        kind: 'verdict',
+        verdict: {
+            // `UNLABELLED` is the profile's own sentinel for calls that carry no
+            // label. It travels through the document as that sentinel and comes
+            // back as null here, so the bridge speaks the bill's language rather
+            // than leaking an internal marker into a caption.
+            label: rawLabel === null || rawLabel === UNLABELLED ? null : rawLabel,
+            model,
+            measuredOn: answered !== null && answered !== model ? answered : null,
+            candidateModel,
+            verdict,
+            selfAgreement: number(evaluation.selfAgreement),
+            crossAgreement: number(evaluation.crossAgreement),
+            cases: Array.isArray(evaluation.cases) ? evaluation.cases.length : 0,
+            callsMade: number(evaluation.callsMade),
+            savingUsd: route !== null && typeof route.savingUsd === 'number' ? route.savingUsd : null,
+        },
+    };
+}
+/**
+ * Whether a verdict describes the route a given slice of the bill is offering.
+ *
+ * Both halves must agree or the pairing is a lie: the same workload, the same
+ * model it goes to now, and the same candidate. A verdict measured on `chat`
+ * shown against `summarise`'s saving would be the exact fault this repository
+ * keeps finding in itself — a number describing something other than what was
+ * measured — and matching on the model alone would produce it on any log with
+ * two workloads on one model.
+ */
+export function verdictMatchesSlice(verdict, slice) {
+    if (slice.route === null)
+        return false;
+    const sliceLabel = slice.label === UNLABELLED ? null : slice.label;
+    return (sliceLabel === verdict.label &&
+        slice.model === verdict.model &&
+        slice.route.candidate.id === verdict.candidateModel);
+}
+//# sourceMappingURL=verdict-bridge.js.map

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.80.1",
+  "version": "1.82.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

@@ -7,7 +7,8 @@ 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 +17,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 +61,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> = {
@@ -142,7 +185,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 +308,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 +362,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 +449,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 +494,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({

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/claude-code.ts

@@ -81,6 +81,34 @@ export interface ClaudeCodeConversion {
    * are excluded by name and counted here, and the caller says how many.
    */
   synthetic: number;
+  /**
+   * Where a later run may safely pick this transcript up again.
+   *
+   * A transcript is append-only, so re-reading two hundred megabytes to learn
+   * what the last thirty seconds added is waste, and on the largest real
+   * session on one machine it is six and a half seconds of waste. The obstacle
+   * to resuming is this converter's own rule: **one call arrives as several
+   * lines and the last one stands**, so a call whose lines straddle the point
+   * where a run stopped would be recorded from its later half only.
+   *
+   * So the resume point is not the end of what was read. It is the first line
+   * of the last call seen, which is the only call that can still gain lines.
+   * `records` says how many of `records` above are settled and will never be
+   * revised; everything from `line` onwards is re-derived next time, and the
+   * caller drops the unsettled tail before appending.
+   *
+   * Measured on 208 real transcripts, 36,468 lines carrying a `requestId`: a
+   * call's lines are contiguous, and no `requestId` ever reappeared after
+   * another had begun. The design does not lean on that. It re-derives the
+   * final call whether or not it needed re-deriving, because a measurement on
+   * one machine is evidence and not a guarantee.
+   */
+  resume: {
+    /** Line index to start from next time, counting every line of the text read. */
+    line: number;
+    /** How many leading entries of `records` are settled. */
+    records: number;
+  };
 }
 
 /** The model id Claude Code writes for a turn no provider ever saw. */
@@ -109,13 +137,16 @@ export function claudeCodeRecords(
     streamed: 0,
     disagreements: 0,
     synthetic: 0,
+    resume: { line: 0, records: 0 },
   };
   /** requestId → index into out.records, so a later line can replace the usage. */
   const byRequest = new Map<string, number>();
   /** requestId → the usage currently standing, to classify a change when one arrives. */
   const seenUsage = new Map<string, ClaudeCodeRecord['usage']>();
 
-  for (const line of text.split('\n')) {
+  const lines = text.split('\n');
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]!;
     if (line.trim() === '') continue;
     let raw: unknown;
     try {
@@ -186,14 +217,20 @@ export function claudeCodeRecords(
 
     const requestId = typeof entry.requestId === 'string' ? entry.requestId : null;
     if (requestId === null) {
+      // Nothing keys this line, so nothing can ever revise it: it is settled
+      // the moment it is read, and the resume point moves past it.
       out.noRequestId += 1;
       out.records.push(record);
+      out.resume = { line: index + 1, records: out.records.length };
       continue;
     }
     const standing = byRequest.get(requestId);
     if (standing === undefined) {
+      // A call begins. Everything before it is settled; this call is not,
+      // because the next line of the transcript may still revise it.
       byRequest.set(requestId, out.records.length);
       seenUsage.set(requestId, record.usage);
+      out.resume = { line: index, records: out.records.length };
       out.records.push(record);
       continue;
     }
@@ -217,6 +254,21 @@ export function claudeCodeRecords(
     }
     out.records[standing] = { ...record };
   }
+
+  /**
+   * Nothing carrying usage was found, so everything read is settled and the
+   * resume point is the end of it.
+   *
+   * With one exception, and it is the one that would lose a record rather than
+   * merely re-derive one: a transcript being appended to can be read mid-line,
+   * and that half-line parses as nothing. Resuming past it would drop the call
+   * it becomes. So when the text does not end in a newline, the resume point
+   * never passes the start of its final line.
+   */
+  if (out.records.length === 0) out.resume = { line: lines.length, records: 0 };
+  if (text !== '' && !text.endsWith('\n')) {
+    out.resume = { ...out.resume, line: Math.min(out.resume.line, lines.length - 1) };
+  }
   return out;
 }