@ljwei-stak/dsh-model-router 0.23.1 → 0.25.0

package/.dsh-plugin/shared/router-state.mjs

@@ -17,9 +17,13 @@ import { mkdir, open, readFile, rename, stat, unlink, writeFile } from 'node:fs/
 import { homedir } from 'node:os'
 import { dirname, isAbsolute, join, resolve } from 'node:path'
 import { archiveSpending, sanitizeArchivedSpending } from './run-ledger.mjs'
+import { sanitizeBudgetReservations } from './budget-reservations.mjs'
+import { archiveSubscriptionUsage, invalidArchivedSubscriptionUsage, invalidSubscriptionAttempts,
+  sanitizeArchivedSubscriptionUsage } from './subscription-usage.mjs'
 
 export const MAX_RUNS = 200
-const STATE_VERSION = 1
+// Older Hosts must refuse v3 instead of dropping the separate usage archive.
+const STATE_VERSION = 3
 
 /** Same DSH home rule as the Host: DSH_HOME (with ~ expansion) or ~/.dsh. */
 export function resolveStateHome(env = process.env, home = homedir(), cwd = process.cwd()) {
@@ -41,7 +45,10 @@ const LOCK_STALE_MS = 15_000
 const LOCK_TIMEOUT_MS = 10_000
 
 function emptyState() {
-  return { version: STATE_VERSION, historyIncomplete: false, onboarding: { completedAt: null }, health: null, quota: {}, authFailures: {}, runs: [], dynamicData: { liveBench: null, pricing: null, status: {}, revision: '' }, archivedSpending: sanitizeArchivedSpending(), notices: [], terminalSessions: [] }
+  return { version: STATE_VERSION, historyIncomplete: false, subscriptionUsageIncomplete: false,
+    onboarding: { completedAt: null }, health: null, quota: {}, authFailures: {}, runs: [], budgetReservations: {},
+    dynamicData: { liveBench: null, pricing: null, status: {}, revision: '' }, archivedSpending: sanitizeArchivedSpending(),
+    archivedSubscriptionUsage: sanitizeArchivedSubscriptionUsage(), notices: [], terminalSessions: [] }
 }
 
 function sanitizeNotices(value) {
@@ -51,9 +58,17 @@ function sanitizeNotices(value) {
 }
 
 function retainRuns(state, maxRuns) {
-  const removed = Math.max(0, state.runs.length - maxRuns)
-  state.archivedSpending = archiveSpending(state.runs.slice(0, removed), state.archivedSpending)
-  state.runs = state.runs.slice(removed)
+  // A partial run must stay addressable until its hold is reconciled. Archiving
+  // it and later upserting a checkpoint would count its receipts twice.
+  const protectedIds = new Set(Object.values(state.budgetReservations ?? {}).map(entry => entry.runId))
+  let remove = Math.max(0, state.runs.length - Math.max(maxRuns, protectedIds.size))
+  const evicted = []
+  state.runs = state.runs.filter(run => {
+    if (remove > 0 && !protectedIds.has(run.id)) { remove -= 1; evicted.push(run); return false }
+    return true
+  })
+  state.archivedSpending = archiveSpending(evicted, state.archivedSpending)
+  state.archivedSubscriptionUsage = archiveSubscriptionUsage(evicted, state.archivedSubscriptionUsage)
   return state
 }
 
@@ -94,28 +109,38 @@ function invalidRunSpending(run) {
 }
 
 function sanitize(value, maxRuns) {
-  if (!value || typeof value !== 'object' || Array.isArray(value) || value.version !== STATE_VERSION
+  if (!value || typeof value !== 'object' || Array.isArray(value) || ![1, 2, STATE_VERSION].includes(value.version)
     || !Array.isArray(value.runs)) {
     const error = new Error('模型路由状态版本或结构不受支持；原文件未修改，请先恢复或升级兼容版本。')
     error.code = 'ROUTER_STATE_UNSUPPORTED'
     throw error
   }
   const runs = value.runs.filter(run => run && typeof run.id === 'string')
+  const held = sanitizeBudgetReservations(value.budgetReservations)
   return retainRuns({
     version: STATE_VERSION,
     // Unlike bounded notices, an incomplete-history marker cannot silently
     // expire. Restoring a verified state file is required to recover budgets.
     historyIncomplete: value.historyIncomplete === true || runs.length !== value.runs.length
-      || invalidArchivedSpending(value.archivedSpending) || runs.some(invalidRunSpending)
+      || invalidArchivedSpending(value.archivedSpending) || runs.some(invalidRunSpending) || held.invalid
+      || Object.values(held.reservations).some(entry => !runs.some(run => run.id === entry.runId))
       || sanitizeNotices(value.notices).some(notice => notice.kind === 'state-corrupt'),
+    subscriptionUsageIncomplete: value.subscriptionUsageIncomplete === true
+      || invalidArchivedSubscriptionUsage(value.archivedSubscriptionUsage)
+      || runs.some(run => invalidArchivedSubscriptionUsage(run.priorAttemptSubscriptionUsage)
+        || [...(Array.isArray(run.packages) ? run.packages : []), ...(Array.isArray(run.reviews) ? run.reviews : [])]
+          .some(item => invalidSubscriptionAttempts(item?.subscriptionAttempts))),
     onboarding: { completedAt: Number.isFinite(value.onboarding?.completedAt) ? value.onboarding.completedAt : null },
     health: value.health && Array.isArray(value.health.tools) ? value.health : null,
     quota: value.quota && typeof value.quota === 'object' && !Array.isArray(value.quota) ? value.quota : {},
     authFailures: Object.fromEntries(Object.entries(value.authFailures && typeof value.authFailures === 'object' && !Array.isArray(value.authFailures) ? value.authFailures : {})
       .filter(([, entry]) => Number.isFinite(entry?.at))),
     runs,
+    budgetReservations: held.reservations,
     dynamicData: value.dynamicData && typeof value.dynamicData === 'object' && !Array.isArray(value.dynamicData) ? value.dynamicData : { liveBench: null, pricing: null, status: {}, revision: '' },
     archivedSpending: sanitizeArchivedSpending(value.archivedSpending),
+    archivedSubscriptionUsage: sanitizeArchivedSubscriptionUsage(value.archivedSubscriptionUsage,
+      { legacySpending: value.archivedSpending }),
     notices: sanitizeNotices(value.notices),
     terminalSessions: sanitizeTerminalSessions(value.terminalSessions),
   }, maxRuns)
@@ -172,7 +197,10 @@ async function acquireLock(lockFile, { staleMs = LOCK_STALE_MS, timeoutMs = LOCK
         if (await readFile(lockFile, 'utf8').catch(() => null) === owner) await unlink(lockFile).catch(() => {})
       }
     } catch (error) {
-      if (error?.code !== 'EEXIST') throw error
+      // Windows can report a sharing/delete-pending race as EPERM while
+      // another owner closes and removes its lock. Retry within the same
+      // bounded wait; never treat this as permission to remove a live lock.
+      if (error?.code !== 'EEXIST' && !(process.platform === 'win32' && error?.code === 'EPERM')) throw error
       const info = await stat(lockFile).catch(() => null)
       const owner = await readFile(lockFile, 'utf8').catch(() => null)
       if (info && owner !== null && now() - info.mtimeMs > staleMs && ownerIsDead(ownerPid(owner))) {

package/.dsh-plugin/shared/run-ledger.mjs

@@ -6,6 +6,7 @@
 
 import { reasoningExecutionFields, unsupportedCliReasoning } from './reasoning-execution.mjs'
 import { packageSelectionFields } from './package-assignments.mjs'
+import { archiveSubscriptionUsage, sanitizeArchivedSubscriptionUsage, sanitizeSubscriptionAttempts } from './subscription-usage.mjs'
 
 export const MAX_STORED_ANSWER = 4_000
 export const MAX_STORED_TASK = 20_000
@@ -13,6 +14,7 @@ export const MAX_STORED_TASK = 20_000
 export const MAX_QUALITY_BIAS = 0.04
 
 const finite = value => typeof value === 'number' && Number.isFinite(value)
+const receiptTimestamp = value => finite(value) && value >= 0 && Number.isFinite(new Date(value).getTime())
 const nonEmptyText = value => (typeof value === 'string' && value.length > 0 ? value : null)
 const routeKey = (provider, model) => `${String(provider ?? '')}\u0000${String(model ?? '')}`
 
@@ -127,7 +129,7 @@ export function actualCost(result, pricing) {
 export function billingOf(result, { loginBilling = null, apiKeyPresent = false } = {}) {
   if (!result || result.blocked) return null
   // The subscription-first executor states the channel it billed explicitly.
-  if (result.billing === 'api' || result.billing === 'subscription') return result.billing
+  if (result.billing === 'api' || result.billing === 'subscription' || result.billing === 'unknown') return result.billing
   if (result.channel !== 'official-cli') return 'api'
   if (result.credentialSource === 'configured-api-key' || result.credentialSource === 'process-environment') return 'api'
   if (!result.credentialSource && apiKeyPresent) return 'api'
@@ -136,6 +138,7 @@ export function billingOf(result, { loginBilling = null, apiKeyPresent = false }
 
 /** Cost fields for storage: subscription runs keep the figure as `referenceCostUsd` only. */
 export function billedCost(result, pricing, billing) {
+  if (billing === 'unknown') return { costUsd: null, costSource: 'billing-unknown', billing, referenceCostUsd: null }
   const cost = actualCost(result, pricing)
   if (billing !== 'subscription') return { ...cost, billing: billing ?? 'api', referenceCostUsd: null }
   return { costUsd: null, costSource: cost.costSource, billing, referenceCostUsd: cost.costUsd }
@@ -372,6 +375,7 @@ function storedPackage(planned, result, pricing, finishedAt, billingFor = billin
     ...(result?.billingMode ? { billingMode: String(result.billingMode) } : {}),
     ...(result?.billingSwitch ? { billingSwitch: { ...result.billingSwitch } } : {}),
     ...(result?.subscriptionRoute ? { subscriptionRoute: { provider: String(result.subscriptionRoute.provider ?? ''), model: String(result.subscriptionRoute.model ?? '') } } : {}),
+    ...(result?.subscriptionAttempts !== undefined ? { subscriptionAttempts: sanitizeSubscriptionAttempts(result.subscriptionAttempts) } : {}),
     error: result?.ok ? null : (result?.error ?? null),
     ...(!result?.ok && result?.diagnostic ? { diagnostic: String(result.diagnostic).slice(0, 2_000) } : {}),
     ...(Number.isInteger(result?.exitCode) ? { exitCode: result.exitCode } : {}),
@@ -382,7 +386,7 @@ function storedPackage(planned, result, pricing, finishedAt, billingFor = billin
     // silently rewrite historical spend calculated from usage.
     pricingSnapshot: pricing ? { ...pricing } : null,
     ...cost,
-    finishedAt,
+    finishedAt: receiptTimestamp(result?.finishedAt) ? result.finishedAt : finishedAt,
     review: planned.review ?? null,
     rating: planned.rating ?? null,
   }
@@ -442,6 +446,8 @@ export function mergeRerun(run, execution, { rerunIds = [], pricingFor = () => n
   // Retrying replaces the visible result, but earlier attempts still incurred
   // charges (or unknown usage). Keep their calendar totals before replacement.
   const replaced = run.packages.filter(stored => retried.has(stored.id) && results.some(item => item.id === stored.id))
+  run.priorAttemptSubscriptionUsage = archiveSubscriptionUsage([{ createdAt: run.createdAt, packages: replaced }],
+    sanitizeArchivedSubscriptionUsage(run.priorAttemptSubscriptionUsage, { legacySpending: run.priorAttemptSpending }))
   run.priorAttemptSpending = archiveSpending([{ createdAt: run.createdAt, packages: replaced }], run.priorAttemptSpending)
   run.packages = run.packages.map(stored => {
     const result = results.find(item => item.id === stored.id)
@@ -459,6 +465,7 @@ export function storedResults(run) {
     id: item.id, name: item.name, ok: item.ok, provider: item.provider, model: item.model,
     channel: item.channel, answer: item.answer, error: item.error, fallback: item.fallback,
     blocked: item.blocked, finishedAt: item.finishedAt,
+    ...(item.subscriptionAttempts !== undefined ? { subscriptionAttempts: sanitizeSubscriptionAttempts(item.subscriptionAttempts) } : {}),
     ...packageSelectionFields(item),
     ...reasoningExecutionFields(item),
     ...(finite(item.durationMs) && item.durationMs >= 0 ? { durationMs: item.durationMs } : {}),
@@ -482,12 +489,17 @@ export function teamExecutionResults(plan, execution) {
     id: result.id,
     ok: result.status === 'succeeded',
     cancelled: result.status === 'cancelled',
+    ...(result.notStarted === true || result.status === 'unsupported' ? { notStarted: true } : {}),
+    ...(result.blocked === true ? { blocked: true } : {}),
+    ...(result.billing === 'api' || result.billing === 'subscription' || result.billing === 'unknown' ? { billing: result.billing } : {}),
+    ...(typeof result.credentialSource === 'string' ? { credentialSource: result.credentialSource } : {}),
     provider: result.provider,
     model: result.recommendedModel,
     ...unsupportedCliReasoning({ reasoningEffort: result.recommendedReasoningEffort }),
     ...reasoningExecutionFields(result),
     ...(finite(result.durationMs) && result.durationMs >= 0 ? { durationMs: result.durationMs } : {}),
     ...(finite(result.inputChars) && result.inputChars >= 0 ? { inputChars: result.inputChars } : {}),
+    ...(receiptTimestamp(result.finishedAt) ? { finishedAt: result.finishedAt } : {}),
     requestedCliModel: result.requestedCliModel ?? null,
     actualModel: result.actualModel ?? null,
     ...(result.reportedModel !== undefined ? { reportedModel: result.reportedModel } : {}),
@@ -495,6 +507,7 @@ export function teamExecutionResults(plan, execution) {
     ...(typeof result.source === 'string' ? { source: result.source } : {}),
     ...(typeof result.sandboxEnforcement === 'string' ? { sandboxEnforcement: result.sandboxEnforcement } : {}),
     ...(result.usageIncomplete === true ? { usageIncomplete: true } : {}),
+    ...(result.subscriptionAttempts !== undefined ? { subscriptionAttempts: sanitizeSubscriptionAttempts(result.subscriptionAttempts) } : {}),
     ...(typeof result.executionEnvironment === 'string' ? { executionEnvironment: result.executionEnvironment } : {}),
     channel: 'official-cli',
     toolId: result.toolId ?? null,
@@ -541,6 +554,10 @@ export function buildToolRunRecord({ toolId, toolLabel, provider, model, cliMode
     status: result?.status ?? 'pending',
     packages: [{
       id: packageId, ok: succeeded, cancelled: result?.status === 'cancelled',
+      ...(result?.notStarted === true || result?.status === 'unsupported' ? { notStarted: true } : {}),
+      ...(result?.blocked === true ? { blocked: true } : {}),
+      ...(result?.billing === 'api' || result?.billing === 'subscription' || result?.billing === 'unknown' ? { billing: result.billing } : {}),
+      ...(typeof result?.credentialSource === 'string' ? { credentialSource: result.credentialSource } : {}),
       provider: plan.directRoute.provider, model: plan.directRoute.model,
       channel: 'official-cli', toolId,
       requestedCliModel: Object.hasOwn(result ?? {}, 'requestedModel') ? result.requestedModel : cliModel,
@@ -550,6 +567,8 @@ export function buildToolRunRecord({ toolId, toolLabel, provider, model, cliMode
       ...(typeof result?.source === 'string' ? { source: result.source } : {}),
       ...(typeof result?.sandboxEnforcement === 'string' ? { sandboxEnforcement: result.sandboxEnforcement } : {}),
       ...(result?.usageIncomplete === true ? { usageIncomplete: true } : {}),
+      ...(result?.subscriptionAttempts !== undefined ? { subscriptionAttempts: sanitizeSubscriptionAttempts(result.subscriptionAttempts) } : {}),
+      ...(receiptTimestamp(result?.finishedAt) ? { finishedAt: result.finishedAt } : {}),
       answer: String(result?.finalText ?? ''),
       error: succeeded ? null : String(result?.error ?? result?.reason ?? result?.status ?? '官方 CLI 未成功完成。'),
       ...(!succeeded && typeof result?.diagnostic === 'string' && result.diagnostic.trim()

package/.dsh-plugin/shared/subscription-usage.mjs

@@ -0,0 +1,210 @@
+/** Subscription quantities are evidence of use, never API dollars or remaining quota. */
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+const counter = value => Number.isSafeInteger(value) && value >= 0
+const timestamp = value => typeof value === 'number' && Number.isFinite(value) && value >= 0 && Number.isFinite(new Date(value).getTime())
+const clean = value => typeof value === 'string' && value.length <= 512 && !/[\u0000-\u001f\u007f]/u.test(value) ? value : null
+const TOKENS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens']
+const COUNTS = ['calls', 'knownUsageCalls', 'unknownUsageCalls']
+const pad = value => String(value).padStart(2, '0')
+const dayKey = at => { const d = new Date(at); return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}` }
+const monthKey = at => { const d = new Date(at); return `${d.getFullYear()}-${pad(d.getMonth() + 1)}` }
+const DAYS = /^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$/u
+const MONTHS = /^\d{4}-(?:0[1-9]|1[0-2])$/u
+export const MAX_SUBSCRIPTION_USAGE_ROUTES = 256
+
+export const emptySubscriptionUsage = () => ({ calls: 0, knownUsageCalls: 0, unknownUsageCalls: 0,
+  inputTokens: null, outputTokens: null, cacheReadTokens: null, cacheWriteTokens: null })
+const period = value => ({ ...Object.fromEntries(COUNTS.map(field => [field, counter(value?.[field]) ? value[field] : 0])),
+  ...Object.fromEntries(TOKENS.map(field => [field, counter(value?.[field]) ? value[field] : null])) })
+const identity = value => ({ provider: clean(value?.provider) || '未知供应商', toolId: clean(value?.toolId), model: clean(value?.model) })
+const keyOf = value => JSON.stringify([value.provider, value.toolId, value.model])
+const emptyBucket = () => ({ total: emptySubscriptionUsage(), byRoute: {} })
+const overflowRoute = { provider: '其他（已合并）', toolId: null, model: null }
+
+function addPeriod(target, source) {
+  for (const field of COUNTS) target[field] += source[field]
+  for (const field of TOKENS) {
+    if (source[field] === null) continue
+    const total = (target[field] ?? 0) + source[field]
+    // A quantity that cannot be represented exactly is not a reported zero.
+    target[field] = counter(total) ? total : null
+  }
+  return target
+}
+
+function addRoute(bucket, route, value) {
+  let id = keyOf(route)
+  if (!Object.hasOwn(bucket.byRoute, id) && Object.keys(bucket.byRoute).length >= MAX_SUBSCRIPTION_USAGE_ROUTES - 1) {
+    route = overflowRoute; id = keyOf(route)
+  }
+  const row = bucket.byRoute[id] ??= { ...route, usage: emptySubscriptionUsage() }
+  addPeriod(row.usage, value)
+}
+
+function addBucket(target, source) {
+  addPeriod(target.total, source.total)
+  for (const row of Object.values(source.byRoute)) addRoute(target, identity(row), row.usage)
+}
+
+/** Legacy calendar records kept counts, but discarded every token quantity. */
+function legacyArchive(spending) {
+  const result = { days: {}, months: {} }
+  for (const [kind, pattern] of [['days', DAYS], ['months', MONTHS]]) {
+    for (const [key, value] of Object.entries(record(spending?.[kind]) ? spending[kind] : {})) {
+      if (!pattern.test(key) || !counter(value?.subscriptionRuns) || value.subscriptionRuns === 0) continue
+      const usage = { ...emptySubscriptionUsage(), calls: value.subscriptionRuns, unknownUsageCalls: value.subscriptionRuns }
+      const bucket = result[kind][key] = { total: usage, byRoute: {} }
+      addRoute(bucket, { provider: '历史订阅（用量未保存）', toolId: null, model: null }, usage)
+    }
+  }
+  return result
+}
+
+/** Bounded quantities and route identifiers only; no answers, prompts, prices or credentials. */
+export function sanitizeArchivedSubscriptionUsage(value, { legacySpending } = {}) {
+  if (value === undefined || value === null) value = legacyArchive(legacySpending)
+  const result = { days: {}, months: {} }
+  for (const [kind, pattern, limit] of [['days', DAYS, 90], ['months', MONTHS, 24]]) {
+    const entries = Object.entries(record(value?.[kind]) ? value[kind] : {}).filter(([key, bucket]) => pattern.test(key) && record(bucket))
+      .sort(([a], [b]) => a.localeCompare(b)).slice(-limit)
+    for (const [key, bucket] of entries) {
+      const next = result[kind][key] = { total: period(bucket.total), byRoute: {} }
+      for (const row of Object.values(record(bucket.byRoute) ? bucket.byRoute : {})) {
+        if (!record(row)) continue
+        addRoute(next, identity(row), period(row.usage))
+      }
+    }
+  }
+  return result
+}
+
+export function invalidArchivedSubscriptionUsage(value) {
+  if (value === undefined) return false
+  if (!record(value)) return true
+  const invalidPeriod = value => !record(value)
+    || COUNTS.some(field => !counter(value[field]))
+    || TOKENS.some(field => value[field] !== null && !counter(value[field]))
+    || value.knownUsageCalls + value.unknownUsageCalls !== value.calls
+  for (const [kind, pattern] of [['days', DAYS], ['months', MONTHS]]) {
+    if (!record(value[kind])) return true
+    for (const [key, bucket] of Object.entries(value[kind])) {
+      if (!pattern.test(key) || !record(bucket) || invalidPeriod(bucket.total) || !record(bucket.byRoute)) return true
+      for (const row of Object.values(bucket.byRoute)) {
+        if (!record(row) || !clean(row.provider) || (row.toolId !== null && !clean(row.toolId))
+          || (row.model !== null && !clean(row.model)) || invalidPeriod(row.usage)) return true
+      }
+    }
+  }
+  return false
+}
+
+/** Only these fields from a subscription receipt can enter the durable ledger. */
+export function sanitizeSubscriptionAttempts(value) {
+  if (value === undefined) return undefined
+  if (!Array.isArray(value)) return [{ usage: null, usageIncomplete: true, unknownEvidence: true }]
+  const attempts = value.slice(0, 16).map(item => {
+    if (!record(item)) return { usage: null, usageIncomplete: true, unknownEvidence: true }
+    return { ...Object.fromEntries(['provider', 'toolId', 'model'].filter(field => Object.hasOwn(item, field))
+      .map(field => [field, clean(item[field])])),
+    usage: record(item.usage)
+      ? Object.fromEntries(TOKENS.filter(field => Object.hasOwn(item.usage, field)).map(field => [field,
+        counter(item.usage[field]) ? item.usage[field] : null])) : null,
+    ...(item.ran === false ? { ran: false } : {}), ...(item.notStarted === true ? { notStarted: true } : {}),
+    ...(item.blocked === true ? { blocked: true } : {}),
+    ...(item.usageIncomplete === true || record(item.usage) && TOKENS.some(field => item.usage[field] !== undefined
+      && item.usage[field] !== null && !counter(item.usage[field])) ? { usageIncomplete: true } : {}),
+    ...(timestamp(item.finishedAt) ? { finishedAt: item.finishedAt } : {}),
+    ...(item.unknownEvidence === true ? { unknownEvidence: true } : {}) }
+  })
+  if (value.length > 16) attempts.push({ usage: null, usageIncomplete: true, unknownEvidence: true })
+  return attempts
+}
+
+export function invalidSubscriptionAttempts(value) {
+  if (value === undefined) return false
+  return !Array.isArray(value) || value.length > 16 || value.some(item => !record(item) || item.unknownEvidence === true
+    || (item.usage !== undefined && item.usage !== null && (!record(item.usage)
+      || TOKENS.some(field => item.usage[field] !== undefined && item.usage[field] !== null && !counter(item.usage[field])))))
+}
+
+function began(item) {
+  const contradictory = record(item.usage) && TOKENS.some(field => item.usage[field] !== undefined
+    && item.usage[field] !== null && item.usage[field] !== 0)
+  return contradictory || !(item.ran === false || item.notStarted === true || item.blocked === true)
+}
+
+function* packageEntries(item, fallbackAt) {
+  if (!record(item)) return
+  // An explicit vector is authoritative: an API result can still include its
+  // earlier subscription attempt; [] means no subscription was attempted.
+  const attempts = Object.hasOwn(item, 'subscriptionAttempts') ? sanitizeSubscriptionAttempts(item.subscriptionAttempts)
+    : item.billing === 'subscription' && item.ran === true ? [item] : []
+  for (const attempt of attempts) {
+    if (!began(attempt)) continue
+    const usage = record(attempt.usage) ? attempt.usage : null
+    const complete = attempt.usageIncomplete !== true && attempt.unknownEvidence !== true
+      && counter(usage?.inputTokens) && counter(usage?.outputTokens)
+      && TOKENS.every(field => usage[field] === undefined || usage[field] === null || counter(usage[field]))
+    const value = { ...emptySubscriptionUsage(), calls: 1, knownUsageCalls: complete ? 1 : 0, unknownUsageCalls: complete ? 0 : 1 }
+    for (const field of TOKENS) if (counter(usage?.[field])) value[field] = usage[field]
+    const when = timestamp(attempt.finishedAt) ? attempt.finishedAt : timestamp(item.finishedAt) ? item.finishedAt : fallbackAt
+    yield { when, route: identity(Object.fromEntries(['provider', 'toolId', 'model'].map(field => [field,
+      Object.hasOwn(attempt, field) ? attempt[field] : item[field]]))), usage: value }
+  }
+}
+
+function* usageEntries(runs) {
+  for (const run of Array.isArray(runs) ? runs : []) {
+    for (const item of [...(Array.isArray(run?.packages) ? run.packages : []), ...(Array.isArray(run?.reviews) ? run.reviews : [])]) {
+      yield* packageEntries(item, run?.createdAt)
+    }
+  }
+}
+
+function addArchive(target, source) {
+  for (const kind of ['days', 'months']) {
+    for (const [key, bucket] of Object.entries(source[kind])) addBucket(target[kind][key] ??= emptyBucket(), bucket)
+  }
+}
+
+function priorArchive(run) {
+  return sanitizeArchivedSubscriptionUsage(run?.priorAttemptSubscriptionUsage, { legacySpending: run?.priorAttemptSpending })
+}
+
+/** Fold only evicted/replaced records. Retained records remain live. */
+export function archiveSubscriptionUsage(runs, archived) {
+  const result = sanitizeArchivedSubscriptionUsage(archived)
+  for (const run of Array.isArray(runs) ? runs : []) addArchive(result, priorArchive(run))
+  for (const { when, route, usage } of usageEntries(runs)) {
+    if (!timestamp(when)) continue
+    for (const [kind, key] of [['days', dayKey(when)], ['months', monthKey(when)]]) {
+      const bucket = result[kind][key] ??= emptyBucket()
+      addPeriod(bucket.total, usage); addRoute(bucket, route, usage)
+    }
+  }
+  return sanitizeArchivedSubscriptionUsage(result)
+}
+
+/** Known quantities only. Missing usage remains explicit instead of becoming zero. */
+export function subscriptionUsage(runs, at = Date.now(), archived = null) {
+  const all = archiveSubscriptionUsage(runs, archived)
+  const daily = all.days[dayKey(at)] ?? emptyBucket(), monthly = all.months[monthKey(at)] ?? emptyBucket()
+  const keys = new Set([...Object.keys(daily.byRoute), ...Object.keys(monthly.byRoute)])
+  return { today: period(daily.total), month: period(monthly.total),
+    byRoute: [...keys].map(key => ({ ...identity(monthly.byRoute[key] ?? daily.byRoute[key]),
+      today: period(daily.byRoute[key]?.usage), month: period(monthly.byRoute[key]?.usage) })) }
+}
+
+export function subscriptionUsageForPackage(item) {
+  const result = emptySubscriptionUsage()
+  for (const { usage } of packageEntries(item)) addPeriod(result, usage)
+  return result
+}
+
+/** Includes prior retry attempts, without summing both daily and monthly copies. */
+export function subscriptionUsageForRun(run) {
+  const result = emptySubscriptionUsage()
+  for (const bucket of Object.values(priorArchive(run).months)) addPeriod(result, bucket.total)
+  for (const { usage } of usageEntries([run])) addPeriod(result, usage)
+  return result
+}