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.

33.9 KB
Raw Blame
import { QUERY_FILTERS_BASE } from '@app/features/next-soup/filters/query-filters';
import {
  enableGraphqlSoup,
  isFeatureEnabled,
} from '@core/constant/featureFlags';
import { fireAndForget } from '@core/util/fireAndForget';
import { Telemetry } from '@macro-inc/observability';
import type { UnifiedSearchResponseItem } from '@service-search/generated/models';
import type {
  PostSoupRequest,
  SoupApiItem,
} from '@service-storage/generated/schemas';
import type { SoupPage } from '@service-storage/generated/schemas/soupPage';
import {
  type InfiniteData,
  partialMatchKey,
  type Query,
  type QueryKey,
} from '@tanstack/solid-query';
import { isAfter } from 'date-fns';
import { match } from 'ts-pattern';
import { queryClient } from '../../client';
import { soupQueryExcludesDone } from '../excludes-done';
import { refreshActiveGraphqlSoupQueries } from '../graphql/active-queries';
import type { SoupAstItemsPage } from '../items';
import { soupKeys } from '../keys';
import {
  insertGroupedPage,
  insertGroupQueries,
  removeGroupedPage,
  removeGroupQueries,
  syncGroupedParents,
  syncGroupQueries,
} from './grouped-operations';
import {
  getNormalizationObjectKey,
  getSoupNormalizer,
  type NormalizerData,
  soupNormKey,
  stripSoupNormPrefix,
} from './normalizer';
import { raiseNotifiedFloor } from './notified-floor';
import { ownTouchStamp } from './own-touch';
import { retainRestoredSoupItem } from './restored-membership';
import type {
  SoupEntityPartial,
  SoupEntityTag,
  SoupTransaction,
} from './types';
import { getSoupQueryMeta } from './utils';

type SoupItemsInfiniteData = InfiniteData<SoupPage, unknown>;
type SoupAstItemsInfiniteData = InfiniteData<SoupAstItemsPage, unknown>;
type SoupSearchInfiniteData = InfiniteData<
  { results: UnifiedSearchResponseItem[] },
  unknown
>;

/**
 * Cancel in-flight soup list refetches before an optimistic cache write.
 *
 * Only cancels queries that already have data. Cancelling an in-flight
 * initial fetch (data === undefined) reverts it to a stuck pending/idle
 * state, which leaves the soup view blank on refresh.
 */
function cancelSoupQueries() {
  const predicate = (query: Query) => query.state.data !== undefined;
  queryClient.cancelQueries({ queryKey: soupKeys.items._def, predicate });
  queryClient.cancelQueries({
    queryKey: soupKeys.astItems._def,
    predicate,
  });
}

/**
 * Optimistically update a single soup entity across all queries that
 * reference it. After normy's field merge, reconciles group membership in
 * every grouped cache containing this entity (`itemIds`-only mutations;
 * the items pool itself isn't moved between groups). Date and
 * non-categorical groupings fall back to invalidation.
 *
 * Partial shape:
 * - Channels: `{ tag: 'channel', data: { channel: { id, ...fields } }, frecency_score }`
 * - Everything else: `{ tag, data: { id, ...fields }, frecency_score }`
 */

export function optimisticUpdateSoupEntity<T extends SoupEntityTag>(
  partial: SoupEntityPartial<T>
): SoupTransaction {
  return updateSoupEntity(partial, true);
}

/** Server hydration must not cancel the list revalidation it accompanies. */
function updateSoupEntity<T extends SoupEntityTag>(
  partial: SoupEntityPartial<T>,
  cancelRefetches: boolean
): SoupTransaction {
  const normalizer = getSoupNormalizer();
  const normKey = getNormalizationObjectKey(partial);

  const dependentKeys = normKey
    ? normalizer.getDependentQueriesByIds([normKey])
    : [];

  // Cancel only the queries this patch touches. A blanket cancel strands
  // unrelated in-flight refetches (e.g. an invalidated destination folder's
  // list refetching on mount): the fetch dies and nothing retries it.
  // Skip cold initial fetches (data === undefined); cancelling those can leave
  // the query stuck pending, which is why cancelSoupQueries has the same guard.
  // Hash the keys once and cancel in a single cache pass: an `exact` cancel
  // per key re-hashes that key against every cached query.
  const cancelHashes = new Set(
    (cancelRefetches ? dependentKeys : [])
      .filter(
        (queryKey) =>
          partialMatchKey(queryKey, soupKeys.items._def) ||
          partialMatchKey(queryKey, soupKeys.astItems._def)
      )
      .map(
        (queryKey) => queryClient.defaultQueryOptions({ queryKey }).queryHash
      )
  );
  if (cancelHashes.size > 0) {
    queryClient.cancelQueries({
      predicate: (query) =>
        query.state.data !== undefined && cancelHashes.has(query.queryHash),
    });
  }
  const previousDependents = dependentKeys.map(
    (key: QueryKey) =>
      [key, queryClient.getQueryData<SoupItemsInfiniteData>(key)] as const
  );
  const previousAllSoup = snapshotSoup();

  normalizer.setNormalizedData(partial as NormalizerData);

  if (normKey) {
    const entityId = stripSoupNormPrefix(normKey);
    const entity = getSoupEntityById(entityId);
    if (entity) {
      syncGroupedParents(entityId, entity);
      syncGroupQueries(entityId, entity);
    }
  }

  return {
    rollback: () => {
      for (const [key, data] of previousDependents) {
        queryClient.setQueryData(key, data);
      }
      restoreSnapshot(previousAllSoup);
    },
  };
}

/** Apply a row read from the server to every list holding it, without
 * cancelling a list revalidation it may accompany. */
export function hydrateSoupEntity<T extends SoupEntityTag>(
  partial: SoupEntityPartial<T>
): void {
  updateSoupEntity(partial, false);
}

export function getSoupEntityById(entityId: string): SoupApiItem | undefined {
  return (getSoupNormalizer().getObjectById(soupNormKey(entityId)) ??
    undefined) as SoupApiItem | undefined;
}

/**
 * Optimistically stamp the viewer's own touch on a cached entity so the
 * touched_by_me (Recent) order moves it to the top immediately, ahead of the
 * activity consumer. Call it only from mutations whose server side records
 * an activity — see the allowlist rule in `own-touch.ts`, which also records
 * the stamp as a floor so touched-mode refetches that outrun the consumer
 * can't clobber the optimistic order; the floor clears once the server's
 * value catches up. Non-touched responses omit the field entirely, so the
 * field-merge never clears the stamp either.
 */
export function bumpSoupEntityTouchedAt(
  entityId: string
): SoupTransaction | undefined {
  const current = getSoupEntityById(entityId);
  if (!current) return undefined;
  const touched_at = ownTouchStamp(entityId);
  const frecency_score = current.frecency_score;

  if (current.tag === 'channel') {
    return optimisticUpdateSoupEntity({
      tag: 'channel',
      data: { channel: { id: current.data.channel.id } },
      frecency_score,
      touched_at,
    });
  }
  if (current.tag === 'call') {
    return optimisticUpdateSoupEntity({
      tag: 'call',
      data: { callId: current.data.callId },
      frecency_score,
      touched_at,
    });
  }
  return optimisticUpdateSoupEntity({
    tag: current.tag,
    data: { id: current.data.id },
    frecency_score,
    touched_at,
  } as SoupEntityPartial);
}

/**
 * Stamp a freshly delivered notification's time on its cached entity so the
 * inbox's notified_at order moves the row up (and re-buckets its date header)
 * without waiting for a refetch. Newest wins: an out-of-order delivery never
 * moves a row back down. The stamp is also recorded as a floor (see
 * `notified-floor.ts`) so a notified page that was in flight when the
 * notification landed cannot overwrite it with the previous stamp. The floor
 * survives optimistic reads and overlapping refreshes for a bounded interval.
 * Non-notified responses omit the field, so field merges preserve the stamp.
 */
export function bumpSoupEntityNotifiedAt(
  entityId: string,
  notifiedAt: string
): SoupTransaction | undefined {
  raiseNotifiedFloor(entityId, notifiedAt);
  const current = getSoupEntityById(entityId);
  if (!current) return undefined;
  const existing = current.notified_at ?? undefined;
  if (!shouldUpdateOptimisticTimestamp(existing, notifiedAt)) return undefined;
  const frecency_score = current.frecency_score;

  if (current.tag === 'channel') {
    return optimisticUpdateSoupEntity({
      tag: 'channel',
      data: { channel: { id: current.data.channel.id } },
      frecency_score,
      notified_at: notifiedAt,
    });
  }
  if (current.tag === 'call') {
    return optimisticUpdateSoupEntity({
      tag: 'call',
      data: { callId: current.data.callId },
      frecency_score,
      notified_at: notifiedAt,
    });
  }
  return optimisticUpdateSoupEntity({
    tag: current.tag,
    data: { id: current.data.id },
    frecency_score,
    notified_at: notifiedAt,
  } as SoupEntityPartial);
}

/**
 * Mark stale only the soup queries containing a specific entity.
 * Prefer this over `invalidateAllSoup` when you know the affected entity ID.
 */
export function invalidateSoupEntity(entityId: string): void {
  const normalizer = getSoupNormalizer();
  const keys = normalizer.getDependentQueriesByIds([soupNormKey(entityId)]);
  for (const queryKey of keys) {
    // Normy JSON-roundtrips complete keys, turning undefined array slots into
    // null. Exact matching uses the same hash; partial matching misses them.
    queryClient.invalidateQueries({ queryKey, exact: true });
  }
}

/** Mark stale soup queries whose query key references any of the given ids (e.g. project-scoped views). */
export function invalidateSoupQueriesReferencing(ids: string[]): void {
  if (ids.length === 0) return;
  queryClient.invalidateQueries({
    queryKey: ['soup'],
    predicate: (query) => {
      const serialized = JSON.stringify(query.queryKey);
      return ids.some((id) => serialized.includes(id));
    },
  });
}

/** Mark every soup list query stale. Use `invalidateSoupEntity` when the entity ID is known. */
export function invalidateAllSoup(): void {
  queryClient.invalidateQueries({
    queryKey: soupKeys.items._def,
  });
  queryClient.invalidateQueries({
    queryKey: soupKeys.astItems._def,
  });
  // Expanded single-group caches back grouped views' rows (mail/inbox group
  // by date); leaving them stale keeps removed rows hidden even after their
  // parent queries refetch.
  queryClient.invalidateQueries({
    queryKey: soupKeys.groupedGroup._def,
  });
}

export function hasSoupEntity(entityId: string): boolean {
  return getSoupNormalizer().getObjectById(soupNormKey(entityId)) != null;
}

/** Channels nest the id under `data.channel.id`; call records under `data.callId`. */
export function getSoupItemId(item: SoupApiItem): string {
  switch (item.tag) {
    case 'channel':
      return item.data.channel.id;
    case 'call':
      return item.data.callId;
    case 'channelThread':
      return item.data.id;
    default:
      return item.data.id;
  }
}

/**
 * Insert a new entity into the first page of every active soup list query.
 * Grouped pages: derive the item's target groups via `computeGroupKeysForItem`
 * and upsert into each resolvable group. Date / unresolved labels invalidate.
 */
export function insertSoupEntity(item: SoupApiItem): SoupTransaction {
  cancelSoupQueries();

  const previous = snapshotSoup();
  queryClient.setQueriesData<SoupItemsInfiniteData>(
    {
      predicate: (query) => {
        if (!partialMatchKey(query.queryKey, soupKeys.items._def)) return false;
        const meta = getSoupQueryMeta(query.meta);
        if (meta.itemFilter && !meta.itemFilter(item)) return false;
        return !meta.insertFilter || meta.insertFilter(item);
      },
    },
    (prev) => {
      if (!prev?.pages) return prev;
      return {
        ...prev,
        pages: prev.pages.map((p, i) =>
          i === 0 ? { ...p, items: [item, ...p.items] } : p
        ),
      };
    }
  );

  const parents = queryClient.getQueriesData<SoupAstItemsInfiniteData>({
    queryKey: soupKeys.astItems._def,
  });

  for (const [key, prev] of parents) {
    if (!prev?.pages?.length) continue;

    const meta = getSoupQueryMeta(
      queryClient.getQueryCache().find({ queryKey: key })?.meta
    );
    const filter = meta.itemFilter;
    if (filter && !filter(item)) continue;
    if (meta.insertFilter && !meta.insertFilter(item)) continue;

    const firstPage = prev.pages[0];

    if (firstPage.kind === 'flat') {
      queryClient.setQueryData<SoupAstItemsInfiniteData>(key, {
        ...prev,
        pages: prev.pages.map((p, i) =>
          i === 0 && p.kind === 'flat' ? { ...p, items: [item, ...p.items] } : p
        ),
      });

      continue;
    }

    const nextPage = insertGroupedPage(
      firstPage,
      item,
      getSoupItemId(item),
      meta.groupBy
    );

    if (!nextPage) {
      queryClient.invalidateQueries({ queryKey: key });
      continue;
    }

    queryClient.setQueryData<SoupAstItemsInfiniteData>(key, {
      ...prev,
      pages: [nextPage, ...prev.pages.slice(1)],
    });
  }

  insertGroupQueries(item, getSoupItemId(item));

  return { rollback: () => restoreSnapshot(previous) };
}

export function removeSoupEntities(
  entityIds: Set<string>,
  matches?: (item: SoupApiItem, id: string) => boolean
): SoupTransaction {
  cancelSoupQueries();

  const previous = snapshotSoup();
  const shouldRemove = (item: SoupApiItem) => {
    const id = getSoupItemId(item);
    return entityIds.has(id) && (!matches || matches(item, id));
  };

  queryClient.setQueriesData<SoupItemsInfiniteData>(
    {
      predicate: (q) => partialMatchKey(q.queryKey, soupKeys.items._def),
    },
    (prev) => {
      if (!prev?.pages) return prev;
      return {
        ...prev,
        pages: prev.pages.map((page) => {
          const items = page.items.filter((item) => !shouldRemove(item));
          if (items.length === page.items.length) return page;
          return { ...page, items };
        }),
      };
    }
  );

  queryClient.setQueriesData<SoupAstItemsInfiniteData>(
    { queryKey: soupKeys.astItems._def },
    (prev) => {
      if (!prev?.pages?.length) return prev;

      const firstPage = prev.pages[0];

      if (firstPage.kind === 'flat') {
        // Flat AST queries can have multiple pages; remove the ids from every
        // page and preserve page references that were not affected.
        let changed = false;
        const pages = prev.pages.map((page) => {
          if (page.kind !== 'flat') return page;

          const items = page.items.filter((item) => !shouldRemove(item));

          if (items.length === page.items.length) return page;

          changed = true;
          return { ...page, items };
        });

        return changed ? { ...prev, pages } : prev;
      }

      // Grouped AST queries only use the first parent page. Group membership is
      // fully represented there by `groups[].itemIds`, so update that page once.
      const nextPage = removeGroupedPage(firstPage, entityIds, matches);

      return nextPage === firstPage
        ? prev
        : { ...prev, pages: [nextPage, ...prev.pages.slice(1)] };
    }
  );

  removeGroupQueries(entityIds, undefined, matches);

  return { rollback: () => restoreSnapshot(previous) };
}

/**
 * Remove entities only from soup queries whose key references any of the
 * given ids (e.g. a source folder's project-scoped views — the project UUID is
 * embedded in their compiled filter AST). Other queries keep the entities.
 */
export function removeSoupEntitiesFromQueriesReferencing(
  entityIds: Set<string>,
  referenceIds: string[]
): SoupTransaction {
  if (referenceIds.length === 0) return { rollback: () => {} };

  return removeSoupEntitiesWhere(entityIds, (key: QueryKey) => {
    const serialized = JSON.stringify(key);
    return referenceIds.some((id) => serialized.includes(id));
  });
}

/**
 * Remove entities from soup queries that filter out done content, leaving
 * them in place everywhere else (e.g. mail "All", which shows done threads).
 * Use with an entity-level done patch so the remaining rows reflect the new
 * state.
 */
export function removeSoupEntitiesFromDoneFilteredQueries(
  entityIds: Set<string>
): SoupTransaction {
  return removeSoupEntitiesWhere(entityIds, soupQueryExcludesDone);
}

/**
 * Prepend a cached entity to the done-excluding soup queries (see
 * `soupQueryExcludesDone`) whose pages don't contain it. A fresh notification
 * puts its entity back into those feeds server-side, but the client row may
 * have been optimistically removed when it was marked done — or the feed was
 * fetched while the entity had nothing outstanding — and the normalized
 * field merge only patches rows already present, so without this the feeds
 * would not show the entity again until their next refetch. Grouped pages
 * and expanded single-group caches (which back grouped views' rows and are
 * cached with staleTime Infinity) are restored the same way; groups that
 * can't be resolved locally (e.g. date buckets) invalidate instead.
 */
export function restoreSoupEntityToDoneFilteredQueries(
  entityId: string,
  incomingState: 'unseen' | 'seen' = 'unseen'
): void {
  const shouldRestore = (key: QueryKey) =>
    soupQueryExcludesDone(key, incomingState);
  const item = getSoupEntityById(entityId);
  if (!item) return;

  const cancelQuery = (key: QueryKey) =>
    queryClient.cancelQueries({
      queryKey: key,
      exact: true,
      predicate: (query) => query.state.data !== undefined,
    });

  const metaFor = (key: QueryKey) =>
    getSoupQueryMeta(queryClient.getQueryCache().find({ queryKey: key })?.meta);

  const containsEntity = (items: SoupApiItem[]) =>
    items.some((existing) => getSoupItemId(existing) === entityId);

  for (const [key, prev] of queryClient.getQueriesData<SoupItemsInfiniteData>({
    queryKey: soupKeys.items._def,
  })) {
    if (!shouldRestore(key)) continue;
    if (!prev?.pages?.length) continue;
    if (prev.pages.some((page) => containsEntity(page.items))) continue;

    const flatMeta = metaFor(key);
    if (flatMeta.itemFilter && !flatMeta.itemFilter(item)) continue;
    if (flatMeta.insertFilter && !flatMeta.insertFilter(item)) continue;

    fireAndForget(cancelQuery(key), 'soup-normalized-cache');
    queryClient.setQueryData<SoupItemsInfiniteData>(key, {
      ...prev,
      pages: prev.pages.map((page, index) =>
        index === 0 ? { ...page, items: [item, ...page.items] } : page
      ),
    });
    retainRestoredSoupItem(queryClient, key, item);
  }

  for (const [
    key,
    prev,
  ] of queryClient.getQueriesData<SoupAstItemsInfiniteData>({
    queryKey: soupKeys.astItems._def,
  })) {
    if (!shouldRestore(key)) continue;
    if (!prev?.pages?.length) continue;

    const meta = metaFor(key);
    if (meta.itemFilter && !meta.itemFilter(item)) continue;
    if (meta.insertFilter && !meta.insertFilter(item)) continue;

    const firstPage = prev.pages[0];

    if (firstPage.kind === 'flat') {
      if (
        prev.pages.some(
          (page) => page.kind === 'flat' && containsEntity(page.items)
        )
      ) {
        continue;
      }

      fireAndForget(cancelQuery(key), 'soup-normalized-cache');
      queryClient.setQueryData<SoupAstItemsInfiniteData>(key, {
        ...prev,
        pages: prev.pages.map((page, index) =>
          index === 0 && page.kind === 'flat'
            ? { ...page, items: [item, ...page.items] }
            : page
        ),
      });
      retainRestoredSoupItem(queryClient, key, item);
      continue;
    }

    // Grouped parents keep membership entirely on the first page.
    if (containsEntity(Object.values(firstPage.items))) {
      continue;
    }

    const nextPage = insertGroupedPage(firstPage, item, entityId, meta.groupBy);
    if (!nextPage) {
      queryClient.invalidateQueries({ queryKey: key });
      continue;
    }

    fireAndForget(cancelQuery(key), 'soup-normalized-cache');
    queryClient.setQueryData<SoupAstItemsInfiniteData>(key, {
      ...prev,
      pages: [nextPage, ...prev.pages.slice(1)],
    });
  }

  insertGroupQueries(item, entityId, shouldRestore);
}

/** Remove entities from the soup queries whose key matches the predicate. */
function removeSoupEntitiesWhere(
  entityIds: Set<string>,
  referencesIds: (key: QueryKey) => boolean
): SoupTransaction {
  // Scoped equivalent of cancelSoupQueries (same data !== undefined guard)
  const cancelPredicate = (query: Query) =>
    query.state.data !== undefined && referencesIds(query.queryKey);
  queryClient.cancelQueries({
    queryKey: soupKeys.items._def,
    predicate: cancelPredicate,
  });
  queryClient.cancelQueries({
    queryKey: soupKeys.astItems._def,
    predicate: cancelPredicate,
  });

  const previous = snapshotSoup();

  queryClient.setQueriesData<SoupItemsInfiniteData>(
    {
      predicate: (q) =>
        partialMatchKey(q.queryKey, soupKeys.items._def) &&
        referencesIds(q.queryKey),
    },
    (prev) => {
      if (!prev?.pages) return prev;
      return {
        ...prev,
        pages: prev.pages.map((page) => {
          const items = page.items.filter(
            (item) => !entityIds.has(getSoupItemId(item))
          );
          if (items.length === page.items.length) return page;
          return { ...page, items };
        }),
      };
    }
  );

  queryClient.setQueriesData<SoupAstItemsInfiniteData>(
    {
      queryKey: soupKeys.astItems._def,
      predicate: (q) => referencesIds(q.queryKey),
    },
    (prev) => {
      if (!prev?.pages?.length) return prev;

      const firstPage = prev.pages[0];

      if (firstPage.kind === 'flat') {
        let changed = false;
        const pages = prev.pages.map((page) => {
          if (page.kind !== 'flat') return page;

          const items = page.items.filter(
            (item) => !entityIds.has(getSoupItemId(item))
          );

          if (items.length === page.items.length) return page;

          changed = true;
          return { ...page, items };
        });

        return changed ? { ...prev, pages } : prev;
      }

      const nextPage = removeGroupedPage(firstPage, entityIds);

      return nextPage === firstPage
        ? prev
        : { ...prev, pages: [nextPage, ...prev.pages.slice(1)] };
    }
  );

  removeGroupQueries(entityIds, referencesIds);

  return { rollback: () => restoreSnapshot(previous) };
}

export function removeSearchEntities(
  entityIds: Set<string>,
  matches?: (item: UnifiedSearchResponseItem, id: string) => boolean
): SoupTransaction {
  queryClient.cancelQueries({ queryKey: soupKeys.search._def });

  const previous = queryClient.getQueriesData<SoupSearchInfiniteData>({
    queryKey: soupKeys.search._def,
  });

  queryClient.setQueriesData<SoupSearchInfiniteData>(
    { queryKey: soupKeys.search._def },
    (prev) => {
      if (!prev) return prev;
      return {
        ...prev,
        pages: prev.pages.map((page) => {
          const results = page.results.filter((result) => {
            const id = getSearchResultId(result);
            return (
              !entityIds.has(id) ||
              (matches !== undefined && !matches(result, id))
            );
          });
          return results.length === page.results.length
            ? page
            : { ...page, results };
        }),
      };
    }
  );

  return {
    rollback: () => {
      for (const [key, data] of previous) {
        queryClient.setQueryData(key, data);
      }
    },
  };
}

/**
 * Fetch a single entity from the server and merge it into the cache.
 * If the entity is already cached, updates it via normy (deep-merge).
 * If it's new, prepends it to the first page of every active soup list query.
 *
 * `ownTouch` marks the refetch as caused by the viewer's own mutation (e.g.
 * entity creation): the fetched item is stamped with an optimistic
 * `touched_at` — the single-entity response never carries one — so the
 * Recent feed's insert gate admits it, and the touched queries are spared
 * from the follow-up invalidation, which would replace their pages with
 * server state that can't include the entity until the activity consumer
 * catches up.
 *
 * `refreshGraphql` also network-refreshes mounted GraphQL Soup operations.
 * REST's normalized entity insertion cannot change GraphQL list or grouped-bin
 * membership, so creation callers must request this transport revalidation.
 *
 * `created` marks an entity that did not exist a moment ago, so it sorts first
 * in newest-first lists. It is inserted into the REST lists whose filters admit
 * it, without refetching any list, in either transport.
 *
 * `notified` marks a new notification about the entity, which a mounted
 * `notified_at` list must show even if the entity isn't cached yet.
 */
export async function refetchSoupEntity(
  entityId: string,
  entityType: SoupEntityTag,
  options?: {
    includeRoot?: boolean;
    ownTouch?: boolean;
    refreshGraphql?: boolean;
    created?: boolean;
    notified?: boolean;
  }
): Promise<void> {
  if (options?.refreshGraphql) {
    fireAndForget(refreshActiveGraphqlSoupQueries(), 'soup-normalized-cache');
  }

  // GraphQL lists never read this cache, so a miss means no REST list shows
  // the entity. Own-touch inserts still land because Home's touched_by_me
  // feed stays on REST, and notified ones because notified_at lists do.
  if (
    !options?.ownTouch &&
    !options?.created &&
    !(options?.notified && mountedNotifiedLists().length > 0) &&
    isFeatureEnabled(enableGraphqlSoup) &&
    !hasSoupEntity(entityId)
  ) {
    return;
  }

  const { storageServiceClient } = await import('@service-storage/client');

  const filter = buildSingleEntityFilter(entityType, entityId, options);

  const result = await storageServiceClient.getSoupItems({
    params: {},
    body: filter,
  });

  if (result.isErr()) {
    console.error(
      '[normalized-cache] operations: failed to fetch individual soup item',
      result
    );
    return;
  }

  const page = result.value;
  if (!page.items.length) return;

  for (let item of page.items) {
    const itemId = getSoupItemId(item);
    if (options?.ownTouch) {
      item = { ...item, touched_at: ownTouchStamp(itemId) };
    }
    if (hasSoupEntity(itemId)) {
      updateSoupEntity(item, false);
    } else {
      insertSoupEntity(item);
      if (options?.created) continue;
      if (options?.ownTouch) {
        invalidateAllSoupExceptTouched();
      } else {
        invalidateAllSoup();
      }
      if (options?.notified) {
        fireAndForget(
          rereadNotifiedListsAfterFirstRead(),
          'soup-normalized-cache'
        );
      }
    }
  }
}

/** Lists on screen ordered by `notified_at`, which only REST serves. */
function mountedNotifiedLists() {
  return queryClient
    .getQueryCache()
    .findAll({ queryKey: soupKeys.astItems._def, type: 'active' })
    .filter((query) => JSON.stringify(query.queryKey).includes('notified_at'));
}

/**
 * A list's first read has no pages to insert into, and invalidating reuses it
 * rather than restarting it, so its response can predate a new notification.
 * Read each of those lists again once its own first read settles.
 */
async function rereadNotifiedListsAfterFirstRead(): Promise<void> {
  const firstReads = mountedNotifiedLists().filter(
    (query) =>
      query.state.data === undefined && query.state.fetchStatus === 'fetching'
  );
  await Promise.allSettled(
    firstReads.map(async (query) => {
      await Promise.allSettled([query.promise]);
      queryClient.invalidateQueries({ queryKey: query.queryKey, exact: true });
    })
  );
}

/**
 * `invalidateAllSoup` minus the touched_by_me queries: an own-touch insert
 * must survive in the Recent feed until the activity consumer has recorded
 * the touch, so those pages keep the optimistic row instead of refetching
 * a server list that would drop it.
 */
function invalidateAllSoupExceptTouched(): void {
  const notTouched = (query: Query) =>
    !JSON.stringify(query.queryKey).includes('touched_by_me');
  queryClient.invalidateQueries({
    queryKey: soupKeys.items._def,
    predicate: notTouched,
  });
  queryClient.invalidateQueries({
    queryKey: soupKeys.astItems._def,
    predicate: notTouched,
  });
  queryClient.invalidateQueries({
    queryKey: soupKeys.groupedGroup._def,
    predicate: notTouched,
  });
}

/** @private */
export function buildSingleEntityFilter(
  entityType: SoupEntityTag,
  entityId: string,
  options?: { includeRoot?: boolean }
): PostSoupRequest {
  const base: PostSoupRequest = {
    ...QUERY_FILTERS_BASE,
    limit: 1,
  };
  return match(entityType)
    .with('document', () => ({
      ...base,
      document_filters: { document_ids: [entityId] },
    }))
    .with('chat', () => ({ ...base, chat_filters: { chat_ids: [entityId] } }))
    .with('channel', () => ({
      ...base,
      channel_filters: { channel_ids: [entityId] },
    }))
    .with('project', () => ({
      ...base,
      project_filters: {
        project_ids: [entityId],
        include_root: options?.includeRoot ?? false,
      },
    }))
    .with('emailThread', () => ({
      ...base,
      email_filters: { email_thread_ids: [entityId] },
    }))
    .with('call', () => ({
      ...base,
      call_filters: { call_ids: [entityId] },
    }))
    .with('crmCompany', () => ({
      ...base,
      crm_company_filters: { company_ids: [entityId] },
    }))
    .with('foreignEntity', () => ({
      ...base,
      foreign_entity_filters: { ids: [entityId] },
    }))
    .with('channelThread', () => ({
      ...base,
      channel_thread_filters: { thread_ids: [entityId] },
    }))
    .with('calendarEvent', () => ({
      ...base,
      calendar_event_filters: { calendar_event_ids: [entityId] },
    }))
    .with('initiative', () => ({
      ...base,
      initiative_filters: { initiative_ids: [entityId] },
    }))
    .with('agentSession', () => ({
      ...base,
      agent_session_filters: { ids: [entityId] },
    }))
    .with('databaseRow', () => {
      throw new Error('Database rows are read through GraphQL Soup only');
    })
    .with('crmContact', () => {
      throw new Error('CRM contacts are read through GraphQL Soup only');
    })
    .exhaustive(() => {
      throw new Error(`Unknown soup entity type: ${entityType}`);
    });
}

async function updateRecentlyViewedItemLazily(
  itemId: string,
  viewedAt: string
): Promise<void> {
  // Lazy import to break circular dependency
  const { updateRecentlyViewedItem } = await import('../recently-viewed');
  updateRecentlyViewedItem(itemId, viewedAt);
}

/**
 * Optimistically update the viewedAt timestamp for a soup item.
 * Updates the item across all soup queries if it exists.
 */
export function optimisticUpdateSoupItemViewedAt(itemId: string) {
  const now = new Date().toISOString();

  updateRecentlyViewedItemLazily(itemId, now).catch((error) =>
    Telemetry.error(error, { surface: 'soup-normalized-cache' })
  );

  const current = getSoupEntityById(itemId);
  if (!current) return;

  if (current.tag === 'channel') {
    optimisticUpdateSoupEntity({
      tag: 'channel',
      data: { channel: { id: itemId }, viewed_at: now },
      frecency_score: current.frecency_score,
    });
  } else if (current.tag === 'call' || current.tag === 'foreignEntity') {
    // Call records, foreign entities, and channel threads don't have viewedAt — skip.
    return;
  } else {
    optimisticUpdateSoupEntity({
      tag: current.tag,
      data: { id: itemId, viewedAt: now },
      frecency_score: current.frecency_score,
    });
  }
}

/**
 * Optimistically update the updatedAt/updated_at timestamp for a soup item.
 * Updates the item across all soup queries if it exists and matches the expected tag.
 *
 * Deliberately does NOT stamp `touched_at`: this helper's caller is the
 * incoming-notification path, i.e. *other people's* actions (your own don't
 * notify you). `updated_at` is global recency, `touched_at` is the viewer's
 * own touch — stamping it here would pull entities a teammate mutated into
 * the viewer's Recent feed. Own-mutation flows stamp `touched_at` at their
 * call sites (see `bumpSoupEntityTouchedAt`).
 */
export function optimisticUpdateSoupItemUpdatedAt(
  itemId: string,
  tag: SoupEntityTag,
  updatedAt: string
): SoupTransaction | undefined {
  const current = getSoupEntityById(itemId);
  if (!current || current.tag !== tag) return;

  if (current.tag === 'channel') {
    if (
      !shouldUpdateOptimisticTimestamp(
        current.data.channel.updated_at,
        updatedAt
      )
    )
      return;

    return optimisticUpdateSoupEntity({
      tag: 'channel',
      data: { channel: { id: itemId, updated_at: updatedAt } },
      frecency_score: current.frecency_score,
    });
  } else if (current.tag === 'call') {
    // Call records use endedAt/startedAt and channel threads nest message timestamps — skip.
    return;
  } else {
    const timestamp =
      current.tag === 'channelThread'
        ? current.data.updated_at
        : current.data.updatedAt;

    if (!shouldUpdateOptimisticTimestamp(timestamp, updatedAt)) return;

    return optimisticUpdateSoupEntity({
      tag: current.tag,
      data: { id: itemId, updatedAt },
      frecency_score: current.frecency_score,
    });
  }
}

/** @private */
function shouldUpdateOptimisticTimestamp(
  currentUpdatedAt: string | undefined,
  incomingUpdatedAt: string
): boolean {
  return currentUpdatedAt
    ? isAfter(Date.parse(incomingUpdatedAt), Date.parse(currentUpdatedAt))
    : true;
}

/** @private */
function getSearchResultId(result: UnifiedSearchResponseItem): string {
  return match(result)
    .with({ type: 'document' }, (r) => r.document_id)
    .with({ type: 'chat' }, (r) => r.chat_id)
    .with({ type: 'channel' }, (r) => r.channel_id)
    .with({ type: 'channelMessage' }, (r) => `${r.channel_id}:${r.message_id}`)
    .with({ type: 'email' }, (r) => r.thread_id)
    .with({ type: 'project' }, (r) => r.id)
    .with({ type: 'call' }, (r) => r.call_id)
    .with({ type: 'company' }, (r) => r.id)
    .with({ type: 'calendarEvent' }, (r) => r.id)
    .with({ type: 'agentSession' }, (r) => r.id)
    .exhaustive(() => '');
}

/** @private Captures every soup-list-shaped query (legacy items, parent
 * astItems, per-group caches) for full-range rollback. */
function snapshotSoup(): [QueryKey, unknown][] {
  return [
    ...queryClient.getQueriesData<unknown>({ queryKey: soupKeys.items._def }),
    ...queryClient.getQueriesData<unknown>({
      queryKey: soupKeys.astItems._def,
    }),
    ...queryClient.getQueriesData<unknown>({
      queryKey: soupKeys.groupedGroup._def,
    }),
  ];
}

/** @private */
function restoreSnapshot(snapshot: [QueryKey, unknown][]): void {
  for (const [key, data] of snapshot) {
    queryClient.setQueryData(key, data);
  }
}