@trazum/core 1.86.0 → 2.1.0

package/src/config-schema.ts

@@ -314,48 +314,104 @@ export interface TrazumConfig {
   pricing?: string;
 }
 
+/**
+ * A key list bound to the shape it describes.
+ *
+ * Every list below is what `rejectUnknownKeys` compares an incoming config
+ * against, and each one is a second copy of an interface declared elsewhere in
+ * this file. Nothing held them together. A plant added `telemetry?: boolean` to
+ * `TrazumConfig`, left `CONFIG_KEYS` alone, and **all 2,115 core tests passed**
+ * — leaving a documented setting the parser refuses by name, and the reverse
+ * plant leaving a key the parser accepts and nothing reads, which is the worse
+ * of the two because it is silent.
+ *
+ * `Record<keyof T, true>` closes both directions at compile time. The published
+ * arrays are derived from the maps rather than written again: key order is
+ * insertion order, so what a consumer reads is unchanged.
+ */
+const keyList = <T>(map: Record<keyof T, true>): readonly (keyof T & string)[] =>
+  Object.keys(map) as (keyof T & string)[];
+
 /**
  * Every key the config accepts. Exported so the CLI's help can be tested
  * against it rather than against a second hand-maintained list — a setting the
  * help never mentions is one only the changelog knows about.
  */
-export const CONFIG_KEYS = [
-  'level',
-  'locale',
-  'disable',
-  'usage',
-  'budgets',
-  'labels',
-  'spend',
-  'limits',
-  'sources',
-  'store',
-  'waive',
-  'maxGrowth',
-  'baseline',
-  'extensions',
-  'ignore',
-  'pricing',
-  'outcomes',
-  'ladders',
-  'owners',
-] as const;
-
-export const CONFIG_BASELINE_KEYS = ['path', 'maxGrowthTokens', 'maxGrowthPct'] as const;
-
-export const CONFIG_SPEND_KEYS = ['maxUsd', 'monthlyUsd', 'maxDayUsd', 'maxSessionUsd', 'maxCacheLossUsd', 'byLabel', 'bySource', 'substitute'] as const;
-
-export const CONFIG_LIMITS_KEYS = ['dayUsd', 'sessionUsd', 'byLabel'] as const;
-
-export const CONFIG_WAIVE_KEYS = ['gate', 'reason', 'until'] as const;
-
-export const CONFIG_STORE_KEYS = ['keepDays'] as const;
-
-export const CONFIG_OUTCOME_KEYS = ['values', 'success'] as const;
-
-export const CONFIG_LADDER_KEYS = ['tiers', 'escalateOn'] as const;
-
-export const CONFIG_OWNERS_KEYS = ['patterns', 'shared', 'budgets'] as const;
+export const CONFIG_KEYS = keyList<TrazumConfig>({
+  level: true,
+  locale: true,
+  disable: true,
+  usage: true,
+  budgets: true,
+  labels: true,
+  spend: true,
+  limits: true,
+  sources: true,
+  store: true,
+  waive: true,
+  maxGrowth: true,
+  baseline: true,
+  extensions: true,
+  ignore: true,
+  pricing: true,
+  outcomes: true,
+  ladders: true,
+  owners: true,
+});
+
+export const CONFIG_BASELINE_KEYS = keyList<BaselineConfig>({
+  path: true,
+  maxGrowthTokens: true,
+  maxGrowthPct: true,
+});
+
+export const CONFIG_SPEND_KEYS = keyList<SpendConfig>({
+  maxUsd: true,
+  monthlyUsd: true,
+  maxDayUsd: true,
+  maxSessionUsd: true,
+  maxCacheLossUsd: true,
+  byLabel: true,
+  bySource: true,
+  substitute: true,
+});
+
+export const CONFIG_LIMITS_KEYS = keyList<LimitsConfig>({
+  dayUsd: true,
+  sessionUsd: true,
+  byLabel: true,
+});
+
+export const CONFIG_WAIVE_KEYS = keyList<WaiveEntry>({
+  gate: true,
+  reason: true,
+  until: true,
+});
+
+/*
+  `store` has no named interface, so the shape is reached through the field
+  itself. Naming a type purely to bind a list would put a third copy in the
+  file, which is the fault this is fixing.
+*/
+export const CONFIG_STORE_KEYS = keyList<NonNullable<TrazumConfig['store']>>({
+  keepDays: true,
+});
+
+export const CONFIG_OUTCOME_KEYS = keyList<OutcomeVocabulary>({
+  values: true,
+  success: true,
+});
+
+export const CONFIG_LADDER_KEYS = keyList<LadderPolicy>({
+  tiers: true,
+  escalateOn: true,
+});
+
+export const CONFIG_OWNERS_KEYS = keyList<OwnersConfig>({
+  patterns: true,
+  shared: true,
+  budgets: true,
+});
 
 /**
  * The gates a waiver can silence. The list is closed on purpose: a waiver
@@ -370,13 +426,13 @@ export const WAIVABLE_GATES = [
   'maxGrowthUsd',
 ] as const;
 
-export const CONFIG_USAGE_KEYS = [
-  'model',
-  'callsPerMonth',
-  'avgOutputTokens',
-  'cacheHitRate',
-  'batchEligible',
-] as const;
+export const CONFIG_USAGE_KEYS = keyList<UsageProfile>({
+  model: true,
+  callsPerMonth: true,
+  avgOutputTokens: true,
+  cacheHitRate: true,
+  batchEligible: true,
+});
 
 const TOP_LEVEL_KEYS = CONFIG_KEYS;
 const USAGE_KEYS = CONFIG_USAGE_KEYS;

package/src/index.ts

@@ -348,10 +348,16 @@ export type { RepeatedTurns, RepeatsOptions, RepeatsTracker } from './repeats.js
 // See context-pressure.ts.
 export { contextPressure } from './context-pressure.js';
 export type { ContextPressure, ContextPressureOptions } from './context-pressure.js';
-export { priceTokensOn, repriceProfile } from './reprice.js';
+export { priceTokensOn, repriceProfile, repriceReceipt } from './reprice.js';
 export { ownRate, switchAnalysis } from './switch.js';
 export type { BreakEvenRefusal, SwitchAnalysis, SwitchOptions } from './switch.js';
-export type { OverContextSlice, RepriceReport, RepricedSlice } from './reprice.js';
+export type {
+  OverContextSlice,
+  RepriceReport,
+  RepriceableInput,
+  RepriceableSlice,
+  RepricedSlice,
+} from './reprice.js';
 export { createSessionLedgerTracker, singleTurnCacheWrites } from './session-ledger.js';
 // What one conversation costs — median and p95, exact. See session-cost.ts.
 export { createSessionCostTracker, sessionCostShapes } from './session-cost.js';

package/src/optimize.ts

@@ -189,7 +189,22 @@ export function optimize(prompt: string, options: OptimizeOptions = {}): Optimiz
 
   const ruleResults: RuleResult[] = [...byRule.values()];
 
-  const optimized = unmask(current, vault).trim();
+  /*
+    **Trimmed before the masks come off, not after.** `unmask(...).trim()` runs
+    on the reassembled string, where a protected span is ordinary text again —
+    so the trim could edit content every mask in this pipeline had just
+    promised to leave alone. A prompt whose first line is indented code lost
+    that indentation here, outside every guard, and the loss was invisible
+    because the trim is the last thing that happens.
+
+    It surfaced through idempotence rather than through a report: the block
+    stopped looking like a block, so the next pass no longer protected it and
+    the rules ate the code. The fuzzer found 54 of 1,500 corpus inputs that way.
+
+    Trimming the masked string cannot reach a protected span, because a
+    protected span is a placeholder at that point.
+  */
+  const optimized = unmask(current.trim(), vault);
   const tokensBefore = count(prompt);
   const tokensAfter = count(optimized);
 

package/src/phrases.ts

@@ -248,6 +248,42 @@ export const FILLER: readonly string[] = [
   "it's important to note that",
   'it is worth noting that',
   "it's worth noting that",
+  /*
+    The five below were missing while the same constructions sat in other
+    languages' sections of this very list, which is how they were found: not by
+    taste, but by reading across the sections and asking what English lacked.
+
+      it should be noted that      <- de: 'es sei darauf hingewiesen, dass'
+      it is worth mentioning that  <- es: 'vale la pena mencionar que'
+      it is important to mention   <- es: 'es importante mencionar que'
+
+    English carried four entries in this family and **two** constructions:
+    `it is important to note that` and `it is worth noting that`, each written
+    twice for the contraction. Spanish carried five constructions in five
+    entries. So the English section was not short of entries — it was spending
+    them on contractions of the same two phrasings while another language
+    covered five different ones.
+
+    That distinction matters and was got wrong once. The first version of this
+    comment said the English section was *the thinnest in the file*, which is
+    false: counted per language it is the longest, 12 entries against Spanish's
+    12 and Italian's 9. The gap was inside one family, and generalising from it
+    to the whole list took a claim nobody had checked. The check is one script.
+
+    Measured on fifteen padded sentences an editor would trim without touching
+    an instruction, the rules recovered 34 of 76 tokens; these were among the
+    misses.
+
+    Nothing is added here for the other five languages. A phrasing they lack is
+    for whoever reads the language to judge — `docs/language-maintainer.md`
+    exists for exactly that, and guessing at French filler from an English ear
+    is how a rule starts editing prompts it does not understand.
+  */
+  'it should be noted that',
+  'it is worth mentioning that',
+  "it's worth mentioning that",
+  'it is important to mention that',
+  "it's important to mention that",
   'needless to say',
   'in essence',
   'at the end of the day',

package/src/receipt.ts

@@ -150,6 +150,34 @@ export interface ReceiptLine {
   money: ReceiptMoney;
   /** The catalogue's published rates, as provenance. */
   pricing: ReceiptPricing;
+  /**
+   * The largest single call in this slice, cache reads and writes included.
+   *
+   * **The one number that says whether these calls would fit somewhere else.**
+   * A cheaper model with a smaller context window does not make a 400k-token
+   * call cheaper, it makes it impossible, and counting an impossible call's
+   * price difference as a saving is the flattering direction this repository
+   * refuses. The maximum rather than an average, for the same reason: one call
+   * over the ceiling is a failed call, and a mean hides it.
+   *
+   * Added in 2.1.0, and the gap it closes is worth naming. The two cache-write
+   * TTL fields above have always been here *so a consumer could reprice this
+   * traffic against another model's rates* -- and `repriceProfile` refuses to
+   * price traffic that would not fit, which no reader of a receipt could
+   * honour, because the receipt did not carry this. The format was built for
+   * repricing and stopped one field short of it.
+   */
+  maxCallInputTokens: number;
+  /**
+   * Calls in this slice whose cache-write TTL the log did not state, so the
+   * cheaper 5-minute rate was assumed.
+   *
+   * The document already reports the organisation-wide figure as an
+   * `assumed-write-ttl` gap. This is the same fact per slice, which is the
+   * resolution a repricing needs: the assumption travels into the comparison,
+   * and a reader is entitled to know which slices carry it.
+   */
+  assumedWriteTtlCalls: number;
 }
 
 /** Everything a receipt refuses to answer, typed rather than left implicit. */
@@ -220,26 +248,50 @@ export interface ReceiptDocument {
 }
 
 /**
- * The fields that leave this machine, listed once, in one place.
+ * The fields that leave this machine, keyed by the interface they describe.
+ *
+ * `Record<keyof ReceiptLine, true>` is what holds the two together: a field
+ * added to `ReceiptLine` and not added here is a **compile error**, and so is
+ * an entry here that `ReceiptLine` does not have. A whitelist maintained in two
+ * places is a whitelist with a hole in it.
+ *
+ * **This used to say the redaction guard held that, and it did not.** The guard
+ * reads the emitted lines and checks every key it finds against this list,
+ * which catches an emitter that emits an unlisted field — a real property, kept
+ * below. It cannot catch a field added to the *type*: a plant added
+ * `operator?: string` to `ReceiptLine`, emitted it on no line the fixture
+ * built, and all twelve checks passed. A field populated in one branch is
+ * exactly the shape a leak takes, and the published whitelist customers read to
+ * see what leaves their machine would have been wrong while its own guard said
+ * otherwise.
+ */
+const RECEIPT_LINE_FIELD_MAP = {
+  label: true,
+  model: true,
+  calls: true,
+  inputTokens: true,
+  cacheReadTokens: true,
+  cacheWriteTokens: true,
+  cacheWrite5mTokens: true,
+  cacheWrite1hTokens: true,
+  outputTokens: true,
+  usd: true,
+  money: true,
+  pricing: true,
+  maxCallInputTokens: true,
+  assumedWriteTtlCalls: true,
+} satisfies Record<keyof ReceiptLine, true>;
+
+/**
+ * The same list, published.
  *
- * 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.
+ * Derived from the map rather than written again, because writing it twice is
+ * the fault this exists to prevent. Key order is insertion order, so the array
+ * a consumer reads is unchanged.
  */
-export const RECEIPT_LINE_FIELDS = Object.freeze([
-  'label',
-  'model',
-  'calls',
-  'inputTokens',
-  'cacheReadTokens',
-  'cacheWriteTokens',
-  'cacheWrite5mTokens',
-  'cacheWrite1hTokens',
-  'outputTokens',
-  'usd',
-  'money',
-  'pricing',
-] as const);
+export const RECEIPT_LINE_FIELDS: readonly string[] = Object.freeze(
+  Object.keys(RECEIPT_LINE_FIELD_MAP),
+);
 
 const lineFrom = (
   label: string,
@@ -282,6 +334,11 @@ const lineFrom = (
       outputPerMTok: priced.outputPerMTok,
       reviewedOn: PROVIDER_REVIEWED[priced.provider ?? ''] ?? null,
     },
+    /* Copied, never derived. Neither can be recovered from the aggregates
+       above: a maximum is not a mean, and how many calls were silent about
+       their TTL is not visible in a token total. */
+    maxCallInputTokens: breakdown.maxCallInputTokens,
+    assumedWriteTtlCalls: breakdown.assumedWriteTtlCalls,
   };
 };
 

package/src/reprice.ts

@@ -1,7 +1,9 @@
 import { effectivePricing, multipliersFor } from './pricing.js';
 import type { PricingCatalogue } from './pricing.js';
 import type { ModelPricing } from './types.js';
+import type { ReceiptDocument } from './receipt.js';
 import type { UsageBreakdown, UsageProfileReport } from './usage.js';
+import { UNLABELLED } from './usage.js';
 
 /**
  * The same tokens at another model's rates.
@@ -195,11 +197,50 @@ export function priceTokensOn(
  * against a price nobody has is worse than no comparison, and the caller is
  * better placed to say so in its own words than this is to invent a zero.
  */
-export function repriceProfile(
-  report: UsageProfileReport,
+/**
+ * The least a slice has to carry to be repriced.
+ *
+ * Narrower than `UsageBreakdown` on purpose, and that narrowing is what lets a
+ * **receipt** be repriced at all. A receipt is the aggregate that leaves a
+ * machine; it does not carry a breakdown's truncation counts or its cache
+ * economics, and it never will, because those are answers to questions a
+ * receipt does not exist to answer. What it does carry — since 2.1.0 — is
+ * exactly this.
+ *
+ * Two entry points feed it and one implementation consumes it. Two copies of
+ * this loop, one reading profiles and one reading receipts, is the defect this
+ * codebase has found more times than any other, and it would be worse here
+ * than usual: the copies would drift on which traffic is refused, and a
+ * refusal that quietly stops happening reads as a saving.
+ */
+export interface RepriceableSlice {
+  /** `UNLABELLED` for the unlabelled bucket, never `null`. */
+  label: string;
+  model: string;
+  calls: number;
+  inputTokens: number;
+  cacheReadTokens: number;
+  cacheWrite5mTokens: number;
+  cacheWrite1hTokens: number;
+  outputTokens: number;
+  /** What it actually cost, as apportioned rather than as recomputed. */
+  totalUsd: number;
+  maxCallInputTokens: number;
+  assumedWriteTtlCalls: number;
+}
+
+/** The slices, plus what could not be priced at all. */
+export interface RepriceableInput {
+  slices: readonly RepriceableSlice[];
+  unpricedModels: readonly string[];
+  unpricedCalls: number;
+}
+
+function repriceSlices(
+  input: RepriceableInput,
   targetId: string,
   catalogue: PricingCatalogue,
-  on: Date = new Date(),
+  on: Date,
 ): RepriceReport | null {
   const target = catalogue.byId.get(targetId);
   if (!target) return null;
@@ -209,17 +250,16 @@ export function repriceProfile(
   const alreadyOnTarget = { calls: 0, usd: 0 };
   let assumedWriteTtlCalls = 0;
 
-  for (const slice of report.byLabelAndModel) {
-    const { breakdown } = slice;
-    if (slice.model === target.id) {
+  for (const breakdown of input.slices) {
+    if (breakdown.model === target.id) {
       alreadyOnTarget.calls += breakdown.calls;
       alreadyOnTarget.usd += breakdown.totalUsd;
       continue;
     }
     if (breakdown.maxCallInputTokens > target.contextWindow) {
       overContext.push({
-        label: slice.label,
-        model: slice.model,
+        label: breakdown.label,
+        model: breakdown.model,
         calls: breakdown.calls,
         currentUsd: breakdown.totalUsd,
         maxCallInputTokens: breakdown.maxCallInputTokens,
@@ -261,8 +301,8 @@ export function repriceProfile(
           }
         : null;
     slices.push({
-      label: slice.label,
-      model: slice.model,
+      label: breakdown.label,
+      model: breakdown.model,
       calls: breakdown.calls,
       currentUsd: breakdown.totalUsd,
       targetUsd,
@@ -287,15 +327,14 @@ export function repriceProfile(
   let batchOnTarget: { targetUsd: number } | null = null;
   if (batchRate !== null && batchRate < 1 && slices.length > 0) {
     const { inputPerMTok, outputPerMTok } = effectivePricing(target, on);
-    const movable = report.byLabelAndModel.filter(
-      (slice) =>
-        slice.model !== target.id && slice.breakdown.maxCallInputTokens <= target.contextWindow,
+    const movable = input.slices.filter(
+      (slice) => slice.model !== target.id && slice.maxCallInputTokens <= target.contextWindow,
     );
     const inOutUsd = movable.reduce(
       (sum, slice) =>
         sum +
-        (slice.breakdown.inputTokens / 1_000_000) * inputPerMTok +
-        (slice.breakdown.outputTokens / 1_000_000) * outputPerMTok,
+        (slice.inputTokens / 1_000_000) * inputPerMTok +
+        (slice.outputTokens / 1_000_000) * outputPerMTok,
       0,
     );
     batchOnTarget = { targetUsd: targetUsd - inOutUsd * (1 - batchRate) };
@@ -310,9 +349,117 @@ export function repriceProfile(
     overContext,
     alreadyOnTarget,
     assumedWriteTtlCalls,
-    unpricedModels: report.unpricedModels,
-    unpricedCalls: report.unpriced.calls,
+    /* Copied rather than passed through. The input's array belongs to the
+       caller -- a profile's own field, or a receipt's gap -- and handing it out
+       inside a report is how a reader ends up able to edit the document they
+       were given. */
+    unpricedModels: [...input.unpricedModels],
+    unpricedCalls: input.unpricedCalls,
     batchOnTarget,
     sameTokensAssumed: true,
   };
 }
+
+
+/**
+ * Reprices a profile's label-and-model slices onto one target model.
+ *
+ * Returns `null` when the catalogue does not know the target: a comparison
+ * against a price nobody has is worse than no comparison, and the caller is
+ * better placed to say so in its own words than this is to invent a zero.
+ */
+export function repriceProfile(
+  report: UsageProfileReport,
+  targetId: string,
+  catalogue: PricingCatalogue,
+  on: Date = new Date(),
+): RepriceReport | null {
+  return repriceSlices(
+    {
+      slices: report.byLabelAndModel.map((slice) => ({
+        label: slice.label,
+        model: slice.model,
+        calls: slice.breakdown.calls,
+        inputTokens: slice.breakdown.inputTokens,
+        cacheReadTokens: slice.breakdown.cacheReadTokens,
+        cacheWrite5mTokens: slice.breakdown.cacheWrite5mTokens,
+        cacheWrite1hTokens: slice.breakdown.cacheWrite1hTokens,
+        outputTokens: slice.breakdown.outputTokens,
+        totalUsd: slice.breakdown.totalUsd,
+        maxCallInputTokens: slice.breakdown.maxCallInputTokens,
+        assumedWriteTtlCalls: slice.breakdown.assumedWriteTtlCalls,
+      })),
+      unpricedModels: report.unpricedModels,
+      unpricedCalls: report.unpriced.calls,
+    },
+    targetId,
+    catalogue,
+    on,
+  );
+}
+
+/**
+ * The same question, asked of a **receipt** rather than of the log behind it.
+ *
+ * ## Why this exists
+ *
+ * A receipt is what leaves a machine, and by the time anybody wants to ask
+ * *what would these calls have cost on the small model* the log is usually
+ * gone — deleted by a retention policy, on a runner that no longer exists, or
+ * simply on somebody else's laptop. A comparison that can only be made where
+ * the log still is can only be made by the person who least needs it.
+ *
+ * It also settles a question the receipt format had left open. The two
+ * cache-write TTL fields say in their own comment that they exist *so a
+ * consumer can reprice this traffic*, and until 2.1.0 no consumer could: the
+ * refusal that protects the whole comparison — never price traffic the target
+ * could not have accepted — needs the largest call, and the receipt did not
+ * carry it. This is the entry point that field was added for.
+ *
+ * ## What it refuses, which is the same four things
+ *
+ * Nothing here is a second implementation. It maps a receipt's lines onto the
+ * same slices `repriceProfile` maps a profile onto, and the one loop that
+ * refuses over-context traffic, excludes calls already on the target, keeps
+ * the write TTLs apart and states `sameTokensAssumed` is the loop both use.
+ *
+ * The unlabelled bucket travels as `UNLABELLED` rather than `null`, which is
+ * the spelling every other consumer of these types already reads.
+ */
+export function repriceReceipt(
+  document: ReceiptDocument,
+  targetId: string,
+  catalogue: PricingCatalogue,
+  on: Date = new Date(),
+): RepriceReport | null {
+  /*
+   * What the catalogue could not price is in the document's gaps rather than
+   * in a line, which is the receipt's own arrangement: an unpriced call has no
+   * rate, so it has no line to be in. Read from there rather than left at
+   * zero, so a comparison covering half a bill cannot look complete.
+   */
+  const unpriced = document.gaps.find((gap) => gap.kind === 'unpriced');
+
+  return repriceSlices(
+    {
+      slices: document.lines.map((line) => ({
+        label: line.label ?? UNLABELLED,
+        model: line.model,
+        calls: line.calls,
+        inputTokens: line.inputTokens,
+        cacheReadTokens: line.cacheReadTokens,
+        cacheWrite5mTokens: line.cacheWrite5mTokens,
+        cacheWrite1hTokens: line.cacheWrite1hTokens,
+        outputTokens: line.outputTokens,
+        totalUsd: line.usd,
+        maxCallInputTokens: line.maxCallInputTokens,
+        assumedWriteTtlCalls: line.assumedWriteTtlCalls,
+      })),
+      unpricedModels: unpriced === undefined ? [] : unpriced.models,
+      unpricedCalls: unpriced === undefined ? 0 : unpriced.calls,
+    },
+    targetId,
+    catalogue,
+    on,
+  );
+}