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