dsh-tacit 0.2.3 → 0.4.0

package/lib/pricing.js

@@ -0,0 +1,311 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 hackernotfound — https://github.com/hackernotfound/dsh-tacit
+/**
+ * dsh-tacit — pure pricing (no I/O).
+ *
+ * Prices one model call from its token usage against either the bundled
+ * DeepSeek list prices (peak / off-peak / Beijing-weekend tiers) or a price
+ * table sourced from the `dsh-cost-meter` plugin's state. Nothing here
+ * touches the network, the store, or the service — `lib/pricing-source.js`
+ * is responsible for fetching the cost-meter state, normalizing it with
+ * `normalizeCostMeterState`, and handing the result in as `table`.
+ *
+ * Tier is decided once, at the request's start time (`atMs`) — not at
+ * finish, so a call that straddles a boundary is priced consistently.
+ */
+
+export const PRICES_AS_OF = '2026-08-22'
+
+/**
+ * `reasoningTokens` (DeepSeek adapter) is always a subset of `outputTokens`,
+ * never a separate quantity — so it must not be billed again. Kept as a
+ * named constant (rather than inlined `false`) so it can be flipped if a
+ * future adapter ever reports reasoning as additional to output.
+ */
+export const REASONING_BILLED_SEPARATELY = false
+
+/** Provider ids that route through DeepSeek's own API (bundled list prices apply). */
+export const OFFICIAL_PROVIDERS = ['deepseek-official', 'deepseek']
+
+/** USD per 1M tokens, as of {@link PRICES_AS_OF}. */
+export const BUNDLED_PRICES = {
+  'deepseek-v4-flash': {
+    offPeak: { cacheHit: 0.007, cacheMiss: 0.22, output: 0.66 },
+    peak: { cacheHit: 0.014, cacheMiss: 0.44, output: 1.32 },
+  },
+  'deepseek-v4-pro': {
+    offPeak: { cacheHit: 0.022, cacheMiss: 0.66, output: 1.98 },
+    peak: { cacheHit: 0.044, cacheMiss: 1.32, output: 3.96 },
+  },
+}
+
+/** Peak hour windows, UTC, `[start, end)`. */
+export const PEAK_WINDOWS_UTC = [{ start: 1, end: 4 }, { start: 6, end: 10 }]
+
+/** Beijing-weekend off-peak rule only applies from this moment on. */
+export const WEEKEND_OFFPEAK_FROM = Date.parse('2026-08-22T16:00:00Z')
+
+const MS_PER_HOUR = 3600 * 1000
+
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+function isPositiveNumber(value) {
+  return isFiniteNumber(value) && value > 0
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** Is the day-of-week of `ms + 8h`, in UTC, a Saturday or Sunday (Beijing calendar)? */
+export function isBeijingWeekend(ms) {
+  if (!isFiniteNumber(ms)) return false
+  const day = new Date(ms + 8 * MS_PER_HOUR).getUTCDay()
+  return day === 0 || day === 6
+}
+
+/**
+ * The pricing tier in effect at `ms`. `offPeak` when `!peakEnabled`, when
+ * `ms < effectiveAtMs`, when it's a Beijing weekend at/after
+ * {@link WEEKEND_OFFPEAK_FROM}, or when the UTC hour falls outside every
+ * window; `peak` otherwise.
+ */
+export function tierAt(ms, { windows = PEAK_WINDOWS_UTC, effectiveAtMs = 0, peakEnabled = true } = {}) {
+  if (!peakEnabled) return 'offPeak'
+  if (!isFiniteNumber(ms)) return 'offPeak'
+  if (isFiniteNumber(effectiveAtMs) && ms < effectiveAtMs) return 'offPeak'
+  if (ms >= WEEKEND_OFFPEAK_FROM && isBeijingWeekend(ms)) return 'offPeak'
+
+  const hour = new Date(ms).getUTCHours()
+  const activeWindows = Array.isArray(windows) ? windows : PEAK_WINDOWS_UTC
+  const inWindow = activeWindows.some(
+    (w) => isPlainObject(w) && isFiniteNumber(w.start) && isFiniteNumber(w.end) && hour >= w.start && hour < w.end,
+  )
+  return inWindow ? 'peak' : 'offPeak'
+}
+
+/**
+ * Does `provider` route through DeepSeek's own API (as opposed to a
+ * proxy/custom route)? Case-folded: a harness reporting `DeepSeek-Official`
+ * names the same route, and an exact match would leave its calls unpriced.
+ */
+export function isOfficialRoute(provider) {
+  return typeof provider === 'string' && OFFICIAL_PROVIDERS.includes(provider.toLowerCase())
+}
+
+/** A well-formed `{cacheHit, cacheMiss, output}` triple, or `null`. */
+function isRateTriple(triple) {
+  return isPlainObject(triple) && isFiniteNumber(triple.cacheHit) && isFiniteNumber(triple.cacheMiss) && isFiniteNumber(triple.output)
+}
+
+/** Look up `table.models[model]`'s tiered rates for an official-route call, or `null`. */
+function costMeterModelRates(table, model, atMs) {
+  const models = isPlainObject(table.models) ? table.models : null
+  const entry = models === null ? undefined : models[model]
+  if (!isPlainObject(entry) || !isRateTriple(entry.offPeak) || !isRateTriple(entry.peak)) return null
+  const tier = tierAt(atMs, {
+    windows: table.windows,
+    effectiveAtMs: table.effectiveAtMs,
+    peakEnabled: table.peakEnabled !== false,
+  })
+  return { tier, rates: entry[tier] }
+}
+
+/**
+ * Look up `table.providers[provider][model]`'s flat rates, or `null`. The key
+ * is case-folded on both sides (`normalizeCostMeterState` lower-cases what it
+ * stores): the cost-meter table is a foreign schema whose provider ids are
+ * whatever its own user typed, and a casing mismatch must not silently drop
+ * the call through to bundled pricing.
+ */
+function costMeterProviderRates(table, provider, model) {
+  const providers = isPlainObject(table.providers) ? table.providers : null
+  const key = typeof provider === 'string' ? provider.toLowerCase() : provider
+  const providerEntry = providers === null ? undefined : providers[key]
+  const flat = isPlainObject(providerEntry) ? providerEntry[model] : undefined
+  return isRateTriple(flat) ? flat : null
+}
+
+/**
+ * Resolve the price source and rates for one call. Resolution order:
+ * (1) `table.models[model]` when the route is official → `costMeter`, tier
+ *     from `tierAt` using the table's own windows/effectiveAt/peakEnabled;
+ * (2) `table.providers[provider][model]` → `costMeter`, `tier:'flat'`;
+ * (3) the bundled list price, when the route is official and the model is
+ *     known → `bundled`;
+ * (4) `null`.
+ *
+ * Always returns fresh copies of `rates` — never a reference into
+ * `BUNDLED_PRICES` or `table`.
+ */
+export function ratesFor({ model, provider, atMs, table = null }) {
+  if (isPlainObject(table)) {
+    if (isOfficialRoute(provider)) {
+      const found = costMeterModelRates(table, model, atMs)
+      if (found !== null) {
+        return {
+          source: 'costMeter',
+          tier: found.tier,
+          rates: { ...found.rates },
+          asOf: typeof table.asOf === 'string' ? table.asOf : PRICES_AS_OF,
+        }
+      }
+    }
+    const flat = costMeterProviderRates(table, provider, model)
+    if (flat !== null) {
+      return {
+        source: 'costMeter',
+        tier: 'flat',
+        rates: { ...flat },
+        asOf: typeof table.asOf === 'string' ? table.asOf : PRICES_AS_OF,
+      }
+    }
+  }
+
+  if (isOfficialRoute(provider) && Object.prototype.hasOwnProperty.call(BUNDLED_PRICES, model)) {
+    const tier = tierAt(atMs)
+    return {
+      source: 'bundled',
+      tier,
+      rates: { ...BUNDLED_PRICES[model][tier] },
+      asOf: PRICES_AS_OF,
+    }
+  }
+
+  return null
+}
+
+/** Read a usage field as a non-negative finite number, defaulting to 0. */
+function tokensOf(usage, key) {
+  const value = usage === null || typeof usage !== 'object' ? undefined : usage[key]
+  return isFiniteNumber(value) && value >= 0 ? value : 0
+}
+
+/**
+ * USD cost of `usage` at `rates`. `inputTokens` is uncached input, billed at
+ * `cacheMiss`; `cacheReadTokens` + `cacheWriteTokens` bill at `cacheHit`;
+ * `reasoningTokens` is added to output only if {@link REASONING_BILLED_SEPARATELY}.
+ */
+export function costOf(usage, rates) {
+  const input = tokensOf(usage, 'inputTokens')
+  const output = tokensOf(usage, 'outputTokens')
+  const cacheRead = tokensOf(usage, 'cacheReadTokens')
+  const cacheWrite = tokensOf(usage, 'cacheWriteTokens')
+  const reasoning = tokensOf(usage, 'reasoningTokens')
+  const billedOutput = REASONING_BILLED_SEPARATELY ? output + reasoning : output
+  const cacheHitTokens = cacheRead + cacheWrite
+
+  const cacheHit = isFiniteNumber(rates?.cacheHit) ? rates.cacheHit : 0
+  const cacheMiss = isFiniteNumber(rates?.cacheMiss) ? rates.cacheMiss : 0
+  const outputRate = isFiniteNumber(rates?.output) ? rates.output : 0
+
+  return (input * cacheMiss + cacheHitTokens * cacheHit + billedOutput * outputRate) / 1e6
+}
+
+/** Price one call end to end: resolve rates via {@link ratesFor}, then cost via {@link costOf}. */
+export function priceCall({ model, provider, atMs, usage, table = null }) {
+  const priced = ratesFor({ model, provider, atMs, table })
+  if (priced === null) return null
+  return { ...priced, usd: costOf(usage, priced.rates) }
+}
+
+// ── costMeter state normalization ───────────────────────────────────────
+
+const DEFAULT_EXCHANGE_RATE = 7.2
+
+/** A `{cacheHit, cacheMiss, output}` triple, currency-converted; `null` if any rate is invalid. */
+function normalizeTriple(triple, currency, exchangeRate) {
+  if (!isRateTriple(triple) || triple.cacheHit < 0 || triple.cacheMiss < 0 || triple.output < 0) return null
+  const divisor = currency === 'CNY' ? (isPositiveNumber(exchangeRate) ? exchangeRate : DEFAULT_EXCHANGE_RATE) : 1
+  return { cacheHit: triple.cacheHit / divisor, cacheMiss: triple.cacheMiss / divisor, output: triple.output / divisor }
+}
+
+/** A model price entry (`{cacheHit,cacheMiss,output}` or `{offPeak,peak}`) → `{offPeak, peak}`, or `null`. */
+function normalizeModelEntry(entry, currency, exchangeRate) {
+  if (!isPlainObject(entry)) return null
+  if (entry.offPeak !== undefined || entry.peak !== undefined) {
+    const offPeak = normalizeTriple(entry.offPeak, currency, exchangeRate)
+    const peak = normalizeTriple(entry.peak, currency, exchangeRate)
+    return offPeak === null || peak === null ? null : { offPeak, peak }
+  }
+  const flat = normalizeTriple(entry, currency, exchangeRate)
+  return flat === null ? null : { offPeak: flat, peak: { ...flat } }
+}
+
+/** A provider price entry `{input, cachedInput?, output}` → `{cacheMiss, cacheHit, output}`, or `null`. */
+function normalizeProviderModelEntry(entry, currency, exchangeRate) {
+  if (!isPlainObject(entry)) return null
+  const cachedInput = entry.cachedInput !== undefined ? entry.cachedInput : entry.input
+  return normalizeTriple({ cacheMiss: entry.input, cacheHit: cachedInput, output: entry.output }, currency, exchangeRate)
+}
+
+/**
+ * Duck-typed normalization of the `dsh-cost-meter` service state (or its
+ * `config` sub-object) into the shape {@link ratesFor} consumes:
+ * `{models, providers, windows, effectiveAtMs, peakEnabled, asOf}`.
+ * Invalid rates (non-finite or negative) drop the entry that carries them;
+ * a non-object input (or config root) yields `null`.
+ */
+/** Epoch ms from either a number or an ISO-ish date string; 0 when it is neither. */
+function normalizeMoment(value) {
+  if (isFiniteNumber(value)) return value
+  if (typeof value !== 'string' || value.length === 0) return 0
+  const parsed = Date.parse(value)
+  return Number.isFinite(parsed) ? parsed : 0
+}
+
+export function normalizeCostMeterState(state) {
+  if (!isPlainObject(state)) return null
+  const config = isPlainObject(state.config) ? state.config : state
+  if (!isPlainObject(config)) return null
+
+  const prices = isPlainObject(config.prices) ? config.prices : {}
+  const currency = prices.currency === 'CNY' ? 'CNY' : 'USD'
+  const exchangeRate = isPositiveNumber(config.exchangeRate) ? config.exchangeRate : DEFAULT_EXCHANGE_RATE
+
+  const models = {}
+  const rawModels = isPlainObject(prices.models) ? prices.models : {}
+  for (const [id, entry] of Object.entries(rawModels)) {
+    const normalized = normalizeModelEntry(entry, currency, exchangeRate)
+    if (normalized !== null) models[id] = normalized
+  }
+
+  const providers = {}
+  const rawProviders = isPlainObject(prices.providers) ? prices.providers : {}
+  for (const [providerId, providerEntry] of Object.entries(rawProviders)) {
+    if (!isPlainObject(providerEntry)) continue
+    const rawProviderModels = isPlainObject(providerEntry.models) ? providerEntry.models : {}
+    const byModel = {}
+    for (const [modelId, entry] of Object.entries(rawProviderModels)) {
+      const normalized = normalizeProviderModelEntry(entry, currency, exchangeRate)
+      if (normalized !== null) byModel[modelId] = normalized
+    }
+    // Lower-cased so a lookup can match whatever case the caller reports; two
+    // keys differing only by case merge, and the first one listed wins.
+    const key = String(providerId).toLowerCase()
+    if (Object.keys(byModel).length > 0 && providers[key] === undefined) providers[key] = byModel
+  }
+
+  // An array that filters down to nothing says as little as no array at all —
+  // and an empty window list would silently price every call off-peak.
+  const rawWindows = Array.isArray(config.peakWindows)
+    ? config.peakWindows.filter((w) => isPlainObject(w) && isFiniteNumber(w.start) && isFiniteNumber(w.end))
+    : []
+  const windows = rawWindows.length > 0
+    ? rawWindows.map((w) => ({ start: w.start, end: w.end }))
+    : PEAK_WINDOWS_UTC.map((w) => ({ ...w }))
+
+  const effectiveAtMs = normalizeMoment(config.peakEffectiveAt)
+  const peakEnabled = typeof config.peakEnabled === 'boolean' ? config.peakEnabled : true
+
+  return {
+    models,
+    providers,
+    windows,
+    effectiveAtMs,
+    peakEnabled,
+    asOf: new Date().toISOString(),
+  }
+}

package/lib/routes.js

@@ -10,7 +10,14 @@
  * into one ctx.effect so a fiber unload removes every route.
  */
 
-function withService(ctx, serviceName, fn) {
+/**
+ * Run `fn(service)` as soon as `serviceName` exists — immediately when it is
+ * already registered, otherwise once on the next `internal/service` event for
+ * it (the listener removes itself). Exported so the service layer can wait on
+ * optional siblings (e.g. `costMeter`) the same way the routes wait on
+ * `webServer`.
+ */
+export function withService(ctx, serviceName, fn) {
   const existing = ctx.get !== undefined && typeof ctx.get === 'function' ? ctx.get(serviceName) : undefined
   if (existing !== undefined && existing !== null) {
     fn(existing)
@@ -130,14 +137,20 @@ export function registerWebRoutes(ctx, service) {
     route('POST', '/api/tacit/reports', (body) => service.getReports(body))
     route('POST', '/api/tacit/history', (body) => service.listHistory(body))
     route('POST', '/api/tacit/analyze', (body) => service.analyzeTurn(body))
+    route('POST', '/api/tacit/analyze-batch', (body) => service.analyzeBatch(body))
     route('POST', '/api/tacit/improve', (body) => service.improveDraft(body))
     route('POST', '/api/tacit/feedback', (body) => service.feedback(body))
     route('POST', '/api/tacit/applied', (body) => service.applied(body))
     route('POST', '/api/tacit/directives', (body) => service.directives(body))
     route('POST', '/api/tacit/stats', (body) => service.stats(body))
     route('POST', '/api/tacit/bootstrap', (body) => service.bootstrap(body))
+    route('POST', '/api/tacit/bootstrap-preview', (body) => service.bootstrapPreview(body))
     route('POST', '/api/tacit/config', (body) => service.updateConfig(body))
     route('POST', '/api/tacit/clear', () => service.clearReports())
+    route('POST', '/api/tacit/usage', (body) => service.usageReport(body))
+    route('POST', '/api/tacit/usage-run', (body) => service.usageRun(body))
+    route('POST', '/api/tacit/usage-clear', () => service.usageClear())
+    route('POST', '/api/tacit/pricing-refresh', () => service.pricingRefresh())
 
     ctx.effect(() => () => {
       for (const dispose of disposers.splice(0).reverse()) {

package/lib/schema.js

@@ -21,6 +21,16 @@ export const COACH_MODELS = ['deepseek-v4-flash', 'deepseek-v4-pro']
  */
 export const COACH_PROVIDER = 'deepseek-official'
 
+/**
+ * The model-call failure codes Tacit is allowed to put on the wire. The client
+ * renders `err.<code>` for whatever the envelope carries, so a raw provider
+ * code (`RATE_LIMIT`, `ERROR`, `ABORTED`, …) would surface as a literal
+ * `err.ABORTED` banner — `coachErrorCode` (`lib/service.js`) maps anything
+ * outside this list onto one of these. Every entry has an `err.*` key in both
+ * dictionaries (`client/src/10-i18n.js`, test-enforced).
+ */
+export const COACH_ERROR_CODES = ['no-llm', 'no-api-key', 'no-credit', 'rate-limited', 'timeout', 'empty-response', 'call-failed']
+
 /**
  * The loader-facing plugin config. Wrapped in `z.preprocess` so a patch row
  * without a `config:` block (`undefined`) resolves to all defaults — a bare
@@ -63,6 +73,12 @@ export const Config = z.preprocess((v) => v ?? {}, z.object({
   bootstrapConcurrency: z.number().default(1),
   /** Also learn from a clean turn that follows a messy one (what the user included the second time). Automatic, capped. */
   learnFromGood: z.boolean().default(true),
+  /** Days of detailed usage-ledger day files kept before they expire (7-365, clamped in mergeConfig). */
+  costHistoryDays: z.number().default(30),
+  /** Daily USD spend that triggers the warn/exceeded cost UI; 0 disables (clamped in mergeConfig). */
+  costWarnDailyUsd: z.number().default(0),
+  /** Same as `costWarnDailyUsd`, over a calendar month; 0 disables (clamped in mergeConfig). */
+  costWarnMonthlyUsd: z.number().default(0),
 }))
 
 /**
@@ -88,6 +104,9 @@ const configPatchSchema = z.object({
   directiveWorseBy: z.number().optional(),
   bootstrapConcurrency: z.number().optional(),
   learnFromGood: z.boolean().optional(),
+  costHistoryDays: z.number().optional(),
+  costWarnDailyUsd: z.number().optional(),
+  costWarnMonthlyUsd: z.number().optional(),
 })
 
 // ── Trajectory projection ──────────────────────────────────────────────────
@@ -213,15 +232,23 @@ const feedbackEntrySchema = z.object({
  * system prompt). `distilled` entries come from analyses; `user` entries are
  * typed in Settings and survive every distillation.
  */
-const directiveTrialSchema = z.object({
-  /** Finished turns observed while the candidate was injected. */
-  turns: z.number().int().min(0),
-  /** How many of those were messy. */
-  messy: z.number().int().min(0),
-  /** Messy-turn rate over the 20 turns before the trial started. */
-  baselineRate: z.number(),
-  startedAt: z.number(),
-})
+const directiveTrialSchema = z.preprocess(
+  // Profiles written before corrections were graded named the messy baseline `baselineRate`.
+  (raw) => (raw !== null && typeof raw === 'object' && 'baselineRate' in raw && !('baselineMessyRate' in raw) ? { ...raw, baselineMessyRate: raw.baselineRate } : raw),
+  z.object({
+    /** Finished turns observed while the candidate was injected. */
+    turns: z.number().int().min(0),
+    /** How many of those were messy. */
+    messy: z.number().int().min(0),
+    /** How many of those the user corrected with their next message. */
+    corrected: z.number().int().min(0).default(0),
+    /** Messy-turn rate over the 20 turns before the trial started. */
+    baselineMessyRate: z.number(),
+    /** Correction rate over those 20 turns; -1 = unknown (older profile), recomputed when the trial next advances. */
+    baselineCorrectionRate: z.number().default(-1),
+    startedAt: z.number(),
+  }),
+)
 
 const directiveSchema = z.object({
   id: z.string(),
@@ -229,8 +256,8 @@ const directiveSchema = z.object({
   enabled: z.boolean().default(true),
   source: z.enum(['distilled', 'user']).default('distilled'),
   createdAt: z.number(),
-  /** candidate = injected on trial; active = proven (or user-made); retired = made things worse. */
-  status: z.enum(['candidate', 'active', 'retired']).default('active'),
+  /** queued = waiting for its scope's trial slot; candidate = injected on trial; active = proven (or user-made); retired = made things worse. */
+  status: z.enum(['queued', 'candidate', 'active', 'retired']).default('active'),
   trial: directiveTrialSchema.optional(),
   retiredReason: z.string().optional(),
   /** Absolute workspace directory this directive is limited to; absent = every conversation. */
@@ -288,6 +315,12 @@ export const analyzeArgSchema = z.object({
   turn: z.number().int().min(1),
 })
 
+/** `/api/tacit/analyze-batch`: one session, up to 50 turns analyzed under a single run. */
+export const analyzeBatchArgSchema = z.object({
+  sessionId: z.string().min(1).max(200),
+  turns: z.array(z.number().int().min(1)).min(1).max(50),
+})
+
 export const improveArgSchema = z.object({
   sessionId: z.string().min(1).max(200),
   draft: z.string().min(1).max(100000),
@@ -308,3 +341,154 @@ export const appliedArgSchema = z.object({
 export const configArgSchema = z.object({
   patch: configPatchSchema,
 })
+
+// ── Usage ledger (content-free: no prompts, no responses, no tool args) ────
+
+/** Every op a metered model call can be tagged with (Task 1's sink + the distillation/enrichment calls). */
+export const USAGE_OPS = [
+  'analysis',
+  'analysis-repair',
+  'directive-distillation',
+  'style-distillation',
+  'improve',
+  'improve-repair',
+  'enrichment',
+]
+
+/** Every state one recorded attempt can end in. */
+export const USAGE_ATTEMPT_STATUSES = ['ok', 'failed', 'unmetered']
+
+/** Every state a run can be in. `running` is written too: the flush persists live runs. */
+export const USAGE_RUN_STATUSES = ['running', 'success', 'partial', 'failed']
+
+/** Every kind of run the tracker groups attempts into. */
+export const USAGE_RUN_TYPES = [
+  'bootstrap',
+  'analysis',
+  'analysis-batch',
+  'improve',
+  'directive-distillation',
+  'style-distillation',
+  'prompt-enrichment',
+]
+
+/** Raw token counts, zero-filled so totals can be summed without null checks. */
+export const tokenBucketsSchema = z.object({
+  inputTokens: z.number().default(0),
+  outputTokens: z.number().default(0),
+  cacheReadTokens: z.number().default(0),
+  cacheWriteTokens: z.number().default(0),
+  reasoningTokens: z.number().default(0),
+})
+
+/**
+ * One metered model call. Mirrors the sink record `callCoachModel` hands the
+ * tracker (`startedAt`..`usage`) plus the identity fields the tracker itself
+ * assigns (`id`, `op`, `sessionId`, `turn`) and the priced result. Never
+ * carries prompt/response text, tool args, or API keys.
+ */
+export const usageAttemptSchema = z.object({
+  id: z.string(),
+  op: z.enum(USAGE_OPS),
+  startedAt: z.number(),
+  durationMs: z.number().default(0),
+  model: z.string().default(''),
+  provider: z.string().default(''),
+  reasoningEffort: z.string().nullable().default(null),
+  finish: z.string().default(''),
+  status: z.enum(USAGE_ATTEMPT_STATUSES),
+  code: z.string().default(''),
+  sessionId: z.string().default(''),
+  turn: z.number().nullable().default(null),
+  usage: tokenBucketsSchema.nullable().default(null),
+  /** null when no price table matched the route/model (e.g. a proxy provider). */
+  priced: z.object({
+    source: z.enum(['bundled', 'costMeter']),
+    tier: z.string(),
+    rates: z.object({ cacheHit: z.number(), cacheMiss: z.number(), output: z.number() }),
+    asOf: z.string(),
+    usd: z.number(),
+  }).nullable().default(null),
+})
+
+/**
+ * A precomputed, already-defaulted instance of a nested object schema.
+ * zod's `.default(value)` injects `value` verbatim when a field is absent —
+ * it does NOT re-run `value` through the schema — so a literal `{}` default
+ * on a nested object would skip that object's own field defaults. Passing
+ * `schema.parse({})` instead gives the same "all defaults" shape correctly.
+ */
+const emptyTokenBuckets = tokenBucketsSchema.parse({})
+
+/** Aggregate counters shared by a run's totals, the lifetime summary, and every summary bucket. */
+export const usageTotalsSchema = z.object({
+  attempts: z.number().default(0),
+  billedCalls: z.number().default(0),
+  unmeteredCalls: z.number().default(0),
+  unpricedCalls: z.number().default(0),
+  tokens: tokenBucketsSchema.default(emptyTokenBuckets),
+  usdKnown: z.number().default(0),
+})
+
+const emptyUsageTotals = usageTotalsSchema.parse({})
+
+/** One tracker run: a group of attempts sharing a trigger (a single call, an auto-analysis, a bootstrap batch, ...). */
+export const usageRunSchema = z.object({
+  runId: z.string(),
+  type: z.enum(USAGE_RUN_TYPES),
+  trigger: z.string().default(''),
+  startedAt: z.number(),
+  endedAt: z.number().default(0),
+  status: z.enum(USAGE_RUN_STATUSES).default('running'),
+  sessionId: z.string().default(''),
+  turn: z.number().nullable().default(null),
+  workspace: z.string().default(''),
+  model: z.string().default(''),
+  provider: z.string().default(''),
+  results: z.record(z.number()).default({}),
+  attempts: z.array(usageAttemptSchema).default([]),
+  totals: usageTotalsSchema.default(emptyUsageTotals),
+})
+
+/** One day's `usage/YYYY-MM-DD.json` file. */
+export const usageDayFileSchema = z.object({
+  version: z.literal(1),
+  day: z.string(),
+  runs: z.array(usageRunSchema).default([]),
+})
+
+const usageDayTotalsSchema = usageTotalsSchema.extend({
+  byType: z.record(usageTotalsSchema).default({}),
+})
+
+/** `usage/summary.json`: rolling totals kept alongside the day files so reports never have to re-scan every day. */
+export const usageSummarySchema = z.object({
+  version: z.literal(1),
+  trackingSince: z.number(),
+  lifetime: usageTotalsSchema.default(emptyUsageTotals),
+  byType: z.record(usageTotalsSchema).default({}),
+  byModel: z.record(usageTotalsSchema).default({}),
+  days: z.record(usageDayTotalsSchema).default({}),
+})
+
+/**
+ * Arguments for `/api/tacit/usage`. Declared here (not next to
+ * `bootstrapArgSchema`) because `z.enum(USAGE_RUN_TYPES)` needs the run-type
+ * list above it. Every field is optional on the wire; `tracker.report()`
+ * applies the defaults (`range: '30d'`, `page: 1`, `pageSize: 20`).
+ */
+export const usageArgSchema = z.object({
+  range: z.enum(['today', '7d', '30d', 'month', 'all']).optional(),
+  type: z.enum(USAGE_RUN_TYPES).optional(),
+  status: z.enum(USAGE_RUN_STATUSES).optional(),
+  model: z.string().max(64).optional(),
+  workspace: z.string().max(200).optional(),
+  sessionId: z.string().max(200).optional(),
+  page: z.number().int().min(1).max(1000).optional(),
+  pageSize: z.number().int().min(1).max(100).optional(),
+})
+
+/** Arguments for `/api/tacit/usage-run`: one run id, as minted by `beginRun`. */
+export const usageRunArgSchema = z.object({
+  runId: z.string().min(1).max(64),
+})