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(crm): hydrate contacts during graphql backfill (#8834)

gbirmana36151316047
diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.md
index fe323fef0b..cb13631aee 100644
--- a/apps/web/AGENTS.md
+++ b/apps/web/AGENTS.md
@@ -531,6 +531,8 @@ resolved session ID; keep the existing `AgentSessionProvider` subscription to
through restarts and remove them on explicit logout. See the Tasks walkthrough.
- Shared server-state queries and mutations live in `src/lib/queries`; keep
feature-specific query orchestration with its owning feature.
+- Keep CRM contacts explicitly included in the auxiliary GraphQL backfill;
+ bump its checkpoint version when changing the hydration input contract.
- Refresh the channel list's bounded unread edge when opening a conversation,
including an empty unread result after a read on another device.
- Decide channel detail access from completed server results; bound confirmations of contradictory cache membership, preserve known unavailable state during retries, and keep unavailable routes registered for notification/reconnect refresh.
diff --git a/apps/web/docs/graphql-normalized-cache-plan.md b/apps/web/docs/graphql-normalized-cache-plan.md
index 33861e084a..4de95badce 100644
--- a/apps/web/docs/graphql-normalized-cache-plan.md
+++ b/apps/web/docs/graphql-normalized-cache-plan.md
@@ -1003,6 +1003,21 @@ Background hydration retains its existing opt-in notification contract. Soup's
local collection source opts in; ordinary foreground queries refresh on their
normal affected-operation notifications.
+## CRM contact hydration
+
+The auxiliary lane in `src/lib/queries/soup/backfill.ts` hydrates CRM contacts
+alongside companies and foreign entities. Contacts require the explicit
+`crmContactFilter: { literal: { include: true } }` opt-in; an omitted filter
+returns no contacts. `SoupBackfill` already selects `GraphqlCrmContactFields`
+under `items @cacheOnly`, so records are persisted without materializing their
+payloads in the page. The backend scopes contacts to visible contacts in the
+viewer's accessible CRM-enabled teams.
+
+Checkpoint version 18 restarts scans saved before contacts were included. The
+lane retains normal cursor pagination, retries, cancellation, storage-generation
+checks, and `graphql_cache.backfill` telemetry. Subsequent passes refresh all
+visible contacts because the contact filter has no updated-at watermark.
+
## Authoritative Mail membership repair
The shared Soup adapter reconciles supported `UPDATED_AT` Mail first pages
diff --git a/apps/web/src/lib/queries/soup/backfill-contacts.test.ts b/apps/web/src/lib/queries/soup/backfill-contacts.test.ts
new file mode 100644
index 0000000000..01b71625c8
--- /dev/null
+++ b/apps/web/src/lib/queries/soup/backfill-contacts.test.ts
@@ -0,0 +1,116 @@
+import { SoupBackfillDocument } from '@service-storage/graphql/generated/graphql';
+import * as Effect from 'effect/Effect';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+ AUXILIARY_SOUP_BACKFILL_LANE,
+ loadSoupBackfillCheckpoint,
+ runSoupBackfill,
+} from './backfill';
+
+const graphqlMocks = vi.hoisted(() => ({
+ hydrateGraphqlSoup: vi.fn(),
+}));
+
+vi.mock('@app/lib/analytics/posthog', () => ({
+ useFeatureFlag: vi.fn(),
+}));
+vi.mock('@core/constant/featureFlags', () => ({
+ ENABLE_GRAPHQL_BACKFILL: true,
+ enableGraphqlSoup: { key: 'enable-graphql-soup' },
+}));
+vi.mock('@core/cross-tab/tab-leader', () => ({
+ createTabLeaderSignal: vi.fn(),
+}));
+vi.mock('@service-storage/graphql-soup', () => ({
+ getGraphqlSoupCacheHost: vi.fn(),
+ hydrateGraphqlSoup: graphqlMocks.hydrateGraphqlSoup,
+}));
+
+describe('CRM contact backfill', () => {
+ beforeEach(() => {
+ localStorage.clear();
+ graphqlMocks.hydrateGraphqlSoup.mockReset();
+ });
+
+ it.each([false, true])(
+ 'hydrates contacts from the beginning with an old checkpoint (completed=%s)',
+ async (completed) => {
+ localStorage.setItem(
+ 'graphql-soup-backfill:v17:user-1:auxiliary-entities',
+ JSON.stringify({
+ userId: 'user-1',
+ storageGeneration: 'storage-1',
+ nextCursor: completed ? null : 'cursor-without-contacts',
+ pagesFetched: 12,
+ completed,
+ scanStartedAt: completed ? null : '2026-09-01T00:00:00.000Z',
+ updatedSince: completed ? '2026-09-01T00:00:00.000Z' : null,
+ completedAt: completed ? '2026-09-02T00:00:00.000Z' : null,
+ })
+ );
+ const host = {
+ currentStorageGeneration: async () => 'storage-1',
+ };
+ graphqlMocks.hydrateGraphqlSoup
+ .mockResolvedValueOnce({ nextCursor: 'contacts-page-2' })
+ .mockResolvedValue({ nextCursor: null });
+
+ await Effect.runPromise(
+ runSoupBackfill('user-1', host, {
+ ...AUXILIARY_SOUP_BACKFILL_LANE,
+ pageDelayMs: 0,
+ })
+ );
+
+ expect(graphqlMocks.hydrateGraphqlSoup).toHaveBeenNthCalledWith(
+ 1,
+ SoupBackfillDocument,
+ {
+ input: {
+ initial: expect.objectContaining({
+ filters: expect.objectContaining({
+ crmContactFilter: { literal: { include: true } },
+ }),
+ }),
+ },
+ },
+ { signal: expect.any(AbortSignal) }
+ );
+ expect(graphqlMocks.hydrateGraphqlSoup).toHaveBeenNthCalledWith(
+ 2,
+ SoupBackfillDocument,
+ {
+ input: {
+ continuation: {
+ cursor: 'contacts-page-2',
+ expand: true,
+ emailView: 'ALL',
+ },
+ },
+ },
+ { signal: expect.any(AbortSignal) }
+ );
+ expect(
+ loadSoupBackfillCheckpoint('user-1', 'auxiliary-entities')
+ ).toMatchObject({
+ pagesFetched: 2,
+ nextCursor: null,
+ completed: true,
+ storageGeneration: 'storage-1',
+ });
+
+ // Contacts have no updatedAt filter; subsequent passes still hydrate
+ // their full corpus, including changes to older contacts.
+ await Effect.runPromise(
+ runSoupBackfill('user-1', host, AUXILIARY_SOUP_BACKFILL_LANE)
+ );
+ expect(graphqlMocks.hydrateGraphqlSoup.mock.calls[2]?.[1]).toMatchObject({
+ input: {
+ initial: {
+ filters: { crmContactFilter: { literal: { include: true } } },
+ },
+ },
+ });
+ }
+ );
+});
diff --git a/apps/web/src/lib/queries/soup/backfill.test.tsx b/apps/web/src/lib/queries/soup/backfill.test.tsx
index 5ae255efa1..2036416d0b 100644
--- a/apps/web/src/lib/queries/soup/backfill.test.tsx
+++ b/apps/web/src/lib/queries/soup/backfill.test.tsx
@@ -108,7 +108,7 @@ function seedCheckpoint(overrides: Partial<SoupBackfillCheckpoint> = {}) {
...overrides,
};
localStorage.setItem(
- 'graphql-soup-backfill:v17:user-1:core-entities',
+ 'graphql-soup-backfill:v18:user-1:core-entities',
JSON.stringify(checkpoint)
);
}
@@ -825,7 +825,7 @@ describe('runSoupBackfills', () => {
'restarts the runner with %s storage semantics and ignores obsolete completions',
async (storage) => {
localStorage.setItem(
- 'graphql-soup-backfill:v17:user-1:core-entities',
+ 'graphql-soup-backfill:v18:user-1:core-entities',
JSON.stringify({
userId: 'user-1',
storageGeneration: 'storage-1',
@@ -899,7 +899,7 @@ describe('runSoupBackfills', () => {
const watermark = '2026-09-01T00:00:00.000Z';
for (const checkpointId of ['core-entities', 'email-thread-pages']) {
localStorage.setItem(
- `graphql-soup-backfill:v17:user-1:${checkpointId}`,
+ `graphql-soup-backfill:v18:user-1:${checkpointId}`,
JSON.stringify({
userId: 'user-1',
storageGeneration: 'storage-1',
diff --git a/apps/web/src/lib/queries/soup/backfill.ts b/apps/web/src/lib/queries/soup/backfill.ts
index 6993718a8d..032dc9a2d6 100644
--- a/apps/web/src/lib/queries/soup/backfill.ts
+++ b/apps/web/src/lib/queries/soup/backfill.ts
@@ -28,9 +28,8 @@ import { useMailAccountsQuery } from '../email/mail-accounts';
// Bump when a default backfill input or completion guarantee changes so
// persisted cursors cannot retain an older hydration contract.
-// Rehydrate raw file-type projections after retiring enum-normalized facts.
-// Old cursors must not skip records when the cache compatibility epoch changes.
-const BACKFILL_VERSION = 17;
+// Restart old cursors whose filters did not include CRM contacts.
+const BACKFILL_VERSION = 18;
const PAGE_LIMIT = 100;
// Five threads × twenty messages reaches the backend's 100-message cap.
const EMAIL_CONTENT_PAGE_LIMIT = 5;
@@ -213,7 +212,7 @@ export const SHARED_EMAIL_FILTER_BACKFILL_LANE: SoupBackfillParams = {
},
};
-/** Backfills CRM companies and foreign entities. */
+/** Backfills CRM companies, contacts, and foreign entities. */
export const AUXILIARY_SOUP_BACKFILL_LANE: SoupBackfillParams = {
checkpointId: 'auxiliary-entities',
input: {
@@ -230,6 +229,7 @@ export const AUXILIARY_SOUP_BACKFILL_LANE: SoupBackfillParams = {
channelFilter: { literal: { channelId: EXCLUDED_ENTITY_ID } },
channelThreadFilter: { literal: { threadId: EXCLUDED_ENTITY_ID } },
callFilter: { literal: { callId: EXCLUDED_ENTITY_ID } },
+ crmContactFilter: { literal: { include: true } },
},
},
};