Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
cache-core
What it is
Part of the web client's shared infrastructure: the normalized GraphQL
cache engine — pure, native-tested core shared by every storage backend and
host (web, Tauri). Design doc:
apps/web/docs/graphql-normalized-cache-plan.md.
How it works
GraphQL responses are normalized into keyed records (normalize.rs);
watched queries and the optimistic mutation queue read/write those records
through the predicate/projection IR; results are denormalized back into
GraphQL response shape for callers. A concrete Storage impl (e.g.
cache-turso) persists the records.
Start here
src/engine.rs: theCacheEngine— the crate's entry point, owns queued mutations, watched queries, and optimistic resolution.src/engine/window_observation.rs: bounded immutable predicate-window proofs over the complete change journal, selected dependencies and catalog input fields; unknown evidence never suppresses invalidation.src/normalize.rs/src/denormalize.rs: GraphQL response ↔ normalized record transforms.src/store.rs: theStoragetrait every backend (e.g.cache-turso) implements.src/predicate.rs+src/record_selection.rs: the predicate/projection IR used to select which cached records satisfy a query.src/search.rs: disposable Quick Access projection (version 4); email matches subjects and all embedded senders, never snippets or bodies; task projects (GraphqlSoupInitiative) index their display name with recency frommetadata; whitespace and commas separate query tokens, as in the server's channel name search, and each token matches independently, so any order works.src/queue.rs: the optimistic mutation queue.tests/: the primary spec for engine behavior — one file per concern (optimistic updates, calendar range, search, subscriptions, fuzz).
Scope
- Owns: normalization, denormalization, optimistic mutation resolution, watched queries, and the storage-agnostic predicate/projection IR.
- Not here: a concrete storage backend →
crates/client/cache-turso; the wasm host shell →crates/client/cache-wasm; Soup-specific projection policy →soup_filter_cache_adapter,soup_filter_projection.
Boundaries
- Depends on:
apollo-compiler/apollo-parser(GraphQL parsing),predicate-index,maybe_send. - Used by:
cache-turso,cache-wasm.
Recipes
- Add a new mutation's optimistic resolver:
src/engine.rs(resolver registration) → a newtests/<name>_optimistic.rsfirst (see the existing*_optimistic.rstests). - Change what a query can select:
src/predicate.rs→src/record_selection.rs→src/query_inspection.rs.
Live views retain at most 32 validated specifications. A registration token
identifies one retained specification, not the caller's reusable view id.
resume_live_query hydrates durable optimistic state before token lookup;
the engine owner serializes token lookup and the read. Replacement, release,
eviction and reset make it miss. A miss requires full registration and never reuses another specification.
Checks
cargo test -p cache-core(SQLX_OFFLINEunset).
Gotchas
Email send persistence and cancellation belong to the frontend email journal, not the normalized cache or its mutation queue.
Opaque JSON scalars must preserve floating-point values on reparse —
serde_jsonis pulled in with thefloat_roundtripfeature; don't drop it.StoredMutation.created_at_msis the first-enqueue time hosts report asenqueuedAtMs: a row replacing an unsent row for the same UUID inherits the earlier time. Lease and backoff checks takenow_msseparately; never readcreated_at_msas the current time.Patches structural query changes in place instead of resending full results (#7825); a new query shape change needs a patch path, not just a resend.
Related
- Docs:
apps/web/docs/graphql-normalized-cache-plan.md