@trazum/core 1.38.0 → 1.40.0

package/dist/verify.js

@@ -0,0 +1,193 @@
+/**
+ * Did it work? — the plan held to the log that came after it.
+ *
+ * Every optimisation tool says what you *would* save; almost none says what
+ * you *did*. This module takes a saved plan and a newer report and answers
+ * per action, with **three outcomes and never two**: the change arrived, the
+ * change did not arrive, or *it cannot be told* — because the workload
+ * vanished, the fields the detection needs stopped being recorded, or the
+ * log simply cannot see the thing (tokens do not say which tier billed
+ * them). The third outcome is the honest one, and the one every other tool
+ * renders as the first.
+ *
+ * **Differences are attributed, not just stated.** A predicted saving that
+ * did not appear in the bill is decomposed against the plan's recorded
+ * baseline: the calls moved, the output per call moved, the input per call
+ * moved — measured ratios with names, never a single number that blames
+ * nobody. And a plan priced under one catalogue verified under another says
+ * so: the tool must not blame a team for a saving that arithmetic revoked.
+ *
+ * Browser-safe like everything here: two documents in, one verdict out.
+ */
+import { cacheEconomics } from './usage.js';
+/** Newer-log slices for one label, dearest first. */
+function slicesForLabel(report, label) {
+    return report.byLabelAndModel
+        .filter((s) => s.label === label && s.breakdown.calls > 0)
+        .sort((a, b) => b.breakdown.totalUsd - a.breakdown.totalUsd);
+}
+function attributionFrom(action, after) {
+    const before = action.detail.baseline;
+    if (before === undefined || after === null)
+        return null;
+    return {
+        calls: { before: before.calls, after: after.calls },
+        inputPerCallTokens: { before: before.inputPerCallTokens, after: after.inputPerCallTokens },
+        outputPerCallTokens: { before: before.outputPerCallTokens, after: after.outputPerCallTokens },
+    };
+}
+function perCall(breakdown) {
+    return {
+        calls: breakdown.calls,
+        inputPerCallTokens: (breakdown.inputTokens + breakdown.cacheReadTokens + breakdown.cacheWriteTokens) / breakdown.calls,
+        outputPerCallTokens: breakdown.outputTokens / breakdown.calls,
+    };
+}
+export function verifyPlan(plan, report, options) {
+    const actions = [];
+    for (const action of plan.actions) {
+        const slices = slicesForLabel(report, action.label);
+        const total = slices.reduce((sum, s) => sum + s.breakdown.totalUsd, 0);
+        const allCalls = slices.reduce((sum, s) => sum + s.breakdown.calls, 0);
+        /** The label carries no priced traffic any more: nothing can be told. */
+        if (slices.length === 0) {
+            actions.push({
+                action,
+                outcome: 'cannot-tell',
+                reason: 'workload-vanished',
+                observed: {},
+                attribution: null,
+                gateFailing: false,
+            });
+            continue;
+        }
+        if (action.kind === 'route' || action.kind === 'route+batch') {
+            const target = action.detail.routeTo;
+            const dearest = slices[0];
+            const onTarget = slices.find((s) => s.model === target.id);
+            const stillOnOld = slices.find((s) => s.model === action.model);
+            const moved = dearest.model === target.id;
+            const after = perCall(moved ? dearest.breakdown : (stillOnOld ?? dearest).breakdown);
+            actions.push({
+                action,
+                outcome: moved ? 'arrived' : 'not-arrived',
+                reason: null,
+                observed: {
+                    dearestModel: dearest.model,
+                    onTargetUsd: onTarget?.breakdown.totalUsd ?? 0,
+                    onOldModelUsd: stillOnOld?.breakdown.totalUsd ?? 0,
+                    labelUsd: total,
+                    labelCalls: allCalls,
+                    // The batch half of route+batch cannot be seen in token counts;
+                    // the rendering names it instead of counting it as arrived.
+                    ...(action.kind === 'route+batch' ? { batchObservable: 0 } : {}),
+                },
+                attribution: attributionFrom(action, after),
+                gateFailing: !moved,
+            });
+            continue;
+        }
+        if (action.kind === 'batch') {
+            // Tokens do not say which tier billed them. Not the team's silence,
+            // so it cannot fail the gate — but it is said, never assumed arrived.
+            actions.push({
+                action,
+                outcome: 'cannot-tell',
+                reason: 'tier-not-recorded',
+                observed: { labelUsd: total, labelCalls: allCalls },
+                attribution: null,
+                gateFailing: false,
+            });
+            continue;
+        }
+        const slice = slices.find((s) => s.model === action.model);
+        if (action.kind === 'fix-truncation') {
+            // The detection needs sessions and timestamps; a log that dropped them
+            // reads as "no retries" for the wrong reason, and that must not pass.
+            if (!report.hasSessions || report.span === null) {
+                actions.push({
+                    action,
+                    outcome: 'cannot-tell',
+                    reason: 'fields-stopped',
+                    observed: {},
+                    attribution: attributionFrom(action, slice ? perCall(slice.breakdown) : null),
+                    gateFailing: true,
+                });
+                continue;
+            }
+            const row = report.truncationRetries.find((r) => r.label === action.label && r.model === action.model);
+            const newStake = row === undefined ? 0 : row.wastedUsd + row.retryUsd;
+            actions.push({
+                action,
+                outcome: row === undefined ? 'arrived' : 'not-arrived',
+                reason: null,
+                observed: {
+                    retryBillUsd: newStake,
+                    retried: row?.retried ?? 0,
+                    truncatedCalls: row?.truncatedCalls ?? 0,
+                },
+                attribution: attributionFrom(action, slice ? perCall(slice.breakdown) : null),
+                gateFailing: row !== undefined,
+            });
+            continue;
+        }
+        // fix-caching.
+        if (slice === undefined) {
+            actions.push({
+                action,
+                outcome: 'cannot-tell',
+                reason: 'workload-vanished',
+                observed: {},
+                attribution: null,
+                gateFailing: false,
+            });
+            continue;
+        }
+        const economics = cacheEconomics(slice.breakdown);
+        if (economics.verdict === 'lost-money' && economics.worstCaseVerdict === economics.verdict) {
+            actions.push({
+                action,
+                outcome: 'not-arrived',
+                reason: null,
+                observed: { deltaUsd: economics.deltaUsd, spentUsd: economics.spentUsd },
+                attribution: attributionFrom(action, perCall(slice.breakdown)),
+                gateFailing: true,
+            });
+        }
+        else if (economics.worstCaseVerdict !== economics.verdict) {
+            // The verdict cannot settle on this log: the fields that would settle
+            // it are not there, and an unverifiable fix is not a verified one.
+            actions.push({
+                action,
+                outcome: 'cannot-tell',
+                reason: 'fields-stopped',
+                observed: {},
+                attribution: attributionFrom(action, perCall(slice.breakdown)),
+                gateFailing: true,
+            });
+        }
+        else {
+            actions.push({
+                action,
+                outcome: 'arrived',
+                reason: null,
+                observed: { deltaUsd: economics.deltaUsd, spentUsd: economics.spentUsd },
+                attribution: attributionFrom(action, perCall(slice.breakdown)),
+                gateFailing: false,
+            });
+        }
+    }
+    return {
+        schemaVersion: 1,
+        planCreatedAt: plan.createdAt ?? null,
+        planPricing: plan.pricingLastReviewed,
+        currentPricing: options.currentPricingLastReviewed,
+        pricesChanged: plan.pricingLastReviewed !== options.currentPricingLastReviewed,
+        actions,
+        arrived: actions.filter((a) => a.outcome === 'arrived').length,
+        notArrived: actions.filter((a) => a.outcome === 'not-arrived').length,
+        cannotTell: actions.filter((a) => a.outcome === 'cannot-tell').length,
+        gateFailures: actions.filter((a) => a.gateFailing).length,
+    };
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA8D5C,qDAAqD;AACrD,SAAS,cAAc,CAAC,MAA0B,EAAE,KAAa;IAC/D,OAAO,MAAM,CAAC,eAAe;SAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,IAAI,CAAC,CAAC,SAAS,CAAC,KAAK,GAAG,CAAC,CAAC;SACzD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,GAAG,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;AACjE,CAAC;AAED,SAAS,eAAe,CACtB,MAAkB,EAClB,KAAwF;IAExF,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;IACtC,IAAI,MAAM,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACxD,OAAO;QACL,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;QACnD,kBAAkB,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,kBAAkB,EAAE,KAAK,EAAE,KAAK,CAAC,kBAAkB,EAAE;QAC1F,mBAAmB,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,mBAAmB,EAAE,KAAK,EAAE,KAAK,CAAC,mBAAmB,EAAE;KAC9F,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,SAA0H;IACzI,OAAO;QACL,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,kBAAkB,EAChB,CAAC,SAAS,CAAC,WAAW,GAAG,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,gBAAgB,CAAC,GAAG,SAAS,CAAC,KAAK;QACpG,mBAAmB,EAAE,SAAS,CAAC,YAAY,GAAG,SAAS,CAAC,KAAK;KAC9D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,UAAU,CACxB,IAA2C,EAC3C,MAA0B,EAC1B,OAA+C;IAE/C,MAAM,OAAO,GAAqB,EAAE,CAAC;IAErC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QACpD,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;QACvE,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAEvE,yEAAyE;QACzE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC;gBACX,MAAM;gBACN,OAAO,EAAE,aAAa;gBACtB,MAAM,EAAE,mBAAmB;gBAC3B,QAAQ,EAAE,EAAE;gBACZ,WAAW,EAAE,IAAI;gBACjB,WAAW,EAAE,KAAK;aACnB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,MAAM,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YAC7D,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,OAAQ,CAAC;YACtC,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;YAC3B,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,EAAE,CAAC,CAAC;YAC3D,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC;YAChE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,KAAK,MAAM,CAAC,EAAE,CAAC;YAC1C,MAAM,KAAK,GAAG,OAAO,CACnB,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,UAAU,IAAI,OAAO,CAAC,CAAC,SAAS,CAC9D,CAAC;YACF,OAAO,CAAC,IAAI,CAAC;gBACX,MAAM;gBACN,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa;gBAC1C,MAAM,EAAE,IAAI;gBACZ,QAAQ,EAAE;oBACR,YAAY,EAAE,OAAO,CAAC,KAAK;oBAC3B,WAAW,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,IAAI,CAAC;oBAC9C,aAAa,EAAE,UAAU,EAAE,SAAS,CAAC,QAAQ,IAAI,CAAC;oBAClD,QAAQ,EAAE,KAAK;oBACf,UAAU,EAAE,QAAQ;oBACpB,gEAAgE;oBAChE,4DAA4D;oBAC5D,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,aAAa,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACjE;gBACD,WAAW,EAAE,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC;gBAC3C,WAAW,EAAE,CAAC,KAAK;aACpB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC5B,oEAAoE;YACpE,sEAAsE;YACtE,OAAO,CAAC,IAAI,CAAC;gBACX,MAAM;gBACN,OAAO,EAAE,aAAa;gBACtB,MAAM,EAAE,mBAAmB;gBAC3B,QAAQ,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE;gBACnD,WAAW,EAAE,IAAI;gBACjB,WAAW,EAAE,KAAK;aACnB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC;QAE3D,IAAI,MAAM,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;YACrC,uEAAuE;YACvE,sEAAsE;YACtE,IAAI,CAAC,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;gBAChD,OAAO,CAAC,IAAI,CAAC;oBACX,MAAM;oBACN,OAAO,EAAE,aAAa;oBACtB,MAAM,EAAE,gBAAgB;oBACxB,QAAQ,EAAE,EAAE;oBACZ,WAAW,EAAE,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;oBAC7E,WAAW,EAAE,IAAI;iBAClB,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,CAAC,iBAAiB,CAAC,IAAI,CACvC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,KAAK,CAC5D,CAAC;YACF,MAAM,QAAQ,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,GAAG,GAAG,CAAC,QAAQ,CAAC;YACtE,OAAO,CAAC,IAAI,CAAC;gBACX,MAAM;gBACN,OAAO,EAAE,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa;gBACtD,MAAM,EAAE,IAAI;gBACZ,QAAQ,EAAE;oBACR,YAAY,EAAE,QAAQ;oBACtB,OAAO,EAAE,GAAG,EAAE,OAAO,IAAI,CAAC;oBAC1B,cAAc,EAAE,GAAG,EAAE,cAAc,IAAI,CAAC;iBACzC;gBACD,WAAW,EAAE,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;gBAC7E,WAAW,EAAE,GAAG,KAAK,SAAS;aAC/B,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,eAAe;QACf,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC;gBACX,MAAM;gBACN,OAAO,EAAE,aAAa;gBACtB,MAAM,EAAE,mBAAmB;gBAC3B,QAAQ,EAAE,EAAE;gBACZ,WAAW,EAAE,IAAI;gBACjB,WAAW,EAAE,KAAK;aACnB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,MAAM,SAAS,GAAG,cAAc,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,SAAS,CAAC,OAAO,KAAK,YAAY,IAAI,SAAS,CAAC,gBAAgB,KAAK,SAAS,CAAC,OAAO,EAAE,CAAC;YAC3F,OAAO,CAAC,IAAI,CAAC;gBACX,MAAM;gBACN,OAAO,EAAE,aAAa;gBACtB,MAAM,EAAE,IAAI;gBACZ,QAAQ,EAAE,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE;gBACxE,WAAW,EAAE,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;gBAC9D,WAAW,EAAE,IAAI;aAClB,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,SAAS,CAAC,gBAAgB,KAAK,SAAS,CAAC,OAAO,EAAE,CAAC;YAC5D,sEAAsE;YACtE,mEAAmE;YACnE,OAAO,CAAC,IAAI,CAAC;gBACX,MAAM;gBACN,OAAO,EAAE,aAAa;gBACtB,MAAM,EAAE,gBAAgB;gBACxB,QAAQ,EAAE,EAAE;gBACZ,WAAW,EAAE,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;gBAC9D,WAAW,EAAE,IAAI;aAClB,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC;gBACX,MAAM;gBACN,OAAO,EAAE,SAAS;gBAClB,MAAM,EAAE,IAAI;gBACZ,QAAQ,EAAE,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE;gBACxE,WAAW,EAAE,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;gBAC9D,WAAW,EAAE,KAAK;aACnB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,aAAa,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI;QACrC,WAAW,EAAE,IAAI,CAAC,mBAAmB;QACrC,cAAc,EAAE,OAAO,CAAC,0BAA0B;QAClD,aAAa,EAAE,IAAI,CAAC,mBAAmB,KAAK,OAAO,CAAC,0BAA0B;QAC9E,OAAO;QACP,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,MAAM;QAC9D,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,aAAa,CAAC,CAAC,MAAM;QACrE,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,aAAa,CAAC,CAAC,MAAM;QACrE,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,MAAM;KAC1D,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/core",
-  "version": "1.38.0",
+  "version": "1.40.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/history.ts

@@ -0,0 +1,284 @@
+/**
+ * The long run: many reports over many periods, as one series.
+ *
+ * Every comparison in Trazum is between two logs, and a product's cost
+ * problem is rarely visible in two — it is visible in twenty. This module
+ * takes *stored reports* (the `--json` documents a team already keeps) and
+ * builds the series no pairwise comparison can see: the workload that grew a
+ * little every week, the model share that has been climbing since a date,
+ * the cache hit rate decaying slowly enough that no single week's report
+ * called it a finding.
+ *
+ * **Still no forecasts.** Twenty points make a trend visible; they do not
+ * make next month knowable. The series is stated, the shape is named as
+ * consecutive movement — never a line fitted through the points — and where
+ * it goes next remains the reader's to judge, the same refusal
+ * `modelMixDrift` has carried since 1.27.
+ *
+ * **Derived from stored reports, not re-parsed logs**, so a year of `--json`
+ * output is enough and the raw logs can be thrown away — which is what the
+ * privacy story requires anyway. Browser-safe: documents in, series out.
+ */
+
+import { UNLABELLED } from './usage.js';
+import type { PlanActionKind, PlanDocument } from './plan.js';
+
+/** The slice of a stored profile document this module actually reads. */
+export interface StoredReport {
+  /** Where it came from — a file name, shown so a finding can be traced. */
+  name: string;
+  span: { fromMs: number; toMs: number } | null;
+  totalUsd: number;
+  calls: number;
+  /** Label → dollars this period. */
+  byLabel: Map<string, number>;
+  /** Model → dollars this period. */
+  byModel: Map<string, number>;
+  /** Share of input tokens served from cache, or null when unknowable. */
+  cacheReadShare: number | null;
+}
+
+/**
+ * A run of consecutive movement, named — never extrapolated.
+ *
+ * `periods` counts the *rises* (or falls), so a run of 3 spans 4 reports.
+ * The floor is 3: two rises is what `--against` already shows, and one is
+ * noise wearing a trend's clothes.
+ */
+export interface HistoryRun {
+  kind: 'label-spend-climbing' | 'model-share-climbing' | 'cache-share-decaying';
+  subject: string;
+  /** Consecutive rises (falls, for decay). */
+  periods: number;
+  /** The report the run started in, by name — "climbing since <this one>". */
+  sinceName: string;
+  /** First and last values of the run, so the reader judges the size. */
+  from: number;
+  to: number;
+}
+
+/** The same action planned again and again: a decision nobody is executing. */
+export interface RepeatedPlanAction {
+  kind: PlanActionKind;
+  label: string;
+  model: string;
+  appearances: number;
+  firstPlanned: string | null;
+  lastPlanned: string | null;
+}
+
+export interface HistoryDocument {
+  schemaVersion: 1;
+  /** Ordered oldest first by span start. */
+  periods: { name: string; fromMs: number; toMs: number; totalUsd: number; calls: number }[];
+  /** Per label, dollars per period — null where the label had no traffic. */
+  labelSeries: { label: string; points: (number | null)[] }[];
+  /** Per model, share of that period's total — null where absent. */
+  modelShareSeries: { model: string; points: (number | null)[] }[];
+  /** Cache read share per period, null where unknowable. */
+  cacheShareSeries: (number | null)[];
+  /** The findings only a series can make. Shapes, never forecasts. */
+  runs: HistoryRun[];
+  /** Plans in the same directory, held against each other. */
+  repeatedPlanActions: RepeatedPlanAction[];
+  /**
+   * Reports that carry no span cannot be placed on a timeline; they are
+   * named here and in no series above, never silently absorbed.
+   */
+  undatedReports: string[];
+}
+
+export const MIN_RUN = 3;
+
+/** The longest run of strictly consecutive movement ending anywhere in the series. */
+function longestRun(
+  points: (number | null)[],
+  direction: 1 | -1,
+): { start: number; length: number } | null {
+  let best: { start: number; length: number } | null = null;
+  let start = -1;
+  let length = 0;
+  for (let i = 1; i < points.length; i++) {
+    const prev = points[i - 1] ?? null;
+    const here = points[i] ?? null;
+    if (prev !== null && here !== null && Math.sign(here - prev) === direction && here !== prev) {
+      if (length === 0) start = i - 1;
+      length += 1;
+      if (best === null || length > best.length) best = { start, length };
+    } else {
+      length = 0;
+    }
+  }
+  return best !== null && best.length >= MIN_RUN ? best : null;
+}
+
+export function buildHistory(
+  reports: StoredReport[],
+  plans: (PlanDocument & { createdAt?: string; name?: string })[] = [],
+): HistoryDocument {
+  const undatedReports = reports.filter((r) => r.span === null).map((r) => r.name);
+  const dated = reports
+    .filter((r) => r.span !== null)
+    .sort((a, b) => a.span!.fromMs - b.span!.fromMs);
+
+  const periods = dated.map((r) => ({
+    name: r.name,
+    fromMs: r.span!.fromMs,
+    toMs: r.span!.toMs,
+    totalUsd: r.totalUsd,
+    calls: r.calls,
+  }));
+
+  const labels = [...new Set(dated.flatMap((r) => [...r.byLabel.keys()]))].sort();
+  const labelSeries = labels.map((label) => ({
+    label,
+    points: dated.map((r) => r.byLabel.get(label) ?? null),
+  }));
+
+  const models = [...new Set(dated.flatMap((r) => [...r.byModel.keys()]))].sort();
+  const modelShareSeries = models.map((model) => ({
+    model,
+    points: dated.map((r) => {
+      const usd = r.byModel.get(model);
+      if (usd === undefined || r.totalUsd <= 0) return null;
+      return usd / r.totalUsd;
+    }),
+  }));
+
+  const cacheShareSeries = dated.map((r) => r.cacheReadShare);
+
+  const runs: HistoryRun[] = [];
+  for (const series of labelSeries) {
+    const run = longestRun(series.points, 1);
+    if (run === null) continue;
+    runs.push({
+      kind: 'label-spend-climbing',
+      subject: series.label,
+      periods: run.length,
+      sinceName: periods[run.start]!.name,
+      from: series.points[run.start]!,
+      to: series.points[run.start + run.length]!,
+    });
+  }
+  for (const series of modelShareSeries) {
+    const run = longestRun(series.points, 1);
+    if (run === null) continue;
+    runs.push({
+      kind: 'model-share-climbing',
+      subject: series.model,
+      periods: run.length,
+      sinceName: periods[run.start]!.name,
+      from: series.points[run.start]!,
+      to: series.points[run.start + run.length]!,
+    });
+  }
+  {
+    const run = longestRun(cacheShareSeries, -1);
+    if (run !== null) {
+      runs.push({
+        kind: 'cache-share-decaying',
+        subject: 'cache',
+        periods: run.length,
+        sinceName: periods[run.start]!.name,
+        from: cacheShareSeries[run.start]!,
+        to: cacheShareSeries[run.start + run.length]!,
+      });
+    }
+  }
+  runs.sort((a, b) => b.periods - a.periods);
+
+  /**
+   * Plans held against each other: the same action (kind, label, model) in
+   * two or more plans is a decision nobody is executing, and the dates make
+   * the sentence sayable — "planned first on <date>, still planned on
+   * <date>".
+   */
+  const seen = new Map<string, RepeatedPlanAction>();
+  const ordered = [...plans].sort((a, b) => (a.createdAt ?? '').localeCompare(b.createdAt ?? ''));
+  for (const plan of ordered) {
+    for (const action of plan.actions) {
+      const key = `${action.kind}\n${action.label}\n${action.model}`;
+      const entry = seen.get(key);
+      if (entry === undefined) {
+        seen.set(key, {
+          kind: action.kind,
+          label: action.label,
+          model: action.model,
+          appearances: 1,
+          firstPlanned: plan.createdAt ?? null,
+          lastPlanned: plan.createdAt ?? null,
+        });
+      } else {
+        entry.appearances += 1;
+        entry.lastPlanned = plan.createdAt ?? entry.lastPlanned;
+      }
+    }
+  }
+  const repeatedPlanActions = [...seen.values()]
+    .filter((entry) => entry.appearances >= 2)
+    .sort((a, b) => b.appearances - a.appearances);
+
+  return {
+    schemaVersion: 1,
+    periods,
+    labelSeries,
+    modelShareSeries,
+    cacheShareSeries,
+    runs,
+    repeatedPlanActions,
+    undatedReports,
+  };
+}
+
+/**
+ * Reads one stored `profile --json` document into the slice history needs.
+ * Returns null when the JSON is not a profile document — the caller names
+ * the file rather than absorbing it.
+ */
+export function storedReportFrom(name: string, parsed: unknown): StoredReport | null {
+  const doc = parsed as {
+    schemaVersion?: number;
+    span?: { fromMs: number; toMs: number } | null;
+    total?: {
+      totalUsd?: number;
+      calls?: number;
+      inputTokens?: number;
+      cacheReadTokens?: number;
+      cacheWriteTokens?: number;
+    };
+    byLabelAndModel?: {
+      label?: string;
+      model?: string;
+      breakdown?: { totalUsd?: number };
+    }[];
+  };
+  if (doc === null || typeof doc !== 'object') return null;
+  if (doc.schemaVersion !== 1 || doc.total === undefined || !Array.isArray(doc.byLabelAndModel)) {
+    return null;
+  }
+
+  const byLabel = new Map<string, number>();
+  const byModel = new Map<string, number>();
+  for (const slice of doc.byLabelAndModel) {
+    const usd = slice.breakdown?.totalUsd ?? 0;
+    const label = slice.label ?? UNLABELLED;
+    const model = slice.model ?? 'unknown';
+    byLabel.set(label, (byLabel.get(label) ?? 0) + usd);
+    byModel.set(model, (byModel.get(model) ?? 0) + usd);
+  }
+
+  const input = doc.total.inputTokens ?? 0;
+  const cacheRead = doc.total.cacheReadTokens ?? 0;
+  const cacheWrite = doc.total.cacheWriteTokens ?? 0;
+  const denominator = input + cacheRead + cacheWrite;
+
+  return {
+    name,
+    span: doc.span ?? null,
+    totalUsd: doc.total.totalUsd ?? 0,
+    calls: doc.total.calls ?? 0,
+    byLabel,
+    byModel,
+    cacheReadShare: denominator > 0 ? cacheRead / denominator : null,
+  };
+}

package/src/index.ts

@@ -46,6 +46,10 @@ export { measuredUsage, labelCoverage, MIN_SCALE_DAYS, SCALE_TO_DAYS } from './m
 export { assignSources, fleetRollup } from './fleet.js';
 export { buildPlan, planLabelName } from './plan.js';
 export type { PlanAction, PlanActionKind, PlanAssumption, PlanDocument } from './plan.js';
+export { verifyPlan } from './verify.js';
+export { buildHistory, storedReportFrom, MIN_RUN } from './history.js';
+export type { HistoryDocument, HistoryRun, RepeatedPlanAction, StoredReport } from './history.js';
+export type { CannotTellReason, PlanVerification, VerifiedAction, VerifyOutcome } from './verify.js';
 export type { FleetSource, FleetRollup } from './fleet.js';
 export type { MeasuredUsage, LabelCoverage } from './measured-profile.js';
 export type { GateExplanation } from './gate-explain.js';

package/src/plan.ts

@@ -78,6 +78,13 @@ export interface PlanAction {
     routeTo?: { id: string; displayName: string };
     /** The measured pieces behind a stake. */
     measured?: Record<string, number>;
+    /**
+     * The slice as it was when the plan was made — what a later verification
+     * compares the newer log against. Without this the plan is a prediction
+     * with no record of the world it was made in, and "calls doubled" could
+     * never be told from "the prediction was wrong".
+     */
+    baseline?: { calls: number; usd: number; inputPerCallTokens: number; outputPerCallTokens: number };
   };
 }
 
@@ -116,6 +123,19 @@ export function buildPlan(
 ): PlanDocument {
   const actions: PlanAction[] = [];
 
+  /** The slice as the plan saw it, recorded so verification has a "before". */
+  const baselineOf = (label: string, model: string) => {
+    const slice = report.byLabelAndModel.find((s) => s.label === label && s.model === model);
+    if (slice === undefined || slice.breakdown.calls === 0) return undefined;
+    const b = slice.breakdown;
+    return {
+      calls: b.calls,
+      usd: b.totalUsd,
+      inputPerCallTokens: (b.inputTokens + b.cacheReadTokens + b.cacheWriteTokens) / b.calls,
+      outputPerCallTokens: b.outputTokens / b.calls,
+    };
+  };
+
   for (const slice of levers.slices) {
     const assumes: PlanAssumption[] = [];
     let kind: PlanActionKind;
@@ -140,7 +160,10 @@ export function buildPlan(
       stakeUsd: null,
       assumes,
       check: slice.route !== null ? 'trazum route <log> --prompt-file <prompt> --cases <cases>' : null,
-      detail: slice.route !== null ? { routeTo: slice.route.candidate } : {},
+      detail: {
+        ...(slice.route !== null ? { routeTo: slice.route.candidate } : {}),
+        baseline: baselineOf(slice.label, slice.model),
+      },
     });
   }
 
@@ -160,6 +183,7 @@ export function buildPlan(
           retried: row.retried,
           truncatedCalls: row.truncatedCalls,
         },
+        baseline: baselineOf(row.label, row.model),
       },
     });
   }
@@ -182,6 +206,7 @@ export function buildPlan(
           spentUsd: economics.spentUsd,
           withoutCachingUsd: economics.withoutCachingUsd,
         },
+        baseline: baselineOf(slice.label, slice.model),
       },
     });
   }