@trazum/core 1.81.0 → 1.83.0

package/dist/receipt.d.ts

@@ -0,0 +1,253 @@
+import type { PricingCatalogue } from './pricing.js';
+import type { UsageProfileReport } from './usage.js';
+/**
+ * The receipt: a bill's counts, with the provenance of every figure attached.
+ *
+ * ## What it is for
+ *
+ * A profile answers a question on the terminal where it ran. A receipt is the
+ * same figures shaped so they can still answer it somewhere else: aggregated by
+ * somebody's dashboard, filed against an invoice, or compared against last
+ * month's by a reader who was not there when the command ran.
+ *
+ * That is why every line carries the rate behind its money and the date that
+ * rate was last read. A dollar figure with no provenance cannot tell a
+ * repricing from a team whose spend moved, and the consumer that most needs
+ * that distinction is the one that cannot read a sentence explaining it.
+ *
+ * ## Why a line carries money per bucket and not only a rate
+ *
+ * The first version of this module published the catalogue's `inputPerMTok`
+ * and `outputPerMTok` beside a dollar figure computed by `profileUsage`. Those
+ * are not always the same rates. A model in a promotional window, or one whose
+ * long-context tier applied, is billed at `effectivePricing`'s figure, and a
+ * cached read is billed at a fraction of input that no published field named at
+ * all. **A consumer multiplying the stated rates by the stated tokens got a
+ * different number from the stated total, with nothing saying which was
+ * wrong.**
+ *
+ * That is a bad defect in a document whose entire purpose is that a figure can
+ * be recomputed by whoever receives it, and it is the exact failure the
+ * doctrine line at the foot of this comment is about.
+ *
+ * So a line now carries the **money as it was actually apportioned** -- input,
+ * cache reads, cache writes and output -- and `usd` is their sum. The rates stay
+ * as provenance, labelled as the catalogue's published figures rather than as
+ * the arithmetic. `receipt-arithmetic.test.js` fails if the four stop adding up,
+ * which is a property a reader can check on any receipt they are handed rather
+ * than a promise they have to take.
+ *
+ * ## What it carries, and what it has no field for
+ *
+ * Counts, model, provider, the money split by bucket, the published rates, the
+ * review date, the label the log carried, the period, and what could not be
+ * priced. There is **no field
+ * for prompt text, for an answer, for a file path, for a branch name or for a
+ * credential** — not redacted, not hashed, absent, because the input this takes
+ * has nowhere to hold them either.
+ *
+ * `receipt-redaction.test.js` holds that by planting all 4 in a log — in the
+ * session field among other places, which is the value this package has
+ * promised since it shipped never comes back out — and failing if any reaches
+ * the output. A property about what a document does not contain is exactly the
+ * kind this repository proves by breaking rather than by asserting.
+ *
+ * ## What it is not
+ *
+ * **Not a transport.** Nothing here opens a socket, reads an environment
+ * variable or takes an endpoint. `receiptFrom` returns a value; where it goes
+ * is the caller's decision. A module in this package that phoned home would
+ * break the roadmap's first rule, which is that no feature may make a network
+ * call a prerequisite for anything.
+ *
+ * **Not a new measurement.** Every figure is one `profileUsage` already
+ * produced. This adds provenance around them and takes nothing away.
+ *
+ * Doctrine: [A machine reader gets the provenance too](../../../docs/doctrine.md#a-machine-reader-gets-the-provenance-too)
+ */
+/**
+ * The catalogue's published rates for this model, and when a human last read
+ * them off the provider's own page.
+ *
+ * **Provenance, not the arithmetic.** These are list rates. The money that was
+ * actually apportioned is in `ReceiptLine.money`, and the two differ whenever a
+ * promotion or a long-context tier applied, or for any token billed at a
+ * fraction of input -- which is every cached read. A consumer wanting the rate
+ * that was really charged divides a bucket's money by its tokens; a consumer
+ * wanting to know whether a provider repriced compares these.
+ */
+export interface ReceiptPricing {
+    provider: string;
+    inputPerMTok: number;
+    outputPerMTok: number;
+    /**
+     * The date this provider's rates were last read off its own page, `null`
+     * when the catalogue carries no date for that provider.
+     *
+     * Per provider rather than per catalogue, because that is how the prices are
+     * actually reviewed: looking at one page and finding nothing changed is not
+     * the same event as not looking. A server comparing two receipts a month
+     * apart reads a repricing as a repricing instead of as a team missing a
+     * target.
+     */
+    reviewedOn: string | null;
+}
+/** Where a line's money went. The four add to `ReceiptLine.usd`. */
+export interface ReceiptMoney {
+    inputUsd: number;
+    cacheReadUsd: number;
+    cacheWriteUsd: number;
+    outputUsd: number;
+}
+/** One slice of a bill: a label's calls to one model. */
+export interface ReceiptLine {
+    /**
+     * The attribution the log carried, or `null` for the unlabelled bucket.
+     *
+     * `null` rather than the sentinel, which is an internal grouping key and is
+     * never serialised. A consumer that saw the raw sentinel would have to know
+     * this package's internals to render it.
+     */
+    label: string | null;
+    model: string;
+    calls: number;
+    inputTokens: number;
+    cacheReadTokens: number;
+    /** Every cache write, whatever its TTL. The sum of the two fields below. */
+    cacheWriteTokens: number;
+    /**
+     * The two write TTLs kept apart, because they are billed at different rates.
+     *
+     * They are here for the same reason `UsageBreakdown` keeps them: the ratio
+     * between them is not a constant across providers, so a total that has lost
+     * the split can be repriced only by guessing at it. A consumer repricing this
+     * traffic against another model's rates needs both.
+     */
+    cacheWrite5mTokens: number;
+    cacheWrite1hTokens: number;
+    outputTokens: number;
+    /**
+     * What it cost, which is exactly the sum of `money` below.
+     *
+     * Every line here is priced; what is not is in `gaps`.
+     */
+    usd: number;
+    /**
+     * Where the money went, as it was apportioned rather than as it might be
+     * recomputed.
+     *
+     * This is the field that makes a receipt checkable. `usd` alone can only be
+     * believed; these four can be added up, and each can be divided by its own
+     * token count to recover the rate that was really charged -- including the
+     * one for cached reads, which no published rate names.
+     */
+    money: ReceiptMoney;
+    /** The catalogue's published rates, as provenance. */
+    pricing: ReceiptPricing;
+}
+/** Everything a receipt refuses to answer, typed rather than left implicit. */
+export type ReceiptGap = 
+/**
+ * Models the catalogue does not price, with the size of what they used.
+ *
+ * The counts are here rather than in a line, and the first draft of this
+ * module got that wrong in a way its own guard caught. `byLabelAndModel`
+ * excludes unpriced calls on purpose — the profile keeps them apart so that
+ * a total is never tokens from one set of calls over dollars from another —
+ * so a receipt built from that list alone silently loses them.
+ *
+ * The obvious repair was worse than the bug: emit a line with `label: null`.
+ * That reads as *this call carried no label*, when in fact it carried one the
+ * profile could not attach to a priced slice. Conflating "unlabelled" with
+ * "unattributable" is the exact failure this project refuses elsewhere, so
+ * the gap carries the magnitude instead and nothing pretends to an
+ * attribution it does not have.
+ */
+{
+    kind: 'unpriced';
+    models: string[];
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+} | {
+    kind: 'unread-lines';
+    count: number;
+} | {
+    kind: 'no-clock';
+}
+/**
+ * Calls whose cache-write TTL the log did not state, so the cheaper rate was
+ * assumed.
+ *
+ * Reported because it changes what kind of figure this is. A total that
+ * includes an assumed TTL is a **floor** on those calls, not a measurement,
+ * and a document that says `counting: 'counted'` while quietly resting on an
+ * assumption is claiming a precision it does not have.
+ */
+ | {
+    kind: 'assumed-write-ttl';
+    calls: number;
+};
+export interface ReceiptDocument {
+    /** The one thing a consumer must branch on. Set here, by the builder. */
+    schemaVersion: 1;
+    /**
+     * When this receipt was made, or `null`.
+     *
+     * Optional on purpose, and the reason is the same one `plan.json` gives: a
+     * document without a stamp is undated, which a reader can act on. A document
+     * with an invented stamp is wrong, which they cannot.
+     */
+    emittedAt: string | null;
+    /** The period the counts cover, from the log's own clock. */
+    span: {
+        fromMs: number;
+        toMs: number;
+        calls: number;
+    } | null;
+    /**
+     * How the tokens were arrived at.
+     *
+     * `counted` for every receipt this function builds, because a usage log
+     * carries the provider's own counts. The field exists because a receipt built
+     * from an estimate would be a different kind of evidence, and a consumer must
+     * never have to guess which one it is holding.
+     */
+    counting: 'counted';
+    lines: ReceiptLine[];
+    total: {
+        calls: number;
+        usd: number;
+    };
+    /**
+     * What this receipt cannot say, and why.
+     *
+     * Present and empty rather than absent when there is nothing to report:
+     * "nothing was refused" and "this document does not record refusals" are
+     * different statements, and a server aggregating a thousand receipts has to
+     * be able to tell them apart.
+     */
+    gaps: ReceiptGap[];
+}
+/**
+ * The fields that leave this machine, listed once, in one place.
+ *
+ * The redaction guard reads this array rather than a copy of it, so a field
+ * added to `ReceiptLine` and not added here fails the guard. A whitelist
+ * maintained in two places is a whitelist with a hole in it.
+ */
+export declare const RECEIPT_LINE_FIELDS: readonly ["label", "model", "calls", "inputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite5mTokens", "cacheWrite1hTokens", "outputTokens", "usd", "money", "pricing"];
+export interface ReceiptOptions {
+    /** Stamp the document. Omit for an undated receipt, which is valid. */
+    emittedAt?: Date;
+}
+/**
+ * Build a receipt from a profile the caller already computed.
+ *
+ * Takes the report rather than the log text, and that is the guarantee rather
+ * than an ergonomic choice: `UsageProfileReport` has no field that can hold
+ * prompt content, so this function could not emit any even if it tried. The
+ * narrow input is what makes the promise checkable instead of merely stated.
+ */
+export declare function receiptFrom(report: UsageProfileReport, catalogue: PricingCatalogue, options?: ReceiptOptions): ReceiptDocument;
+//# sourceMappingURL=receipt.d.ts.map

package/dist/receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.d.ts","sourceRoot":"","sources":["../src/receipt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAkB,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;;;;OASG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,KAAK,EAAE,YAAY,CAAC;IACpB,sDAAsD;IACtD,OAAO,EAAE,cAAc,CAAC;CACzB;AAED,+EAA+E;AAC/E,MAAM,MAAM,UAAU;AACpB;;;;;;;;;;;;;;;GAeG;AACD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAChG;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE;AACtB;;;;;;;;GAQG;GACD;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,aAAa,EAAE,CAAC,CAAC;IACjB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,6DAA6D;IAC7D,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7D;;;;;;;OAOG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC;;;;;;;OAOG;IACH,IAAI,EAAE,UAAU,EAAE,CAAC;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,mLAarB,CAAC;AA8CZ,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,kBAAkB,EAC1B,SAAS,EAAE,gBAAgB,EAC3B,OAAO,GAAE,cAAmB,GAC3B,eAAe,CA8CjB"}

package/dist/receipt.js

@@ -0,0 +1,111 @@
+import { PROVIDER_REVIEWED, modelFrom } from './pricing.js';
+import { UNLABELLED } from './usage.js';
+/**
+ * The fields that leave this machine, listed once, in one place.
+ *
+ * The redaction guard reads this array rather than a copy of it, so a field
+ * added to `ReceiptLine` and not added here fails the guard. A whitelist
+ * maintained in two places is a whitelist with a hole in it.
+ */
+export const RECEIPT_LINE_FIELDS = Object.freeze([
+    'label',
+    'model',
+    'calls',
+    'inputTokens',
+    'cacheReadTokens',
+    'cacheWriteTokens',
+    'cacheWrite5mTokens',
+    'cacheWrite1hTokens',
+    'outputTokens',
+    'usd',
+    'money',
+    'pricing',
+]);
+const lineFrom = (label, model, breakdown, catalogue) => {
+    /*
+     * Every slice reaching here is priced: `byLabelAndModel` holds only what the
+     * catalogue knows. What it does not know is reported by the `unpriced` gap,
+     * with its size, so the receipt's total is never mistaken for the whole bill.
+     */
+    const priced = modelFrom(catalogue, model);
+    return {
+        label: label === UNLABELLED ? null : label,
+        model,
+        calls: breakdown.calls,
+        inputTokens: breakdown.inputTokens,
+        cacheReadTokens: breakdown.cacheReadTokens,
+        cacheWriteTokens: breakdown.cacheWriteTokens,
+        cacheWrite5mTokens: breakdown.cacheWrite5mTokens,
+        cacheWrite1hTokens: breakdown.cacheWrite1hTokens,
+        outputTokens: breakdown.outputTokens,
+        usd: breakdown.totalUsd,
+        /*
+         * Copied from the breakdown rather than recomputed from the rates below.
+         * Recomputing would reintroduce the defect this field exists to fix: the
+         * published rates are list rates, and a promotion, a long-context tier or
+         * any cached token is billed at something else.
+         */
+        money: {
+            inputUsd: breakdown.inputUsd,
+            cacheReadUsd: breakdown.cacheReadUsd,
+            cacheWriteUsd: breakdown.cacheWriteUsd,
+            outputUsd: breakdown.outputUsd,
+        },
+        pricing: {
+            provider: priced.provider ?? 'unknown',
+            inputPerMTok: priced.inputPerMTok,
+            outputPerMTok: priced.outputPerMTok,
+            reviewedOn: PROVIDER_REVIEWED[priced.provider ?? ''] ?? null,
+        },
+    };
+};
+/**
+ * Build a receipt from a profile the caller already computed.
+ *
+ * Takes the report rather than the log text, and that is the guarantee rather
+ * than an ergonomic choice: `UsageProfileReport` has no field that can hold
+ * prompt content, so this function could not emit any even if it tried. The
+ * narrow input is what makes the promise checkable instead of merely stated.
+ */
+export function receiptFrom(report, catalogue, options = {}) {
+    const lines = report.byLabelAndModel.map((slice) => lineFrom(slice.label, slice.model, slice.breakdown, catalogue));
+    const gaps = [];
+    if (report.unpricedModels.length > 0) {
+        gaps.push({
+            kind: 'unpriced',
+            models: [...report.unpricedModels],
+            calls: report.unpriced.calls,
+            inputTokens: report.unpriced.inputTokens,
+            outputTokens: report.unpriced.outputTokens,
+        });
+    }
+    if (report.skippedLines.length > 0) {
+        gaps.push({ kind: 'unread-lines', count: report.skippedLines.length });
+    }
+    if (report.span === null)
+        gaps.push({ kind: 'no-clock' });
+    /*
+     * Summed across the lines rather than read off a total, because the profile
+     * keeps this per slice and a receipt reports it once for the document.
+     */
+    const assumed = report.byLabelAndModel.reduce((sum, slice) => sum + slice.breakdown.assumedWriteTtlCalls, 0);
+    if (assumed > 0)
+        gaps.push({ kind: 'assumed-write-ttl', calls: assumed });
+    return {
+        schemaVersion: 1,
+        emittedAt: options.emittedAt?.toISOString() ?? null,
+        span: report.span === null ? null : { ...report.span },
+        counting: 'counted',
+        lines,
+        /*
+         * `report.total` already excludes what could not be priced — the profile
+         * keeps those in `unpriced` precisely so a total is never tokens from one
+         * set of calls divided by dollars from another. The receipt inherits that
+         * separation rather than re-deriving it, and `gaps` carries the size of
+         * what is missing.
+         */
+        total: { calls: report.total.calls, usd: report.total.totalUsd },
+        gaps,
+    };
+}
+//# sourceMappingURL=receipt.js.map

package/dist/receipt.js.map

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

package/dist/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AA6CjD;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoG1E,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE1E"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AA6CjD;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwI1E,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE1E"}

package/dist/schemas.js

@@ -145,6 +145,42 @@ export const CONTRACT_SCHEMAS = {
         cannotSay: array,
         unpricedRecords: number,
     }),
+    'routing-measurement': doc('routing-measurement', {
+        slice: object,
+        evaluation: object,
+    }),
+    'example-pruning': doc('example-pruning', {
+        provider: string,
+        model: string,
+        selfAgreement: number,
+        recoverableTokens: number,
+        callsMade: number,
+        contributions: array,
+    }),
+    'store-inventory': doc('store-inventory', {
+        providers: array,
+        totalRecords: number,
+        span: objectOrNull,
+        possiblyDouble: number,
+        unknownVersion: number,
+        totalUsd: number,
+        unreadable: array,
+    }),
+    conformance: doc('conformance', {
+        contract: stringOrNull,
+        because: stringOrNull,
+        problems: array,
+        unavailable: array,
+        records: { type: ['number', 'null'] },
+        conforms: boolean,
+    }),
+    'watch-cycle': doc('watch-cycle', {
+        firedAtMs: number,
+        crossings: array,
+        suppressed: array,
+        abstentions: array,
+        gap: objectOrNull,
+    }),
 };
 /** The schema for one named contract — the object `trazum schema` prints. */
 export function contractSchema(name) {

package/dist/schemas.js.map

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

package/dist/tokenizer.d.ts

@@ -2,71 +2,67 @@
  * Dependency-free token estimator.
  *
  * This is NOT a real tokenizer: it is a heuristic calibrated per character
- * class. It is built to keep the typical error on ordinary text
- * (English/Spanish, markdown, code) inside ±10%, which is plenty for comparing
- * two versions of the same prompt — but do NOT bill anyone from it.
+ * class, built for comparing two versions of the same prompt — but do NOT bill
+ * anyone from it.
  *
- * **That band is a design target that has not been measured.** It is printed on
- * every report and every dollar figure descends from it, and until
- * `scripts/measure-token-band.mjs` has been run against the official counting
- * endpoint, nothing in this repository establishes that it holds. It is stated
- * as one number for all text, which is a further assumption: the branches below
- * treat CJK, digits and punctuation quite differently from words, and there is
- * no reason those should land on the same accuracy.
+ * **Its accuracy is not one number, and the years it was written as one were
+ * the mistake.** The branches below treat CJK, digits and punctuation quite
+ * differently from words, and there was never a reason those should land on the
+ * same accuracy. Measured over 47 samples against the official counting
+ * endpoint they do not: the worst error is 3.2% on CJK, 5.6% on Latin prose,
+ * 25.1% on code and quoting, and 32.5% on a digit-dominant table. `band.ts`
+ * holds the bands those measurements earn and `bandFor(text)` is what a caller
+ * should print; the constant below is only the widest of them, for callers that
+ * have no text in hand.
  *
- * `test/token-band.test.js` asserts the band per text type as soon as the ground
- * truth exists. Until then it says so rather than passing quietly.
+ * `test/token-band.test.js` holds every sample against the band `bandFor` gives
+ * it, and a sample edited since it was measured fails rather than passing
+ * quietly.
  *
  * For exact numbers use `countTokensAnthropic` (the official token-counting
  * endpoint, which is free) or pass your own `TokenCounter`.
  */
 /**
- * The error band this estimator is published under, as a percentage.
+ * The widest band this estimator is published under, as a percentage.
  *
- * **Measured, not chosen, and it has moved three times.** It was `15` for eight
- * releases as a design target nobody had checked; the first measurement found two
- * of eight samples outside it and it went to `25`; fixing the digit divisor and
- * calibrating per language brought it back to `15`. This is the fourth value and
- * the first one that is comfortably above what the corpus actually shows.
+ * **A history worth keeping, because each value was believed at the time.** It
+ * was `15` for eight releases as a design target nobody had checked; the first
+ * measurement found two of eight samples outside it and it went to `25`; fixing
+ * the digit divisor and calibrating per language brought it back to `15`, and
+ * splitting kana from han — Japanese had been +11.2% and Chinese −3.2% under one
+ * rule — brought it to `10`. Four values, each an improvement, and all four
+ * wrong in the same way.
  *
- * ```
- * worst measured error   6.4%   (code-heavy, which nothing is fitted to)
- * published band        10%
- * ```
+ * **The corpus they were measured on was the corpus they were fitted to.**
+ * Twenty-one samples held thirteen files of Latin prose and exactly one each of
+ * code, numeric and punctuation, and those single files were where the constants
+ * came from. The worst error it could show was 6.4%, and 10 looked like a
+ * comfortable margin over it. Neither figure was about the estimator.
  *
- * **The margin is deliberate and it is not slack.** 6.4 rounded up is 7, and
- * publishing 7 would be a tighter claim than twenty-one samples across six text
- * types can support: the corpus has no Korean, no Arabic, no Cyrillic prose, no
- * mixed-script document, and a seventh text type could easily land at eight. A
- * band that becomes false the first time somebody measures something new is the
- * exact fault this whole exercise was fixing. Overstating the uncertainty is the
- * safe direction for a tool that reports money.
+ * **It is no longer one number, and this one is the widest.** A corpus of
+ * thirteen prose files and one each of code, numeric and punctuation put the
+ * band at 10, and those single files were the set the constants had been fitted
+ * to. Measured on forty-seven, the same estimator is 6% out on prose and 33%
+ * out on a CSV ledger. `bandFor` in `band.ts` is what a caller that has the
+ * text should use.
  *
- * What earned the drop from 15 was **splitting kana from han**. Every CJK
- * character was charged one token, which put Japanese at +11.2% — the worst error
- * anywhere in the corpus — while Chinese sat at −3.2% under the same rule. Kana
- * measure 0.75 tokens per character and han 1.05, and that pair takes the two
- * samples to −1.5% and +1.3%. See `KANA_TOKENS_PER_CHAR`.
- *
- * **Which samples the band rests on matters more than the number.** Eight of the
- * twenty-one had a constant fitted to them — seven Latin divisors and the digit
- * divisor — so their residuals are optimistic by construction. The two worst
- * errors in the corpus, `code-heavy` at 6.4% and `punctuation-heavy` at 5.7%, are
- * fitted to nothing at all, and they are what sets this figure.
- *
- * Exported so every report, README and tool description reads the same number. It
- * was a literal in twenty-four files before this, with the only machine-readable
- * copy in a test, and `token-band.test.js` now fails any file that states a
- * different one.
+ * This stays for the callers that do not have it — a figure covering the whole
+ * catalogue of text, which can only be the worst of them. Widening it from 10
+ * to 33 makes every claim that reads it true where it had been false, at the
+ * cost of understating the estimator on prose. That trade is deliberate: a
+ * caller with no text cannot know which it is holding, and there is only one
+ * safe direction to guess in.
  */
-export declare const ESTIMATE_ERROR_BAND_PCT = 10;
+export declare const ESTIMATE_ERROR_BAND_PCT = 33;
 /**
  * Whose tokenizer that band was measured against.
  *
  * The number above is not a property of the estimator; it is a property of the
- * estimator **against Claude**. Twenty-one samples, one counting endpoint, one
- * family. Trazum prices seven, and until somebody runs the harness against the
- * others nobody knows what the error is on a GPT or a Gemini prompt.
+ * estimator **against Claude**. Forty-seven samples, one counting endpoint, one
+ * family. Trazum prices seven, and the two that have since been run are far
+ * outside anything published here: DeepSeek 94.5% at worst, Mistral 103.1%. On
+ * a GPT or a Gemini prompt nobody has measured it at all, and
+ * `measuredForeignError` answers null rather than the nearest number.
  *
  * Exported as a name rather than left implicit in a comment because the band
  * had already leaked out of its domain in three places: an advisory that told a

package/dist/tokenizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokenizer.d.ts","sourceRoot":"","sources":["../src/tokenizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,cAAc,CAAC;AAEpD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAExE;AAmGD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuHnD;AAED,sDAAsD;AACtD,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAElE,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,gFAAgF;IAChF,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,iBAAiB,CA6BxF"}
+{"version":3,"file":"tokenizer.d.ts","sourceRoot":"","sources":["../src/tokenizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,cAAc,CAAC;AAEpD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAExE;AA+HD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiJnD;AAED,sDAAsD;AACtD,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAElE,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,gFAAgF;IAChF,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,iBAAiB,CA6BxF"}