Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(command): validate cache hydration checkpoints and stabilize ranking (#7086)

teoe06fdc2db38e
diff --git a/Cargo.lock b/Cargo.lock
index 792f3b466b..d23ae12cee 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3161,7 +3161,7 @@ dependencies = [
[[package]]
name = "cache-wasm"
-version = "0.6.26"
+version = "0.6.27"
dependencies = [
"async-lock",
"cache-core",
diff --git a/apps/web/src/features/command/rank-command-search-items.test.ts b/apps/web/src/features/command/rank-command-search-items.test.ts
new file mode 100644
index 0000000000..81e2e2b5cd
--- /dev/null
+++ b/apps/web/src/features/command/rank-command-search-items.test.ts
@@ -0,0 +1,117 @@
+import type { EntityItem } from '@core/context/quickAccess';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { rankCommandSearchItems } from './rank-command-search-items';
+import type { CommandMenuItem } from './useCommandItems';
+
+const NOW = Date.parse('2026-09-26T12:00:00Z');
+const DAY = 24 * 60 * 60 * 1000;
+
+function channel(
+ id: string,
+ name: string,
+ viewedAt = NOW,
+ bucket: 'channel' | 'dm' = 'channel'
+): EntityItem {
+ return {
+ id,
+ kind: 'entity',
+ bucket,
+ searchText: name,
+ sortTimestamp: viewedAt,
+ timestamps: { viewedAt: new Date(viewedAt), updatedAt: new Date(NOW) },
+ data: {
+ id,
+ type: 'channel',
+ name,
+ ownerId: 'owner',
+ channelType: bucket === 'dm' ? 'direct_message' : 'public',
+ },
+ };
+}
+
+function command(id: string, name: string, viewedAt: number): CommandMenuItem {
+ return {
+ id,
+ kind: 'command',
+ bucket: 'command',
+ searchText: name,
+ sortTimestamp: viewedAt,
+ timestamps: { viewedAt: new Date(viewedAt) },
+ data: {
+ description: name,
+ scopeId: 'command-menu',
+ runWithInputFocused: true,
+ },
+ };
+}
+
+function ids(items: CommandMenuItem[], query: string, cacheEnabled = true) {
+ return rankCommandSearchItems(items, query, {
+ preserveAdditionalEntityMatches: cacheEnabled,
+ }).map((item) => item.id);
+}
+
+describe('command menu search ranking', () => {
+ beforeEach(() => vi.useFakeTimers({ now: NOW }));
+ afterEach(() => vi.useRealTimers());
+
+ it.each([false, true])(
+ 'keeps the DM preference with GraphQL %s',
+ (cacheEnabled) => {
+ const items = [
+ channel('channel', 'Alex', NOW),
+ channel('dm', 'Alex', NOW - DAY, 'dm'),
+ ];
+ expect(ids(items, 'Alex', cacheEnabled)).toEqual(['dm', 'channel']);
+ }
+ );
+
+ it.each([false, true])(
+ 'ranks commands and entities by the same viewed recency with GraphQL %s',
+ (cacheEnabled) => {
+ const items = [
+ channel('old-channel', 'Planning', NOW - 20 * DAY),
+ command('command', 'Planning', NOW - DAY),
+ channel('recent-channel', 'Planning', NOW),
+ ];
+ expect(ids(items, 'Planning', cacheEnabled)).toEqual([
+ 'recent-channel',
+ 'command',
+ 'old-channel',
+ ]);
+ }
+ );
+
+ it('keeps ranking independent of whether a match came from cached or local results', () => {
+ const cached = channel('cached', 'Planning', NOW - DAY);
+ const local = channel('local', 'Planning', NOW);
+ expect(ids([cached, local], 'Planning')).toEqual(['local', 'cached']);
+ expect(ids([local, cached], 'Planning')).toEqual(['local', 'cached']);
+ });
+
+ it('breaks equal search scores by recency then id across refreshes', () => {
+ const items = [
+ channel('older', 'Planning', NOW - 50 * DAY),
+ channel('b', 'Planning', NOW - 40 * DAY),
+ channel('a', 'Planning', NOW - 40 * DAY),
+ ];
+ expect(ids(items, 'Planning')).toEqual(['a', 'b', 'older']);
+ expect(ids([...items].reverse(), 'Planning')).toEqual(['a', 'b', 'older']);
+ });
+
+ it('retains broader cache subsequences after regular matches without retaining unmatched commands', () => {
+ const items = [
+ channel('b', 'Quarterly plan'),
+ channel('a', 'Quarterly plan'),
+ command('unmatched-command', 'Quarterly plan', NOW),
+ channel('direct-match', 'Qtr plan', NOW - DAY),
+ ];
+ expect(ids(items, 'qtr', false)).toEqual(['direct-match']);
+ expect(ids(items, 'qtr')).toEqual(['direct-match', 'a', 'b']);
+ expect(ids([...items].reverse(), 'qtr')).toEqual([
+ 'direct-match',
+ 'a',
+ 'b',
+ ]);
+ });
+});
diff --git a/apps/web/src/features/command/rank-command-search-items.ts b/apps/web/src/features/command/rank-command-search-items.ts
new file mode 100644
index 0000000000..36a0d65695
--- /dev/null
+++ b/apps/web/src/features/command/rank-command-search-items.ts
@@ -0,0 +1,46 @@
+import { createFreshSearch } from '@core/util/freshSort';
+import type { CommandMenuItem } from './useCommandItems';
+
+const search = createFreshSearch<CommandMenuItem>({
+ config: {
+ useViewedAt: true,
+ dmBoost: 1.8,
+ fuzzyWeight: 0.7,
+ timeWeight: 0.7,
+ minFuzzyThreshold: 0.1,
+ commaSeparatedChannelMatch: true,
+ },
+ getName: (item) => item.searchText,
+ isDmItem: (item) => item.bucket === 'dm',
+ getTimestamp: (item) => item.timestamps,
+});
+
+function compareRecency(left: CommandMenuItem, right: CommandMenuItem) {
+ return (
+ right.sortTimestamp - left.sortTimestamp || left.id.localeCompare(right.id)
+ );
+}
+
+/** Rank cached and local candidates together using the command menu's rules. */
+export function rankCommandSearchItems(
+ items: CommandMenuItem[],
+ query: string,
+ options: { preserveAdditionalEntityMatches: boolean }
+): CommandMenuItem[] {
+ const ranked = search(items, query)
+ .sort(
+ (left, right) =>
+ right.combinedScore - left.combinedScore ||
+ compareRecency(left.item, right.item)
+ )
+ .map(({ item }) => item);
+ if (!options.preserveAdditionalEntityMatches) return ranked;
+
+ // Cache search accepts broader subsequences than the menu's fuzzy matcher.
+ // Keep these additional matches reachable after the regular ranked results.
+ const matchedIds = new Set(ranked.map((item) => item.id));
+ const additional = items
+ .filter((item) => item.kind === 'entity' && !matchedIds.has(item.id))
+ .sort(compareRecency);
+ return [...ranked, ...additional];
+}
diff --git a/apps/web/src/features/command/useCommandItems.ts b/apps/web/src/features/command/useCommandItems.ts
index 461c25d9d6..6f291c0911 100644
--- a/apps/web/src/features/command/useCommandItems.ts
+++ b/apps/web/src/features/command/useCommandItems.ts
@@ -17,13 +17,10 @@ import {
} from '@core/hotkey/getCommands';
import { activeScope, hotkeyScopeTree } from '@core/hotkey/state';
import type { HotkeyCommand } from '@core/hotkey/types';
-import {
- createFreshSearch,
- type FreshSortConfig,
- type TimestampedItem,
-} from '@core/util/freshSort';
+import type { TimestampedItem } from '@core/util/freshSort';
import { mergeSortedArrays } from '@core/util/list';
import { type Accessor, createMemo } from 'solid-js';
+import { rankCommandSearchItems } from './rank-command-search-items';
import { getCommandLastUsedAt } from './recency';
import { CommandState } from './state';
import type { CategoryFilter, DisplayHotkeyStep } from './types';
@@ -142,17 +139,6 @@ function makeAskAiItem(query: string): AskAiItem {
};
}
-function createSearchConfig(hasQuery: boolean): FreshSortConfig {
- return {
- useViewedAt: true,
- dmBoost: hasQuery ? 1.8 : 1.0,
- fuzzyWeight: hasQuery ? 0.7 : 0.0,
- timeWeight: hasQuery ? 0.7 : 0.9,
- minFuzzyThreshold: hasQuery ? 0.1 : 0,
- commaSeparatedChannelMatch: true,
- };
-}
-
/**
* Helper to convert commands to CommandItem format.
* Deduplicates commands by description since commands with multiple hotkeys
@@ -424,43 +410,15 @@ export function useCommandItems(
);
const categoryItems = category.items;
- const search = createMemo(() => {
- const q = query();
- const hasQuery = q.trim().length > 0;
- return createFreshSearch<CommandMenuItem>({
- config: createSearchConfig(hasQuery),
- getName: (item) => item.searchText,
- isDmItem: (item) => item.bucket === 'dm',
- getTimestamp: (item) => item.timestamps,
- });
- });
-
const rankItems = (
items: CommandMenuItem[],
queryText: string
): CommandMenuItem[] => {
if (!queryText.trim()) return items.filter(showInRecencyList);
- if (
- !quickAccess.usesRecordSelection() &&
- !quickAccess.usesSearchProjection()
- ) {
- return search()(items, queryText).map((result) => result.item);
- }
-
- const entities = items.filter(isEntityItem);
- const localItems = items.filter((item) => !isEntityItem(item));
- const rankedLocalItems = search()(localItems, queryText).map(
- (result) => result.item
- );
- if (entities.length === 0) return rankedLocalItems;
-
- const topCommands = rankedLocalItems.filter(isCommandItem).slice(0, 3);
- const topCommandIds = new Set(topCommands.map((item) => item.id));
- return [
- ...topCommands,
- ...entities,
- ...rankedLocalItems.filter((item) => !topCommandIds.has(item.id)),
- ];
+ return rankCommandSearchItems(items, queryText, {
+ preserveAdditionalEntityMatches:
+ quickAccess.usesRecordSelection() || quickAccess.usesSearchProjection(),
+ });
};
const shouldShowSearchRow = (q: string) => {
diff --git a/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.test.ts b/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.test.ts
index 0792af24ba..8d1d6cc0ca 100644
--- a/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.test.ts
+++ b/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.test.ts
@@ -6,6 +6,7 @@ import type {
SearchDocumentWire,
} from '@graphql-cache/index';
import { INITIAL_CACHE_REVISION } from '@graphql-cache/index';
+import type { CachedGraphqlChannel } from '@queries/channel/graphql';
import type { HistoryItem } from '@queries/history/types';
import { render } from '@solidjs/testing-library';
import {
@@ -35,6 +36,9 @@ import {
const mocks = vi.hoisted(() => ({
search: vi.fn<(args: SearchCacheArgs) => Promise<SearchCachePage>>(),
history: [] as HistoryItem[],
+ channels: vi.fn(() => []),
+ cachedChannels: (): CachedGraphqlChannel[] => [],
+ projectedChannels: [] as CachedGraphqlChannel[],
changed: undefined as (() => void) | undefined,
unsubscribe: vi.fn(),
channelRefetch: vi.fn(),
@@ -61,7 +65,10 @@ vi.mock('@core/constant/allBlocks', () => ({
itemToSafeName: (item: { name: string }) => item.name,
}));
vi.mock('@core/context/channels', () => ({
- useChannelsContext: () => ({ channels: () => [], isLoading: () => false }),
+ useChannelsContext: () => ({
+ channels: () => mocks.channels(),
+ isLoading: () => false,
+ }),
useDmActivityByUserId: () => () => new Map(),
}));
vi.mock('@core/user', () => ({
@@ -71,14 +78,24 @@ vi.mock('@core/user', () => ({
vi.mock('@queries/channel/channels', () => ({
useCachedGraphqlChannelsQuery: () =>
mocks.queries.channels?.() ?? {
- data: [],
+ get data() {
+ return mocks.cachedChannels();
+ },
isSuccess: true,
isLoading: false,
refetch: mocks.channelRefetch,
},
}));
vi.mock('@queries/channel/graphql', () => ({
- materializeCachedGraphqlChannels: async () => [],
+ materializeCachedGraphqlChannels: async (
+ _host: unknown,
+ documents: SearchDocumentWire[]
+ ) =>
+ mocks.projectedChannels.filter((channel) =>
+ documents.some(
+ (document) => document.recordKey === `GraphqlSoupChannel:${channel.id}`
+ )
+ ),
}));
vi.mock('@queries/history/history', () => ({
useHistoryQuery: () =>
@@ -171,6 +188,9 @@ beforeEach(() => {
vi.clearAllMocks();
vi.spyOn(document, 'visibilityState', 'get').mockReturnValue('visible');
mocks.history = [];
+ mocks.channels.mockReset().mockReturnValue([]);
+ mocks.cachedChannels = () => [];
+ mocks.projectedChannels = [];
mocks.companies = [];
mocks.crmEnabled = () => true;
mocks.cacheEnabled = true;
@@ -224,6 +244,33 @@ const restCompany: CrmCompanyEntity = {
domains: [{ id: 'domain-1', companyId: 'company-1', domain: 'acme.example' }],
};
+function cachedChannel(
+ id: string,
+ overrides: Partial<CachedGraphqlChannel> = {}
+): CachedGraphqlChannel {
+ return {
+ id,
+ name: id,
+ ownerId: 'owner',
+ channelType: 'public',
+ participantIds: [],
+ createdAt: '2026-08-01T00:00:00.000Z',
+ updatedAt: '2026-08-02T00:00:00.000Z',
+ ...overrides,
+ };
+}
+
+function channelHit(channel: CachedGraphqlChannel): SearchDocumentWire {
+ return {
+ profile: 'quick-access-v1',
+ recordKey: `GraphqlSoupChannel:${channel.id}`,
+ bucket: channel.channelType === 'direct_message' ? 'dm' : 'channel',
+ searchText: channel.name,
+ timestampMs: Date.parse(channel.updatedAt),
+ sourceHash: channel.id,
+ };
+}
+
const retainedHistory: HistoryItem[] = [
{
id: 'older-note',
@@ -428,6 +475,124 @@ describe('Quick Access source integration', () => {
}
}
);
+ it('uses only GraphQL channels when the cache is enabled', async () => {
+ const channel = cachedChannel('cached-channel');
+ mocks.cachedChannels = () => [channel];
+ mocks.search.mockResolvedValue({
+ documents: [channelHit(channel)],
+ nextCursor: null,
+ });
+ const lists = setup((source) => [
+ source.useList('channel'),
+ source.useList({ buckets: ['channel'] }),
+ ]);
+ await vi.waitFor(() =>
+ expect(lists.every((list) => !list.isLoading())).toBe(true)
+ );
+ for (const list of lists) {
+ expect(list.items().map((item) => item.id)).toEqual(['cached-channel']);
+ }
+ expect(mocks.channels).not.toHaveBeenCalled();
+ });
+
+ it('loads channels beyond the recent query through cache search', async () => {
+ const channels = Array.from({ length: 75 }, (_, i) =>
+ cachedChannel(`channel-${i}`)
+ );
+ mocks.cachedChannels = () => channels.slice(0, 50);
+ mocks.projectedChannels = channels;
+ mocks.search.mockResolvedValue({
+ documents: channels.map(channelHit),
+ nextCursor: null,
+ });
+ const list = setup((source) => source.useList({ buckets: ['channel'] }));
+ await vi.waitFor(() => expect(list.isLoading()).toBe(false));
+ expect(list.items()).toHaveLength(75);
+ expect(new Set(list.items().map((item) => item.id)).size).toBe(75);
+ expect(list.items().some((item) => item.id === 'channel-74')).toBe(true);
+ expect(mocks.channels).not.toHaveBeenCalled();
+ });
+
+ it('sorts projected and known browse rows together using viewed recency', async () => {
+ const projectedChannel = cachedChannel('older-channel', {
+ viewedAt: '2026-08-01T00:00:00.000Z',
+ updatedAt: '2026-08-04T00:00:00.000Z',
+ });
+ mocks.projectedChannels = [projectedChannel];
+ mocks.history = [
+ {
+ id: 'recent-note',
+ type: 'document',
+ name: 'Recent note',
+ fileType: 'md',
+ ownerId: 'owner',
+ viewedAt: '2026-08-03T00:00:00.000Z',
+ updatedAt: '2026-08-05T00:00:00.000Z',
+ },
+ ];
+ mocks.search.mockResolvedValue({
+ documents: [channelHit(projectedChannel)],
+ nextCursor: null,
+ });
+ const list = setup((source) =>
+ source.useList({ buckets: ['note', 'channel'] })
+ );
+ expect(list.items().map((item) => item.id)).toEqual(['recent-note']);
+ await vi.waitFor(() => expect(list.isLoading()).toBe(false));
+ expect(list.items().map((item) => [item.id, item.sortTimestamp])).toEqual([
+ ['recent-note', Date.parse('2026-08-03T00:00:00.000Z')],
+ ['older-channel', Date.parse('2026-08-01T00:00:00.000Z')],
+ ]);
+ });
+
+ it('keeps equal-recency browse rows in a stable order during hydration', async () => {
+ mocks.cachedChannels = () => [
+ cachedChannel('channel-b'),
+ cachedChannel('channel-a'),
+ ];
+ mocks.search.mockResolvedValue({
+ documents: [channelHit(cachedChannel('channel-b'))],
+ nextCursor: null,
+ });
+ const list = setup((source) => source.useList({ buckets: ['channel'] }));
+ const expected = ['channel-a', 'channel-b'];
+ expect(list.items().map((item) => item.id)).toEqual(expected);
+ await vi.waitFor(() => expect(list.isLoading()).toBe(false));
+ expect(list.items().map((item) => item.id)).toEqual(expected);
+ mocks.search.mockResolvedValue({
+ documents: [channelHit(cachedChannel('channel-a'))],
+ nextCursor: null,
+ });
+ mocks.changed?.();
+ await vi.waitFor(() => expect(list.isLoading()).toBe(false));
+ expect(list.items().map((item) => item.id)).toEqual(expected);
+ });
+
+ it('keeps equal-recency pages in cache record order across entity types', async () => {
+ const channel = cachedChannel('z-channel', {
+ updatedAt: cachedCompany.updatedAt,
+ });
+ mocks.projectedChannels = [channel];
+ mocks.search
+ .mockResolvedValueOnce({
+ documents: [channelHit(channel)],
+ nextCursor: {
+ recordKey: `GraphqlSoupChannel:${channel.id}`,
+ timestampMs: Date.parse(channel.updatedAt),
+ },
+ })
+ .mockResolvedValueOnce({ documents: [companyHit], nextCursor: null });
+ const list = setup((source) =>
+ source.useList({ buckets: ['channel', 'crm_company'] })
+ );
+ await vi.waitFor(() => expect(list.isLoading()).toBe(false));
+ expect(list.items().map((item) => item.id)).toEqual(['z-channel']);
+ await list.loadMore();
+ expect(list.items().map((item) => item.id)).toEqual([
+ 'z-channel',
+ 'company-1',
+ ]);
+ });
it.each(
(['history', 'channels', 'recently-viewed'] as const).flatMap((source) =>
diff --git a/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.tsx b/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.tsx
index 16c2b465fc..dd10bd020f 100644
--- a/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.tsx
+++ b/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.tsx
@@ -191,10 +191,15 @@ function toTimestamp(value: DateValue | null | undefined): number {
return toDate(value).getTime();
}
+function latestDate<T extends DateValue>(
+ a: T | null | undefined,
+ b: T | null | undefined
+): T | undefined {
+ return (toTimestamp(a) > toTimestamp(b) ? a : b) ?? undefined;
+}
+
function channelToQuickAccessItem(
- channel: CachedGraphqlChannel,
- sortTimestamp = toTimestamp(channel.viewedAt) ||
- toTimestamp(channel.updatedAt)
+ channel: CachedGraphqlChannel
): QuickAccessItem {
const bucket: Bucket =
channel.channelType === 'direct_message' ? 'dm' : 'channel';
@@ -203,7 +208,8 @@ function channelToQuickAccessItem(
id: channel.id,
bucket,
searchText: channel.name,
- sortTimestamp,
+ sortTimestamp:
+ toTimestamp(channel.viewedAt) || toTimestamp(channel.updatedAt),
timestamps: {
viewedAt: channel.viewedAt,
updatedAt: channel.updatedAt,
@@ -225,7 +231,10 @@ function equalActivityMaps(
return true;
}
-function getHistoryItemVersion(item: HistoryItem, viewedAt?: string): string {
+function getHistoryItemVersion(
+ item: HistoryItem,
+ viewedAt?: DateValue | null
+): string {
return `${item.name}|${item.updatedAt}|${viewedAt}|${item.deletedAt}`;
}
@@ -273,7 +282,7 @@ function mergeSortedIndices(a: IndexEntry[], b: IndexEntry[]): IndexEntry[] {
let j = 0;
while (i < a.length && j < b.length) {
- if (a[i].sortTimestamp >= b[j].sortTimestamp) {
+ if (compareRecency(a[i], b[j]) <= 0) {
result.push(a[i]);
i++;
} else {
@@ -303,8 +312,36 @@ function mergeMultipleSortedIndices(arrays: IndexEntry[][]): IndexEntry[] {
return arrays.reduce((acc, arr) => mergeSortedIndices(acc, arr));
}
+// Match the cache browse cursor's typename/id tie-break, including document
+// subtypes that share one normalized record type. This keeps later pages from
+// moving ahead of already loaded rows when their timestamps are equal.
+const RECORD_TYPE_BY_BUCKET: Record<Bucket, string> = {
+ channel: 'GraphqlSoupChannel',
+ dm: 'GraphqlSoupChannel',
+ chat: 'GraphqlSoupChat',
+ crm_company: 'GraphqlSoupCrmCompany',
+ document: 'GraphqlSoupDocument',
+ task: 'GraphqlSoupDocument',
+ snippet: 'GraphqlSoupDocument',
+ skill: 'GraphqlSoupDocument',
+ note: 'GraphqlSoupDocument',
+ email: 'GraphqlSoupEmailThread',
+ project: 'GraphqlSoupProject',
+ person: 'GraphqlUser',
+ agent_session: 'AgentSession',
+};
+
+function compareRecency(a: IndexEntry, b: IndexEntry): number {
+ const timestampOrder = b.sortTimestamp - a.sortTimestamp;
+ if (timestampOrder) return timestampOrder;
+ const aType = RECORD_TYPE_BY_BUCKET[a.bucket];
+ const bType = RECORD_TYPE_BY_BUCKET[b.bucket];
+ if (aType !== bType) return aType < bType ? -1 : 1;
+ return a.id === b.id ? 0 : a.id < b.id ? -1 : 1;
+}
+
function sortIndexEntries(entries: IndexEntry[]): IndexEntry[] {
- entries.sort((a, b) => b.sortTimestamp - a.sortTimestamp);
+ entries.sort(compareRecency);
return entries;
}
@@ -393,7 +430,7 @@ export function createQuickAccessValue(): QuickAccessContextValue {
if (hidden.has(item.id)) continue;
seenIds.add(item.id);
- const viewedAt = viewedAtMap.get(item.id);
+ const viewedAt = latestDate(viewedAtMap.get(item.id), item.viewedAt);
const version = getHistoryItemVersion(item, viewedAt);
const cached = itemCache.get(item.id);
@@ -451,9 +488,8 @@ export function createQuickAccessValue(): QuickAccessContextValue {
: []
: channels().map(apiChannelToQuickAccessChannel);
for (const sourceChannel of channelData) {
- const viewedAt = cacheHost
- ? sourceChannel.viewedAt
- : (viewedAtMap.get(sourceChannel.id) ?? sourceChannel.viewedAt);
+ const recentlyViewedAt = viewedAtMap.get(sourceChannel.id);
+ const viewedAt = latestDate(recentlyViewedAt, sourceChannel.viewedAt);
const channel = { ...sourceChannel, viewedAt };
const version = getChannelVersion(channel, viewedAt);
const cached = itemCache.get(channel.id);
@@ -942,15 +978,25 @@ export function createQuickAccessValue(): QuickAccessContextValue {
if (cached) return [cached];
const historyItem = historyById.get(id);
if (historyItem) {
- const entity = historyItemToEntity(historyItem);
+ const viewedAt = latestDate(
+ soupViewedAtMap().get(id),
+ historyItem.viewedAt
+ );
+ const entity = {
+ ...historyItemToEntity(historyItem),
+ viewedAt,
+ };
return [
{
kind: 'entity',
id,
bucket: getBucketForHistoryItem(historyItem),
searchText: getEntitySearchText(entity),
- sortTimestamp: document.timestampMs,
+ sortTimestamp:
+ toTimestamp(viewedAt) ||
+ toTimestamp(historyItem.updatedAt),
timestamps: {
+ viewedAt,
updatedAt: historyItem.updatedAt,
createdAt: historyItem.createdAt,
},
@@ -966,7 +1012,9 @@ export function createQuickAccessValue(): QuickAccessContextValue {
id,
bucket: 'crm_company',
searchText: getCrmCompanySearchText(company),
- sortTimestamp: document.timestampMs,
+ sortTimestamp:
+ toTimestamp(company.viewedAt) ||
+ toTimestamp(company.updatedAt),
timestamps: {
viewedAt: company.viewedAt,
updatedAt: company.updatedAt,
@@ -977,9 +1025,7 @@ export function createQuickAccessValue(): QuickAccessContextValue {
];
}
const channel = channelsById.get(id);
- return channel
- ? [channelToQuickAccessItem(channel, document.timestampMs)]
- : [];
+ return channel ? [channelToQuickAccessItem(channel)] : [];
});
},
})
@@ -989,13 +1035,18 @@ export function createQuickAccessValue(): QuickAccessContextValue {
const local = localItems();
if (!projected || options?.enabled?.() === false) return local;
- // Search describes cached contents, not corpus completeness. Preserve
- // projection rank, then append candidates from the existing local sources.
+ // Search describes cached contents, not corpus completeness. Merge known
+ // rows before sorting recency so hydration cannot promote older items.
const ranked = projected
.items()
.map((item) => itemCache.get(item.id)?.item ?? item);
const seen = new Set(ranked.map((item) => item.id));
- return ranked.concat(local.filter((item) => !seen.has(item.id)));
+ const combined = ranked.concat(
+ local.filter((item) => !seen.has(item.id))
+ );
+ return options?.searchTerm?.().trim()
+ ? combined
+ : combined.sort(compareRecency);
});
return {
items: list,
diff --git a/apps/web/src/lib/core/util/freshSort.test.ts b/apps/web/src/lib/core/util/freshSort.test.ts
index 36c66e0415..5ef1d437b0 100644
--- a/apps/web/src/lib/core/util/freshSort.test.ts
+++ b/apps/web/src/lib/core/util/freshSort.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
import { applyDurationToDate } from './dateSearch/dateParser';
import { createFreshSearch, normalizeFuzzyScore } from './freshSort';
@@ -33,6 +33,34 @@ function createSearch(opts: { useViewedAt?: boolean; channelBoost?: number }) {
}
describe('freshSort ordering', () => {
+ it('scores equal timestamps equally when time advances while scoring candidates', () => {
+ vi.useFakeTimers({ now: new Date('2026-09-26T12:00:00Z') });
+ try {
+ const viewedAt = new Date(Date.now() - 1000);
+ const items: MockItem[] = ['a', 'b', 'c'].map((id) => ({
+ id,
+ name: 'Planning',
+ type: 'item',
+ viewedAt,
+ }));
+ const search = createFreshSearch<MockItem>({
+ config: { useViewedAt: true },
+ getName: (item) => item.name,
+ getTimestamp: (item) => {
+ vi.advanceTimersByTime(1);
+ return { viewedAt: item.viewedAt };
+ },
+ });
+ const scores = search(items, 'Planning').map(
+ (result) => result.combinedScore
+ );
+
+ expect(new Set(scores).size).toBe(1);
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
it('orders by viewedAt - most recent first', () => {
const now = new Date();
const items: MockItem[] = [
diff --git a/apps/web/src/lib/core/util/freshSort.ts b/apps/web/src/lib/core/util/freshSort.ts
index 43451fba07..1ca39072fb 100644
--- a/apps/web/src/lib/core/util/freshSort.ts
+++ b/apps/web/src/lib/core/util/freshSort.ts
@@ -105,11 +105,11 @@ function extractTimestamp(
function calculateTimeScore(
timestamp: DateValue | null,
- config: FreshSortConfigWithDefaults
+ config: FreshSortConfigWithDefaults,
+ now: Date
): number {
if (!timestamp) return 0;
- const now = new Date();
const ageMs = Math.max(0, differenceInMilliseconds(now, timestamp));
const maxAgeMs = parsedDurationToMilliseconds(config.maxAge);
@@ -213,6 +213,7 @@ function freshSort<T>(
? Math.max(...filterNoInfResults.map((r) => r.score))
: 1;
+ const now = new Date();
const scoredResults: FreshSortResult<T>[] = filterResults.map((result) => {
const timestampInfo = getTimestamp(result.original);
const rawScore = result.score === Infinity ? maxFuzzyScore : result.score;
@@ -220,7 +221,8 @@ function freshSort<T>(
maxFuzzyScore === 0 ? 0 : normalizeFuzzyScore(rawScore, maxFuzzyScore);
const timeScore = calculateTimeScore(
extractTimestamp(timestampInfo, finalConfig.useViewedAt),
- finalConfig
+ finalConfig,
+ now
);
const textForBrevity = result.string || '';
diff --git a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
index 3deeb17495..874a4b271b 100644
--- a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
@@ -277,6 +277,9 @@ function makeFakeHost(): FakeHost {
async currentRevision() {
return INITIAL_CACHE_REVISION;
},
+ async currentStorageGeneration() {
+ return '00000000-0000-4000-8000-000000000001';
+ },
async readQuery(args) {
host.reads.push({
opKey: args.opKey,
diff --git a/apps/web/src/lib/graphql-cache/host/noop-host.ts b/apps/web/src/lib/graphql-cache/host/noop-host.ts
index eab2f7ddd8..ff0a047e50 100644
--- a/apps/web/src/lib/graphql-cache/host/noop-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/noop-host.ts
@@ -29,6 +29,9 @@ export function createNoopCacheHost(reason: string): CacheHost {
async currentRevision() {
return INITIAL_CACHE_REVISION;
},
+ async currentStorageGeneration() {
+ throw new Error('normalized GraphQL cache is unavailable');
+ },
async readQuery(): Promise<ReadResult> {
return { kind: 'miss' };
},
diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts
index c7ed61b57a..0f73b0931f 100644
--- a/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts
+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts
@@ -51,6 +51,32 @@ describe('createTauriCacheHost', () => {
});
});
+ it('reads the database generation after native initialization', async () => {
+ const generation = '00000000-0000-4000-8000-000000000001';
+ invokeMock.mockImplementation(async (command: string) =>
+ command === 'graphql_cache_current_storage_generation' ? generation : null
+ );
+ const host = createTauriCacheHost({ scope: 'scope-1' });
+ await expect(host.currentStorageGeneration()).resolves.toBe(generation);
+ expect(invokeMock.mock.calls.map(([command]) => command)).toEqual([
+ 'graphql_cache_init',
+ 'graphql_cache_current_storage_generation',
+ ]);
+ host.dispose();
+ });
+
+ it('reports logical storage resets to generation subscribers', () => {
+ const host = createTauriCacheHost({ scope: 'scope-1' });
+ const changed = vi.fn();
+ host.onCacheGenerationChanged(changed);
+ const notify = eventCallbacks.get('graphql-cache://cache-changed')!;
+ notify({ payload: { revision: INITIAL_CACHE_REVISION } });
+ expect(changed).not.toHaveBeenCalled();
+ notify({ payload: { revision: INITIAL_CACHE_REVISION, reset: true } });
+ expect(changed).toHaveBeenCalledExactlyOnceWith({ storage: 'reset' });
+ host.dispose();
+ });
+
it('initializes the native cache once and prefixes op ids', async () => {
invokeMock.mockImplementation((command: string) =>
Promise.resolve(
diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.ts
index 97a3df0de2..7a2b065a10 100644
--- a/apps/web/src/lib/graphql-cache/host/tauri-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.ts
@@ -33,11 +33,13 @@ import type {
} from '../protocol';
import {
parseCacheRevision,
+ parseStorageGeneration,
validateCacheSearchArgs,
validateRecordSelectionKeys,
} from '../protocol';
import type {
CacheChangeOptions,
+ CacheGenerationChange,
CacheHost,
CacheReadArgs,
CacheWriteArgs,
@@ -62,7 +64,7 @@ type OpsAffectedPayload = {
keys: string[];
};
-type CacheChangedPayload = { revision: string };
+type CacheChangedPayload = { revision: string; reset?: boolean };
// Older native binaries omit the advancement bit and still receive OTA JS.
type NativeHydrationResult = HydrationResult & { revisionAdvanced?: boolean };
@@ -88,6 +90,9 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
const affectedSubscribers = new Set<(opKeys: number[]) => void>();
const cacheChangeSubscribers = new Set<(revision: CacheRevision) => void>();
const hydrationSubscribers = new Set<(revision: CacheRevision) => void>();
+ const generationChangeSubscribers = new Set<
+ (change: CacheGenerationChange) => void
+ >();
const settlementSubscribers = new Set<
(settlement: MutationSettlement) => void
>();
@@ -164,6 +169,9 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
listen<CacheChangedPayload>(CACHE_CHANGED_EVENT, (event) => {
const revision = parseCacheRevision(event.payload.revision);
observeRevision(revision);
+ if (event.payload.reset) {
+ for (const cb of generationChangeSubscribers) cb({ storage: 'reset' });
+ }
for (const cb of cacheChangeSubscribers) cb(revision);
}).catch((error) => {
console.warn('graphql cache change listener failed', error);
@@ -217,6 +225,13 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
);
},
+ async currentStorageGeneration(): Promise<string> {
+ await ready;
+ return parseStorageGeneration(
+ await request<string>('graphql_cache_current_storage_generation', {})
+ );
+ },
+
async readQuery(args: CacheReadArgs): Promise<ReadResult> {
await ready;
return await request<ReadResult>('graphql_cache_read', {
@@ -490,9 +505,11 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
};
},
- onCacheGenerationChanged(): () => void {
- // The native host process owns one engine generation for its lifetime.
- return () => undefined;
+ onCacheGenerationChanged(
+ cb: (change: CacheGenerationChange) => void
+ ): () => void {
+ generationChangeSubscribers.add(cb);
+ return () => generationChangeSubscribers.delete(cb);
},
onMutationSettled(
@@ -506,6 +523,7 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
affectedSubscribers.clear();
cacheChangeSubscribers.clear();
hydrationSubscribers.clear();
+ generationChangeSubscribers.clear();
settlementSubscribers.clear();
void unlistenOps.then((fn) => fn?.());
void unlistenCacheChanges.then((fn) => fn?.());
diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.ts
index aedcf09101..5bfb39f53d 100644
--- a/apps/web/src/lib/graphql-cache/host/types.ts
+++ b/apps/web/src/lib/graphql-cache/host/types.ts
@@ -102,6 +102,9 @@ export interface CacheHost {
/** Returns the current revision of the active cache-engine generation. */
currentRevision(): Promise<CacheRevision>;
+ /** Durable database identity, preserved across engine restarts and replaced
+ * whenever the stored cache is cleared or recreated. */
+ currentStorageGeneration(): Promise<string>;
readQuery(args: CacheReadArgs): Promise<ReadResult>;
/** Projects a bounded explicit set of normalized entity keys. */
readRecordsByKeys(
@@ -177,8 +180,9 @@ export interface CacheHost {
options?: CacheChangeOptions
): () => void;
- /** Invalidates in-memory revisions/dependencies on every engine replacement.
- * Durable checkpoints survive replacements that preserve stored records. */
+ /** Reports engine replacements and live storage resets. Durable checkpoints
+ * must also validate currentStorageGeneration on startup: notifications are
+ * not replayed and may precede a subscriber. */
onCacheGenerationChanged(
cb: (change: CacheGenerationChange) => void
): () => void;
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
index e9265de39e..629bddefcb 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
@@ -30,6 +30,7 @@ import { CacheNavigationError } from './navigation-error';
import { createWorkerCacheHost } from './worker-host';
const CLIENT_ID = '00000000-0000-4000-8000-000000000007';
+const STORAGE_GENERATION = '00000000-0000-7000-8000-000000000001';
const EMPTY_WRITE: WriteResult = {
revision: INITIAL_CACHE_REVISION,
revisionAdvanced: false,
@@ -42,6 +43,8 @@ function responseFor(request: CacheRequest): unknown {
switch (request.kind) {
case 'current-revision':
return INITIAL_CACHE_REVISION;
+ case 'current-storage-generation':
+ return STORAGE_GENERATION;
case 'read':
return { kind: 'miss' };
case 'read-records-by-keys':
@@ -247,6 +250,44 @@ describe('createWorkerCacheHost', () => {
);
});
+ it('reads the durable generation through initialization without requiring a reset notification', async () => {
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+ await expect(host.currentStorageGeneration()).resolves.toBe(
+ STORAGE_GENERATION
+ );
+ expect(requireAdapter().requests.map(({ kind }) => kind)).toEqual([
+ 'init',
+ 'current-storage-generation',
+ ]);
+ host.dispose();
+ });
+
+ it('notifies generation subscribers only when a live cache change resets storage', async () => {
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+ await host.currentStorageGeneration();
+ const changed = vi.fn();
+ const unsubscribe = host.onCacheGenerationChanged(changed);
+ requireAdapter().push({
+ kind: 'cache-changed',
+ revision: INITIAL_CACHE_REVISION,
+ });
+ expect(changed).not.toHaveBeenCalled();
+ requireAdapter().push({
+ kind: 'cache-changed',
+ revision: INITIAL_CACHE_REVISION,
+ reset: true,
+ });
+ expect(changed).toHaveBeenCalledExactlyOnceWith({ storage: 'reset' });
+ unsubscribe();
+ requireAdapter().push({
+ kind: 'cache-changed',
+ revision: INITIAL_CACHE_REVISION,
+ reset: true,
+ });
+ expect(changed).toHaveBeenCalledOnce();
+ host.dispose();
+ });
+
it('uses the no-op host when OPFS is unavailable', () => {
vi.stubGlobal('navigator', {
locks: { request: vi.fn() },
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.ts
index 2c52f40999..9b3f535908 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts
@@ -25,6 +25,7 @@ import {
type MutationClaim,
type MutationSettlement,
OWNER_EPOCH_LOST_ERROR_CODE,
+ parseStorageGeneration,
type ReadRecordsByKeysArgs,
type ReadRecordsByKeysResult,
type ReadResult,
@@ -278,6 +279,10 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
return;
}
if (msg.kind === 'cache-changed') {
+ if (msg.reset) {
+ for (const cb of generationChangeSubscribers)
+ cb({ storage: 'reset' });
+ }
for (const cb of cacheChangeSubscribers) cb(msg.revision);
return;
}
@@ -854,6 +859,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
msg.kind === 'init'
? initializationTimeoutMs
: msg.kind === 'current-revision' ||
+ msg.kind === 'current-storage-generation' ||
msg.kind === 'read' ||
msg.kind === 'read-records-by-keys' ||
msg.kind === 'search' ||
@@ -1070,6 +1076,13 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
})) as CacheRevision;
},
+ async currentStorageGeneration(): Promise<string> {
+ await ensureInitialized();
+ return parseStorageGeneration(
+ await request({ kind: 'current-storage-generation' })
+ );
+ },
+
async readQuery(args: CacheReadArgs): Promise<ReadResult> {
if (args.opKey !== undefined) trackActiveOperation(args.opKey);
return (await initializedRequest(
diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.ts
index 45416885c8..6261e6f3c8 100644
--- a/apps/web/src/lib/graphql-cache/protocol.ts
+++ b/apps/web/src/lib/graphql-cache/protocol.ts
@@ -40,6 +40,19 @@ export function parseCacheRevision(value: unknown): CacheRevision {
export const INITIAL_CACHE_REVISION = '0' as CacheRevision;
+/** Validates the durable database-generation UUID shared by cache hosts. */
+export function parseStorageGeneration(value: unknown): string {
+ if (
+ typeof value !== 'string' ||
+ !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(
+ value
+ )
+ ) {
+ throw new TypeError('invalid cache storage generation');
+ }
+ return value;
+}
+
/** Scheduling hint for latency-sensitive cache reads. */
export type CacheReadPriority = 'user-visible';
@@ -435,6 +448,7 @@ export type MutationSettlement =
export type CacheRequest = { id: number } & (
| { kind: 'init'; scope: string; hotCapacity?: number }
| { kind: 'current-revision' }
+ | { kind: 'current-storage-generation' }
| {
kind: 'read';
opId?: string;
@@ -594,7 +608,7 @@ export type CachePush =
/** Changed entity keys, for diagnostics/advanced consumers. */
keys: string[];
}
- | { kind: 'cache-changed'; revision: CacheRevision }
+ | { kind: 'cache-changed'; revision: CacheRevision; reset?: boolean }
| { kind: 'cache-hydrated'; revision: CacheRevision }
| { kind: 'mutation-settled'; settlement: MutationSettlement };
@@ -670,6 +684,11 @@ export function isCachePush(value: unknown): value is CachePush {
isWireStringArray(value.keys)
);
case 'cache-changed':
+ return (
+ hasOnlyWireKeys(value, ['kind', 'revision', 'reset']) &&
+ isCacheRevision(value.revision) &&
+ (value.reset === undefined || typeof value.reset === 'boolean')
+ );
case 'cache-hydrated':
return (
hasOnlyWireKeys(value, ['kind', 'revision']) &&
diff --git a/apps/web/src/lib/graphql-cache/telemetry.ts b/apps/web/src/lib/graphql-cache/telemetry.ts
index f6cf2f21dc..1edd8436bd 100644
--- a/apps/web/src/lib/graphql-cache/telemetry.ts
+++ b/apps/web/src/lib/graphql-cache/telemetry.ts
@@ -516,7 +516,12 @@ export function operationCategoryForRequest(
() => 'inspection' as const
)
.with('invalidate', 'delete-records', () => 'invalidation' as const)
- .with('teardown', 'clear', () => 'lifecycle' as const)
+ .with(
+ 'teardown',
+ 'clear',
+ 'current-storage-generation',
+ () => 'lifecycle' as const
+ )
.exhaustive();
}
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts
index 7c025e0a44..0afe763de6 100644
--- a/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts
@@ -16,7 +16,7 @@ import {
declare const self: DedicatedWorkerGlobalScope;
-const withVersion = <T extends { coordinatorVersion: 4 }>(
+const withVersion = <T extends { coordinatorVersion: 5 }>(
value: T extends unknown ? Omit<T, 'coordinatorVersion'> : never
): T =>
({
diff --git a/apps/web/src/lib/graphql-cache/worker/cache-coordinator-runtime.test.ts b/apps/web/src/lib/graphql-cache/worker/cache-coordinator-runtime.test.ts
index 435f2cb80d..bd6ff68338 100644
--- a/apps/web/src/lib/graphql-cache/worker/cache-coordinator-runtime.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/cache-coordinator-runtime.test.ts
@@ -44,7 +44,7 @@ class FakeEndpoint extends EventTarget {
}
const message = {
- coordinatorVersion: 4,
+ coordinatorVersion: 5,
kind: 'disconnect-tab',
tabId: 'tab-a',
reason: 'test',
@@ -90,7 +90,7 @@ describe('cache coordinator runtime', () => {
expect(() =>
ports[0]?.postMessage({
- coordinatorVersion: 4,
+ coordinatorVersion: 5,
kind: 'protocol-error',
error: 'test',
} satisfies CoordinatorToTabEnvelope)
diff --git a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts
index c990a4ae1e..7b0f8e2dae 100644
--- a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts
+++ b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts
@@ -84,7 +84,7 @@ export interface CacheEngineRuntimeOptions {
memoryTelemetryIntervalMs?: number;
}
-const withVersion = <T extends { coordinatorVersion: 4 }>(
+const withVersion = <T extends { coordinatorVersion: 5 }>(
value: T extends unknown ? Omit<T, 'coordinatorVersion'> : never
): T =>
({
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts
index 767c8a412d..dc9aa58280 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts
@@ -75,7 +75,7 @@ interface CoordinatorConnection {
const DEFAULT_GRACEFUL_TIMEOUT_MS = 10_000;
-const withVersion = <T extends { coordinatorVersion: 4 }>(
+const withVersion = <T extends { coordinatorVersion: 5 }>(
value: T extends unknown ? Omit<T, 'coordinatorVersion'> : never
): T =>
({
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts
index 0f7832e00a..bac80c4977 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts
@@ -24,6 +24,14 @@ const enginePort = {
} as unknown as MessagePort;
describe('coordinator runtime protocol', () => {
+ it('accepts a durable-generation read without caller parameters', () => {
+ const request = {
+ id: 1,
+ kind: 'current-storage-generation',
+ };
+ expect(isCacheRequest(request)).toBe(true);
+ expect(isCacheRequest({ ...request, unexpected: true })).toBe(false);
+ });
it('validates the staged startup handshake and rejects the old ungated protocol', () => {
const progress = {
...version,
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
index c23b307326..08a108bf00 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
@@ -20,7 +20,7 @@ import {
export { isCachePush, isCacheResponse, isWorkerMessage };
/** Version of the topology envelope and routed cache RPC surface. */
-export const CACHE_COORDINATOR_PROTOCOL_VERSION = 4 as const;
+export const CACHE_COORDINATOR_PROTOCOL_VERSION = 5 as const;
export type EngineStartupPhase = 'loading-assets' | 'opening-database';
export type OwnerEpoch = number;
@@ -40,7 +40,7 @@ export type ActivationFailureCode =
export type TabToCoordinatorEnvelope =
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'register-tab';
scope: string;
tabId: string;
@@ -48,40 +48,40 @@ export type TabToCoordinatorEnvelope =
hotCapacity?: number;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'cache-request';
tabId: string;
request: CacheRequest;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'attach-engine-port';
tabId: string;
ownerEpoch: OwnerEpoch;
enginePort: MessagePort;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'graceful-departure';
tabId: string;
ownerEpoch: OwnerEpoch;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'navigation-departure';
tabId: string;
ownerEpoch: OwnerEpoch;
reason: string;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'engine-lost';
tabId: string;
ownerEpoch: OwnerEpoch;
reason: string;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'disconnect-tab';
tabId: string;
reason: string;
@@ -89,12 +89,12 @@ export type TabToCoordinatorEnvelope =
export type CoordinatorToTabEnvelope =
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'registered';
tabId: string;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'become-owner';
scope: string;
tabId: string;
@@ -104,25 +104,25 @@ export type CoordinatorToTabEnvelope =
hotCapacity?: number;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'cache-message';
message: WorkerMessage;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'terminate-engine';
tabId: string;
ownerEpoch: OwnerEpoch;
reason: string;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'retire-complete';
tabId: string;
ownerEpoch: OwnerEpoch;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'engine-startup';
ownerEpoch: OwnerEpoch;
phase: EngineStartupPhase;
@@ -130,26 +130,26 @@ export type CoordinatorToTabEnvelope =
timeoutMs: number;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'engine-replaced';
ownerEpoch: OwnerEpoch;
/** Whether this engine reopened durable data or created/reset it. */
openOutcome: EngineOpenOutcome;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'protocol-error';
error: string;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'terminal-error';
error: string;
storageUntouched?: true;
};
export type PageToEngineEnvelope = {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'activate-engine';
scope: string;
tabId: string;
@@ -161,24 +161,24 @@ export type PageToEngineEnvelope = {
export type CoordinatorToEngineEnvelope =
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'open-engine';
ownerEpoch: OwnerEpoch;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'engine-request';
ownerEpoch: OwnerEpoch;
routeId: RouteId;
request: CacheRequest;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'drain-engine';
ownerEpoch: OwnerEpoch;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'heartbeat';
ownerEpoch: OwnerEpoch;
heartbeatId: number;
@@ -186,13 +186,13 @@ export type CoordinatorToEngineEnvelope =
export type EngineToCoordinatorEnvelope =
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'engine-assets-ready';
tabId: string;
ownerEpoch: OwnerEpoch;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'engine-ready';
tabId: string;
ownerEpoch: OwnerEpoch;
@@ -202,26 +202,26 @@ export type EngineToCoordinatorEnvelope =
openOutcome: EngineOpenOutcome;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'engine-response';
ownerEpoch: OwnerEpoch;
routeId: RouteId;
response: CacheResponse;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'engine-push';
ownerEpoch: OwnerEpoch;
push: CachePush;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'engine-drained';
tabId: string;
ownerEpoch: OwnerEpoch;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'engine-fatal';
tabId: string;
ownerEpoch: OwnerEpoch;
@@ -229,7 +229,7 @@ export type EngineToCoordinatorEnvelope =
fatalCode: EngineFatalCode;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'activation-failed';
tabId: string;
ownerEpoch: OwnerEpoch;
@@ -237,7 +237,7 @@ export type EngineToCoordinatorEnvelope =
failureCode: ActivationFailureCode;
}
| {
- coordinatorVersion: 4;
+ coordinatorVersion: 5;
kind: 'heartbeat-ack';
ownerEpoch: OwnerEpoch;
heartbeatId: number;
@@ -395,6 +395,7 @@ export function isCacheRequest(value: unknown): value is CacheRequest {
isOptionalPositiveInteger(value.hotCapacity)
);
case 'current-revision':
+ case 'current-storage-generation':
return hasOnlyKeys(value, ['id', 'kind']);
case 'read':
return (
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts
index bb5f59a839..3032126f72 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts
@@ -122,7 +122,7 @@ type WithoutVersion<T> = T extends unknown
? Omit<T, 'coordinatorVersion'>
: never;
-const envelope = <T extends { coordinatorVersion: 4 }>(
+const envelope = <T extends { coordinatorVersion: 5 }>(
value: WithoutVersion<T>
): T =>
({
diff --git a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
index 5e3cf3a2e1..f4c86c70eb 100644
--- a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
+++ b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
@@ -69,6 +69,7 @@ export type CacheEngineHydrationResult = WriteResult & {
export interface CacheEngine {
currentRevision(): Promise<CacheRevision>;
+ currentStorageGeneration(): Promise<string>;
boundIdentity(): Promise<string | null>;
/** Optional for compatibility engines; absence means unavailable. */
queueDiagnostics?(): Promise<CacheQueueDiagnostics>;
diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
index cd67e8435b..1d46812905 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
@@ -16,6 +16,33 @@ describe('CacheWorkerCore', () => {
vi.useRealTimers();
});
+ it('obtains durable generations from the engine on every request', async () => {
+ const before = '00000000-0000-4000-8000-000000000001';
+ const after = '00000000-0000-4000-8000-000000000002';
+ const currentStorageGeneration = vi
+ .fn()
+ .mockResolvedValueOnce(before)
+ .mockResolvedValueOnce(after);
+ loadCacheWasmMock.mockResolvedValue({
+ openCache: vi.fn().mockResolvedValue({ currentStorageGeneration }),
+ });
+ const messages: unknown[] = [];
+ const port = { postMessage: (message: unknown) => messages.push(message) };
+ const core = new CacheWorkerCore();
+ await core.handleRequest(port, { id: 1, kind: 'init', scope: 'scope-1' });
+ await core.handleRequest(port, {
+ id: 2,
+ kind: 'current-storage-generation',
+ });
+ await core.handleRequest(port, {
+ id: 3,
+ kind: 'current-storage-generation',
+ });
+ expect(messages).toContainEqual({ id: 2, ok: true, result: before });
+ expect(messages).toContainEqual({ id: 3, ok: true, result: after });
+ expect(currentStorageGeneration).toHaveBeenCalledTimes(2);
+ });
+
it('dispatches explicit-key projection to the wasm engine', async () => {
const records = [
{
@@ -477,6 +504,63 @@ describe('CacheWorkerCore', () => {
expect(hydrateQuery).toHaveBeenCalledBefore(writeQuery);
});
+ it('checks storage generation after earlier hydration before later foreground reads', async () => {
+ const order: string[] = [];
+ const blocker = Promise.withResolvers<void>();
+ const started = Promise.withResolvers<void>();
+ const generation = '00000000-0000-4000-8000-000000000001';
+ loadCacheWasmMock.mockResolvedValue({
+ openCache: vi.fn().mockResolvedValue({
+ readQuery: async (opId: string) => {
+ order.push(opId);
+ if (opId === 'blocker') {
+ started.resolve();
+ await blocker.promise;
+ }
+ return { kind: 'miss' };
+ },
+ hydrateQuery: async () => {
+ order.push('hydrate');
+ return { changed: [], affectedOps: [], reset: false, data: null };
+ },
+ currentStorageGeneration: async () => {
+ order.push('generation');
+ return generation;
+ },
+ }),
+ });
+ const port = { postMessage: vi.fn() };
+ const core = new CacheWorkerCore();
+ await core.handleRequest(port, { id: 1, kind: 'init', scope: 'scope-1' });
+ const running = core.handleRequest(port, {
+ id: 2,
+ kind: 'read',
+ opId: 'blocker',
+ query: 'query Blocker { blocker }',
+ });
+ await started.promise;
+ const hydration = core.handleRequest(port, {
+ id: 3,
+ kind: 'hydrate',
+ query: 'query Backfill { backfill }',
+ data: { backfill: true },
+ });
+ const proof = core.handleRequest(port, {
+ id: 4,
+ kind: 'current-storage-generation',
+ });
+ const visible = core.handleRequest(port, {
+ id: 5,
+ kind: 'read',
+ opId: 'visible',
+ query: 'query Visible { visible }',
+ priority: 'user-visible',
+ });
+ blocker.resolve();
+ await Promise.all([running, hydration, proof, visible]);
+ expect(order).toEqual(['blocker', 'hydrate', 'generation', 'visible']);
+ });
+
it('coalesces queued affected rereads and runs them ahead of incidental reads', async () => {
const order: string[] = [];
let releaseBlocker!: () => void;
@@ -1461,6 +1545,7 @@ describe('CacheWorkerCore', () => {
expect(port.postMessage).toHaveBeenCalledWith({
kind: 'cache-changed',
revision: INITIAL_CACHE_REVISION,
+ reset: true,
});
expect(port.postMessage).toHaveBeenLastCalledWith({
id: 2,
diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
index db93a21230..cb6b66ef25 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
@@ -18,7 +18,7 @@ import type {
SearchCachePage,
WriteResult,
} from '../protocol';
-import { parseCacheRevision } from '../protocol';
+import { parseCacheRevision, parseStorageGeneration } from '../protocol';
import {
type CacheTelemetryRecorderLike,
classifyCacheError,
@@ -75,6 +75,7 @@ const CACHE_WRITE_PRIORITY = 2;
function isOrderingBarrier(request: CacheRequest): boolean {
return (
request.kind === 'init' ||
+ request.kind === 'current-storage-generation' ||
request.kind === 'teardown' ||
request.kind === 'clear'
);
@@ -428,6 +429,11 @@ export class CacheWorkerCore {
.with({ kind: 'current-revision' }, async () => {
return parseCacheRevision(await this.requireEngine().currentRevision());
})
+ .with({ kind: 'current-storage-generation' }, async () => {
+ return parseStorageGeneration(
+ await this.requireEngine().currentStorageGeneration()
+ );
+ })
.with({ kind: 'read' }, async (request) => {
const engine = this.requireEngine();
const result: ReadResult = await engine.readQuery(
@@ -686,7 +692,7 @@ export class CacheWorkerCore {
.with({ kind: 'clear' }, async () => {
const result: CacheRevisionResult = await this.requireEngine().clear();
const revision = parseCacheRevision(result.revision);
- this.push({ kind: 'cache-changed', revision });
+ this.push({ kind: 'cache-changed', revision, reset: true });
return revision;
})
.exhaustive();
@@ -937,7 +943,11 @@ export class CacheWorkerCore {
});
}
if (cacheChanged && result.revisionAdvanced) {
- this.push({ kind: 'cache-changed', revision: result.revision });
+ this.push({
+ kind: 'cache-changed',
+ revision: result.revision,
+ ...(result.reset ? { reset: true } : {}),
+ });
}
}
diff --git a/apps/web/src/lib/queries/history/graphql.ts b/apps/web/src/lib/queries/history/graphql.ts
index 0cd0dc2979..eccd2c7443 100644
--- a/apps/web/src/lib/queries/history/graphql.ts
+++ b/apps/web/src/lib/queries/history/graphql.ts
@@ -49,17 +49,14 @@ function historyItemFromSearchDocument(
if (separator < 0) return undefined;
const typename = document.recordKey.slice(0, separator);
const id = document.recordKey.slice(separator + 1);
- const date = new Date(document.timestampMs);
- const updatedAt = Number.isNaN(date.getTime())
- ? undefined
- : date.toISOString();
const base = {
id,
name: record.name,
rawName: record.name,
ownerId: record.ownerId,
createdAt: record.createdAt,
- updatedAt,
+ updatedAt: record.updatedAt,
+ viewedAt: record.viewedAt,
deletedAt: null,
};
switch (typename) {
diff --git a/apps/web/src/lib/queries/history/tests/graphql.test.ts b/apps/web/src/lib/queries/history/tests/graphql.test.ts
index 6d8897eb0c..8e8c9abbf1 100644
--- a/apps/web/src/lib/queries/history/tests/graphql.test.ts
+++ b/apps/web/src/lib/queries/history/tests/graphql.test.ts
@@ -74,6 +74,8 @@ describe('cached GraphQL history', () => {
createdAt: isChat
? '2025-01-01T00:00:00.000Z'
: '2024-12-31T00:00:00.000Z',
+ updatedAt: '2025-01-02T00:00:00.000Z',
+ viewedAt: isChat ? null : '2025-01-01T12:00:00.000Z',
...(!isChat && {
subType: isTask
? { __typename: 'GraphqlTaskSubType', isCompleted: true }
@@ -110,6 +112,12 @@ describe('cached GraphQL history', () => {
expect(result[0]).toMatchObject({
ownerId: 'document-owner',
createdAt: '2024-12-31T00:00:00.000Z',
+ updatedAt: '2025-01-02T00:00:00.000Z',
+ viewedAt: '2025-01-01T12:00:00.000Z',
+ });
+ expect(result[1]).toMatchObject({
+ updatedAt: '2025-01-02T00:00:00.000Z',
+ viewedAt: null,
});
expect(result[2]).toMatchObject({
type: 'document',
@@ -125,6 +133,8 @@ describe('cached GraphQL history', () => {
for (const [{ document }] of readRecordsByKeys.mock.calls) {
expect(document).toMatch(/QuickAccessName on GraphqlSoup/);
expect(document).toMatch(/name/);
+ expect(document).toMatch(/updatedAt/);
+ expect(document).toMatch(/viewedAt/);
}
});
diff --git a/apps/web/src/lib/queries/history/types.ts b/apps/web/src/lib/queries/history/types.ts
index 979900e785..2db46172e5 100644
--- a/apps/web/src/lib/queries/history/types.ts
+++ b/apps/web/src/lib/queries/history/types.ts
@@ -4,6 +4,7 @@ import type { Item } from '@service-storage/generated/schemas/item';
type BaseHistoryItem = Pick<Item, 'id' | 'name'> & {
createdAt?: DateValue | null;
updatedAt?: DateValue | null;
+ viewedAt?: DateValue | null;
deletedAt?: DateValue | null;
// TODO: item name without safe name transform
rawName?: string;
diff --git a/apps/web/src/lib/queries/soup/backfill.test.tsx b/apps/web/src/lib/queries/soup/backfill.test.tsx
index d079239260..94910aa8c5 100644
--- a/apps/web/src/lib/queries/soup/backfill.test.tsx
+++ b/apps/web/src/lib/queries/soup/backfill.test.tsx
@@ -8,6 +8,7 @@ import {
loadSoupBackfillCheckpoint,
runSoupBackfill,
runSoupBackfills,
+ type SoupBackfillCheckpoint,
type SoupBackfillParams,
useSoupBackfills,
} from './backfill';
@@ -33,6 +34,7 @@ const cacheGenerationCallbacks = new Set<
(change: CacheGenerationChange) => void
>();
const mockCacheHost = {
+ currentStorageGeneration: vi.fn<() => Promise<string>>(),
onCacheGenerationChanged: vi.fn(
(callback: (change: CacheGenerationChange) => void) => {
cacheGenerationCallbacks.add(callback);
@@ -80,6 +82,24 @@ const lane = (
},
});
+function seedCheckpoint(overrides: Partial<SoupBackfillCheckpoint> = {}) {
+ const checkpoint: SoupBackfillCheckpoint = {
+ userId: 'user-1',
+ storageGeneration: 'storage-1',
+ nextCursor: 'saved-cursor',
+ pagesFetched: 12,
+ completed: false,
+ scanStartedAt: '2026-09-01T00:00:00.000Z',
+ updatedSince: null,
+ completedAt: null,
+ ...overrides,
+ };
+ localStorage.setItem(
+ 'graphql-soup-backfill:v15:user-1:core-entities',
+ JSON.stringify(checkpoint)
+ );
+}
+
function BackfillRunner(props: { userId: string }) {
useSoupBackfills(props.userId);
return null;
@@ -93,6 +113,9 @@ describe('runSoupBackfills', () => {
.mockReturnValue(() => ({ enabled: true, payload: undefined }));
cacheGenerationCallbacks.clear();
mockCacheHost.onCacheGenerationChanged.mockClear();
+ mockCacheHost.currentStorageGeneration
+ .mockReset()
+ .mockResolvedValue('storage-1');
graphqlMocks.getGraphqlSoupCacheHost
.mockReset()
.mockReturnValue(mockCacheHost);
@@ -109,6 +132,162 @@ describe('runSoupBackfills', () => {
vi.restoreAllMocks();
});
+ it.each([
+ { savedGeneration: 'storage-1', resumes: true },
+ { savedGeneration: 'replaced-storage', resumes: false },
+ { savedGeneration: null, resumes: false },
+ { savedGeneration: undefined, resumes: false },
+ ])(
+ 'resumes only checkpoints from the current storage: $savedGeneration',
+ async ({ savedGeneration, resumes }) => {
+ seedCheckpoint({ storageGeneration: savedGeneration });
+ const fetchPage = vi.fn(async (_input: unknown) => ({
+ nextCursor: null,
+ }));
+ // A new host can use intact storage without receiving its open event.
+ const reopenedHost = {
+ currentStorageGeneration: async () => 'storage-1',
+ };
+ await Effect.runPromise(
+ runSoupBackfill(
+ 'user-1',
+ reopenedHost,
+ lane('core-entities', fetchPage)
+ )
+ );
+ expect(fetchPage).toHaveBeenCalledOnce();
+ expect(fetchPage.mock.calls[0]?.[0]).toMatchObject(
+ resumes
+ ? { continuation: { cursor: 'saved-cursor' } }
+ : { initial: { limit: 1 } }
+ );
+ expect(loadSoupBackfillCheckpoint('user-1')).toMatchObject({
+ storageGeneration: 'storage-1',
+ pagesFetched: resumes ? 13 : 1,
+ completed: true,
+ });
+ }
+ );
+
+ it('waits for initial cache storage readiness before admitting a saved cursor', async () => {
+ seedCheckpoint();
+ let resolveGeneration!: (generation: string) => void;
+ const ready = new Promise<string>((resolve) => {
+ resolveGeneration = resolve;
+ });
+ mockCacheHost.currentStorageGeneration.mockReturnValue(ready);
+ const fetchPage = vi.fn(async (_input: unknown) => ({ nextCursor: null }));
+ const running = Effect.runPromise(
+ runSoupBackfill('user-1', mockCacheHost, lane('core-entities', fetchPage))
+ );
+ await vi.waitFor(() =>
+ expect(mockCacheHost.currentStorageGeneration).toHaveBeenCalledOnce()
+ );
+ expect(fetchPage).not.toHaveBeenCalled();
+ expect(loadSoupBackfillCheckpoint('user-1').nextCursor).toBe(
+ 'saved-cursor'
+ );
+
+ resolveGeneration('recreated-storage');
+ await running;
+ expect(fetchPage.mock.calls[0]?.[0]).toMatchObject({
+ initial: { limit: 1 },
+ });
+ expect(loadSoupBackfillCheckpoint('user-1')).toMatchObject({
+ storageGeneration: 'recreated-storage',
+ pagesFetched: 1,
+ completed: true,
+ });
+ });
+
+ it('drops completed watermarks when storage changed before the runner subscribed', async () => {
+ const watermark = '2026-09-01T00:00:00.000Z';
+ seedCheckpoint({
+ storageGeneration: 'replaced-storage',
+ nextCursor: null,
+ completed: true,
+ scanStartedAt: null,
+ updatedSince: watermark,
+ completedAt: watermark,
+ });
+ const fetchPage = vi.fn(async (_input: unknown) => ({ nextCursor: null }));
+ await Effect.runPromise(
+ runSoupBackfill('user-1', mockCacheHost, lane('core-entities', fetchPage))
+ );
+ expect(fetchPage.mock.calls[0]?.[0]).toEqual({
+ initial: { limit: 1, expand: true, sortMethod: 'VIEWED_UPDATED' },
+ });
+ expect(loadSoupBackfillCheckpoint('user-1').pagesFetched).toBe(1);
+ });
+
+ it('restarts after storage changes during hydration without a generation event', async () => {
+ seedCheckpoint();
+ const fetchPage = vi.fn(async (_input: unknown) => {
+ if (fetchPage.mock.calls.length === 1) {
+ mockCacheHost.currentStorageGeneration.mockResolvedValue('storage-2');
+ return { nextCursor: 'obsolete-page-cursor' };
+ }
+ return { nextCursor: null };
+ });
+ const createFetchPage = vi.fn(async () => fetchPage);
+ const onCheckpoint = vi.fn();
+ await Effect.runPromise(
+ runSoupBackfill(
+ 'user-1',
+ mockCacheHost,
+ { ...lane('core-entities', fetchPage), createFetchPage },
+ onCheckpoint
+ )
+ );
+ expect(fetchPage.mock.calls.map(([input]) => input)).toEqual([
+ { continuation: { cursor: 'saved-cursor', expand: true } },
+ { initial: { limit: 1, expand: true, sortMethod: 'VIEWED_UPDATED' } },
+ ]);
+ expect(createFetchPage).toHaveBeenCalledTimes(2);
+ expect(onCheckpoint).toHaveBeenCalledOnce();
+ expect(onCheckpoint).toHaveBeenCalledWith(
+ expect.objectContaining({
+ storageGeneration: 'storage-2',
+ pagesFetched: 1,
+ })
+ );
+ expect(loadSoupBackfillCheckpoint('user-1')).toMatchObject({
+ storageGeneration: 'storage-2',
+ nextCursor: null,
+ completed: true,
+ pagesFetched: 1,
+ });
+ });
+
+ it('restarts before the next page when storage changes between pages', async () => {
+ const fetchPage = vi.fn(async (_input: unknown) => ({
+ nextCursor: fetchPage.mock.calls.length === 1 ? 'saved-page' : null,
+ }));
+ await Effect.runPromise(
+ runSoupBackfill(
+ 'user-1',
+ mockCacheHost,
+ { ...lane('core-entities', fetchPage), pageDelayMs: 0 },
+ (checkpoint) => {
+ if (checkpoint.nextCursor === 'saved-page') {
+ mockCacheHost.currentStorageGeneration.mockResolvedValue(
+ 'storage-2'
+ );
+ }
+ }
+ )
+ );
+ expect(fetchPage).toHaveBeenCalledTimes(2);
+ for (const [input] of fetchPage.mock.calls) {
+ expect(input).toMatchObject({ initial: { limit: 1 } });
+ }
+ expect(loadSoupBackfillCheckpoint('user-1')).toMatchObject({
+ storageGeneration: 'storage-2',
+ completed: true,
+ pagesFetched: 1,
+ });
+ });
+
it('refreshes all Mail metadata instead of using message timestamps for archive/read changes', async () => {
const fetchPage = vi.fn(
async (
@@ -119,8 +298,8 @@ describe('runSoupBackfills', () => {
...lane('email-filter-metadata', fetchPage),
refreshAll: true,
};
- await Effect.runPromise(runSoupBackfill('user-1', params));
- await Effect.runPromise(runSoupBackfill('user-1', params));
+ await Effect.runPromise(runSoupBackfill('user-1', mockCacheHost, params));
+ await Effect.runPromise(runSoupBackfill('user-1', mockCacheHost, params));
expect(fetchPage).toHaveBeenCalledTimes(2);
expect(fetchPage.mock.calls[1]?.[0]).toEqual(fetchPage.mock.calls[0]?.[0]);
});
@@ -143,7 +322,7 @@ describe('runSoupBackfills', () => {
});
const running = Effect.runPromise(
- runSoupBackfills('user-1', [
+ runSoupBackfills('user-1', mockCacheHost, [
lane('first-lane', firstFetch),
lane('second-lane', secondFetch),
])
@@ -179,7 +358,7 @@ describe('runSoupBackfills', () => {
);
await Effect.runPromise(
- runSoupBackfill('user-1', {
+ runSoupBackfill('user-1', mockCacheHost, {
...lane('email-thread-pages', fetchPage),
catchUpAfterInitialPass: true,
})
@@ -261,7 +440,9 @@ describe('runSoupBackfills', () => {
catchUpAfterInitialPass: true,
};
- const fiber = Effect.runFork(runSoupBackfill('user-1', params));
+ const fiber = Effect.runFork(
+ runSoupBackfill('user-1', mockCacheHost, params)
+ );
await catchUpStarted;
expect(
@@ -277,7 +458,7 @@ describe('runSoupBackfills', () => {
await Effect.runPromise(Fiber.interrupt(fiber));
holdCatchUp = false;
- await Effect.runPromise(runSoupBackfill('user-1', params));
+ await Effect.runPromise(runSoupBackfill('user-1', mockCacheHost, params));
expect(fetchPage).toHaveBeenCalledTimes(3);
expect(fetchPage.mock.calls[2]?.[0]).toMatchObject({
@@ -322,7 +503,11 @@ describe('runSoupBackfills', () => {
await expect(
Effect.runPromise(
- runSoupBackfill('user-1', lane('projection-v2', fetchPage))
+ runSoupBackfill(
+ 'user-1',
+ mockCacheHost,
+ lane('projection-v2', fetchPage)
+ )
)
).rejects.toMatchObject({ cause: projectionFailure });
@@ -336,6 +521,26 @@ describe('runSoupBackfills', () => {
);
});
+ it('retries cache readiness failures before fetching a lane', async () => {
+ vi.useFakeTimers();
+ mockCacheHost.currentStorageGeneration.mockRejectedValueOnce(
+ new Error('cache temporarily unavailable')
+ );
+ const fetchPage = vi.fn(async () => ({ nextCursor: null }));
+ const running = Effect.runPromise(
+ runSoupBackfills('user-1', mockCacheHost, [
+ lane('core-entities', fetchPage),
+ ])
+ );
+ await vi.advanceTimersByTimeAsync(1_000);
+ await running;
+ expect(fetchPage).toHaveBeenCalledOnce();
+ expect(loadSoupBackfillCheckpoint('user-1')).toMatchObject({
+ storageGeneration: 'storage-1',
+ completed: true,
+ });
+ });
+
it('continues to later lanes after a lane exhausts its retries', async () => {
vi.useFakeTimers();
const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
@@ -345,7 +550,7 @@ describe('runSoupBackfills', () => {
const laterFetch = vi.fn(async () => ({ nextCursor: null }));
const running = Effect.runPromise(
- runSoupBackfills('user-1', [
+ runSoupBackfills('user-1', mockCacheHost, [
lane('failed-lane', failedFetch),
lane('later-lane', laterFetch),
])
@@ -394,6 +599,22 @@ describe('runSoupBackfills', () => {
rendered.unmount();
});
+ it('does not hydrate through a disabled cache host', async () => {
+ vi.useFakeTimers();
+ graphqlMocks.getGraphqlSoupCacheHost.mockReturnValue({
+ ...mockCacheHost,
+ disabled: true,
+ });
+ const rendered = render(() => <BackfillRunner userId="user-1" />);
+ try {
+ await vi.advanceTimersByTimeAsync(10_000);
+ expect(mockCacheHost.currentStorageGeneration).not.toHaveBeenCalled();
+ expect(graphqlMocks.hydrateGraphqlSoup).not.toHaveBeenCalled();
+ } finally {
+ rendered.unmount();
+ }
+ });
+
it('starts when only the cache host becomes available', async () => {
vi.useFakeTimers();
let cacheHost: typeof mockCacheHost | undefined;
@@ -441,6 +662,7 @@ describe('runSoupBackfills', () => {
'graphql-soup-backfill:v15:user-1:core-entities',
JSON.stringify({
userId: 'user-1',
+ storageGeneration: 'storage-1',
nextCursor: 'stale-cursor',
pagesFetched: 12,
completed: false,
@@ -475,6 +697,9 @@ describe('runSoupBackfills', () => {
continuation: { cursor: 'stale-cursor' },
});
+ if (storage === 'reset') {
+ mockCacheHost.currentStorageGeneration.mockResolvedValue('storage-2');
+ }
for (const callback of cacheGenerationCallbacks) callback({ storage });
await vi.waitFor(() =>
@@ -503,7 +728,7 @@ describe('runSoupBackfills', () => {
);
it.each(['preserved', 'reset'] as const)(
- 'keeps completed watermarks and other lanes only for %s storage',
+ 'resumes completed lane watermarks only for %s storage',
async (storage) => {
const watermark = '2026-09-01T00:00:00.000Z';
for (const checkpointId of ['core-entities', 'email-thread-pages']) {
@@ -511,6 +736,7 @@ describe('runSoupBackfills', () => {
`graphql-soup-backfill:v15:user-1:${checkpointId}`,
JSON.stringify({
userId: 'user-1',
+ storageGeneration: 'storage-1',
nextCursor: null,
pagesFetched: 12,
completed: true,
@@ -530,6 +756,9 @@ describe('runSoupBackfills', () => {
);
const firstInput = graphqlMocks.hydrateGraphqlSoup.mock.calls[0][1];
expect(JSON.stringify(firstInput)).toContain(watermark);
+ if (storage === 'reset') {
+ mockCacheHost.currentStorageGeneration.mockResolvedValue('storage-2');
+ }
for (const callback of cacheGenerationCallbacks) callback({ storage });
await vi.waitFor(() =>
expect(graphqlMocks.hydrateGraphqlSoup).toHaveBeenCalledTimes(2)
@@ -537,23 +766,46 @@ describe('runSoupBackfills', () => {
const nextInput = graphqlMocks.hydrateGraphqlSoup.mock.calls[1][1];
if (storage === 'preserved') {
expect(nextInput).toEqual(firstInput);
- expect(
- loadSoupBackfillCheckpoint('user-1', 'email-thread-pages')
- ).toMatchObject({
- completed: true,
- pagesFetched: 12,
- updatedSince: watermark,
- });
} else {
expect(JSON.stringify(nextInput)).not.toContain(watermark);
- expect(
- loadSoupBackfillCheckpoint('user-1', 'email-thread-pages')
- ).toMatchObject({
- completed: false,
- pagesFetched: 0,
- updatedSince: null,
+ }
+ // Notifications restart the active runner. Other lane checkpoints keep
+ // their generation and are validated when that lane starts.
+ expect(
+ loadSoupBackfillCheckpoint('user-1', 'email-thread-pages')
+ ).toMatchObject({
+ storageGeneration: 'storage-1',
+ completed: true,
+ pagesFetched: 12,
+ updatedSince: watermark,
+ });
+ const fetchEmailPage = vi.fn(async (_input: unknown) => ({
+ nextCursor: null,
+ }));
+ await Effect.runPromise(
+ runSoupBackfill(
+ 'user-1',
+ mockCacheHost,
+ lane('email-thread-pages', fetchEmailPage)
+ )
+ );
+ const emailInput = JSON.stringify(fetchEmailPage.mock.calls[0][0]);
+ if (storage === 'preserved') {
+ expect(emailInput).toContain(watermark);
+ } else {
+ expect(emailInput).not.toContain(watermark);
+ expect(fetchEmailPage.mock.calls[0][0]).toMatchObject({
+ initial: { limit: 1 },
});
}
+ expect(
+ loadSoupBackfillCheckpoint('user-1', 'email-thread-pages')
+ ).toMatchObject({
+ storageGeneration:
+ storage === 'preserved' ? 'storage-1' : 'storage-2',
+ pagesFetched: storage === 'preserved' ? 13 : 1,
+ completed: true,
+ });
} finally {
rendered.unmount();
}
diff --git a/apps/web/src/lib/queries/soup/backfill.ts b/apps/web/src/lib/queries/soup/backfill.ts
index 941711fb4f..aa0bc7762f 100644
--- a/apps/web/src/lib/queries/soup/backfill.ts
+++ b/apps/web/src/lib/queries/soup/backfill.ts
@@ -178,6 +178,8 @@ export const DEFAULT_SOUP_BACKFILL_LANES = [
export type SoupBackfillCheckpoint = {
userId: string;
+ /** Durable cache data generation that owns this cursor and watermark. */
+ storageGeneration: string | null;
nextCursor: string | null;
pagesFetched: number;
completed: boolean;
@@ -191,12 +193,12 @@ export type SoupBackfillCheckpoint = {
type StoredSoupBackfillCheckpoint = Omit<
SoupBackfillCheckpoint,
- 'scanStartedAt' | 'updatedSince' | 'completedAt'
+ 'storageGeneration' | 'scanStartedAt' | 'updatedSince' | 'completedAt'
> &
Partial<
Pick<
SoupBackfillCheckpoint,
- 'scanStartedAt' | 'updatedSince' | 'completedAt'
+ 'storageGeneration' | 'scanStartedAt' | 'updatedSince' | 'completedAt'
>
>;
@@ -204,9 +206,13 @@ function checkpointKey(userId: string, checkpointId: string): string {
return `graphql-soup-backfill:v${BACKFILL_VERSION}:${userId}:${checkpointId}`;
}
-function initialCheckpoint(userId: string): SoupBackfillCheckpoint {
+function initialCheckpoint(
+ userId: string,
+ storageGeneration: string | null = null
+): SoupBackfillCheckpoint {
return {
userId,
+ storageGeneration,
nextCursor: null,
pagesFetched: 0,
completed: false,
@@ -216,7 +222,7 @@ function initialCheckpoint(userId: string): SoupBackfillCheckpoint {
};
}
-function isOptionalTimestamp(value: unknown): boolean {
+function isOptionalString(value: unknown): boolean {
return value === undefined || value === null || typeof value === 'string';
}
@@ -233,9 +239,10 @@ function isCheckpoint(
checkpoint.nextCursor === null) &&
typeof checkpoint.pagesFetched === 'number' &&
typeof checkpoint.completed === 'boolean' &&
- isOptionalTimestamp(checkpoint.scanStartedAt) &&
- isOptionalTimestamp(checkpoint.updatedSince) &&
- isOptionalTimestamp(checkpoint.completedAt)
+ isOptionalString(checkpoint.storageGeneration) &&
+ isOptionalString(checkpoint.scanStartedAt) &&
+ isOptionalString(checkpoint.updatedSince) &&
+ isOptionalString(checkpoint.completedAt)
);
}
@@ -252,6 +259,7 @@ export function loadSoupBackfillCheckpoint(
return {
...parsed,
+ storageGeneration: parsed.storageGeneration ?? null,
scanStartedAt: parsed.scanStartedAt ?? null,
updatedSince: parsed.updatedSince ?? null,
completedAt: parsed.completedAt ?? null,
@@ -278,23 +286,6 @@ function saveSoupBackfillCheckpoint(
}
}
-export function resetSoupBackfillCheckpoint(
- userId: string,
- checkpointId = CORE_SOUP_BACKFILL_LANE.checkpointId
-): void {
- try {
- localStorage.removeItem(checkpointKey(userId, checkpointId));
- } catch {
- // Storage can be unavailable in restricted browser contexts.
- }
-}
-
-function resetDefaultSoupBackfillCheckpoints(userId: string): void {
- for (const lane of DEFAULT_SOUP_BACKFILL_LANES) {
- resetSoupBackfillCheckpoint(userId, lane.checkpointId);
- }
-}
-
type SoupBackfillTelemetryState =
| 'started'
| 'progress'
@@ -375,14 +366,26 @@ export function withUpdatedSince(
};
}
+type SoupBackfillCacheHost = Pick<CacheHost, 'currentStorageGeneration'>;
+
export const runSoupBackfill = Effect.fn('runSoupBackfill')(function* (
userId: string,
+ host: SoupBackfillCacheHost,
params: SoupBackfillParams,
onCheckpoint?: (checkpoint: SoupBackfillCheckpoint) => void
) {
+ // Await storage readiness before reading a cursor. Generation notifications
+ // may predate this runner or belong to another tab, so they cannot prove that
+ // a saved continuation still refers to records in the current database.
+ const storageGeneration = yield* Effect.tryPromise(() =>
+ host.currentStorageGeneration()
+ );
let checkpoint = yield* Effect.sync(() =>
loadSoupBackfillCheckpoint(userId, params.checkpointId)
);
+ if (checkpoint.storageGeneration !== storageGeneration) {
+ checkpoint = initialCheckpoint(userId, storageGeneration);
+ }
if (params.restartOnRun) {
checkpoint = {
...checkpoint,
@@ -392,11 +395,6 @@ export const runSoupBackfill = Effect.fn('runSoupBackfill')(function* (
scanStartedAt: null,
};
}
- // Only a never-completed full scan needs the additional watermark pass. An
- // interrupted catch-up already has updatedSince and resumes normally.
- let catchUpPassPending =
- params.catchUpAfterInitialPass === true && checkpoint.updatedSince === null;
-
const startPass = () => {
checkpoint = {
...checkpoint,
@@ -406,89 +404,110 @@ export const runSoupBackfill = Effect.fn('runSoupBackfill')(function* (
};
saveSoupBackfillCheckpoint(checkpoint, params.checkpointId);
};
+ const restartForGeneration = (generation: string) => {
+ checkpoint = initialCheckpoint(userId, generation);
+ startPass();
+ };
+ const createPageFetcher = () =>
+ params.createFetchPage
+ ? Effect.tryPromise(() => params.createFetchPage!(userId))
+ : Effect.succeed(params.fetchPage ?? fetchSoupPage);
// `completed` marks the end of one pass. Start a fresh pass from its stored
// watermark, while an unfinished checkpoint keeps its cursor.
if (checkpoint.completed || checkpoint.scanStartedAt === null) {
yield* Effect.sync(startPass);
}
-
- const fetchPage = params.createFetchPage
- ? yield* Effect.tryPromise(() => params.createFetchPage!(userId))
- : (params.fetchPage ?? fetchSoupPage);
+ let fetchPage = yield* createPageFetcher();
while (true) {
+ const beforeFetchGeneration = yield* Effect.tryPromise(() =>
+ host.currentStorageGeneration()
+ );
+ if (checkpoint.storageGeneration !== beforeFetchGeneration) {
+ yield* Effect.sync(() => restartForGeneration(beforeFetchGeneration));
+ fetchPage = yield* createPageFetcher();
+ continue;
+ }
const passInput = withUpdatedSince(
params.input,
params.refreshAll ? null : checkpoint.updatedSince
);
+ const input: GraphqlSoupInput = checkpoint.nextCursor
+ ? {
+ continuation: {
+ cursor: checkpoint.nextCursor,
+ expand: passInput.expand,
+ emailView: passInput.emailView,
+ },
+ }
+ : { initial: passInput };
+ // Hydration returns only the cursor projection. Cache-only entity
+ // payloads are persisted without being materialized back into this page.
+ const page = yield* Effect.tryPromise((signal) =>
+ fetchPage(input, { signal })
+ );
+ const afterFetchGeneration = yield* Effect.tryPromise(() =>
+ host.currentStorageGeneration()
+ );
+ if (checkpoint.storageGeneration !== afterFetchGeneration) {
+ // A reset during hydration invalidates the page's continuation even when
+ // its request could not be cancelled. Never save it into the new scan.
+ yield* Effect.sync(() => restartForGeneration(afterFetchGeneration));
+ fetchPage = yield* createPageFetcher();
+ continue;
+ }
- while (true) {
- const input: GraphqlSoupInput = checkpoint.nextCursor
- ? {
- continuation: {
- cursor: checkpoint.nextCursor,
- expand: passInput.expand,
- emailView: passInput.emailView,
- },
- }
- : { initial: passInput };
- // Hydration returns only the cursor projection. Cache-only entity
- // payloads are persisted without being materialized back into this page.
- const page = yield* Effect.tryPromise((signal) =>
- fetchPage(input, { signal })
- );
-
- const passCompleted = page.nextCursor == null;
- const transitionToCatchUp = passCompleted && catchUpPassPending;
- const passCompletedAt = passCompleted ? new Date().toISOString() : null;
- checkpoint = {
- ...checkpoint,
- nextCursor: page.nextCursor ?? null,
- pagesFetched: checkpoint.pagesFetched + 1,
- // Atomically persist the required catch-up as in progress instead of
- // exposing a completed lane between the two passes.
- completed: passCompleted && !transitionToCatchUp,
- ...(passCompleted
- ? transitionToCatchUp
- ? {
- // Filter from the full pass start, while using its completion
- // as the resumable catch-up pass watermark.
- updatedSince:
- checkpoint.scanStartedAt ?? checkpoint.updatedSince,
- completedAt: null,
- scanStartedAt: passCompletedAt,
- }
- : {
- // Use the pass start rather than its completion time so updates
- // made while this pass was running are included next time.
- updatedSince:
- checkpoint.scanStartedAt ?? checkpoint.updatedSince,
- completedAt: passCompletedAt,
- scanStartedAt: null,
- }
- : {}),
- };
- if (transitionToCatchUp) catchUpPassPending = false;
- yield* Effect.sync(() => {
- saveSoupBackfillCheckpoint(checkpoint, params.checkpointId);
- onCheckpoint?.(checkpoint);
- });
-
- if (passCompleted) break;
+ const passCompleted = page.nextCursor == null;
+ // Only a never-completed full scan needs the additional watermark pass. An
+ // interrupted catch-up already has updatedSince and resumes normally.
+ const transitionToCatchUp =
+ passCompleted &&
+ params.catchUpAfterInitialPass === true &&
+ checkpoint.updatedSince === null;
+ const passCompletedAt = passCompleted ? new Date().toISOString() : null;
+ checkpoint = {
+ ...checkpoint,
+ nextCursor: page.nextCursor ?? null,
+ pagesFetched: checkpoint.pagesFetched + 1,
+ // Atomically persist the required catch-up as in progress instead of
+ // exposing a completed lane between the two passes.
+ completed: passCompleted && !transitionToCatchUp,
+ ...(passCompleted
+ ? transitionToCatchUp
+ ? {
+ // Filter from the full pass start, while using its completion
+ // as the resumable catch-up pass watermark.
+ updatedSince: checkpoint.scanStartedAt ?? checkpoint.updatedSince,
+ completedAt: null,
+ scanStartedAt: passCompletedAt,
+ }
+ : {
+ // Use the pass start rather than its completion time so updates
+ // made while this pass was running are included next time.
+ updatedSince: checkpoint.scanStartedAt ?? checkpoint.updatedSince,
+ completedAt: passCompletedAt,
+ scanStartedAt: null,
+ }
+ : {}),
+ };
+ yield* Effect.sync(() => {
+ saveSoupBackfillCheckpoint(checkpoint, params.checkpointId);
+ onCheckpoint?.(checkpoint);
+ });
+ if (checkpoint.completed) return;
+ // The terminal page transitions directly into the narrowed catch-up pass.
+ if (!passCompleted) {
yield* Effect.sleep(params.pageDelayMs ?? PAGE_DELAY_MS);
}
-
- if (checkpoint.completed) return;
- // The only incomplete terminal-page state is the atomic transition above.
- // Continue directly into its narrowed catch-up pass.
}
});
/** Runs each backfill lane to completion before starting the next lane. */
export const runSoupBackfills = Effect.fn('runSoupBackfills')(function* (
userId: string,
+ host: SoupBackfillCacheHost,
lanes: readonly SoupBackfillParams[] = DEFAULT_SOUP_BACKFILL_LANES
) {
yield* Effect.forEach(
@@ -499,18 +518,18 @@ export const runSoupBackfills = Effect.fn('runSoupBackfills')(function* (
const initialCheckpoint = yield* Effect.sync(() =>
loadSoupBackfillCheckpoint(userId, lane.checkpointId)
);
- const initialPagesFetched = initialCheckpoint.pagesFetched;
+ let pagesFetched = 0;
yield* Effect.sync(() =>
recordSoupBackfillTelemetry({
checkpointId: lane.checkpointId,
pagesFetched: 0,
state: 'started',
- totalPagesFetched: initialPagesFetched,
+ totalPagesFetched: initialCheckpoint.pagesFetched,
})
);
- yield* runSoupBackfill(userId, lane, (checkpoint) => {
- const pagesFetched = checkpoint.pagesFetched - initialPagesFetched;
+ yield* runSoupBackfill(userId, host, lane, (checkpoint) => {
+ pagesFetched += 1;
if (
!checkpoint.completed &&
pagesFetched % BACKFILL_PROGRESS_PAGE_INTERVAL === 0
@@ -538,7 +557,7 @@ export const runSoupBackfills = Effect.fn('runSoupBackfills')(function* (
recordSoupBackfillTelemetry({
checkpointId: lane.checkpointId,
durationMs: Date.now() - startedAt,
- pagesFetched: checkpoint.pagesFetched - initialPagesFetched,
+ pagesFetched,
state: 'failed',
totalPagesFetched: checkpoint.pagesFetched,
});
@@ -556,7 +575,7 @@ export const runSoupBackfills = Effect.fn('runSoupBackfills')(function* (
recordSoupBackfillTelemetry({
checkpointId: lane.checkpointId,
durationMs: Date.now() - startedAt,
- pagesFetched: checkpoint.pagesFetched - initialPagesFetched,
+ pagesFetched,
state: 'completed',
totalPagesFetched: checkpoint.pagesFetched,
});
@@ -570,7 +589,7 @@ export const runSoupBackfills = Effect.fn('runSoupBackfills')(function* (
const waitForGraphqlSoupCacheHost = Effect.suspend(() => {
const host = getGraphqlSoupCacheHost();
- return host === undefined
+ return !host || host.disabled
? Effect.fail('cache-host-unavailable' as const)
: Effect.succeed(host);
}).pipe(
@@ -615,18 +634,20 @@ export function useSoupBackfills(userId: string): void {
const host = cacheHost();
if (!host) return;
- const unsubscribe = host.onCacheGenerationChanged(({ storage }) => {
- if (storage === 'reset') resetDefaultSoupBackfillCheckpoints(userId);
+ const unsubscribe = host.onCacheGenerationChanged(() => {
setCacheGeneration((generation) => generation + 1);
});
onCleanup(unsubscribe);
});
createEffect(() => {
- if (!cacheHost()) return;
+ const host = cacheHost();
+ if (!host) return;
cacheGeneration();
- const fiber = Effect.runFork(runSoupBackfills(userId).pipe(Effect.ignore));
+ const fiber = Effect.runFork(
+ runSoupBackfills(userId, host).pipe(Effect.ignore)
+ );
onCleanup(() => {
Effect.runFork(Fiber.interrupt(fiber));
});
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql/generated/graphql.ts b/apps/web/src/lib/service-clients/service-storage/graphql/generated/graphql.ts
index 74e1c94d42..3420cd313c 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql/generated/graphql.ts
+++ b/apps/web/src/lib/service-clients/service-storage/graphql/generated/graphql.ts
@@ -7545,16 +7545,16 @@ export type GraphqlChatHistoryFieldsFragment = { __typename: 'GraphqlSoupChat',
export type GraphqlProjectHistoryFieldsFragment = { __typename: 'GraphqlSoupProject', id: string, ownerId: string, createdAt: string, updatedAt: string, viewedAt: string | null, deletedAt: string | null, projectName: string };
-export type GraphqlDocumentQuickAccessNameFragment = { __typename: 'GraphqlSoupDocument', name: string, fileType: string | null, ownerId: string, createdAt: string, subType:
+export type GraphqlDocumentQuickAccessNameFragment = { __typename: 'GraphqlSoupDocument', name: string, fileType: string | null, ownerId: string, createdAt: string, updatedAt: string, viewedAt: string | null, subType:
| { __typename: 'GraphqlInitiativeDescriptionSubType' }
| { __typename: 'GraphqlSkillSubType' }
| { __typename: 'GraphqlSnippetSubType' }
| { __typename: 'GraphqlTaskSubType', isCompleted: boolean }
| null };
-export type GraphqlChatQuickAccessNameFragment = { __typename: 'GraphqlSoupChat', name: string, ownerId: string, createdAt: string };
+export type GraphqlChatQuickAccessNameFragment = { __typename: 'GraphqlSoupChat', name: string, ownerId: string, createdAt: string, updatedAt: string, viewedAt: string | null };
-export type GraphqlProjectQuickAccessNameFragment = { __typename: 'GraphqlSoupProject', name: string, ownerId: string, createdAt: string };
+export type GraphqlProjectQuickAccessNameFragment = { __typename: 'GraphqlSoupProject', name: string, ownerId: string, createdAt: string, updatedAt: string, viewedAt: string | null };
export type GraphqlChannelQuickAccessFieldsFragment = { __typename: 'GraphqlSoupChannel', name: string | null, channelType: string, ownerId: string, createdAt: string, updatedAt: string, viewedAt: string | null, interactedAt: string | null, participants: Array<{ userId: string }> };
@@ -13098,9 +13098,9 @@ export const FavoriteFieldsFragmentDoc = {"kind":"Document","definitions":[{"kin
export const GraphqlDocumentHistoryFieldsFragmentDoc = {"kind":"Document","definitions":[{"kind":"FragmentDefinition","name":{"kind":"Name","value":"GraphqlDocumentHistoryFields"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupDocument"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","alias":{"kind":"Name","value":"documentName"},"name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"ownerId"}},{"kind":"Field","name":{"kind":"Name","value":"fileType"}},{"kind":"Field","name":{"kind":"Name","value":"createdAt"}},{"kind":"Field","name":{"kind":"Name","value":"updatedAt"}},{"kind":"Field","name":{"kind":"Name","value":"viewedAt"}},{"kind":"Field","name":{"kind":"Name","value":"deletedAt"}},{"kind":"Field","name":{"kind":"Name","value":"subType"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlTaskSubType"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"isCompleted"}}]}}]}}]}}]} as unknown as DocumentNode<GraphqlDocumentHistoryFieldsFragment, unknown>;
export const GraphqlChatHistoryFieldsFragmentDoc = {"kind":"Document","definitions":[{"kind":"FragmentDefinition","name":{"kind":"Name","value":"GraphqlChatHistoryFields"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupChat"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","alias":{"kind":"Name","value":"chatName"},"name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"ownerId"}},{"kind":"Field","name":{"kind":"Name","value":"isPersistent"}},{"kind":"Field","name":{"kind":"Name","value":"createdAt"}},{"kind":"Field","name":{"kind":"Name","value":"updatedAt"}},{"kind":"Field","name":{"kind":"Name","value":"viewedAt"}},{"kind":"Field","name":{"kind":"Name","value":"deletedAt"}}]}}]} as unknown as DocumentNode<GraphqlChatHistoryFieldsFragment, unknown>;
export const GraphqlProjectHistoryFieldsFragmentDoc = {"kind":"Document","definitions":[{"kind":"FragmentDefinition","name":{"kind":"Name","value":"GraphqlProjectHistoryFields"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupProject"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","alias":{"kind":"Name","value":"projectName"},"name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"ownerId"}},{"kind":"Field","name":{"kind":"Name","value":"createdAt"}},{"kind":"Field","name":{"kind":"Name","value":"updatedAt"}},{"kind":"Field","name":{"kind":"Name","value":"viewedAt"}},{"kind":"Field","name":{"kind":"Name","value":"deletedAt"}}]}}]} as unknown as DocumentNode<GraphqlProjectHistoryFieldsFragment, unknown>;
-export const GraphqlDocumentQuickAccessNameFragmentDoc = {"kind":"Document","definitions":[{"kind":"FragmentDefinition","name":{"kind":"Name","value":"GraphqlDocumentQuickAccessName"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupDocument"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"fileType"}},{"kind":"Field","name":{"kind":"Name","value":"ownerId"}},{"kind":"Field","name":{"kind":"Name","value":"createdAt"}},{"kind":"Field","name":{"kind":"Name","value":"subType"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlTaskSubType"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"isCompleted"}}]}}]}}]}}]} as unknown as DocumentNode<GraphqlDocumentQuickAccessNameFragment, unknown>;
-export const GraphqlChatQuickAccessNameFragmentDoc = {"kind":"Document","definitions":[{"kind":"FragmentDefinition","name":{"kind":"Name","value":"GraphqlChatQuickAccessName"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupChat"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"ownerId"}},{"kind":"Field","name":{"kind":"Name","value":"createdAt"}}]}}]} as unknown as DocumentNode<GraphqlChatQuickAccessNameFragment, unknown>;
-export const GraphqlProjectQuickAccessNameFragmentDoc = {"kind":"Document","definitions":[{"kind":"FragmentDefinition","name":{"kind":"Name","value":"GraphqlProjectQuickAccessName"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupProject"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"ownerId"}},{"kind":"Field","name":{"kind":"Name","value":"createdAt"}}]}}]} as unknown as DocumentNode<GraphqlProjectQuickAccessNameFragment, unknown>;
+export const GraphqlDocumentQuickAccessNameFragmentDoc = {"kind":"Document","definitions":[{"kind":"FragmentDefinition","name":{"kind":"Name","value":"GraphqlDocumentQuickAccessName"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupDocument"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"fileType"}},{"kind":"Field","name":{"kind":"Name","value":"ownerId"}},{"kind":"Field","name":{"kind":"Name","value":"createdAt"}},{"kind":"Field","name":{"kind":"Name","value":"updatedAt"}},{"kind":"Field","name":{"kind":"Name","value":"viewedAt"}},{"kind":"Field","name":{"kind":"Name","value":"subType"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlTaskSubType"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"isCompleted"}}]}}]}}]}}]} as unknown as DocumentNode<GraphqlDocumentQuickAccessNameFragment, unknown>;
+export const GraphqlChatQuickAccessNameFragmentDoc = {"kind":"Document","definitions":[{"kind":"FragmentDefinition","name":{"kind":"Name","value":"GraphqlChatQuickAccessName"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupChat"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"ownerId"}},{"kind":"Field","name":{"kind":"Name","value":"createdAt"}},{"kind":"Field","name":{"kind":"Name","value":"updatedAt"}},{"kind":"Field","name":{"kind":"Name","value":"viewedAt"}}]}}]} as unknown as DocumentNode<GraphqlChatQuickAccessNameFragment, unknown>;
+export const GraphqlProjectQuickAccessNameFragmentDoc = {"kind":"Document","definitions":[{"kind":"FragmentDefinition","name":{"kind":"Name","value":"GraphqlProjectQuickAccessName"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupProject"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"ownerId"}},{"kind":"Field","name":{"kind":"Name","value":"createdAt"}},{"kind":"Field","name":{"kind":"Name","value":"updatedAt"}},{"kind":"Field","name":{"kind":"Name","value":"viewedAt"}}]}}]} as unknown as DocumentNode<GraphqlProjectQuickAccessNameFragment, unknown>;
export const GraphqlChannelQuickAccessFieldsFragmentDoc = {"kind":"Document","definitions":[{"kind":"FragmentDefinition","name":{"kind":"Name","value":"GraphqlChannelQuickAccessFields"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupChannel"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"channelType"}},{"kind":"Field","name":{"kind":"Name","value":"ownerId"}},{"kind":"Field","name":{"kind":"Name","value":"createdAt"}},{"kind":"Field","name":{"kind":"Name","value":"updatedAt"}},{"kind":"Field","name":{"kind":"Name","value":"viewedAt"}},{"kind":"Field","name":{"kind":"Name","value":"interactedAt"}},{"kind":"Field","name":{"kind":"Name","value":"participants"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"userId"}}]}}]}}]} as unknown as DocumentNode<GraphqlChannelQuickAccessFieldsFragment, unknown>;
export const ItemPreviewFieldsFragmentDoc = {"kind":"Document","definitions":[{"kind":"FragmentDefinition","name":{"kind":"Name","value":"ItemPreviewFields"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupEntity"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"displayName"}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupDocument"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"documentName"},"name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"fileType"}},{"kind":"Field","name":{"kind":"Name","value":"subType"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlTaskSubType"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"isCompleted"}}]}}]}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupChat"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"chatName"},"name":{"kind":"Name","value":"name"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupProject"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"projectName"},"name":{"kind":"Name","value":"name"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupEmailThread"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"emailName"},"name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"senderEmail"}},{"kind":"Field","name":{"kind":"Name","value":"senderName"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupChannel"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"channelDisplayName"},"name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"channelType"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupCall"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"customName"}},{"kind":"Field","name":{"kind":"Name","value":"channelName"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupCrmCompany"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"companyName"},"name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"domains"}}]}}]}}]} as unknown as DocumentNode<ItemPreviewFieldsFragment, unknown>;
export const ItemPreviewDetailsFieldsFragmentDoc = {"kind":"Document","definitions":[{"kind":"FragmentDefinition","name":{"kind":"Name","value":"ItemPreviewDetailsFields"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupEntity"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"FragmentSpread","name":{"kind":"Name","value":"ItemPreviewFields"}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupDocument"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"properties"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"FragmentSpread","name":{"kind":"Name","value":"SoupPropertyFields"}}]}},{"kind":"Field","name":{"kind":"Name","value":"viewerPermission"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlAccessLevelPermission"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"accessLevel"}}]}}]}}]}}]}},{"kind":"FragmentDefinition","name":{"kind":"Name","value":"ItemPreviewFields"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupEntity"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"displayName"}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupDocument"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"documentName"},"name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"fileType"}},{"kind":"Field","name":{"kind":"Name","value":"subType"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlTaskSubType"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"isCompleted"}}]}}]}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupChat"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"chatName"},"name":{"kind":"Name","value":"name"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupProject"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"projectName"},"name":{"kind":"Name","value":"name"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupEmailThread"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"emailName"},"name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"senderEmail"}},{"kind":"Field","name":{"kind":"Name","value":"senderName"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupChannel"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"channelDisplayName"},"name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"channelType"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupCall"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"customName"}},{"kind":"Field","name":{"kind":"Name","value":"channelName"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupCrmCompany"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"companyName"},"name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"domains"}}]}}]}},{"kind":"FragmentDefinition","name":{"kind":"Name","value":"SoupPropertyFields"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlProperty"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"propertyDefinitionId"}},{"kind":"Field","name":{"kind":"Name","value":"displayName"}},{"kind":"Field","name":{"kind":"Name","value":"dataType"}},{"kind":"Field","name":{"kind":"Name","value":"isMultiSelect"}},{"kind":"Field","name":{"kind":"Name","value":"specificEntityType"}},{"kind":"Field","name":{"kind":"Name","value":"isSystem"}},{"kind":"Field","name":{"kind":"Name","value":"isMetadata"}},{"kind":"Field","name":{"kind":"Name","value":"value"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlBooleanPropertyValue"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"boolValue"},"name":{"kind":"Name","value":"value"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlNumberPropertyValue"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"numberValue"},"name":{"kind":"Name","value":"value"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlStringPropertyValue"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"stringValue"},"name":{"kind":"Name","value":"value"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlDatePropertyValue"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","alias":{"kind":"Name","value":"dateValue"},"name":{"kind":"Name","value":"value"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSelectOptionPropertyValue"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"optionIds"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlEntityReferencePropertyValue"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"references"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"entityId"}},{"kind":"Field","name":{"kind":"Name","value":"entityType"}},{"kind":"Field","name":{"kind":"Name","value":"specificMessageId"}}]}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlLinkPropertyValue"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"urls"}}]}}]}}]}}]} as unknown as DocumentNode<ItemPreviewDetailsFieldsFragment, unknown>;
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql/history.graphql b/apps/web/src/lib/service-clients/service-storage/graphql/history.graphql
index fa6158d353..faba7cab52 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql/history.graphql
+++ b/apps/web/src/lib/service-clients/service-storage/graphql/history.graphql
@@ -45,6 +45,8 @@ fragment GraphqlDocumentQuickAccessName on GraphqlSoupDocument {
fileType
ownerId
createdAt
+ updatedAt
+ viewedAt
subType {
__typename
... on GraphqlTaskSubType {
@@ -58,6 +60,8 @@ fragment GraphqlChatQuickAccessName on GraphqlSoupChat {
name
ownerId
createdAt
+ updatedAt
+ viewedAt
}
fragment GraphqlProjectQuickAccessName on GraphqlSoupProject {
@@ -65,6 +69,8 @@ fragment GraphqlProjectQuickAccessName on GraphqlSoupProject {
name
ownerId
createdAt
+ updatedAt
+ viewedAt
}
fragment GraphqlChannelQuickAccessFields on GraphqlSoupChannel {
diff --git a/apps/web/tauri/graphql_cache_plugin/src/commands.rs b/apps/web/tauri/graphql_cache_plugin/src/commands.rs
index 3b5e64593b..dfcc63418b 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/commands.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/commands.rs
@@ -90,6 +90,14 @@ pub async fn graphql_cache_current_revision(
Ok(engine_handle(&state)?.current_revision().await.to_string())
}
+/// Returns the durable cache generation, initializing it when absent.
+#[tauri::command]
+pub async fn graphql_cache_current_storage_generation(
+ state: State<'_, CacheState>,
+) -> Result<String, String> {
+ engine_handle(&state)?.current_storage_generation().await
+}
+
/// Attempts a cache read; registers `op_id` as active when given.
#[tauri::command]
pub async fn graphql_cache_read(
@@ -183,7 +191,7 @@ pub async fn graphql_cache_write<R: Runtime>(
.await?;
emit_ops_affected(&app, &result.affected_ops, &result.changed);
if result.revision_advanced {
- emit_cache_changed(&app, &result.revision);
+ emit_cache_changed(&app, &result.revision, result.reset);
}
Ok(result)
}
@@ -241,7 +249,11 @@ pub async fn graphql_cache_hydrate<R: Runtime>(
&result.write_result.changed,
);
if result.write_result.revision_advanced {
- emit_cache_changed(&app, &result.write_result.revision);
+ emit_cache_changed(
+ &app,
+ &result.write_result.revision,
+ result.write_result.reset,
+ );
}
}
Ok(match result.data {
@@ -295,7 +307,7 @@ pub async fn graphql_cache_enqueue_optimistic_mutation<R: Runtime>(
.await?;
emit_ops_affected(&app, &result.result.affected_ops, &result.result.changed);
if result.result.revision_advanced {
- emit_cache_changed(&app, &result.result.revision);
+ emit_cache_changed(&app, &result.result.revision, result.result.reset);
}
if let MutationUpsertKindWire::ReplacedPending {
removed_transaction_id,
@@ -396,7 +408,7 @@ pub async fn graphql_cache_defer_optimistic_write<R: Runtime>(
{
emit_ops_affected(&app, &write_result.affected_ops, &write_result.changed);
if write_result.revision_advanced {
- emit_cache_changed(&app, &write_result.revision);
+ emit_cache_changed(&app, &write_result.revision, write_result.reset);
}
emit_mutation_settled(
&app,
@@ -443,7 +455,7 @@ pub async fn graphql_cache_commit_optimistic_write<R: Runtime>(
};
emit_ops_affected(&app, &write_result.affected_ops, &write_result.changed);
if write_result.revision_advanced {
- emit_cache_changed(&app, &write_result.revision);
+ emit_cache_changed(&app, &write_result.revision, write_result.reset);
}
emit_mutation_settled(
&app,
@@ -479,7 +491,7 @@ pub async fn graphql_cache_rollback_optimistic_write<R: Runtime>(
} => {
emit_ops_affected(&app, &write_result.affected_ops, &write_result.changed);
if write_result.revision_advanced {
- emit_cache_changed(&app, &write_result.revision);
+ emit_cache_changed(&app, &write_result.revision, write_result.reset);
}
emit_mutation_settled(
&app,
@@ -495,7 +507,7 @@ pub async fn graphql_cache_rollback_optimistic_write<R: Runtime>(
} => {
emit_ops_affected(&app, &write_result.affected_ops, &write_result.changed);
if write_result.revision_advanced {
- emit_cache_changed(&app, &write_result.revision);
+ emit_cache_changed(&app, &write_result.revision, write_result.reset);
}
emit_mutation_settled(
&app,
@@ -519,7 +531,7 @@ pub async fn graphql_cache_invalidate<R: Runtime>(
) -> Result<AffectedOperationsResultWire, String> {
let affected = engine_handle(&state)?.invalidate(keys.clone()).await?;
emit_ops_affected(&app, &affected.affected_ops, &keys);
- emit_cache_changed(&app, &affected.revision);
+ emit_cache_changed(&app, &affected.revision, false);
Ok(affected)
}
@@ -533,7 +545,7 @@ pub async fn graphql_cache_delete_records<R: Runtime>(
) -> Result<AffectedOperationsResultWire, String> {
let affected = engine_handle(&state)?.delete_records(keys.clone()).await?;
emit_ops_affected(&app, &affected.affected_ops, &keys);
- emit_cache_changed(&app, &affected.revision);
+ emit_cache_changed(&app, &affected.revision, false);
Ok(affected)
}
@@ -553,6 +565,6 @@ pub async fn graphql_cache_clear<R: Runtime>(
state: State<'_, CacheState>,
) -> Result<String, String> {
let revision = engine_handle(&state)?.clear().await?.to_string();
- emit_cache_changed(&app, &revision);
+ emit_cache_changed(&app, &revision, true);
Ok(revision)
}
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine.rs b/apps/web/tauri/graphql_cache_plugin/src/engine.rs
index eb5387fa7a..38e25b8526 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine.rs
@@ -423,6 +423,18 @@ impl EngineHandle {
self.inner.lock().await.engine.current_revision()
}
+ /// Returns the durable cache generation, initializing it when absent.
+ pub async fn current_storage_generation(&self) -> Result<String, String> {
+ self.inner
+ .lock()
+ .await
+ .engine
+ .current_storage_generation()
+ .await
+ .map(|generation| generation.to_string())
+ .map_err(|error| error.to_string())
+ }
+
/// Cache read; registers `op_id` as active when given.
pub async fn read(
&self,
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
index 78c4ce5275..6d2fa7f9c2 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
@@ -41,6 +41,32 @@ fn spawn_handle() -> EngineHandle {
EngineHandle::new(storage, None)
}
+#[test]
+fn storage_generation_survives_native_reopening_and_rotates_after_clear() {
+ let dir = tempfile::tempdir().unwrap();
+ let database = cache_turso::TursoFileDatabase::new(dir.path().join("cache.turso")).unwrap();
+ let handle = EngineHandle::new(database.open_or_reset("scope-1").unwrap(), None);
+ let first = block_on(handle.current_storage_generation()).unwrap();
+ assert_eq!(
+ block_on(handle.clone().current_storage_generation()).unwrap(),
+ first
+ );
+ handle.shutdown().unwrap();
+ let handle = EngineHandle::new(database.open_or_reset("scope-1").unwrap(), None);
+ assert_eq!(
+ block_on(handle.current_storage_generation()).unwrap(),
+ first
+ );
+ block_on(handle.clear()).unwrap();
+ let replacement = block_on(handle.current_storage_generation()).unwrap();
+ assert_ne!(replacement, first);
+ assert_eq!(
+ block_on(handle.current_storage_generation()).unwrap(),
+ replacement
+ );
+ handle.shutdown().unwrap();
+}
+
fn write(
handle: &EngineHandle,
origin: Option<&str>,
diff --git a/apps/web/tauri/graphql_cache_plugin/src/lib.rs b/apps/web/tauri/graphql_cache_plugin/src/lib.rs
index 172340609e..472ec23457 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/lib.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/lib.rs
@@ -59,6 +59,9 @@ pub struct OpsAffectedEvent {
pub struct CacheChangedEvent {
/// Effective-view revision installed by the logical mutation.
pub revision: String,
+ /// Present when the write cleared durable records and hydration must restart.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub reset: Option<bool>,
}
#[derive(Clone, Debug, Serialize)]
@@ -109,11 +112,12 @@ fn emit_ops_affected<R: Runtime>(app: &AppHandle<R>, op_ids: &[String], keys: &[
.ok();
}
-fn emit_cache_changed<R: Runtime>(app: &AppHandle<R>, revision: &str) {
+fn emit_cache_changed<R: Runtime>(app: &AppHandle<R>, revision: &str, reset: bool) {
app.emit(
CACHE_CHANGED_EVENT,
CacheChangedEvent {
revision: revision.to_owned(),
+ reset: reset.then_some(true),
},
)
.inspect_err(|e| tracing::error!(error=?e, "failed to emit graphql cache change event"))
diff --git a/apps/web/tauri/src-tauri/README.md b/apps/web/tauri/src-tauri/README.md
index f47e9442c0..6183b645ed 100644
--- a/apps/web/tauri/src-tauri/README.md
+++ b/apps/web/tauri/src-tauri/README.md
@@ -104,6 +104,12 @@ The `beforeBuildCommand` is `just build-tauri`, which runs `bun run build` and
emits the frontend into `dist`. Tauri then packages that output
according to `tauri.conf.json`.
+GraphQL hydration checkpoints require the native
+`graphql_cache_current_storage_generation` command. When shipping this frontend
+through the bundle updater, set `MIN_NATIVE_BUILD` to the first native build that
+includes that command. Older binaries must receive a native update before this
+bundle; they cannot validate a saved hydration cursor against the cache database.
+
## Automated offline tests (Linux)
See [native E2E](../../tests/native/README.md) for the isolated WebDriver setup,
diff --git a/apps/web/tauri/src-tauri/src/lib.rs b/apps/web/tauri/src-tauri/src/lib.rs
index 3336d07a3e..f61e1ceec0 100644
--- a/apps/web/tauri/src-tauri/src/lib.rs
+++ b/apps/web/tauri/src-tauri/src/lib.rs
@@ -251,6 +251,7 @@ pub fn run() {
.invoke_handler(tauri::generate_handler![
graphql_cache_plugin::commands::graphql_cache_init,
graphql_cache_plugin::commands::graphql_cache_current_revision,
+ graphql_cache_plugin::commands::graphql_cache_current_storage_generation,
graphql_cache_plugin::commands::graphql_cache_read,
graphql_cache_plugin::commands::graphql_cache_read_records_by_keys,
graphql_cache_plugin::commands::graphql_cache_search,
diff --git a/crates/client/README.md b/crates/client/README.md
index 0b8dc0ac58..2ab6eadd59 100644
--- a/crates/client/README.md
+++ b/crates/client/README.md
@@ -39,6 +39,15 @@ make retries incorrectly look unchanged. With no optimistic layers, the changed
record keys also identify visible changes without duplicate before/after snapshots.
Pending layers still use full effective-view comparison and rebasing.
+Soup hydration checkpoints carry the cache's durable storage-generation UUID.
+The engine stores this marker alongside normalized records, so clearing or
+replacing the database invalidates its cursors and update watermarks even when
+localStorage survives. Backfill waits for the current generation before resuming
+and checks it again after each hydrated page. A mismatch starts a full scan;
+ordinary engine handoff preserves the marker and continues the saved scan.
+Reset notifications restart active backfills promptly, but checkpoint validity
+does not depend on observing a notification.
+
## Browser OPFS writes
The OPFS adapter coalesces each Turso vectored write into batches of at most
@@ -54,6 +63,13 @@ states that differ from stored state. An updated normalized record does not forc
unchanged index facts to be deleted and reinserted. Pending optimistic projections
are still rebased for every affected key, even when authority is unchanged.
+Quick Access browse timestamps prefer `viewedAt`, then `updatedAt`, for Soup
+documents, chats, projects, channels, and CRM companies. This matches their
+frontend and server ordering before pagination. A versioned derived-search
+projection rebuild upgrades existing indexes once on open, preserving normalized
+records, storage generation, and queued mutations. Routine opens with the current
+projection version do not scan the corpus.
+
## Local filter execution
Local SQL materializes Boolean result sets once, but enumerates a universe only
diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rs
index 9aca1f567f..1b2cadc86d 100644
--- a/crates/client/cache-core/src/engine.rs
+++ b/crates/client/cache-core/src/engine.rs
@@ -275,6 +275,8 @@ struct BegunOptimisticWrite {
/// contain `:`).
const IDENTITY_META_KEY: &str = "__meta:identity";
const IDENTITY_VALUE_FIELD: &str = "identity";
+const STORAGE_GENERATION_META_KEY: &str = "__meta:storage-generation";
+const STORAGE_GENERATION_VALUE_FIELD: &str = "generation";
/// Hydration/binding state of the session identity tag for this cache.
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -331,6 +333,42 @@ impl<S: Storage> Engine<S> {
self.revision
}
+ /// Returns the durable identity of the currently stored cache data.
+ ///
+ /// A fresh generation is installed when the marker is absent or malformed.
+ /// Existing records are preserved when upgrading a cache without this marker.
+ /// Logical clears, identity changes, and physical resets
+ /// remove the marker with the data, so old hydration checkpoints cannot resume.
+ /// Read storage each time: engine replacement and external resets must not
+ /// leave an in-memory generation that outlives its records.
+ pub async fn current_storage_generation(&mut self) -> Result<Uuid, EngineError<S::Error>> {
+ let key = EntityKey(STORAGE_GENERATION_META_KEY.into());
+ let fetched = self
+ .storage
+ .get_batch(std::slice::from_ref(&key))
+ .await
+ .map_err(EngineError::Storage)?;
+ if let Some(record) = fetched.into_iter().next().flatten()
+ && let Some(crate::value::CacheValue::String(value)) =
+ record.fields.get(STORAGE_GENERATION_VALUE_FIELD)
+ && let Ok(generation) = Uuid::parse_str(value)
+ {
+ return Ok(generation);
+ }
+
+ let generation = Uuid::now_v7();
+ let mut record = Record::default();
+ record.fields.insert(
+ STORAGE_GENERATION_VALUE_FIELD.to_string(),
+ crate::value::CacheValue::String(generation.to_string()),
+ );
+ self.storage
+ .put_batch(vec![(key, record)])
+ .await
+ .map_err(EngineError::Storage)?;
+ Ok(generation)
+ }
+
fn ensure_revision_can_advance(&self) -> Result<(), EngineError<S::Error>> {
self.revision
.checked_successor()
diff --git a/crates/client/cache-core/src/engine/test.rs b/crates/client/cache-core/src/engine/test.rs
index 1b2b8a20e1..36eb6c14d5 100644
--- a/crates/client/cache-core/src/engine/test.rs
+++ b/crates/client/cache-core/src/engine/test.rs
@@ -1,6 +1,105 @@
use super::*;
use crate::store::InMemoryStorage;
+#[test]
+fn storage_generation_survives_reopening_and_preserves_existing_records() {
+ pollster::block_on(async {
+ let query = "query Viewer { user { id } }";
+ let data = serde_json::json!({"user": {"id": "viewer"}});
+ let variables = serde_json::Map::new();
+ let mut original = Engine::new(InMemoryStorage::new());
+ original
+ .write_query(None, query, None, &variables, &data, None)
+ .await
+ .unwrap();
+ let revision = original.current_revision();
+ let first = original.current_storage_generation().await.unwrap();
+ assert_eq!(first.get_version_num(), 7);
+ assert_eq!(original.current_revision(), revision);
+ assert_eq!(original.current_storage_generation().await.unwrap(), first);
+
+ let mut reopened = Engine::new(original.into_storage());
+ assert_eq!(reopened.current_storage_generation().await.unwrap(), first);
+ assert!(matches!(
+ reopened.read_query(None, query, None, &variables).await.unwrap(),
+ ReadResult::Hit { data: read } if read == data
+ ));
+ });
+}
+
+#[test]
+fn storage_generation_changes_after_logical_clear_and_identity_rebinding() {
+ pollster::block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ let first = engine.current_storage_generation().await.unwrap();
+ engine.clear().await.unwrap();
+ let after_clear = engine.current_storage_generation().await.unwrap();
+ assert_ne!(after_clear, first);
+
+ let query = "query Viewer { user { id } }";
+ let variables = serde_json::Map::new();
+ engine
+ .write_query(
+ None,
+ query,
+ None,
+ &variables,
+ &serde_json::json!({"user": {"id": "one"}}),
+ Some("one"),
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ engine.current_storage_generation().await.unwrap(),
+ after_clear
+ );
+ let write = engine
+ .write_query(
+ None,
+ query,
+ None,
+ &variables,
+ &serde_json::json!({"user": {"id": "two"}}),
+ Some("two"),
+ )
+ .await
+ .unwrap();
+ assert!(write.reset);
+ let after_identity_change = engine.current_storage_generation().await.unwrap();
+ assert_ne!(after_identity_change, after_clear);
+ assert_ne!(after_identity_change, first);
+ });
+}
+
+#[test]
+fn storage_generation_reads_external_clears_and_repairs_invalid_markers() {
+ pollster::block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ let first = engine.current_storage_generation().await.unwrap();
+ // Storage is authoritative even when this engine receives no reset notification.
+ engine.storage.clear().await.unwrap();
+ let replacement = engine.current_storage_generation().await.unwrap();
+ assert_ne!(replacement, first);
+
+ let mut malformed = Record::default();
+ malformed.fields.insert(
+ STORAGE_GENERATION_VALUE_FIELD.to_string(),
+ crate::value::CacheValue::String("invalid-generation".to_string()),
+ );
+ engine
+ .storage
+ .put_batch(vec![(
+ EntityKey(STORAGE_GENERATION_META_KEY.into()),
+ malformed,
+ )])
+ .await
+ .unwrap();
+ let repaired = engine.current_storage_generation().await.unwrap();
+ assert_ne!(repaired, replacement);
+ assert_eq!(engine.current_storage_generation().await.unwrap(), repaired);
+ });
+}
+
#[test]
fn ordinary_network_refresh_loads_each_cold_batch_only_once() {
pollster::block_on(async {
diff --git a/crates/client/cache-core/src/search.rs b/crates/client/cache-core/src/search.rs
index 80afcac9fc..6b4c3e2fe0 100644
--- a/crates/client/cache-core/src/search.rs
+++ b/crates/client/cache-core/src/search.rs
@@ -72,7 +72,7 @@ pub struct SearchDocument {
pub bucket: String,
/// Lower-cased, whitespace-normalized text used by fuzzy matching.
pub search_text: String,
- /// Best available viewed/interacted/updated/created timestamp.
+ /// Viewed-first recency for Soup entities; activity recency for other rows.
pub timestamp_ms: i64,
/// Compact hash of the fully merged source record.
pub source_hash: String,
@@ -122,6 +122,23 @@ pub enum SearchError {
QueryTooLong,
}
+/// Revision of the derived Quick Access rows. Storage adapters rebuild existing
+/// rows when this changes; normalized records and pending writes remain valid.
+pub const QUICK_ACCESS_PROJECTION_VERSION: u32 = 2;
+
+/// Normalized entity types used by the Quick Access projection. Storage rebuilds
+/// restrict decoding to this set so unrelated payloads do not delay readiness.
+pub const QUICK_ACCESS_TYPENAMES: &[&str] = &[
+ "GraphqlSoupDocument",
+ "GraphqlSoupChat",
+ "GraphqlSoupProject",
+ "GraphqlSoupEmailThread",
+ "GraphqlSoupChannel",
+ "GraphqlSoupCrmCompany",
+ "GraphqlUser",
+ "User",
+];
+
/// Maximum number of compact documents returned by one RPC.
pub const MAX_SEARCH_LIMIT: usize = 500;
/// Maximum accepted query length in bytes.
@@ -205,7 +222,7 @@ fn project_quick_access(key: &EntityKey<'static>, record: &Record) -> Option<Sea
record_key: key.clone(),
bucket: bucket.to_owned(),
search_text,
- timestamp_ms: best_timestamp(record),
+ timestamp_ms: quick_access_timestamp(typename, record),
source_hash: source_hash(record),
})
}
@@ -279,7 +296,24 @@ fn normalize_search_text(value: &str) -> String {
.to_lowercase()
}
-fn best_timestamp(record: &Record) -> i64 {
+fn quick_access_timestamp(typename: &str, record: &Record) -> i64 {
+ // Match VIEWED_UPDATED and the menu before applying a browse limit. Using
+ // max(viewedAt, updatedAt) would let newly updated, long-unopened records
+ // displace recently viewed records into later pages.
+ if matches!(
+ typename,
+ "GraphqlSoupDocument"
+ | "GraphqlSoupChat"
+ | "GraphqlSoupProject"
+ | "GraphqlSoupChannel"
+ | "GraphqlSoupCrmCompany"
+ ) {
+ return ["viewedAt", "updatedAt", "createdAt"]
+ .into_iter()
+ .find_map(|field| record.fields.get(field).and_then(value_timestamp))
+ .unwrap_or(0);
+ }
+
[
"viewedAt",
"interactedAt",
diff --git a/crates/client/cache-core/src/search/test.rs b/crates/client/cache-core/src/search/test.rs
index 381706f463..fc03e5bd29 100644
--- a/crates/client/cache-core/src/search/test.rs
+++ b/crates/client/cache-core/src/search/test.rs
@@ -81,3 +81,39 @@ fn fuzzy_matching_rewards_prefix_and_freshness() {
assert!(fuzzy_freshness_score(&recent, "qtr plan", 1_000).is_some());
assert!(fuzzy_freshness_score(&recent, "missing", 1_000).is_none());
}
+
+#[test]
+fn soup_entity_recency_prefers_viewed_at_over_newer_activity() {
+ for typename in [
+ "GraphqlSoupDocument",
+ "GraphqlSoupChat",
+ "GraphqlSoupProject",
+ "GraphqlSoupChannel",
+ "GraphqlSoupCrmCompany",
+ ] {
+ let mut record = string_record(&[
+ ("__typename", typename),
+ ("name", "Viewed entity"),
+ ("viewedAt", "2025-01-01T00:00:00Z"),
+ ("updatedAt", "2025-01-03T00:00:00Z"),
+ ("interactedAt", "2025-01-04T00:00:00Z"),
+ ("createdAt", "2024-12-01T00:00:00Z"),
+ ]);
+ let key = EntityKey::entity(typename, &["entity"]);
+ assert_eq!(
+ project_search_documents(&key, &record)[0].timestamp_ms,
+ parse_rfc3339_millis("2025-01-01T00:00:00Z").unwrap(),
+ "{typename} must retain viewed-first ordering"
+ );
+ record.fields.insert("viewedAt".into(), CacheValue::Null);
+ assert_eq!(
+ project_search_documents(&key, &record)[0].timestamp_ms,
+ parse_rfc3339_millis("2025-01-03T00:00:00Z").unwrap()
+ );
+ record.fields.remove("updatedAt");
+ assert_eq!(
+ project_search_documents(&key, &record)[0].timestamp_ms,
+ parse_rfc3339_millis("2024-12-01T00:00:00Z").unwrap()
+ );
+ }
+}
diff --git a/crates/client/cache-turso/src/storage.rs b/crates/client/cache-turso/src/storage.rs
index 7771e0abbd..c63732c848 100644
--- a/crates/client/cache-turso/src/storage.rs
+++ b/crates/client/cache-turso/src/storage.rs
@@ -18,7 +18,10 @@ use cache_core::queue::{
MutationRequest, MutationUpsertKind, MutationUpsertResult, NewQueuedMutation,
PersistedOptimisticLayer, QueuedMutation, StoredMutation,
};
-use cache_core::search::{SearchCursor, SearchDocument, SearchProfile, project_search_documents};
+use cache_core::search::{
+ QUICK_ACCESS_PROJECTION_VERSION, QUICK_ACCESS_TYPENAMES, SearchCursor, SearchDocument,
+ SearchProfile, project_search_documents,
+};
use cache_core::store::{QueueDiagnostics, QueueDiagnosticsAvailability, Storage};
use cache_core::value::{EntityKey, Record};
use predicate_index::{
@@ -53,6 +56,13 @@ use turso_opfs::{
/// Frozen storage schema version, independent of cache postcard versions.
pub const STORAGE_SCHEMA_VERSION: u32 = 11;
+const QUICK_ACCESS_PROJECTION_VERSION_KEY: &str = "quick_access_projection_version";
+const SEARCH_REBUILD_BATCH_SIZE: i64 = 256;
+const SEARCH_REBUILD_RECORDS: &str =
+ "SELECT id, value FROM records WHERE __typename = ?1 ORDER BY id LIMIT ?2";
+const SEARCH_REBUILD_RECORDS_AFTER: &str =
+ "SELECT id, value FROM records WHERE __typename = ?1 AND id > ?2 ORDER BY id LIMIT ?3";
+
/// Coarse outcome of validating a Turso database.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum TursoStorageOpenOutcome {
@@ -2863,6 +2873,7 @@ fn initialize(
"INSERT INTO meta (key, value) VALUES ('storage_schema_version', ?1)",
vec![text(&STORAGE_SCHEMA_VERSION.to_string())],
)?;
+ save_search_projection_version(connection)?;
Ok(())
})
.map_err(TursoStorageError::initialization)?;
@@ -2871,8 +2882,8 @@ fn initialize(
return Ok(());
}
- // Reopening must not scan every cached record/page. Keep compatibility and
- // pending-write validation here; full scans belong to explicit diagnostics.
+ // Ordinary reopen only validates compatibility and pending writes. A changed
+ // derived projection performs one bounded rebuild before serving queries.
validate_frozen_schema(connection)?;
let metadata = driver::query(
connection,
@@ -2934,7 +2945,85 @@ fn initialize(
driver::validate(connection, sql).map_err(TursoStorageError::initialization)?;
}
validate_queue_consistency(connection)?;
- validate_optimistic_shadow_consistency(connection)
+ validate_optimistic_shadow_consistency(connection)?;
+ ensure_search_projection_version(connection)
+}
+
+fn save_search_projection_version(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {
+ driver::execute(
+ connection,
+ "INSERT INTO meta (key, value) VALUES (?1, ?2) ON CONFLICT (key) DO UPDATE SET value = excluded.value",
+ vec![
+ text(QUICK_ACCESS_PROJECTION_VERSION_KEY),
+ text(&QUICK_ACCESS_PROJECTION_VERSION.to_string()),
+ ],
+ )?;
+ Ok(())
+}
+
+fn ensure_search_projection_version(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {
+ let versions = driver::query(
+ connection,
+ "SELECT value FROM meta WHERE key = ?1",
+ vec![text(QUICK_ACCESS_PROJECTION_VERSION_KEY)],
+ )?;
+ if let [row] = versions.as_slice()
+ && required_text(row, 0)? == QUICK_ACCESS_PROJECTION_VERSION.to_string()
+ {
+ return Ok(());
+ }
+
+ // Regenerate disposable search rows atomically without replacing normalized
+ // records, the data generation marker, or pending optimistic mutations.
+ driver::write_transaction(connection, || {
+ driver::execute(
+ connection,
+ "DELETE FROM search_documents WHERE profile = ?1",
+ vec![text(SearchProfile::QuickAccessV1.as_str())],
+ )?;
+ for typename in QUICK_ACCESS_TYPENAMES {
+ let mut last_id: Option<String> = None;
+ loop {
+ let (sql, parameters) = match last_id.as_ref() {
+ Some(id) => (
+ SEARCH_REBUILD_RECORDS_AFTER,
+ vec![
+ text(typename),
+ text(id),
+ Value::from_i64(SEARCH_REBUILD_BATCH_SIZE),
+ ],
+ ),
+ None => (
+ SEARCH_REBUILD_RECORDS,
+ vec![text(typename), Value::from_i64(SEARCH_REBUILD_BATCH_SIZE)],
+ ),
+ };
+ let rows = driver::query(connection, sql, parameters)?;
+ if rows.is_empty() {
+ break;
+ }
+ let mut projected = Vec::new();
+ for row in rows {
+ let key = RecordKey {
+ typename: (*typename).to_owned(),
+ id: required_text(&row, 0)?,
+ };
+ let record = decode_record(&required_blob(&row, 1)?)
+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::Codec))?;
+ for document in project_search_documents(&key.clone().into_entity()?, &record) {
+ projected.push((key.clone(), document));
+ }
+ last_id = Some(key.id);
+ }
+ let documents = projected
+ .iter()
+ .map(|(key, document)| (key, document))
+ .collect::<Vec<_>>();
+ upsert_search_documents_batch(connection, &documents)?;
+ }
+ }
+ save_search_projection_version(connection)
+ })
}
fn enable_foreign_keys(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {
diff --git a/crates/client/cache-turso/src/storage/test.rs b/crates/client/cache-turso/src/storage/test.rs
index 9f0cbcb9d6..4f214184e7 100644
--- a/crates/client/cache-turso/src/storage/test.rs
+++ b/crates/client/cache-turso/src/storage/test.rs
@@ -8,6 +8,7 @@ mod filter_scope_cost;
mod filter_scope_semantics;
mod predicate_cost;
mod projection_writes;
+mod search_projection;
mod startup;
use cache_core::normalize::RecordUpdates;
use pollster::block_on;
@@ -487,7 +488,7 @@ fn fresh_schema_metadata_foreign_keys_quick_check_and_cascade_are_real() {
let mut storage = TursoStorage::open_in_memory("schema-scope").unwrap();
assert_eq!(raw_scalar(&storage, "PRAGMA foreign_keys"), 1);
storage.check_integrity().unwrap();
- assert_eq!(raw_scalar(&storage, "SELECT COUNT(*) FROM meta"), 3);
+ assert_eq!(raw_scalar(&storage, "SELECT COUNT(*) FROM meta"), 4);
let violation = driver::execute(
&storage.connection(),
diff --git a/crates/client/cache-turso/src/storage/test/search_projection.rs b/crates/client/cache-turso/src/storage/test/search_projection.rs
new file mode 100644
index 0000000000..4f95899482
--- /dev/null
+++ b/crates/client/cache-turso/src/storage/test/search_projection.rs
@@ -0,0 +1,260 @@
+use super::*;
+use cache_core::engine::Engine;
+use cache_core::search::{SearchRequest, compare_recent};
+use cache_core::value::{CacheNumber, CacheValue};
+
+fn channel(viewed_at: u64, updated_at: u64) -> Record {
+ Record {
+ fields: [
+ (
+ "__typename".into(),
+ CacheValue::String("GraphqlSoupChannel".into()),
+ ),
+ ("name".into(), CacheValue::String("Channel".into())),
+ (
+ "viewedAt".into(),
+ CacheValue::Number(CacheNumber::PosInt(viewed_at)),
+ ),
+ (
+ "updatedAt".into(),
+ CacheValue::Number(CacheNumber::PosInt(updated_at)),
+ ),
+ ]
+ .into(),
+ }
+}
+
+#[test]
+fn viewed_first_browse_order_is_applied_before_the_page_limit() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("viewed-first-pages").unwrap();
+ let mut entries = (0..50)
+ .map(|index| {
+ (
+ key(&format!("GraphqlSoupChannel:{index:02}")),
+ channel(1, 3),
+ )
+ })
+ .collect::<Vec<_>>();
+ entries.push((key("GraphqlSoupChannel:recently-viewed"), channel(2, 2)));
+ storage.put_batch(entries).await.unwrap();
+ let mut engine = Engine::new(storage);
+ let mut request = SearchRequest {
+ profile: SearchProfile::QuickAccessV1,
+ buckets: vec!["channel".into()],
+ query: String::new(),
+ cursor: None,
+ limit: 50,
+ now_ms: 3,
+ };
+ let first = engine.search(&request).await.unwrap();
+ assert_eq!(first.documents.len(), 50);
+ assert_eq!(
+ first.documents[0].record_key.as_ref(),
+ "GraphqlSoupChannel:recently-viewed"
+ );
+ request.cursor = first.next_cursor;
+ assert!(request.cursor.is_some());
+ let second = engine.search(&request).await.unwrap();
+ assert_eq!(second.documents.len(), 1);
+ assert!(second.next_cursor.is_none());
+ let rows = first
+ .documents
+ .into_iter()
+ .chain(second.documents)
+ .collect::<Vec<_>>();
+ assert!(
+ rows.windows(2)
+ .all(|rows| !compare_recent(&rows[0], &rows[1]).is_gt())
+ );
+ });
+}
+
+#[test]
+fn reopen_rebuilds_old_search_rows_once_without_replacing_durable_data() {
+ block_on(async {
+ for old_version in [None, Some("1")] {
+ let database =
+ TursoMemoryDatabase::new(format!("projection-upgrade-{old_version:?}.db"));
+ let mut storage = database.open("scope").unwrap();
+ // More than two batches, with keys crossing a typename boundary.
+ let mut entries = (0..600)
+ .map(|index| {
+ (
+ key(&format!("GraphqlSoupChannel:{index:03}")),
+ channel(1, 3),
+ )
+ })
+ .collect::<Vec<_>>();
+ entries.push((key("GraphqlSoupChannel:recently-viewed"), channel(2, 2)));
+ entries.push((
+ key("GraphqlSoupDocument:document"),
+ quick_access_document("Document", 2),
+ ));
+ entries.push((key("Thing:retained"), record("unchanged")));
+ storage.put_batch(entries.clone()).await.unwrap();
+ storage.enqueue_mutation(queued("Pending")).await.unwrap();
+ let pending = storage.load_mutation_queue().await.unwrap();
+ let mut engine = Engine::new(storage);
+ let generation = engine.current_storage_generation().await.unwrap();
+ let storage = engine.into_storage();
+ // Model rows written by the previous max(viewedAt, updatedAt) projection.
+ raw_execute(
+ &storage,
+ "UPDATE search_documents SET timestamp_ms = 3 WHERE __typename = 'GraphqlSoupChannel'",
+ vec![],
+ );
+ raw_execute(
+ &storage,
+ "DELETE FROM meta WHERE key = 'quick_access_projection_version'",
+ vec![],
+ );
+ if let Some(version) = old_version {
+ raw_execute(
+ &storage,
+ "INSERT INTO meta (key, value) VALUES ('quick_access_projection_version', ?1)",
+ vec![text(version)],
+ );
+ }
+ storage.try_close().unwrap();
+
+ let mut storage = database.open("scope").unwrap();
+ let rows = storage
+ .load_search_documents(SearchProfile::QuickAccessV1)
+ .await
+ .unwrap();
+ assert_eq!(rows.len(), 602);
+ assert_eq!(rows.iter().filter(|row| row.timestamp_ms == 1).count(), 600);
+ assert_eq!(
+ storage
+ .get_batch(
+ &entries
+ .iter()
+ .map(|(key, _)| key.clone())
+ .collect::<Vec<_>>()
+ )
+ .await
+ .unwrap(),
+ entries
+ .iter()
+ .map(|(_, record)| Some(record.clone()))
+ .collect::<Vec<_>>()
+ );
+ assert_eq!(storage.load_mutation_queue().await.unwrap(), pending);
+ let mut engine = Engine::new(storage);
+ assert_eq!(
+ engine.current_storage_generation().await.unwrap(),
+ generation
+ );
+ storage = engine.into_storage();
+ storage.try_close().unwrap();
+
+ // A normal subsequent reopen must not scan or decode the corpus.
+ driver::arm_reset_failure(SEARCH_REBUILD_RECORDS);
+ let storage = database.open("scope").unwrap();
+ assert_eq!(storage.load_mutation_queue().await.unwrap(), pending);
+ expect_reset_reason(
+ driver::query(
+ &storage.connection(),
+ SEARCH_REBUILD_RECORDS,
+ vec![text("GraphqlSoupChannel"), Value::from_i64(1)],
+ ),
+ PhysicalResetReason::TransactionOutcomeUncertain,
+ );
+ storage.try_close().unwrap();
+ }
+ });
+}
+
+#[test]
+fn projection_rebuild_rolls_back_search_rows_and_version_on_failure() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("projection-upgrade-failure").unwrap();
+ storage
+ .put_batch(vec![(key("GraphqlSoupChannel:channel"), channel(1, 3))])
+ .await
+ .unwrap();
+ raw_execute(
+ &storage,
+ "UPDATE search_documents SET timestamp_ms = 3",
+ vec![],
+ );
+ raw_execute(
+ &storage,
+ "UPDATE meta SET value = '1' WHERE key = 'quick_access_projection_version'",
+ vec![],
+ );
+ let before = storage
+ .load_search_documents(SearchProfile::QuickAccessV1)
+ .await
+ .unwrap();
+ // Fail after the DELETE has executed; the enclosing transaction must
+ // retain the complete previous projection and its previous version.
+ driver::arm_reset_failure(SEARCH_REBUILD_RECORDS);
+ expect_reset_reason(
+ ensure_search_projection_version(&storage.connection()),
+ PhysicalResetReason::TransactionOutcomeUncertain,
+ );
+ assert_eq!(
+ storage
+ .load_search_documents(SearchProfile::QuickAccessV1)
+ .await
+ .unwrap(),
+ before
+ );
+ assert_eq!(
+ raw_scalar(
+ &storage,
+ "SELECT CAST(value AS INTEGER) FROM meta WHERE key = 'quick_access_projection_version'"
+ ),
+ 1
+ );
+ ensure_search_projection_version(&storage.connection()).unwrap();
+ assert_eq!(
+ storage
+ .load_search_documents(SearchProfile::QuickAccessV1)
+ .await
+ .unwrap()[0]
+ .timestamp_ms,
+ 1
+ );
+ });
+}
+
+#[test]
+fn projection_rebuild_seeks_past_earlier_rows_instead_of_scanning_them() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("projection-upgrade-cost").unwrap();
+ storage
+ .put_batch(
+ (0..2_000)
+ .map(|index| {
+ (
+ key(&format!("GraphqlSoupChannel:{index:04}")),
+ channel(1, 3),
+ )
+ })
+ .collect(),
+ )
+ .await
+ .unwrap();
+ let mut statement =
+ driver::prepare(&storage.connection(), SEARCH_REBUILD_RECORDS_AFTER).unwrap();
+ let rows = driver::query_prepared(
+ &mut statement,
+ vec![
+ text("GraphqlSoupChannel"),
+ text("1989"),
+ Value::from_i64(10),
+ ],
+ )
+ .unwrap();
+ assert_eq!(rows.len(), 10);
+ assert_eq!(required_text(&rows[0], 0).unwrap(), "1990");
+ assert!(
+ statement.metrics().vm_steps < 500,
+ "late rebuild batch took {} VM steps",
+ statement.metrics().vm_steps
+ );
+ });
+}
diff --git a/crates/client/cache-wasm/Cargo.toml b/crates/client/cache-wasm/Cargo.toml
index 45835b9857..3f32f9905d 100644
--- a/crates/client/cache-wasm/Cargo.toml
+++ b/crates/client/cache-wasm/Cargo.toml
@@ -2,8 +2,8 @@
edition = "2024"
name = "cache-wasm"
publish = false
-# Rebuild the browser cache with initiative activity action schema support.
-version = "0.6.26"
+# Rebuild for durable hydration generations and viewed-first search projections.
+version = "0.6.27"
[features]
default = []
@@ -38,10 +38,10 @@ serde = { workspace = true }
serde-wasm-bindgen = { workspace = true }
serde_json = { workspace = true }
turso-opfs = { path = "../turso-opfs" }
+uuid = { workspace = true, features = ["js"] }
wasm-bindgen = { workspace = true }
wasm-bindgen-futures = { workspace = true }
[target.'cfg(target_arch = "wasm32")'.dev-dependencies]
soup-filter-projection = { path = "../../soup_filter_projection", default-features = false }
-uuid = { workspace = true, features = ["js"] }
wasm-bindgen-test = { workspace = true }
diff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rs
index 6e2a6abcf4..ed6abc3bf7 100644
--- a/crates/client/cache-wasm/src/shell.rs
+++ b/crates/client/cache-wasm/src/shell.rs
@@ -941,6 +941,18 @@ impl CacheEngine {
})
}
+ /// Returns the durable cache generation, initializing it when absent.
+ #[wasm_bindgen(js_name = currentStorageGeneration)]
+ pub fn current_storage_generation(&self) -> js_sys::Promise {
+ let state = self.state.clone();
+ future_to_promise(async move {
+ let mut state = state.lock().await;
+ let result = state.engine_mut()?.current_storage_generation().await;
+ let generation = state.engine_result(result)?;
+ Ok(JsValue::from_str(&generation.to_string()))
+ })
+ }
+
/// Returns the opaque identity bound to this cache, or `null` when no
/// identity-bearing response has been stored yet.
#[wasm_bindgen(js_name = boundIdentity)]
diff --git a/docs/AGENT_GUIDE/navigation.md b/docs/AGENT_GUIDE/navigation.md
index 71e1906ea6..e35e8ea082 100644
--- a/docs/AGENT_GUIDE/navigation.md
+++ b/docs/AGENT_GUIDE/navigation.md
@@ -427,10 +427,18 @@ Counts describe loaded results, not the full server corpus. Scans through
incomplete or already-visible cache hits are bounded per action; continue
navigating/scrolling, or narrow the query, to resume from the saved cursor.
A failed local refresh keeps displayed rows and their continuation available for
-another pagination attempt. A missing item may still be uncached, but should appear after hydration without retyping. Cmd+K's
+another pagination attempt. Missing items may still be uncached, but should appear
+after hydration without retyping, including channels outside the first cached
+page. Cmd+K's
local search excludes unsupported email hits before limiting entity results;
email mentions keep their separate search-service path.
+Cmd+K merges cached and locally available items before applying recency order.
+An empty query prefers when an item was last viewed, falling back to its update
+time; equal timestamps have a stable entity-type and ID order. Searching retains the menu's
+relevance/recency ranking and DM boost with GraphQL enabled. Verify that refreshing
+the cache or reopening the menu with unchanged data does not reorder the results.
+
Pending or failed Quick Access history, recently-viewed, and cached-channel lookups
must not hide the app shell. Verify a cold lookup with Cmd/Ctrl+K: navigation stays
mounted and usable while the optional source loads or fails. When no entity rows
@@ -444,10 +452,14 @@ then catch up with one coalesced refresh. Verify with cache reads slower than th
waiting for background updates to stop. Changing the query/category or closing
the menu still discards obsolete search results. A failed background
refresh retains available history/channel items and recently-viewed ordering.
-Placeholder results also remain usable while replacement data loads. A normal cache-worker
-handoff between tabs preserves backfill cursors and watermarks; only a replacement
-that creates or resets stored cache data discards them. Per-lane full-refresh and
-Shared Mail restart rules still apply.
+Placeholder results also remain usable while replacement data loads. A normal
+cache-worker handoff between tabs preserves backfill cursors and watermarks.
+Hydration checkpoints belong to the stored cache generation: resetting or
+recreating the database starts a full scan even when an old checkpoint survives
+or the page missed the reset notification. Verify that clearing only the cache
+database and reloading recovers older channels as well as recent ones. A reset
+during hydration must also restart the scan. Per-lane full-refresh and Shared Mail
+restart rules still apply.
## Keyboard model (from the in-app guide; verified partially)