Open History to see the last commit
1import type { UsageProviderKind } from "@t3tools/contracts";
2import type {
3 TranscriptUsageFormat,
4 UsageRecord,
5 UsageSpeed,
6} from "@t3tools/provider-core/server/usage";
7import * as Schema from "effect/Schema";
8
9import { CLAUDE_SYNTHETIC_MODEL } from "../provider/Drivers/claudeUsage.ts";
10import { mergeUsageCopies } from "./usageAggregation.ts";
11import { GUARD_LENGTH, type TranscriptParsePosition } from "./usageTranscriptReader.ts";
12
13const USAGE_SCAN_CACHE_VERSION = 14 as const;
14const SPEED_COMPATIBLE_SINCE_VERSION = 4;
15
16/**
17 * An older server sharing that directory cannot read a newer cache and would
18 * replace it, dropping saved usage for deleted transcripts. Separate files keep
19 * the newer one; older files are removed once it is saved.
20 */
21export const SCAN_CACHE_FILE_NAME = "usage-scan-cache-v14.json";
22export const LEGACY_SCAN_CACHE_FILE_NAMES = [
23 "usage-scan-cache-v13.json",
24 "usage-scan-cache-v12.json",
25 "usage-scan-cache-v11.json",
26 "usage-scan-cache-v10.json",
27 "usage-scan-cache-v9.json",
28 "usage-scan-cache-v8.json",
29 "usage-scan-cache-v7.json",
30 "usage-scan-cache-v6.json",
31 "usage-scan-cache-v5.json",
32 "usage-scan-cache.json",
33] as const;
34
35const SPEEDS: readonly UsageSpeed[] = ["standard", "fast", "ultrafast"];
36
37export interface CachedFile {
38 readonly size: number;
39 readonly mtimeMs: number;
40 readonly provider: UsageProviderKind;
41 readonly records: readonly UsageRecord[];
42 /** Unterminated tail records stay separate because incremental parsing rereads them. */
43 readonly tailRecords: readonly UsageRecord[];
44 /** Whole-file count, including diagnostics from the tentative tail. */
45 readonly malformedRecords: number;
46 readonly position: TranscriptParsePosition;
47}
48
49export type ScanCache = Map<string, CachedFile>;
50
51type SerializedRecord = readonly [
52 timestampMs: number,
53 modelIndex: number,
54 sessionIndex: number,
55 uncachedInputTokens: number,
56 cachedInputTokens: number,
57 cacheCreationTokens: number,
58 outputTokens: number,
59 reasoningTokens: number,
60 dedupeKey: string | null,
61 reportedCostUsd: number | null,
62 speed: number,
63 rateModelIndex?: number | null,
64 unresolvedServiceTierTurnId?: string | null,
65 cacheCreation1hTokens?: number,
66];
67
68interface SerializedFile {
69 readonly s: number;
70 readonly m: number;
71 readonly p: UsageProviderKind;
72 readonly r: readonly SerializedRecord[];
73 readonly t: readonly SerializedRecord[];
74 readonly mr: number;
75 readonly o: number;
76 readonly gl: number;
77 readonly gh: number;
78 readonly cs: unknown;
79}
80
81interface SerializedCache {
82 readonly version: number;
83 readonly models: readonly string[];
84 readonly sessions: readonly string[];
85 readonly files: Readonly<Record<string, SerializedFile>>;
86}
87
88interface InternTables {
89 readonly models: string[];
90 readonly sessions: string[];
91 readonly modelIndex: Map<string, number>;
92 readonly sessionIndex: Map<string, number>;
93}
94
95function makeInternTables(): InternTables {
96 return { models: [], sessions: [], modelIndex: new Map(), sessionIndex: new Map() };
97}
98
99function intern(table: string[], index: Map<string, number>, value: string): number {
100 const existing = index.get(value);
101 if (existing !== undefined) return existing;
102 const next = table.length;
103 table.push(value);
104 index.set(value, next);
105 return next;
106}
107
108function serializeFile(entry: CachedFile, tables: InternTables): SerializedFile {
109 const serializeRecord = (record: UsageRecord): SerializedRecord => [
110 record.timestampMs,
111 intern(tables.models, tables.modelIndex, record.model),
112 intern(tables.sessions, tables.sessionIndex, record.sessionId),
113 record.totals.uncachedInputTokens,
114 record.totals.cachedInputTokens,
115 record.totals.cacheCreationTokens,
116 record.totals.outputTokens,
117 record.totals.reasoningTokens,
118 record.dedupeKey,
119 record.reportedCostUsd,
120 SPEEDS.indexOf(record.speed),
121 record.rateModel === undefined
122 ? null
123 : intern(tables.models, tables.modelIndex, record.rateModel),
124 ...(record.cacheCreation1hTokens !== undefined
125 ? ([record.unresolvedServiceTierTurnId ?? null, record.cacheCreation1hTokens] as const)
126 : record.unresolvedServiceTierTurnId !== undefined
127 ? ([record.unresolvedServiceTierTurnId] as const)
128 : ([] as const)),
129 ];
130 return {
131 s: entry.size,
132 m: entry.mtimeMs,
133 p: entry.provider,
134 r: entry.records.map(serializeRecord),
135 t: entry.tailRecords.map(serializeRecord),
136 mr: entry.malformedRecords,
137 o: entry.position.resumeOffset,
138 gl: entry.position.guardLength,
139 gh: entry.position.guardHash,
140 cs: entry.position.state,
141 };
142}
143
144/** Yields the document in pieces so large caches never become one string; growing intern tables preserve indexes, retaining unused strings until restart. */
145export function makeScanCacheWriter(): (
146 cache: ScanCache,
147 extra: Readonly<Record<string, unknown>>,
148) => Iterable<string> {
149 const tables = makeInternTables();
150 function* encode(entries: readonly (readonly [string, CachedFile])[], extra: object) {
151 yield '{"files":{';
152 for (const [index, [path, entry]] of entries.entries()) {
153 yield `${index === 0 ? "" : ","}${JSON.stringify(path)}:${JSON.stringify(serializeFile(entry, tables))}`;
154 }
155 // Encoded after the files, which may have added to the intern tables.
156 const tail = JSON.stringify({
157 ...extra,
158 version: USAGE_SCAN_CACHE_VERSION,
159 models: tables.models,
160 sessions: tables.sessions,
161 });
162 yield `},${tail.slice(1)}`;
163 }
164 // Snapshot now: the encoding runs later, while the file is written.
165 return (cache, extra) => encode([...cache], extra);
166}
167
168function isRecordArray(value: unknown): value is readonly unknown[] {
169 return Array.isArray(value);
170}
171
172export function decodeScanCache(
173 document: unknown,
174 formats: ReadonlyMap<UsageProviderKind, TranscriptUsageFormat<unknown>>,
175): ScanCache {
176 const cache: ScanCache = new Map();
177 const isValidState = makeStateValidators(formats);
178 if (typeof document !== "object" || document === null) return cache;
179
180 const root = document as Partial<SerializedCache>;
181 const version = root.version;
182 if (
183 typeof version !== "number" ||
184 version < SPEED_COMPATIBLE_SINCE_VERSION ||
185 version > USAGE_SCAN_CACHE_VERSION
186 ) {
187 return cache;
188 }
189 if (!isRecordArray(root.models) || !isRecordArray(root.sessions)) return cache;
190 if (typeof root.files !== "object" || root.files === null) return cache;
191
192 if (!root.models.every((value) => typeof value === "string")) return cache;
193 if (!root.sessions.every((value) => typeof value === "string")) return cache;
194 const models = root.models as readonly string[];
195 const sessions = root.sessions as readonly string[];
196
197 // Reject entire corrupt entries; partial survivors would appear warm and hide usage until the file changes.
198 const decodeRecords = (
199 rows: readonly unknown[],
200 provider: UsageProviderKind,
201 ): UsageRecord[] | null => {
202 const records: UsageRecord[] = [];
203 for (const row of rows) {
204 if (!isRecordArray(row) || row.length < 11) return null;
205 const [
206 timestampMs,
207 modelIndex,
208 sessionIndex,
209 uncached,
210 cached,
211 cacheCreation,
212 output,
213 reasoning,
214 dedupeKey,
215 reportedCostUsd,
216 speedIndex,
217 rateModelIndex,
218 unresolvedServiceTierTurnId,
219 cacheCreation1h = 0,
220 ] = row as SerializedRecord;
221 const speed = typeof speedIndex === "number" ? SPEEDS[speedIndex] : undefined;
222
223 const model = typeof modelIndex === "number" ? models[modelIndex] : undefined;
224 const rateModel = typeof rateModelIndex === "number" ? models[rateModelIndex] : undefined;
225 if (
226 typeof timestampMs !== "number" ||
227 !Number.isFinite(timestampMs) ||
228 model === undefined ||
229 (unresolvedServiceTierTurnId != null && typeof unresolvedServiceTierTurnId !== "string") ||
230 !Number.isFinite(cacheCreation1h) ||
231 (rateModelIndex != null && rateModel === undefined) ||
232 !Number.isFinite(uncached) ||
233 !Number.isFinite(cached) ||
234 !Number.isFinite(cacheCreation) ||
235 !Number.isFinite(output) ||
236 !Number.isFinite(reasoning) ||
237 speed === undefined
238 ) {
239 return null;
240 }
241
242 // Unchanged and deleted transcripts may only exist in the cache, so the
243 // parser cannot remove their previously saved local placeholders.
244 if (provider === "claude" && model === CLAUDE_SYNTHETIC_MODEL) continue;
245
246 records.push({
247 provider,
248 timestampMs,
249 model,
250 ...(rateModel === undefined ? {} : { rateModel }),
251 sessionId: (typeof sessionIndex === "number" ? sessions[sessionIndex] : undefined) ?? "",
252 totals: {
253 uncachedInputTokens: uncached,
254 cachedInputTokens: cached,
255 cacheCreationTokens: cacheCreation,
256 outputTokens: output,
257 reasoningTokens: reasoning,
258 },
259 ...(cacheCreation1h > 0 ? { cacheCreation1hTokens: cacheCreation1h } : {}),
260 reportedCostUsd: typeof reportedCostUsd === "number" ? reportedCostUsd : null,
261 speed,
262 ...(version >= 7 && unresolvedServiceTierTurnId != null
263 ? { unresolvedServiceTierTurnId }
264 : {}),
265 dedupeKey: typeof dedupeKey === "string" ? dedupeKey : null,
266 });
267 }
268 return records;
269 };
270
271 for (const [path, raw] of Object.entries(root.files)) {
272 if (typeof raw !== "object" || raw === null) continue;
273 const entry = raw as Partial<SerializedFile>;
274 if (typeof entry.s !== "number" || typeof entry.m !== "number") continue;
275 if (entry.p === undefined) continue;
276 const format = formats.get(entry.p);
277 if (format === undefined) continue;
278 if (!isRecordArray(entry.r) || !isRecordArray(entry.t)) continue;
279 const malformedRecords = entry.mr === undefined ? 0 : entry.mr;
280 if (!Number.isSafeInteger(malformedRecords) || malformedRecords < 0) continue;
281 // Position fields feed byte offsets and a Buffer allocation in the reader,
282 // so anything outside their real ranges must reject the entry: a bogus
283 // guard length would otherwise fail every parse of the file, silently
284 // dropping its usage instead of costing the documented cold re-parse.
285 if (
286 typeof entry.o !== "number" ||
287 !Number.isSafeInteger(entry.o) ||
288 entry.o < 0 ||
289 typeof entry.gl !== "number" ||
290 !Number.isSafeInteger(entry.gl) ||
291 entry.gl < 0 ||
292 entry.gl > GUARD_LENGTH ||
293 entry.gl > entry.o ||
294 typeof entry.gh !== "number" ||
295 !Number.isFinite(entry.gh)
296 ) {
297 continue;
298 }
299 // Keep history for deleted rollouts, but re-parse incompatible reducer state.
300 // v14 uses Codex request ledgers, including compaction spending omitted by context snapshots.
301 // v10 adds Claude advisor calls; before v12 a repeated Claude key kept its first, possibly partial, copy.
302 // v13 adds Claude 1-hour cache writes.
303 const legacy =
304 (entry.p === "claude" && version < 13) ||
305 (format.state !== undefined && (version < 6 || (entry.p === "codex" && version < 14)));
306 // A corrupt state disqualifies the entry: resuming with it would attach
307 // appended usage to the wrong model or replay fork-copied history.
308 if (!legacy && !isValidState.get(entry.p)?.(entry.cs)) continue;
309 // Before v11 a clean scan could end past an interrupted request whose usage its state dropped,
310 // so a grown file re-parses whole instead of resuming.
311 const resumable = !legacy && !(entry.p === "codex" && version < 11);
312
313 const provider = entry.p;
314 const records = decodeRecords(entry.r, provider);
315 const tailRecords = decodeRecords(entry.t, provider);
316 if (records === null || tailRecords === null) continue;
317
318 cache.set(path, {
319 size: legacy ? -1 : entry.s,
320 mtimeMs: entry.m,
321 provider,
322 records,
323 tailRecords,
324 malformedRecords,
325 position: resumable
326 ? {
327 resumeOffset: entry.o,
328 guardLength: entry.gl,
329 guardHash: entry.gh,
330 state: entry.cs,
331 }
332 : { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
333 });
334 }
335
336 return cache;
337}
338
339function makeStateValidators(
340 formats: ReadonlyMap<UsageProviderKind, TranscriptUsageFormat<unknown>>,
341): ReadonlyMap<UsageProviderKind, (value: unknown) => boolean> {
342 return new Map(
343 [...formats].map(([provider, format]) => {
344 const isState = format.state === undefined ? undefined : Schema.is(format.state.schema);
345 return [
346 provider,
347 (value: unknown) => value === null || (isState !== undefined && isState(value)),
348 ] as const;
349 }),
350 );
351}
352
353export function pruneScanCache(cache: ScanCache, retentionCutoffMs: number): number {
354 let removed = 0;
355 for (const [path, entry] of cache) {
356 if (entry.mtimeMs < retentionCutoffMs) {
357 cache.delete(path);
358 removed += 1;
359 }
360 }
361 return removed;
362}
363
364/** Pass only newline-terminated records: an unterminated tail can still change, so the aggregator merges it per scan. */
365export function dedupeWithinFile(records: readonly UsageRecord[]): readonly UsageRecord[] {
366 const kept: UsageRecord[] = [];
367 const firstIndex = new Map<string, number>();
368 for (const record of records) {
369 if (record.dedupeKey !== null) {
370 const index = firstIndex.get(record.dedupeKey);
371 if (index !== undefined) {
372 kept[index] = mergeUsageCopies(kept[index]!, record);
373 continue;
374 }
375 firstIndex.set(record.dedupeKey, kept.length);
376 }
377 kept.push(record);
378 }
379 return kept;
380}