@trazum/core 1.35.0 → 1.37.0

package/dist/measured-profile.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The usage profile `optimize` multiplies by, taken from a log instead of
+ * from somebody's typing.
+ *
+ * `optimize` prices a prompt change as `token delta × callsPerMonth`, with
+ * `avgOutputTokens` and `cacheHitRate` shaping the rest. Those three numbers
+ * are typed into a config file by a human who is guessing, and the two values
+ * most often typed are `1000` and whatever the README's example used. A usage
+ * log sitting in the same repository knows all three exactly.
+ *
+ * **What this module does not do is turn an estimate into a fact.** The token
+ * delta stays an estimate with its ±10% band; what stops being a guess is
+ * everything it is multiplied by. That distinction has to survive into the
+ * rendering, which is why `MeasuredUsage` carries the provenance of each
+ * figure rather than only the figures.
+ *
+ * The hardest decision here is the call count. A month's saving from a log
+ * covering three days is a forecast wearing arithmetic's clothes, and this
+ * repository refuses those. So the scaling has a floor, it is stated whenever
+ * it happens, and under the floor the tool reports the period it measured and
+ * declines the multiplication rather than performing it quietly.
+ */
+import type { UsageProfileReport } from './usage.js';
+import type { UsageProfile } from './types.js';
+/**
+ * The shortest span that may be scaled to a month, in days.
+ *
+ * A full week, because the week is the cycle traffic actually has: weekdays
+ * against weekends is the one periodicity nearly every workload shows, and a
+ * span shorter than one cycle scaled up multiplies whichever part of the
+ * cycle it happened to catch. Three weekdays scaled to a month is not a
+ * monthly figure, it is a Tuesday with a multiplier.
+ *
+ * Above the floor this is still a *rate*, not a prediction: "at the rate this
+ * log measured" is arithmetic about the past, and every rendering says so.
+ */
+export declare const MIN_SCALE_DAYS = 7;
+/** Days in the month this scales to. Stated rather than hidden in a constant. */
+export declare const SCALE_TO_DAYS = 30;
+export interface MeasuredUsage {
+    /** Ready to hand to `optimize`. Every field below is measured, not typed. */
+    profile: UsageProfile;
+    /** Calls the log actually recorded for this slice. Never scaled. */
+    calls: number;
+    /** What those calls actually cost. The measured half of any comparison. */
+    spentUsd: number;
+    /**
+     * The period the calls fall in, in days, or null when no call carried a
+     * clock. Null is why `scaled` can be null with calls above the floor.
+     */
+    spanDays: number | null;
+    /**
+     * How `callsPerMonth` was reached, or **null when it was not scaled at
+     * all** — in which case `profile.callsPerMonth` is the raw measured count
+     * over whatever period the log covers, and the rendering must say so
+     * rather than printing it under a "per month" heading.
+     */
+    scaled: {
+        fromDays: number;
+        factor: number;
+    } | null;
+    /**
+     * The share of input tokens served from cache, 0–1.
+     *
+     * `UsageProfile.cacheHitRate` is documented as the fraction of *calls* that
+     * reuse the prefix; what a log can measure is the fraction of input
+     * *tokens* that were cache reads. Those are the same number only when every
+     * call is the same size. It is handed over as the better of two
+     * approximations — a measured token share beats a typed call share — and
+     * named honestly here so no rendering can call it something it is not.
+     */
+    cacheReadShare: number;
+    /**
+     * The model carrying the most spend in this slice, and how many models the
+     * slice used at all. Above one, the single model handed to `optimize` is a
+     * simplification and the rendering says which share it covers.
+     */
+    models: {
+        chosen: string;
+        count: number;
+        chosenShareOfSpend: number;
+    };
+    /** True when no call in the slice recorded any output tokens. */
+    outputUnmeasured: boolean;
+}
+/**
+ * Derives the usage profile for one label from a measured report.
+ *
+ * Returns `null` when the label carries no priced calls — a slice with no
+ * measured traffic has nothing to hand over, and inventing a zero-call
+ * profile would produce a $0 saving that reads as "this change is worthless"
+ * rather than "nothing here was measured".
+ */
+export declare function measuredUsage(report: UsageProfileReport, label: string, options?: {
+    batchEligible?: boolean;
+}): MeasuredUsage | null;
+/**
+ * Every label the report priced, with the prompt file the config maps to it —
+ * and, deliberately, both kinds of mismatch.
+ *
+ * The two failures this surfaces are the ones a person cannot see from either
+ * side alone: a prompt file mapped to a label that no longer appears in the
+ * log (renamed, retired, or a typo that has been silently doing nothing), and
+ * a label carrying real money with no prompt file mapped at all (the workload
+ * nobody can optimise because nobody said where it lives).
+ */
+export interface LabelCoverage {
+    /** Labels with both traffic and a mapped prompt file. */
+    joined: {
+        label: string;
+        promptPath: string;
+        spentUsd: number;
+    }[];
+    /** Mapped prompt files whose label has no priced traffic in this log. */
+    mappedWithoutTraffic: {
+        label: string;
+        promptPath: string;
+    }[];
+    /** Labels with priced traffic and no prompt file mapped, dearest first. */
+    trafficWithoutPrompt: {
+        label: string;
+        spentUsd: number;
+    }[];
+}
+export declare function labelCoverage(report: UsageProfileReport, labels: Record<string, string>): LabelCoverage;
+//# sourceMappingURL=measured-profile.d.ts.map

package/dist/measured-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measured-profile.d.ts","sourceRoot":"","sources":["../src/measured-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,iFAAiF;AACjF,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,OAAO,EAAE,YAAY,CAAC;IACtB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;;;OAKG;IACH,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACpD;;;;;;;;;OASG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,iEAAiE;IACjE,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACxC,aAAa,GAAG,IAAI,CAuDtB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClE,yEAAyE;IACzE,oBAAoB,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9D,2EAA2E;IAC3E,oBAAoB,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7D;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,aAAa,CAsBf"}

package/dist/measured-profile.js

@@ -0,0 +1,114 @@
+/**
+ * The usage profile `optimize` multiplies by, taken from a log instead of
+ * from somebody's typing.
+ *
+ * `optimize` prices a prompt change as `token delta × callsPerMonth`, with
+ * `avgOutputTokens` and `cacheHitRate` shaping the rest. Those three numbers
+ * are typed into a config file by a human who is guessing, and the two values
+ * most often typed are `1000` and whatever the README's example used. A usage
+ * log sitting in the same repository knows all three exactly.
+ *
+ * **What this module does not do is turn an estimate into a fact.** The token
+ * delta stays an estimate with its ±10% band; what stops being a guess is
+ * everything it is multiplied by. That distinction has to survive into the
+ * rendering, which is why `MeasuredUsage` carries the provenance of each
+ * figure rather than only the figures.
+ *
+ * The hardest decision here is the call count. A month's saving from a log
+ * covering three days is a forecast wearing arithmetic's clothes, and this
+ * repository refuses those. So the scaling has a floor, it is stated whenever
+ * it happens, and under the floor the tool reports the period it measured and
+ * declines the multiplication rather than performing it quietly.
+ */
+import { UNLABELLED } from './usage.js';
+/**
+ * The shortest span that may be scaled to a month, in days.
+ *
+ * A full week, because the week is the cycle traffic actually has: weekdays
+ * against weekends is the one periodicity nearly every workload shows, and a
+ * span shorter than one cycle scaled up multiplies whichever part of the
+ * cycle it happened to catch. Three weekdays scaled to a month is not a
+ * monthly figure, it is a Tuesday with a multiplier.
+ *
+ * Above the floor this is still a *rate*, not a prediction: "at the rate this
+ * log measured" is arithmetic about the past, and every rendering says so.
+ */
+export const MIN_SCALE_DAYS = 7;
+/** Days in the month this scales to. Stated rather than hidden in a constant. */
+export const SCALE_TO_DAYS = 30;
+/**
+ * Derives the usage profile for one label from a measured report.
+ *
+ * Returns `null` when the label carries no priced calls — a slice with no
+ * measured traffic has nothing to hand over, and inventing a zero-call
+ * profile would produce a $0 saving that reads as "this change is worthless"
+ * rather than "nothing here was measured".
+ */
+export function measuredUsage(report, label, options = {}) {
+    const slices = report.byLabelAndModel.filter((row) => row.label === label);
+    if (slices.length === 0)
+        return null;
+    const calls = slices.reduce((sum, row) => sum + row.breakdown.calls, 0);
+    if (calls === 0)
+        return null;
+    const spentUsd = slices.reduce((sum, row) => sum + row.breakdown.totalUsd, 0);
+    const outputTokens = slices.reduce((sum, row) => sum + row.breakdown.outputTokens, 0);
+    const inputTokens = slices.reduce((sum, row) => sum + row.breakdown.inputTokens, 0);
+    const cacheReadTokens = slices.reduce((sum, row) => sum + row.breakdown.cacheReadTokens, 0);
+    // The model carrying the most spend. Ties break on the larger call count, so
+    // the answer is stable rather than dependent on map ordering.
+    const ranked = [...slices].sort((a, b) => b.breakdown.totalUsd - a.breakdown.totalUsd || b.breakdown.calls - a.breakdown.calls);
+    const chosen = ranked[0];
+    const chosenShareOfSpend = spentUsd > 0 ? chosen.breakdown.totalUsd / spentUsd : 0;
+    /**
+     * The span of *this slice*, not of the whole log. A label active for three
+     * days of a thirty-day log has a three-day rate, and using the log's span
+     * would divide its calls across weeks it never ran in.
+     */
+    const spanDays = report.span === null ? null : (report.span.toMs - report.span.fromMs) / 86_400_000;
+    const scaled = spanDays !== null && spanDays >= MIN_SCALE_DAYS
+        ? { fromDays: spanDays, factor: SCALE_TO_DAYS / spanDays }
+        : null;
+    const readShare = inputTokens + cacheReadTokens > 0 ? cacheReadTokens / (inputTokens + cacheReadTokens) : 0;
+    return {
+        profile: {
+            model: chosen.model,
+            // Scaled when the span earns it, the raw measured count otherwise. The
+            // caller must read `scaled` before printing this under any heading that
+            // says "month".
+            callsPerMonth: scaled === null ? calls : Math.round(calls * scaled.factor),
+            avgOutputTokens: Math.round(outputTokens / calls),
+            cacheHitRate: readShare,
+            batchEligible: options.batchEligible ?? false,
+        },
+        calls,
+        spentUsd,
+        spanDays,
+        scaled,
+        cacheReadShare: readShare,
+        models: { chosen: chosen.model, count: slices.length, chosenShareOfSpend },
+        outputUnmeasured: outputTokens === 0,
+    };
+}
+export function labelCoverage(report, labels) {
+    const spendByLabel = new Map(report.byLabel.map((row) => [row.label, row.breakdown.totalUsd]));
+    const joined = [];
+    const mappedWithoutTraffic = [];
+    for (const [label, promptPath] of Object.entries(labels)) {
+        const spentUsd = spendByLabel.get(label);
+        if (spentUsd === undefined)
+            mappedWithoutTraffic.push({ label, promptPath });
+        else
+            joined.push({ label, promptPath, spentUsd });
+    }
+    const trafficWithoutPrompt = report.byLabel
+        // The unlabelled bucket is not a workload somebody forgot to map; it is
+        // calls that carry no label at all, which `fieldCoverage` already reports.
+        .filter((row) => row.label !== UNLABELLED && labels[row.label] === undefined)
+        .map((row) => ({ label: row.label, spentUsd: row.breakdown.totalUsd }))
+        .sort((a, b) => b.spentUsd - a.spentUsd);
+    joined.sort((a, b) => b.spentUsd - a.spentUsd);
+    mappedWithoutTraffic.sort((a, b) => a.label.localeCompare(b.label));
+    return { joined, mappedWithoutTraffic, trafficWithoutPrompt };
+}
+//# sourceMappingURL=measured-profile.js.map

package/dist/measured-profile.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/core",
-  "version": "1.35.0",
+  "version": "1.37.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/config-schema.ts

@@ -82,6 +82,14 @@ export interface SpendConfig {
   maxSessionUsd?: number;
   /** Per-label budgets, each gated against that label's own spend. */
   byLabel?: Record<string, number>;
+  /**
+   * Money budgets per source, in dollars — the fleet's version of `byLabel`.
+   * A source is a named service from the top-level `sources` block, and a
+   * budget written here fails `profile --by-source` when that service alone
+   * crosses it, with the failing service named rather than a total that
+   * hides which.
+   */
+  bySource?: Record<string, number>;
 }
 
 export interface TrazumConfig {
@@ -120,6 +128,14 @@ export interface TrazumConfig {
    * workload against its own limit in the same run. A flag still wins over
    * the config, as everywhere in this tool.
    */
+  /**
+   * The fleet: named services, each a list of glob patterns over usage-log
+   * paths. `profile --by-source` builds one report per source plus a rollup,
+   * assigning each file to the most specific matching pattern — the same
+   * precedence rule the budget patterns use. A file matching no source is
+   * named in the output rather than silently joining no report.
+   */
+  sources?: Record<string, string[]>;
   spend?: SpendConfig;
   /**
    * Findings as policy: a gate failure the team has looked at and decided to
@@ -169,6 +185,7 @@ export const CONFIG_KEYS = [
   'budgets',
   'labels',
   'spend',
+  'sources',
   'waive',
   'maxGrowth',
   'baseline',
@@ -178,7 +195,7 @@ export const CONFIG_KEYS = [
 
 export const CONFIG_BASELINE_KEYS = ['path', 'maxGrowthTokens', 'maxGrowthPct'] as const;
 
-export const CONFIG_SPEND_KEYS = ['maxUsd', 'maxDayUsd', 'maxSessionUsd', 'byLabel'] as const;
+export const CONFIG_SPEND_KEYS = ['maxUsd', 'maxDayUsd', 'maxSessionUsd', 'byLabel', 'bySource'] as const;
 
 export const CONFIG_WAIVE_KEYS = ['gate', 'reason', 'until'] as const;
 
@@ -385,6 +402,19 @@ function parseSpend(raw: unknown, source: string): SpendConfig {
   if (raw.maxSessionUsd !== undefined) {
     spend.maxSessionUsd = requireNonNegativeNumber(raw.maxSessionUsd, 'spend.maxSessionUsd', source);
   }
+  if (raw.bySource !== undefined) {
+    if (!isPlainObject(raw.bySource)) {
+      throw new ConfigError('"spend.bySource" must be an object', source);
+    }
+    const bySource: Record<string, number> = {};
+    for (const [name, value] of Object.entries(raw.bySource)) {
+      if (name.trim().length === 0) {
+        throw new ConfigError('"spend.bySource" has an empty source name', source);
+      }
+      bySource[name] = requireNonNegativeNumber(value, `spend.bySource["${name}"]`, source);
+    }
+    spend.bySource = bySource;
+  }
   if (raw.byLabel !== undefined) {
     if (!isPlainObject(raw.byLabel)) {
       throw new ConfigError('"spend.byLabel" must be an object', source);
@@ -401,6 +431,32 @@ function parseSpend(raw: unknown, source: string): SpendConfig {
   return spend;
 }
 
+/**
+ * Validates the `sources` block: named services, each a non-empty list of
+ * glob patterns. Patterns are not checked against a filesystem here — a
+ * config file is validated wherever it is read, browser included, and which
+ * files exist is the CLI's question at run time.
+ */
+function parseSources(raw: unknown, source: string): Record<string, string[]> {
+  if (!isPlainObject(raw)) throw new ConfigError('"sources" must be an object', source);
+  const sources: Record<string, string[]> = {};
+  for (const [name, value] of Object.entries(raw)) {
+    if (name.trim().length === 0) {
+      throw new ConfigError('"sources" has an empty source name', source);
+    }
+    if (!Array.isArray(value) || value.length === 0) {
+      throw new ConfigError(`"sources.${name}" must be a non-empty array of glob patterns`, source);
+    }
+    for (const pattern of value) {
+      if (typeof pattern !== 'string' || pattern.trim().length === 0) {
+        throw new ConfigError(`"sources.${name}" has an empty pattern`, source);
+      }
+    }
+    sources[name] = value as string[];
+  }
+  return sources;
+}
+
 /**
  * Validates the `waive` list.
  *
@@ -597,6 +653,7 @@ export function parseConfig(raw: string, source = CONFIG_FILENAME): TrazumConfig
   if (document.budgets !== undefined) config.budgets = parseBudgets(document.budgets, source);
   if (document.labels !== undefined) config.labels = parseLabels(document.labels, source);
   if (document.spend !== undefined) config.spend = parseSpend(document.spend, source);
+  if (document.sources !== undefined) config.sources = parseSources(document.sources, source);
   if (document.waive !== undefined) config.waive = parseWaive(document.waive, source);
   if (document.baseline !== undefined) {
     config.baseline = parseBaselineConfig(document.baseline, source);

package/src/fleet.ts

@@ -0,0 +1,212 @@
+/**
+ * Twelve services, one rollup, and the one that is actually bleeding.
+ *
+ * `profile` merges a directory of logs into one bill, which is right for one
+ * service and wrong for a fleet: the merged report hides which service the
+ * money is coming from, per-service budgets cannot exist at all, and the
+ * findings a *comparison between services* could make are invisible — the
+ * same workload on Opus in one team and Haiku in another is a decision
+ * somebody should get to see, and no single merged total shows it.
+ *
+ * This module does the fleet arithmetic on reports the caller already built.
+ * It reads no files and runs no globs against a filesystem — the caller hands
+ * it file names and per-source reports, so the module stays browser-safe and
+ * the CLI keeps its monopoly on I/O.
+ *
+ * **The rollup refuses to average what it cannot compare.** Two sources whose
+ * logs cover different periods can be *summed* — a total is a total — but a
+ * share of that total is not a comparison of rates, and the module says which
+ * sources cover which days rather than letting a 3-day log look cheap beside
+ * a 30-day one.
+ */
+
+import { mostSpecificMatch } from './glob.js';
+import { UNLABELLED } from './usage.js';
+import type { UsageProfileReport } from './usage.js';
+
+/**
+ * Which source each file belongs to.
+ *
+ * Assignment is by the most specific matching glob, so `services/api/**`
+ * beats `services/**` on the same file — the same tie-break the budget
+ * patterns use, because two rules for pattern precedence in one tool is one
+ * rule too many. Files matching no source are returned rather than dropped:
+ * a log that silently joined no report would be spend missing from every
+ * bill, which is the flattering omission this repository refuses everywhere.
+ */
+export function assignSources(
+  files: string[],
+  sources: Record<string, string[]>,
+): { bySource: Map<string, string[]>; unmatched: string[] } {
+  const bySource = new Map<string, string[]>();
+  const unmatched: string[] = [];
+
+  // Flatten to (pattern, source) pairs so specificity decides across sources.
+  const patterns: { pattern: string; source: string }[] = [];
+  for (const [source, globs] of Object.entries(sources)) {
+    for (const pattern of globs) patterns.push({ pattern, source });
+  }
+
+  for (const file of files) {
+    const best = mostSpecificMatch(
+      patterns.map((p) => p.pattern),
+      file,
+    );
+    if (best === null) {
+      unmatched.push(file);
+      continue;
+    }
+    const source = patterns.find((p) => p.pattern === best)!.source;
+    const list = bySource.get(source) ?? [];
+    list.push(file);
+    bySource.set(source, list);
+  }
+  return { bySource, unmatched };
+}
+
+export interface FleetSource {
+  name: string;
+  report: UsageProfileReport;
+}
+
+export interface FleetRollup {
+  /** Sum over every source. A total is a total, whatever the spans. */
+  totalUsd: number;
+  calls: number;
+  /** Every source, dearest first, with its share of the fleet's total. */
+  sources: { name: string; usd: number; calls: number; share: number; spanDays: number | null }[];
+  /**
+   * The one that is actually bleeding: the dearest source, with its share —
+   * or null when the fleet spent nothing, because "nothing is bleeding" and
+   * "the worst of nothing" are different statements.
+   */
+  worst: { name: string; usd: number; share: number } | null;
+  /**
+   * True when the sources' logs cover meaningfully different periods (their
+   * spans differ by more than one day, or some carry no clock at all). Shares
+   * of the total remain valid — they are shares of a sum — but reading them
+   * as *rate* comparisons is exactly the mistake this flag exists to stop,
+   * and every rendering states it when set.
+   */
+  mismatchedSpans: boolean;
+  /**
+   * The same workload label running on different models in different sources
+   * — one team on Opus, another on Haiku, same job. A merged bill renders
+   * this invisible: the label's slices coexist with no seam. Only splits
+   * where both sides carry real spend are reported, dearest gap first.
+   */
+  splitBrains: {
+    label: string;
+    sources: { name: string; model: string; usd: number }[];
+  }[];
+  /**
+   * Sources where caching lost money while the fleet's aggregate paid off.
+   * An aggregate verdict is the flattering rendering when three sources are
+   * quietly underwater; each is named with its own delta. Sources whose
+   * verdict matches the aggregate are not listed — this is the exception
+   * report, not the census.
+   */
+  cacheUnderwater: { name: string; deltaUsd: number }[];
+}
+
+/** Span length in days, or null when the report has no clock. */
+function spanDaysOf(report: UsageProfileReport): number | null {
+  return report.span === null ? null : (report.span.toMs - report.span.fromMs) / 86_400_000;
+}
+
+export function fleetRollup(
+  sources: FleetSource[],
+  options: {
+    /**
+     * Per-source cache verdict delta, positive meaning caching added money to
+     * the bill — the caller computes it with `cacheEconomics` because that
+     * module owns the counterfactual, and this one must not restate it.
+     */
+    cacheDeltas?: Map<string, number>;
+    /** The fleet-wide delta under the same convention. */
+    aggregateCacheDelta?: number;
+  } = {},
+): FleetRollup {
+  const rows = sources
+    .map((s) => ({
+      name: s.name,
+      usd: s.report.total.totalUsd,
+      calls: s.report.total.calls,
+      spanDays: spanDaysOf(s.report),
+    }))
+    .sort((a, b) => b.usd - a.usd);
+
+  const totalUsd = rows.reduce((sum, r) => sum + r.usd, 0);
+  const calls = rows.reduce((sum, r) => sum + r.calls, 0);
+  const withShare = rows.map((r) => ({
+    ...r,
+    share: totalUsd > 0 ? r.usd / totalUsd : 0,
+  }));
+
+  const spans = rows.map((r) => r.spanDays);
+  const known = spans.filter((d): d is number => d !== null);
+  const mismatchedSpans =
+    spans.some((d) => d === null && known.length > 0) ||
+    (known.length > 1 && Math.max(...known) - Math.min(...known) > 1);
+
+  /**
+   * Split brains: one label, different models, different sources. Judged on
+   * each source's *dearest* model for the label, so a stray experiment call
+   * does not report a team as migrated.
+   */
+  const labelModel = new Map<string, Map<string, { model: string; usd: number }>>();
+  for (const source of sources) {
+    for (const slice of source.report.byLabelAndModel) {
+      if (slice.label === UNLABELLED) continue;
+      const perSource = labelModel.get(slice.label) ?? new Map();
+      const current = perSource.get(source.name);
+      if (current === undefined || slice.breakdown.totalUsd > current.usd) {
+        perSource.set(source.name, { model: slice.model, usd: slice.breakdown.totalUsd });
+      }
+      labelModel.set(slice.label, perSource);
+    }
+  }
+  const splitBrains: FleetRollup['splitBrains'] = [];
+  for (const [label, perSource] of labelModel) {
+    if (perSource.size < 2) continue;
+    const models = new Set([...perSource.values()].map((v) => v.model));
+    if (models.size < 2) continue;
+    const list = [...perSource.entries()]
+      .map(([name, v]) => ({ name, model: v.model, usd: v.usd }))
+      .filter((v) => v.usd > 0)
+      .sort((a, b) => b.usd - a.usd);
+    if (new Set(list.map((v) => v.model)).size < 2) continue;
+    splitBrains.push({ label, sources: list });
+  }
+  splitBrains.sort(
+    (a, b) =>
+      b.sources.reduce((s, v) => s + v.usd, 0) - a.sources.reduce((s, v) => s + v.usd, 0),
+  );
+
+  /**
+   * Cache underwater: only meaningful when the aggregate paid off — when the
+   * aggregate itself lost money, the whole-fleet report already shouts and
+   * naming each source would repeat it in pieces.
+   */
+  const cacheUnderwater: FleetRollup['cacheUnderwater'] = [];
+  if (
+    options.cacheDeltas !== undefined &&
+    options.aggregateCacheDelta !== undefined &&
+    options.aggregateCacheDelta <= 0
+  ) {
+    for (const [name, deltaUsd] of options.cacheDeltas) {
+      if (deltaUsd > 0) cacheUnderwater.push({ name, deltaUsd });
+    }
+    cacheUnderwater.sort((a, b) => b.deltaUsd - a.deltaUsd);
+  }
+
+  return {
+    totalUsd,
+    calls,
+    sources: withShare,
+    worst: totalUsd > 0 ? { name: rows[0]!.name, usd: rows[0]!.usd, share: withShare[0]!.share } : null,
+    mismatchedSpans,
+    splitBrains,
+    cacheUnderwater,
+  };
+}

package/src/index.ts

@@ -42,6 +42,10 @@ export { driversBetween } from './against.js';
 export type { AgainstDriver } from './against.js';
 export { coverageDrift, COVERAGE_FIELDS, COVERAGE_DRIFT_MIN } from './coverage-drift.js';
 export { explainGateFailure, gateMargin, GATE_MARGIN_TIGHT } from './gate-explain.js';
+export { measuredUsage, labelCoverage, MIN_SCALE_DAYS, SCALE_TO_DAYS } from './measured-profile.js';
+export { assignSources, fleetRollup } from './fleet.js';
+export type { FleetSource, FleetRollup } from './fleet.js';
+export type { MeasuredUsage, LabelCoverage } from './measured-profile.js';
 export type { GateExplanation } from './gate-explain.js';
 export type { CoverageDrift, CoverageField } from './coverage-drift.js';
 // The same tokens at another model's rates — arithmetic, not advice, and it