Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
graphql_soup
What it is
Backs the Soup feature (the app's unified entity search/home surface): the
soup-domain GraphQL wrapper types. The composed schema (root query, viewer,
SDL export) lives in complete_graph — see ../complete_graph/AGENTS.md for
the schema conventions (presence-of-id normalized-cache rules and the
viewer pattern), which apply to every type defined here.
Gotchas
PROJECTgrouping forwards the Project property (initiative membership) to Soup; legacy folder IDs are not grouping keys.SoupItemLoader(single-entity lookups,soupUpdateshydration) resolves email threads through entity-access view receipts, the rule the REST thread route applies, not through the viewer's inbox scope; Soup's email leg only serves lists. A thread shared through a team's CRM, a project, or a share therefore opens throughemailThreadeven though it lives in a teammate's inbox.Build
AgentSessionEntityLoaderandPrimarySoupItemLoaderwith::new, which rechecks the viewer's team. PRs are stored for the team; without it, a session row readspullRequestState: nulland overwrites the list's state in the client cache.Property grouping accepts optional
groupBy.bucketingwithtype: DATE_RANGES, caller-defined half-open UTCranges, andmissingValueBucketKey; client query keys restart pagination when ranges change.Use
PROPERTY,sortPropertyDefinitionId, andsortDirectionfor numeric property sorting through ordinary Soup requests; preserve timestamp cursor decoding.Property sorts and date-range groups use source-owned item access gates without a separate property-definition check; validate ranges during input conversion.
Build
groupSoupthrough Soup's sharedbuild_grouped_response; keepdocument_server_factsinGroupedSoup::from_responsefor cache projections.NOTIFIED_ATmaps to Soup's notified request, not a simple sort:soupaccepts it descending only andgroupSouprejects it. Its continuation cursors carry their own sort tag and string identifiers, separate from timestamp and selected-property cursors.External chats are intentionally excluded from Soup hydration; use the
/external-chatsAPI.