@oar-sh/oar 0.9.15 → 0.9.17

package/server/migrations/0026-deepseek-usage-served-models.mjs

@@ -0,0 +1,222 @@
+'use strict';
+
+/**
+ * Migration: DeepSeek usage rows booked under a Claude model name are folded
+ * into the DeepSeek model that served them (services/plan-usage-service.mjs,
+ * the DeepSeek card in Check Usage). Builds on 0024 and 0025.
+ *
+ * A DeepSeek chat runs Claude Code. Before the CLI's model aliases were pinned
+ * to the chat's model, a sub-agent asked for as "opus" went to DeepSeek as
+ * `claude-opus-5-5`, which DeepSeek's Anthropic-compatible endpoint serves
+ * with V4 Pro (and `claude-sonnet*` / `claude-haiku*` with Flash). Such
+ * turns were booked under the Claude name and, as shared/deepseek-pricing.mjs
+ * prices only DeepSeek's ids, without a price.
+ *
+ * For each of `deepseek_usage_totals`, `deepseek_usage_days` and
+ * `deepseek_usage_checkpoints`, every row whose model name
+ * shared/deepseek-models.mjs maps to a DeepSeek model (`deepseekServedModel`)
+ * is added to that model's row (created when there is none) and deleted:
+ * tokens, requests and turns are summed; `first_seen_at` / `last_seen_at`
+ * widen. The folded tokens are priced at the DeepSeek model's price for the
+ * row's last turn time (`last_seen_at` of a totals row, `updated_at` of a
+ * daily row: peak or off-peak by that time, as the rows keep no per-turn
+ * times), the folded requests at the request price for that time, and the
+ * amounts are added to the target's costs. A checkpoint is a CLI session's
+ * running total per model, so the Claude-named and the DeepSeek-named
+ * checkpoints of one session add up to what the session reports once its
+ * worker names the DeepSeek model.
+ *
+ * Idempotent: a database without such rows is left as it is. Safe to run on
+ * every boot.
+ *
+ * Usage: node server/migrations/0026-deepseek-usage-served-models.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import Database from 'better-sqlite3';
+
+import { DEEPSEEK_USAGE_CHECKPOINTS_TABLE, DEEPSEEK_USAGE_TOTALS_TABLE } from './0024-deepseek-usage-totals.mjs';
+import { DEEPSEEK_USAGE_DAYS_TABLE, migrateDeepSeekUsageRequestsDaily } from './0025-deepseek-usage-requests-daily.mjs';
+import { deepseekServedModel } from '../../shared/deepseek-models.mjs';
+import { estimateCost, estimateSearchCost } from '../../shared/deepseek-pricing.mjs';
+
+/** The DeepSeek model a stored model name is folded into, or '' when the row stays. */
+export function deepseekFoldedModel(model) {
+  const name = String(model ?? '').trim();
+  const served = deepseekServedModel(name);
+  return served && served !== name ? served : '';
+}
+
+function foldableRows(db, table) {
+  return db.prepare(`SELECT * FROM ${table}`).all()
+    .map((row) => ({ row, target: deepseekFoldedModel(row.model) }))
+    .filter((entry) => entry.target);
+}
+
+/** The rows the service would still read under a Claude name: '' when none. */
+export function deepseekUsageServedModelsProblem(db) {
+  for (const table of [DEEPSEEK_USAGE_TOTALS_TABLE, DEEPSEEK_USAGE_DAYS_TABLE, DEEPSEEK_USAGE_CHECKPOINTS_TABLE]) {
+    const count = foldableRows(db, table).length;
+    if (count) return `${table} holds ${count} row(s) under a model name DeepSeek served with another model`;
+  }
+  return '';
+}
+
+const count = (value) => Math.max(0, Math.round(Number(value) || 0));
+const money = (value) => (value === null || value === undefined ? null : Number(value));
+
+/** The folded row's token and request costs at the target model's price for `at`. */
+function repriced(target, row, at) {
+  const tokens = { hitTokens: count(row.hit_tokens), missTokens: count(row.miss_tokens), outputTokens: count(row.output_tokens) };
+  const tokenCount = tokens.hitTokens + tokens.missTokens + tokens.outputTokens;
+  const requests = { searchRequests: count(row.search_requests), fetchRequests: count(row.fetch_requests) };
+  return {
+    costUsd: tokenCount > 0 ? estimateCost({ model: target, at, currency: 'USD', ...tokens }) : null,
+    costCny: tokenCount > 0 ? estimateCost({ model: target, at, currency: 'CNY', ...tokens }) : null,
+    toolsCostUsd: estimateSearchCost({ at, currency: 'USD', ...requests }) || 0,
+    toolsCostCny: estimateSearchCost({ at, currency: 'CNY', ...requests }) || 0,
+  };
+}
+
+const sumCost = (current, added) => (added === null ? money(current) : (Number(current) || 0) + added);
+
+function foldTotals(db) {
+  const entries = foldableRows(db, DEEPSEEK_USAGE_TOTALS_TABLE);
+  const get = db.prepare(`SELECT * FROM ${DEEPSEEK_USAGE_TOTALS_TABLE} WHERE model = ?`);
+  const put = db.prepare(`
+    INSERT OR REPLACE INTO ${DEEPSEEK_USAGE_TOTALS_TABLE} (
+      model, hit_tokens, miss_tokens, output_tokens, search_requests, fetch_requests, turn_count,
+      cost_usd, cost_cny, tools_cost_usd, tools_cost_cny, first_seen_at, last_seen_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const remove = db.prepare(`DELETE FROM ${DEEPSEEK_USAGE_TOTALS_TABLE} WHERE model = ?`);
+  for (const { row, target } of entries) {
+    const into = get.get(target) || {};
+    const price = repriced(target, row, row.last_seen_at);
+    const earliest = [into.first_seen_at, row.first_seen_at].filter(Boolean).sort()[0];
+    const latest = [into.last_seen_at, row.last_seen_at].filter(Boolean).sort().at(-1);
+    put.run(
+      target,
+      count(into.hit_tokens) + count(row.hit_tokens),
+      count(into.miss_tokens) + count(row.miss_tokens),
+      count(into.output_tokens) + count(row.output_tokens),
+      count(into.search_requests) + count(row.search_requests),
+      count(into.fetch_requests) + count(row.fetch_requests),
+      count(into.turn_count) + count(row.turn_count),
+      sumCost(into.cost_usd ?? null, price.costUsd),
+      sumCost(into.cost_cny ?? null, price.costCny),
+      (Number(into.tools_cost_usd) || 0) + price.toolsCostUsd,
+      (Number(into.tools_cost_cny) || 0) + price.toolsCostCny,
+      earliest,
+      latest,
+      [into.updated_at, row.updated_at].filter(Boolean).sort().at(-1),
+    );
+    remove.run(row.model);
+  }
+  return entries.length;
+}
+
+function foldDays(db) {
+  const entries = foldableRows(db, DEEPSEEK_USAGE_DAYS_TABLE);
+  const get = db.prepare(`SELECT * FROM ${DEEPSEEK_USAGE_DAYS_TABLE} WHERE day = ? AND model = ?`);
+  const put = db.prepare(`
+    INSERT OR REPLACE INTO ${DEEPSEEK_USAGE_DAYS_TABLE} (
+      day, model, hit_tokens, miss_tokens, output_tokens, search_requests, fetch_requests, turn_count,
+      cost_usd, cost_cny, tools_cost_usd, tools_cost_cny, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const remove = db.prepare(`DELETE FROM ${DEEPSEEK_USAGE_DAYS_TABLE} WHERE day = ? AND model = ?`);
+  for (const { row, target } of entries) {
+    const into = get.get(row.day, target) || {};
+    const price = repriced(target, row, row.updated_at);
+    put.run(
+      row.day,
+      target,
+      count(into.hit_tokens) + count(row.hit_tokens),
+      count(into.miss_tokens) + count(row.miss_tokens),
+      count(into.output_tokens) + count(row.output_tokens),
+      count(into.search_requests) + count(row.search_requests),
+      count(into.fetch_requests) + count(row.fetch_requests),
+      count(into.turn_count) + count(row.turn_count),
+      sumCost(into.cost_usd ?? null, price.costUsd),
+      sumCost(into.cost_cny ?? null, price.costCny),
+      (Number(into.tools_cost_usd) || 0) + price.toolsCostUsd,
+      (Number(into.tools_cost_cny) || 0) + price.toolsCostCny,
+      [into.updated_at, row.updated_at].filter(Boolean).sort().at(-1),
+    );
+    remove.run(row.day, row.model);
+  }
+  return entries.length;
+}
+
+function foldCheckpoints(db) {
+  const entries = foldableRows(db, DEEPSEEK_USAGE_CHECKPOINTS_TABLE);
+  const get = db.prepare(`
+    SELECT * FROM ${DEEPSEEK_USAGE_CHECKPOINTS_TABLE} WHERE conversation_id = ? AND native_session_id = ? AND model = ?
+  `);
+  const put = db.prepare(`
+    INSERT OR REPLACE INTO ${DEEPSEEK_USAGE_CHECKPOINTS_TABLE} (
+      conversation_id, native_session_id, model, hit_tokens, miss_tokens, output_tokens, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?)
+  `);
+  const remove = db.prepare(`
+    DELETE FROM ${DEEPSEEK_USAGE_CHECKPOINTS_TABLE} WHERE conversation_id = ? AND native_session_id = ? AND model = ?
+  `);
+  for (const { row, target } of entries) {
+    const into = get.get(row.conversation_id, row.native_session_id, target) || {};
+    put.run(
+      row.conversation_id,
+      row.native_session_id,
+      target,
+      count(into.hit_tokens) + count(row.hit_tokens),
+      count(into.miss_tokens) + count(row.miss_tokens),
+      count(into.output_tokens) + count(row.output_tokens),
+      [into.updated_at, row.updated_at].filter(Boolean).sort().at(-1),
+    );
+    remove.run(row.conversation_id, row.native_session_id, row.model);
+  }
+  return entries.length;
+}
+
+export function migrateDeepSeekUsageServedModels(db) {
+  // The rows live in 0024's and 0025's tables: a database without them gets
+  // them first (and then has nothing to fold).
+  migrateDeepSeekUsageRequestsDaily(db);
+  const result = db.transaction(() => ({
+    totalsFolded: foldTotals(db),
+    daysFolded: foldDays(db),
+    checkpointsFolded: foldCheckpoints(db),
+  }))();
+  return { applied: result.totalsFolded + result.daysFolded + result.checkpointsFolded > 0, ...result };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateDeepSeekUsageServedModels(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0026 on ${dbPath}`);
+    console.log(result.applied
+      ? `  deepseek usage served models: totals folded ${result.totalsFolded}, days folded ${result.daysFolded}, checkpoints folded ${result.checkpointsFolded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0026 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0027-deepseek-usage-checkpoint-runs.mjs

@@ -0,0 +1,101 @@
+'use strict';
+
+/**
+ * Migration: the DeepSeek usage checkpoint learns which worker process its
+ * totals came from, and keeps the process's web search and fetch counts
+ * (services/plan-usage-service.mjs, the DeepSeek card in Check Usage).
+ * Builds on 0024.
+ *
+ * `deepseek_usage_checkpoints` gains three columns:
+ * - `run_id`: the id the worker gives each Claude Code process it spawns
+ *   (`runId` of a `POST /api/deepseek-plan-usage` body); '' for a report
+ *   from an older worker. Running totals only grow within one process, so
+ *   a report below the checkpoint under the SAME run id is a stale one (a
+ *   retried or reordered post) and books nothing, while one under a NEW run
+ *   id is a process that started counting over, booked in full. Before, any
+ *   drop was taken as a fresh run and booked in full: a reordered pair of
+ *   reports booked the turns before them twice.
+ * - `search_requests`, `fetch_requests`: the process's running counts of
+ *   web searches and fetches, which a worker with a run id reports in place
+ *   of the turn's counts, so a repeated post adds nothing.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0027-deepseek-usage-checkpoint-runs.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+import { DEEPSEEK_USAGE_CHECKPOINTS_TABLE, migrateDeepSeekUsageTotals } from './0024-deepseek-usage-totals.mjs';
+
+// Added to deepseek_usage_checkpoints, with their DDL.
+export const DEEPSEEK_USAGE_CHECKPOINT_RUN_COLUMNS = Object.freeze([
+  ['run_id', "TEXT NOT NULL DEFAULT ''"],
+  ['search_requests', 'INTEGER NOT NULL DEFAULT 0'],
+  ['fetch_requests', 'INTEGER NOT NULL DEFAULT 0'],
+]);
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+function columnNames(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name));
+}
+
+/** What keeps the service from using the columns: '' when nothing does. */
+export function deepseekUsageCheckpointRunsProblem(db) {
+  if (!tableExists(db, DEEPSEEK_USAGE_CHECKPOINTS_TABLE)) return `no ${DEEPSEEK_USAGE_CHECKPOINTS_TABLE} table`;
+  const present = columnNames(db, DEEPSEEK_USAGE_CHECKPOINTS_TABLE);
+  const missing = DEEPSEEK_USAGE_CHECKPOINT_RUN_COLUMNS.map(([name]) => name).filter((name) => !present.has(name));
+  if (missing.length) return `${DEEPSEEK_USAGE_CHECKPOINTS_TABLE} lacks ${missing.join(', ')}`;
+  return '';
+}
+
+export function migrateDeepSeekUsageCheckpointRuns(db) {
+  // The columns go on 0024's table: a database that skipped 0024 gets it first.
+  migrateDeepSeekUsageTotals(db);
+  let columnsAdded = 0;
+  const present = columnNames(db, DEEPSEEK_USAGE_CHECKPOINTS_TABLE);
+  for (const [name, ddl] of DEEPSEEK_USAGE_CHECKPOINT_RUN_COLUMNS) {
+    if (present.has(name)) continue;
+    db.exec(`ALTER TABLE ${DEEPSEEK_USAGE_CHECKPOINTS_TABLE} ADD COLUMN ${name} ${ddl}`);
+    columnsAdded += 1;
+  }
+  return { applied: columnsAdded > 0, columnsAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateDeepSeekUsageCheckpointRuns(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0027 on ${dbPath}`);
+    console.log(result.applied
+      ? `  deepseek usage checkpoint runs: columns added ${result.columnsAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0027 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0028-deepseek-usage-checkpoint-request-runs.mjs

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * Migration: the DeepSeek usage checkpoint keeps the run id of its web
+ * search and fetch counts apart from the run id of its token totals
+ * (services/plan-usage-service.mjs, the DeepSeek card in Check Usage).
+ * Builds on 0027.
+ *
+ * `deepseek_usage_checkpoints` gains one column:
+ * - `request_run_id`: the worker's id of the Claude Code process the
+ *   `search_requests` and `fetch_requests` counts came from; '' before any
+ *   report with a run id carried counts for the model. With 0027 one
+ *   `run_id` served both the totals and the counts, so a report that
+ *   carried only counts for a model (a sub-agent's model that searched
+ *   without a token entry of its own) moved the run id of that model's token
+ *   totals too: a later token report of the earlier process was then read
+ *   as a new process and booked in full instead of as a stale one. Now a
+ *   token entry moves `run_id` and a request entry moves `request_run_id`,
+ *   and neither disturbs the other.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0028-deepseek-usage-checkpoint-request-runs.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+import { DEEPSEEK_USAGE_CHECKPOINTS_TABLE } from './0024-deepseek-usage-totals.mjs';
+import { migrateDeepSeekUsageCheckpointRuns } from './0027-deepseek-usage-checkpoint-runs.mjs';
+
+// Added to deepseek_usage_checkpoints, with their DDL.
+export const DEEPSEEK_USAGE_CHECKPOINT_REQUEST_RUN_COLUMNS = Object.freeze([
+  ['request_run_id', "TEXT NOT NULL DEFAULT ''"],
+]);
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+function columnNames(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name));
+}
+
+/** What keeps the service from using the column: '' when nothing does. */
+export function deepseekUsageCheckpointRequestRunsProblem(db) {
+  if (!tableExists(db, DEEPSEEK_USAGE_CHECKPOINTS_TABLE)) return `no ${DEEPSEEK_USAGE_CHECKPOINTS_TABLE} table`;
+  const present = columnNames(db, DEEPSEEK_USAGE_CHECKPOINTS_TABLE);
+  const missing = DEEPSEEK_USAGE_CHECKPOINT_REQUEST_RUN_COLUMNS.map(([name]) => name).filter((name) => !present.has(name));
+  if (missing.length) return `${DEEPSEEK_USAGE_CHECKPOINTS_TABLE} lacks ${missing.join(', ')}`;
+  return '';
+}
+
+export function migrateDeepSeekUsageCheckpointRequestRuns(db) {
+  // The column goes next to 0027's: a database that skipped 0027 gets them first.
+  migrateDeepSeekUsageCheckpointRuns(db);
+  let columnsAdded = 0;
+  const present = columnNames(db, DEEPSEEK_USAGE_CHECKPOINTS_TABLE);
+  for (const [name, ddl] of DEEPSEEK_USAGE_CHECKPOINT_REQUEST_RUN_COLUMNS) {
+    if (present.has(name)) continue;
+    db.exec(`ALTER TABLE ${DEEPSEEK_USAGE_CHECKPOINTS_TABLE} ADD COLUMN ${name} ${ddl}`);
+    columnsAdded += 1;
+  }
+  return { applied: columnsAdded > 0, columnsAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateDeepSeekUsageCheckpointRequestRuns(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0028 on ${dbPath}`);
+    console.log(result.applied
+      ? `  deepseek usage checkpoint request runs: columns added ${result.columnsAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0028 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0029-deepseek-balance-rises.mjs

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * Migration: the DeepSeek balance reference notes when the balance last rose
+ * (services/plan-usage-service.mjs, the DeepSeek card's balance bar). Builds
+ * on 0025.
+ *
+ * `deepseek_balance_reference` gains these columns:
+ * - `rose_at`: when a read last found the balance above the read before it
+ *   (a top-up or a grant); NULL while no rise was seen. `reference_at` cannot
+ *   tell: it is also set by the first read of a currency. A starting balance
+ *   set on the DeepSeek tab counts until the balance rises after it was set
+ *   (plan-usage-deepseek.mjs).
+ * - `last_read_at`: when `last_total` was read; NULL for a row from before.
+ * - `rose_from_at`: when the balance before that rise was read; NULL when
+ *   unknown. A rise the relay first sees after the starting balance was set
+ *   may be a top-up from before it, unless the balance before the rise was
+ *   read after it too.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0029-deepseek-balance-rises.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+import { DEEPSEEK_BALANCE_REFERENCE_TABLE, migrateDeepSeekUsageRequestsDaily } from './0025-deepseek-usage-requests-daily.mjs';
+
+// Added to deepseek_balance_reference, with their DDL.
+export const DEEPSEEK_BALANCE_RISE_COLUMNS = Object.freeze([
+  ['rose_at', 'TEXT'],
+  ['last_read_at', 'TEXT'],
+  ['rose_from_at', 'TEXT'],
+]);
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+function columnNames(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name));
+}
+
+/** What keeps the service from using the column: '' when nothing does. */
+export function deepseekBalanceRisesProblem(db) {
+  if (!tableExists(db, DEEPSEEK_BALANCE_REFERENCE_TABLE)) return `no ${DEEPSEEK_BALANCE_REFERENCE_TABLE} table`;
+  const present = columnNames(db, DEEPSEEK_BALANCE_REFERENCE_TABLE);
+  const missing = DEEPSEEK_BALANCE_RISE_COLUMNS.map(([name]) => name).filter((name) => !present.has(name));
+  if (missing.length) return `${DEEPSEEK_BALANCE_REFERENCE_TABLE} lacks ${missing.join(', ')}`;
+  return '';
+}
+
+export function migrateDeepSeekBalanceRises(db) {
+  // The column goes on 0025's table: a database that skipped 0025 gets it first.
+  migrateDeepSeekUsageRequestsDaily(db);
+  let columnsAdded = 0;
+  const present = columnNames(db, DEEPSEEK_BALANCE_REFERENCE_TABLE);
+  for (const [name, ddl] of DEEPSEEK_BALANCE_RISE_COLUMNS) {
+    if (present.has(name)) continue;
+    db.exec(`ALTER TABLE ${DEEPSEEK_BALANCE_REFERENCE_TABLE} ADD COLUMN ${name} ${ddl}`);
+    columnsAdded += 1;
+  }
+  return { applied: columnsAdded > 0, columnsAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateDeepSeekBalanceRises(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0029 on ${dbPath}`);
+    console.log(result.applied
+      ? `  deepseek balance rises: columns added ${result.columnsAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0029 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0030-deepseek-usage-actuals.mjs

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * Migration: the figures of DeepSeek's own usage export, imported from the
+ * platform's two CSV files (services/deepseek-usage-import.mjs). The usage
+ * card in Check Usage shows them instead of the relay's estimate for the
+ * days and models they cover.
+ *
+ * Adds one table of its own, `deepseek_usage_actuals`, one row per export
+ * day, model and API key (the key is the day, so a re-export taken in
+ * another time zone replaces the day instead of adding a second row):
+ * - `day`: the local date of `period_start`, in the export's time zone;
+ * - `period_start`, `period_end`: the first start and last end of the day's
+ *   periods as the export gives them (ISO with the export's offset);
+ * - `model`, `key_fp` (the key masked as `sk-XXXXX…YYYY`), `key_name`;
+ * - `hit_tokens`, `miss_tokens`, `output_tokens`, `request_count`;
+ * - `cost`, `currency`: the period's cost, amount × price summed;
+ * - `imported_at`.
+ *
+ * The relay's own usage tables are not touched. Additive and idempotent.
+ * Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0030-deepseek-usage-actuals.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+export const DEEPSEEK_USAGE_ACTUALS_TABLE = 'deepseek_usage_actuals';
+
+export const DEEPSEEK_USAGE_ACTUALS_COLUMNS = Object.freeze([
+  'period_start',
+  'period_end',
+  'day',
+  'model',
+  'key_fp',
+  'key_name',
+  'hit_tokens',
+  'miss_tokens',
+  'output_tokens',
+  'request_count',
+  'cost',
+  'currency',
+  'imported_at',
+]);
+
+const CREATE_SQL = `
+  CREATE TABLE IF NOT EXISTS ${DEEPSEEK_USAGE_ACTUALS_TABLE} (
+    period_start TEXT NOT NULL,
+    period_end TEXT NOT NULL,
+    day TEXT NOT NULL,
+    model TEXT NOT NULL,
+    key_fp TEXT NOT NULL,
+    key_name TEXT NOT NULL DEFAULT '',
+    hit_tokens INTEGER NOT NULL DEFAULT 0,
+    miss_tokens INTEGER NOT NULL DEFAULT 0,
+    output_tokens INTEGER NOT NULL DEFAULT 0,
+    request_count INTEGER NOT NULL DEFAULT 0,
+    cost REAL NOT NULL DEFAULT 0,
+    currency TEXT NOT NULL DEFAULT '',
+    imported_at TEXT NOT NULL,
+    PRIMARY KEY (day, model, key_fp)
+  );
+  CREATE INDEX IF NOT EXISTS idx_${DEEPSEEK_USAGE_ACTUALS_TABLE}_key_day
+    ON ${DEEPSEEK_USAGE_ACTUALS_TABLE} (key_fp, day);
+`;
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+function columnNames(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name));
+}
+
+/** What keeps the import from using the table: '' when nothing does. */
+export function deepseekUsageActualsProblem(db) {
+  if (!tableExists(db, DEEPSEEK_USAGE_ACTUALS_TABLE)) return `no ${DEEPSEEK_USAGE_ACTUALS_TABLE} table`;
+  const present = columnNames(db, DEEPSEEK_USAGE_ACTUALS_TABLE);
+  const missing = DEEPSEEK_USAGE_ACTUALS_COLUMNS.filter((name) => !present.has(name));
+  if (missing.length) return `${DEEPSEEK_USAGE_ACTUALS_TABLE} lacks ${missing.join(', ')}`;
+  return '';
+}
+
+export function migrateDeepSeekUsageActuals(db) {
+  const existed = tableExists(db, DEEPSEEK_USAGE_ACTUALS_TABLE);
+  db.exec(CREATE_SQL);
+  return { applied: !existed, tableCreated: !existed };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateDeepSeekUsageActuals(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0030 on ${dbPath}`);
+    console.log(result.applied
+      ? '  deepseek usage actuals: table created'
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0030 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}