Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
complete_graph — schema conventions
What it is
Part of the web client's shared infrastructure: this crate composes the
domain GraphQL adapter crates (graphql_soup, graphql_properties,
graphql_notification, graphql_email, graphql_entity_mutation,
graphql_work_feed, graphql_notification_inbox, graphql_registered_work,
with shared plumbing in
graphql_common) into the complete GraphQL schema
consumed by the client's normalized cache (crates/client, design doc:
apps/web/docs/graphql-normalized-cache-plan.md). The conventions below are
load-bearing for cache correctness and API consistency. The cache's build
validates shapes but cannot validate semantics — that's what schema
review is for.
1. id is a reserved, semantic field name (presence-of-id convention)
Clients key cache records by __typename:id. Consequences:
- An output object type with an
id: ID!field is a normalized entity. Two responses containing the same__typename:idpair are merged into one record — soidmust identify the same logical value everywhere it can appear, across all queries, arguments, and parent objects. - Only name a field
idwhen it is the object's global identity. If a type carries a reference to something else's id, name it accordingly:GraphqlProperty.idis the globally unique entity-property assignment id.propertyDefinitionIdremains separate because definitions are shared while assignment values are per-entity.GraphqlSoupChannelMessage.id(renamed frommessageId) — it is the message's identity, so it uses the reserved name.
- Types without an
idfield are embedded inline in their parent record (SoupPage, participants, property values,DocumentSubType). This is correct for value objects and query-scoped wrappers. Do not add constant or synthetic ids to such types — a constant id (e.g."soup_page") would merge every instance into a single record globally. A type without anidmay only carry fields that are facts about the edge it represents, never facts about an entity — entity facts belong on the entity record where every view shares them. Soup pages therefore return entities directly (there is no per-item wrapper type), and per-view state is limited to list membership and order. A value derived per view (the Soup email thread'ssortTs, which depends on the query'semailView) is not an entity fact either: clients must not select it into the shared record, because the last view to fetch the thread would win. Expose the facts it derives from (latestInboundMessageTs,reminderReturnedAt,latestOutboundMessageTs,latestNonSpamMessageTs) and let each view recompute its key. idfields must be exactlyID!(non-null, non-list); the cache build (crates/client/cache-core/build.rs) fails otherwise, and fails if the query root exposes anid.
Review checklist when adding/changing a type:
- Does it have a stable global identity? → expose it as
id: ID!. - Is its content dependent on where it appears (parent entity, arguments)?
→ no
idfield; expose reference ids under descriptive names. - Renaming/removing an
idfield changes client caching semantics — it rotates cache keys and turns entities into embedded values (or vice versa). Deliberate, but call it out in review.
2. QueryRoot → user (viewer pattern) is the identity witness
All user-scoped data hangs off user: GraphqlUser!, and GraphqlUser.id
must be the authenticated user's id from the request context. The
client extracts it from every response and passes it to the cache as a
session tag: a response for a different user than the one bound to the
cache triggers a full wipe-and-rebind (cross-user leak protection on
account switches).
- Never resolve
GraphqlUser.idfrom anything other than the authenticated request context. - New user-scoped root data should be added under
GraphqlUser, not as new root fields.
3. GraphqlSoupEntity owns the shared entity contract
Every field implemented by all concrete Soup entity types belongs on the
GraphqlSoupEntity interface. Today that contract is id, entityType,
displayName, metadata, properties, notifications, isFavorited, and
viewerPermission.
content is deliberately not part of the interface. Content has different
domain shapes and loading policies across documents, email threads, channels,
messages, calls, and future entity types. Define it on the concrete entity or a
domain-specific composed edge, with the type that domain actually owns.
The interface is the public API contract; Rust crate ownership must not leak
into it. Cross-domain resolvers remain composed by SoupEdges in this crate,
while graphql_soup's SoupEntityEdges trait declares their associated output
types and resolver contract. Adding a field to all concrete entity types
therefore also requires adding it to the interface and its SDL contract test.
Expensive fields remain lazy because GraphQL only invokes resolvers selected by
a query.
4. Soup patches contain hydrated updates or explicit deletions
SoupUpdated.item is non-nullable. Use SoupPatch::hydrate_updated for updated
entities and SoupPatch::deleted for explicit deletions. The subscription adapter
coalesces realtime patches by entity type and ID (last operation wins), preserving
last-occurrence order. Mutation adapters map their own domain effects directly;
they must not depend on realtime patch types. Poll hydration futures concurrently
so the DataLoader can batch them. Missing items are logged and omitted, never inferred
to be deleted. Hydration service errors remain GraphQL errors. Do not reintroduce
lazy nullable item lookup inside the update.
Regenerating the SDL
After schema changes:
cargo run -p complete_graph --bin graphql_schema -- static_assets/schema.graphql # from repo root
The exported static_assets/schema.graphql feeds both the client codegen
(apps/web && bun gen-graphql) and the cache metadata codegen. Additive changes
keep persisted client caches; a change that makes stored records unsafe needs a
bump of CACHE_SCHEMA_COMPATIBILITY_EPOCH in crates/client/cache-core/src/codec.rs.
Email send admission, cancellation and status are exposed by graphql_email;
GraphqlUser.pendingEmailSends lists authorized inbox attempts with cursor pagination.
Keep this viewer-scoped listing independent of normalized-cache initialization.
Never remove or narrow anything deployed clients send without a dated
deprecation (Remove after YYYY-MM-DD, at least 30 days out).
cargo x graphql-schema-compat checks the SDL against origin/main, and CI runs
it; see step 8 of the field guide.
Saved-view definitions live under authenticated GraphqlUser; mutations use the authenticated request user and a domain service from request data. Run cargo test -p complete_graph --lib saved_view_contract after changing the saved-view contract.
- Mail capsule negotiation lives in
mail_cache_profile: absent/unknown capabilities receive v2; explicitsoup-mail-v5receives current capsules. Never infer client support from the server version.