@aryacode/dsh-aryacode-polish 0.0.0-stage → 0.3.4

package/entries/cost.js

@@ -0,0 +1,273 @@
+/**
+ * Estimated session cost, priced from recorded provider usage.
+ *
+ * The Host half registers one durable projection: the fold replays
+ * model-attributed token usage from the session log, and the wire view prices
+ * it at the published DeepSeek rates. The browser half only formats numbers,
+ * so no rate table and no money arithmetic live in the bundle.
+ */
+import { z } from 'zod'
+import { applyModelUsage, initialModelUsage } from './usage.js'
+
+/**
+ * Off-peak price per million tokens. Peak is twice this. `usd` is the English
+ * price page and `cny` the Chinese one; cache writes are billed as misses.
+ * Verified 2026-09-27 against https://api-docs.deepseek.com/quick_start/pricing/
+ */
+const OFF_PEAK = {
+  flash: {
+    usd: { cache: '0.003', miss: '0.15', output: '0.6' },
+    cny: { cache: '0.02', miss: '1', output: '4' },
+  },
+  pro: {
+    usd: { cache: '0.022', miss: '0.66', output: '1.98' },
+    cny: { cache: '0.15', miss: '4.5', output: '13.5' },
+  },
+}
+
+/**
+ * Days the table above describes. Append a new period when prices change; the
+ * fold stamps each row with the hour its usage landed in.
+ */
+const RATE_PERIODS = [{ from: Date.parse('2026-09-10T04:00:00Z'), until: Infinity, rates: OFF_PEAK }]
+
+/** Providers whose prices this table describes. */
+const PRICED_PROVIDERS = ['deepseek-official', 'deepseek-account']
+
+/** Models that bill at the flash rate. */
+const FLASH_MODELS = ['deepseek-flash', 'deepseek-v4-flash', 'deepseek-v4-flash-vision-exp']
+
+/** Models that bill at the pro rate. */
+const PRO_MODELS = ['deepseek-v4-pro']
+
+const bucketsSchema = z.object({
+  uncachedInputTokens: z.number().int().nonnegative(),
+  outputTokens: z.number().int().nonnegative(),
+  cacheReadTokens: z.number().int().nonnegative(),
+  cacheWriteTokens: z.number().int().nonnegative(),
+}).strict()
+
+const rowSchema = z.object({
+  provider: z.string(),
+  model: z.string(),
+  requests: z.number().int().nonnegative(),
+  hour: z.number().int().nonnegative(),
+  peak: bucketsSchema,
+  offPeak: bucketsSchema,
+}).strict()
+
+const viewSchema = z.object({ models: z.array(rowSchema) }).strict()
+
+const lastSchema = z.object({
+  turn: z.number().int().nonnegative(),
+  step: z.number().int().nonnegative(),
+  key: z.string(),
+  peak: z.boolean(),
+  buckets: bucketsSchema,
+}).strict()
+
+const stateSchema = z.object({
+  rows: z.record(z.string(), rowSchema),
+  pending: z.object({ provider: z.string(), model: z.string() }).strict().nullable(),
+  last: lastSchema.nullable(),
+  view: viewSchema,
+}).strict()
+
+/** One priced model row: tokens, requests, and money when a rate is known. */
+const pricedModelSchema = z.object({
+  provider: z.string(),
+  model: z.string(),
+  requests: z.number().int().nonnegative(),
+  cacheRead: z.number().int().nonnegative(),
+  uncached: z.number().int().nonnegative(),
+  cacheWrite: z.number().int().nonnegative(),
+  output: z.number().int().nonnegative(),
+  incomplete: z.boolean(),
+  costCny: z.string().optional(),
+  costUsd: z.string().optional(),
+}).strict()
+
+/** The wire view: session totals plus one row per model. */
+const pricedSessionSchema = z.object({
+  tokens: z.number().int().nonnegative(),
+  cacheRead: z.number().int().nonnegative(),
+  uncached: z.number().int().nonnegative(),
+  cacheWrite: z.number().int().nonnegative(),
+  output: z.number().int().nonnegative(),
+  requests: z.number().int().nonnegative(),
+  incomplete: z.boolean(),
+  models: z.array(pricedModelSchema),
+  costCny: z.string().optional(),
+  costUsd: z.string().optional(),
+}).strict()
+
+/**
+ * @param {string} provider - routed provider id.
+ * @param {string} model - routed model id.
+ * @param {number} time - event time in milliseconds.
+ * @returns {object | undefined} the rate table for that route, when one is known.
+ */
+export function rateTable(provider, model, time) {
+  if (!PRICED_PROVIDERS.includes(provider)) return undefined
+  const kind = PRO_MODELS.includes(model) ? 'pro' : FLASH_MODELS.includes(model) ? 'flash' : undefined
+  if (kind === undefined) return undefined
+  const period = RATE_PERIODS.find(candidate => time >= candidate.from && time < candidate.until)
+  return period === undefined ? undefined : period.rates[kind]
+}
+
+/**
+ * @param {number} tokens - tokens billed at that rate.
+ * @param {string} perMillion - published price per million tokens.
+ * @param {boolean} peak - whether to double the price.
+ * @returns {number} money for those tokens.
+ */
+function price(tokens, perMillion, peak) {
+  const rate = Number(perMillion)
+  return (peak ? rate * 2 : rate) * tokens / 1_000_000
+}
+
+/**
+ * @param {object} band - one band's four counts.
+ * @returns {object} the same counts under the names the surface shows.
+ */
+function bandTokens(band) {
+  return {
+    cacheRead: band.cacheReadTokens,
+    uncached: band.uncachedInputTokens,
+    cacheWrite: band.cacheWriteTokens,
+    output: band.outputTokens,
+  }
+}
+
+/**
+ * @param {object} row - one usage row.
+ * @returns {object} both bands added up.
+ */
+function addCounts(row) {
+  const peak = bandTokens(row.peak)
+  const off = bandTokens(row.offPeak)
+  return {
+    cacheRead: peak.cacheRead + off.cacheRead,
+    uncached: peak.uncached + off.uncached,
+    cacheWrite: peak.cacheWrite + off.cacheWrite,
+    output: peak.output + off.output,
+  }
+}
+
+/**
+ * @param {object} band - one band's four counts.
+ * @param {object} table - rate table for the route.
+ * @param {boolean} peak - whether that band is billed as peak.
+ * @returns {{ cny: number, usd: number }} money for that band.
+ */
+function priceBand(band, table, peak) {
+  // Cache writes are a disjoint input bucket; DeepSeek bills them with misses.
+  const input = band.uncachedInputTokens + band.cacheWriteTokens
+  return {
+    cny: price(band.cacheReadTokens, table.cny.cache, peak)
+      + price(input, table.cny.miss, peak)
+      + price(band.outputTokens, table.cny.output, peak),
+    usd: price(band.cacheReadTokens, table.usd.cache, peak)
+      + price(input, table.usd.miss, peak)
+      + price(band.outputTokens, table.usd.output, peak),
+  }
+}
+
+/** The priced view of a session that has recorded nothing yet. */
+const EMPTY_PRICED = {
+  tokens: 0, cacheRead: 0, uncached: 0, cacheWrite: 0, output: 0, requests: 0, incomplete: false, models: [],
+}
+
+/**
+ * Price the durable model projection at the published DeepSeek rates.
+ * Unknown providers, models, or periods keep their tokens and mark the subtotal
+ * incomplete, so the surface never reports money it cannot stand behind.
+ * @param {object} usage - the projection's raw view.
+ * @returns {object} token totals, money for priced models, and one row per model.
+ */
+export function priceModelUsage(usage) {
+  if (usage === undefined || !Array.isArray(usage.models) || usage.models.length === 0) return EMPTY_PRICED
+  let cacheRead = 0
+  let uncached = 0
+  let cacheWrite = 0
+  let output = 0
+  let requests = 0
+  let cny = 0
+  let usd = 0
+  let priced = false
+  let incomplete = false
+  const grouped = new Map()
+  for (const row of usage.models) {
+    const counts = addCounts(row)
+    cacheRead += counts.cacheRead
+    uncached += counts.uncached
+    cacheWrite += counts.cacheWrite
+    output += counts.output
+    requests += row.requests
+    const table = rateTable(row.provider, row.model, row.hour * 3_600_000)
+    let costs
+    if (table !== undefined) {
+      const peakCost = priceBand(row.peak, table, true)
+      const offCost = priceBand(row.offPeak, table, false)
+      costs = { cny: peakCost.cny + offCost.cny, usd: peakCost.usd + offCost.usd }
+    }
+    if (costs === undefined) incomplete = true
+    else {
+      cny += costs.cny
+      usd += costs.usd
+      priced = true
+    }
+    const key = JSON.stringify([row.provider, row.model])
+    const previous = grouped.get(key)
+    const merged = {
+      provider: row.provider,
+      model: row.model,
+      requests: row.requests + (previous?.requests ?? 0),
+      cacheRead: counts.cacheRead + (previous?.cacheRead ?? 0),
+      uncached: counts.uncached + (previous?.uncached ?? 0),
+      cacheWrite: counts.cacheWrite + (previous?.cacheWrite ?? 0),
+      output: counts.output + (previous?.output ?? 0),
+      incomplete: costs === undefined || previous?.incomplete === true,
+    }
+    if (costs !== undefined || previous?.costUsd !== undefined) {
+      merged.costCny = ((costs?.cny ?? 0) + Number(previous?.costCny ?? 0)).toFixed(8)
+      merged.costUsd = ((costs?.usd ?? 0) + Number(previous?.costUsd ?? 0)).toFixed(8)
+    }
+    grouped.set(key, merged)
+  }
+  return {
+    tokens: cacheRead + uncached + cacheWrite + output,
+    cacheRead,
+    uncached,
+    cacheWrite,
+    output,
+    requests,
+    incomplete,
+    models: [...grouped.values()],
+    ...priced ? { costCny: cny.toFixed(8), costUsd: usd.toFixed(8) } : {},
+  }
+}
+
+/**
+ * The durable unit this feature registers. The fold is `entries/usage.js`; the
+ * wire view is its priced shape, so the browser half receives money, not rates.
+ */
+export const costProjection = {
+  key: 'polishCost',
+  stateVersion: 1,
+  stateSchema,
+  init: initialModelUsage,
+  apply: applyModelUsage,
+  wire: { viewSchema: pricedSessionSchema, view: state => priceModelUsage(state.view) },
+}
+
+/**
+ * Mount the host half of the cost surface.
+ * @param {object} ctx - the feature's own cordis context; its effects release the registration.
+ * @returns {Promise<void>} resolves once the projection is registered.
+ */
+export async function mountCost(ctx) {
+  const projections = ctx.get('sessionProjections')
+  if (projections === undefined) return
+  await projections.register(costProjection)
+}

package/entries/polish.js

@@ -0,0 +1,57 @@
+/**
+ * The `polish` row: every feature of the bundle behind one switch each.
+ *
+ * Mounting this row mounts the host half of each enabled feature. A feature that
+ * is switched off is disposed, not just ignored, so its listeners and routes go
+ * away — a switch that only hid behaviour would keep costing the app.
+ *
+ * @module dsh-aryacode-polish
+ */
+import z from '@deepseek-ai/schemastery'
+import { flag } from './config.js'
+import { configSchema, features } from './registry.js'
+
+/** The plugin name inside a composition. */
+export const name = 'aryacode-polish'
+
+/** No services are required; features that need one declare it in their own module. */
+export const inject = []
+
+export { features }
+
+/**
+ * The row's config: one volatile boolean per registered feature, derived from
+ * `entries/registry.js` so a new feature gains its switch automatically.
+ */
+export const Config = z.object(configSchema(z))
+
+/**
+ * Mount the enabled features and follow the switches at runtime.
+ *
+ * @param ctx - plugin context.
+ * @param config - the row config; every field is a volatile reference, not a value.
+ */
+export function apply(ctx, config = {}) {
+  /** @type {Map<string, { dispose: () => unknown }>} */
+  const mounted = new Map()
+
+  // The loader commits a volatile-only change into the live references and emits
+  // `loader/volatile-update` instead of re-running apply(), so the switches have
+  // to mount and dispose their feature in place — otherwise the page would claim
+  // a feature is on while nothing is running.
+  const sync = () => {
+    for (const feature of features) {
+      const wanted = flag(config[feature.id], feature.defaultOn ?? true)
+      const running = mounted.get(feature.id)
+      if (wanted && running === undefined) {
+        if (typeof feature.mount === 'function') mounted.set(feature.id, ctx.plugin(feature.mount))
+      } else if (!wanted && running !== undefined) {
+        void running.dispose()
+        mounted.delete(feature.id)
+      }
+    }
+  }
+
+  sync()
+  ctx.on('loader/volatile-update', sync)
+}

package/entries/registry.js

@@ -0,0 +1,73 @@
+/**
+ * The feature list — the one place a quality-of-life feature is declared.
+ *
+ * One entry is one feature, and one feature is one switch: the row's `Config`
+ * schema is derived from this array (see `configSchema`), so adding an entry
+ * here is what makes the switch appear in the Configure page. There is no second
+ * registration to forget.
+ *
+ * Entry shape:
+ *
+ *   {
+ *     id: 'spellcheck',            // the config field name and the switch name
+ *     label: 'Spelling corrections', // the words the Configure page shows
+ *     description: 'Right-click a misspelled word to pick a correction.',
+ *     defaultOn: true,             // the switch defaults to on
+ *     mount: spellcheck,           // optional host half, a Cordis plugin
+ *   }
+ *
+ * `mount` is the host half: a Cordis plugin object (or function) that this row
+ * plugs in when the switch is on and disposes when it is off. A feature with no
+ * host work omits `mount` and lives only in the client face.
+ *
+ * @module dsh-aryacode-polish-registry
+ */
+
+import { mountCost } from './cost.js'
+
+/**
+ * Every feature this bundle ships. Spelling corrections are investigated and
+ * documented in `docs/parked-spellcheck.md`; they are parked because a
+ * right-click correction menu needs a shell change no plugin can reach.
+ *
+ * @type {ReadonlyArray<{ id: string, label: string, description: string, defaultOn: boolean, mount?: unknown }>}
+ */
+export const features = [
+  {
+    id: 'sessionCost',
+    label: 'Estimated session cost',
+    description: 'Show what the open session has cost so far, priced from recorded usage at the published DeepSeek rates.',
+    defaultOn: true,
+    mount: mountCost,
+  },
+  {
+    id: 'accountBalance',
+    label: 'Account balance',
+    description: 'Show the remaining account balance in the sidebar foot, above the account row.',
+    defaultOn: true,
+  },
+]
+
+/**
+ * Derive the row's config shape from the feature list.
+ *
+ * Every field is boolean, defaults to the feature's own default, and is
+ * `.volatile()`: a volatile field is committed into the running fiber without a
+ * remount, so flipping a switch does not restart the plugin — `apply()` listens
+ * for `loader/volatile-update` and mounts or disposes the feature in place.
+ *
+ * @param z - the schemastery factory (`import z from '@deepseek-ai/schemastery'`).
+ * @param list - features to derive from; the real list unless a test passes one.
+ * @returns a schema shape: one field per feature.
+ */
+export function configSchema(z, list = features) {
+  const shape = {}
+  for (const feature of list) {
+    shape[feature.id] = z
+      .boolean()
+      .default(feature.defaultOn ?? true)
+      .volatile()
+      .description(feature.description)
+  }
+  return shape
+}

package/entries/usage.js

@@ -0,0 +1,265 @@
+/**
+ * Model-attributed provider usage, replayed from the durable session log.
+ *
+ * The Host keeps this fold so the browser half never has to read the event
+ * window itself: the projection's wire view carries everything the cost
+ * surface shows.
+ */
+
+/** The empty wire view handed to a session with no usage yet. */
+const EMPTY_VIEW = { models: [] }
+
+/** One empty token band. */
+function zero() {
+  return { uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 }
+}
+
+/**
+ * Beijing peak is weekdays 09:00-12:00 and 14:00-18:00; weekends are off-peak
+ * all day. DeepSeek bills peak hours at twice the off-peak rate.
+ * @param {number} time - event time in milliseconds.
+ * @returns {boolean} whether that instant is a billed peak instant.
+ */
+export function isBeijingPeak(time) {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone: 'Asia/Shanghai', weekday: 'short', hour: 'numeric', hourCycle: 'h23',
+  }).formatToParts(new Date(time))
+  const weekday = parts.find(part => part.type === 'weekday')?.value
+  const hour = Number(parts.find(part => part.type === 'hour')?.value)
+  if (weekday === 'Sat' || weekday === 'Sun' || !Number.isInteger(hour)) return false
+  return (hour >= 9 && hour < 12) || (hour >= 14 && hour < 18)
+}
+
+/** @returns {boolean} whether the value is a usable non-negative integer count. */
+function isCount(value) {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
+}
+
+/**
+ * @param {object} usage - provider-reported usage for one call.
+ * @returns {object | undefined} the four disjoint buckets, or undefined when the sample is unusable.
+ */
+function bucketsFrom(usage) {
+  if (!isCount(usage.inputTokens) || !isCount(usage.outputTokens)) return undefined
+  if (usage.cacheReadTokens !== undefined && !isCount(usage.cacheReadTokens)) return undefined
+  if (usage.cacheWriteTokens !== undefined && !isCount(usage.cacheWriteTokens)) return undefined
+  return {
+    uncachedInputTokens: usage.inputTokens,
+    outputTokens: usage.outputTokens,
+    cacheReadTokens: usage.cacheReadTokens ?? 0,
+    cacheWriteTokens: usage.cacheWriteTokens ?? 0,
+  }
+}
+
+/**
+ * @param {object} left - first band.
+ * @param {object} right - second band.
+ * @returns {boolean} whether the two bands hold the same four counts.
+ */
+function bucketsEqual(left, right) {
+  return left.uncachedInputTokens === right.uncachedInputTokens
+    && left.outputTokens === right.outputTokens
+    && left.cacheReadTokens === right.cacheReadTokens
+    && left.cacheWriteTokens === right.cacheWriteTokens
+}
+
+/**
+ * The last raw stream chunk of one type, scanning backwards.
+ * @param {readonly object[]} stream - compact records from one durable settlement.
+ * @param {string} type - chunk type that only appears as a raw record.
+ * @returns {object | undefined} the stream's final chunk of that type.
+ */
+function lastChunk(stream, type) {
+  if (!Array.isArray(stream)) return undefined
+  for (let index = stream.length - 1; index >= 0; index -= 1) {
+    const record = stream[index]
+    if (record?.type === 'chunk' && record.chunk?.type === type) return record.chunk
+  }
+  return undefined
+}
+
+/**
+ * @param {object} event - one durable session event.
+ * @returns {object | undefined} the provider usage reported by that event.
+ */
+function usageOf(event) {
+  if (event.type === 'assistant/message' && event.data?.usage !== undefined) return event.data.usage
+  if (event.type !== 'assistant/message' && event.type !== 'assistant/attempt') return undefined
+  return lastChunk(event.data?.stream, 'usage')?.usage
+}
+
+/**
+ * @param {object} route - provider and model.
+ * @param {number} hour - UTC hour bucket.
+ * @returns {string} the row key for one route in one hour.
+ */
+function routeKey(route, hour) {
+  return JSON.stringify([route.provider, route.model, hour])
+}
+
+/**
+ * @param {object} event - one durable session event.
+ * @param {object | null} pending - route carried over from the request header.
+ * @returns {object} the route that produced this sample.
+ */
+function routeOf(event, pending) {
+  if (event.type === 'assistant/message') {
+    const source = event.data?.message?.source
+    if (typeof source?.provider === 'string' && source.provider.length > 0
+      && typeof source?.model === 'string' && source.model.length > 0) {
+      return { provider: source.provider, model: source.model }
+    }
+  }
+  return pending ?? { provider: '', model: '' }
+}
+
+/**
+ * @param {object} event - one `request/header` event.
+ * @returns {object | undefined} the routed provider and model, when both are named.
+ */
+function headerRoute(event) {
+  const config = event.data?.header?.config
+  const provider = config?.provider
+  const model = config?.model
+  if (typeof provider !== 'string' || typeof model !== 'string') return undefined
+  if (provider.length === 0 || model.length === 0) return undefined
+  return { provider, model }
+}
+
+/**
+ * @param {object} row - one usage row.
+ * @returns {number} every bucket of both bands added up.
+ */
+function totalTokens(row) {
+  const bands = [row.peak, row.offPeak]
+  return bands.reduce((sum, band) => sum
+    + band.uncachedInputTokens + band.cacheReadTokens + band.cacheWriteTokens + band.outputTokens, 0)
+}
+
+/**
+ * @param {Record<string, object>} rows - usage rows by key.
+ * @returns {object} the wire view: the non-empty rows, heaviest first.
+ */
+function viewOf(rows) {
+  const models = Object.values(rows).filter(row => totalTokens(row) > 0).sort((left, right) => {
+    const delta = totalTokens(right) - totalTokens(left)
+    if (delta !== 0) return delta
+    if (left.model === right.model && left.provider === right.provider) return left.hour - right.hour
+    if (left.model === right.model) return left.provider < right.provider ? -1 : 1
+    return left.model < right.model ? -1 : 1
+  })
+  return models.length === 0 ? EMPTY_VIEW : { models }
+}
+
+/**
+ * @param {object} band - band to change.
+ * @param {object} delta - counts to add or remove.
+ * @param {1 | -1} sign - direction.
+ * @returns {object} the changed band.
+ */
+function addBand(band, delta, sign) {
+  return {
+    uncachedInputTokens: band.uncachedInputTokens + sign * delta.uncachedInputTokens,
+    outputTokens: band.outputTokens + sign * delta.outputTokens,
+    cacheReadTokens: band.cacheReadTokens + sign * delta.cacheReadTokens,
+    cacheWriteTokens: band.cacheWriteTokens + sign * delta.cacheWriteTokens,
+  }
+}
+
+/**
+ * Record one sample, replacing the sample this turn and step reported before.
+ * @param {object} state - previous fold.
+ * @param {object} route - provider and model that produced the sample.
+ * @param {boolean} peak - whether the sample fell in a billed peak hour.
+ * @param {object} buckets - the sample's four disjoint counts.
+ * @param {number} turn - turn index.
+ * @param {number} step - step index within the turn.
+ * @param {number} hour - UTC hour bucket.
+ * @returns {object} the updated fold.
+ */
+function withSample(state, route, peak, buckets, turn, step, hour) {
+  const key = routeKey(route, hour)
+  const previous = state.last !== null && state.last.turn === turn && state.last.step === step
+    ? state.last
+    : undefined
+  if (previous !== undefined
+    && previous.key === key
+    && previous.peak === peak
+    && bucketsEqual(previous.buckets, buckets)) return state
+
+  const rows = { ...state.rows }
+  const touch = (modelKey, bandPeak, delta, sign, requests) => {
+    const current = rows[modelKey] ?? {
+      provider: route.provider,
+      model: route.model,
+      hour,
+      requests: 0,
+      peak: zero(),
+      offPeak: zero(),
+    }
+    rows[modelKey] = {
+      ...current,
+      requests: current.requests + requests,
+      peak: bandPeak ? addBand(current.peak, delta, sign) : current.peak,
+      offPeak: bandPeak ? current.offPeak : addBand(current.offPeak, delta, sign),
+    }
+  }
+
+  if (previous === undefined) touch(key, peak, buckets, 1, 1)
+  else {
+    touch(previous.key, previous.peak, previous.buckets, -1, previous.key === key ? 0 : -1)
+    touch(key, peak, buckets, 1, previous.key === key ? 0 : 1)
+  }
+  return {
+    ...state,
+    rows,
+    last: { turn, step, key, peak, buckets },
+    view: viewOf(rows),
+  }
+}
+
+/**
+ * Fold one durable event.
+ * @param {object} state - previous fold.
+ * @param {object} event - next durable event.
+ * @returns {object} the updated fold.
+ */
+export function applyModelUsage(state, event) {
+  if (event.type === 'request/header') {
+    const route = headerRoute(event)
+    if (route === undefined) return { ...state, pending: null }
+    if (state.pending?.provider === route.provider && state.pending.model === route.model) return state
+    return { ...state, pending: route }
+  }
+  if (event.type === 'llm/retry-started') {
+    return state.last?.turn === event.data?.turn && state.last?.step === event.data?.step
+      ? { ...state, last: null }
+      : state
+  }
+  if (event.type !== 'assistant/message' && event.type !== 'assistant/attempt') return state
+  const sample = usageOf(event)
+  if (sample === undefined) return state
+  const buckets = bucketsFrom(sample)
+  if (buckets === undefined) return state
+  return withSample(
+    state, routeOf(event, state.pending), isBeijingPeak(event.time), buckets,
+    event.data?.turn ?? 0, event.data?.step ?? 0, Math.floor(event.time / 3_600_000),
+  )
+}
+
+/**
+ * @returns {object} an empty accumulator.
+ */
+export function initialModelUsage() {
+  return { rows: {}, pending: null, last: null, view: EMPTY_VIEW }
+}
+
+/**
+ * @param {readonly object[]} events - durable events in session order.
+ * @returns {object} usage grouped by provider, model, and hour.
+ */
+export function deriveModelUsage(events) {
+  let state = initialModelUsage()
+  for (const event of events) state = applyModelUsage(state, event)
+  return state.view
+}