diff --git a/apps/server/src/serverSettings.test.ts b/apps/server/src/serverSettings.test.ts index 873649cb168f5..03b89e495553c 100644 --- a/apps/server/src/serverSettings.test.ts +++ b/apps/server/src/serverSettings.test.ts @@ -2365,7 +2365,10 @@ it.layer(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))("server settings" }).pipe(Effect.provide(layerServerSettings())), ); - it.effect("leaves an unreadable settings.json untouched instead of folding over it", () => + it.effect.each([ + { label: "malformed JSON", broken: '{"defaultAutoPull": tru' }, + { label: "invalid retention", broken: '{"usageHistoryRetentionDays": 0}' }, + ])("leaves settings.json with $label untouched and disables destructive defaults", ({ broken }) => Effect.gen(function* () { const serverConfig = yield* ServerConfig.ServerConfig; const fileSystem = yield* FileSystem.FileSystem; @@ -2380,12 +2383,12 @@ it.layer(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))("server settings" ${"2026-08-25T00:00:00.000Z"}, ${"2026-08-25T00:00:00.000Z"} ) `; - const broken = '{"defaultAutoPull": tru'; yield* fileSystem.writeFileString(serverConfig.settingsPath, broken); const settings = yield* serverSettings.getSettings; assert.isFalse(settings.projectSettingsFolded); assert.isFalse(settings.continueThreadsAfterServerUpdate); + assert.equal(settings.usageHistoryRetentionDays, "unlimited"); assert.deepEqual(settings.projectSettingsOverrides, {}); assert.equal(yield* fileSystem.readFileString(serverConfig.settingsPath), broken); diff --git a/apps/server/src/serverSettings.ts b/apps/server/src/serverSettings.ts index 4dc30d29a6cff..81106d27b7c76 100644 --- a/apps/server/src/serverSettings.ts +++ b/apps/server/src/serverSettings.ts @@ -806,7 +806,11 @@ const make = Effect.gen(function* () { if (decoded._tag === "Failure" || legacySettings._tag === "Failure") { const failure = decoded._tag === "Failure" ? decoded : legacySettings; // The file may hold an opt-out we can no longer read; never resume threads on a guess. - settings = { ...managed.defaults, continueThreadsAfterServerUpdate: false }; + settings = { + ...managed.defaults, + continueThreadsAfterServerUpdate: false, + usageHistoryRetentionDays: "unlimited", + }; if (failure._tag === "Failure") { parseFailure = Option.some(Cause.squash(failure.cause)); yield* Effect.logWarning("failed to parse settings.json, using defaults", { diff --git a/apps/server/src/usage/UsageService.test.ts b/apps/server/src/usage/UsageService.test.ts index 01cbf3a9f52ce..9a7f7ab82c8f1 100644 --- a/apps/server/src/usage/UsageService.test.ts +++ b/apps/server/src/usage/UsageService.test.ts @@ -25,6 +25,7 @@ import { } from "@t3tools/contracts"; import * as Duration from "effect/Duration"; import * as Clock from "effect/Clock"; +import * as DateTime from "effect/DateTime"; import * as Deferred from "effect/Deferred"; import * as Effect from "effect/Effect"; import * as Exit from "effect/Exit"; @@ -289,12 +290,14 @@ function makeFakeCursor() { events: [] as { readonly timestampMs: number; readonly outputTokens: number }[], error: null as string | null, gate: undefined as Deferred.Deferred | undefined, + started: undefined as Deferred.Deferred | undefined, calls: [] as { readonly sinceMs: number; readonly untilMs: number }[], credentials: [] as unknown[], }; const read = (credential: unknown, sinceMs: number, untilMs: number) => Effect.gen(function* () { state.calls.push({ sinceMs, untilMs }); + if (state.started !== undefined) yield* Deferred.succeed(state.started, undefined); state.credentials.push(credential); if (state.gate !== undefined) yield* Deferred.await(state.gate); const { accountKey, error } = state; @@ -1864,45 +1867,119 @@ describe("UsageService", () => { }), ); - it.effect("restores the Cursor account cache after a restart", () => + it.effect.each([ + { label: "default", retention: undefined, cutoff: CURSOR_NOW - 92 * 24 * HOUR_MS }, + { label: "unlimited", retention: "unlimited" as const, cutoff: 0 }, + { label: "36500 days", retention: 36500, cutoff: 0 }, + ])( + "propagates the $label cutoff and restores the Cursor account cache after a restart", + ({ retention, cutoff }) => + Effect.gen(function* () { + const { settings, home } = yield* setup; + yield* TestClock.setTime(CURSOR_NOW); + const before = makeFakeCursor(); + before.state.events = [ + { timestampMs: CURSOR_NOW - 30 * HOUR_MS, outputTokens: 5 }, + { timestampMs: CURSOR_NOW - 3 * HOUR_MS, outputTokens: 7 }, + ]; + yield* Effect.gen(function* () { + const first = yield* makeWithCursor(before.read); + const original = yield* first.readSummary({ ...WINDOW, awaitRefresh: true }); + assert.deepStrictEqual(before.state.calls, [{ sinceMs: cutoff, untilMs: CURSOR_NOW }]); + yield* first.awaitPersisted; + + const after = makeFakeCursor(); + after.state.events = before.state.events; + const restarted = yield* makeWithCursor(after.read); + const restored = yield* restarted.readSummary(WINDOW); + assert.isUndefined(cursorSource(restored)?.refreshing); + assert.deepStrictEqual(restored.buckets, original.buckets); + assert.deepStrictEqual(cursorSource(restored), cursorSource(original)); + assert.strictEqual(after.state.calls.length, 0); + + yield* TestClock.adjust(Duration.minutes(2)); + const refreshed = yield* restarted.readSummary({ ...WINDOW, awaitRefresh: true }); + assert.deepStrictEqual(refreshed.buckets, original.buckets); + assert.deepStrictEqual(after.state.calls, [ + { sinceMs: CURSOR_NOW - HOUR_MS, untilMs: CURSOR_NOW + 2 * 60 * 1000 }, + ]); + }).pipe( + Effect.provide( + layerService({ + prefix: "usage-service-cursor-restart", + environment: { CURSOR_API_KEY: "test-key" }, + home, + settings: { + ...settings, + ...(retention === undefined ? {} : { usageHistoryRetentionDays: retention }), + }, + }), + ), + ); + }), + ); + + it.effect("widens Cursor history after awaiting a shared narrower refresh", () => Effect.gen(function* () { const { settings, home } = yield* setup; yield* TestClock.setTime(CURSOR_NOW); - const before = makeFakeCursor(); - before.state.events = [ - { timestampMs: CURSOR_NOW - 30 * HOUR_MS, outputTokens: 5 }, + const cursor = makeFakeCursor(); + cursor.state.gate = yield* Deferred.make(); + cursor.state.started = yield* Deferred.make(); + cursor.state.events = [ + { timestampMs: CURSOR_NOW - 120 * 24 * HOUR_MS, outputTokens: 5 }, { timestampMs: CURSOR_NOW - 3 * HOUR_MS, outputTokens: 7 }, ]; - yield* Effect.gen(function* () { - const first = yield* makeWithCursor(before.read); - const original = yield* first.readSummary({ ...WINDOW, awaitRefresh: true }); - yield* first.awaitPersisted; - - const after = makeFakeCursor(); - after.state.events = before.state.events; - const restarted = yield* makeWithCursor(after.read); - const restored = yield* restarted.readSummary(WINDOW); - assert.isUndefined(cursorSource(restored)?.refreshing); - assert.deepStrictEqual(restored.buckets, original.buckets); - assert.deepStrictEqual(cursorSource(restored), cursorSource(original)); - assert.strictEqual(after.state.calls.length, 0); - - yield* TestClock.adjust(Duration.minutes(2)); - const refreshed = yield* restarted.readSummary({ ...WINDOW, awaitRefresh: true }); - assert.deepStrictEqual(refreshed.buckets, original.buckets); - assert.deepStrictEqual(after.state.calls, [ - { sinceMs: CURSOR_NOW - HOUR_MS, untilMs: CURSOR_NOW + 2 * 60 * 1000 }, - ]); - }).pipe( - Effect.provide( - layerService({ - prefix: "usage-service-cursor-restart", - home, - settings, + const context = yield* Layer.build( + layerCursorUsageAccounts( + Layer.succeed(CursorAccountReader.CursorAccountReader, { read: cursor.read }), + ).pipe( + Layer.provide( + layerService({ + prefix: "usage-service-cursor-shared-refresh", + home, + settings, + platform: "darwin", + }), + ), + ), + ); + const accounts = Context.get(context, CursorUsageAccounts.CursorUsageAccounts); + const input = { + instances: [ + { + instanceId: ProviderInstanceId.make("cursor"), environment: { CURSOR_API_KEY: "test-key" }, - }), + }, + ], + windowStartMs: 0, + retentionCutoffMs: CURSOR_NOW - 92 * 24 * HOUR_MS, + awaitRefresh: false, + }; + const narrow = yield* accounts.scan(input); + assert.isTrue(narrow[0]?.refreshing); + yield* Deferred.await(cursor.state.started); + const wider = yield* accounts + .scan({ ...input, retentionCutoffMs: 0, awaitRefresh: true }) + .pipe(Effect.forkChild({ startImmediately: true })); + assert.strictEqual(cursor.state.calls.length, 1); + yield* Deferred.succeed(cursor.state.gate, undefined); + const sources = yield* Fiber.join(wider); + assert.deepStrictEqual(cursor.state.calls, [ + { sinceMs: input.retentionCutoffMs, untilMs: CURSOR_NOW }, + { sinceMs: 0, untilMs: CURSOR_NOW }, + ]); + assert.strictEqual(sources[0]?.status, "ok"); + assert.deepStrictEqual( + sources[0]?.files?.flatMap((file) => + file.records.map(({ timestampMs, totals }) => ({ + timestampMs, + outputTokens: totals.outputTokens, + })), ), + cursor.state.events, ); + yield* accounts.awaitPersisted; }), ); @@ -3536,6 +3613,116 @@ describe("UsageService", () => { }), ); + it.effect.each([ + { label: "the default 92 days", retention: undefined, expected: 1 }, + { label: "unlimited", retention: "unlimited" as const, expected: 15 }, + ])( + "retains deleted transcripts according to $label across restart and settings changes", + ({ retention, expected }) => + Effect.gen(function* () { + const { transcript, settings, home } = yield* setup; + const now = Date.parse("2026-08-02T12:00:00Z"); + yield* TestClock.setTime(now); + const window = { ...WINDOW, sinceDay: UsageDay.make("2024-01-01") }; + const files = [92, 93, 180, 730].map((days, index) => ({ + path: `${transcript}-${index}.jsonl`, + timestamp: now - days * 86400000, + content: claudeLine(index, 2 ** index).replace( + "2026-08-01T10:00:00Z", + DateTime.formatIso(DateTime.makeUnsafe(now - days * 86400000)), + ), + })); + yield* Effect.promise(async () => { + for (const file of files) { + await NodeFSP.writeFile(file.path, file.content); + await NodeFSP.utimes(file.path, file.timestamp / 1000, file.timestamp / 1000); + } + }); + yield* Effect.gen(function* () { + const service = yield* UsageService.make; + const first = yield* service.readSummary(window); + assert.strictEqual(totalOutputTokens(first), 15); + yield* service.awaitPersisted; + yield* Effect.promise(() => Promise.all(files.map((file) => NodeFSP.rm(file.path)))); + const restarted = yield* UsageService.make; + const saved = yield* restarted.readSummary(window); + assert.strictEqual(totalOutputTokens(saved), expected); + assert.deepStrictEqual(saved.sources[0]?.fingerprint, first.sources[0]?.fingerprint); + const narrow = yield* restarted.readSummary(WINDOW); + assert.strictEqual(totalOutputTokens(narrow), 0); + assert.strictEqual(narrow.sources[0]?.distinctSessions, 0); + + const config = yield* ServerSettings.ServerSettingsService; + yield* config.updateSettings({ usageHistoryRetentionDays: 1 }); + assert.strictEqual(totalOutputTokens(yield* restarted.readSummary(window)), 0); + yield* restarted.awaitPersisted; + yield* config.updateSettings({ usageHistoryRetentionDays: "unlimited" }); + const afterPruning = yield* UsageService.make; + assert.strictEqual(totalOutputTokens(yield* afterPruning.readSummary(window)), 0); + }).pipe( + Effect.provide( + layerService({ + prefix: "usage-service-retention", + home, + settings: { + ...settings, + ...(retention === undefined ? {} : { usageHistoryRetentionDays: retention }), + }, + }), + ), + ); + }), + ); + + it.effect("keeps retained history when an obsolete scan finishes after retention widens", () => + Effect.gen(function* () { + const { transcript, settings, home } = yield* setup; + yield* TestClock.setTime(CURSOR_NOW); + const timestamp = CURSOR_NOW - 180 * 24 * HOUR_MS; + yield* Effect.promise(async () => { + await NodeFSP.writeFile( + transcript, + claudeLine(1, 11).replace( + "2026-08-01T10:00:00Z", + DateTime.formatIso(DateTime.makeUnsafe(timestamp)), + ), + ); + await NodeFSP.utimes(transcript, timestamp / 1000, timestamp / 1000); + }); + const started = yield* Deferred.make(); + const release = yield* Deferred.make(); + let scans = 0; + yield* Effect.gen(function* () { + const config = yield* ServerSettings.ServerSettingsService; + const service = yield* UsageService.make.pipe( + Effect.provideService(CursorUsageAccounts.CursorUsageAccounts, { + scan: () => + Effect.gen(function* () { + if (++scans === 1) { + yield* Deferred.succeed(started, undefined); + yield* Deferred.await(release); + } + return []; + }), + awaitPersisted: Effect.void, + }), + ); + const window = { ...WINDOW, sinceDay: UsageDay.make("2024-01-01") }; + const oldScan = yield* service.readSummary(window).pipe(Effect.forkChild); + yield* Deferred.await(started); + yield* config.updateSettings({ usageHistoryRetentionDays: "unlimited" }); + assert.strictEqual(totalOutputTokens(yield* service.readSummary(window)), 11); + yield* service.awaitPersisted; + yield* Effect.promise(() => NodeFSP.rm(transcript)); + yield* Deferred.succeed(release, undefined); + yield* Fiber.join(oldScan); + yield* service.awaitPersisted; + const restarted = yield* UsageService.make; + assert.strictEqual(totalOutputTokens(yield* restarted.readSummary(window)), 11); + }).pipe(Effect.provide(layerService({ prefix: "usage-retention-race", home, settings }))); + }), + ); + it.effect("credits the same copy of a duplicate after its transcripts are deleted", () => Effect.gen(function* () { const { transcript, settings, home } = yield* setup; diff --git a/apps/server/src/usage/UsageService.ts b/apps/server/src/usage/UsageService.ts index a59fbc66a02ca..30edc903a580f 100644 --- a/apps/server/src/usage/UsageService.ts +++ b/apps/server/src/usage/UsageService.ts @@ -77,7 +77,6 @@ const RATES_REFRESH_FLOOR_MS = 60 * 1000; const MTIME_SLACK_MS = 36 * 60 * 60 * 1000; const MAX_HOURLY_WINDOW_MS = 24 * 60 * 60 * 1000; -const CACHE_RETENTION_DAYS = 92; const STALE_TEMP_DIRECTORY_MS = 60 * 60 * 1000; const TRANSCRIPT_READ_CONCURRENCY = 4; @@ -872,7 +871,10 @@ export const make = Effect.gen(function* () { const windowStartMs = (hourlyWindow?.sinceTimeMs ?? DateTime.toEpochMillis(windowStart.value)) - MTIME_SLACK_MS; - const retentionCutoffMs = startedAtMs - CACHE_RETENTION_DAYS * 24 * 60 * 60 * 1000; + const retentionCutoffMs = + settings.usageHistoryRetentionDays === "unlimited" + ? 0 + : Math.max(0, startedAtMs - settings.usageHistoryRetentionDays * 24 * 60 * 60 * 1000); const awaitRefresh = input.awaitRefresh === true; const collect = Effect.gen(function* () { @@ -1144,14 +1146,26 @@ export const make = Effect.gen(function* () { }); } - const pruned = pruneScanCache(fileCache, retentionCutoffMs); - if (pruned > 0) { - cacheDirty = true; - // Pruned files are no longer saved, so nothing before the cutoff stays covered. - for (const [key, since] of coveredSince) { - if (since < retentionCutoffMs) coveredSince.set(key, retentionCutoffMs); - } - } + yield* settingsService + .withSettingsSnapshot((currentSettings) => + Effect.sync(() => { + if (settings.usageHistoryRetentionDays === currentSettings.usageHistoryRetentionDays) { + const pruned = pruneScanCache(fileCache, retentionCutoffMs); + if (pruned > 0) { + cacheDirty = true; + // Pruned files are no longer saved, so nothing before the cutoff stays covered. + for (const [key, since] of coveredSince) { + if (since < retentionCutoffMs) coveredSince.set(key, retentionCutoffMs); + } + } + } + }), + ) + .pipe( + Effect.catchCause((cause) => + Effect.logWarning("failed to read settings before pruning the usage cache", { cause }), + ), + ); const aggregated = aggregator.finish(); const readAt = yield* DateTime.now; diff --git a/docs/user/usage.md b/docs/user/usage.md index e6b3a46d5a14e..5160becc21567 100644 --- a/docs/user/usage.md +++ b/docs/user/usage.md @@ -20,6 +20,13 @@ record are missing from the totals. Text generation (thread titles, commit messages, PR text, branch names and review guides) is not in the totals for Codex or Claude Code 2.0.63 and newer, because those runs save no session history. +The server keeps scanned usage history for 92 days by default. Claude Code deletes its own +transcripts after 30 days, so for older Claude usage this history is the only record left. To keep +it longer, set `usageHistoryRetentionDays` in `/userdata/settings.json` to a number of days +such as `365`, or to `"unlimited"`. Usage views still show at most 90 days. Lowering the value +prunes older history on the next refresh, and raising it again does not bring pruned history back. +While `settings.json` cannot be read, nothing is pruned. + OpenCode reads its SQLite database and older JSON history. Antigravity reads local conversation databases, including T3-managed profiles. Set `OPENCODE_DATA_DIR` or `ANTIGRAVITY_DATA_DIR` on the server to read a different data directory; comma-separated paths read multiple directories. diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts index 0013e288983e0..040b5e0736a31 100644 --- a/packages/contracts/src/settings.ts +++ b/packages/contracts/src/settings.ts @@ -1348,6 +1348,11 @@ export const StorageCleanupSettings = Schema.Struct({ }); export type StorageCleanupSettings = typeof StorageCleanupSettings.Type; +const UsageHistoryRetentionDays = Schema.Union([ + Schema.Int.check(Schema.isGreaterThan(0)), + Schema.Literal("unlimited"), +]); + const CloudSpeechCredential = SettingsSecretValue.pipe( Schema.withDecodingDefault(Effect.succeed("")), ); @@ -1583,6 +1588,10 @@ export const ServerSettings = Schema.Struct({ Schema.withDecodingDefault(Effect.succeed({})), ), + usageHistoryRetentionDays: UsageHistoryRetentionDays.pipe( + Schema.withDecodingDefault(Effect.succeed(92)), + ), + usagePriceOverrides: Schema.Record(TrimmedNonEmptyString, UsageModelPriceOverride).pipe( Schema.withDecodingDefault(Effect.succeed({})), ), @@ -1971,6 +1980,8 @@ export const ServerSettingsPatch = Schema.Struct({ Schema.Record(SecretProviderId, Schema.NullOr(SecretProviderConfigWrite)), ), + usageHistoryRetentionDays: Schema.optionalKey(UsageHistoryRetentionDays), + usagePriceOverrides: Schema.optionalKey( Schema.Record(TrimmedNonEmptyString, Schema.NullOr(UsageModelPriceOverride)), ), diff --git a/packages/provider-cursor/src/server/CursorUsageAccounts.ts b/packages/provider-cursor/src/server/CursorUsageAccounts.ts index 8c36c107a409c..088a59ca285ed 100644 --- a/packages/provider-cursor/src/server/CursorUsageAccounts.ts +++ b/packages/provider-cursor/src/server/CursorUsageAccounts.ts @@ -198,11 +198,19 @@ const make = Effect.gen(function* () { let refreshing = false; if ( (recentFailure === undefined || nowMs - recentFailure.atMs >= CURSOR_ACCOUNT_TTL_MS) && - !isCursorCacheFresh(caches.get(credentialKey), nowMs) + !isCursorCacheFresh(caches.get(credentialKey), nowMs, retentionStartMs) ) { const refresh = yield* startRefresh(credential, credentialKey, retentionStartMs); - if (awaitRefresh) yield* Deferred.await(refresh); - else refreshing = true; + if (awaitRefresh) { + yield* Deferred.await(refresh); + if ( + !failures.has(credentialKey) && + !isCursorCacheFresh(caches.get(credentialKey), nowMs, retentionStartMs) + ) { + const retry = yield* startRefresh(credential, credentialKey, retentionStartMs); + yield* Deferred.await(retry); + } + } else refreshing = true; } const cache = caches.get(credentialKey); diff --git a/packages/provider-cursor/src/server/accountCache.test.ts b/packages/provider-cursor/src/server/accountCache.test.ts index 939bc6fc22f03..f14e68efe19be 100644 --- a/packages/provider-cursor/src/server/accountCache.test.ts +++ b/packages/provider-cursor/src/server/accountCache.test.ts @@ -1,6 +1,6 @@ import { assert, describe, it } from "@effect/vitest"; -import { cursorFetchRange, mergeCursorFetch } from "./accountCache.ts"; +import { cursorFetchRange, isCursorCacheFresh, mergeCursorFetch } from "./accountCache.ts"; import type { UsageRecord } from "@t3tools/provider-core/server/usage"; const DAY_MS = 24 * 60 * 60 * 1000; @@ -31,6 +31,20 @@ describe("cursorAccountCache", () => { fetchedAtMs: 10 * DAY_MS, records: [record(5 * DAY_MS)], }; + assert.isTrue(isCursorCacheFresh(cache, 10 * DAY_MS, 0)); + const narrow = { ...cache, sinceMs: DAY_MS }; + assert.isFalse(isCursorCacheFresh(narrow, 10 * DAY_MS, 0)); + const widenedRange = cursorFetchRange(narrow, 0, 10 * DAY_MS); + assert.deepStrictEqual(widenedRange, { + sinceMs: 0, + untilMs: 10 * DAY_MS, + }); + const widened = mergeCursorFetch(narrow, "a", widenedRange, cache.records, 10 * DAY_MS, 0); + assert.isTrue(isCursorCacheFresh(widened.cache, 10 * DAY_MS, 0)); + assert.deepStrictEqual(cursorFetchRange(widened.cache, 0, 11 * DAY_MS), { + sinceMs: 10 * DAY_MS - 60 * 60 * 1000, + untilMs: 11 * DAY_MS, + }); const nowMs = 100 * DAY_MS; const range = cursorFetchRange(cache, 10 * DAY_MS, nowMs); assert.deepStrictEqual(range, { sinceMs: 10 * DAY_MS, untilMs: nowMs }); @@ -75,6 +89,19 @@ describe("cursorAccountCache", () => { ); assert.isTrue(pruned.changed); assert.deepStrictEqual(pruned.cache.records, [record(10 * DAY_MS)]); + assert.isTrue( + mergeCursorFetch(cache, "a", range, [record(10 * DAY_MS)], 11 * DAY_MS, 2 * DAY_MS).changed, + ); + assert.isTrue( + mergeCursorFetch( + { ...cache, sinceMs: DAY_MS, records: [] }, + "a", + { sinceMs: 0, untilMs: 11 * DAY_MS }, + [], + 11 * DAY_MS, + 0, + ).changed, + ); assert.isTrue( mergeCursorFetch( cache, diff --git a/packages/provider-cursor/src/server/accountCache.ts b/packages/provider-cursor/src/server/accountCache.ts index c5a68592423df..3d36083626bef 100644 --- a/packages/provider-cursor/src/server/accountCache.ts +++ b/packages/provider-cursor/src/server/accountCache.ts @@ -25,8 +25,13 @@ interface CursorFetchRange { export function isCursorCacheFresh( cache: CursorAccountCache | undefined, nowMs: number, + retentionStartMs: number, ): cache is CursorAccountCache { - return cache !== undefined && nowMs - cache.fetchedAtMs < CURSOR_ACCOUNT_TTL_MS; + return ( + cache !== undefined && + cache.sinceMs <= retentionStartMs && + nowMs - cache.fetchedAtMs < CURSOR_ACCOUNT_TTL_MS + ); } export function cursorFetchRange( @@ -61,6 +66,7 @@ export function mergeCursorFetch( } const changed = cache === undefined || + cache.sinceMs > retentionStartMs || pruned || replacedKeys.size !== added.length || added.some((record) => !replacedKeys.has(record.dedupeKey));