Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! Read path: normalized records → response JSON.
//!
//! Pure and synchronous: reads records through a [`RecordSource`] snapshot.
//! When records are absent from the source the walk *continues* and gathers
//! every missing key, so the engine can batch-fetch from storage and retry
//! (see the engine's read loop). A record that exists but lacks a selected
//! field is a cache miss (Phase 1: no partial results — nullability-based
//! partials are a later phase; the metadata is already generated).
use crate::deps::DependencyTracker;
use crate::document::{
FieldNode, MissingVariable, Operation, Selection, resolve_args, resolved_args_key,
};
use crate::entity_resolver::EntityResolverLookup;
use crate::meta;
use crate::value::{CacheValue, EntityKey, Record, field_key};
use serde_json::Value as Json;
use std::borrow::Cow;
use std::collections::BTreeSet;
use thiserror::Error;
mod plan;
mod projection;
pub(crate) use plan::ReadPlans;
use plan::{Field, FieldSource};
pub(crate) use projection::QueryProjection;
/// Synchronous view over records available right now (hot tier + any
/// batch-fetched records).
pub trait RecordSource {
fn get(&self, key: &EntityKey<'static>) -> Option<&Record>;
}
impl RecordSource for std::collections::BTreeMap<EntityKey<'static>, Record> {
fn get(&self, key: &EntityKey<'static>) -> Option<&Record> {
std::collections::BTreeMap::get(self, key)
}
}
impl RecordSource for std::collections::HashMap<EntityKey<'static>, Record> {
fn get(&self, key: &EntityKey<'static>) -> Option<&Record> {
std::collections::HashMap::get(self, key)
}
}
#[derive(Debug, Error)]
pub enum DenormalizeError {
#[error(transparent)]
Document(#[from] crate::document::DocumentError),
#[error(transparent)]
MissingVariable(#[from] MissingVariable),
#[error("unknown field `{type_name}.{field}` (schema drift?)")]
UnknownField { type_name: String, field: String },
#[error("stored value for `{type_name}.{field}` does not match the selection shape")]
Shape { type_name: String, field: String },
}
/// Outcome of a read attempt.
#[derive(Debug)]
pub enum ReadOutcome {
/// All selected data present.
Complete(Json),
/// Some records weren't in the [`RecordSource`]; fetch these and retry.
NeedRecords(BTreeSet<EntityKey<'static>>),
/// A record exists but a selected field was never written → miss.
Miss {
entity: EntityKey<'static>,
field: String,
},
}
/// Attempts to answer `op` from `source`. `deps` accumulates every entity
/// key touched (for dependency tracking), regardless of outcome.
pub fn denormalize(
schema: &crate::meta::Schema,
op: &Operation,
variables: &serde_json::Map<String, Json>,
source: &impl RecordSource,
deps: &mut impl DependencyTracker,
) -> Result<ReadOutcome, DenormalizeError> {
denormalize_with_entity_resolvers(
schema,
op,
variables,
source,
deps,
&EntityResolverLookup::default(),
)
}
/// Attempts to answer `op` while applying validated read-only entity links.
pub fn denormalize_with_entity_resolvers(
schema: &crate::meta::Schema,
op: &Operation,
variables: &serde_json::Map<String, Json>,
source: &impl RecordSource,
deps: &mut impl DependencyTracker,
entity_resolvers: &EntityResolverLookup,
) -> Result<ReadOutcome, DenormalizeError> {
let op = op.prepare(variables)?;
denormalize_record_with_entity_resolvers(
schema,
&EntityKey::root(),
schema.query_root(),
&op.selection_set,
variables,
source,
deps,
entity_resolvers,
)
}
/// Projects one normalized record through a fragment selection.
pub fn denormalize_record(
schema: &crate::meta::Schema,
key: &EntityKey<'static>,
type_name: &str,
selections: &[Selection],
variables: &serde_json::Map<String, Json>,
source: &impl RecordSource,
deps: &mut impl DependencyTracker,
) -> Result<ReadOutcome, DenormalizeError> {
denormalize_record_with_entity_resolvers(
schema,
key,
type_name,
selections,
variables,
source,
deps,
&EntityResolverLookup::default(),
)
}
#[expect(
clippy::too_many_arguments,
reason = "explicit schema and read dependencies"
)]
fn denormalize_record_with_entity_resolvers(
schema: &crate::meta::Schema,
key: &EntityKey<'static>,
type_name: &str,
selections: &[Selection],
variables: &serde_json::Map<String, Json>,
source: &impl RecordSource,
deps: &mut impl DependencyTracker,
entity_resolvers: &EntityResolverLookup,
) -> Result<ReadOutcome, DenormalizeError> {
ReadSession::new(schema, key, type_name, selections).resume(
variables,
source,
deps,
entity_resolvers,
&mut ReadPlans::default(),
)
}
/// A response under construction. Only absent record branches are suspended;
/// completed fields and list positions survive storage hydration rounds.
/// The source must remain an immutable logical snapshot until completion.
pub(crate) struct ReadSession<'a> {
schema: &'a crate::meta::Schema,
data: Json,
pub(crate) projection: Option<QueryProjection>,
pending: Vec<PendingRecord<'a>>,
deleted_items: BTreeSet<Vec<ResponsePath<'a>>>,
miss: Option<(EntityKey<'static>, String)>,
}
#[derive(Clone, PartialEq, Eq, PartialOrd, Ord)]
enum ResponsePath<'a> {
Field(&'a str),
Index(usize),
}
#[derive(Clone, Copy)]
enum DeletedRecord {
Miss,
Null,
Omit,
}
struct PendingRecord<'a> {
deleted: DeletedRecord,
aliases: Vec<EntityKey<'static>>,
key: EntityKey<'static>,
type_name: &'a str,
selections: &'a [Selection],
// An overwritten duplicate field still contributes dependencies and misses,
// but must never replace the later field's output when it finishes.
destination: Option<Vec<ResponsePath<'a>>>,
}
impl<'a> ReadSession<'a> {
pub(crate) fn new(
schema: &'a crate::meta::Schema,
key: &EntityKey<'static>,
type_name: &'a str,
selections: &'a [Selection],
) -> Self {
Self {
schema,
data: Json::Null,
projection: None,
pending: vec![PendingRecord {
key: key.clone(),
type_name,
selections,
destination: Some(Vec::new()),
deleted: DeletedRecord::Miss,
aliases: Vec::new(),
}],
deleted_items: BTreeSet::new(),
miss: None,
}
}
pub(crate) fn resume(
&mut self,
variables: &serde_json::Map<String, Json>,
source: &impl RecordSource,
deps: &mut impl DependencyTracker,
entity_resolvers: &EntityResolverLookup,
plans: &mut ReadPlans<'a>,
) -> Result<ReadOutcome, DenormalizeError> {
for pending in std::mem::take(&mut self.pending) {
let retain_output = pending.destination.is_some();
let mut walk = Walk {
schema: self.schema,
variables,
source,
deps,
entity_resolvers,
plans,
pending: &mut self.pending,
deleted_items: &mut self.deleted_items,
miss: &mut self.miss,
path: pending.destination.unwrap_or_default(),
retain_output,
projection: &mut self.projection,
};
let data = walk.read_record(
&pending.key,
pending.type_name,
pending.selections,
pending.deleted,
pending.aliases,
)?;
if retain_output {
let mut slot = &mut self.data;
for segment in walk.path {
slot = match segment {
ResponsePath::Field(field) => slot.get_mut(field),
ResponsePath::Index(index) => slot.get_mut(index),
}
.expect("suspended response slot remains present");
}
merge_response(slot, data);
}
}
if !self.pending.is_empty() {
return Ok(ReadOutcome::NeedRecords(
self.pending
.iter()
.map(|pending| pending.key.clone())
.collect(),
));
}
if let Some((entity, field)) = self.miss.take() {
return Ok(ReadOutcome::Miss { entity, field });
}
// Keep array positions stable until every suspended branch has finished.
// Remove later indices and deeper paths first so earlier paths stay valid.
// Compaction moves response indices; bindings move with them.
if let Some(projection) = self.projection.as_mut() {
projection.compact(&self.deleted_items);
projection.finish();
}
for path in std::mem::take(&mut self.deleted_items).into_iter().rev() {
let Some((ResponsePath::Index(index), parent)) = path.split_last() else {
continue;
};
let mut slot = &mut self.data;
for segment in parent {
slot = match segment {
ResponsePath::Field(field) => slot.get_mut(*field),
ResponsePath::Index(index) => slot.get_mut(*index),
}
.expect("deleted response slot remains present");
}
slot.as_array_mut()
.expect("deleted list item")
.remove(*index);
}
Ok(ReadOutcome::Complete(self.data.take()))
}
}
struct Walk<'a, 'document, S: RecordSource, D: DependencyTracker> {
schema: &'document crate::meta::Schema,
variables: &'a serde_json::Map<String, Json>,
source: &'a S,
deps: &'a mut D,
entity_resolvers: &'a EntityResolverLookup,
plans: &'a mut ReadPlans<'document>,
pending: &'a mut Vec<PendingRecord<'document>>,
deleted_items: &'a mut BTreeSet<Vec<ResponsePath<'document>>>,
miss: &'a mut Option<(EntityKey<'static>, String)>,
path: Vec<ResponsePath<'document>>,
retain_output: bool,
projection: &'a mut Option<QueryProjection>,
}
impl<'document, S: RecordSource, D: DependencyTracker> Walk<'_, 'document, S, D> {
fn read_record(
&mut self,
key: &EntityKey<'static>,
type_name: &'document str,
selections: &'document [Selection],
deleted: DeletedRecord,
mut aliases: Vec<EntityKey<'static>>,
) -> Result<Json, DenormalizeError> {
let mut key = key.clone();
let record = loop {
self.deps.record(&key);
if aliases.contains(&key) || aliases.len() >= crate::identity::MAX_ALIAS_CHAIN_DEPTH {
self.mark_miss(&key, "cyclic cache identity".into());
return Ok(Json::Null);
}
let Some(record) = self.source.get(&key) else {
self.pending.push(PendingRecord {
key,
type_name,
selections,
deleted,
aliases,
destination: self.retain_output.then(|| self.path.clone()),
});
return Ok(Json::Null);
};
if let Some(projection) = self.projection.as_mut() {
projection.record(&key, record);
}
if let Some(target) = crate::identity::alias_target(record) {
aliases.push(key);
key = target.clone();
continue;
}
break record;
};
if record.fields.get(crate::identity::DELETED_FIELD) == Some(&CacheValue::Bool(true)) {
match deleted {
DeletedRecord::Miss => self.mark_miss(&key, "deleted cache identity".into()),
DeletedRecord::Omit if self.retain_output => {
self.deleted_items.insert(self.path.clone());
}
_ => {}
}
return Ok(Json::Null);
}
let concrete = record.typename().unwrap_or(type_name);
self.deps.field(&key, concrete, "__typename");
self.read_fields(&key, &record.fields, concrete, selections, true)
}
fn read_fields(
&mut self,
owner: &EntityKey<'static>,
fields: &std::collections::BTreeMap<String, CacheValue>,
concrete: &str,
selections: &'document [Selection],
normalized: bool,
) -> Result<Json, DenormalizeError> {
let fields_plan = self.plans.fields(
self.schema,
selections,
concrete,
self.variables,
self.entity_resolvers,
)?;
let mut out = serde_json::Map::new();
for planned_field in fields_plan.iter() {
let field = planned_field.node;
self.path.push(ResponsePath::Field(&field.response_key));
if normalized
&& self.retain_output
&& let Some(projection) = self.projection.as_mut()
{
match &planned_field.source {
FieldSource::Stored { key, ty } => {
let value = fields.get(key.as_ref());
let selection = projection.compile_value(
self.schema,
value,
field,
ty,
self.variables,
self.entity_resolvers,
self.plans,
)?;
projection.selected_field(owner, key, value, &self.path, selection);
}
FieldSource::Entity { storage_key, .. } | FieldSource::Missing(storage_key) => {
projection.guard(owner, storage_key, fields.get(storage_key.as_ref()))
}
_ => {}
}
}
let value = self.read_field(owner, fields, concrete, planned_field)?;
self.path.pop();
if let Some(value) = value {
merge_response(
out.entry(field.response_key.clone()).or_insert(Json::Null),
value,
);
}
}
Ok(Json::Object(out))
}
fn read_field(
&mut self,
owner: &EntityKey<'static>,
fields: &std::collections::BTreeMap<String, CacheValue>,
concrete: &str,
field: &Field<'document>,
) -> Result<Option<Json>, DenormalizeError> {
match &field.source {
FieldSource::Typename => Ok(Some(Json::String(concrete.to_owned()))),
FieldSource::MissingArguments => {
self.mark_miss(owner, field.node.name.clone());
Ok(None)
}
FieldSource::Missing(key) => {
self.deps.field(owner, concrete, key);
if matches!(fields.get(key.as_ref()), Some(CacheValue::Null)) {
return Ok(Some(Json::Null));
}
self.mark_miss(owner, key.to_string());
Ok(None)
}
FieldSource::Entity {
key,
ty,
storage_key,
} => {
self.deps.field(owner, concrete, storage_key);
// A server-observed null wins over an argument-derived relation.
if matches!(fields.get(storage_key.as_ref()), Some(CacheValue::Null)) {
return Ok(Some(Json::Null));
}
self.read_value(owner, field.node, ty, &CacheValue::Ref(key.clone()))
.map(Some)
}
FieldSource::Stored { key, ty } => {
self.deps.field(owner, concrete, key);
let Some(value) = fields.get(key.as_ref()) else {
self.mark_miss(owner, key.to_string());
return Ok(None);
};
self.read_value(owner, field.node, ty, value).map(Some)
}
}
}
fn mark_miss(&mut self, owner: &EntityKey<'static>, field: String) {
if self.miss.is_none() {
*self.miss = Some((owner.clone(), field));
}
}
fn read_value(
&mut self,
owner: &EntityKey<'static>,
field: &'document FieldNode,
ty: &meta::FieldType<'document>,
value: &CacheValue,
) -> Result<Json, DenormalizeError> {
Ok(match value {
CacheValue::Null => Json::Null,
CacheValue::Bool(value) => Json::Bool(*value),
CacheValue::Number(value) => Json::Number(value.to_json()),
CacheValue::String(value) => Json::String(value.clone()),
CacheValue::Opaque(value) => {
serde_json::from_str(value).map_err(|_| DenormalizeError::Shape {
type_name: ty.name.to_string(),
field: field.name.clone(),
})?
}
CacheValue::List(items) => {
let mut out = Vec::with_capacity(items.len());
for (index, item) in items.iter().enumerate() {
self.path.push(ResponsePath::Index(index));
out.push(self.read_value(owner, field, ty, item)?);
self.path.pop();
}
Json::Array(out)
}
CacheValue::Ref(key) => self.read_record(
key,
ty.name,
&field.selection_set,
if ty.list {
DeletedRecord::Omit
} else if ty.nullable {
DeletedRecord::Null
} else {
DeletedRecord::Miss
},
Vec::new(),
)?,
CacheValue::Object(map) => {
let concrete = match map.get("__typename") {
Some(CacheValue::String(typename)) => typename.as_str(),
_ => ty.name,
};
self.read_fields(owner, map, concrete, &field.selection_set, false)?
}
})
}
}
// GraphQL merges repeated response keys, including selections contributed by
// different fragments and records that finish in different hydration rounds.
fn merge_response(target: &mut Json, value: Json) {
match (target, value) {
(Json::Object(target), Json::Object(values)) => {
for (key, value) in values {
merge_response(target.entry(key).or_insert(Json::Null), value);
}
}
(Json::Array(target), Json::Array(values)) if target.len() == values.len() => {
for (target, value) in target.iter_mut().zip(values) {
merge_response(target, value);
}
}
(target, value) => *target = value,
}
}
fn collect_fields<'a>(
schema: &crate::meta::Schema,
selections: &'a [Selection],
concrete_type: &str,
out: &mut Vec<&'a FieldNode>,
) {
for sel in selections {
match sel {
Selection::Field(f) => out.push(f),
Selection::Fragment {
type_condition,
selection_set,
..
} => {
let applies = match type_condition {
None => true,
Some(cond) => schema.type_matches(concrete_type, cond),
};
if applies {
collect_fields(schema, selection_set, concrete_type, out);
}
}
}
}
}
#[cfg(test)]
mod test;