Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

feat(server): 用量成本在写入用量行时就定格

lmliheng6c30e14aca46
diff --git a/changelog/unreleased/2026-10-08-usage-cost-at-record-time.md b/changelog/unreleased/2026-10-08-usage-cost-at-record-time.md
new file mode 100644
index 00000000..1d1ee415
--- /dev/null
+++ b/changelog/unreleased/2026-10-08-usage-cost-at-record-time.md
@@ -0,0 +1,62 @@
+# A request's cost is fixed when its usage row is written
+
+- **Date:** 2026-10-08
+- **Type:** feature
+- **Scope:** `server`
+- **Breaking:** yes — a price change no longer re-prices usage already recorded
+
+[中文版](2026-10-08-usage-cost-at-record-time.zh.md)
+
+Each usage record now carries the cost of the Request it summarises, fixed at the moment the row is
+written, at the price the Project stores for that paired reference then. Editing a price, running
+**Sync presets**, or a promotion starting or ending changes only what later Requests cost: the cost
+center, the conversation toolbar, `penguin cost` and company-mode budgets sum the stored costs, and
+none of their queries looks a price up any more.
+
+## Server
+
+- `db/schema.ts` and migration **14** `usage-record-cost` add `cost` (REAL; NULL = the model has no
+ price) and `cost_settled` (INTEGER, default 0) to `usage_records`, via `ensureColumn` so a
+ declarative-track database that already has them is untouched. The migration deliberately does not
+ cost the rows already there: pricing them needs each Project's config, which SQLite does not have.
+- `db/repos/usage.ts`: `insert` writes both columns; the aggregates sum `cost` and count `uncosted`
+ instead of returning raw Token sums, so a group's cost is the bill and `hasUncosted` still flags a
+ lower bound. `unsettledRefs` / `unsettledRows` / `settle` drive the one-time compatibility pass.
+- `runtime/usage-recorder.ts` prices each row from `ProjectConfigStore.getPricing(projectId,
+ provider, modelId, at)` at its own clock's instant, and takes that as the bill. A price that
+ cannot be read counts as no price: the row is written anyway, since losing the Tokens would be
+ worse than not costing them.
+- `services/project-config-service.ts`: `getPricing` now takes the instant and returns the one rate
+ in force then — the stored price, less the row's promotion, at the tier that instant falls in
+ (`scheduledRateAt`, next to the existing `promotedRates`). A hand-typed price is billed as typed in
+ both tiers: nothing here knows whether it is a peak rate, and halving it would invent a discount.
+- `services/usage-service.ts`: the queries no longer price anything; a row's cost is what the
+ recorder fixed. `lifetimeCost` (the admin backend's per-account cost column) is the same recorded
+ sum, one unfiltered grouped scan.
+- `services/trace-service.ts`: the Trace page is unchanged in kind — it still prices each Request at
+ the Project's current price, at that Request's own timestamp (memoized per hour and reference), so
+ after a price change it can differ from the cost center, which stays the bill.
+
+## Compatibility
+
+Rows written before this change carry no cost. `Startup` settles them once, before anything reads the
+cost center (`UsageService.settleUnsettledCosts`, idempotent, keyed on `cost_settled`), at the price
+each Project stores now and at the tier each row's own timestamp fell in. A failure is recorded
+(`usage_cost_settle_failed`) rather than thrown, and those rows then read as uncosted until a later
+boot. Remove `cost_settled` and the settle two releases after this one.
+
+## Deliberately not adopted from upstream
+
+This is upstream's `feat/usage-cost-at-record-time`, still unmerged, of which only the server half is
+taken — in this tree the per-row promotion lives in `web.db`'s `model_promotions` table, which the
+core process cannot read, so core cannot stamp the rate a Request was billed at on its `token_usage`
+event. Left out, with the reason:
+
+- Core's `token_usage.pricing` stamp and the `resolveBilledPricing` / `billedRates` helpers that read
+ it. With the promotion in `web.db`, core sees only the file's list price, so a stamped rate would
+ bill every promoted row at full price.
+- The catalog's `discountUntil` / `discountRateAt`. A promotion here is a row in `model_promotions`
+ with no end instant, so a time-bounded discount has nowhere to live yet.
+
+The complete version of this feature would move the promotion into the Project's own config beside
+the list price and let core stamp the rate. That is a product decision, not a mechanical port.
diff --git a/changelog/unreleased/2026-10-08-usage-cost-at-record-time.zh.md b/changelog/unreleased/2026-10-08-usage-cost-at-record-time.zh.md
new file mode 100644
index 00000000..84a82971
--- /dev/null
+++ b/changelog/unreleased/2026-10-08-usage-cost-at-record-time.zh.md
@@ -0,0 +1,54 @@
+# 请求成本在写入用量行时就定格
+
+- **Date:** 2026-10-08
+- **Type:** feature
+- **Scope:** `server`
+- **Breaking:** yes — 改价不再重算已记录的用量
+
+[English](2026-10-08-usage-cost-at-record-time.md)
+
+每条用量记录现在都带上它所代表那次请求的成本,在写入这一行的那一刻、按 Project 当时为这个
+provider/model 组合存下的价格定格。改价、执行**同步预置**、促销开始或结束,都只影响之后的请求:
+成本中心、对话页工具栏、`penguin cost` 与公司模式预算都改为加总存下的成本,查询时一律不再取价。
+
+## 服务端
+
+- `db/schema.ts` 与迁移 **14** `usage-record-cost` 给 `usage_records` 加上 `cost`(REAL,
+ NULL = 该模型没有价格)与 `cost_settled`(INTEGER,默认 0),走 `ensureColumn` —— 声明式那条
+ 轨道已经加过这两列的库不受影响。迁移本身**有意不给已有行算成本**:算它要读每个 Project 的配置,
+ SQLite 里没有。
+- `db/repos/usage.ts`:`insert` 同时写入这两列;聚合改为对 `cost` 求和、统计 `uncosted`,不再返回
+ 原始 token 汇总 —— 于是每组的成本就是账单,`hasUncosted` 仍然说明它只是下限。
+ `unsettledRefs` / `unsettledRows` / `settle` 支撑那一次性的兼容补算。
+- `runtime/usage-recorder.ts` 按自己的时钟时刻调用 `ProjectConfigStore.getPricing(projectId,
+ provider, modelId, at)` 给每一行定价,并把它当作账单。取价失败按「没有价格」处理:这一行照写,
+ 丢掉 token 比不记账更糟。
+- `services/project-config-service.ts`:`getPricing` 现在多收一个时刻,返回那一刻实际生效的单一费率
+ —— 存下的价格、扣掉该行的促销、再按那一刻落在的分时段档位折算(新增的 `scheduledRateAt`,与既有的
+ `promotedRates` 并列)。手工改过的价格在两个档位都按原样计费:这里并不知道它是不是高峰价,
+ 减半等于凭空造出一个折扣。
+- `services/usage-service.ts`:查询不再做任何定价,成本就是 recorder 定格的那个数。`lifetimeCost`
+ (管理后台每账号的开销列)也是同一个「已记录成本」求和,一句不带筛选的分组扫描。
+- `services/trace-service.ts`:Trace 页的性质不变 —— 仍按 Project 当前价格、以每个请求自己的
+ 时间戳定价(按小时与 provider/model 记忆化),所以改价之后它可以与成本中心不同,而账单以成本中心为准。
+
+## 兼容性
+
+升级前的用量记录没有成本。`Startup` 会在任何东西读取成本中心之前补算一次
+(`UsageService.settleUnsettledCosts`,幂等,以 `cost_settled` 为准):按每个 Project **现在**存的价格、
+按每一行自己时间戳所在的档位。失败会被记进错误表(`usage_cost_settle_failed`)而不是抛出,
+那些行在此后的一次启动前一直读作「未计价」。这个补算与 `cost_settled` 列在本版之后两个发布上移除。
+
+## 有意未采用的上游部分
+
+这条来自上游尚未合入的 `feat/usage-cost-at-record-time`,只取了服务端那一半 —— 在我们的树里,
+逐行促销存在 `web.db` 的 `model_promotions` 表里,core 进程读不到,因此 core 无法把一次请求实际
+计费的单价盖在它的 `token_usage` 事件上。未采用的部分与理由:
+
+- core 的 `token_usage.pricing` 戳记,以及读它的 `resolveBilledPricing` / `billedRates`。促销在
+ `web.db` 里,core 只看得到文件里的牌价,盖上的费率会把每一行促销模型都按原价计费。
+- 目录的 `discountUntil` / `discountRateAt`。这里的促销是 `model_promotions` 里的一行、没有截止时刻,
+ 带时限的折扣暂时无处安放。
+
+这个功能的完整形态是把促销搬进 Project 自己的配置、与牌价并排存放,再由 core 盖戳费率。
+那是一个产品决定,不是一次机械移植。
diff --git a/packages/server/src/db/migrations.ts b/packages/server/src/db/migrations.ts
index 33c921e9..d93cd489 100644
--- a/packages/server/src/db/migrations.ts
+++ b/packages/server/src/db/migrations.ts
@@ -554,6 +554,33 @@ export const MIGRATIONS: readonly Migration[] = [
db.exec(`DROP TABLE IF EXISTS org_desk_mentions;`);
},
},
+ {
+ version: 14,
+ name: "usage-record-cost",
+ // Two columns with defaults on usage_records, nothing existing rewritten: a platform rolled
+ // back to a predecessor that does not know them keeps inserting rows without a cost, which
+ // simply read unsettled (cost_settled 0) and are settled by the next build that boots.
+ swapSafe: true,
+ up(db) {
+ // Frozen copy of the DDL as of fixing a request's cost at record time; do not re-derive
+ // from schema.ts. ensureColumn because the declarative track may already have added them
+ // (ADOPTION). The rows already in the table are costed by the startup settle
+ // (UsageService.settleUnsettledCosts), not here: pricing them needs each Project's config.
+ ensureColumn(db, "usage_records", "cost", "REAL");
+ ensureColumn(db, "usage_records", "cost_settled", "INTEGER NOT NULL DEFAULT 0");
+ },
+ // LOSES every fixed cost. A build with this migration adds the columns back unsettled and
+ // costs every row again at startup, at the prices the Projects store by then — so a price
+ // changed in between re-prices history, the one thing the columns exist to prevent.
+ // Dropped in reverse order for symmetry with `up`; neither column is indexed, which is what
+ // lets SQLite drop them at all.
+ down(db) {
+ const cols = db.prepare("PRAGMA table_info(usage_records)").all() as { name: string }[];
+ const has = (name: string): boolean => cols.some((c) => c.name === name);
+ if (has("cost_settled")) db.exec("ALTER TABLE usage_records DROP COLUMN cost_settled");
+ if (has("cost")) db.exec("ALTER TABLE usage_records DROP COLUMN cost");
+ },
+ },
];
/** The highest version this build knows how to reach. */
diff --git a/packages/server/src/db/repos/usage.ts b/packages/server/src/db/repos/usage.ts
index f34f5f35..a45a0fe2 100644
--- a/packages/server/src/db/repos/usage.ts
+++ b/packages/server/src/db/repos/usage.ts
@@ -1,9 +1,9 @@
/**
* usage_records table repo:
- * one row per token_usage (per-request bucket). Stores Token counts only, not cost —
- * cost is computed on the fly by usage-service against current pricing at query time,
- * so every aggregation is broken down by the `(provider, model_id)` pair and returns
- * raw Token sums (a model_id shared across providers is aggregated separately; never concatenated).
+ * one row per token_usage (per-request bucket), with the Request's cost fixed when the row is
+ * written (see usage-recorder) — no aggregation re-prices anything, it sums what was recorded.
+ * Every aggregation is still broken down by the `(provider, model_id)` pair (a model_id shared
+ * across providers is aggregated separately; never concatenated).
*/
import type { UsageGroupBy } from "../../api/types.js";
import { Component, Use } from "@lmliheng/penguin-core/kernel";
@@ -27,6 +27,8 @@ export interface UsageRecordInsert {
total: number;
/** Request outcome; defaults to completed (success, carries tokens). Failed requests are stored with 0 tokens + status, for success-rate calculations. */
status?: string;
+ /** The Request's cost in USD, fixed now and never re-derived; null = the model had no price. */
+ cost: number | null;
}
/** Generic filter: date range + agent / model dimensions (cost center top bar switches by agent/model). */
@@ -53,26 +55,19 @@ export interface UsageModelSums {
output: number;
total: number;
requests: number;
- /**
- * Which tier of a time-based price these Tokens ran in, decided from each record's own `ts`.
- *
- * A model with no schedule has one price and every row reports `true`. A scheduled one is
- * summed into two rows per reference, so a week that straddles the boundary is priced at the
- * rate each request actually ran at — rather than at whichever tier happens to be in force
- * when someone opens the page, which would move a finished week's cost twice a day.
- */
- peak: boolean;
+ /** Sum of the recorded costs (USD); null when no row in the group has one. */
+ cost: number | null;
+ /** Rows in the group with no recorded cost — the model had no price — which makes `cost` a lower bound. */
+ uncosted: number;
}
-/** A time-based price to split an aggregation by: which references carry it, and when it is peak. */
-export interface PeakTier {
- refs: ReadonlyArray<{ provider: string; modelId: string }>;
- /** Minutes east of UTC the schedule's local hours are written in. */
- utcOffsetMinutes: number;
- /** ISO weekday numbers the windows apply to; a day not listed is off-peak throughout. */
- peakDays: readonly number[];
- /** `[startHour, endHour)` in the schedule's own local hours. */
- peakHours: readonly (readonly [number, number])[];
+/** One usage row still waiting for its cost (see UsageRepo.unsettledRows). */
+export interface UnsettledUsageRow {
+ id: number;
+ ts: string;
+ cacheRead: number;
+ cacheWrite: number;
+ output: number;
}
/** Raw Token sums by group key x Model. */
@@ -131,57 +126,25 @@ const GROUP_COLUMNS: Record<UsageGroupBy, string> = {
session: "session_id",
};
-/**
- * A `1`/`0` expression naming the tier a row's own `ts` fell in, for the references that have
- * one; every other row is `1`, the single price it has.
- *
- * Written from the schedule rather than hardcoded so a second vendor's windows cost one more
- * entry and no more SQL. The hours compare as integers because a window boundary is a whole
- * hour in every schedule the catalog can express; a half-hour boundary would need the minutes.
- * Literals only — the numbers come from the catalog and the references are bound.
- */
-function peakExpr(tiers: readonly PeakTier[]): { sql: string; params: Record<string, string> } {
- if (tiers.length === 0) return { sql: "1", params: {} };
- const params: Record<string, string> = {};
- const branches: string[] = [];
- tiers.forEach((tier, ti) => {
- if (tier.refs.length === 0 || tier.peakDays.length === 0) return;
- const shift = `'${tier.utcOffsetMinutes >= 0 ? "+" : "-"}${Math.abs(tier.utcOffsetMinutes)} minutes'`;
- const refs = tier.refs.map((ref, ri) => {
- const p = `t${ti}p${ri}`;
- const m = `t${ti}m${ri}`;
- params[p] = ref.provider;
- params[m] = ref.modelId;
- return `(provider = :${p} AND model_id = :${m})`;
- });
- // `%w` is 0=Sunday; the schedule counts ISO days, so Sunday maps to 7.
- const day = `CASE CAST(strftime('%w', ts, ${shift}) AS INTEGER) WHEN 0 THEN 7 ELSE CAST(strftime('%w', ts, ${shift}) AS INTEGER) END`;
- const hour = `CAST(strftime('%H', ts, ${shift}) AS INTEGER)`;
- const windows = tier.peakHours.map(([from, to]) => `(${hour} >= ${from} AND ${hour} < ${to})`);
- branches.push(
- `WHEN (${refs.join(" OR ")}) THEN (CASE WHEN ${day} IN (${tier.peakDays.join(", ")}) AND (${windows.join(" OR ")}) THEN 1 ELSE 0 END)`,
- );
- });
- if (branches.length === 0) return { sql: "1", params: {} };
- return { sql: `CASE ${branches.join(" ")} ELSE 1 END`, params };
-}
-
const SUM_COLUMNS = `COALESCE(SUM(cache_read), 0) AS cache_read,
COALESCE(SUM(cache_write), 0) AS cache_write,
COALESCE(SUM(output), 0) AS output,
COALESCE(SUM(total), 0) AS total,
- COUNT(*) AS requests`;
+ COUNT(*) AS requests,
+ SUM(cost) AS cost,
+ COUNT(*) - COUNT(cost) AS uncosted`;
function toSums(r: Record<string, unknown>): UsageModelSums {
return {
provider: r.provider as string,
modelId: r.model_id as string,
- peak: r.peak !== 0,
cacheRead: r.cache_read as number,
cacheWrite: r.cache_write as number,
output: r.output as number,
total: r.total as number,
requests: r.requests as number,
+ cost: r.cost === null || r.cost === undefined ? null : (r.cost as number),
+ uncosted: r.uncosted as number,
};
}
@@ -194,8 +157,8 @@ export class UsageRepo implements UsageStore {
.prepare(
`INSERT INTO usage_records
(ts, date, project_id, agent_id, session_id, origin_session_id, provider, model_id,
- cache_read, cache_write, output, total, status)
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+ cache_read, cache_write, output, total, status, cost, cost_settled)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1)`,
)
.run(
r.ts,
@@ -211,9 +174,60 @@ export class UsageRepo implements UsageStore {
r.output,
r.total,
r.status ?? "completed",
+ r.cost,
);
}
+ /**
+ * The paired references (per Project) that still have rows without a fixed cost: rows written
+ * before costs were fixed at record time, or by an older build a hot update rolled back to.
+ */
+ unsettledRefs(): Array<{ projectId: string; provider: string; modelId: string }> {
+ const rows = this.db
+ .prepare(
+ `SELECT DISTINCT project_id, provider, model_id FROM usage_records WHERE cost_settled = 0`,
+ )
+ .all();
+ return rows.map((r) => ({
+ projectId: r.project_id as string,
+ provider: r.provider as string,
+ modelId: r.model_id as string,
+ }));
+ }
+
+ /** One reference's rows still without a fixed cost, with what pricing them needs. */
+ unsettledRows(projectId: string, provider: string, modelId: string): UnsettledUsageRow[] {
+ const rows = this.db
+ .prepare(
+ `SELECT id, ts, cache_read, cache_write, output FROM usage_records
+ WHERE cost_settled = 0 AND project_id = ? AND provider = ? AND model_id = ?`,
+ )
+ .all(projectId, provider, modelId);
+ return rows.map((r) => ({
+ id: r.id as number,
+ ts: r.ts as string,
+ cacheRead: r.cache_read as number,
+ cacheWrite: r.cache_write as number,
+ output: r.output as number,
+ }));
+ }
+
+ /** Fixes the given rows' costs in one transaction; a row settled in the meantime is left alone. */
+ settle(rows: ReadonlyArray<{ id: number; cost: number | null }>): void {
+ if (rows.length === 0) return;
+ const stmt = this.db.prepare(
+ "UPDATE usage_records SET cost = ?, cost_settled = 1 WHERE id = ? AND cost_settled = 0",
+ );
+ this.db.exec("BEGIN IMMEDIATE");
+ try {
+ for (const r of rows) stmt.run(r.cost, r.id);
+ this.db.exec("COMMIT");
+ } catch (err) {
+ this.db.exec("ROLLBACK");
+ throw err;
+ }
+ }
+
/** WHERE fragment (project + optional date/agent/model) plus named params. */
private conds(
projectId: string,
@@ -263,24 +277,16 @@ export class UsageRepo implements UsageStore {
return { where: conds.join(" AND "), params };
}
- /**
- * Sums (broken down by paired reference, and by price tier where one applies): date range +
- * optional agent/model filter.
- */
- bucketByModel(
- projectId: string,
- f: UsageFilter = {},
- tiers: readonly PeakTier[] = [],
- ): UsageModelSums[] {
+ /** Sums (broken down by paired reference): date range + optional agent/model filter. */
+ bucketByModel(projectId: string, f: UsageFilter = {}): UsageModelSums[] {
const { where, params } = this.conds(projectId, f);
- const peak = peakExpr(tiers);
const rows = this.db
.prepare(
- `SELECT provider, model_id, ${peak.sql} AS peak, ${SUM_COLUMNS}
+ `SELECT provider, model_id, ${SUM_COLUMNS}
FROM usage_records WHERE ${where}
- GROUP BY provider, model_id, peak`,
+ GROUP BY provider, model_id`,
)
- .all({ ...params, ...peak.params });
+ .all(params);
return rows.map(toSums);
}
@@ -289,18 +295,16 @@ export class UsageRepo implements UsageStore {
projectId: string,
groupBy: UsageGroupBy,
f: UsageFilter = {},
- tiers: readonly PeakTier[] = [],
): UsageGroupModelSums[] {
const col = GROUP_COLUMNS[groupBy];
const { where, params } = this.conds(projectId, f);
- const peak = peakExpr(tiers);
const rows = this.db
.prepare(
- `SELECT ${col} AS key, provider, model_id, ${peak.sql} AS peak, ${SUM_COLUMNS}
+ `SELECT ${col} AS key, provider, model_id, ${SUM_COLUMNS}
FROM usage_records WHERE ${where}
- GROUP BY ${col}, provider, model_id, peak`,
+ GROUP BY ${col}, provider, model_id`,
)
- .all({ ...params, ...peak.params });
+ .all(params);
return rows.map((r) => ({ key: r.key as string, ...toSums(r) }));
}
@@ -314,20 +318,18 @@ export class UsageRepo implements UsageStore {
projectId: string,
granularity: UsageSeriesGranularity,
f: UsageFilter = {},
- tiers: readonly PeakTier[] = [],
): UsageSeriesModelSums[] {
const expr = BUCKET_EXPRS[granularity];
const { where, params } = this.conds(projectId, f);
- const peak = peakExpr(tiers);
const rows = this.db
.prepare(
- `SELECT ${expr} AS key, provider, model_id, ${peak.sql} AS peak, ${SUM_COLUMNS},
+ `SELECT ${expr} AS key, provider, model_id, ${SUM_COLUMNS},
COALESCE(SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END), 0) AS completed,
COALESCE(SUM(CASE WHEN status <> 'aborted' THEN 1 ELSE 0 END), 0) AS denominator
FROM usage_records WHERE ${where}
- GROUP BY key, provider, model_id, peak`,
+ GROUP BY key, provider, model_id`,
)
- .all({ ...params, ...peak.params });
+ .all(params);
return rows.map((r) => ({
key: r.key as string,
...toSums(r),
diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.ts
index 1cc2d24a..b9a0068e 100644
--- a/packages/server/src/db/schema.ts
+++ b/packages/server/src/db/schema.ts
@@ -110,8 +110,10 @@ CREATE TABLE IF NOT EXISTS usage_records (
cache_write INTEGER NOT NULL,
output INTEGER NOT NULL,
total INTEGER NOT NULL, -- from token_usage.request (one row per Request)
- status TEXT NOT NULL DEFAULT 'completed' -- request outcome: completed=success (with tokens); others=failure (0 tokens, for success rate)
-); -- cost is not stored: computed at query time from current pricing
+ status TEXT NOT NULL DEFAULT 'completed', -- request outcome: completed=success (with tokens); others=failure (0 tokens, for success rate)
+ cost REAL, -- USD, fixed by the recorder when the row is written, from the price the Project stores at that instant; NULL = the model has no price (or the row is not settled yet)
+ cost_settled INTEGER NOT NULL DEFAULT 0 -- 1 once cost is fixed; 0 = written by a build that did not price rows (settled once at startup)
+); -- rebuildable from the Traces: the token counts still come from token_usage
CREATE INDEX IF NOT EXISTS idx_usage_project_date ON usage_records(project_id, date);
CREATE INDEX IF NOT EXISTS idx_usage_session_ts ON usage_records(session_id, ts); -- (session_id) alone was idx_usage_session (dropped on open): ts makes the last_active_at backfill's MAX(ts) a covering index scan instead of a random row lookup per usage record
CREATE TABLE IF NOT EXISTS error_records ( -- server-side error capture (the Costs page's "Errors" tab)
diff --git a/packages/server/src/mechanisms/observability.ts b/packages/server/src/mechanisms/observability.ts
index 9f84ddcc..eca4a6b7 100644
--- a/packages/server/src/mechanisms/observability.ts
+++ b/packages/server/src/mechanisms/observability.ts
@@ -19,7 +19,7 @@ import type {
UsageRecordInsert,
UsageSeriesGranularity,
UsageSeriesModelSums,
- PeakTier,
+ UnsettledUsageRow,
} from "../db/repos/usage.js";
import type {
UsageErrorsPage,
@@ -90,22 +90,19 @@ export abstract class Errors {
@Interface()
export abstract class UsageStore {
abstract insert(r: UsageRecordInsert): void;
- abstract bucketByModel(
- projectId: string,
- f?: UsageFilter,
- tiers?: readonly PeakTier[],
- ): UsageModelSums[];
+ abstract unsettledRefs(): Array<{ projectId: string; provider: string; modelId: string }>;
+ abstract unsettledRows(projectId: string, provider: string, modelId: string): UnsettledUsageRow[];
+ abstract settle(rows: ReadonlyArray<{ id: number; cost: number | null }>): void;
+ abstract bucketByModel(projectId: string, f?: UsageFilter): UsageModelSums[];
abstract groupsByModel(
projectId: string,
groupBy: UsageGroupBy,
f?: UsageFilter,
- tiers?: readonly PeakTier[],
): UsageGroupModelSums[];
abstract seriesByModel(
projectId: string,
granularity: UsageSeriesGranularity,
f?: UsageFilter,
- tiers?: readonly PeakTier[],
): UsageSeriesModelSums[];
abstract agentSeries(
projectId: string,
@@ -130,10 +127,12 @@ export abstract class UsageQueries {
abstract queryErrors(projectId: string, q: UsageErrorsQuery): UsageErrorsPage;
abstract clearErrors(projectId: string, q: UsageErrorsClearQuery): number;
abstract modelTotals(projectId: string): UsageModelTotals;
+ /** Fixes the cost of every usage row that has none yet; returns how many it settled. */
+ abstract settleUnsettledCosts(): Promise<number>;
/**
- * The Project's lifetime cost: every usage record it ever wrote, folded with the same
- * per-reference rate lookup `query` uses (current prices). `unpriced` says some of that usage
- * ran on a model this Project has no price for, so `cost` is a lower bound.
+ * The Project's lifetime cost: every usage record it ever wrote, summed from the costs fixed
+ * when the rows were written. `unpriced` says some of that usage ran on a model this Project
+ * has no price for, so `cost` is a lower bound.
*/
abstract lifetimeCost(
projectId: string,
diff --git a/packages/server/src/mechanisms/projects.ts b/packages/server/src/mechanisms/projects.ts
index 75d38e11..bb5ee84f 100644
--- a/packages/server/src/mechanisms/projects.ts
+++ b/packages/server/src/mechanisms/projects.ts
@@ -33,7 +33,7 @@ import type {
PluginTables,
ProjectConfig,
} from "@lmliheng/penguin-core";
-import type { TieredRates } from "../services/usage-service.js";
+import type { PricingRates } from "../services/usage-service.js";
import type {
PlatformModelApplyResult,
PlatformModelCatalog,
@@ -145,7 +145,8 @@ export abstract class ProjectConfigStore {
projectId: string,
provider: string,
modelId: string,
- ): Promise<TieredRates | undefined>;
+ at: Date,
+ ): Promise<PricingRates | undefined>;
abstract detectVision(
projectId: string,
req: ModelVisionDetectRequest,
diff --git a/packages/server/src/platform.ts b/packages/server/src/platform.ts
index 56aff570..fc0c13fd 100644
--- a/packages/server/src/platform.ts
+++ b/packages/server/src/platform.ts
@@ -198,6 +198,7 @@ export class Startup {
@Use() private readonly machines!: Machines;
@Use() private readonly errors!: Errors;
@Use() private readonly projectConfig!: ProjectConfigStore;
+ @Use() private readonly usage!: UsageQueries;
async setup() {
// The shared default Project's display name, on every start rather than only where it is
@@ -206,6 +207,15 @@ export class Startup {
// showing the raw id as the Project's label. Idempotent and file-guarded — a root without
// that Project's config file is untouched, so nothing is ever created here.
await this.projectConfig.ensureDisplayName(DEFAULT_PROJECT_ID, DEFAULT_PROJECT_NAME);
+ // Usage rows with no fixed cost yet — from before costs were fixed at record time, or
+ // written by an older build a hot update rolled back to — are costed once, before anything
+ // reads the cost center (COMPATIBILITY: see UsageService.settleUnsettledCosts). Awaited, but
+ // a failure is recorded rather than thrown: the rows then read as uncosted until a later boot.
+ try {
+ await this.usage.settleUnsettledCosts();
+ } catch (err) {
+ this.errors.record({ source: "process", err, code: "usage_cost_settle_failed" });
+ }
// Schedule scheduler: startup reconciliation (missed, don't backfill) + periodic scan.
await this.scheduler.start();
// Company mode's scheduler: same lifetime and the same startup rule (reconcile once,
diff --git a/packages/server/src/runtime/usage-recorder.ts b/packages/server/src/runtime/usage-recorder.ts
index 5664e971..47cb76c5 100644
--- a/packages/server/src/runtime/usage-recorder.ts
+++ b/packages/server/src/runtime/usage-recorder.ts
@@ -7,9 +7,14 @@
* cost is priced against the actual Model used);
* - `token_usage` → inserts one usage_records row: the four token fields come from
* `payload.request` (per-Request increment; subagents are recorded one row at a
- * time, with `session_id` attributed to their owning main Session). Only tokens are
- * persisted, not cost — pricing may be added later, and cost is computed on the fly
- * against current pricing when usage-service queries.
+ * time, with `session_id` attributed to their owning main Session), and the Request's
+ * cost is FIXED here, from the price the Project stores for that paired reference at
+ * this instant. Nothing re-prices a row afterwards: a later price edit, preset sync or
+ * promotion only changes what later Requests cost.
+ *
+ * The price is read from the Project's own config (getPricing, which folds in the row's
+ * promotion), not from the rates a `token_usage` event may carry: a promotion lives in
+ * web.db beside the file's list price, so only this side can state what a Request was billed.
* The attribution key is always the paired reference `(provider, model_id)` (the same
* model_id name across different vendors is attributed separately).
*/
@@ -19,6 +24,9 @@ import { formatLocalDate } from "../internal/dates.js";
import { Component, Use } from "@lmliheng/penguin-core/kernel";
import type { Clock } from "../hmr/capabilities.js";
import type { UsageRecording, UsageStore } from "../mechanisms/observability.js";
+import type { ProjectConfigStore } from "../mechanisms/projects.js";
+import { requestCostUsd } from "../services/usage-service.js";
+import type { PricingLookup } from "../services/usage-service.js";
/** Attribution context for one record (top-level Session scope). */
export interface UsageContext {
@@ -42,6 +50,30 @@ export class UsageRecorder implements UsageRecording {
@Use() private readonly usage!: UsageStore;
@Use() private readonly clock!: Clock;
+ @Use() private readonly projectConfig!: ProjectConfigStore;
+ private lookupPricing: PricingLookup = (projectId, provider, modelId, at) =>
+ this.projectConfig.getPricing(projectId, provider, modelId, at);
+
+ /**
+ * A record's cost, fixed now: the three buckets at the price the Project stores for this
+ * reference at this instant — `null` when it stores none (an uncosted model). A price that
+ * cannot be read counts as no price: the row is written either way, since losing the Tokens
+ * would be worse than not costing them.
+ */
+ private async costOf(
+ projectId: string,
+ ref: { provider: string; modelId: string },
+ counts: { cacheRead: number; cacheWrite: number; output: number },
+ at: Date,
+ ): Promise<number | null> {
+ try {
+ const rates = await this.lookupPricing(projectId, ref.provider, ref.modelId, at);
+ if (rates === undefined) return null;
+ return requestCostUsd(counts, rates);
+ } catch {
+ return null;
+ }
+ }
/** Consume one outgoing message; messages other than session_meta / token_usage are a no-op. */
async record(ctx: UsageContext, msg: OmniMessage): Promise<void> {
@@ -91,12 +123,12 @@ export class UsageRecorder implements UsageRecording {
if (payload.type === "token_usage" && payload.request) {
// A successful request: persist along with tokens (status defaults to completed).
const r = payload.request;
+ const counts = { cacheRead: r.cache_read, cacheWrite: r.cache_write, output: r.output };
this.usage.insert({
...base,
- cacheRead: r.cache_read,
- cacheWrite: r.cache_write,
- output: r.output,
+ ...counts,
total: r.total,
+ cost: await this.costOf(ctx.projectId, ref, counts, now),
});
return;
}
@@ -104,13 +136,14 @@ export class UsageRecorder implements UsageRecording {
// persist 0 tokens + status, feeding the "model success rate" stat; a successful
// request is already counted once via the token_usage branch above, not repeated here.
if (payload.type === "request_end" && payload.status && payload.status !== "completed") {
+ const counts = { cacheRead: 0, cacheWrite: 0, output: 0 };
this.usage.insert({
...base,
- cacheRead: 0,
- cacheWrite: 0,
- output: 0,
+ ...counts,
total: 0,
status: payload.status,
+ // Zero, not null, for a priced model: nothing was billed, and the group is not uncosted.
+ cost: await this.costOf(ctx.projectId, ref, counts, now),
});
}
}
diff --git a/packages/server/src/services/admin-service.ts b/packages/server/src/services/admin-service.ts
index 61bd18fd..df247e0f 100644
--- a/packages/server/src/services/admin-service.ts
+++ b/packages/server/src/services/admin-service.ts
@@ -43,11 +43,11 @@ export class AdminService implements Admin {
* avatar is a data URL of up to 128 KiB and this list is unpaged, so carrying one per account
* would answer a table that only shows the nickname with megabytes.
*
- * The cost is summed per Project because pricing is per Project (each one carries its own
- * configured rates), and it is read at the CURRENT rates for every record ever written — the
- * one figure the cost center's "cumulative" card shows, extended over everything the account
- * owns. `costUnpriced` travels with it: a Model this deployment has no price for makes the sum
- * a lower bound, and a table that presented it as exact would overstate its own accuracy.
+ * The cost is summed per Project because a Project is what carries the price a Request was
+ * billed at, and every record contributes the cost fixed when it was written — the one figure
+ * the cost center's "cumulative" card shows, extended over everything the account owns.
+ * `costUnpriced` travels with it: a Model this deployment had no price for makes the sum a
+ * lower bound, and a table that presented it as exact would overstate its own accuracy.
*/
async listUsers(): Promise<UserInfo[]> {
const out: UserInfo[] = [];
diff --git a/packages/server/src/services/project-config-service.ts b/packages/server/src/services/project-config-service.ts
index f1369f69..b65a0888 100644
--- a/packages/server/src/services/project-config-service.ts
+++ b/packages/server/src/services/project-config-service.ts
@@ -43,6 +43,7 @@ import {
defaultProjectConfig,
imageUrlMessage,
metaMaxTokens,
+ offPeakAt,
presetPromotions,
projectConfigFromTable,
projectConfigPath,
@@ -103,7 +104,7 @@ import {
classifyVisionProbe,
classifyVisionProbeError,
} from "./vision-detect.js";
-import type { PricingRates, TieredRates } from "./usage-service.js";
+import type { PricingRates } from "./usage-service.js";
import { Component, Use } from "@lmliheng/penguin-core/kernel";
import type { Config, Paths } from "../hmr/capabilities.js";
import type {
@@ -190,40 +191,33 @@ function promotedRates(rates: PricingRates, discount: number): PricingRates {
}
/**
- * Both tiers of a price read from a Project's config.
+ * A price read from a Project's config, at the instant it is billed.
*
* A scheduled row stores its PEAK price — the one number that is true whatever hour it is
- * written — and the reduced rate is derived here. Both are returned rather than one of them
- * chosen, because the caller prices a RANGE: a week that straddles a boundary holds Tokens of
- * both kinds, and each is billed at the rate it actually ran at. Choosing here would mean
- * pricing a finished week at whichever tier happened to be in force when someone opened the
- * page, which moves a settled number twice a day.
- *
- * The two tiers differ only while the stored price is still exactly the catalog's peak: once
- * the user has typed their own number, nothing here knows whether it is a peak rate, and
+ * written — and the reduced tier is derived here, from the instant the Request completed or the
+ * record ran. The two differ only while the stored price is still exactly the catalog's peak:
+ * once the user has typed their own number, nothing here knows whether it is a peak rate, and
* halving it would invent a discount. The models page's badge bails on the same condition, so
* the card and the bill always agree about what this row costs.
*/
-function tieredRates(provider: string, modelId: string, rates: PricingRates): TieredRates {
+function scheduledRateAt(
+ provider: string,
+ modelId: string,
+ rates: PricingRates,
+ at: Date,
+): PricingRates {
const entry = catalogEntryFor(provider, modelId);
const schedule = entry?.offPeakDiscount;
- if (schedule === undefined || entry?.pricing === undefined)
- return { peak: rates, offPeak: rates };
+ if (schedule === undefined || entry?.pricing === undefined || Number.isNaN(at.getTime())) {
+ return rates;
+ }
const peak = entry.pricing;
const untouched =
rates.cacheRead === peak.cache_read &&
rates.cacheWrite === peak.cache_write &&
rates.output === peak.output;
- if (!untouched) return { peak: rates, offPeak: rates };
- const off = (v: number): number => Math.round(v * (1 - schedule.rate) * 1e6) / 1e6;
- return {
- peak: rates,
- offPeak: {
- cacheRead: off(rates.cacheRead),
- cacheWrite: off(rates.cacheWrite),
- output: off(rates.output),
- },
- };
+ if (!untouched || !offPeakAt(schedule, at)) return rates;
+ return promotedRates(rates, schedule.rate);
}
function optStr(v: unknown): string | undefined {
@@ -777,26 +771,25 @@ export class ProjectConfigService implements ProjectConfigStore {
}
/**
- * Pricing lookup for usage-recorder: the current pricing for this paired reference (undefined
- * if none -> cost is NULL). The file holds the list price; a stored promotion takes its
- * fraction off both tiers, so a scheduled row on a promotion bills the two factors multiplied.
+ * The price a Request on this paired reference is billed at, completing at `at`, or undefined
+ * when the Project stores no price for it (-> the record's cost is NULL). The file holds the
+ * list price and the row's promotion its fraction; both are folded here, at the tier `at` falls
+ * in, so the recorder fixes a Request's cost with the one figure in force when it completed and
+ * the Trace page can ask the same question at a past Request's own timestamp.
*/
async getPricing(
projectId: string,
provider: string,
modelId: string,
- ): Promise<TieredRates | undefined> {
+ at: Date,
+ ): Promise<PricingRates | undefined> {
const raw = await this.readRaw(projectId);
const entry = asArray(raw.models).find((m) => entryMatches(m, provider, modelId));
const rates = pricingDtoOf(entry?.pricing);
if (rates === undefined) return undefined;
- const tiered = tieredRates(provider, modelId, rates);
+ const scheduled = scheduledRateAt(provider, modelId, rates, at);
const discount = this.promotions?.get(projectId, provider, modelId);
- if (discount === undefined) return tiered;
- return {
- peak: promotedRates(tiered.peak, discount),
- offPeak: promotedRates(tiered.offPeak, discount),
- };
+ return discount === undefined ? scheduled : promotedRates(scheduled, discount);
}
/**
diff --git a/packages/server/src/services/trace-service.ts b/packages/server/src/services/trace-service.ts
index fca177cd..cf4d92f6 100644
--- a/packages/server/src/services/trace-service.ts
+++ b/packages/server/src/services/trace-service.ts
@@ -54,8 +54,8 @@ import type { SessionRow } from "../db/repos/sessions.js";
import type { TraceFileRow, TraceSessionRow } from "../db/repos/trace-index.js";
import { HttpError } from "../http/errors.js";
import { formatLocalDate } from "../internal/dates.js";
-import { ratesAt, requestCostUsd } from "./usage-service.js";
-import type { PricingLookup, TieredRates } from "./usage-service.js";
+import { requestCostUsd } from "./usage-service.js";
+import type { PricingLookup, PricingRates } from "./usage-service.js";
import type { ProjectConfigStore } from "../mechanisms/projects.js";
import {
cloneScanState,
@@ -289,13 +289,14 @@ export class TraceService implements Traces {
@Use() private readonly sources?: SessionOrigins;
@Use() private readonly projectConfig?: ProjectConfigStore;
/**
- * The Project's current price for a paired reference — the same lookup the cost center
- * prices `usage_records` with, so the analysis' per-turn cost and the toolbar's figure come
- * from one price table. Narrow tests wire their own or none; without a price the analysis
- * carries no cost at all.
+ * What the Project bills for a paired reference, at the instant asked for. The analysis answers
+ * "what these Requests are worth at today's price": each Request is priced with this, at its own
+ * timestamp's tier — it never reads the rates the Request recorded, so after a price change it
+ * can differ from the cost center's fixed figures, which stay the bill. Narrow tests wire their
+ * own or none; without it the analysis carries no cost at all.
*/
- private lookupPricing: PricingLookup = async (projectId, provider, modelId) =>
- this.projectConfig?.getPricing(projectId, provider, modelId);
+ private lookupPricing: PricingLookup = async (projectId, provider, modelId, at) =>
+ this.projectConfig?.getPricing(projectId, provider, modelId, at);
/**
* Test observability: called with the path of every Trace shard this service reads
* from disk (windowed-read tests assert an old-window request never touches the
@@ -975,16 +976,16 @@ export class TraceService implements Traces {
}
/**
- * The price table the analysis costs a file's Requests against: the Project's current rates
- * for the model named by the file's own `session_meta` head, in both tiers. Null when there
- * is no lookup, when the model has no pricing, and for a head that names no provider — such
- * a Trace is legacy data (core refuses to resume it), and the id alone can exist under
- * several providers at different prices, so nothing is priced rather than a first match.
+ * What the analysis prices a file's Requests on: the paired reference named by the file's own
+ * `session_meta` head. Null when there is no lookup and for a head that names no provider —
+ * such a Trace is legacy data (core refuses to resume it), and the id alone can exist under
+ * several providers at different prices, so nothing is priced rather than a first match. The
+ * rate itself is asked for per Request (see analyze): it depends on that Request's timestamp.
*/
private async filePricing(
projectId: string,
meta: OmniMessage | undefined,
- ): Promise<{ provider: string; modelId: string; rates: TieredRates } | null> {
+ ): Promise<{ provider: string; modelId: string } | null> {
if (meta === undefined) return null;
const { provider, model_id: modelId } = meta.payload as {
provider?: unknown;
@@ -992,8 +993,7 @@ export class TraceService implements Traces {
};
if (typeof provider !== "string" || provider === "") return null;
if (typeof modelId !== "string" || modelId === "") return null;
- const rates = await this.lookupPricing(projectId, provider, modelId);
- return rates === undefined ? null : { provider, modelId, rates };
+ return { provider, modelId };
}
/** Performance analysis: derived from a single Trace file. */
@@ -1009,6 +1009,17 @@ export class TraceService implements Traces {
(m) => isSessionMeta(m) && (m.origin === undefined || m.origin.length === 0),
);
const pricing = await this.filePricing(projectId, meta);
+ // The rates the file's Requests are priced at, memoized by hour: a tier boundary is a whole
+ // hour in every schedule the catalog can express, so one lookup per hour a Trace spans is
+ // enough, and a long Trace does not read the Project's config once per Request. Lives only as
+ // long as this analysis.
+ const fileRates = new Map<string, PricingRates | undefined>();
+ // Whether the Project prices this reference AT ALL, which the instant does not affect
+ // (`getPricing` answers undefined only when no price is stored for it). Read off the lookups
+ // this pass already makes: a priced file states a cost for every turn — a turn with no
+ // Request included — so its cards read $0, while a file nothing could price carries no cost
+ // field at all, which is what "no price" means to the card. See the task finalize below.
+ let priced = false;
const headWindow = (meta?.payload as { model_context_window?: unknown } | undefined)
?.model_context_window;
const modelContextWindow =
@@ -1080,9 +1091,8 @@ export class TraceService implements Traces {
startTs: "",
endTs: "",
tokens: { cacheRead: 0, cacheWrite: 0, output: 0 },
- // A priced file states a cost for every turn, a turn with no Request included: the
- // card then reads $0 rather than "no price", which is what an absent field means.
- ...(pricing !== null ? { cost: 0 } : {}),
+ // `cost` is filled in below: either by the Turn's own Requests, or — for a Turn with
+ // none, on a file whose reference the Project does price — with a zero at finalize.
llmMs: 0,
toolMs: 0,
};
@@ -1362,24 +1372,32 @@ export class TraceService implements Traces {
t.tokens.cacheWrite += request?.cache_write ?? 0;
t.tokens.output += request?.output ?? 0;
if (pricing !== null) {
- // Priced per Request, at the tier this Request's own timestamp fell in — the
- // rule the cost center applies to the usage row this same event produced, so
- // the two figures for one request are the same figure.
- t.cost =
- (t.cost ?? 0) +
- requestCostUsd(
- {
- cacheRead: request?.cache_read ?? 0,
- cacheWrite: request?.cache_write ?? 0,
- output: request?.output ?? 0,
- },
- ratesAt(
- pricing.rates,
- pricing.provider,
- pricing.modelId,
- new Date(msg.timestamp),
- ),
+ // Priced per Request at the price the Project stores TODAY, at the tier that
+ // Request's own timestamp fell in (see lookupPricing) — the rule it was billed by,
+ // applied to today's price. After a price change this can therefore differ from the
+ // cost center's figure, which stays the bill.
+ const at = new Date(msg.timestamp);
+ const key = `${pricing.provider}\0${pricing.modelId}\0${Math.floor(at.getTime() / 3_600_000)}`;
+ if (!fileRates.has(key)) {
+ fileRates.set(
+ key,
+ await this.lookupPricing(projectId, pricing.provider, pricing.modelId, at),
);
+ }
+ const rates = fileRates.get(key);
+ if (rates !== undefined) {
+ priced = true;
+ t.cost =
+ (t.cost ?? 0) +
+ requestCostUsd(
+ {
+ cacheRead: request?.cache_read ?? 0,
+ cacheWrite: request?.cache_write ?? 0,
+ output: request?.output ?? 0,
+ },
+ rates,
+ );
+ }
}
if (!compactionActive) {
// The context snapshot only takes non-compaction Requests: tokens
@@ -1550,7 +1568,11 @@ export class TraceService implements Traces {
// follows above, so a reader adding up the turn cards lands on the totals.
const apiMs = tasks.reduce((sum, t) => sum + t.llmMs, 0);
const toolMs = tasks.reduce((sum, t) => sum + t.toolMs, 0);
- const cost = pricing !== null ? tasks.reduce((sum, t) => sum + (t.cost ?? 0), 0) : undefined;
+ // A file the Project prices states a cost for every Turn, including one that made no
+ // Request (a billed zero, so the card reads $0); a file it prices nothing in carries no cost
+ // at all, which the card draws as "no price". This is where `priced` decides the difference.
+ if (priced) for (const t of tasks) t.cost ??= 0;
+ const cost = priced ? tasks.reduce((sum, t) => sum + (t.cost ?? 0), 0) : undefined;
return {
elapsedMs,
apiMs,
diff --git a/packages/server/src/services/usage-service.ts b/packages/server/src/services/usage-service.ts
index 4946bd6d..40014347 100644
--- a/packages/server/src/services/usage-service.ts
+++ b/packages/server/src/services/usage-service.ts
@@ -1,12 +1,12 @@
/**
* Usage statistics query.
*
- * Cost is **computed in real time**: usage_records only stores Tokens (pricing may
- * be added later), so at query time each Model's cost is converted using the
- * current Project's configured pricing — the repo returns raw Token totals broken
- * down by `(provider, model_id)` paired reference, and this service looks up each
- * reference's price once and folds it into cost / hasUncosted (if a Model has no
- * pricing, its consumption is excluded from cost and hasUncosted is flagged).
+ * Cost is **fixed when a Request completes**: every usage_records row carries the cost the
+ * recorder computed from the rates in force at that moment, and nothing here re-prices it — a
+ * price edited, synced or discounted later only changes what later Requests cost. The repo
+ * returns sums broken down by `(provider, model_id)` paired reference, and this service folds
+ * them into cost / hasUncosted (a row whose model had no price is excluded from cost and flags
+ * hasUncosted).
* Summary cards (today / last 7 days / cumulative), grouped aggregation (date /
* agent / model / session, with the session dimension supporting agentId drill-down
* filtering), and the zero-filled time series the cost center's charts draw.
@@ -30,18 +30,12 @@ import type {
UsageSeriesPoint,
} from "../api/types.js";
import type { ErrorFilter } from "../db/repos/errors.js";
-import {
- catalogEntryFor,
- offPeakAt,
- offPeakScheduledRefs,
-} from "@lmliheng/penguin-core/model-catalog";
import type {
UsageModelSums,
UsageGroupModelSums,
UsageSeriesModelSums,
UsageAgentBucketCount,
UsageFilter,
- PeakTier,
} from "../db/repos/usage.js";
import {
enumerateBuckets,
@@ -71,23 +65,16 @@ export interface PricingRates {
}
/**
- * What one Model costs, in the tiers it can be billed in.
- *
- * `offPeak` differs from `peak` only for a catalog row on a time-based schedule whose stored
- * price is still the catalog's own. Both are returned together because a query spans time: a
- * week that straddles the boundary contains Tokens of both kinds, and each half is priced at
- * the rate it actually ran at rather than at whichever tier is in force when it is read.
+ * The price a Project stores for a paired reference — what a Request on it is billed at when
+ * it completes at `at` (the Project's list price for the row, less its promotion, at the tier
+ * in force then); undefined = the Project stores no price for it.
*/
-export interface TieredRates {
- peak: PricingRates;
- offPeak: PricingRates;
-}
-
export type PricingLookup = (
projectId: string,
provider: string,
modelId: string,
-) => Promise<TieredRates | undefined>;
+ at: Date,
+) => Promise<PricingRates | undefined>;
export interface UsageQuery {
from?: string;
@@ -165,32 +152,6 @@ export function requestCostUsd(
);
}
-/**
- * The rates one usage record is billed at, decided from the record's own timestamp: the
- * off-peak tier when the reference carries a catalog schedule and `at` falls outside its peak
- * windows, the peak tier otherwise. For a reference with no schedule, or whose stored price is
- * no longer the catalog's, the two tiers are the same figure (see project-config-service's
- * `tieredRates`), so the decision changes nothing there. `peakExpr` in the usage repo is this
- * rule written in SQL for the aggregations; the two must agree record for record, which is why
- * an unreadable timestamp — which the repo never stores — takes the peak tier rather than
- * inventing a discount.
- */
-export function ratesAt(
- tiered: TieredRates,
- provider: string,
- modelId: string,
- at: Date,
-): PricingRates {
- const schedule = catalogEntryFor(provider, modelId)?.offPeakDiscount;
- if (schedule === undefined || Number.isNaN(at.getTime())) return tiered.peak;
- return offPeakAt(schedule, at) ? tiered.offPeak : tiered.peak;
-}
-
-/** Cost formula: sum of the three buckets at the tier these Tokens ran in, USD per million. */
-function costOf(sums: UsageModelSums, tiered: TieredRates): number {
- return requestCostUsd(sums, sums.peak ? tiered.peak : tiered.offPeak);
-}
-
/** In-process Map key for a paired reference (\0-separated, the same style as session-manager's agentKey; never persisted). */
function refKey(provider: string, modelId: string): string {
return `${provider}\0${modelId}`;
@@ -202,31 +163,44 @@ export class UsageService implements UsageQueries {
@Use() private readonly errors!: ErrorLog;
@Use() private readonly projectConfig!: ProjectConfigStore;
@Use() private readonly clock!: Clock;
- private lookupPricing: PricingLookup = (projectId, provider, modelId) =>
- this.projectConfig.getPricing(projectId, provider, modelId);
+ private lookupPricing: PricingLookup = (projectId, provider, modelId, at) =>
+ this.projectConfig.getPricing(projectId, provider, modelId, at);
/**
- * The catalog's time-based schedules, as the aggregations want them.
- *
- * Split by the SCHEDULE, not by whether this Project is on the catalog's price: a Project
- * that edited the price gets one rate for both halves from {@link lookupPricing}, so the extra
- * dimension costs a row and changes no number. Doing it the other way round would need the
- * config read before the query that discovers which references occur.
+ * COMPATIBILITY — remove two releases after the one that fixes costs at record time, together
+ * with the `cost_settled` column. Fixes the cost of every usage record that has none yet: rows
+ * written before costs were fixed at record time, and rows an older build wrote after a hot
+ * update rolled back to it. Each is priced at the price its Project stores now, at the tier the
+ * record's own timestamp fell in — the read-time cost center's promotion, with the tier pinned
+ * to the row rather than to the hour the page happened to be opened. That is the one figure
+ * which moves at the upgrade (a row the old page showed in the other tier corrects itself) and
+ * never again after it. Idempotent — a settled row is never touched again — and safe beside the
+ * recorder, whose rows are settled when written. Returns how many rows it settled.
*/
- private tiers(): PeakTier[] {
- return offPeakScheduledRefs().map(({ schedule, refs }) => ({
- refs,
- utcOffsetMinutes: schedule.utcOffsetMinutes,
- peakDays: schedule.peakDays,
- peakHours: schedule.peakHours,
- }));
+ async settleUnsettledCosts(): Promise<number> {
+ let settled = 0;
+ for (const ref of this.usage.unsettledRefs()) {
+ const rows = this.usage.unsettledRows(ref.projectId, ref.provider, ref.modelId);
+ const costs: Array<{ id: number; cost: number | null }> = [];
+ for (const r of rows) {
+ const rates = await this.lookupPricing(
+ ref.projectId,
+ ref.provider,
+ ref.modelId,
+ new Date(r.ts),
+ );
+ costs.push({ id: r.id, cost: rates === undefined ? null : requestCostUsd(r, rates) });
+ }
+ this.usage.settle(costs);
+ settled += rows.length;
+ }
+ return settled;
}
/**
* Period cost per session, for company mode's attribution by the sessions an organization
- * owns: sums by paired reference priced at the current rates (each half at the tier its own
- * records ran in). `unpriced` says some usage ran on a model without pricing, so the numbers
- * are a lower bound.
+ * owns: the recorded costs summed per session. `unpriced` says some usage ran on a model
+ * without pricing, so the numbers are a lower bound.
*/
async costBySession(
projectId: string,
@@ -236,25 +210,11 @@ export class UsageService implements UsageQueries {
): Promise<{ bySession: Map<string, number>; unpriced: boolean }> {
const bySession = new Map<string, number>();
if (sessionIds.length === 0) return { bySession, unpriced: false };
- const rows = this.usage.groupsByModel(
- projectId,
- "session",
- { sessionIds, fromTs, toTs },
- this.tiers(),
- );
- const rates = new Map<string, TieredRates | undefined>();
+ const rows = this.usage.groupsByModel(projectId, "session", { sessionIds, fromTs, toTs });
let unpriced = false;
for (const r of rows) {
- const key = refKey(r.provider, r.modelId);
- if (!rates.has(key)) {
- rates.set(key, await this.lookupPricing(projectId, r.provider, r.modelId));
- }
- const rate = rates.get(key);
- if (!rate) {
- unpriced = true;
- continue;
- }
- bySession.set(r.key, (bySession.get(r.key) ?? 0) + costOf(r, rate));
+ if (r.uncosted > 0) unpriced = true;
+ if (r.cost !== null) bySession.set(r.key, (bySession.get(r.key) ?? 0) + r.cost);
}
return { bySession, unpriced };
}
@@ -267,22 +227,10 @@ export class UsageService implements UsageQueries {
toTs: string,
): Promise<Array<{ date: string; cost: number }>> {
if (sessionIds.length === 0) return [];
- const rows = this.usage.seriesByModel(
- projectId,
- "day",
- { sessionIds, fromTs, toTs },
- this.tiers(),
- );
- const rates = new Map<string, TieredRates | undefined>();
+ const rows = this.usage.seriesByModel(projectId, "day", { sessionIds, fromTs, toTs });
const byDate = new Map<string, number>();
for (const r of rows) {
- const key = refKey(r.provider, r.modelId);
- if (!rates.has(key)) {
- rates.set(key, await this.lookupPricing(projectId, r.provider, r.modelId));
- }
- const rate = rates.get(key);
- if (!rate) continue;
- byDate.set(r.key, (byDate.get(r.key) ?? 0) + costOf(r, rate));
+ if (r.cost !== null) byDate.set(r.key, (byDate.get(r.key) ?? 0) + r.cost);
}
return [...byDate.entries()]
.sort(([a], [b]) => a.localeCompare(b))
@@ -310,20 +258,16 @@ export class UsageService implements UsageQueries {
...(q.fromTs !== undefined ? { fromTs: q.fromTs } : {}),
...(q.toTs !== undefined ? { toTs: q.toTs } : {}),
};
- const tiers = this.tiers();
- const todayRows = this.usage.bucketByModel(projectId, win(today, today), tiers);
+ const todayRows = this.usage.bucketByModel(projectId, win(today, today));
const last7dRows = this.usage.bucketByModel(
projectId,
win(localDateMinusDays(this.clock.now(), 6)),
- tiers,
- );
- const totalRows = this.usage.bucketByModel(projectId, { ...win(q.from, q.to), ...ts }, tiers);
- const groupRows = this.usage.groupsByModel(
- projectId,
- q.groupBy,
- { ...win(q.from, q.to), ...ts },
- tiers,
);
+ const totalRows = this.usage.bucketByModel(projectId, { ...win(q.from, q.to), ...ts });
+ const groupRows = this.usage.groupsByModel(projectId, q.groupBy, {
+ ...win(q.from, q.to),
+ ...ts,
+ });
// Time series at the requested precision, zero-filled over the requested
// range, defaulting to the last 30 days when no range is given.
const granularity = q.granularity ?? "day";
@@ -351,12 +295,10 @@ export class UsageService implements UsageQueries {
"Date range too wide for this granularity; narrow the range or coarsen the granularity.",
);
}
- const seriesRows = this.usage.seriesByModel(
- projectId,
- granularity,
- { ...win(seriesFrom, seriesTo), ...ts },
- tiers,
- );
+ const seriesRows = this.usage.seriesByModel(projectId, granularity, {
+ ...win(seriesFrom, seriesTo),
+ ...ts,
+ });
// Per-Agent and per-Model series: each drops its own dimension's filter (its
// chart draws that dimension's whole breakdown) but honors the other
// dimension plus the selected range.
@@ -395,26 +337,16 @@ export class UsageService implements UsageQueries {
...(q.includeGlobalErrors === true ? { includeGlobal: true } : {}),
};
- // Each paired reference that occurs is looked up for its current price only once.
- const rates = new Map<string, TieredRates | undefined>();
- const allRefs = new Map<string, { provider: string; modelId: string }>();
- for (const r of [...todayRows, ...last7dRows, ...totalRows, ...groupRows, ...seriesRows]) {
- allRefs.set(refKey(r.provider, r.modelId), { provider: r.provider, modelId: r.modelId });
- }
- for (const [key, ref] of allRefs) {
- rates.set(key, await this.lookupPricing(projectId, ref.provider, ref.modelId));
- }
-
return {
summary: {
- today: this.foldBucket(todayRows, rates),
- last7d: this.foldBucket(last7dRows, rates),
- total: this.foldBucket(totalRows, rates),
+ today: this.foldBucket(todayRows),
+ last7d: this.foldBucket(last7dRows),
+ total: this.foldBucket(totalRows),
},
groupBy: q.groupBy,
- groups: this.foldGroups(groupRows, rates, q.groupBy),
+ groups: this.foldGroups(groupRows, q.groupBy),
granularity,
- series: this.foldSeries(bucketKeys, seriesRows, rates),
+ series: this.foldSeries(bucketKeys, seriesRows),
byAgentSeries: foldAgentSeries(bucketKeys, agentBucketRows),
byModelSeries: foldModelSeries(bucketKeys, modelBucketRows),
errors: this.foldErrors(projectId, errorFilter, q.utcOffsetMinutes),
@@ -508,28 +440,17 @@ export class UsageService implements UsageQueries {
/**
* The Project's lifetime cost — one unfiltered grouped scan, the same one `modelTotals` runs,
- * priced at the current rates. Its consumer is a per-account figure (the admin user backend's
- * cost column), so there is exactly one number: `cost` stays null while nothing could be
- * priced rather than reporting a zero the caller cannot tell from "ran for free", and
- * `unpriced` marks a lower bound.
+ * summing the costs fixed when the rows were written. Its consumer is a per-account figure
+ * (the admin user backend's cost column), so there is exactly one number: `cost` stays null
+ * while nothing could be priced rather than reporting a zero the caller cannot tell from "ran
+ * for free", and `unpriced` marks a lower bound.
*/
async lifetimeCost(projectId: string): Promise<{ cost: number | null; unpriced: boolean }> {
- const rows = this.usage.bucketByModel(projectId, {}, this.tiers());
- const rates = new Map<string, TieredRates | undefined>();
- for (const r of rows) {
- const key = refKey(r.provider, r.modelId);
- if (!rates.has(key)) {
- rates.set(key, await this.lookupPricing(projectId, r.provider, r.modelId));
- }
- }
- const { cost, hasUncosted } = this.foldBucket(rows, rates);
+ const { cost, hasUncosted } = this.foldBucket(this.usage.bucketByModel(projectId));
return { cost, unpriced: hasUncosted };
}
- private foldBucket(
- rows: UsageModelSums[],
- rates: Map<string, TieredRates | undefined>,
- ): UsageBucket {
+ private foldBucket(rows: UsageModelSums[]): UsageBucket {
let total = 0;
let requests = 0;
let cost: number | null = null;
@@ -537,18 +458,13 @@ export class UsageService implements UsageQueries {
for (const r of rows) {
total += r.total;
requests += r.requests;
- const rate = rates.get(refKey(r.provider, r.modelId));
- if (rate) cost = (cost ?? 0) + costOf(r, rate);
- else hasUncosted = true;
+ if (r.cost !== null) cost = (cost ?? 0) + r.cost;
+ if (r.uncosted > 0) hasUncosted = true;
}
return { total, requests, cost, hasUncosted };
}
- private foldGroups(
- rows: UsageGroupModelSums[],
- rates: Map<string, TieredRates | undefined>,
- groupBy: UsageGroupBy,
- ): UsageGroupRow[] {
+ private foldGroups(rows: UsageGroupModelSums[], groupBy: UsageGroupBy): UsageGroupRow[] {
// The model dimension folds by paired reference (a shared model_id name across providers is split into separate rows); other dimensions fold by their group key.
const keyOf = (r: UsageGroupModelSums): string =>
groupBy === "model" ? refKey(r.provider, r.key) : r.key;
@@ -570,9 +486,8 @@ export class UsageService implements UsageQueries {
acc.output += r.output;
acc.total += r.total;
acc.requests += r.requests;
- const rate = rates.get(refKey(r.provider, r.modelId));
- if (rate) acc.cost = (acc.cost ?? 0) + costOf(r, rate);
- else acc.hasUncosted = true;
+ if (r.cost !== null) acc.cost = (acc.cost ?? 0) + r.cost;
+ if (r.uncosted > 0) acc.hasUncosted = true;
byKey.set(keyOf(r), acc);
}
const out = [...byKey.values()];
@@ -591,11 +506,7 @@ export class UsageService implements UsageQueries {
* `ts` and can therefore fall outside a skeleton built from `date` if a row
* was recorded under a different clock.
*/
- private foldSeries(
- keys: string[],
- rows: UsageSeriesModelSums[],
- rates: Map<string, TieredRates | undefined>,
- ): UsageSeriesPoint[] {
+ private foldSeries(keys: string[], rows: UsageSeriesModelSums[]): UsageSeriesPoint[] {
const byKey = new Map<string, UsageSeriesPoint>(
keys.map((bucket) => [
bucket,
@@ -622,8 +533,7 @@ export class UsageService implements UsageQueries {
acc.requests += r.requests;
acc.completed += r.completed;
acc.denominator += r.denominator;
- const rate = rates.get(refKey(r.provider, r.modelId));
- if (rate) acc.cost = (acc.cost ?? 0) + costOf(r, rate);
+ if (r.cost !== null) acc.cost = (acc.cost ?? 0) + r.cost;
}
return keys.map((k) => byKey.get(k)!);
}
diff --git a/packages/server/test/admin-users.test.ts b/packages/server/test/admin-users.test.ts
index 288d2612..78abcb7e 100644
--- a/packages/server/test/admin-users.test.ts
+++ b/packages/server/test/admin-users.test.ts
@@ -155,7 +155,7 @@ describe("admin users backend", () => {
/**
* The two read-only columns the user backend carries. Both are the server's own figures: the
* sign-in stamp AuthService writes on a password login, and the lifetime cost of the Projects
- * the account OWNS, priced at the current rates.
+ * the account OWNS — every record's cost as it was fixed when the row was written.
*/
it("user list: last sign-in is stamped by the login that succeeded, absent for an account never used", async () => {
const kate = await provisionUser(t.app, "kate");
@@ -178,8 +178,8 @@ describe("admin users backend", () => {
it("user list: cost sums the Projects the account owns, and says so when a model has no price", async () => {
const kate = await provisionUser(t.app, "kate");
- // Two models in Kate's own Project: `m-priced` costs (10*1 + 1*2 + 5*3)/1e6 per record,
- // `m-free` carries no pricing block at all.
+ // Kate's Project stores a price for `m-priced` — (10*1 + 1*2 + 5*3)/1e6 per record — and none
+ // at all for `m-free`, so a row on the latter is recorded without a cost.
await saveProjectConfig(t.root, "kate-default_project", {
default_model: { provider: "custom", model_id: "m-priced" },
models: [
@@ -191,11 +191,12 @@ describe("admin users backend", () => {
{ provider: "custom", model_id: "m-free" },
],
});
- const insertUsage = (modelId: string, date: string): void => {
+ /** A row as the recorder writes it: the Tokens, and the cost its Project's price fixed. */
+ const insertUsage = (modelId: string, date: string, cost: number | null): void => {
t.deps.db
.prepare(
- "INSERT INTO usage_records (ts, date, project_id, agent_id, session_id, origin_session_id, provider, model_id, cache_read, cache_write, output, total)" +
- " VALUES (?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, ?, ?)",
+ "INSERT INTO usage_records (ts, date, project_id, agent_id, session_id, origin_session_id, provider, model_id, cache_read, cache_write, output, total, cost, cost_settled)" +
+ " VALUES (?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, ?, ?, ?, 1)",
)
.run(
`${date}T00:00:00.000Z`,
@@ -209,21 +210,23 @@ describe("admin users backend", () => {
1,
5,
16,
+ cost,
);
};
- insertUsage("m-priced", "2026-10-01");
- insertUsage("m-priced", "2026-10-02");
+ const ROW_COST = (10 * 1 + 1 * 2 + 5 * 3) / 1e6;
+ insertUsage("m-priced", "2026-10-01", ROW_COST);
+ insertUsage("m-priced", "2026-10-02", ROW_COST);
// Nobody else's: the admin's own default Project has no usage, and Kate's cost counts only
// what her own Project recorded — the figure is per owned Project, not per caller.
let list = (await (await admin.get("/api/admin/users")).json()) as AdminUsersResponse;
const priced = list.users.find((u) => u.userId === "kate")!;
- expect(priced.totalCostUsd).toBeCloseTo((2 * (10 * 1 + 1 * 2 + 5 * 3)) / 1e6, 12);
+ expect(priced.totalCostUsd).toBeCloseTo(2 * ROW_COST, 12);
expect(priced.costUnpriced).toBeUndefined();
expect(list.users.find((u) => u.userId === "admin")!.totalCostUsd).toBeUndefined();
- // A record on a model with no price block makes the sum a lower bound — reported as such
- // instead of silently dropped.
- insertUsage("m-free", "2026-10-03");
+ // A record whose model had no price when it was written makes the sum a lower bound —
+ // reported as such instead of silently dropped.
+ insertUsage("m-free", "2026-10-03", null);
list = (await (await admin.get("/api/admin/users")).json()) as AdminUsersResponse;
const bounded = list.users.find((u) => u.userId === "kate")!;
expect(bounded.totalCostUsd).toBeCloseTo(priced.totalCostUsd!, 12);
diff --git a/packages/server/test/db-migrations.test.ts b/packages/server/test/db-migrations.test.ts
index 40404990..9eca5f69 100644
--- a/packages/server/test/db-migrations.test.ts
+++ b/packages/server/test/db-migrations.test.ts
@@ -1,8 +1,8 @@
/**
* The ordered-migration mechanism, the 0.2.4 → 0.2.7 migration that is its first entry, the
- * 0.2.9 → 0.2.10 drop that is its first restart-only one, the additive column pair that
- * the user profile added to `users`, and the channels migration that is its first table
- * recreation.
+ * 0.2.9 → 0.2.10 drop that is its first restart-only one, the additive column pairs that
+ * the user profile added to `users` and the fixed cost added to `usage_records`, and the
+ * channels migration that is its first table recreation.
*
* Two properties carry everything else: a real 0.2.4 database reaches exactly the shape a
* fresh one is created with (so a runtime older than the platform pushed onto it becomes
@@ -80,6 +80,7 @@ function open024(): DatabaseSync {
// must come off, or a round trip through migration 5's down would land on a narrower
// `users` than this fixture and read as a rollback that lost something.
dropProfileColumns(db);
+ dropUsageCostColumns(db);
db.exec(GOAL_STATE_DDL);
return db;
}
@@ -115,9 +116,11 @@ function open6(): DatabaseSync {
db.exec("DROP TABLE IF EXISTS model_provider_auth_tokens");
db.exec("DROP TABLE IF EXISTS model_promotions");
db.exec(PRE_CHANNEL_CHAT_DDL);
- // SCHEMA_SQL declares the CURRENT shape; migration 8's queue and migration 13's came after 6.
+ // SCHEMA_SQL declares the CURRENT shape; migration 8's queue, migration 13's came after 6, and
+ // the cost columns are migration 14's.
db.exec("DROP TABLE IF EXISTS org_desk_notices");
db.exec("DROP TABLE IF EXISTS org_desk_mentions");
+ dropUsageCostColumns(db);
db.exec("PRAGMA user_version = 6");
return db;
}
@@ -130,6 +133,7 @@ function open7(): DatabaseSync {
db.exec("DROP TABLE IF EXISTS org_desk_mentions");
db.exec("DROP TABLE IF EXISTS model_provider_auth_tokens");
db.exec("DROP TABLE IF EXISTS model_promotions");
+ dropUsageCostColumns(db);
db.exec("PRAGMA user_version = 7");
return db;
}
@@ -141,6 +145,7 @@ function open8(): DatabaseSync {
db.exec("DROP TABLE IF EXISTS model_provider_auth_tokens");
db.exec("DROP TABLE IF EXISTS model_promotions");
db.exec("DROP TABLE IF EXISTS org_desk_mentions");
+ dropUsageCostColumns(db);
db.exec("PRAGMA user_version = 8");
return db;
}
@@ -151,6 +156,7 @@ function open9(): DatabaseSync {
db.exec(SCHEMA_SQL);
db.exec("DROP TABLE IF EXISTS model_provider_auth_tokens");
db.exec("DROP TABLE IF EXISTS org_desk_mentions");
+ dropUsageCostColumns(db);
db.exec("PRAGMA user_version = 9");
return db;
}
@@ -160,6 +166,7 @@ function open12(): DatabaseSync {
const db = new sqlite.DatabaseSync(":memory:");
db.exec(SCHEMA_SQL);
db.exec("DROP TABLE IF EXISTS org_desk_mentions");
+ dropUsageCostColumns(db);
db.exec("PRAGMA user_version = 12");
return db;
}
@@ -177,6 +184,7 @@ function open029(): DatabaseSync {
// both the fixture is a database no release made.
db.exec("DROP TABLE machine_project; DROP TABLE machines; DROP TABLE machine;");
dropProfileColumns(db);
+ dropUsageCostColumns(db);
db.exec("PRAGMA user_version = 2");
return db;
}
@@ -195,10 +203,23 @@ function openPreProfile(): DatabaseSync {
// Version 4 predates company mode as well: its three migrations (6–8) come after the
// profile's, so a database at 4 has none of their tables.
dropCompanyTables(db);
+ dropUsageCostColumns(db);
db.exec("PRAGMA user_version = 4");
return db;
}
+/**
+ * A database from before costs were fixed at record time: today's declaration minus exactly the
+ * two usage_records columns migration 14 adds, stamped at the version before it.
+ */
+function openPreUsageCost(): DatabaseSync {
+ const db = new sqlite.DatabaseSync(":memory:");
+ db.exec(SCHEMA_SQL);
+ dropUsageCostColumns(db);
+ db.exec("PRAGMA user_version = 13");
+ return db;
+}
+
/** Takes everything migrations 6–8 and 13 create off a database built from the current declaration. */
function dropCompanyTables(db: DatabaseSync): void {
db.exec(`
@@ -223,6 +244,18 @@ function dropProfileColumns(db: DatabaseSync): void {
db.exec("ALTER TABLE users DROP COLUMN display_name");
}
+/** Takes migration 9's two usage_records columns off a database built from the current declaration. */
+function dropUsageCostColumns(db: DatabaseSync): void {
+ db.exec("ALTER TABLE usage_records DROP COLUMN cost_settled");
+ db.exec("ALTER TABLE usage_records DROP COLUMN cost");
+}
+
+/** Column names of `usage_records`. */
+function usageColumns(db: DatabaseSync): string[] {
+ const rows = db.prepare("PRAGMA table_info(usage_records)").all() as { name: string }[];
+ return rows.map((r) => r.name);
+}
+
/** Column names of `users`, for the two cases that are about columns rather than whole shapes. */
function userColumns(db: DatabaseSync): string[] {
const rows = db.prepare("PRAGMA table_info(users)").all() as { name: string }[];
@@ -590,8 +623,9 @@ describe("migration 8 → current: model-promotions", () => {
"sessions-sandbox",
"machines-columns",
"company-mode-desk-mentions",
+ "usage-record-cost",
]);
- expect(schemaVersion(db)).toBe(13);
+ expect(schemaVersion(db)).toBe(14);
expect(promotionsTableExists()).toEqual({ "1": 1 });
expect(authTokensTableExists()).toEqual({ "1": 1 });
@@ -613,8 +647,9 @@ describe("migration 8 → current: model-promotions", () => {
"sessions-sandbox",
"machines-columns",
"company-mode-desk-mentions",
+ "usage-record-cost",
]);
- expect(schemaVersion(db)).toBe(13);
+ expect(schemaVersion(db)).toBe(14);
} finally {
db.close();
}
@@ -636,8 +671,9 @@ describe("migration 9 → current: model-provider-auth-tokens", () => {
"sessions-sandbox",
"machines-columns",
"company-mode-desk-mentions",
+ "usage-record-cost",
]);
- expect(schemaVersion(db)).toBe(13);
+ expect(schemaVersion(db)).toBe(14);
expect(tableExists()).toEqual({ "1": 1 });
db.exec(
"INSERT INTO users (user_id, password_hash, is_admin, created_at)" +
@@ -680,7 +716,7 @@ describe("migration 12 → current: company-mode-desk-mentions", () => {
try {
fresh.exec(SCHEMA_SQL);
expect(shape(db)).not.toBe(shape(fresh));
- expect(migrate(db).applied).toEqual(["company-mode-desk-mentions"]);
+ expect(migrate(db).applied).toEqual(["company-mode-desk-mentions", "usage-record-cost"]);
expect(schemaVersion(db)).toBe(LATEST_VERSION);
expect(shape(db)).toBe(shape(fresh));
queue(db, "msg-1");
@@ -716,6 +752,70 @@ describe("migration 12 → current: company-mode-desk-mentions", () => {
});
});
+describe("pre-cost → current: usage-record-cost", () => {
+ const legacyRow =
+ "INSERT INTO usage_records (ts, date, project_id, agent_id, session_id, provider, model_id, cache_read, cache_write, output, total)" +
+ " VALUES ('2026-09-01T00:00:00Z', '2026-09-01', 'p1', 'a1', 's1', 'custom', 'm1', 10, 1, 5, 16)";
+
+ it("adds both columns with every existing row unsettled, and a database that already has them migrates the same", () => {
+ const db = openPreUsageCost();
+ const fresh = new sqlite.DatabaseSync(":memory:");
+ try {
+ fresh.exec(SCHEMA_SQL);
+ db.exec(legacyRow);
+ expect(usageColumns(db)).not.toContain("cost");
+ expect(migrate(db).applied).toEqual(
+ MIGRATIONS.filter((m) => m.version > 13).map((m) => m.name),
+ );
+ expect(shape(db)).toBe(shape(fresh));
+ // The row a pre-cost build wrote waits for the startup settle: no cost, not settled.
+ expect(db.prepare("SELECT cost, cost_settled FROM usage_records").all()).toEqual([
+ { cost: null, cost_settled: 0 },
+ ]);
+
+ // ADOPTION: on a database this build created, the declarative track already added both.
+ fresh.exec("PRAGMA user_version = 13");
+ expect(migrate(fresh).applied).toEqual(
+ MIGRATIONS.filter((m) => m.version > 13).map((m) => m.name),
+ );
+ expect(usageColumns(fresh).filter((c) => c === "cost")).toEqual(["cost"]);
+ } finally {
+ db.close();
+ fresh.close();
+ }
+ });
+
+ it("is swap-safe: a rolled-back predecessor keeps inserting, and its rows read unsettled", () => {
+ const db = openPreUsageCost();
+ try {
+ migrate(db, { swapPath: true });
+ db.exec(legacyRow); // what a predecessor that does not know the columns writes
+ expect(db.prepare("SELECT cost, cost_settled FROM usage_records").all()).toEqual([
+ { cost: null, cost_settled: 0 },
+ ]);
+ } finally {
+ db.close();
+ }
+ });
+
+ it("down removes both columns, taking every fixed cost with them; the rows survive", () => {
+ const db = openPreUsageCost();
+ try {
+ db.exec(legacyRow);
+ const before = shape(db);
+ migrate(db);
+ db.exec("UPDATE usage_records SET cost = 0.5, cost_settled = 1");
+
+ rollbackTo(db, 13);
+ expect(shape(db)).toBe(before);
+ expect(usageColumns(db)).not.toContain("cost_settled");
+ expect(db.prepare("SELECT total FROM usage_records").all()).toEqual([{ total: 16 }]);
+ } finally {
+ db.close();
+ }
+ });
+});
+
describe("0.2.4 → current", () => {
/** The whole point: an older runtime's database becomes what a current build creates. */
it("brings a 0.2.4 database to the shape a fresh one is created with", () => {
diff --git a/packages/server/test/models.test.ts b/packages/server/test/models.test.ts
index eaad31f9..e0956ab3 100644
--- a/packages/server/test/models.test.ts
+++ b/packages/server/test/models.test.ts
@@ -52,6 +52,7 @@ import type {
SessionCreateResponse,
} from "../src/api/types.js";
import { ProjectConfigService } from "../src/services/project-config-service.js";
+import type { RuntimeSession } from "../src/runtime/session-manager.js";
import type { ChannelEvent } from "../src/runtime/channel.js";
import { jsonResponse, stubFetch } from "./fixtures/fetch.js";
import { fakeSession, sessionRow } from "./fixtures/session.js";
@@ -978,17 +979,22 @@ describe("model-reference rekeying and the connectivity test", () => {
expect(toml).not.toContain("openai/gpt-5.5");
});
- it("a scheduled row answers with both of its rates, from the one stable price on disk", async () => {
- // No clock is passed and none is wanted: which tier a given request ran in is decided from
- // that record's own timestamp when the usage is aggregated, so the price lookup's whole job
- // is to say what the two tiers are. The number on disk is the peak one either way.
+ // 2026-08-31 is a Monday: 01:30Z is 09:30 in Beijing (peak), 12:00Z is 20:00 (off-peak).
+ const PEAK = new Date("2026-08-31T01:30:00Z");
+ const OFF_PEAK = new Date("2026-08-31T12:00:00Z");
+
+ it("a scheduled row stores the one stable price, and the tier is derived from a Request's own instant", async () => {
+ // The number on disk is the peak price whatever the hour; which tier a Request bills at is
+ // decided by when it completed, so the same stored price bills twice as much at 09:30 as at
+ // 20:00 on the same Monday.
const svc = wire(ProjectConfigService, { paths: { root: t.root } });
- const rates = await svc.getPricing(projectId, "deepseek", "deepseek-flash");
+ const peak = await svc.getPricing(projectId, "deepseek", "deepseek-flash", PEAK);
const catalogPeak = catalogEntryFor("deepseek", "deepseek-flash")!.pricing!;
- expect(rates!.peak.output).toBe(catalogPeak.output);
- expect(rates!.offPeak.output).toBeCloseTo(catalogPeak.output / 2, 5);
- expect(rates!.peak.cacheRead).toBe(catalogPeak.cache_read);
- expect(rates!.offPeak.cacheRead).toBeCloseTo(catalogPeak.cache_read / 2, 6);
+ expect(peak!.output).toBe(catalogPeak.output);
+ expect(peak!.cacheRead).toBe(catalogPeak.cache_read);
+ const off = await svc.getPricing(projectId, "deepseek", "deepseek-flash", OFF_PEAK);
+ expect(off!.output).toBeCloseTo(catalogPeak.output / 2, 5);
+ expect(off!.cacheRead).toBeCloseTo(catalogPeak.cache_read / 2, 6);
});
it("a hand-edited price on a scheduled row is billed as typed, in both tiers", async () => {
@@ -1012,12 +1018,10 @@ describe("model-reference rekeying and the connectivity test", () => {
await api.put(url(), { models: entries });
const svc = wire(ProjectConfigService, { paths: { root: t.root } });
// Nothing here knows whether 3 is a peak rate, so halving it would invent a discount: the
- // two tiers collapse to the typed number and the split costs a row and changes nothing.
+ // typed number is what bills, whenever the Request runs.
const typed = { cacheRead: 1, cacheWrite: 2, output: 3 };
- expect(await svc.getPricing(projectId, "deepseek", "deepseek-flash")).toEqual({
- peak: typed,
- offPeak: typed,
- });
+ expect(await svc.getPricing(projectId, "deepseek", "deepseek-flash", PEAK)).toEqual(typed);
+ expect(await svc.getPricing(projectId, "deepseek", "deepseek-flash", OFF_PEAK)).toEqual(typed);
});
it("a stored promotion takes its fraction off the list price on disk, multiplied with a scheduled row's off-peak tier", async () => {
@@ -1030,10 +1034,7 @@ describe("model-reference rekeying and the connectivity test", () => {
cacheWrite: off(list.cache_write, 0.1),
output: off(list.output, 0.1),
};
- expect(await svc.getPricing(projectId, "tokendance", "glm-5.3-flash")).toEqual({
- peak: promoted,
- offPeak: promoted,
- });
+ expect(await svc.getPricing(projectId, "tokendance", "glm-5.3-flash", PEAK)).toEqual(promoted);
// A scheduled row still at the catalog's peak price, with a promotion of its own: peak bills
// the promotion alone, off-peak the half-price tier with the promotion taken off it too.
@@ -1052,9 +1053,15 @@ describe("model-reference rekeying and the connectivity test", () => {
},
],
});
- const rates = (await svc.getPricing(projectId, "deepseek", "deepseek-v4-flash"))!;
- expect(rates.peak.output).toBe(off(peak.output, 0.2));
- expect(rates.offPeak.output).toBe(off(off(peak.output, 0.5), 0.2));
+ const peakRates = (await svc.getPricing(projectId, "deepseek", "deepseek-v4-flash", PEAK))!;
+ expect(peakRates.output).toBe(off(peak.output, 0.2));
+ const offPeakRates = (await svc.getPricing(
+ projectId,
+ "deepseek",
+ "deepseek-v4-flash",
+ OFF_PEAK,
+ ))!;
+ expect(offPeakRates.output).toBe(off(off(peak.output, 0.5), 0.2));
});
it("PUT discount: a declared one is stored and null clears it; an omitted one survives only on an unrenamed row at an unchanged price", async () => {
diff --git a/packages/server/test/project-config-cache.test.ts b/packages/server/test/project-config-cache.test.ts
index ba53eeb3..325a8325 100644
--- a/packages/server/test/project-config-cache.test.ts
+++ b/packages/server/test/project-config-cache.test.ts
@@ -46,19 +46,14 @@ describe("project-config read cache", () => {
await fs.rm(root, { recursive: true, force: true });
});
- /** This fixture's model has no schedule, so both tiers are the one price it stores. */
+ /** The price this fixture's model stores. Its id has no schedule, so the instant is immaterial. */
const RATES = { cacheRead: 1, cacheWrite: 2, output: 3 };
+ const AT = new Date("2026-08-31T01:30:00Z");
it("repeat reads cost one readFile: pricing, name and the typed loadConfig view share the cached parse", async () => {
const reads = vi.spyOn(fs, "readFile");
- expect(await svc.getPricing(P, "custom", "m1")).toEqual({
- peak: RATES,
- offPeak: RATES,
- });
- expect(await svc.getPricing(P, "custom", "m1")).toEqual({
- peak: RATES,
- offPeak: RATES,
- });
+ expect(await svc.getPricing(P, "custom", "m1", AT)).toEqual(RATES);
+ expect(await svc.getPricing(P, "custom", "m1", AT)).toEqual(RATES);
expect(await svc.getName(P)).toBe("cached");
expect((await svc.loadConfig(P)).models.map((m) => m.model_id)).toEqual(["m1"]);
expect(reads).toHaveBeenCalledTimes(1);
@@ -70,10 +65,7 @@ describe("project-config read cache", () => {
await backdate(file, "2026-01-01T00:01:00Z");
const reads = vi.spyOn(fs, "readFile");
expect(await svc.getName(P)).toBe("renamed");
- expect(await svc.getPricing(P, "custom", "m1")).toEqual({
- peak: RATES,
- offPeak: RATES,
- });
+ expect(await svc.getPricing(P, "custom", "m1", AT)).toEqual(RATES);
expect(reads).toHaveBeenCalledTimes(1);
});
@@ -87,7 +79,7 @@ describe("project-config read cache", () => {
await backdate(file, "2026-01-01T00:02:00Z"); // Stable, but a different mtime than cached.
expect(await svc.getName(P)).toBe("edited");
expect((await svc.loadConfig(P)).models.map((m) => m.model_id)).toEqual(["m2"]);
- expect(await svc.getPricing(P, "custom", "m1")).toBeUndefined();
+ expect(await svc.getPricing(P, "custom", "m1", AT)).toBeUndefined();
});
it("a fresh mtime is never cached as clean: reads keep hitting disk until the file has been quiet", async () => {
diff --git a/packages/server/test/trace-service.test.ts b/packages/server/test/trace-service.test.ts
index fb38312d..e07bf7b3 100644
--- a/packages/server/test/trace-service.test.ts
+++ b/packages/server/test/trace-service.test.ts
@@ -6,15 +6,18 @@
import fs from "node:fs/promises";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import {
+ DEEPSEEK_OFF_PEAK,
abortEvent,
approvalDecision,
assistantText,
buildBackgroundTaskDoneMessage,
+ catalogEntryFor,
compactionBegin,
compactionEnd,
imageUrlMessage,
mcpConnectBegin,
mcpConnectEnd,
+ offPeakAt,
requestBegin,
requestEnd,
sessionMeta,
@@ -42,7 +45,8 @@ import { wire } from "@lmliheng/penguin-core/kernel";
import { ErrorsRepo } from "../src/db/repos/errors.js";
import { UsageRepo } from "../src/db/repos/usage.js";
import { SessionSources } from "../src/runtime/session-sources.js";
-import { UsageService } from "../src/services/usage-service.js";
+import { UsageRecorder } from "../src/runtime/usage-recorder.js";
+import { UsageService, requestCostUsd } from "../src/services/usage-service.js";
import type { PricingLookup } from "../src/services/usage-service.js";
import { makeTempRoot, makeTraceHarness, writeTraceFile } from "./helpers.js";
@@ -242,59 +246,86 @@ describe("trace-service", () => {
];
};
- it("prices each Request at the tier its own timestamp ran in, and the file adds up to what the cost center bills the same rows", async () => {
- // A DeepSeek reference carries the catalog's Beijing-hours schedule; the lookup answers
- // both tiers, as project-config-service does for a row still at the catalog's price.
+ it("prices each Request at the tier its own timestamp ran in, and the file adds up to what the cost center fixed for the same rows", async () => {
+ // A DeepSeek reference still storing the catalog's peak price bills by the catalog's
+ // Beijing-hours schedule, so the lookup answers as project-config-service does for such a
+ // row: the peak rate inside the windows, half of it outside, for the instant it is asked for.
const REF = { provider: "deepseek", model_id: "deepseek-flash" };
+ const peak = catalogEntryFor(REF.provider, REF.model_id)!.pricing!;
+ const stored = {
+ cacheRead: peak.cache_read,
+ cacheWrite: peak.cache_write,
+ output: peak.output,
+ };
+ const half = (v: number): number => Math.round(v * 0.5 * 1e6) / 1e6;
+ const offPeakRates = {
+ cacheRead: half(stored.cacheRead),
+ cacheWrite: half(stored.cacheWrite),
+ output: half(stored.output),
+ };
const lookups: string[] = [];
- const lookup: PricingLookup = async (projectId, provider, modelId) => {
- lookups.push(`${projectId}/${provider}/${modelId}`);
- return {
- peak: { cacheRead: 1, cacheWrite: 2, output: 4 },
- offPeak: { cacheRead: 0.5, cacheWrite: 1, output: 2 },
- };
+ const lookup: PricingLookup = async (projectId, provider, modelId, at) => {
+ lookups.push(`${projectId}/${provider}/${modelId}@${at.toISOString()}`);
+ return offPeakAt(DEEPSEEK_OFF_PEAK, at) ? offPeakRates : stored;
};
const priced = makeTraceHarness(root, { lookupPricing: lookup });
const usage = buckets(10, 1, 5);
- // Tuesday 10:30 Beijing (peak), Tuesday 21:00 Beijing (off-peak), Sunday 11:00 Beijing
- // (an hour a weekday bills at peak, off-peak on a weekend).
+ const counts = { cacheRead: 10, cacheWrite: 1, output: 5 };
+ // Tuesday 10:30 Beijing (peak), Tuesday 21:00 Beijing (off-peak), Sunday 11:00 Beijing (an
+ // hour a weekday bills at peak, off-peak on a weekend) and ten minutes after that last one,
+ // which must share its lookup rather than read the Project's config again.
const stamps = [
"2026-07-07T02:30:00.000Z",
"2026-07-07T13:00:00.000Z",
"2026-07-12T03:00:00.000Z",
+ "2026-07-12T03:10:00.000Z",
];
+ /** The instant a turn's usage is stamped at: its request plus the three seconds of `priceTurn`. */
+ const usageAt = (ts: string): string => new Date(Date.parse(ts) + 3000).toISOString();
try {
await writeTraceFile(root, P, A, "2026-07-07", S, 1, [
sessionMeta(metaPayload(REF)),
...stamps.flatMap((ts) => priceTurn(ts, usage)),
]);
const a = await priced.service.analyze(P, A, S, 1);
- const peakCost = (10 * 1 + 1 * 2 + 5 * 4) / 1e6;
- expect(a.tasks.map((t) => t.cost)).toEqual([peakCost, peakCost / 2, peakCost / 2]);
- expect(a.cost).toBeCloseTo(peakCost * 2, 12);
- expect(lookups).toEqual([`${P}/deepseek/deepseek-flash`]);
+ const peakCost = requestCostUsd(counts, stored);
+ const offPeakCost = requestCostUsd(counts, offPeakRates);
+ expect(offPeakCost).toBeLessThan(peakCost);
+ expect(a.tasks.map((t) => t.cost)).toEqual([peakCost, offPeakCost, offPeakCost, offPeakCost]);
+ expect(a.cost).toBeCloseTo(peakCost + offPeakCost * 3, 12);
+ // One lookup per hour a Trace spans, not one per Request: the four stamps fall in three
+ // hours (two of them off-peak for different reasons), and each is asked for at its own
+ // instant.
+ expect(lookups).toEqual([
+ `${P}/deepseek/deepseek-flash@${usageAt(stamps[0]!)}`,
+ `${P}/deepseek/deepseek-flash@${usageAt(stamps[1]!)}`,
+ `${P}/deepseek/deepseek-flash@${usageAt(stamps[2]!)}`,
+ ]);
- // The same three requests as usage rows, priced by the cost center's session grouping —
- // the figure the conversation toolbar shows — land on the file's total.
+ // The same Requests as the recorder fixes them — each priced at its own completion,
+ // from the same lookup — summed by the cost center's session grouping (the figure the
+ // conversation toolbar shows) land on the file's total.
const db = openDatabase(":memory:");
try {
const rows = wire(UsageRepo, { db });
for (const ts of stamps) {
- const at = new Date(Date.parse(ts) + 3000).toISOString();
- rows.insert({
- ts: at,
- date: at.slice(0, 10),
- projectId: P,
- agentId: A,
- sessionId: S,
- originSessionId: null,
- provider: REF.provider,
- modelId: REF.model_id,
- cacheRead: usage.cache_read,
- cacheWrite: usage.cache_write,
- output: usage.output,
- total: usage.total,
+ const done = new Date(Date.parse(ts) + 3000);
+ const event = tokenUsage(usage, usage);
+ const recorder = wire(UsageRecorder, {
+ usage: rows,
+ clock: { now: () => done },
+ lookupPricing: lookup,
});
+ await recorder.record(
+ {
+ projectId: P,
+ agentId: A,
+ sessionId: S,
+ provider: REF.provider,
+ modelId: REF.model_id,
+ },
+ event,
+ );
}
const center = wire(UsageService, {
usage: rows,
@@ -317,13 +348,7 @@ describe("trace-service", () => {
const priced = makeTraceHarness(root, {
lookupPricing: async (_projectId, provider, modelId) => {
lookups.push(`${provider}/${modelId}`);
- // A second tier the schedule gate must never reach for an unscheduled reference.
- return modelId === "m1"
- ? {
- peak: { cacheRead: 1, cacheWrite: 1, output: 1 },
- offPeak: { cacheRead: 0, cacheWrite: 0, output: 0 },
- }
- : undefined;
+ return modelId === "m1" ? { cacheRead: 1, cacheWrite: 1, output: 1 } : undefined;
},
});
try {
diff --git a/packages/server/test/usage.test.ts b/packages/server/test/usage.test.ts
index 030ec926..f8c7cf8d 100644
--- a/packages/server/test/usage.test.ts
+++ b/packages/server/test/usage.test.ts
@@ -1,25 +1,27 @@
/**
- * Usage persistence and statistics behind the cost center. Only Tokens are persisted; cost is
- * priced against the current pricing at query time.
+ * Usage persistence and statistics behind the cost center. Each record's cost is fixed when the
+ * row is written, from the price its Project stores for the paired reference at that instant: a
+ * later price edit, preset sync or promotion only changes what later Requests cost.
*
* Recording:
- * - A token_usage message is one row of Tokens (never a cost); anything else writes nothing.
+ * - A token_usage message is one row, with its cost fixed by the recorder here; a request_end
+ * that is not `completed` writes 0 tokens + status, priced the same way (0 for a priced model).
* - A sub-session's usage is attributed to its own model through its session_meta, and falls
* back to the main Session's model when that mapping is missing or was evicted past its cap.
*
* Querying:
- * - A scheduled model is priced per record by the tier its request ran in, each seller by its
- * own windows, so a finished period's total never moves with the clock.
- * - The summary cards cover today, the last 7 days and everything; a model without pricing is
- * flagged, and a price added later prices past records at once; only the references the
- * response prices are looked up.
+ * - Nothing is re-priced: every figure sums the costs recorded, so a finished period's total
+ * never moves with the clock.
+ * - The summary cards cover today, the last 7 days and everything; a Model with no price is
+ * flagged, a price added later never re-prices the rows already written, and no query looks a
+ * price up at all.
* - Groups aggregate by date (newest first), Agent, model and Session, folded across models and
* narrowed by Agent and range.
* - Success counts completed requests over every non-aborted one: a user's Stop is not a model
* failure.
* - Model totals sum every record a model ever wrote, per paired reference, per Project.
- * - Lifetime cost is that same whole history priced at the current rates, one number per
- * Project: null while nothing could be priced, and flagged when a Model has no price.
+ * - Lifetime cost is that same whole history summed from the recorded costs, one number per
+ * Project: null while nothing was priced, and flagged when a Model has no price.
* - Series are zero-filled buckets by minute, hour (local clock), day, ISO week or month, with
* per-Agent and per-model series aligned to them; a minute series needs a timestamp window,
* the range defaults to 30 days, and an oversized series is refused.
@@ -29,13 +31,20 @@
* covered through its route in errors.test.ts).
*/
import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { sessionMeta, tokenUsage, withOrigin } from "@lmliheng/penguin-core";
+import {
+ catalogEntryFor,
+ offPeakAt,
+ requestEnd,
+ sessionMeta,
+ tokenUsage,
+ withOrigin,
+} from "@lmliheng/penguin-core";
import type { SessionMetaPayload, TokenCounts } from "@lmliheng/penguin-core";
import { ORIGIN_MODELS_MAX, UsageRecorder } from "../src/runtime/usage-recorder.js";
import { ErrorsRepo } from "../src/db/repos/errors.js";
import { UsageRepo } from "../src/db/repos/usage.js";
-import { UsageService } from "../src/services/usage-service.js";
-import type { PricingRates } from "../src/services/usage-service.js";
+import { UsageService, requestCostUsd } from "../src/services/usage-service.js";
+import type { PricingLookup, PricingRates } from "../src/services/usage-service.js";
import { openDatabase } from "../src/db/database.js";
import { enumerateBuckets, enumerateTsBuckets, formatLocalDate } from "../src/internal/dates.js";
import type { DatabaseSync } from "node:sqlite";
@@ -68,6 +77,9 @@ function meta(sessionId: string, modelId: string, provider = "custom"): SessionM
describe("usage-recorder", () => {
let db: DatabaseSync;
let repo: UsageRepo;
+ /** A recorder whose price lookup answers `stored` (default: no price anywhere). */
+ const recorder = (lookupPricing: PricingLookup = async () => undefined, now = new Date()) =>
+ wire(UsageRecorder, { usage: repo, clock: { now: () => now }, lookupPricing });
beforeEach(() => {
db = openDatabase(":memory:");
@@ -75,9 +87,14 @@ describe("usage-recorder", () => {
});
afterEach(() => db.close());
- it("token_usage → one row (the request bucket; only Tokens persisted, never cost)", async () => {
- const rec = wire(UsageRecorder, { usage: repo, clock: { now: () => new Date() } });
- await rec.record(CTX, tokenUsage(counts(1000), counts(115)));
+ it("token_usage → one row (the request bucket), its cost fixed from the price the Project stores", async () => {
+ // The lookup stands in for getPricing: the one price the Project bills for a reference. What
+ // core stamps on the event is not consulted at all — a promotion lives in web.db beside the
+ // file's list price, so only this side can state what a Request cost.
+ await recorder(async () => ({ cacheRead: 1, cacheWrite: 2, output: 4 })).record(
+ CTX,
+ tokenUsage(counts(1000), counts(115)),
+ );
const rows = db.prepare("SELECT * FROM usage_records").all();
expect(rows).toHaveLength(1);
const row = rows[0]!;
@@ -86,10 +103,92 @@ describe("usage-recorder", () => {
expect(row.model_id).toBe("main-model");
expect(row.total).toBe(115); // taken from request.total
expect(row.cache_read).toBe(100);
+ expect(row.cost).toBeCloseTo((100 * 1 + 10 * 2 + 5 * 4) / 1e6, 15);
+ expect(row.cost_settled).toBe(1);
+ });
+
+ it("a model with no price: the row is written uncosted, and settled", async () => {
+ await recorder(async () => undefined).record(CTX, tokenUsage(counts(10), counts(10)));
+ const row = db.prepare("SELECT cost, cost_settled FROM usage_records").get()!;
+ expect(row.cost).toBeNull();
+ expect(row.cost_settled).toBe(1);
+ });
+
+ it("the price is asked at the instant the row is written: the same stored peak price bills half off-peak", async () => {
+ // A DeepSeek row still storing the catalog's peak price, written at 20:00 Beijing on a Monday
+ // (2026-08-31), is billed the off-peak tier — the tier is a fact about when the row was
+ // written, never about when someone opens the page (the defect this change fixes).
+ //
+ // The lookup stands in for getPricing, which folds the stored price, the row's promotion and
+ // that instant's tier: what this test pins is that the recorder asks it at its OWN clock's
+ // instant and takes the answer as the bill.
+ const entry = catalogEntryFor("deepseek", "deepseek-flash")!;
+ const peak = entry.pricing!;
+ const schedule = entry.offPeakDiscount!;
+ const off = (v: number): number => Math.round(v * (1 - schedule.rate) * 1e6) / 1e6;
+ const stored = {
+ cacheRead: peak.cache_read,
+ cacheWrite: peak.cache_write,
+ output: peak.output,
+ };
+ const asked: string[] = [];
+ const ctx = { ...CTX, provider: "deepseek", modelId: "deepseek-flash" };
+ const recorderAt = (at: Date) =>
+ recorder(async (_p, provider, modelId, when) => {
+ asked.push(`${provider}/${modelId}@${when.toISOString()}`);
+ return offPeakAt(schedule, when)
+ ? {
+ cacheRead: off(stored.cacheRead),
+ cacheWrite: off(stored.cacheWrite),
+ output: off(stored.output),
+ }
+ : stored;
+ }, at);
+
+ await recorderAt(new Date("2026-08-31T01:30:00Z")).record(
+ ctx,
+ tokenUsage(counts(115), counts(115)),
+ );
+ const peakRow = db.prepare("SELECT cost FROM usage_records").get()!;
+ db.prepare("DELETE FROM usage_records").run();
+ await recorderAt(new Date("2026-08-31T12:00:00Z")).record(
+ ctx,
+ tokenUsage(counts(115), counts(115)),
+ );
+ const offRow = db.prepare("SELECT cost FROM usage_records").get()!;
+
+ expect(asked).toEqual([
+ "deepseek/deepseek-flash@2026-08-31T01:30:00.000Z",
+ "deepseek/deepseek-flash@2026-08-31T12:00:00.000Z",
+ ]);
+ expect(peakRow.cost).toBeCloseTo(
+ requestCostUsd({ cacheRead: 100, cacheWrite: 10, output: 5 }, stored),
+ 15,
+ );
+ // The off-peak rates are the stored ones rounded to six decimals, so the half-price figure
+ // agrees with the peak one to a few parts in 1e12 rather than exactly.
+ expect(offRow.cost).toBeCloseTo((peakRow.cost as number) * (1 - schedule.rate), 10);
+ });
+
+ it("a failed Request costs 0 on a priced model and nothing on an unpriced one; a failing lookup still writes the row", async () => {
+ await recorder(async () => ({ cacheRead: 1, cacheWrite: 1, output: 1 })).record(
+ CTX,
+ requestEnd("fatal"),
+ );
+ await recorder(async () => undefined).record(CTX, requestEnd("fatal"));
+ await recorder(async () => {
+ throw new Error("config unreadable");
+ }).record(CTX, tokenUsage(counts(5), counts(5)));
+ const rows = db.prepare("SELECT status, cost FROM usage_records ORDER BY id").all();
+ expect(rows).toEqual([
+ { status: "fatal", cost: 0 },
+ { status: "fatal", cost: null },
+ { status: "completed", cost: null },
+ ]);
});
it("a sub-session's session_meta registers the origin→model mapping; token_usage is attributed via it", async () => {
- const rec = wire(UsageRecorder, { usage: repo, clock: { now: () => new Date() } });
+ const rec = recorder();
const childMeta = withOrigin(
sessionMeta(meta("session-child", "child-model")),
"session-child",
@@ -103,20 +202,20 @@ describe("usage-recorder", () => {
});
it("falls back to the main Session's Model when the origin mapping is missing", async () => {
- const rec = wire(UsageRecorder, { usage: repo, clock: { now: () => new Date() } });
+ const rec = recorder();
await rec.record(CTX, withOrigin(tokenUsage(counts(5), counts(5)), "session-unknown"));
const row = db.prepare("SELECT model_id FROM usage_records").get()!;
expect(row.model_id).toBe("main-model");
});
it("non-token_usage messages are a no-op", async () => {
- const rec = wire(UsageRecorder, { usage: repo, clock: { now: () => new Date() } });
+ const rec = recorder();
await rec.record(CTX, sessionMeta(meta("session-main", "main-model")));
expect(db.prepare("SELECT COUNT(*) AS n FROM usage_records").get()!.n).toBe(0);
});
it("the origin mapping is capped: past the limit the earliest entry is evicted and falls back to the main Session's Model", async () => {
- const rec = wire(UsageRecorder, { usage: repo, clock: { now: () => new Date() } });
+ const rec = recorder();
for (let i = 0; i <= ORIGIN_MODELS_MAX; i++) {
// ORIGIN_MODELS_MAX + 1 entries total: the earliest, sub-0, gets evicted.
await rec.record(CTX, withOrigin(sessionMeta(meta(`sub-${i}`, "sub-model")), `sub-${i}`));
@@ -129,19 +228,20 @@ describe("usage-recorder", () => {
});
});
-describe("usage-service (cost computed on the fly)", () => {
+describe("usage-service (sums the costs fixed at record time)", () => {
let db: DatabaseSync;
let repo: UsageRepo;
let service: (now: Date) => UsageService;
- /** Mutable pricing table: simulates a "price added later" — change the price after inserting a record, and the query reflects it immediately. */
+ /**
+ * The price each model has when a row is WRITTEN: `insert` fixes the row's cost from it, as the
+ * recorder does. Changing it afterwards simulates a later price edit — which must not move a
+ * recorded row.
+ */
let pricing: Record<string, PricingRates | undefined>;
- // The pricing lookup callback takes three params (projectId, provider, modelId): locates the
- // price via the paired reference. These fixtures use models with no schedule, so both tiers
- // are the one rate — a scheduled model's two tiers are exercised in the peak-split test below.
- const lookup = async (_p: string, _provider: string, modelId: string) => {
- const rates = pricing[modelId];
- return rates === undefined ? undefined : { peak: rates, offPeak: rates };
+ /** Queries never look a price up: they sum what was recorded. */
+ const lookup: PricingLookup = async () => {
+ throw new Error("a usage query must not re-price recorded rows");
};
beforeEach(() => {
@@ -158,7 +258,16 @@ describe("usage-service (cost computed on the fly)", () => {
const ROW_COST = (10 * 0.3 + 1 * 3.75 + 5 * 15) / 1e6;
function insert(date: string, opts: Partial<Parameters<UsageRepo["insert"]>[0]> = {}): void {
+ const row = {
+ cacheRead: 10,
+ cacheWrite: 1,
+ output: 5,
+ modelId: "m1",
+ ...opts,
+ };
+ const rates = pricing[row.modelId];
repo.insert({
+ cost: rates === undefined ? null : requestCostUsd(row, rates),
ts: `${date}T00:00:00.000Z`,
date,
projectId: "p1",
@@ -175,63 +284,21 @@ describe("usage-service (cost computed on the fly)", () => {
});
}
- it("a scheduled model is priced per record, and the total does not move with the clock", async () => {
- // The defect this pins: pricing the whole table at whichever tier is in force when the page
- // is opened made a finished week's cost double at 09:00 Beijing and halve at 12:00. The tier
- // is a fact about when each request ran, so it is decided from that record's own `ts`.
- //
- // 2026-08-31 is a Monday. 01:30Z is 09:30 in Beijing (peak); 12:00Z is 20:00 (off-peak).
- const REF = { provider: "deepseek", modelId: "deepseek-flash" };
- insert("2026-08-31", { ...REF, ts: "2026-08-31T01:30:00.000Z" });
- insert("2026-08-31", { ...REF, ts: "2026-08-31T12:00:00.000Z" });
- pricing["deepseek-flash"] = { cacheRead: 1, cacheWrite: 2, output: 4 };
- const tiered = async () => ({
- peak: { cacheRead: 1, cacheWrite: 2, output: 4 },
- offPeak: { cacheRead: 0.5, cacheWrite: 1, output: 2 },
- });
- // One row's Tokens are cacheRead 10 / cacheWrite 1 / output 5, so the peak record costs
- // (10*1 + 1*2 + 5*4)/1e6 and the off-peak one exactly half of that.
- const peakCost = (10 * 1 + 1 * 2 + 5 * 4) / 1e6;
- const expected = peakCost + peakCost / 2;
+ it("a query sums the recorded costs, and the total does not move with the clock", async () => {
+ // Two rows fixed at different rates (the tier each ran in, decided when it was recorded):
+ // reading them at any hour gives the same total.
+ insert("2026-08-31", { ts: "2026-08-31T01:30:00.000Z", cost: 0.002 });
+ insert("2026-08-31", { ts: "2026-08-31T12:00:00.000Z", cost: 0.001 });
for (const at of ["2026-08-31T01:30:00Z", "2026-08-31T12:00:00Z", "2026-09-06T01:30:00Z"]) {
- const svc = wire(UsageService, {
- usage: repo,
- errors: wire(ErrorsRepo, { db: db }),
- lookupPricing: tiered,
- clock: { now: () => new Date(at) },
+ const res = await service(new Date(at)).query("p1", {
+ groupBy: "date",
+ from: "2026-08-31",
+ to: "2026-08-31",
});
- const res = await svc.query("p1", { groupBy: "date", from: "2026-08-31", to: "2026-08-31" });
- expect(res.summary.total.cost, at).toBeCloseTo(expected, 10);
+ expect(res.summary.total.cost, at).toBeCloseTo(0.003, 12);
}
});
- it("each scheduled reference is priced by its own seller's windows in the same query", async () => {
- // Two schedules in the catalog: Qwen's DeepSeek rows bill peak 08:00-22:00 Beijing every
- // day, DeepSeek's own rows only in weekday office hours. 2026-09-05 is a Saturday: 02:00Z
- // is 10:00 in Beijing (peak for Qwen, off-peak for DeepSeek), 15:00Z is 23:00 (off-peak for
- // both).
- const QWEN = { provider: "qwen-pay-as-you-go", modelId: "deepseek-v4.1-flash" };
- const DEEPSEEK = { provider: "deepseek", modelId: "deepseek-flash" };
- insert("2026-09-05", { ...QWEN, ts: "2026-09-05T02:00:00.000Z" });
- insert("2026-09-05", { ...QWEN, ts: "2026-09-05T15:00:00.000Z" });
- insert("2026-09-05", { ...DEEPSEEK, ts: "2026-09-05T02:00:00.000Z" });
- const svc = wire(UsageService, {
- usage: repo,
- errors: wire(ErrorsRepo, { db: db }),
- lookupPricing: async () => ({
- peak: { cacheRead: 1, cacheWrite: 2, output: 4 },
- offPeak: { cacheRead: 0.5, cacheWrite: 1, output: 2 },
- }),
- clock: { now: () => new Date("2026-09-05T12:00:00Z") },
- });
- const res = await svc.query("p1", { groupBy: "model", from: "2026-09-05", to: "2026-09-05" });
- const costOf = (ref: { provider: string; modelId: string }) =>
- res.groups.find((g) => g.provider === ref.provider && g.key === ref.modelId)?.cost;
- const peakCost = (10 * 1 + 1 * 2 + 5 * 4) / 1e6;
- expect(costOf(QWEN)).toBeCloseTo(peakCost + peakCost / 2, 10);
- expect(costOf(DEEPSEEK)).toBeCloseTo(peakCost / 2, 10);
- });
-
it("summary cards: today / last 7 days / cumulative; Models without pricing flag hasUncosted", async () => {
const now = new Date("2026-07-06T10:00:00");
const today = formatLocalDate(now);
@@ -249,19 +316,27 @@ describe("usage-service (cost computed on the fly)", () => {
expect(res.summary.last7d.hasUncosted).toBe(false);
});
- it("price added later: no pricing at insert time; once configured, queries price it immediately", async () => {
+ it("a price changed later never re-prices a recorded row: only the rows written after it carry it", async () => {
const now = new Date("2026-07-06T10:00:00");
- insert("2026-07-06", { modelId: "m-late" });
+ insert("2026-07-06", { modelId: "m-late" }); // no price yet: recorded uncosted
+ insert("2026-07-06"); // m1 at its old price
const svc = service(now);
const before = await svc.query("p1", { groupBy: "date" });
- expect(before.summary.total.cost).toBeNull();
+ expect(before.summary.total.cost).toBeCloseTo(ROW_COST, 12);
expect(before.summary.total.hasUncosted).toBe(true);
+ // A price added for m-late and m1 re-priced: the two recorded rows keep their figures.
pricing["m-late"] = { cacheRead: 1, cacheWrite: 1, output: 1 };
+ pricing.m1 = { cacheRead: 100, cacheWrite: 100, output: 100 };
+ const unchanged = await svc.query("p1", { groupBy: "date" });
+ expect(unchanged.summary.total.cost).toBeCloseTo(ROW_COST, 12);
+ expect(unchanged.summary.total.hasUncosted).toBe(true);
+
+ insert("2026-07-06", { modelId: "m-late" });
const after = await svc.query("p1", { groupBy: "date" });
- expect(after.summary.total.cost).toBeCloseTo((10 + 1 + 5) / 1e6, 12);
- expect(after.summary.total.hasUncosted).toBe(false);
+ expect(after.summary.total.cost).toBeCloseTo(ROW_COST + (10 + 1 + 5) / 1e6, 12);
+ expect(after.summary.total.hasUncosted).toBe(true); // the first m-late row stays uncosted
});
it("group aggregation: date sorted descending; agent/model/session dimensions with agentId drill-down; folded across Models", async () => {
@@ -290,25 +365,16 @@ describe("usage-service (cost computed on the fly)", () => {
expect(other.groups).toEqual([]);
});
- it("pricing is looked up for every reference the response prices, and only those", async () => {
+ it("every cost figure in a response is the recorded sum, with no price lookup at all", async () => {
const now = new Date("2026-07-06T10:00:00");
- pricing["m-old"] = { cacheRead: 1, cacheWrite: 1, output: 1 };
insert("2026-07-06", { modelId: "m1" });
- // Inside the last 30 days but outside the requested range: no surviving aggregate
- // covers it, so it must not be priced — and must not perturb the ones that are.
- insert("2026-06-20", { modelId: "m-old" });
- const asked: string[] = [];
- const svc = wire(UsageService, {
- usage: repo,
- errors: wire(ErrorsRepo, { db: db }),
- lookupPricing: async (p: string, provider: string, modelId: string) => {
- asked.push(modelId);
- return lookup(p, provider, modelId);
- },
- clock: { now: () => now },
+ // Outside the requested range: it must not perturb the figures that are in range.
+ insert("2026-06-20", { modelId: "m1", cost: 1 });
+ const res = await service(now).query("p1", {
+ groupBy: "date",
+ from: "2026-07-06",
+ to: "2026-07-06",
});
- const res = await svc.query("p1", { groupBy: "date", from: "2026-07-06", to: "2026-07-06" });
- expect(asked).toEqual(["m1"]);
expect(res.summary.total.cost).toBeCloseTo(ROW_COST, 12);
expect(res.summary.today.cost).toBeCloseTo(ROW_COST, 12);
expect(res.groups[0]!.cost).toBeCloseTo(ROW_COST, 12);
@@ -433,6 +499,7 @@ describe("usage-service model totals (unfiltered, for the models page)", () => {
function insert(date: string, opts: Partial<Parameters<UsageRepo["insert"]>[0]> = {}): void {
repo.insert({
+ cost: null,
ts: `${date}T00:00:00.000Z`,
date,
projectId: "p1",
@@ -478,11 +545,9 @@ describe("usage-service series (zero-filled time-series buckets)", () => {
let db: DatabaseSync;
let repo: UsageRepo;
let service: (now: Date) => UsageService;
+ /** The price a row's cost is fixed at when `insert` writes it. */
let pricing: Record<string, PricingRates | undefined>;
- const lookup = async (_p: string, _provider: string, modelId: string) => {
- const rates = pricing[modelId];
- return rates === undefined ? undefined : { peak: rates, offPeak: rates };
- };
+ const lookup: PricingLookup = async () => undefined;
beforeEach(() => {
db = openDatabase(":memory:");
@@ -497,7 +562,10 @@ describe("usage-service series (zero-filled time-series buckets)", () => {
const ROW_COST = (10 * 0.3 + 1 * 3.75 + 5 * 15) / 1e6;
function insert(date: string, opts: Partial<Parameters<UsageRepo["insert"]>[0]> = {}): void {
+ const row = { cacheRead: 10, cacheWrite: 1, output: 5, modelId: "m1", ...opts };
+ const rates = pricing[row.modelId];
repo.insert({
+ cost: rates === undefined ? null : requestCostUsd(row, rates),
ts: `${date}T00:00:00.000Z`,
date,
projectId: "p1",
@@ -706,6 +774,123 @@ describe("usage-service series (zero-filled time-series buckets)", () => {
});
});
+describe("usage-service settleUnsettledCosts (COMPATIBILITY: rows from before costs were fixed)", () => {
+ let db: DatabaseSync;
+ let repo: UsageRepo;
+
+ beforeEach(() => {
+ db = openDatabase(":memory:");
+ repo = wire(UsageRepo, { db: db });
+ });
+ afterEach(() => db.close());
+
+ const COUNTS = { cacheRead: 10, cacheWrite: 1, output: 5 };
+
+ /** A row as a build that did not price rows wrote it: Tokens only, cost_settled left at 0. */
+ function legacyRow(ts: string, provider: string, modelId: string): void {
+ db.prepare(
+ `INSERT INTO usage_records
+ (ts, date, project_id, agent_id, session_id, provider, model_id, cache_read, cache_write, output, total)
+ VALUES (?, ?, 'p1', 'a1', 's1', ?, ?, 10, 1, 5, 16)`,
+ ).run(ts, ts.slice(0, 10), provider, modelId);
+ }
+
+ it("costs each old row once, at the price its Project stores now, at the tier its own timestamp fell in", async () => {
+ // The lookup stands in for `getPricing`: what the Project bills for a reference, at the
+ // instant asked — list price, the row's promotion and that instant's tier, all folded in. A
+ // scheduled reference's two legacy rows, eight hours of Beijing time apart, therefore settle
+ // at the two different tiers they actually ran in rather than at one hour of the clock's.
+ const deepseekEntry = catalogEntryFor("deepseek", "deepseek-v4-flash")!;
+ const schedule = deepseekEntry.offPeakDiscount!;
+ const peak = deepseekEntry.pricing!;
+ const peakRate = {
+ cacheRead: peak.cache_read,
+ cacheWrite: peak.cache_write,
+ output: peak.output,
+ };
+ const less = (v: number, fraction: number): number =>
+ Math.round(v * (1 - fraction) * 1e6) / 1e6;
+ const half = (v: number): number => less(v, schedule.rate);
+ // A catalog row on a flat promotion: the Project's price for it is the list rate less that
+ // fraction, at either tier (glm-5.3-flash has no schedule).
+ const promoted = catalogEntryFor("tokendance", "glm-5.3-flash")!;
+ expect(promoted.discount).toBeGreaterThan(0);
+ const list = promoted.pricing!;
+ const discounted = {
+ cacheRead: less(list.cache_read, promoted.discount!),
+ cacheWrite: less(list.cache_write, promoted.discount!),
+ output: less(list.output, promoted.discount!),
+ };
+ const lookups: string[] = [];
+ const svc = wire(UsageService, {
+ usage: repo,
+ errors: wire(ErrorsRepo, { db: db }),
+ lookupPricing: async (_p: string, provider: string, modelId: string, at: Date) => {
+ lookups.push(`${provider}/${modelId}@${at.toISOString()}`);
+ if (provider === "deepseek") {
+ return offPeakAt(schedule, at)
+ ? {
+ cacheRead: half(peakRate.cacheRead),
+ cacheWrite: half(peakRate.cacheWrite),
+ output: half(peakRate.output),
+ }
+ : peakRate;
+ }
+ if (provider === "tokendance") return discounted;
+ return undefined;
+ },
+ clock: { now: () => new Date() },
+ });
+ // Monday 2026-08-31: 01:30Z is 09:30 Beijing (peak), 12:00Z is 20:00 (off-peak).
+ legacyRow("2026-08-31T01:30:00.000Z", "deepseek", "deepseek-v4-flash");
+ legacyRow("2026-08-31T12:00:00.000Z", "deepseek", "deepseek-v4-flash");
+ legacyRow("2026-08-31T12:00:00.000Z", "tokendance", "glm-5.3-flash");
+ legacyRow("2026-08-31T12:00:00.000Z", "custom", "m-unpriced");
+ // A row the recorder fixed is never touched, and never priced for again.
+ repo.insert({
+ ts: "2026-08-31T12:00:00.000Z",
+ date: "2026-08-31",
+ projectId: "p1",
+ agentId: "a1",
+ sessionId: "s1",
+ originSessionId: null,
+ provider: "deepseek",
+ modelId: "deepseek-v4-flash",
+ ...COUNTS,
+ total: 16,
+ cost: 42,
+ });
+
+ expect(await svc.settleUnsettledCosts()).toBe(4);
+ // Every unsettled row is asked for at its OWN timestamp (the settled one is not asked for at
+ // all), so the two rows of one reference settle at the tier each actually ran in.
+ expect([...lookups].sort()).toEqual(
+ [
+ "deepseek/deepseek-v4-flash@2026-08-31T01:30:00.000Z",
+ "deepseek/deepseek-v4-flash@2026-08-31T12:00:00.000Z",
+ "tokendance/glm-5.3-flash@2026-08-31T12:00:00.000Z",
+ "custom/m-unpriced@2026-08-31T12:00:00.000Z",
+ ].sort(),
+ );
+ const rows = db
+ .prepare("SELECT cost, cost_settled FROM usage_records ORDER BY id")
+ .all() as Array<{ cost: number | null; cost_settled: number }>;
+ const peakCost = requestCostUsd(COUNTS, peakRate);
+ expect(rows[0]!.cost).toBeCloseTo(peakCost, 15);
+ expect(rows[1]!.cost).toBeCloseTo(peakCost * (1 - schedule.rate), 10);
+ expect(rows[1]!.cost).toBeLessThan(rows[0]!.cost!);
+ expect(rows[2]!.cost).toBeCloseTo(requestCostUsd(COUNTS, discounted), 15);
+ expect(rows[3]!.cost).toBeNull();
+ expect(rows[4]!.cost).toBe(42);
+ expect(rows.every((r) => r.cost_settled === 1)).toBe(true);
+
+ // A second boot finds nothing left to settle, and reads no price for it.
+ lookups.length = 0;
+ expect(await svc.settleUnsettledCosts()).toBe(0);
+ expect(lookups).toEqual([]);
+ });
+});
+
describe("bucket enumeration across a DST transition", () => {
// The zero-fill skeleton and SQLite's `strftime(..., 'localtime')` must agree key for key.
// A fall-back replays a whole local hour, so two instants an hour apart share one key;