@trazum/core 1.36.0 → 1.38.0

package/dist/plan.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Not a list of findings — a ranked, costed, non-additive plan of what to do.
+ *
+ * The report names findings; a person then decides what to do first by doing
+ * arithmetic in their head, and head-arithmetic on savings gets done by
+ * *adding* them — which the levers module has documented as wrong since it
+ * shipped ($12.60 plus $10.50 against a $21.00 slice). This module does the
+ * composition once, correctly, and attaches to every action the things the
+ * log cannot confirm, because a plan that hides its assumptions is advice
+ * pretending to be arithmetic.
+ *
+ * **Everything here is derived from figures the report already computed.**
+ * Route and batch come from `billLevers` (combined, never summed). The
+ * truncation action's stake is the retry bill `truncationRetries` measured.
+ * The cache action's stake is `cacheEconomics`' own delta. Nothing is
+ * invented, and each action carries how to check the part that is not
+ * arithmetic.
+ *
+ * **The total is stated honestly.** Actions on *different* slices add
+ * cleanly; the one composition that does not add — route and batch on the
+ * same slice — arrives already combined inside a single action, so the
+ * plan's total is a sum of non-overlapping figures by construction. Measured
+ * stakes (money already spent on retries, money already lost to caching) are
+ * totalled separately from projected savings: "what you would save" and
+ * "what you already paid" are different columns, and merging them makes a
+ * number that is neither.
+ */
+import type { UsageProfileReport } from './usage.js';
+import type { BillLevers } from './levers.js';
+export type PlanActionKind = 'route' | 'batch' | 'route+batch' | 'fix-truncation' | 'fix-caching';
+/**
+ * What the log cannot confirm, as data rather than prose.
+ *
+ * Rendering lives with whoever renders — the CLI localizes these, and 1.39's
+ * verification can match them structurally. An English sentence baked in here
+ * would be a browser-safe module deciding the reader's language.
+ */
+export type PlanAssumption = 
+/** The cheaper model can actually do this work — quality, not arithmetic. */
+{
+    kind: 'model-capability';
+    model: string;
+}
+/** These calls tolerate a batch window's latency. */
+ | {
+    kind: 'batch-window';
+}
+/** The truncation-retry pairing is real — the log sees shapes, not content. */
+ | {
+    kind: 'retry-pattern-real';
+}
+/** A max_tokens the answers fit inside removes the retry pair. */
+ | {
+    kind: 'max-tokens-fits';
+}
+/** The traffic pattern holds — a cache underwater on this log may pay on other traffic. */
+ | {
+    kind: 'traffic-pattern-holds';
+};
+export interface PlanAction {
+    kind: PlanActionKind;
+    /** The workload this acts on. `UNLABELLED` renders as the unlabelled bucket. */
+    label: string;
+    model: string;
+    /**
+     * Projected saving per the log's own period, for route/batch — or null for
+     * the measured-stake actions, whose money is in `stakeUsd` instead. Never
+     * both: a projection and a measurement in one field is a number that is
+     * neither.
+     */
+    savingUsd: number | null;
+    /**
+     * Money already measured against this problem — the retry bill, the cache
+     * loss. Null for the projected actions.
+     */
+    stakeUsd: number | null;
+    /** What the log cannot confirm. Every entry is a human's question to answer. */
+    assumes: PlanAssumption[];
+    /** How to check the assumption, when a Trazum command can. */
+    check: string | null;
+    /** What this action does, in one machine-stable keyword per detail. */
+    detail: {
+        /** Route target, when the action moves the calls. */
+        routeTo?: {
+            id: string;
+            displayName: string;
+        };
+        /** The measured pieces behind a stake. */
+        measured?: Record<string, number>;
+    };
+}
+export interface PlanDocument {
+    /** Same contract discipline as the profile JSON. */
+    schemaVersion: 1;
+    /** The period the plan's figures cover, or null when the log had no clock. */
+    span: {
+        fromMs: number;
+        toMs: number;
+    } | null;
+    /** The price table behind every dollar here. */
+    pricingLastReviewed: string;
+    /** Ranked: largest money first, projected or staked alike. */
+    actions: PlanAction[];
+    /**
+     * Projected savings summed — additive by construction, because same-slice
+     * compositions arrive pre-combined in one action.
+     */
+    projectedSavingUsd: number;
+    /** Measured stakes summed: money already paid to problems this plan names. */
+    measuredStakeUsd: number;
+    /** The bill the plan was made against. */
+    totalUsd: number;
+}
+/**
+ * Builds the plan from a report and its levers.
+ *
+ * `pricingLastReviewed` is passed in rather than imported so the plan records
+ * the catalogue that actually priced it — an overlay's date when one was in
+ * effect, which 1.39's verification needs to tell "the prediction was wrong"
+ * from "the prices changed".
+ */
+export declare function buildPlan(report: UsageProfileReport, levers: BillLevers, pricingLastReviewed: string): PlanDocument;
+/** Renders `UNLABELLED` for humans without leaking the sentinel. */
+export declare function planLabelName(label: string, unlabelled: string): string;
+//# sourceMappingURL=plan.d.ts.map

package/dist/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,GAAG,aAAa,GAAG,gBAAgB,GAAG,aAAa,CAAC;AAElG;;;;;;GAMG;AACH,MAAM,MAAM,cAAc;AACxB,6EAA6E;AAC3E;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAC7C,qDAAqD;GACnD;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE;AAC1B,+EAA+E;GAC7E;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE;AAChC,kEAAkE;GAChE;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE;AAC7B,2FAA2F;GACzF;IAAE,IAAI,EAAE,uBAAuB,CAAA;CAAE,CAAC;AAEtC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,gFAAgF;IAChF,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,8DAA8D;IAC9D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uEAAuE;IACvE,MAAM,EAAE;QACN,qDAAqD;QACrD,OAAO,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC;QAC9C,0CAA0C;QAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACnC,CAAC;CACH;AAED,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,aAAa,EAAE,CAAC,CAAC;IACjB,8EAA8E;IAC9E,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,gDAAgD;IAChD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,8DAA8D;IAC9D,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,UAAU,EAClB,mBAAmB,EAAE,MAAM,GAC1B,YAAY,CAsFd;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvE"}

package/dist/plan.js

@@ -0,0 +1,125 @@
+/**
+ * Not a list of findings — a ranked, costed, non-additive plan of what to do.
+ *
+ * The report names findings; a person then decides what to do first by doing
+ * arithmetic in their head, and head-arithmetic on savings gets done by
+ * *adding* them — which the levers module has documented as wrong since it
+ * shipped ($12.60 plus $10.50 against a $21.00 slice). This module does the
+ * composition once, correctly, and attaches to every action the things the
+ * log cannot confirm, because a plan that hides its assumptions is advice
+ * pretending to be arithmetic.
+ *
+ * **Everything here is derived from figures the report already computed.**
+ * Route and batch come from `billLevers` (combined, never summed). The
+ * truncation action's stake is the retry bill `truncationRetries` measured.
+ * The cache action's stake is `cacheEconomics`' own delta. Nothing is
+ * invented, and each action carries how to check the part that is not
+ * arithmetic.
+ *
+ * **The total is stated honestly.** Actions on *different* slices add
+ * cleanly; the one composition that does not add — route and batch on the
+ * same slice — arrives already combined inside a single action, so the
+ * plan's total is a sum of non-overlapping figures by construction. Measured
+ * stakes (money already spent on retries, money already lost to caching) are
+ * totalled separately from projected savings: "what you would save" and
+ * "what you already paid" are different columns, and merging them makes a
+ * number that is neither.
+ */
+import { UNLABELLED, cacheEconomics } from './usage.js';
+/**
+ * Builds the plan from a report and its levers.
+ *
+ * `pricingLastReviewed` is passed in rather than imported so the plan records
+ * the catalogue that actually priced it — an overlay's date when one was in
+ * effect, which 1.39's verification needs to tell "the prediction was wrong"
+ * from "the prices changed".
+ */
+export function buildPlan(report, levers, pricingLastReviewed) {
+    const actions = [];
+    for (const slice of levers.slices) {
+        const assumes = [];
+        let kind;
+        if (slice.route !== null && slice.batch !== null) {
+            kind = 'route+batch';
+            assumes.push({ kind: 'model-capability', model: slice.route.candidate.displayName });
+            assumes.push({ kind: 'batch-window' });
+        }
+        else if (slice.route !== null) {
+            kind = 'route';
+            assumes.push({ kind: 'model-capability', model: slice.route.candidate.displayName });
+        }
+        else if (slice.batch !== null) {
+            kind = 'batch';
+            assumes.push({ kind: 'batch-window' });
+        }
+        else {
+            continue;
+        }
+        actions.push({
+            kind,
+            label: slice.label,
+            model: slice.model,
+            savingUsd: slice.combinedUsd,
+            stakeUsd: null,
+            assumes,
+            check: slice.route !== null ? 'trazum route <log> --prompt-file <prompt> --cases <cases>' : null,
+            detail: slice.route !== null ? { routeTo: slice.route.candidate } : {},
+        });
+    }
+    for (const row of report.truncationRetries) {
+        actions.push({
+            kind: 'fix-truncation',
+            label: row.label,
+            model: row.model,
+            savingUsd: null,
+            stakeUsd: row.wastedUsd + row.retryUsd,
+            assumes: [{ kind: 'retry-pattern-real' }, { kind: 'max-tokens-fits' }],
+            check: null,
+            detail: {
+                measured: {
+                    wastedUsd: row.wastedUsd,
+                    retryUsd: row.retryUsd,
+                    retried: row.retried,
+                    truncatedCalls: row.truncatedCalls,
+                },
+            },
+        });
+    }
+    for (const slice of report.byLabelAndModel) {
+        const economics = cacheEconomics(slice.breakdown);
+        // Only a settled loss becomes an action: an unsettled verdict is a
+        // missing field, and "add the field" is the report's advice, not a plan's.
+        if (economics.verdict !== 'lost-money' || economics.worstCaseVerdict !== economics.verdict)
+            continue;
+        actions.push({
+            kind: 'fix-caching',
+            label: slice.label,
+            model: slice.model,
+            savingUsd: null,
+            stakeUsd: economics.deltaUsd,
+            assumes: [{ kind: 'traffic-pattern-holds' }],
+            check: null,
+            detail: {
+                measured: {
+                    spentUsd: economics.spentUsd,
+                    withoutCachingUsd: economics.withoutCachingUsd,
+                },
+            },
+        });
+    }
+    actions.sort((a, b) => (b.savingUsd ?? b.stakeUsd ?? 0) - (a.savingUsd ?? a.stakeUsd ?? 0));
+    return {
+        schemaVersion: 1,
+        span: report.span === null ? null : { fromMs: report.span.fromMs, toMs: report.span.toMs },
+        pricingLastReviewed,
+        actions,
+        projectedSavingUsd: actions.reduce((sum, a) => sum + (a.savingUsd ?? 0), 0),
+        measuredStakeUsd: actions.reduce((sum, a) => sum + (a.stakeUsd ?? 0), 0),
+        totalUsd: report.total.totalUsd,
+    };
+}
+/** Renders `UNLABELLED` for humans without leaking the sentinel. */
+export function planLabelName(label, unlabelled) {
+    return label === UNLABELLED ? unlabelled : label;
+}
+//# sourceMappingURL=plan.js.map

package/dist/plan.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/core",
-  "version": "1.36.0",
+  "version": "1.38.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

@@ -43,6 +43,10 @@ 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 { buildPlan, planLabelName } from './plan.js';
+export type { PlanAction, PlanActionKind, PlanAssumption, PlanDocument } from './plan.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';