tledger 0.3.0 → 0.4.0

package/bin/token-ledger-trend.mjs

@@ -1,13 +1,25 @@
 import {
-  creditsForUsage,
-  FAST_MODE_MULTIPLIER,
-  RATE_CARD_AS_OF,
-} from "./token-ledger-rates.mjs";
+  calculateCodexPurchasedCredits,
+  CODEX_CREDIT_RATE_CARD_AS_OF,
+} from "../lib/token-ledger-rates.mjs";
 import {
-  splitUsageBucketsAtBoundaries,
-  usageBuckets,
-  usageBucketsInRange,
+  MAX_SAFE_TOKEN_COUNT,
+  checkedFiniteAdd,
+  checkedTokenAdd,
+  tokenValue,
 } from "../lib/token-ledger-usage.mjs";
+import {
+  createTimeZoneFormatter,
+  localDateBoundary,
+  localDateString,
+  shiftCalendarDate,
+  todayInTimeZone,
+} from "../lib/token-ledger-calendar.mjs";
+import { buildRangeAnalysis as buildIndexedRangeAnalysis } from "../lib/token-ledger-range-analysis.mjs";
+import {
+  quotaIdentityMatchesContract,
+  snapshotHasCurrentQuotaIdentityContract,
+} from "../lib/token-ledger-quota-contract.mjs";
 
 const WEEK_MINUTES = 10_080;
 const RESET_JITTER_SECONDS = 5 * 60;
@@ -17,96 +29,41 @@ const MAX_TREND_DAYS = 3_650;
 const LONG_GAP_MS = 36 * 60 * 60 * 1_000;
 
 const MODEL_SORT_ORDER = new Map([
-  ["Luna", 0],
-  ["Sol", 1],
-  ["Terra", 2],
-  ["GPT-5.5", 3],
-  ["GPT-5.4", 4],
-  ["Daybreak", 5],
-  ["Auto review", 6],
-  ["Other", 7],
-  ["Unknown", 8],
-  ["Unattributed", 9],
+  ["Astra", 0],
+  ["Luna", 1],
+  ["Sol", 2],
+  ["Terra", 3],
+  ["GPT-5.5", 4],
+  ["GPT-5.4", 5],
+  ["Daybreak", 6],
+  ["Auto review", 7],
+  ["Other", 8],
+  ["Unknown", 9],
+  ["Unattributed", 10],
 ]);
 
 function finiteTimestamp(value) {
-  const timestamp = new Date(value).getTime();
+  if (typeof value !== "string" && !Number.isFinite(value)) return null;
+  const timestamp = typeof value === "string"
+    ? Date.parse(value)
+    : new Date(value).getTime();
   return Number.isFinite(timestamp) ? timestamp : null;
 }
 
-function dateStringFromParts(parts) {
-  return [parts.year, parts.month, parts.day]
-    .map((value, index) =>
-      index === 0 ? String(value) : String(value).padStart(2, "0"),
-    )
-    .join("-");
-}
-
-function shiftCalendarDate(dateString, amount) {
-  const [year, month, day] = dateString.split("-").map(Number);
-  const date = new Date(Date.UTC(year, month - 1, day + amount));
-  return dateStringFromParts({
-    year: date.getUTCFullYear(),
-    month: date.getUTCMonth() + 1,
-    day: date.getUTCDate(),
-  });
-}
-
-function offsetAt(instant, timeZone) {
-  const parts = new Intl.DateTimeFormat("en-US", {
-    timeZone,
-    timeZoneName: "longOffset",
-  }).formatToParts(instant);
-  const value = parts.find((part) => part.type === "timeZoneName")?.value ?? "GMT";
-  if (value === "GMT") return 0;
-  const match = value.match(/^GMT([+-])(\d{2}):?(\d{2})?$/);
-  if (!match) return 0;
-  const minutes = Number(match[2]) * 60 + Number(match[3] || 0);
-  return (match[1] === "+" ? 1 : -1) * minutes * 60 * 1_000;
-}
-
-function zonedMidnight(dateString, timeZone) {
-  const [year, month, day] = dateString.split("-").map(Number);
-  const utcGuess = Date.UTC(year, month - 1, day);
-  let instant = new Date(utcGuess - offsetAt(new Date(utcGuess), timeZone));
-  instant = new Date(utcGuess - offsetAt(instant, timeZone));
-  return instant;
-}
-
-function localDateString(timestampMs, timeZone) {
-  return new Intl.DateTimeFormat("en-CA", {
-    timeZone,
-    year: "numeric",
-    month: "2-digit",
-    day: "2-digit",
-  }).format(new Date(timestampMs));
-}
-
-function todayInTimeZone(timeZone) {
-  const parts = new Intl.DateTimeFormat("en-US", {
-    timeZone,
-    year: "numeric",
-    month: "2-digit",
-    day: "2-digit",
-  }).formatToParts(new Date());
-  const values = Object.fromEntries(
-    parts
-      .filter((part) => part.type !== "literal")
-      .map((part) => [part.type, Number(part.value)]),
-  );
-  return dateStringFromParts(values);
-}
-
 export function multiDayBounds(value, timeZone, rangeDays) {
   const days = Number(rangeDays);
   if (!Number.isSafeInteger(days) || days < 1 || days > MAX_TREND_DAYS) {
     throw new Error(`Trend range must be between 1 and ${MAX_TREND_DAYS} days.`);
   }
+  const formatter = createTimeZoneFormatter(timeZone);
   let endDateString = value;
   if (!endDateString || endDateString === "today") {
-    endDateString = todayInTimeZone(timeZone);
+    endDateString = todayInTimeZone(timeZone, formatter);
   } else if (endDateString === "yesterday") {
-    endDateString = shiftCalendarDate(todayInTimeZone(timeZone), -1);
+    endDateString = shiftCalendarDate(
+      todayInTimeZone(timeZone, formatter),
+      -1,
+    );
   }
   if (!/^\d{4}-\d{2}-\d{2}$/.test(endDateString)) {
     throw new Error("Trend end date must be YYYY-MM-DD, today, or yesterday.");
@@ -125,19 +82,28 @@ export function multiDayBounds(value, timeZone, rangeDays) {
     dateString: endDateString,
     startDateString,
     endDateString,
-    start: zonedMidnight(startDateString, timeZone),
-    end: zonedMidnight(shiftCalendarDate(endDateString, 1), timeZone),
+    start: localDateBoundary(startDateString, timeZone, formatter),
+    end: localDateBoundary(
+      shiftCalendarDate(endDateString, 1),
+      timeZone,
+      formatter,
+    ),
     timeZone,
     rangeDays: days,
   };
 }
 
-function clampPercent(value) {
-  return Math.min(100, Math.max(0, Number(value) || 0));
+export function priorPeriodBounds(bounds, days = bounds.rangeDays) {
+  return multiDayBounds(
+    shiftCalendarDate(bounds.startDateString, -1),
+    bounds.timeZone,
+    days,
+  );
 }
 
 export function trendModelLabel(value) {
   const model = String(value || "unknown").trim().toLowerCase();
+  if (model.includes("astra")) return "Astra";
   if (model.includes("luna")) return "Luna";
   if (model.includes("sol")) return "Sol";
   if (model.includes("terra")) return "Terra";
@@ -150,55 +116,40 @@ export function trendModelLabel(value) {
 }
 
 export function weeklyQuotaObservations(snapshot = {}) {
-  let observations = (snapshot.quotaObservations ?? [])
-    .map((observation) => ({
-      ...observation,
-      timestampMs: finiteTimestamp(observation.timestamp),
-      resetsAt: Number(observation.resetsAt),
-      usedPercent: Number(observation.usedPercent),
-    }))
-    .filter(
-      (observation) =>
-        Number(observation.windowMinutes) === WEEK_MINUTES &&
-        observation.timestampMs !== null &&
-        Number.isFinite(observation.resetsAt) &&
-        observation.resetsAt > 0 &&
-        Number.isFinite(observation.usedPercent),
+  if (!snapshotHasCurrentQuotaIdentityContract(snapshot)) return [];
+  if (!Array.isArray(snapshot.quotaObservations)) return [];
+  let observations = snapshot.quotaObservations
+    .filter((observation) =>
+      observation !== null &&
+      typeof observation === "object" &&
+      observation.windowMinutes === WEEK_MINUTES &&
+      Number.isFinite(observation.resetsAt) &&
+      observation.resetsAt > 0 &&
+      Number.isFinite(observation.usedPercent) &&
+      observation.usedPercent >= 0 &&
+      observation.usedPercent <= 100,
     )
-    .map((observation) => ({
-      ...observation,
-      usedPercent: clampPercent(observation.usedPercent),
-    }));
-
-  // Keep exactly one meter: the account-wide weekly limit. Legacy snapshots
-  // tag it with scope: "account"; current snapshots carry a limitKey per
-  // limit bucket, where the account-wide bucket has no limitName. Named
-  // buckets (per-model limit pools) are separate meters and must not be
-  // stitched into this line.
-  const accountScoped = observations.filter(
-    (observation) => observation.scope === "account",
+    .map((observation) => {
+      const timestampMs = finiteTimestamp(observation.timestamp);
+      const lastSeenAtMs = finiteTimestamp(observation.lastSeenAt);
+      return {
+        ...observation,
+        timestampMs,
+        observedThroughMs:
+          timestampMs === null
+            ? lastSeenAtMs
+            : Math.max(timestampMs, lastSeenAtMs ?? timestampMs),
+      };
+    })
+    .filter((observation) => observation.timestampMs !== null);
+
+  // Keep exactly one meter: only explicit provider-derived account scope is
+  // authoritative. A missing display label does not prove account scope.
+  observations = observations.filter(
+    (observation) =>
+      observation.scope === "account" &&
+      quotaIdentityMatchesContract(observation),
   );
-  if (accountScoped.length) {
-    observations = accountScoped;
-  } else if (observations.some((observation) => observation.limitKey)) {
-    const groups = new Map();
-    for (const observation of observations) {
-      const key = observation.limitKey ?? "anonymous";
-      const group = groups.get(key) ?? [];
-      group.push(observation);
-      groups.set(key, group);
-    }
-    const accountWide = [...groups.values()].filter((group) =>
-      group.every((observation) => !observation.limitName),
-    );
-    const pool = accountWide.length ? accountWide : [...groups.values()];
-    observations = pool.sort((left, right) => right.length - left.length)[0];
-  } else {
-    const accountWide = observations.filter(
-      (observation) => !observation.limitName,
-    );
-    if (accountWide.length) observations = accountWide;
-  }
 
   observations.sort(
     (left, right) =>
@@ -214,6 +165,13 @@ export function weeklyQuotaObservations(snapshot = {}) {
 // stale readings from sessions still reporting a superseded window would
 // otherwise be fused into one line, producing meter drain that never happened.
 export function normalizeQuotaTimeline(observations) {
+  // Some source logs stamp new quota payloads with an old session timestamp.
+  // A weekly reading cannot precede its own window. Such an anchor would
+  // reorder entire epochs and suppress otherwise valid subsequent readings.
+  observations = observations.filter((observation) =>
+    observation.timestampMs >=
+      (observation.resetsAt - WEEK_MINUTES * 60 - RESET_JITTER_SECONDS) * 1_000,
+  );
   if (!observations.length) return [];
 
   const epochs = [];
@@ -277,6 +235,12 @@ export function normalizeQuotaTimeline(observations) {
           : Math.max(usedPercent, observation.usedPercent);
       normalized.push({
         ...observation,
+        observedThroughMs: Math.min(
+          Number.isFinite(observation.observedThroughMs)
+            ? observation.observedThroughMs
+            : observation.timestampMs,
+          nextFirstMs,
+        ),
         cycle,
         reset: !emitted && previousEpoch !== null,
         resetKind,
@@ -291,46 +255,53 @@ export function normalizeQuotaTimeline(observations) {
 }
 
 export function eventCredits(event) {
-  // Recompute from token components first so the current rate card applies;
-  // snapshots can carry credits stored under an outdated card. Fast-mode
-  // turns (service tier "priority") debit the limit at a higher rate.
-  const multiplier =
-    event.serviceTier === "priority" ? FAST_MODE_MULTIPLIER : 1;
-  const computed = creditsForUsage(event.model, event);
-  if (Number.isFinite(computed) && computed >= 0) return computed * multiplier;
-  const stored = Number(event.rateCardCredits);
-  if (event.rateCardCredits !== null && event.rateCardCredits !== undefined) {
-    // Stored credits from current snapshots already include the fast-mode
-    // multiplier.
-    if (Number.isFinite(stored) && stored >= 0) return stored;
-  }
-  return null;
+  // Always recompute with the current purchased-credit card. Snapshot values
+  // may have been stored under an older card and must not fill a current gap.
+  return calculateCodexPurchasedCredits({
+    model: event.rateCardModel ?? event.model,
+    serviceTier: event.serviceTier,
+    usage: event,
+  });
 }
 
 function eventWeight(event, fallbackCreditsPerToken) {
   const credits = eventCredits(event);
   if (Number.isFinite(credits) && credits > 0) return credits;
-  const tokens = Math.max(0, Number(event.totalTokens) || 0);
+  const tokens = tokenValue(event.totalTokens, {
+    allowFractional: event.rangeAllocationEstimated === true,
+  });
   return fallbackCreditsPerToken > 0 ? tokens * fallbackCreditsPerToken : tokens;
 }
 
+function addRatedTotals(totals, credits, tokens) {
+  const scaledTokens = tokens / totals.scale;
+  const scaledCredits = credits / totals.scale;
+  const nextTokens = totals.tokens + scaledTokens;
+  const nextCredits = checkedFiniteAdd(totals.credits, scaledCredits);
+  const scaleFactor = Math.max(1, nextTokens / MAX_SAFE_TOKEN_COUNT);
+  totals.tokens = nextTokens / scaleFactor;
+  totals.credits = nextCredits / scaleFactor;
+  totals.scale *= scaleFactor;
+}
+
 function allocateBurn(delta, events, timeZone) {
   if (!(delta > 0)) return { contributions: new Map(), method: "none" };
 
-  let ratedCredits = 0;
-  let ratedTokens = 0;
+  const ratedTotals = { credits: 0, tokens: 0, scale: 1 };
   let hasUnrated = false;
   for (const event of events) {
+    if (event?.invalidTokenRecord === true) continue;
     const credits = eventCredits(event);
-    const tokens = Math.max(0, Number(event.totalTokens) || 0);
+    const allowFractional = event.rangeAllocationEstimated === true;
+    const tokens = tokenValue(event.totalTokens, { allowFractional });
     if (Number.isFinite(credits) && credits > 0) {
-      ratedCredits += credits;
-      ratedTokens += tokens;
+      addRatedTotals(ratedTotals, credits, tokens);
     } else if (tokens > 0) {
       hasUnrated = true;
     }
   }
 
+  const { credits: ratedCredits, tokens: ratedTokens } = ratedTotals;
   const fallbackCreditsPerToken =
     ratedCredits > 0 && ratedTokens > 0 ? ratedCredits / ratedTokens : 0;
   const weights = new Map();
@@ -340,12 +311,12 @@ function allocateBurn(delta, events, timeZone) {
     const weight = eventWeight(event, fallbackCreditsPerToken);
     if (!(weight > 0)) continue;
     const model = trendModelLabel(event.model);
-    weights.set(model, (weights.get(model) ?? 0) + weight);
+    weights.set(model, checkedFiniteAdd(weights.get(model) ?? 0, weight));
     if (timeZone) {
       const day = localDateString(event.timestampMs, timeZone);
-      dayWeights.set(day, (dayWeights.get(day) ?? 0) + weight);
+      dayWeights.set(day, checkedFiniteAdd(dayWeights.get(day) ?? 0, weight));
     }
-    totalWeight += weight;
+    totalWeight = checkedFiniteAdd(totalWeight, weight);
   }
 
   if (!(totalWeight > 0)) {
@@ -377,19 +348,24 @@ function allocateBurn(delta, events, timeZone) {
 }
 
 // Fractions of the span [startMs, endMs) falling on each local calendar day.
-function durationDayShares(startMs, endMs, timeZone) {
+export function durationDayShares(startMs, endMs, timeZone) {
+  const formatter = createTimeZoneFormatter(timeZone);
   if (!(endMs > startMs)) {
-    return new Map([[localDateString(endMs, timeZone), 1]]);
+    return new Map([[localDateString(endMs, timeZone, formatter), 1]]);
   }
   const shares = new Map();
   let cursor = startMs;
   while (cursor < endMs) {
-    const day = localDateString(cursor, timeZone);
-    const nextMidnightMs = zonedMidnight(
+    const day = localDateString(cursor, timeZone, formatter);
+    const nextBoundaryMs = localDateBoundary(
       shiftCalendarDate(day, 1),
       timeZone,
+      formatter,
     ).getTime();
-    const sliceEnd = Math.min(endMs, Math.max(nextMidnightMs, cursor + 1));
+    if (!(nextBoundaryMs > cursor)) {
+      throw new Error(`Local calendar boundary did not advance after ${day}.`);
+    }
+    const sliceEnd = Math.min(endMs, nextBoundaryMs);
     shares.set(day, (shares.get(day) ?? 0) + (sliceEnd - cursor));
     cursor = sliceEnd;
   }
@@ -399,11 +375,27 @@ function durationDayShares(startMs, endMs, timeZone) {
 
 function tokenTotalsByModel(events) {
   const totals = new Map();
+  let scale = 1;
+  let totalTokens = 0;
   for (const event of events) {
-    const tokens = Math.max(0, Number(event.totalTokens) || 0);
+    if (event?.invalidTokenRecord === true) continue;
+    const allowFractional = event.rangeAllocationEstimated === true;
+    const tokens = tokenValue(event.totalTokens, { allowFractional });
     if (!(tokens > 0)) continue;
     const model = trendModelLabel(event.model);
-    totals.set(model, (totals.get(model) ?? 0) + tokens);
+    const contribution = tokens / scale;
+    const nextTotal = totalTokens + contribution;
+    const scaleFactor = Math.max(1, nextTotal / MAX_SAFE_TOKEN_COUNT);
+    if (scaleFactor > 1) {
+      for (const [modelName, value] of totals) {
+        totals.set(modelName, value / scaleFactor);
+      }
+      totalTokens /= scaleFactor;
+      scale *= scaleFactor;
+    }
+    const scaledContribution = contribution / scaleFactor;
+    totals.set(model, (totals.get(model) ?? 0) + scaledContribution);
+    totalTokens += scaledContribution;
   }
   return totals;
 }
@@ -420,12 +412,6 @@ function cloneAllocations(allocations) {
   );
 }
 
-function eventsInBounds(events, bounds) {
-  const startMs = bounds.start.getTime();
-  const endMs = bounds.end.getTime();
-  return usageBucketsInRange({ events }, startMs, endMs);
-}
-
 function buildModelStats(displayedEvents, intervals, bounds) {
   const rows = new Map();
   const rowFor = (model) => {
@@ -443,17 +429,26 @@ function buildModelStats(displayedEvents, intervals, bounds) {
   };
 
   for (const event of displayedEvents) {
+    if (event?.invalidTokenRecord === true) continue;
     const model = trendModelLabel(event.model);
     const row = rowFor(model);
-    const tokens = Math.max(0, Number(event.totalTokens) || 0);
+    const allowFractional = event.rangeAllocationEstimated === true;
+    const tokens = tokenValue(event.totalTokens, { allowFractional });
     const credits = eventCredits(event);
-    row.tokens += tokens;
+    row.tokens = checkedTokenAdd(row.tokens, tokens, { allowFractional });
     if (Number.isFinite(credits) && credits >= 0) {
-      row.credits += credits;
-      row.ratedTokens += tokens;
+      row.credits = checkedFiniteAdd(row.credits, credits);
+      row.ratedTokens = checkedTokenAdd(row.ratedTokens, tokens, {
+        allowFractional,
+      });
     }
     const effort = String(event.effort || "unknown").toLowerCase();
-    row.efforts.set(effort, (row.efforts.get(effort) ?? 0) + tokens);
+    row.efforts.set(
+      effort,
+      checkedTokenAdd(row.efforts.get(effort) ?? 0, tokens, {
+        allowFractional,
+      }),
+    );
   }
 
   const startMs = bounds.start.getTime();
@@ -462,8 +457,12 @@ function buildModelStats(displayedEvents, intervals, bounds) {
     if (interval.endMs < startMs || interval.endMs >= endMs) continue;
     for (const [model, burnPoints] of interval.contributions) {
       const row = rowFor(model);
-      row.burnPoints += burnPoints;
-      row.attributedTokens += interval.modelTokens.get(model) ?? 0;
+      row.burnPoints = checkedFiniteAdd(row.burnPoints, burnPoints);
+      row.attributedTokens = checkedTokenAdd(
+        row.attributedTokens,
+        interval.modelTokens.get(model) ?? 0,
+        { allowFractional: true },
+      );
     }
   }
 
@@ -496,13 +495,33 @@ function buildModelStats(displayedEvents, intervals, bounds) {
     );
 }
 
-export function buildUsageTrend(snapshot = {}, bounds) {
+export function buildRangeAnalysis(
+  snapshot = {},
+  bounds,
+  { priorBounds = null, includeTrend = true } = {},
+) {
+  const quotaObservations = normalizeQuotaTimeline(
+    weeklyQuotaObservations(snapshot),
+  );
+  const indexed = buildIndexedRangeAnalysis(snapshot, bounds, {
+    priorBounds,
+    quotaObservations,
+  });
+  return Object.freeze({
+    ...indexed,
+    trend: includeTrend
+      ? buildUsageTrendFromAnalysis(snapshot, bounds, indexed)
+      : null,
+  });
+}
+
+function buildUsageTrendFromAnalysis(snapshot, bounds, rangeAnalysis) {
   const startMs = bounds.start.getTime();
   const endMs = bounds.end.getTime();
-  const displayedEvents = eventsInBounds(usageBuckets(snapshot), bounds);
-  const observations = normalizeQuotaTimeline(
-    weeklyQuotaObservations(snapshot),
-  ).filter((observation) => observation.timestampMs < endMs);
+  const displayedEvents = rangeAnalysis.currentEvents;
+  const observations = rangeAnalysis.quotaObservations.filter(
+    (observation) => observation.timestampMs < endMs,
+  );
 
   if (!observations.length) {
     return {
@@ -514,23 +533,12 @@ export function buildUsageTrend(snapshot = {}, bounds) {
       sampleCount: 0,
       allocationMethod: "unavailable",
       observedThroughMs: null,
-      rateCardAsOf: snapshot.provenance?.rateCardAsOf ?? RATE_CARD_AS_OF,
+      rateCardAsOf: CODEX_CREDIT_RATE_CARD_AS_OF,
     };
   }
 
-  const sortedEvents = splitUsageBucketsAtBoundaries(
-    usageBuckets(snapshot),
-    [
-      startMs,
-      endMs,
-      ...observations.flatMap((observation) => [
-        observation.cycleStartMs,
-        observation.timestampMs,
-      ]),
-    ],
-  )
+  const sortedEvents = rangeAnalysis.trendEvents
     .map((event) => ({ ...event, timestampMs: finiteTimestamp(event.timestamp) }))
-    .filter((event) => event.timestampMs !== null && event.timestampMs < endMs)
     .sort((left, right) => left.timestampMs - right.timestampMs);
   const points = [];
   const resets = [];
@@ -592,7 +600,10 @@ export function buildUsageTrend(snapshot = {}, bounds) {
       methods.add(allocation.method);
     }
     for (const [model, burnPoints] of allocation.contributions) {
-      allocations.set(model, (allocations.get(model) ?? 0) + burnPoints);
+      allocations.set(
+        model,
+        checkedFiniteAdd(allocations.get(model) ?? 0, burnPoints),
+      );
     }
     if (delta > 0) {
       intervals.push({
@@ -617,6 +628,7 @@ export function buildUsageTrend(snapshot = {}, bounds) {
     }
     points.push({
       timestampMs: observation.timestampMs,
+      observedThroughMs: observation.observedThroughMs,
       cycle: observation.cycle,
       usedPercent: observation.normalizedUsedPercent,
       remainingPercent: 100 - observation.normalizedUsedPercent,
@@ -645,15 +657,46 @@ export function buildUsageTrend(snapshot = {}, bounds) {
       (point) => point.timestampMs > startMs && point.timestampMs < endMs,
     ),
   );
-  const lastPoint = displayPoints.at(-1);
-  if (lastPoint) {
-    displayPoints.push({
-      ...lastPoint,
-      timestampMs: endMs,
-      observed: false,
-      carried: true,
-    });
+
+  // Repeated equal meter readings are compacted into an observed span. Extend
+  // each displayed cycle only through its last real sample; never synthesize a
+  // flat line through the unobserved remainder of the report range.
+  const sourcePointsByCycle = new Map();
+  for (const point of points) {
+    const cyclePoints = sourcePointsByCycle.get(point.cycle) ?? [];
+    cyclePoints.push(point);
+    sourcePointsByCycle.set(point.cycle, cyclePoints);
   }
+  const displayedCycles = new Set(displayPoints.map((point) => point.cycle));
+  for (const cycle of displayedCycles) {
+    const cyclePoints = sourcePointsByCycle.get(cycle) ?? [];
+    const displayedCyclePoints = displayPoints.filter(
+      (point) => point.cycle === cycle,
+    );
+    const lastPoint = displayedCyclePoints.at(-1);
+    if (!lastPoint || !cyclePoints.length) continue;
+    const observedThroughMs = Math.max(
+      ...cyclePoints.map((point) => point.observedThroughMs),
+    );
+    const nextResetMs = resets.find((reset) => reset.cycle === cycle + 1)
+      ?.timestampMs;
+    const crossesNextReset = Number.isFinite(nextResetMs) &&
+      observedThroughMs >= nextResetMs;
+    const endpointMs = Math.min(observedThroughMs, endMs);
+    if (!crossesNextReset && endpointMs > lastPoint.timestampMs) {
+      displayPoints.push({
+        ...lastPoint,
+        timestampMs: endpointMs,
+        observedThroughMs: endpointMs,
+        observed: true,
+        carried: false,
+        confirmation: true,
+      });
+    }
+  }
+  displayPoints.sort(
+    (left, right) => left.timestampMs - right.timestampMs || left.cycle - right.cycle,
+  );
 
   const hasUnattributed = methods.has("unattributed");
   let allocationMethod = "unavailable";
@@ -699,12 +742,21 @@ export function buildUsageTrend(snapshot = {}, bounds) {
     ).length,
     allocationMethod,
     observedThroughMs:
-      [...points].reverse().find((point) => point.timestampMs < endMs)
+      [...displayPoints].reverse().find((point) => point.observed)
         ?.timestampMs ?? null,
-    rateCardAsOf: snapshot.provenance?.rateCardAsOf ?? RATE_CARD_AS_OF,
+    rateCardAsOf: CODEX_CREDIT_RATE_CARD_AS_OF,
   };
 }
 
+export function buildUsageTrend(snapshot = {}, bounds, { analysis = null } = {}) {
+  const rangeAnalysis = analysis ?? buildRangeAnalysis(snapshot, bounds);
+  return rangeAnalysis.trend ?? buildUsageTrendFromAnalysis(
+    snapshot,
+    bounds,
+    rangeAnalysis,
+  );
+}
+
 // Bin observed meter drain into calendar-day (or multi-day) columns in the
 // same percent unit as the meter line. Daily totals are the meter's own
 // observed drops; only the per-model split within a drop and the day
@@ -741,8 +793,8 @@ export function buildBurnDayBins(trend, bounds, { days, binSize = 1 } = {}) {
       )) {
         const share = burnPoints * fraction;
         if (!(share > 0)) continue;
-        bin.values.set(model, (bin.values.get(model) ?? 0) + share);
-        bin.totalPercent += share;
+        bin.values.set(model, checkedFiniteAdd(bin.values.get(model) ?? 0, share));
+        bin.totalPercent = checkedFiniteAdd(bin.totalPercent, share);
       }
     }
   }
@@ -751,8 +803,8 @@ export function buildBurnDayBins(trend, bounds, { days, binSize = 1 } = {}) {
   let totalPercent = 0;
   for (const bin of bins) {
     for (const [model, value] of bin.values) {
-      totals.set(model, (totals.get(model) ?? 0) + value);
-      totalPercent += value;
+      totals.set(model, checkedFiniteAdd(totals.get(model) ?? 0, value));
+      totalPercent = checkedFiniteAdd(totalPercent, value);
     }
   }
   return { bins, totals, totalPercent, binSize, binCount };