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
//! Typed-query cache inspection primitives.
//!
//! Inspection discovers argument-qualified instances of one selected field
//! without exposing normalized entity or field keys to host callers.
use crate::document::{ArgValue, FieldNode, Operation, OperationKind, Selection, resolve_args_key};
use crate::meta::FieldKind;
use crate::query_path::{
possible_selected_fields, selected_field, selected_storage_key, selected_type,
};
use crate::value::{CacheValue, EntityKey, Record, canonical_json};
use serde::Serialize;
use serde_json::Value as Json;
use std::collections::{BTreeMap, BTreeSet, HashMap};
use thiserror::Error;
#[cfg(test)]
mod test;
/// Maximum field-only path depth accepted by query inspection.
pub const MAX_INSPECTION_PATH_DEPTH: usize = 16;
/// Maximum cached argument variants returned by one inspection.
pub const MAX_INSPECTED_VARIANTS: usize = 128;
/// A generated query and selected response-key path to inspect.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct QueryInspection {
/// Serialized GraphQL operation document.
pub query: String,
/// Selected operation for multi-operation documents.
pub operation_name: Option<String>,
/// Field-only response-key path beginning at the query root.
pub path: Vec<String>,
/// Recursive partial-variable filters. A variant is materialized when it
/// matches any filter; an empty list materializes every cached variant.
pub variable_filters: Vec<serde_json::Map<String, Json>>,
}
/// One cached argument variant reconstructed as generated query variables.
#[derive(Debug, Clone, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct CachedQueryVariant {
/// Variables recovered from the selected field's normalized arguments.
pub variables: serde_json::Map<String, Json>,
}
/// One materialized cached argument variant.
#[derive(Debug, Clone, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct CachedQueryInstance {
/// Variables recovered from the selected field's normalized arguments.
pub variables: serde_json::Map<String, Json>,
/// Selected value in the effective cache view. Absent on a query miss.
#[serde(skip_serializing_if = "Option::is_none")]
pub value: Option<Json>,
}
/// Validation or traversal failure for query inspection.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum QueryInspectionError {
/// The selected operation is not a query.
#[error("query inspection entrypoint must be a query")]
NotQuery,
/// The path is empty or exceeds the defensive limit.
#[error("invalid query inspection path depth {0}")]
InvalidDepth(usize),
/// A response key is not selected at the current schema type.
#[error("query does not select `{field}` on `{type_name}`")]
UnselectedField { type_name: String, field: String },
/// More than one selected field can supply a response key.
#[error("query inspection path `{field}` is ambiguous on `{type_name}`")]
AmbiguousField { type_name: String, field: String },
/// A prefix path field depends on operation variables.
#[error("query inspection prefix field `{0}` contains an unbound variable")]
VariablePrefix(String),
/// An operation variable cannot be recovered from the final field.
#[error("operation variable `{0}` cannot be recovered from the inspected field")]
UnrecoverableVariable(String),
/// The final selected field is not an object-valued field.
#[error("query inspection final field must select an object value")]
NonCompositeFinalField,
/// A path field cannot be traversed as an object.
#[error("query inspection path encountered an incompatible cache value")]
WrongShape,
/// The selected field owner has too many cached argument variants.
#[error("query inspection variant count {actual} exceeds limit {maximum}")]
TooManyVariants { actual: usize, maximum: usize },
/// A complete query result unexpectedly lacks the validated path.
#[error("complete query result does not contain the inspected path")]
MissingResultPath,
}
/// Validated information needed to enumerate an inspection.
pub(crate) struct PreparedInspection {
required_variables: BTreeSet<String>,
}
/// The effective owner record and final selected field.
pub(crate) struct InspectionOwner<'records, 'selection> {
pub fields: &'records BTreeMap<String, CacheValue>,
pub field: &'selection FieldNode,
}
/// Result of resolving the owner through currently loaded effective records.
pub(crate) enum OwnerResolution<'records, 'selection> {
Owner(InspectionOwner<'records, 'selection>),
NeedRecord(EntityKey<'records>),
Absent,
}
/// Validates the query-rooted path and variable recoverability constraints.
pub(crate) fn prepare(
schema: &crate::meta::Schema,
operation: &Operation,
path: &[String],
) -> Result<PreparedInspection, QueryInspectionError> {
if operation.kind != OperationKind::Query {
return Err(QueryInspectionError::NotQuery);
}
if path.is_empty() || path.len() > MAX_INSPECTION_PATH_DEPTH {
return Err(QueryInspectionError::InvalidDepth(path.len()));
}
let mut selections = operation.selection_set.as_slice();
let mut type_name = schema.query_root();
let mut final_variables = BTreeSet::new();
for (index, response_key) in path.iter().enumerate() {
let mut fields = Vec::new();
possible_selected_fields(schema, selections, type_name, response_key, &mut fields);
let field = match fields.as_slice() {
[] => {
return Err(QueryInspectionError::UnselectedField {
type_name: type_name.to_string(),
field: response_key.clone(),
});
}
[field] => *field,
_ => {
return Err(QueryInspectionError::AmbiguousField {
type_name: type_name.to_string(),
field: response_key.clone(),
});
}
};
let mut variables = BTreeSet::new();
collect_field_variables(field, &mut variables);
if index + 1 == path.len() {
final_variables = variables;
} else if !variables.is_empty() {
return Err(QueryInspectionError::VariablePrefix(response_key.clone()));
}
let Some(metadata) = schema.field_meta(type_name, &field.name) else {
return Err(QueryInspectionError::UnselectedField {
type_name: type_name.to_string(),
field: response_key.clone(),
});
};
if metadata.ty.kind != FieldKind::Composite {
return if index + 1 == path.len() {
Err(QueryInspectionError::NonCompositeFinalField)
} else {
Err(QueryInspectionError::WrongShape)
};
}
type_name = metadata.ty.name;
selections = &field.selection_set;
}
let mut required_variables = BTreeSet::new();
collect_selection_variables(&operation.selection_set, &mut required_variables);
if let Some(variable) = required_variables
.iter()
.find(|variable| !final_variables.contains(*variable))
{
return Err(QueryInspectionError::UnrecoverableVariable(
variable.clone(),
));
}
Ok(PreparedInspection { required_variables })
}
/// Resolves the record/object that owns the final selected field.
pub(crate) fn resolve_owner<'records, 'selection>(
schema: &crate::meta::Schema,
records: &'records HashMap<EntityKey<'static>, Record>,
operation: &'selection Operation,
path: &[String],
) -> Result<OwnerResolution<'records, 'selection>, QueryInspectionError> {
resolve_record_owner(
schema,
records,
EntityKey::root(),
schema.query_root(),
&operation.selection_set,
path,
)
}
fn resolve_record_owner<'records, 'selection>(
schema: &crate::meta::Schema,
records: &'records HashMap<EntityKey<'static>, Record>,
key: EntityKey<'records>,
declared_type: &str,
selections: &'selection [Selection],
path: &[String],
) -> Result<OwnerResolution<'records, 'selection>, QueryInspectionError> {
let Some(record) = records.get(&key) else {
return Ok(OwnerResolution::NeedRecord(key));
};
let concrete = record.typename().unwrap_or(declared_type);
resolve_fields_owner(schema, records, &record.fields, concrete, selections, path)
}
fn resolve_fields_owner<'records, 'selection>(
schema: &crate::meta::Schema,
records: &'records HashMap<EntityKey<'static>, Record>,
fields: &'records BTreeMap<String, CacheValue>,
concrete: &str,
selections: &'selection [Selection],
path: &[String],
) -> Result<OwnerResolution<'records, 'selection>, QueryInspectionError> {
let response_key = &path[0];
let Some(field) = selected_field(schema, selections, concrete, response_key) else {
return Ok(OwnerResolution::Absent);
};
if path.len() == 1 {
return Ok(OwnerResolution::Owner(InspectionOwner { fields, field }));
}
let storage_key = selected_storage_key(field, &serde_json::Map::new())
.map_err(|_| QueryInspectionError::VariablePrefix(response_key.clone()))?;
let Some(value) = fields.get(&storage_key) else {
return Ok(OwnerResolution::Absent);
};
let next_type = selected_type(schema, concrete, field).ok_or_else(|| {
QueryInspectionError::UnselectedField {
type_name: concrete.to_string(),
field: response_key.clone(),
}
})?;
match value {
CacheValue::Ref(key) => resolve_record_owner(
schema,
records,
key.borrowed(),
next_type,
&field.selection_set,
&path[1..],
),
CacheValue::Object(object) => {
let concrete = object
.get("__typename")
.and_then(|value| match value {
CacheValue::String(value) => Some(value.as_str()),
_ => None,
})
.unwrap_or(next_type);
resolve_fields_owner(
schema,
records,
object,
concrete,
&field.selection_set,
&path[1..],
)
}
CacheValue::Null => Ok(OwnerResolution::Absent),
_ => Err(QueryInspectionError::WrongShape),
}
}
/// Recovers and canonically deduplicates variables from matching owner fields.
pub(crate) fn recover_variants(
owner: &InspectionOwner<'_, '_>,
prepared: &PreparedInspection,
) -> Result<Vec<serde_json::Map<String, Json>>, QueryInspectionError> {
let mut matching = 0usize;
let mut unique = BTreeMap::new();
for storage_key in owner.fields.keys() {
let Some(stored_arguments) = parse_stored_arguments(storage_key, &owner.field.name) else {
continue;
};
matching += 1;
if matching > MAX_INSPECTED_VARIANTS {
return Err(QueryInspectionError::TooManyVariants {
actual: matching,
maximum: MAX_INSPECTED_VARIANTS,
});
}
let Some(variables) = invert_arguments(owner.field, &stored_arguments) else {
continue;
};
if prepared
.required_variables
.iter()
.any(|variable| !variables.contains_key(variable))
{
continue;
}
let key = canonical_json(&Json::Object(variables.clone()));
unique.entry(key).or_insert(variables);
}
Ok(unique.into_values().collect())
}
/// Returns whether one recovered variable set should be materialized.
///
/// Filter objects use recursive partial-object matching and OR semantics. A
/// scalar or array leaf must equal the cached value exactly.
pub(crate) fn matches_variable_filters(
variables: &serde_json::Map<String, Json>,
filters: &[serde_json::Map<String, Json>],
) -> bool {
filters.is_empty()
|| filters
.iter()
.any(|filter| partial_object_match(variables, filter))
}
fn partial_object_match(
value: &serde_json::Map<String, Json>,
filter: &serde_json::Map<String, Json>,
) -> bool {
filter.iter().all(|(key, expected)| {
value
.get(key)
.is_some_and(|actual| partial_json_match(actual, expected))
})
}
fn partial_json_match(actual: &Json, expected: &Json) -> bool {
match (actual, expected) {
(Json::Object(actual), Json::Object(expected)) => partial_object_match(actual, expected),
_ => actual == expected,
}
}
fn parse_stored_arguments(
storage_key: &str,
field_name: &str,
) -> Option<serde_json::Map<String, Json>> {
if storage_key == field_name {
return Some(serde_json::Map::new());
}
let encoded = storage_key
.strip_prefix(field_name)?
.strip_prefix('(')?
.strip_suffix(')')?;
let Json::Object(arguments) = serde_json::from_str(encoded).ok()? else {
return None;
};
Some(arguments)
}
fn invert_arguments(
field: &FieldNode,
stored: &serde_json::Map<String, Json>,
) -> Option<serde_json::Map<String, Json>> {
if stored.len() != field.arguments.len() {
return None;
}
let mut variables = serde_json::Map::new();
for (name, expression) in &field.arguments {
bind_expression(expression, stored.get(name)?, &mut variables)?;
}
let resolved = resolve_args_key(field, &variables).ok()?;
let resolved = resolved
.as_deref()
.map(|arguments| format!("{}({arguments})", field.name))
.unwrap_or_else(|| field.name.clone());
let stored_key = if stored.is_empty() {
field.name.clone()
} else {
format!(
"{}({})",
field.name,
canonical_json(&Json::Object(stored.clone()))
)
};
(resolved == stored_key).then_some(variables)
}
fn bind_expression(
expression: &ArgValue,
stored: &Json,
variables: &mut serde_json::Map<String, Json>,
) -> Option<()> {
match expression {
ArgValue::Const(expected) => (expected == stored).then_some(()),
ArgValue::Variable(name) => match variables.get(name) {
Some(bound) => (bound == stored).then_some(()),
None => {
variables.insert(name.clone(), stored.clone());
Some(())
}
},
ArgValue::List(expressions) => {
let Json::Array(stored) = stored else {
return None;
};
if expressions.len() != stored.len() {
return None;
}
for (expression, stored) in expressions.iter().zip(stored) {
bind_expression(expression, stored, variables)?;
}
Some(())
}
ArgValue::Object(expressions) => {
let Json::Object(stored) = stored else {
return None;
};
if expressions.len() != stored.len() {
return None;
}
for (name, expression) in expressions {
bind_expression(expression, stored.get(name)?, variables)?;
}
Some(())
}
}
}
fn collect_selection_variables(selections: &[Selection], out: &mut BTreeSet<String>) {
for selection in selections {
match selection {
Selection::Field(field) => {
collect_field_variables(field, out);
collect_selection_variables(&field.selection_set, out);
}
Selection::Fragment { selection_set, .. } => {
collect_selection_variables(selection_set, out);
}
}
}
}
fn collect_field_variables(field: &FieldNode, out: &mut BTreeSet<String>) {
for (_, value) in &field.arguments {
collect_arg_variables(value, out);
}
}
fn collect_arg_variables(value: &ArgValue, out: &mut BTreeSet<String>) {
match value {
ArgValue::Variable(name) => {
out.insert(name.clone());
}
ArgValue::List(values) => {
for value in values {
collect_arg_variables(value, out);
}
}
ArgValue::Object(fields) => {
for (_, value) in fields {
collect_arg_variables(value, out);
}
}
ArgValue::Const(_) => {}
}
}
/// Extracts the selected value from one complete denormalized query result.
pub(crate) fn selected_result_value(
data: &Json,
path: &[String],
) -> Result<Json, QueryInspectionError> {
let mut current = data;
for field in path {
let Json::Object(object) = current else {
return Err(QueryInspectionError::MissingResultPath);
};
current = object
.get(field)
.ok_or(QueryInspectionError::MissingResultPath)?;
}
Ok(current.clone())
}