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

package/.dsh-plugin/shared/execution-accounting.mjs

@@ -0,0 +1,61 @@
+/** API money and subscription quantities are separate dimensions. */
+import { plannedPackages } from './run-ledger.mjs'
+import { billingPlan } from './subscription-billing.mjs'
+import { toolForProvider } from './official-tool-registry.mjs'
+import { estimateAssignedPackage } from './router.mjs'
+
+export function initialFunding(route, { billing = null, officialCli = false, toolId = null,
+  loginBillingFor = () => 'unknown', apiKeyFor = () => false, forceApi = false, executionChannel = null } = {}) {
+  const id = toolId ?? toolForProvider(route?.provider)?.id
+  if (forceApi) return { billing: 'api', route }
+  if (officialCli) return { billing: !apiKeyFor(id) && loginBillingFor(id) === 'subscription' ? 'subscription' : 'api', route }
+  if (!billing) return { billing: 'api', route }
+  const policy = billingPlan(route, billing.routes ?? [])
+  if (policy.mode === 'subscription-only') return { billing: 'subscription', route }
+  if (policy.mode === 'api-only' || billing.choice === 'api') return { billing: 'api', route: policy.apiRoute ?? route }
+  const sub = policy.subscription
+  if (!sub) return { billing: 'api', route }
+  if (billing.quota?.status?.(sub.key)) return { billing: 'api', route: policy.apiRoute ?? route }
+  if (sub.kind === 'plan-key') return { billing: 'subscription', route }
+  if (billing.choice === 'subscription') return { billing: 'subscription', route }
+  const login = billing.loginBillingFor?.(sub.toolId) ?? loginBillingFor(sub.toolId)
+  return { billing: route?.execution === 'api' || executionChannel === 'harness-llm'
+    || login !== 'subscription' ? 'api' : 'subscription', route }
+}
+
+export function attachPlanAccounting(plan, task, routes = [], context = {}) {
+  const entries = plannedPackages(plan, task).map((item, index) => {
+    const selected = item.manualAssignment?.kind === 'api' ? item.manualAssignment
+      : { provider: item.recommendedProvider, model: item.recommendedModel }
+    const route = routes.find(route => route.provider === selected.provider && route.model === selected.model) ?? selected
+    const funding = initialFunding(route, { ...context, executionChannel: item.executionChannel ?? plan.executionChannel,
+      ...(context.billingChoices?.[item.id] && context.billing ? { billing: { ...context.billing, choice: context.billingChoices[item.id] } } : {}),
+      ...(item.manualAssignment?.kind === 'api' ? { forceApi: true } : {}),
+      ...(item.manualAssignment?.kind === 'tool' ? { officialCli: true, toolId: item.manualAssignment.toolId } : {}) })
+    const resource = plan.costBreakdown?.[index] ?? estimateAssignedPackage(route, item, task, plan.complexity?.band ?? 'balanced')
+    const changed = funding.route?.provider !== route.provider || funding.route?.model !== route.model
+    const estimate = changed || plan.subscriptionPricedRoutes?.includes(`${route.provider}/${route.model}`)
+      ? estimateAssignedPackage(funding.route, item, task, plan.complexity?.band ?? 'balanced').estimatedCost
+      : item.estimatedCost ?? null
+    return { id: item.id, billing: funding.billing,
+      apiEstimatedCostUsd: funding.billing === 'subscription' ? 0 : estimate,
+      estimatedUsage: { inputTokens: resource.inputTokens ?? null, outputTokens: resource.outputTokens ?? null } }
+  })
+  const api = entries.filter(item => item.billing === 'api')
+  plan.accounting = { packages: entries, apiExposure: api.length > 0,
+    apiEstimatedCostUsd: api.some(item => !Number.isFinite(item.apiEstimatedCostUsd)) ? null
+      : api.reduce((sum, item) => sum + item.apiEstimatedCostUsd, 0) }
+  return plan.accounting
+}
+
+export const accountingEstimates = plan => plan.accounting.packages.map(item => ({ id: item.id,
+  billing: item.billing, estimatedCostUsd: item.apiEstimatedCostUsd }))
+
+/** Zero marginal API expense for subscription routes; never rewrite real prices. */
+export function planningFundingPrices(routes, context, channelForRoute = () => null) {
+  const subscriptionPricedRoutes = routes.filter(route => initialFunding(route, {
+    ...context, executionChannel: channelForRoute(route),
+  }).billing === 'subscription').map(route => `${route.provider}/${route.model}`)
+  return { subscriptionPricedRoutes, pricing: Object.fromEntries(subscriptionPricedRoutes.map(key => [key,
+    { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }])) }
+}

package/.dsh-plugin/shared/execution-lifecycle.mjs

@@ -10,7 +10,7 @@ export async function beginExecutionLifecycle({ state, buildRun, packageEstimate
   const manager = createBudgetReservations({ state })
   await manager.recoverInterruptedExecutions()
   const started = new Map(), results = new Map(), completed = new Set()
-  const estimates = new Map(packageEstimates.map(item => [item.id, item.estimatedCostUsd ?? item.estimatedCost ?? null]))
+  const estimates = new Map(packageEstimates.map(item => [item.id, { estimatedCostUsd: item.estimatedCostUsd ?? item.estimatedCost ?? null, billing: item.billing ?? 'api' }]))
   let workspace = {}, poisoned = null, closed = false
   const current = (status = 'running') => {
     const receipts = [...started].map(([id, item]) => results.get(id) ?? {
@@ -24,6 +24,7 @@ export async function beginExecutionLifecycle({ state, buildRun, packageEstimate
       for (const item of run.packages ?? []) {
         if (!started.has(item.id) || completed.has(item.id)) continue
         item.status = 'running'; item.inFlight = true
+        if (!results.has(item.id) || results.get(item.id)?.notStarted) item.billing = estimates.get(item.id)?.billing ?? 'api'
         if (!results.has(item.id)) Object.assign(item, { ran: false, costUsd: null, costSource: 'pending-receipt' })
       }
     }
@@ -65,6 +66,7 @@ export async function beginExecutionLifecycle({ state, buildRun, packageEstimate
     id: initial.id,
     current,
     results: () => [...results.values()],
+    reservationFor: id => estimates.get(id),
     activePackageId: () => [...started.keys()].findLast(id => !completed.has(id)),
     async onCheckpointStart(item) {
       const previous = started.get(item.id)
@@ -117,9 +119,9 @@ export async function beginExecutionLifecycle({ state, buildRun, packageEstimate
     },
     async reserveExtra(id, estimatedCostUsd, { confirmOverBudget: extraConfirmation = false } = {}) {
       return required(async () => {
-        const next = new Map(estimates); next.set(id, estimatedCostUsd)
+        const next = new Map(estimates); next.set(id, { estimatedCostUsd, billing: 'api' })
         const changed = await manager.resizeExecution({ ...identity,
-          packageEstimates: [...next].filter(([key]) => !completed.has(key)).map(([key, value]) => ({ id: key, estimatedCostUsd: value })),
+          packageEstimates: [...next].filter(([key]) => !completed.has(key)).map(([key, value]) => ({ id: key, ...value })),
           ...settings, confirmOverBudget: extraConfirmation === true })
         if (changed.accepted) { estimates.clear(); for (const [key, value] of next) estimates.set(key, value) }
         return changed

package/.dsh-plugin/shared/official-team-runtime.mjs

@@ -515,6 +515,11 @@ export async function runOfficialTeam({ plan, task, workspace, allowedRoot, mode
       actualModel: reportedModel,
       ...(result.reportedModel !== undefined ? { reportedModel: result.reportedModel } : {}),
       ...(result.usageIncomplete === true ? { usageIncomplete: true } : {}),
+      ...(result.notStarted === true || result.status === 'unsupported' ? { notStarted: true } : {}),
+      ...(result.blocked === true ? { blocked: true } : {}),
+      ...(['api', 'subscription'].includes(result.billing) ? { billing: result.billing } : {}),
+      ...(['configured-api-key', 'process-environment', 'cli-session'].includes(result.credentialSource)
+        ? { credentialSource: result.credentialSource } : {}),
       ...(typeof result.source === 'string' ? { source: result.source } : {}),
       ...(typeof result.sandboxEnforcement === 'string' ? { sandboxEnforcement: result.sandboxEnforcement } : {}),
       executionEnvironment,

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

@@ -18,10 +18,12 @@ 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
-// Older Hosts must refuse v2 instead of dropping durable execution holds.
-const STATE_VERSION = 2
+// 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()) {
@@ -43,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: [], budgetReservations: {}, 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) {
@@ -63,6 +68,7 @@ function retainRuns(state, maxRuns) {
     return true
   })
   state.archivedSpending = archiveSpending(evicted, state.archivedSpending)
+  state.archivedSubscriptionUsage = archiveSubscriptionUsage(evicted, state.archivedSubscriptionUsage)
   return state
 }
 
@@ -103,7 +109,7 @@ function invalidRunSpending(run) {
 }
 
 function sanitize(value, maxRuns) {
-  if (!value || typeof value !== 'object' || Array.isArray(value) || ![1, STATE_VERSION].includes(value.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'
@@ -119,6 +125,11 @@ function sanitize(value, maxRuns) {
       || 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 : {},
@@ -128,6 +139,8 @@ function sanitize(value, maxRuns) {
     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)

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
@@ -128,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'
@@ -137,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 }
@@ -373,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 } : {}),
@@ -443,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)
@@ -460,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 } : {}),
@@ -483,6 +489,10 @@ 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 }),
@@ -497,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,
@@ -545,6 +556,8 @@ export function buildToolRunRecord({ toolId, toolLabel, provider, model, cliMode
       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,
@@ -554,6 +567,7 @@ 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 未成功完成。'),

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
+}