fix(insights): bound usage settling by the stream cap, discard unreadable segments, neutral zero delta

Author: waleedlatif1

apps/sim/ee/organization-usage/components/usage-credits.test.tsx

@@ -34,6 +34,18 @@ describe('UsageCredits', () => {
     expect(failed).toContain('load credits.')
   })
 
+  it('shows an unchanged period as neutral, not as a decrease', () => {
+    const markup = renderToStaticMarkup(
+      <UsageCredits
+        overview={{ ...overview, totals: { credits: 100 }, previousTotals: { credits: 100 } }}
+        isLoading={false}
+        isError={false}
+      />
+    )
+    expect(markup).toContain('No change compared with the previous period')
+    expect(markup).not.toContain('↓')
+  })
+
   it('omits the allowance outside the organization period', () => {
     const markup = renderToStaticMarkup(
       <UsageCredits

apps/sim/ee/organization-usage/components/usage-credits.tsx

@@ -104,7 +104,8 @@ export function UsageCredits({
   const { layers, legend } = useMemo(() => toCreditLayers(current?.series ?? []), [current])
   const used = current?.totals.credits ?? 0
   const previous = current?.previousTotals?.credits ?? 0
-  const delta = current && previous > 0 ? ((used - previous) / previous) * 100 : null
+  /** Rounded once, so the arrow and the figure never disagree about a sub-percent change. */
+  const delta = current && previous > 0 ? Math.round(((used - previous) / previous) * 100) : null
   const limit = current?.limitCredits ?? null
   const highlight = useLegendHighlight(legend.map((item) => item.id))
 
@@ -122,8 +123,12 @@ export function UsageCredits({
             <Badge
               variant={delta > 0 ? 'amber' : 'gray-secondary'}
               size='sm'
-              aria-label={`${Math.abs(delta).toFixed(0)}% ${delta > 0 ? 'increase' : delta < 0 ? 'decrease' : 'change'} compared with the previous period`}
-            >{`${delta > 0 ? '↑' : '↓'} ${Math.abs(delta).toFixed(0)}%`}</Badge>
+              aria-label={
+                delta === 0
+                  ? 'No change compared with the previous period'
+                  : `${Math.abs(delta)}% ${delta > 0 ? 'increase' : 'decrease'} compared with the previous period`
+              }
+            >{`${delta > 0 ? '↑ ' : delta < 0 ? '↓ ' : ''}${Math.abs(delta)}%`}</Badge>
           )}
           {limit !== null && used > limit && (
             <Badge variant='red' size='sm'>

apps/sim/ee/organization-usage/hooks/use-legend-highlight.ts

@@ -5,15 +5,16 @@ import { useState } from 'react'
 /**
  * Hover and click highlighting shared by a chart and its legend.
  *
- * A selection whose series the current window no longer draws is ignored: otherwise
- * every layer would stay dimmed after a period change, with no legend entry left to
- * clear it.
+ * A hover or selection whose series the current window no longer draws is ignored:
+ * otherwise every layer would stay dimmed after a period change, with no legend entry
+ * left to clear it.
  */
 export function useLegendHighlight(seriesIds: readonly string[]) {
   const [hoveredId, setHoveredId] = useState<string | null>(null)
   const [selectedId, setSelectedId] = useState<string | null>(null)
-  const activeSelection = selectedId !== null && seriesIds.includes(selectedId) ? selectedId : null
-  const highlightedId = hoveredId ?? activeSelection
+  const isDrawn = (id: string | null): id is string => id !== null && seriesIds.includes(id)
+  const activeSelection = isDrawn(selectedId) ? selectedId : null
+  const highlightedId = isDrawn(hoveredId) ? hoveredId : activeSelection
   return {
     highlightedId,
     legendProps: {

apps/sim/lib/billing/core/usage-analytics.ts

@@ -6,6 +6,7 @@ import {
   resolveEnterpriseReportingPeriod,
 } from '@/lib/billing/core/reporting-period'
 import type { BillingEntity } from '@/lib/billing/core/usage-log'
+import { STREAM_TIMEOUT_MS } from '@/lib/copilot/constants'
 import { zonedWallClockToUtc } from '@/lib/core/utils/timezone'
 
 /**
@@ -487,10 +488,11 @@ export function usageBucketTimestamps(
  * How long after a stretch of time ends before its ledger rows are final.
  *
  * Rows are stamped when inserted, but a cumulative model charge tops up its row's
- * cost in place for as long as the stream runs. Past this lag a day or hour is
- * treated as settled.
+ * cost in place for as long as its stream runs — which {@link STREAM_TIMEOUT_MS}
+ * caps — plus the retry flushes that follow it. Past the cap and this margin a day or
+ * hour can no longer change and is treated as settled.
  */
-export const USAGE_SETTLE_MS = 3 * 60 * 60 * 1000
+export const USAGE_SETTLE_MS = STREAM_TIMEOUT_MS + 2 * 60 * 60 * 1000
 
 const HOUR_MS = 60 * 60 * 1000
 

apps/sim/lib/billing/core/usage-segment-cache.test.ts

@@ -4,7 +4,8 @@
 import { generateShortId } from '@sim/utils/id'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
-vi.mock('@/lib/core/config/redis', () => ({ getRedisClient: () => null }))
+const redisMock = vi.hoisted(() => ({ client: null as unknown }))
+vi.mock('@/lib/core/config/redis', () => ({ getRedisClient: () => redisMock.client }))
 
 import { type UsageSegment, usageHourKey } from '@/lib/billing/core/usage-analytics'
 import { readThroughSegments } from '@/lib/billing/core/usage-segment-cache'
@@ -58,9 +59,20 @@ describe('readThroughSegments', () => {
 
   beforeEach(() => {
     vi.clearAllMocks()
+    redisMock.client = null
     namespace = `test-${generateShortId()}`
   })
 
+  it('reads the ledger when a stored entry does not parse, rather than failing', async () => {
+    redisMock.client = {
+      mget: async (...keys: string[]) => keys.map(() => '{not json'),
+      pipeline: () => ({ set: () => undefined, exec: async () => [] }),
+    }
+    const entries = await read([day('2026-01-05')])
+    expect(fetchRange).toHaveBeenCalledTimes(1)
+    expect(totalByDay(entries)).toEqual({ '2026-01-05': 24 })
+  })
+
   it('reads every missing segment in one merged range and counts each hour once', async () => {
     const segments = [day('2026-01-01'), ...hours('2026-01-02', 10)]
     const entries = await read(segments)

apps/sim/lib/billing/core/usage-segment-cache.ts

@@ -60,6 +60,21 @@ async function readStored(keys: string[]): Promise<(string | null)[]> {
   }
 }
 
+/**
+ * A stored value, or `undefined` for a miss. An entry that does not parse — written by
+ * an older shape, or corrupted — is a miss too: the ledger answers instead of a failed
+ * page, and the fresh value overwrites it.
+ */
+function parseStored<T>(key: string, value: string | null | undefined): T | undefined {
+  if (value == null) return undefined
+  try {
+    return JSON.parse(value) as T
+  } catch (error) {
+    logger.warn('Discarding unreadable usage segment', { key, error: getErrorMessage(error) })
+    return undefined
+  }
+}
+
 /** Fire-and-forget: a page never waits on, or fails because of, a cache write. */
 function writeStored(entries: { key: string; value: string; ttlMs: number }[]): void {
   if (entries.length === 0) return
@@ -141,14 +156,16 @@ export async function readThroughSegments<T>({
   const writes: { key: string; value: string; ttlMs: number }[] = []
   const cached = new Map<UsageSegment, T>()
   settled.forEach((segment, index) => {
-    const value = stored[index]
-    if (value != null) cached.set(segment, JSON.parse(value) as T)
+    const value = parseStored<T>(keyOf(segment.key), stored[index])
+    if (value !== undefined) cached.set(segment, value)
   })
   assemblable.forEach((segment, index) => {
     if (cached.has(segment)) return
-    const hours = storedHours.slice(index * 24, index * 24 + 24)
-    if (hours.some((hour) => hour == null)) return
-    const value = combine(hours.map((hour) => JSON.parse(hour as string) as T))
+    const hours = storedHours
+      .slice(index * 24, index * 24 + 24)
+      .map((hour, offset) => parseStored<T>(keyOf(usageHourKey(segment.day, offset)), hour))
+    if (hours.some((hour) => hour === undefined)) return
+    const value = combine(hours as T[])
     cached.set(segment, value)
     writes.push({ key: keyOf(segment.key), value: JSON.stringify(value), ttlMs })
   })