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
perf(cache-core): patch structural query changes instead of resending results (#7825)
teoc7b4495dc1fe
diff --git a/Cargo.lock b/Cargo.lockindex 418bf15989..f63e31556d 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -3460,7 +3460,7 @@ dependencies = [[[package]]name = "cache-wasm"-version = "0.6.45"+version = "0.6.47"dependencies = ["async-lock","cache-core",diff --git a/apps/web/docs/graphql-normalized-cache-plan.md b/apps/web/docs/graphql-normalized-cache-plan.mdindex 718cd8e504..4a1fb8b312 100644--- a/apps/web/docs/graphql-normalized-cache-plan.md+++ b/apps/web/docs/graphql-normalized-cache-plan.md@@ -693,19 +693,27 @@ await client.mutation(DeleteEntityPropertyDocument, {Cache-core compiles response paths while reading normalized records. Bindingsunderstand response aliases, argument-qualified fields, concrete fragment types,-variable defaults and `@include`/`@skip`. Identity aliases are supported. A-subscription retains selected-field bindings rather than another complete-response. Bindings are bounded by count and estimated retained bytes.+variable defaults and `@include`/`@skip`. Identity aliases are supported, and+bindings follow list compaction when tombstoned items are omitted. A+subscription retains its bindings and the last response it was sent; both count+toward the bound on count and estimated retained bytes.Subsequent reads carry the last accepted engine revision. For scalar, scalar-listand opaque-scalar changes, the engine reads only changed dependency records and-returns response-path patches. The JS adapter preserves immutable urql snapshots-and applies those paths in one Solid batch. Relationships, embedded-object edits,-list reordering, invalidation, eviction, cursor mismatch and journal gaps use a-complete cache read to rebuild bindings. Query teardown and account/engine reset-discard the corresponding retained state. Unknown directives, schema drift and-incomplete cached results follow the query's normal network policy; `cache-only`-never starts a network request.+returns response-path patches. Relationships, embedded-object edits, list+membership and order, tombstones, invalidation and journal gaps re-read the+query, rebuild its bindings and diff the result against the retained response.+Diffs only target paths present in the previous response: an object whose key+set changed (another fragment type) or a list whose length or item identities+(`id`, `__typename`) changed is replaced at its own path. A new root, or+replacements larger than half of the response (such as a compacted page),+return the complete result instead: such a patch would carry nearly as much+and cost the engine a copy of every replaced value. Eviction and cursor+mismatch also return a complete result. The JS adapter preserves+immutable urql snapshots and applies those paths in one Solid batch. Query+teardown and account/engine reset discard the corresponding retained state.+Unknown directives, schema drift and incomplete cached results follow the+query's normal network policy; `cache-only` never starts a network request.### Collection semantics and limitsdiff --git a/apps/web/src/lib/graphql-cache/exchange/live-query.timing.test.ts b/apps/web/src/lib/graphql-cache/exchange/live-query.timing.test.tsnew file mode 100644index 0000000000..dfa33a0623--- /dev/null+++ b/apps/web/src/lib/graphql-cache/exchange/live-query.timing.test.ts@@ -0,0 +1,227 @@+// Opt-in main-thread timings for a Soup-like page: a full result (parse plus+// keyed reconcile) vs the patches cache-core sends for leaf, link and+// tombstone edits. Mirrors crates/client/cache-core/tests/watch_query_timing.rs.+// LIVE_QUERY_TIMINGS=1 bunx vitest run --project graphql-cache \+// --reporter=default live-query.timing+import { gql } from '@urql/core';+import { createComputed, createRoot } from 'solid-js';+import { describe, expect, it } from 'vitest';+import type { QueryFieldPatch } from '../protocol';+import { LiveQuery } from './live-query';+import { applyQueryPatches } from './query-patches';+import { queryShape } from './query-shape';++const SAMPLES = 200;+const WARMUP = 20;+const EDITED = 7;+const SHAPE = queryShape(gql`+ query Page($input: SoupInput!) {+ user { id soup(input: $input) { items {+ __typename id frecencyScore+ ... on GraphqlSoupDocument {+ documentName: name ownerId fileType projectId createdAt updatedAt viewedAt deletedAt+ subType { __typename ... on GraphqlTaskSubType { isCompleted } }+ properties { id propertyDefinitionId displayName dataType isMultiSelect value {+ __typename+ ... on GraphqlSelectOptionPropertyValue { optionIds }+ ... on GraphqlStringPropertyValue { value }+ } }+ }+ } nextCursor } }+ }+`);++type PropertyValue = {+ __typename: string;+ optionIds?: string[];+ value?: string;+};++const property = (id: string, definition: string, value: PropertyValue) => ({+ id,+ propertyDefinitionId: definition,+ displayName: definition,+ dataType: value.optionIds ? 'SELECT_STRING' : 'STRING',+ isMultiSelect: false,+ value,+});++const properties = (row: number) => [+ property(`status-${row}`, 'status', {+ __typename: 'GraphqlSelectOptionPropertyValue',+ optionIds: ['todo'],+ }),+ property(`note-${row}`, 'note', {+ __typename: 'GraphqlStringPropertyValue',+ value: 'note',+ }),+];++function page(rows: number) {+ const items = Array.from({ length: rows }, (_, i) => ({+ __typename: 'GraphqlSoupDocument',+ id: `doc-${i}`,+ frecencyScore: 0.5,+ documentName: `Document ${i}`,+ ownerId: 'macro|[email protected]',+ fileType: 'md',+ projectId: i % 3 === 0 ? null : 'project-1',+ createdAt: '2026-10-01T00:00:00Z',+ updatedAt: '2026-10-02T00:00:00Z',+ viewedAt: '2026-10-03T00:00:00Z',+ deletedAt: null,+ subType: { __typename: 'GraphqlTaskSubType', isCompleted: false },+ properties: properties(i),+ }));+ return { user: { id: 'viewer', soup: { items, nextCursor: null } } };+}+type Page = ReturnType<typeof page>;++/** Like a rendered `<For>`: the list tracks rows, each row its own fields. */+function mount(rows: number): LiveQuery {+ return createRoot(() => {+ const view = new LiveQuery(page(rows), SHAPE);+ const items = () => (view.data as Page).user.soup.items;+ createComputed(() => {+ for (const item of items()) void item.id;+ });+ for (const item of items()) {+ createComputed(() => {+ void item.documentName;+ void item.updatedAt;+ void item.subType.isCompleted;+ for (const { value } of item.properties)+ void (value.optionIds?.join(',') ?? value.value);+ });+ }+ return view;+ });+}++/** Median microseconds per call. */+function median(run: (sample: number) => void): number {+ for (let sample = 0; sample < WARMUP; sample++) run(sample);+ const times: number[] = [];+ for (let sample = WARMUP; sample < WARMUP + SAMPLES; sample++) {+ const start = performance.now();+ run(sample);+ times.push(performance.now() - start);+ }+ times.sort((a, b) => a - b);+ return times[times.length >> 1] * 1000;+}++/** Times parsing a transferred patch list and applying it to a mounted view. */+function timePatches(rows: number, payloads: (sample: number) => string) {+ const view = mount(rows);+ const encoded = Array.from({ length: WARMUP + SAMPLES }, (_, sample) =>+ payloads(sample)+ );+ const time = median((sample) => {+ const patches = JSON.parse(encoded[sample]) as QueryFieldPatch[];+ view.replace(applyQueryPatches(view.snapshot, patches));+ });+ return { time, bytes: encoded[0].length, view };+}++describe.skipIf(!process.env.LIVE_QUERY_TIMINGS)(+ 'live query update timings',+ () => {+ it('prints full-result and patch costs', () => {+ const lines = [+ '| rows | update | main thread: parse + apply/reconcile | payload |',+ '|---:|---|---:|---:|',+ ];+ const us = (value: number) => `${value.toFixed(1)} µs`;+ for (const rows of [100, 500]) {+ const full = page(rows);+ const serialized = JSON.stringify(full);+ const hitView = mount(rows);+ const hit = median((sample) => {+ const next = JSON.parse(serialized) as Page;+ next.user.soup.items[(sample * 7) % rows].documentName =+ `Renamed ${sample}`;+ hitView.replace(next);+ });+ lines.push(+ `| ${rows} | full result, one field changed | ${us(hit)} | ${serialized.length} B |`+ );+ const shrunk = JSON.stringify({+ user: {+ ...full.user,+ soup: {+ ...full.user.soup,+ items: full.user.soup.items.filter((_, row) => row !== EDITED),+ },+ },+ });+ const membershipView = mount(rows);+ const membership = median((sample) =>+ membershipView.replace(+ JSON.parse(sample % 2 === 0 ? shrunk : serialized) as Page+ )+ );+ lines.push(+ `| ${rows} | full result, item tombstoned / restored | ${us(membership)} | ${shrunk.length} B |`+ );+ lines.push(+ `| ${rows} | structuredClone of full result (worker → page) | ${us(median(() => structuredClone(full)))} | |`+ );++ const leaf = timePatches(rows, (sample) =>+ JSON.stringify([+ {+ path: [+ 'user',+ 'soup',+ 'items',+ (sample * 7) % rows,+ 'documentName',+ ],+ value: `Renamed ${sample}`,+ },+ ])+ );+ const extra = property(`extra-${EDITED}`, 'extra', {+ __typename: 'GraphqlSelectOptionPropertyValue',+ optionIds: ['added'],+ });+ const linked = [...properties(EDITED), extra];+ const link = timePatches(rows, (sample) =>+ JSON.stringify([+ {+ path: ['user', 'soup', 'items', EDITED, 'properties'],+ value: sample % 2 === 0 ? linked : properties(EDITED),+ },+ ])+ );+ const remaining = full.user.soup.items.filter(+ (_, row) => row !== EDITED+ );+ const tombstone = timePatches(rows, (sample) =>+ JSON.stringify([+ {+ path: ['user', 'soup', 'items'],+ value: sample % 2 === 0 ? remaining : full.user.soup.items,+ },+ ])+ );+ expect(+ (link.view.data as Page).user.soup.items[EDITED].properties+ ).toHaveLength((WARMUP + SAMPLES) % 2 === 0 ? 2 : 3);+ expect((tombstone.view.data as Page).user.soup.items).toHaveLength(+ (WARMUP + SAMPLES) % 2 === 0 ? rows : rows - 1+ );+ for (const [name, result] of [+ ['patch: leaf field', leaf],+ ['patch: add / remove an assignment', link],+ ['patch: tombstone / restore (replaces the list)', tombstone],+ ] as const)+ lines.push(+ `| ${rows} | ${name} | ${us(result.time)} | ${result.bytes} B |`+ );+ }+ console.log(lines.join('\n'));+ }, 120_000);+ }+);diff --git a/apps/web/src/lib/graphql-cache/exchange/live-query.ts b/apps/web/src/lib/graphql-cache/exchange/live-query.tsindex 0d2723cc6c..cff63ffe21 100644--- a/apps/web/src/lib/graphql-cache/exchange/live-query.ts+++ b/apps/web/src/lib/graphql-cache/exchange/live-query.ts@@ -84,19 +84,31 @@ export class LiveQuery {const target = parent as Record<string | number, unknown>;const field = path[path.length - 1];if (value !== null && typeof value === 'object') {+ // The replaced value's previous snapshot lets unchanged rows+ // keep their store objects instead of being rebuilt.+ let previous: unknown = delta.base;+ for (const part of path)+ previous = (previous as Record<string | number, unknown>)[+ part+ ];// Reconcile just the changed subtree to retain keyed rows and// unchanged field observers. A wrapper also allows its root// to be replaced when the value's type or identity changes.- target[field] = reconcile(+ const current = unwrap(target[field]);+ const next = reconcile({value: storeValue(value,shapeAtPath(this.shape, path),- unwrap(target[field])+ current,+ previous),},{ key: RECONCILE_KEY, merge: false }- )({ value: unwrap(target[field]) }).value;+ )({ value: current }).value;+ // Reassigning an in-place reconciliation would only make+ // the draft unwrap the whole subtree again.+ if (next !== current) target[field] = next;} else {target[field] = value;}diff --git a/crates/client/README.md b/crates/client/README.mdindex bf4e12ce91..110bdadac4 100644--- a/crates/client/README.md+++ b/crates/client/README.md@@ -191,8 +191,12 @@ response-path patches. Existing `createUrqlQuery` and `createUrqlInfiniteQuery`consumers benefit from the same path automatically and need no migration;cursor-paginated documents use `createUrqlInfiniteQuery`.Aliases, fragment types, arguments, variable defaults and conditional selections-are resolved by the core reader. Structural edits rebuild the projection;-teardown, account resets and bounded retention discard obsolete bindings. See+are resolved by the core reader. Leaf edits patch through compiled field+bindings without reading. Structural edits (links, list membership and order,+tombstones, type changes) and journal barriers re-read the query, rebuild its+bindings and diff the result against the retained response; only a new root or a+replacement of most of the response resends it. Teardown, account resets and+bounded retention discard obsolete bindings and responses. See[the live query API guide](../../apps/web/docs/graphql-normalized-cache-plan.md#8-live-query-api)for mutation examples and the distinction between reactive cached fields anddomain-specific collection membership.diff --git a/crates/client/cache-core/src/denormalize.rs b/crates/client/cache-core/src/denormalize.rsindex 979c2aa438..15f81c60cb 100644--- a/crates/client/cache-core/src/denormalize.rs+++ b/crates/client/cache-core/src/denormalize.rs@@ -271,9 +271,10 @@ impl<'a> ReadSession<'a> {}// 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. Recompile on subsequent updates.- if !self.deleted_items.is_empty() {- self.projection = None;+ // 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 {@@ -388,7 +389,7 @@ impl<'document, S: RecordSource, D: DependencyTracker> Walk<'_, 'document, S, D>match &planned_field.source {FieldSource::Stored { key, ty } => {let value = fields.get(key.as_ref());- let selection = projection::ValueProjection::compile(+ let selection = projection.compile_value(self.schema,value,field,diff --git a/crates/client/cache-core/src/denormalize/projection.rs b/crates/client/cache-core/src/denormalize/projection.rsindex 0e8dd4e377..d13fef38ac 100644--- a/crates/client/cache-core/src/denormalize/projection.rs+++ b/crates/client/cache-core/src/denormalize/projection.rs@@ -1,19 +1,68 @@//! Response-path bindings compiled by the schema-aware read, never from IDs//! guessed out of response JSON. Relationship changes require a fresh read.+//!+//! Bound paths share prefixes in one node tree and names are interned, so a+//! binding costs a few words rather than an owned path per field.use super::*;use crate::engine::live_query::{LiveFieldPatch, ResponsePathSegment};-use std::collections::BTreeMap;+use std::collections::HashMap;+use std::mem::size_of;++const NO_NODE: u32 = u32::MAX;+// Direct-mapped slots in front of the interning map; selections repeat per row.+const RECENT_NAMES: usize = 256;+// Conservative overhead of one bound record: its key twice, index and list.+const RECORD_BYTES: usize = 160;#[derive(Default)]pub(crate) struct QueryProjection {- pub records: BTreeMap<EntityKey<'static>, BTreeMap<String, FieldProjection>>,+ records: Vec<(EntityKey<'static>, Vec<Binding>)>,+ index: HashMap<EntityKey<'static>, u32>,+ nodes: Vec<Node>,+ names: Vec<Box<str>>,+ bytes: usize,+ compile: Option<Box<Compile>>,}-pub(crate) struct FieldProjection {- value: Option<CacheValue>,- selections: Vec<(Vec<ResponsePathSegment>, ValueProjection)>,+/// State that only lives while the read builds the projection. Names are+/// keyed by address, which is stable only while the read borrows its document.+#[derive(Default)]+struct Compile {+ names: HashMap<(usize, usize), u32>,+ recent: Vec<(usize, usize, u32)>,+ /// Nodes of the previous binding's path, to share its prefix.+ cursor: Vec<(Step, u32)>,+ owner: Option<u32>,+}++#[derive(Clone, Copy, PartialEq, Eq)]+enum Step {+ Field(usize, usize),+ Index(usize),+}++#[derive(Clone, Copy)]+enum Segment {+ Field(u32),+ Index(u32),+ /// A tombstoned list item omitted from the response.+ Removed,+}++struct Node {+ parent: u32,+ segment: Segment,+}++/// One selected or guarded field of a record. Guards have no path: any change+/// to them is structural.+struct Binding {+ key: u32,+ node: u32,structural: bool,+ value: Option<CacheValue>,+ selection: ValueProjection,}/// A selected embedded value retains schema-resolved keys and response aliases.@@ -26,47 +75,29 @@ pub(super) enum ValueProjection {}pub(super) struct EmbeddedField {- key: String,- response_key: String,+ key: u32,+ response_key: u32,value: ValueProjection,}+fn step(part: &ResponsePath<'_>) -> Step {+ match part {+ ResponsePath::Field(field) => Step::Field(field.as_ptr() as usize, field.len()),+ ResponsePath::Index(index) => Step::Index(*index),+ }+}+impl QueryProjection {- // Conservative accounting includes tree/map/path allocations as well as data.+ /// Whether any field of `key` is bound or guarded.+ pub(crate) fn binds(&self, key: &EntityKey<'static>) -> bool {+ self.index.contains_key(key)+ }++ // Conservative accounting includes tree, map and list allocations.pub(crate) fn retained_bytes(&self) -> usize {- self.records- .iter()- .map(|(key, fields)| {- key.as_ref().len()- + 128- + fields- .iter()- .map(|(field, binding)| {- field.len()- + 128- + binding.value.as_ref().map_or(0, value_bytes)- + binding- .selections- .iter()- .map(|(path, selection)| {- 32 + selection.retained_bytes()- + path- .iter()- .map(|part| {- 32 + match part {- ResponsePathSegment::Field(field) => {- field.len()- }- ResponsePathSegment::Index(_) => 0,- }- })- .sum::<usize>()- })- .sum::<usize>()- })- .sum::<usize>()- })- .sum()+ self.bytes+ + self.nodes.capacity() * size_of::<Node>()+ + self.names.iter().map(|name| name.len() + 16).sum::<usize>()}pub(super) fn record(&mut self, key: &EntityKey<'static>, record: &Record) {@@ -81,21 +112,27 @@ impl QueryProjection {pub(super) fn guard(&mut self,- key: &EntityKey<'static>,+ owner: &EntityKey<'static>,field: &str,value: Option<&CacheValue>,) {- let binding = self- .records- .entry(key.clone())- .or_default()- .entry(field.to_owned())- .or_insert_with(|| FieldProjection {- value: value.cloned(),- selections: Vec::new(),- structural: false,- });- binding.structural = true;+ let key = self.intern(field);+ let bytes = size_of::<Binding>() + value.map_or(0, value_bytes);+ let bindings = self.bindings(owner);+ if bindings+ .iter()+ .any(|binding| binding.structural && binding.key == key)+ {+ return;+ }+ bindings.push(Binding {+ key,+ node: NO_NODE,+ structural: true,+ value: value.cloned(),+ selection: ValueProjection::Structural,+ });+ self.bytes += bytes;}pub(super) fn selected_field(@@ -106,17 +143,156 @@ impl QueryProjection {path: &[ResponsePath<'_>],selection: ValueProjection,) {- let binding = self- .records- .entry(owner.clone())- .or_default()- .entry(key.to_string())- .or_insert_with(|| FieldProjection {- value: value.cloned(),- selections: Vec::new(),- structural: false,+ let node = self.node(path);+ let key = self.intern(key);+ self.bytes +=+ size_of::<Binding>() + value.map_or(0, value_bytes) + selection.retained_bytes();+ self.bindings(owner).push(Binding {+ key,+ node,+ structural: false,+ value: value.cloned(),+ selection,+ });+ }++ fn bindings(&mut self, owner: &EntityKey<'static>) -> &mut Vec<Binding> {+ let compile = self.compile.get_or_insert_with(Default::default);+ let slot = match compile.owner {+ Some(slot) if self.records[slot as usize].0 == *owner => slot,+ _ => {+ let slot = match self.index.get(owner) {+ Some(slot) => *slot,+ None => {+ let slot = self.records.len() as u32;+ self.records.push((owner.clone(), Vec::new()));+ self.index.insert(owner.clone(), slot);+ self.bytes += 2 * owner.as_ref().len() + RECORD_BYTES;+ slot+ }+ };+ compile.owner = Some(slot);+ slot+ }+ };+ &mut self.records[slot as usize].1+ }++ /// The node for `path`, sharing the prefix of the previous binding's path.+ fn node(&mut self, path: &[ResponsePath<'_>]) -> u32 {+ let compile = self.compile.get_or_insert_with(Default::default);+ let shared = compile+ .cursor+ .iter()+ .zip(path)+ .take_while(|((cursor, _), part)| *cursor == step(part))+ .count();+ compile.cursor.truncate(shared);+ let mut parent = compile.cursor.last().map_or(NO_NODE, |(_, node)| *node);+ for part in &path[shared..] {+ let segment = match part {+ ResponsePath::Field(field) => Segment::Field(self.intern(field)),+ ResponsePath::Index(index) => Segment::Index(*index as u32),+ };+ let node = self.nodes.len() as u32;+ self.nodes.push(Node { parent, segment });+ self.compile+ .get_or_insert_with(Default::default)+ .cursor+ .push((step(part), node));+ parent = node;+ }+ parent+ }++ fn intern(&mut self, name: &str) -> u32 {+ let compile = self.compile.get_or_insert_with(Default::default);+ if compile.recent.is_empty() {+ compile.recent = vec![(0, 0, 0); RECENT_NAMES];+ }+ let address = (name.as_ptr() as usize, name.len());+ let slot = (address.0 >> 3 ^ address.1) % RECENT_NAMES;+ let (cached, length, id) = compile.recent[slot];+ if (cached, length) == address {+ return id;+ }+ let id = *compile.names.entry(address).or_insert_with(|| {+ self.names.push(name.into());+ self.names.len() as u32 - 1+ });+ compile.recent[slot] = (address.0, address.1, id);+ id+ }++ /// Ends compilation: interned addresses are only valid during the read.+ pub(super) fn finish(&mut self) {+ self.compile = None;+ self.nodes.shrink_to_fit();+ }++ /// Follows list compaction: later items move up one position per removed+ /// item. A removed (deleted) record selects no fields, and its guard still+ /// detects a restore. `removed` uses pre-compaction positions; like+ /// compaction itself, later and deeper removals apply first.+ pub(super) fn compact(&mut self, removed: &BTreeSet<Vec<ResponsePath<'_>>>) {+ for item in removed.iter().rev() {+ let Some((ResponsePath::Index(index), parent)) = item.split_last() else {+ continue;+ };+ for node in 0..self.nodes.len() {+ let Segment::Index(position) = self.nodes[node].segment else {+ continue;+ };+ if !self.is_path(self.nodes[node].parent, parent) {+ continue;+ }+ self.nodes[node].segment = match (position as usize).cmp(index) {+ std::cmp::Ordering::Equal => Segment::Removed,+ std::cmp::Ordering::Greater => Segment::Index(position - 1),+ std::cmp::Ordering::Less => continue,+ };+ }+ }+ }++ fn is_path(&self, mut node: u32, path: &[ResponsePath<'_>]) -> bool {+ for part in path.iter().rev() {+ let Some(current) = self.nodes.get(node as usize) else {+ return false;+ };+ let same = match (current.segment, part) {+ (Segment::Field(name), ResponsePath::Field(field)) => {+ *self.names[name as usize] == **field+ }+ (Segment::Index(position), ResponsePath::Index(index)) => {+ position as usize == *index+ }+ _ => false,+ };+ if !same {+ return false;+ }+ node = current.parent;+ }+ node == NO_NODE+ }++ /// The response path of `node`, or `None` inside a removed list item.+ fn path(&self, mut node: u32) -> Option<Vec<ResponsePathSegment>> {+ let mut path = Vec::new();+ while node != NO_NODE {+ let current = &self.nodes[node as usize];+ path.push(match current.segment {+ Segment::Field(name) => {+ ResponsePathSegment::Field(self.names[name as usize].to_string())+ }+ Segment::Index(index) => ResponsePathSegment::Index(index as usize),+ Segment::Removed => return None,});- binding.selections.push((response_path(path), selection));+ node = current.parent;+ }+ path.reverse();+ Some(path)}/// Inspect only records touched since the last accepted revision. A missing@@ -128,30 +304,35 @@ impl QueryProjection {) -> Option<(Vec<LiveFieldPatch>, isize)> {let mut patches = Vec::new();for (key, record) in records {- let fields = self.records.get(key)?;+ let (_, bindings) = &self.records[*self.index.get(key)? as usize];let record = record.as_ref()?;- for (field, binding) in fields {- let value = record.fields.get(field);+ for binding in bindings {+ let value = record.fields.get(&*self.names[binding.key as usize]);if value == binding.value.as_ref() {continue;}if binding.structural {return None;}- for (path, selection) in &binding.selections {- selection.update(- binding.value.as_ref()?,- value?,- &mut path.clone(),- &mut patches,- )?;- }+ // A binding inside an omitted item has no visible output.+ let Some(mut path) = self.path(binding.node) else {+ continue;+ };+ binding.selection.update(+ &self.names,+ binding.value.as_ref()?,+ value?,+ &mut path,+ &mut patches,+ )?;}}let mut byte_delta = 0;for (key, record) in records {- for (field, binding) in self.records.get_mut(key)? {- let value = record.as_ref()?.fields.get(field);+ let slot = *self.index.get(key)? as usize;+ let record = record.as_ref()?;+ for binding in &mut self.records[slot].1 {+ let value = record.fields.get(&*self.names[binding.key as usize]);if value != binding.value.as_ref() {byte_delta += value.map_or(0, value_bytes) as isize- binding.value.as_ref().map_or(0, value_bytes) as isize;@@ -159,21 +340,16 @@ impl QueryProjection {}}}+ self.bytes = self.bytes.saturating_add_signed(byte_delta);Some((patches, byte_delta))}-}-fn response_path(path: &[ResponsePath<'_>]) -> Vec<ResponsePathSegment> {- path.iter()- .map(|part| match part {- ResponsePath::Field(field) => ResponsePathSegment::Field((*field).to_owned()),- ResponsePath::Index(index) => ResponsePathSegment::Index(*index),- })- .collect()-}--impl ValueProjection {- pub(super) fn compile<'a>(+ #[expect(+ clippy::too_many_arguments,+ reason = "explicit schema and read dependencies"+ )]+ pub(super) fn compile_value<'a>(+ &mut self,schema: &'a crate::meta::Schema,value: Option<&CacheValue>,field: &'a FieldNode,@@ -181,9 +357,9 @@ impl ValueProjection {variables: &serde_json::Map<String, Json>,resolvers: &EntityResolverLookup,plans: &mut ReadPlans<'a>,- ) -> Result<Self, DenormalizeError> {+ ) -> Result<ValueProjection, DenormalizeError> {if ty.kind != meta::FieldKind::Composite {- return Ok(Self::Leaf);+ return Ok(ValueProjection::Leaf);}Ok(match value {Some(CacheValue::Object(values)) => {@@ -198,10 +374,8 @@ impl ValueProjection {{match &selected.source {FieldSource::Typename => {}- FieldSource::Stored { key, ty } => fields.push(EmbeddedField {- key: key.to_string(),- response_key: selected.node.response_key.clone(),- value: Self::compile(+ FieldSource::Stored { key, ty } => {+ let value = self.compile_value(schema,values.get(key.as_ref()),selected.node,@@ -209,27 +383,43 @@ impl ValueProjection {variables,resolvers,plans,- )?,- }),- _ => return Ok(Self::Structural),+ )?;+ fields.push(EmbeddedField {+ key: self.intern(key),+ response_key: self.intern(&selected.node.response_key),+ value,+ });+ }+ _ => return Ok(ValueProjection::Structural),}}- Self::Object(fields)+ ValueProjection::Object(fields)}- Some(CacheValue::List(values)) => Self::List(+ Some(CacheValue::List(values)) => ValueProjection::List(values.iter().map(|value| {- Self::compile(schema, Some(value), field, ty, variables, resolvers, plans)+ self.compile_value(+ schema,+ Some(value),+ field,+ ty,+ variables,+ resolvers,+ plans,+ )}).collect::<Result<_, _>>()?,),- _ => Self::Structural,+ _ => ValueProjection::Structural,})}+}+impl ValueProjection {fn update(&self,+ names: &[Box<str>],before: &CacheValue,after: &CacheValue,path: &mut Vec<ResponsePathSegment>,@@ -247,13 +437,13 @@ impl ValueProjection {if before.get("__typename") == after.get("__typename") =>{for field in fields {- path.push(ResponsePathSegment::Field(field.response_key.clone()));- field.value.update(- before.get(&field.key)?,- after.get(&field.key)?,- path,- patches,- )?;+ let key = &*names[field.key as usize];+ path.push(ResponsePathSegment::Field(+ names[field.response_key as usize].to_string(),+ ));+ field+ .value+ .update(names, before.get(key)?, after.get(key)?, path, patches)?;path.pop();}}@@ -264,7 +454,7 @@ impl ValueProjection {items.iter().zip(before).zip(after).enumerate(){path.push(ResponsePathSegment::Index(index));- selection.update(before, after, path, patches)?;+ selection.update(names, before, after, path, patches)?;path.pop();}}@@ -274,14 +464,15 @@ impl ValueProjection {}fn retained_bytes(&self) -> usize {- 32 + match self {+ match self {Self::Object(fields) => fields.iter()- .map(|field| {- 64 + field.key.len() + field.response_key.len() + field.value.retained_bytes()- })+ .map(|field| size_of::<EmbeddedField>() + field.value.retained_bytes())+ .sum(),+ Self::List(items) => items+ .iter()+ .map(|item| size_of::<Self>() + item.retained_bytes()).sum(),- Self::List(items) => items.iter().map(Self::retained_bytes).sum(),_ => 0,}}diff --git a/crates/client/cache-core/src/engine/watch_query.rs b/crates/client/cache-core/src/engine/watch_query.rsindex 6cb3ef1e55..2863a2788b 100644--- a/crates/client/cache-core/src/engine/watch_query.rs+++ b/crates/client/cache-core/src/engine/watch_query.rs@@ -1,21 +1,38 @@//! Incremental projections of ordinary GraphQL queries. The read compiler owns//! aliases, arguments and concrete fragment types; transports only apply paths.+//!+//! Field bindings patch leaf edits without reading. When they cannot (a link,+//! list, tombstone or type change, or a journal barrier), the query is re-read+//! and diffed against the retained response, which is the subscriber's base.use super::*;use crate::denormalize::QueryProjection;use crate::engine::live_query::LiveFieldPatch;use serde::Serialize;+use std::sync::Arc;++mod diff;const WATCH_CAPACITY: usize = 64;const WATCH_BYTES: usize = 16 * 1024 * 1024;+// A patch replacing most of the response (a compacted page) saves subscribers+// little, while the engine must copy every replaced value into it. Beyond this+// share a re-read publishes the shared result instead. Small ones always patch.+const MAX_REPLACED_SHARE: usize = 2;+const MIN_REPLACED_BYTES: usize = 16 * 1024;/// An atomic query read. A patch is applicable only to the exact revision the-/// subscriber supplied; eviction, structural edits and revision gaps reset it.+/// subscriber supplied; eviction, spec changes and revision mismatches reset it.#[derive(Debug, Serialize)]#[serde(tag = "kind", rename_all = "kebab-case")]pub enum QueryUpdate {- /// Complete replacement, also establishing a new patch base.- Hit { data: Json, revision: String },+ /// Complete replacement, also establishing a new patch base. The watch+ /// shares it as its diff base; serialization is that of the plain JSON.+ Hit {+ #[serde(serialize_with = "serialize_shared")]+ data: Arc<Json>,+ revision: String,+ },/// Selected field replacements, including an empty update for no change.Patch {patches: Vec<LiveFieldPatch>,@@ -25,6 +42,13 @@ pub enum QueryUpdate {Miss { revision: String },}+fn serialize_shared<S: serde::Serializer>(+ data: &Arc<Json>,+ serializer: S,+) -> Result<S::Ok, S::Error> {+ data.as_ref().serialize(serializer)+}+#[derive(PartialEq, Eq)]struct QuerySpec {query: String,@@ -36,10 +60,45 @@ struct QuerySpec {struct QueryWatch {spec: QuerySpec,projection: QueryProjection,+ base: Base,revision: CacheRevision,bytes: usize,}+/// The subscriber's result at the watch revision: the base for re-read diffs.+struct Base {+ /// Shared with the last `Hit`; hosts drop theirs once it is encoded.+ data: Arc<Json>,+ bytes: usize,+}++impl QueryWatch {+ fn new(+ spec: QuerySpec,+ projection: QueryProjection,+ base: Base,+ revision: CacheRevision,+ ) -> Self {+ let bytes = spec.query.len()+ + serde_json::to_vec(&spec.variables).map_or(0, |json| json.len())+ + projection.retained_bytes()+ + base.bytes;+ Self {+ spec,+ projection,+ base,+ revision,+ bytes,+ }+ }++ /// Frees the stale bindings before a re-read compiles new ones, so both are+ /// never resident together.+ fn into_base(self) -> Base {+ self.base+ }+}+pub(super) struct QueryWatches {views: LruCache<OpId, QueryWatch>,bytes: usize,@@ -100,63 +159,101 @@ impl<S: Storage> Engine<S> {variables: variables.clone(),entity_resolvers: entity_resolvers.to_vec(),};- let previous = self.query_watches.pop(op_id);- if let Some(mut view) = previous- && view.spec == spec- && Some(view.revision) == since- && let Some(changes) = self- .live_queries- .changes_since(view.revision, self.revision)- {- let keys = changes- .records- .into_iter()- .filter(|key| view.projection.records.contains_key(key))- .collect();- let bases = self.load_bases(&keys).await?;- let effective = effective_records(&bases, &self.optimistic, &keys);- if let Some((patches, byte_delta)) = view.projection.update(&effective) {- view.revision = self.revision;- // Values (especially opaque scalars) may grow between reads.- view.bytes = view.bytes.saturating_add_signed(byte_delta);- self.query_watches.put(op_id, view);- return Ok(QueryUpdate::Patch {- patches,- revision: self.revision.to_string(),- });- }- }+ let Some(mut view) = self+ .query_watches+ .pop(op_id)+ .filter(|view| view.spec == spec && Some(view.revision) == since)+ else {+ return self.read_watched(op_id, spec, None).await;+ };+ // A journal barrier cannot say what changed; only a re-read can.+ let Some(changes) = self+ .live_queries+ .changes_since(view.revision, self.revision)+ else {+ return self.read_watched(op_id, spec, Some(view.into_base())).await;+ };+ let keys = changes+ .records+ .into_iter()+ .filter(|key| view.projection.binds(key))+ .collect();+ let bases = self.load_bases(&keys).await?;+ let effective = effective_records(&bases, &self.optimistic, &keys);+ let Some((patches, binding_delta)) = view.projection.update(&effective) else {+ return self.read_watched(op_id, spec, Some(view.into_base())).await;+ };+ let Some(data_delta) = diff::apply_patches(Arc::make_mut(&mut view.base.data), &patches)+ else {+ // A binding path missing from the base would desynchronize diffs.+ return self.read_watched(op_id, spec, None).await;+ };+ view.revision = self.revision;+ // Values (especially opaque scalars) may grow between reads.+ view.base.bytes = view.base.bytes.saturating_add_signed(data_delta);+ view.bytes = view.bytes.saturating_add_signed(binding_delta + data_delta);+ self.query_watches.put(op_id, view);+ Ok(QueryUpdate::Patch {+ patches,+ revision: self.revision.to_string(),+ })+ }++ /// Reads the whole query and recompiles its bindings. With the subscriber's+ /// base it publishes a diff, falling back to a replacement for a new root.+ async fn read_watched(+ &mut self,+ op_id: OpId,+ spec: QuerySpec,+ base: Option<Base>,+ ) -> Result<QueryUpdate, EngineError<S::Error>> {let (result, projection) = self.read_query_tracked(Some(op_id),- query,- operation_name,- variables,- entity_resolvers,+ &spec.query,+ spec.operation_name.as_deref(),+ &spec.variables,+ &spec.entity_resolvers,true,).await?;let revision = self.revision.to_string();- match result {- ReadResult::Hit { data } => {- if let Some(projection) = projection {- let bytes = projection.retained_bytes()- + spec.query.len()- + serde_json::to_vec(&spec.variables).map_or(0, |json| json.len());- self.query_watches.put(- op_id,- QueryWatch {- spec,- projection,- revision: self.revision,- bytes,- },- );- }- Ok(QueryUpdate::Hit { data, revision })- }- ReadResult::Miss => Ok(QueryUpdate::Miss { revision }),- }+ let ReadResult::Hit { data } = result else {+ return Ok(QueryUpdate::Miss { revision });+ };+ let Some(projection) = projection else {+ return Ok(QueryUpdate::Hit {+ data: Arc::new(data),+ revision,+ });+ };+ let diff = base.and_then(|base| {+ let budget = (base.bytes / MAX_REPLACED_SHARE).max(MIN_REPLACED_BYTES);+ diff::diff_response(&base.data, &data, budget).map(|diff| (diff, base.bytes))+ });+ let data = Arc::new(data);+ let (update, bytes) = match diff {+ Some((diff, bytes)) => (+ QueryUpdate::Patch {+ patches: diff.patches,+ revision,+ },+ bytes.saturating_add_signed(diff.byte_delta),+ ),+ None => (+ QueryUpdate::Hit {+ data: Arc::clone(&data),+ revision,+ },+ diff::json_bytes(&data),+ ),+ };+ let base = Base { data, bytes };+ self.query_watches.put(+ op_id,+ QueryWatch::new(spec, projection, base, self.revision),+ );+ Ok(update)}}diff --git a/crates/client/cache-core/src/engine/watch_query/diff.rs b/crates/client/cache-core/src/engine/watch_query/diff.rsnew file mode 100644index 0000000000..c2f86cdbb0--- /dev/null+++ b/crates/client/cache-core/src/engine/watch_query/diff.rs@@ -0,0 +1,155 @@+//! Response diffs a document subscriber can apply to its previous result.+//!+//! Unlike row diffs, a document patch must target a path that already exists in+//! the subscriber's base, and no two patches may overlap. Objects whose key set+//! changed (another fragment type) and lists whose identities moved are+//! replaced at their own path instead of being patched below it.++use crate::engine::live_query::{LiveFieldPatch, ResponsePathSegment};+use serde_json::Value as Json;++// Rough in-memory cost of one JSON value or object entry, beyond its text.+const JSON_NODE_BYTES: usize = 32;++#[derive(Clone, Copy)]+enum Segment<'a> {+ Field(&'a str),+ Index(usize),+}++/// Patches from `before` to `after`, with the change in retained bytes.+pub(super) struct ResponseDiff {+ pub patches: Vec<LiveFieldPatch>,+ pub byte_delta: isize,+ /// Retained bytes of replaced values still allowed before giving up.+ budget: usize,+}++/// Returns `None` when the root itself must be replaced, or when replaced+/// values exceed `budget` retained bytes: subscribers reconcile a complete+/// result faster than a patch that replaces most of it.+pub(super) fn diff_response(before: &Json, after: &Json, budget: usize) -> Option<ResponseDiff> {+ match (before, after) {+ (Json::Object(previous), Json::Object(next)) if same_keys(previous, next) => {}+ _ => return None,+ }+ let mut diff = ResponseDiff {+ patches: Vec::new(),+ byte_delta: 0,+ budget,+ };+ diff.visit(before, after, &mut Vec::new())?;+ Some(diff)+}++impl ResponseDiff {+ fn visit<'a>(+ &mut self,+ before: &Json,+ after: &'a Json,+ path: &mut Vec<Segment<'a>>,+ ) -> Option<()> {+ match (before, after) {+ (Json::Object(previous), Json::Object(next)) if same_keys(previous, next) => {+ for ((_, previous), (key, value)) in previous.iter().zip(next) {+ path.push(Segment::Field(key));+ self.visit(previous, value, path)?;+ path.pop();+ }+ }+ (Json::Array(previous), Json::Array(next))+ if previous.len() == next.len()+ && previous.iter().zip(next).all(|(a, b)| same_item(a, b)) =>+ {+ for (index, (previous, value)) in previous.iter().zip(next).enumerate() {+ path.push(Segment::Index(index));+ self.visit(previous, value, path)?;+ path.pop();+ }+ }+ _ if before == after => {}+ _ => {+ let replaced = json_bytes(after);+ self.budget = self.budget.checked_sub(replaced)?;+ self.byte_delta += replaced as isize - json_bytes(before) as isize;+ self.patches.push(LiveFieldPatch {+ path: path+ .iter()+ .map(|segment| match segment {+ Segment::Field(field) => {+ ResponsePathSegment::Field((*field).to_owned())+ }+ Segment::Index(index) => ResponsePathSegment::Index(*index),+ })+ .collect(),+ value: after.clone(),+ });+ }+ }+ Some(())+ }+}++// Reads of one spec emit keys in a stable order, so comparing in order also+// pairs the values. A reordered map is merely replaced, never mispatched.+fn same_keys(+ before: &serde_json::Map<String, Json>,+ after: &serde_json::Map<String, Json>,+) -> bool {+ before.len() == after.len() && before.keys().eq(after.keys())+}++/// Objects keep their position while their selected identity is unchanged.+/// Other values are their own identity, so a changed scalar replaces its list.+fn same_item(before: &Json, after: &Json) -> bool {+ match (before, after) {+ (Json::Object(previous), Json::Object(next)) => {+ previous.get("id") == next.get("id")+ && previous.get("__typename") == next.get("__typename")+ }+ _ => before == after,+ }+}++/// Applies binding patches to the retained base so it stays the subscriber's+/// result. Returns the change in retained bytes, or `None` (leaving `data`+/// untouched) when a path is absent.+pub(super) fn apply_patches(data: &mut Json, patches: &[LiveFieldPatch]) -> Option<isize> {+ if !patches+ .iter()+ .all(|patch| slot(data, &patch.path).is_some())+ {+ return None;+ }+ let mut delta = 0;+ for patch in patches {+ let target = slot(data, &patch.path)?;+ delta += json_bytes(&patch.value) as isize - json_bytes(target) as isize;+ *target = patch.value.clone();+ }+ Some(delta)+}++fn slot<'a>(data: &'a mut Json, path: &[ResponsePathSegment]) -> Option<&'a mut Json> {+ path.iter().try_fold(data, |slot, segment| match segment {+ ResponsePathSegment::Field(field) => slot.as_object_mut()?.get_mut(field),+ ResponsePathSegment::Index(index) => slot.as_array_mut()?.get_mut(*index),+ })+}++/// Conservative retained size of a response value, for bounded watch retention.+pub(super) fn json_bytes(value: &Json) -> usize {+ JSON_NODE_BYTES+ + match value {+ Json::String(text) => text.len(),+ Json::Array(items) => items.iter().map(json_bytes).sum(),+ Json::Object(fields) => fields+ .iter()+ .map(|(key, value)| key.len() + JSON_NODE_BYTES + json_bytes(value))+ .sum(),+ _ => 0,+ }+}++#[cfg(test)]+mod test;diff --git a/crates/client/cache-core/src/engine/watch_query/diff/test.rs b/crates/client/cache-core/src/engine/watch_query/diff/test.rsnew file mode 100644index 0000000000..d562a0d30a--- /dev/null+++ b/crates/client/cache-core/src/engine/watch_query/diff/test.rs@@ -0,0 +1,122 @@+use super::*;+use serde_json::json;++fn patches(before: Json, after: Json) -> Json {+ let diff = diff_response(&before, &after, usize::MAX).expect("root is patchable");+ serde_json::to_value(diff.patches).unwrap()+}++#[test]+fn scalars_and_matching_objects_patch_only_changed_leaves() {+ assert_eq!(+ patches(+ json!({"user": {"id": "u", "name": "a", "count": 1, "seen": null}}),+ json!({"user": {"id": "u", "name": "b", "count": 1, "seen": true}}),+ ),+ json!([+ {"path": ["user", "name"], "value": "b"},+ {"path": ["user", "seen"], "value": true},+ ])+ );+ assert_eq!(+ patches(json!({"a": {"b": [1]}}), json!({"a": {"b": [1]}})),+ json!([])+ );+}++#[test]+fn changed_key_sets_and_nulls_replace_the_whole_object() {+ assert_eq!(+ patches(+ json!({"value": {"kind": "Select", "selected": ["a"]}}),+ json!({"value": {"kind": "Text", "text": "a"}}),+ ),+ json!([{"path": ["value"], "value": {"kind": "Text", "text": "a"}}])+ );+ assert_eq!(+ patches(json!({"value": {"kind": "Text"}}), json!({"value": null})),+ json!([{"path": ["value"], "value": null}])+ );+ assert_eq!(+ patches(json!({"value": null}), json!({"value": {"kind": "Text"}})),+ json!([{"path": ["value"], "value": {"kind": "Text"}}])+ );+}++#[test]+fn lists_patch_items_only_when_lengths_and_identities_match() {+ let row = |id: &str, name: &str| json!({"__typename": "Doc", "id": id, "name": name});+ assert_eq!(+ patches(+ json!({"items": [row("1", "a"), row("2", "b")]}),+ json!({"items": [row("1", "a"), row("2", "c")]}),+ ),+ json!([{"path": ["items", 1, "name"], "value": "c"}])+ );+ for after in [+ json!({"items": [row("2", "b"), row("1", "a")]}),+ json!({"items": [row("1", "a")]}),+ json!({"items": [row("1", "a"), {"__typename": "Thread", "id": "2", "name": "b"}]}),+ ] {+ assert_eq!(+ patches(+ json!({"items": [row("1", "a"), row("2", "b")]}),+ after.clone()+ ),+ json!([{"path": ["items"], "value": after["items"]}])+ );+ }+ // Embedded objects without identity keep their positions.+ assert_eq!(+ patches(+ json!({"refs": [{"target": "a"}, {"target": "b"}]}),+ json!({"refs": [{"target": "a"}, {"target": "c"}]}),+ ),+ json!([{"path": ["refs", 1, "target"], "value": "c"}])+ );+ // Scalar items are their own identity: a changed scalar replaces its list.+ assert_eq!(+ patches(json!({"ids": ["a", "b"]}), json!({"ids": ["a", "c"]})),+ json!([{"path": ["ids"], "value": ["a", "c"]}])+ );+}++#[test]+fn root_replacements_are_not_patches() {+ assert!(diff_response(&json!({"a": 1}), &json!({"b": 1}), usize::MAX).is_none());+ assert!(diff_response(&json!({"a": 1}), &json!({"a": 1, "b": 2}), usize::MAX).is_none());+ assert!(diff_response(&json!(null), &json!({"a": 1}), usize::MAX).is_none());+}++#[test]+fn replacements_beyond_the_budget_are_not_patches() {+ let before = json!({"small": 1, "list": ["a", "b"]});+ let after = json!({"small": 2, "list": ["a"]});+ let list = json_bytes(&after["list"]);+ let small = json_bytes(&after["small"]);+ assert!(diff_response(&before, &after, small + list).is_some());+ assert!(diff_response(&before, &after, small + list - 1).is_none());+}++#[test]+fn applied_patches_reproduce_the_target_and_track_bytes() {+ let before = json!({"a": "short", "b": [1, 2], "c": {"d": null}});+ let after = json!({"a": "much longer text", "b": [1, 2, 3], "c": {"d": {"e": 1}}});+ let mut data = before.clone();+ let diff = diff_response(&before, &after, usize::MAX).unwrap();+ let expected = json_bytes(&after) as isize - json_bytes(&before) as isize;+ assert_eq!(diff.byte_delta, expected);+ assert_eq!(apply_patches(&mut data, &diff.patches), Some(expected));+ assert_eq!(data, after);+ let missing = LiveFieldPatch {+ path: vec![+ ResponsePathSegment::Field("a".into()),+ ResponsePathSegment::Index(0),+ ],+ value: json!(1),+ };+ let mut patches = diff_response(&after, &before, usize::MAX).unwrap().patches;+ patches.push(missing);+ assert!(apply_patches(&mut data, &patches).is_none());+ assert_eq!(data, after, "an inapplicable batch changes nothing");+}diff --git a/crates/client/cache-core/src/engine/watch_query/test.rs b/crates/client/cache-core/src/engine/watch_query/test.rsindex 2494283b05..31810061fd 100644--- a/crates/client/cache-core/src/engine/watch_query/test.rs+++ b/crates/client/cache-core/src/engine/watch_query/test.rs@@ -4,6 +4,7 @@ use pollster::block_on;use serde_json::json;mod embedded;+mod generated;const PAGE: &str = "query Page($input: SoupInput!) { user { id soup(input: $input) { items { __typename id ... on GraphqlSoupEmailThread { isRead } } nextCursor } } }";const DETAIL: &str = "query Detail($id: ID!, $show: Boolean! = true) { user { alias: emailThread(input: {threadId: $id}) { ...Fields @include(if: $show) } } } fragment Fields on GraphqlSoupEmailThread { seen: isRead }";@@ -54,6 +55,53 @@ fn patches(update: QueryUpdate) -> Json {serde_json::to_value(patches).unwrap()}+/// Applies an update under the JS document applier's rules: every patch+/// targets an existing non-root path and changes it. Identical duplicates are+/// applied once; any other pair of patches must not overlap.+fn apply(snapshot: &mut Json, update: QueryUpdate) -> CacheRevision {+ let cursor = revision(&update);+ match update {+ QueryUpdate::Hit { data, .. } => *snapshot = Json::clone(&data),+ QueryUpdate::Patch { mut patches, .. } => {+ let encoded = |patch: &live_query::LiveFieldPatch| serde_json::to_value(patch).unwrap();+ let mut seen = Vec::new();+ patches.retain(|patch| {+ let patch = encoded(patch);+ let distinct = !seen.contains(&patch);+ seen.push(patch);+ distinct+ });+ let paths: Vec<Json> = patches+ .iter()+ .map(|patch| serde_json::to_value(&patch.path).unwrap())+ .collect();+ for (index, path) in paths.iter().enumerate() {+ let path = path.as_array().unwrap();+ assert!(!path.is_empty(), "a patch cannot replace the root");+ for other in &paths[index + 1..] {+ let other = other.as_array().unwrap();+ let shared = path.len().min(other.len());+ assert_ne!(path[..shared], other[..shared], "patches overlap");+ }+ }+ for patch in patches {+ let mut slot = &mut *snapshot;+ for part in patch.path {+ slot = match part {+ live_query::ResponsePathSegment::Field(name) => slot.get_mut(name.as_str()),+ live_query::ResponsePathSegment::Index(index) => slot.get_mut(index),+ }+ .expect("patch targets an existing path");+ }+ assert_ne!(*slot, patch.value, "unchanged values are not published");+ *slot = patch.value;+ }+ }+ QueryUpdate::Miss { .. } => panic!("unexpected miss"),+ }+ cursor+}+#[test]fn targets_one_field_in_a_thousand_rows_for_every_subscriber() {block_on(async {@@ -67,7 +115,7 @@ fn targets_one_field_in_a_thousand_rows_for_every_subscriber() {.watch_query(2, PAGE, None, &vars(), &[], None).await.unwrap();- assert!(matches!(&first, QueryUpdate::Hit { data: result, .. } if *result == data(1000)));+ assert!(matches!(&first, QueryUpdate::Hit { data: result, .. } if **result == data(1000)));change(&mut engine, "17", "isRead", CacheValue::Bool(true)).await;let before = engine.storage().record_get_count();for (op, previous) in [(1, first), (2, second)] {@@ -87,6 +135,105 @@ fn targets_one_field_in_a_thousand_rows_for_every_subscriber() {});}+#[test]+fn unrelated_changes_and_leaf_edits_never_reread_but_structural_edits_do() {+ block_on(async {+ // A one-record hot tier makes any re-read visible as storage reads.+ let mut engine = Engine::with_capacity(InMemoryStorage::new(), 1);+ seed(&mut engine, 2).await;+ let first = engine+ .watch_query(1, PAGE, None, &vars(), &[], None)+ .await+ .unwrap();+ let mut cursor = revision(&first);+ let edits = [+ (+ "unrelated",+ "isRead",+ CacheValue::Bool(true),+ json!([]),+ false,+ ),+ (+ "1",+ "isRead",+ CacheValue::Bool(true),+ json!([{"path": ["user", "soup", "items", 1, "isRead"], "value": true}]),+ false,+ ),+ (+ "1",+ "__typename",+ CacheValue::String("GraphqlSoupDocument".into()),+ // A changed item identity replaces its list.+ json!([{"path": ["user", "soup", "items"], "value": [+ {"__typename": "GraphqlSoupEmailThread", "id": "0", "isRead": false},+ {"__typename": "GraphqlSoupDocument", "id": "1"},+ ]}]),+ true,+ ),+ ];+ for (id, field, value, expected, rereads) in edits {+ change(&mut engine, id, field, value).await;+ let before = engine.storage().record_get_count();+ let next = engine+ .watch_query(1, PAGE, None, &vars(), &[], Some(cursor))+ .await+ .unwrap();+ assert_eq!(+ engine.storage().record_get_count() - before > 1,+ rereads,+ "{field} on {id}"+ );+ cursor = revision(&next);+ assert_eq!(patches(next), expected, "{field} on {id}");+ }+ });+}++#[test]+fn journal_barriers_and_gaps_diff_against_the_subscriber_base() {+ block_on(async {+ let mut engine = Engine::new(InMemoryStorage::new());+ seed(&mut engine, 2).await;+ let first = engine+ .watch_query(1, PAGE, None, &vars(), &[], None)+ .await+ .unwrap();+ change(&mut engine, "1", "isRead", CacheValue::Bool(true)).await;+ let key = EntityKey::entity("GraphqlSoupEmailThread", &["1"]);+ engine.invalidate_keys([&key]).unwrap();+ let barrier = engine+ .watch_query(1, PAGE, None, &vars(), &[], Some(revision(&first)))+ .await+ .unwrap();+ let cursor = revision(&barrier);+ assert_eq!(+ patches(barrier),+ json!([{"path": ["user", "soup", "items", 1, "isRead"], "value": true}])+ );+ // Overflow the bounded journal with unrelated revisions.+ for index in 0..200 {+ change(+ &mut engine,+ "unrelated",+ "isRead",+ CacheValue::Bool(index % 2 == 0),+ )+ .await;+ }+ change(&mut engine, "0", "isRead", CacheValue::Bool(true)).await;+ let gap = engine+ .watch_query(1, PAGE, None, &vars(), &[], Some(cursor))+ .await+ .unwrap();+ assert_eq!(+ patches(gap),+ json!([{"path": ["user", "soup", "items", 0, "isRead"], "value": true}])+ );+ });+}+#[test]fn aliases_fragments_defaults_and_synthetic_relations_need_no_selected_identity() {block_on(async {@@ -104,7 +251,7 @@ fn aliases_fragments_defaults_and_synthetic_relations_need_no_selected_identity(.await.unwrap();assert!(- matches!(&first, QueryUpdate::Hit { data, .. } if *data == json!({"user":{"alias":{"seen":false}}}))+ matches!(&first, QueryUpdate::Hit { data, .. } if **data == json!({"user":{"alias":{"seen":false}}})));change(&mut engine, "0", "isRead", CacheValue::Bool(true)).await;let update = engine@@ -136,13 +283,13 @@ fn aliases_fragments_defaults_and_synthetic_relations_need_no_selected_identity(.await.unwrap();assert!(- matches!(update, QueryUpdate::Hit { data, .. } if data == json!({"user":{"alias":{}}}))+ matches!(update, QueryUpdate::Hit { data, .. } if *data == json!({"user":{"alias":{}}})));});}#[test]-fn structural_edits_rebuild_paths_and_tombstones_cannot_patch_stale_indices() {+fn reorders_and_tombstones_replace_the_list_instead_of_patching_stale_indices() {block_on(async {let mut engine = Engine::new(InMemoryStorage::new());seed(&mut engine, 2).await;@@ -163,10 +310,14 @@ fn structural_edits_rebuild_paths_and_tombstones_cannot_patch_stale_indices() {.watch_query(1, PAGE, None, &vars(), &[], Some(revision(&initial))).await.unwrap();- assert!(matches!(&replacement, QueryUpdate::Hit { data, .. } if *data == reordered));+ let cursor = revision(&replacement);+ assert_eq!(+ patches(replacement),+ json!([{"path":["user","soup","items"],"value":reordered["user"]["soup"]["items"]}])+ );change(&mut engine, "0", "isRead", CacheValue::Bool(true)).await;let next = engine- .watch_query(1, PAGE, None, &vars(), &[], Some(revision(&replacement)))+ .watch_query(1, PAGE, None, &vars(), &[], Some(cursor)).await.unwrap();let cursor = revision(&next);@@ -185,20 +336,83 @@ fn structural_edits_rebuild_paths_and_tombstones_cannot_patch_stale_indices() {.watch_query(1, PAGE, None, &vars(), &[], Some(cursor)).await.unwrap();- assert!(- matches!(&deleted, QueryUpdate::Hit { data, .. } if data["user"]["soup"]["items"].as_array().unwrap().len() == 1)+ let cursor = revision(&deleted);+ assert_eq!(+ patches(deleted),+ json!([{"path":["user","soup","items"],"value":[+ {"__typename": "GraphqlSoupEmailThread", "id": "0", "isRead": true}+ ]}]));change(&mut engine, "0", "isRead", CacheValue::Bool(false)).await;let after = engine- .watch_query(1, PAGE, None, &vars(), &[], Some(revision(&deleted)))+ .watch_query(1, PAGE, None, &vars(), &[], Some(cursor)).await.unwrap();- assert!(- matches!(after, QueryUpdate::Hit { data, .. } if data["user"]["soup"]["items"][0]["isRead"] == false)+ assert_eq!(+ patches(after),+ json!([{"path":["user","soup","items",0,"isRead"],"value":false}]),+ "compacted indices are diffed against the published list");});}+#[test]+fn bindings_follow_list_compaction_without_rereading() {+ block_on(async {+ // A one-record hot tier makes any re-read visible as storage reads.+ let mut engine = Engine::with_capacity(InMemoryStorage::new(), 1);+ seed(&mut engine, 3).await;+ let first = engine+ .watch_query(1, PAGE, None, &vars(), &[], None)+ .await+ .unwrap();+ let mut cursor = revision(&first);+ let edits = [+ ("0", identity::DELETED_FIELD, true, None),+ (+ "2",+ "isRead",+ true,+ Some(json!([{"path":["user","soup","items",1,"isRead"],"value":true}])),+ ),+ ("0", identity::DELETED_FIELD, false, None),+ (+ "2",+ "isRead",+ false,+ Some(json!([{"path":["user","soup","items",2,"isRead"],"value":false}])),+ ),+ ];+ for (id, field, value, leaf) in edits {+ change(&mut engine, id, field, CacheValue::Bool(value)).await;+ let before = engine.storage().record_get_count();+ let update = engine+ .watch_query(1, PAGE, None, &vars(), &[], Some(cursor))+ .await+ .unwrap();+ cursor = revision(&update);+ let reads = engine.storage().record_get_count() - before;+ match leaf {+ Some(expected) => {+ assert!(reads <= 1, "{field} on {id} used the bindings");+ assert_eq!(patches(update), expected);+ }+ None => {+ assert!(reads > 1, "{field} on {id} re-read");+ let full = engine.read_query(None, PAGE, None, &vars()).await.unwrap();+ let ReadResult::Hit { data } = full else {+ panic!("seeded page must hit");+ };+ assert_eq!(+ patches(update),+ json!([{"path":["user","soup","items"],"value":data["user"]["soup"]["items"]}])+ );+ }+ }+ }+ });+}+#[test]fn stale_cursors_teardown_eviction_and_generation_changes_get_replacements() {block_on(async {@@ -276,7 +490,7 @@ fn skipped_fields_do_not_resurface_and_repeated_fragment_selections_merge() {let merged ="query { user { id } user { soup(input:{initial:{limit:1000}}) { nextCursor } } }";assert!(- matches!(engine.watch_query(2, merged, None, &serde_json::Map::new(), &[], None).await.unwrap(), QueryUpdate::Hit { data, .. } if data == json!({"user":{"id":"viewer","soup":{"nextCursor":null}}}))+ matches!(engine.watch_query(2, merged, None, &serde_json::Map::new(), &[], None).await.unwrap(), QueryUpdate::Hit { data, .. } if *data == json!({"user":{"id":"viewer","soup":{"nextCursor":null}}})));});}@@ -358,7 +572,7 @@ fn network_identity_aliases_and_default_arguments_round_trip() {.watch_query(1, query, None, &variables, &[], None).await.unwrap();- assert!(matches!(&first, QueryUpdate::Hit { data: actual, .. } if *actual == data));+ assert!(matches!(&first, QueryUpdate::Hit { data: actual, .. } if **actual == data));change(&mut engine, "0", "isRead", CacheValue::Bool(true)).await;let next = engine.watch_query(1, query, None, &variables, &[], Some(revision(&first)))@@ -372,7 +586,7 @@ fn network_identity_aliases_and_default_arguments_round_trip() {}#[test]-fn account_changes_discard_query_bindings_and_old_entities() {+fn account_changes_discard_query_watches_and_old_entities() {block_on(async {let mut engine = Engine::new(InMemoryStorage::new());engine@@ -394,6 +608,6 @@ fn account_changes_discard_query_bindings_and_old_entities() {.watch_query(1, PAGE, None, &vars(), &[], Some(revision(&first))).await.unwrap();- assert!(matches!(result, QueryUpdate::Hit { data, .. } if data == next));+ assert!(matches!(result, QueryUpdate::Hit { data, .. } if *data == next));});}diff --git a/crates/client/cache-core/src/engine/watch_query/test/embedded.rs b/crates/client/cache-core/src/engine/watch_query/test/embedded.rsindex 5f1da0954f..6f9954e114 100644--- a/crates/client/cache-core/src/engine/watch_query/test/embedded.rs+++ b/crates/client/cache-core/src/engine/watch_query/test/embedded.rs@@ -61,7 +61,7 @@ fn nested_property_edits_patch_each_subscriber_without_reading_other_rows() {.await.unwrap();assert!(- matches!(&first, QueryUpdate::Hit { data, .. } if *data == property_page(1000))+ matches!(&first, QueryUpdate::Hit { data, .. } if **data == property_page(1000)));cursors.push((op, revision(&first)));}@@ -96,7 +96,7 @@ fn nested_property_edits_patch_each_subscriber_without_reading_other_rows() {}#[test]-fn embedded_nulls_type_changes_and_missing_fields_rebuild_the_selected_shape() {+fn embedded_nulls_and_type_changes_replace_the_value_and_missing_fields_miss() {block_on(async {let mut engine = Engine::new(InMemoryStorage::new());engine@@ -131,8 +131,12 @@ fn embedded_nulls_type_changes_and_missing_fields_rebuild_the_selected_shape() {.await.unwrap();cursor = revision(&update);- assert!(- matches!(update, QueryUpdate::Hit { data, .. } if data["user"]["soup"]["items"][0]["properties"][0]["value"] == expected)+ assert_eq!(+ patches(update),+ json!([{+ "path": ["user", "soup", "items", 0, "properties", 0, "value"],+ "value": expected+ }]));}set_value(@@ -155,7 +159,7 @@ fn embedded_nulls_type_changes_and_missing_fields_rebuild_the_selected_shape() {}#[test]-fn nested_lists_preserve_aliases_and_rebuild_after_membership_changes() {+fn nested_lists_preserve_aliases_and_replace_changed_membership() {block_on(async {let mut engine = Engine::new(InMemoryStorage::new());let mut data = property_page(1);@@ -196,7 +200,84 @@ fn nested_lists_preserve_aliases_and_rebuild_after_membership_changes() {.watch_query(1, PROPERTIES, None, &vars(), &[], Some(cursor)).await.unwrap();- assert!(matches!(next, QueryUpdate::Hit { data: actual, .. } if actual == data));+ assert_eq!(+ patches(next),+ json!([{+ "path": ["user", "soup", "items", 0, "properties", 0, "value", "references"], "value": []+ }])+ );+ });+}++#[test]+fn link_edits_patch_one_row_but_large_list_replacements_resend_the_result() {+ block_on(async {+ let mut engine = Engine::new(InMemoryStorage::new());+ engine+ .write_query(None, PROPERTIES, None, &vars(), &property_page(1000), None)+ .await+ .unwrap();+ let first = engine+ .watch_query(1, PROPERTIES, None, &vars(), &[], None)+ .await+ .unwrap();+ let document =+ |id: usize| EntityKey::entity("GraphqlSoupDocument", &[&format!("doc-{id}")]);+ let property = |id: usize| {+ CacheValue::Ref(EntityKey::entity(+ "GraphqlProperty",+ &[&format!("property-{id}")],+ ))+ };+ let mut snapshot = property_page(1000);+ let mut cursor = apply(&mut snapshot, first);+ let edits = [+ (+ "properties",+ CacheValue::List(vec![property(17), property(18)]),+ false,+ ),+ (identity::DELETED_FIELD, CacheValue::Bool(true), true),+ ];+ for (field, value, resend) in edits {+ engine+ .put_records_with_projections(+ None,+ vec![(+ document(17),+ Record {+ fields: BTreeMap::from([(field.into(), value)]),+ },+ )],+ vec![],+ )+ .await+ .unwrap();+ let update = engine+ .watch_query(1, PROPERTIES, None, &vars(), &[], Some(cursor))+ .await+ .unwrap();+ match &update {+ QueryUpdate::Hit { .. } => assert!(resend, "{field} resent the result"),+ QueryUpdate::Patch { patches, .. } => {+ assert!(!resend, "{field} patched a compacted list");+ assert_eq!(+ serde_json::to_value(patches).unwrap()[0]["path"],+ json!(["user", "soup", "items", 17, "properties"])+ );+ }+ QueryUpdate::Miss { .. } => panic!("complete page cannot miss"),+ }+ cursor = apply(&mut snapshot, update);+ let ReadResult::Hit { data } = engine+ .read_query(None, PROPERTIES, None, &vars())+ .await+ .unwrap()+ else {+ panic!("complete page cannot miss");+ };+ assert_eq!(snapshot, data);+ }});}@@ -308,21 +389,7 @@ proptest! {};set_value(&mut engine, id, value).await;let next = engine.watch_query(1, PROPERTIES, None, &vars(), &[], Some(cursor)).await.unwrap();- cursor = revision(&next);- match next {- QueryUpdate::Hit { data, .. } => snapshot = data,- QueryUpdate::Patch { patches, .. } => for patch in patches {- let mut slot = &mut snapshot;- for part in patch.path {- slot = match part {- live_query::ResponsePathSegment::Field(name) => slot.get_mut(&name),- live_query::ResponsePathSegment::Index(index) => slot.get_mut(index),- }.expect("patch targets an existing selected field");- }- *slot = patch.value;- },- QueryUpdate::Miss { .. } => panic!("complete property values cannot miss"),- }+ cursor = apply(&mut snapshot, next);let full = engine.read_query(None, PROPERTIES, None, &vars()).await.unwrap();let ReadResult::Hit { data } = full else { panic!("full read missed") };prop_assert_eq!(&snapshot, &data);diff --git a/crates/client/cache-core/src/engine/watch_query/test/generated.rs b/crates/client/cache-core/src/engine/watch_query/test/generated.rsnew file mode 100644index 0000000000..5a02de142f--- /dev/null+++ b/crates/client/cache-core/src/engine/watch_query/test/generated.rs@@ -0,0 +1,287 @@+//! Generated edit histories. Applying each published update to the previous+//! result, under the JS applier's rules, must equal a fresh full read. Leaf+//! edits take the binding path; links, tombstones, reorders, type changes and+//! barriers take the re-read diff.++use super::*;+use proptest::prelude::*;++const QUERY: &str = r#"+query Page($input: SoupInput!) {+ user { id soup(input: $input) { items {+ __typename id+ ... on GraphqlSoupEmailThread { isRead }+ ... on GraphqlSoupDocument {+ title: name+ properties { id value {+ kind: __typename+ ... on GraphqlSelectOptionPropertyValue { selected: optionIds }+ ... on GraphqlStringPropertyValue { text: value }+ } }+ }+ } nextCursor } }+}"#;+const ROWS: usize = 6;++#[derive(Clone, Debug)]+enum PropertyValue {+ Null,+ Options(Vec<String>),+ Text(String),+}++#[derive(Clone, Debug)]+enum Edit {+ /// Rewrites membership, order, property list lengths and row fields.+ Page(Vec<(usize, usize, PropertyValue)>),+ Scalar {+ row: usize,+ value: String,+ },+ Property {+ row: usize,+ slot: usize,+ value: PropertyValue,+ },+ Delete {+ row: usize,+ slot: Option<usize>,+ deleted: bool,+ },+ /// Replaces a document's assignment links: adds, removes and reorders.+ Assign {+ row: usize,+ slots: Vec<usize>,+ },+ /// A journal barrier, as for records another engine changed.+ Invalidate {+ row: usize,+ },+ Unrelated(String),+}++fn property_value() -> impl Strategy<Value = PropertyValue> {+ prop_oneof![+ Just(PropertyValue::Null),+ prop::collection::vec("[a-c]", 0..3).prop_map(PropertyValue::Options),+ "[a-c]{0,2}".prop_map(PropertyValue::Text),+ ]+}++// Leaf edits and tombstones dominate so that compacted bindings get exercised.+fn edit() -> impl Strategy<Value = Edit> {+ prop_oneof![+ 1 => prop::collection::vec((0..ROWS, 0usize..3, property_value()), 0..=ROWS)+ .prop_map(Edit::Page),+ 4 => (0..ROWS, "[a-c]{1,2}").prop_map(|(row, value)| Edit::Scalar { row, value }),+ 3 => (0..ROWS, 0usize..3, property_value()).prop_map(|(row, slot, value)| Edit::Property {+ row,+ slot,+ value+ }),+ 3 => (0..ROWS, prop::option::weighted(0.3, 0usize..3), any::<bool>())+ .prop_map(|(row, slot, deleted)| Edit::Delete { row, slot, deleted }),+ 2 => (0..ROWS, prop::collection::vec(0usize..3, 0..4))+ .prop_map(|(row, slots)| Edit::Assign { row, slots }),+ 1 => (0..ROWS).prop_map(|row| Edit::Invalidate { row }),+ 1 => "[a-b]{0,2}".prop_map(Edit::Unrelated),+ ]+}++/// Even rows are documents with properties; odd rows are email threads.+fn is_document(row: usize) -> bool {+ row.is_multiple_of(2)+}++fn row_key(row: usize) -> EntityKey<'static> {+ if is_document(row) {+ EntityKey::entity("GraphqlSoupDocument", &[&format!("doc-{row}")])+ } else {+ EntityKey::entity("GraphqlSoupEmailThread", &[&format!("thread-{row}")])+ }+}++fn property_key(row: usize, slot: usize) -> EntityKey<'static> {+ EntityKey::entity("GraphqlProperty", &[&format!("property-{row}-{slot}")])+}++fn response_value(value: &PropertyValue) -> Json {+ match value {+ PropertyValue::Null => Json::Null,+ PropertyValue::Options(ids) => {+ json!({"kind": "GraphqlSelectOptionPropertyValue", "selected": ids})+ }+ PropertyValue::Text(text) => json!({"kind": "GraphqlStringPropertyValue", "text": text}),+ }+}++fn stored_value(value: &PropertyValue) -> CacheValue {+ let (typename, field, value) = match value {+ PropertyValue::Null => return CacheValue::Null,+ PropertyValue::Options(ids) => (+ "GraphqlSelectOptionPropertyValue",+ "optionIds",+ CacheValue::List(ids.iter().cloned().map(CacheValue::String).collect()),+ ),+ PropertyValue::Text(text) => (+ "GraphqlStringPropertyValue",+ "value",+ CacheValue::String(text.clone()),+ ),+ };+ CacheValue::Object(BTreeMap::from([+ ("__typename".into(), CacheValue::String(typename.into())),+ (field.into(), value),+ ]))+}++fn page(rows: &[(usize, usize, PropertyValue)]) -> Json {+ let items: Vec<_> = rows+ .iter()+ .map(|(row, count, value)| {+ if is_document(*row) {+ json!({+ "__typename": "GraphqlSoupDocument", "id": format!("doc-{row}"),+ "title": format!("doc {row}"),+ "properties": (0..*count).map(|slot| json!({+ "id": format!("property-{row}-{slot}"), "value": response_value(value)+ })).collect::<Vec<_>>()+ })+ } else {+ json!({"__typename": "GraphqlSoupEmailThread", "id": format!("thread-{row}"), "isRead": false})+ }+ })+ .collect();+ json!({"user": {"id": "viewer", "soup": {"items": items, "nextCursor": null}}})+}++async fn put(+ engine: &mut Engine<InMemoryStorage>,+ key: EntityKey<'static>,+ field: &str,+ value: CacheValue,+) {+ engine+ .put_records_with_projections(+ None,+ vec![(+ key,+ Record {+ fields: BTreeMap::from([(field.into(), value)]),+ },+ )],+ vec![],+ )+ .await+ .unwrap();+}++async fn run(engine: &mut Engine<InMemoryStorage>, edit: Edit) {+ match edit {+ Edit::Page(rows) => {+ engine+ .write_query(None, QUERY, None, &vars(), &page(&rows), None)+ .await+ .unwrap();+ }+ Edit::Scalar { row, value } => {+ let (field, value) = if is_document(row) {+ ("name", CacheValue::String(value))+ } else {+ ("isRead", CacheValue::Bool(value.len() == 1))+ };+ put(engine, row_key(row), field, value).await;+ }+ Edit::Property { row, slot, value } => {+ put(+ engine,+ property_key(row, slot),+ "value",+ stored_value(&value),+ )+ .await;+ }+ Edit::Delete { row, slot, deleted } => {+ let key = slot.map_or_else(|| row_key(row), |slot| property_key(row, slot));+ put(+ engine,+ key,+ identity::DELETED_FIELD,+ CacheValue::Bool(deleted),+ )+ .await;+ }+ Edit::Assign { row, slots } => {+ let links = slots+ .into_iter()+ .map(|slot| CacheValue::Ref(property_key(row, slot)))+ .collect();+ put(engine, row_key(row), "properties", CacheValue::List(links)).await;+ }+ Edit::Invalidate { row } => {+ engine.invalidate_keys([&row_key(row)]).unwrap();+ }+ Edit::Unrelated(value) => {+ let key = EntityKey::entity("GraphqlSoupDocument", &["unrelated"]);+ put(engine, key, "name", CacheValue::String(value)).await;+ }+ }+}++struct Subscriber {+ op: OpId,+ data: Json,+ cursor: Option<CacheRevision>,+}++impl Subscriber {+ async fn check(&mut self, engine: &mut Engine<InMemoryStorage>) -> Result<(), TestCaseError> {+ let update = engine+ .watch_query(self.op, QUERY, None, &vars(), &[], self.cursor)+ .await+ .unwrap();+ let full = engine.read_query(None, QUERY, None, &vars()).await.unwrap();+ match (update, full) {+ (QueryUpdate::Miss { .. }, ReadResult::Miss) => self.cursor = None,+ (update, ReadResult::Hit { data }) => {+ self.cursor = Some(apply(&mut self.data, update));+ prop_assert_eq!(&self.data, &data);+ }+ (update, ReadResult::Miss) => prop_assert!(false, "{update:?} for a missing query"),+ }+ Ok(())+ }+}++proptest! {+ #![proptest_config(ProptestConfig::with_cases(128))]+ #[test]+ fn applied_updates_match_full_reads(+ capacity in prop::sample::select(vec![1usize, DEFAULT_HOT_CAPACITY]),+ edits in prop::collection::vec((edit(), any::<bool>()), 1..24),+ ) {+ block_on(async {+ let mut engine = Engine::with_capacity(InMemoryStorage::new(), capacity);+ // Store every assignment, then link only the first so links can be added.+ for count in [3, 1] {+ let initial = (0..ROWS)+ .map(|row| (row, count, PropertyValue::Options(vec!["a".into()])))+ .collect();+ run(&mut engine, Edit::Page(initial)).await;+ }+ // The second subscriber skips reads, so its updates span several revisions.+ let mut subscribers = [1, 2].map(|op| Subscriber { op, data: Json::Null, cursor: None });+ for subscriber in &mut subscribers {+ subscriber.check(&mut engine).await?;+ }+ for (edit, read_second) in edits {+ run(&mut engine, edit).await;+ subscribers[0].check(&mut engine).await?;+ if read_second {+ subscribers[1].check(&mut engine).await?;+ }+ }+ subscribers[1].check(&mut engine).await+ })?;+ }+}diff --git a/crates/client/cache-core/tests/support/optimistic_model.rs b/crates/client/cache-core/tests/support/optimistic_model.rsindex 9efb743348..cd679f54ad 100644--- a/crates/client/cache-core/tests/support/optimistic_model.rs+++ b/crates/client/cache-core/tests/support/optimistic_model.rs@@ -294,7 +294,7 @@ impl Subscriber {.unwrap();let revision = match update {QueryUpdate::Hit { data, revision } => {- self.data = data;+ self.data = Json::clone(&data);revision}QueryUpdate::Patch { patches, revision } => {diff --git a/crates/client/cache-core/tests/watch_query_timing.rs b/crates/client/cache-core/tests/watch_query_timing.rsnew file mode 100644index 0000000000..91e28c5f52--- /dev/null+++ b/crates/client/cache-core/tests/watch_query_timing.rs@@ -0,0 +1,426 @@+//! Prints the worker-side cost of watched document queries on Soup-like pages:+//! leaf edits, structural edits, journal barriers and retained memory. Ignored+//! by default; run in release mode:+//! `cargo test --release -p cache-core --test watch_query_timing -- --ignored --nocapture`++use cache_core::engine::watch_query::QueryUpdate;+use cache_core::engine::{Engine, ReadResult};+use cache_core::identity::DELETED_FIELD;+use cache_core::revision::CacheRevision;+use cache_core::store::InMemoryStorage;+use cache_core::value::{CacheValue, EntityKey, Record};+use pollster::block_on;+use serde_json::{Map, Value as Json, json};+use std::alloc::{GlobalAlloc, Layout, System};+use std::collections::BTreeMap;+use std::sync::atomic::{AtomicIsize, Ordering};+use std::time::{Duration, Instant};++/// Tracks live heap bytes so the harness can report what a watch retains.+struct Counting;++static LIVE_BYTES: AtomicIsize = AtomicIsize::new(0);++// SAFETY: every method delegates to `System` with the caller's arguments.+unsafe impl GlobalAlloc for Counting {+ unsafe fn alloc(&self, layout: Layout) -> *mut u8 {+ LIVE_BYTES.fetch_add(layout.size() as isize, Ordering::Relaxed);+ // SAFETY: forwarded unchanged from the caller.+ unsafe { System.alloc(layout) }+ }++ unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8 {+ LIVE_BYTES.fetch_add(layout.size() as isize, Ordering::Relaxed);+ // SAFETY: forwarded unchanged from the caller.+ unsafe { System.alloc_zeroed(layout) }+ }++ unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {+ LIVE_BYTES.fetch_sub(layout.size() as isize, Ordering::Relaxed);+ // SAFETY: forwarded unchanged from the caller.+ unsafe { System.dealloc(ptr, layout) }+ }++ unsafe fn realloc(&self, ptr: *mut u8, layout: Layout, new_size: usize) -> *mut u8 {+ LIVE_BYTES.fetch_add(+ new_size as isize - layout.size() as isize,+ Ordering::Relaxed,+ );+ // SAFETY: forwarded unchanged from the caller.+ unsafe { System.realloc(ptr, layout, new_size) }+ }+}++#[global_allocator]+static ALLOCATOR: Counting = Counting;++const PAGE: &str = r#"+query Page($input: SoupInput!) {+ user { id soup(input: $input) { items {+ __typename id frecencyScore+ ... on GraphqlSoupDocument {+ documentName: name ownerId fileType projectId createdAt updatedAt viewedAt deletedAt+ subType { __typename ... on GraphqlTaskSubType { isCompleted } }+ properties { id propertyDefinitionId displayName dataType isMultiSelect value {+ __typename+ ... on GraphqlSelectOptionPropertyValue { optionIds }+ ... on GraphqlStringPropertyValue { value }+ } }+ }+ } nextCursor } }+}"#;+const SAMPLES: usize = 200;+const INITIAL_SAMPLES: usize = 40;+const OP: u64 = 1;++fn variables(rows: usize) -> Map<String, Json> {+ json!({"input": {"initial": {"limit": rows}}})+ .as_object()+ .unwrap()+ .clone()+}++fn page(rows: usize) -> Json {+ let items: Vec<_> = (0..rows)+ .map(|i| {+ json!({+ "__typename": "GraphqlSoupDocument",+ "id": format!("doc-{i}"),+ "frecencyScore": 0.5,+ "documentName": format!("Document {i}"),+ "ownerId": "macro|[email protected]",+ "fileType": "md",+ "projectId": if i % 3 == 0 { Json::Null } else { json!("project-1") },+ "createdAt": "2026-10-01T00:00:00Z",+ "updatedAt": "2026-10-02T00:00:00Z",+ "viewedAt": "2026-10-03T00:00:00Z",+ "deletedAt": null,+ "subType": {"__typename": "GraphqlTaskSubType", "isCompleted": false},+ "properties": [+ {+ "id": format!("status-{i}"), "propertyDefinitionId": "status",+ "displayName": "Status", "dataType": "SELECT_STRING", "isMultiSelect": false,+ "value": {"__typename": "GraphqlSelectOptionPropertyValue", "optionIds": ["todo"]}+ },+ {+ "id": format!("note-{i}"), "propertyDefinitionId": "note",+ "displayName": "Note", "dataType": "STRING", "isMultiSelect": false,+ "value": {"__typename": "GraphqlStringPropertyValue", "value": "note"}+ }+ ]+ })+ })+ .collect();+ json!({"user": {"id": "viewer", "soup": {"items": items, "nextCursor": null}}})+}++fn document(row: usize) -> EntityKey<'static> {+ EntityKey::entity("GraphqlSoupDocument", &[&format!("doc-{row}")])+}++fn property(id: &str) -> EntityKey<'static> {+ EntityKey::entity("GraphqlProperty", &[id])+}++fn string(value: &str) -> CacheValue {+ CacheValue::String(value.into())+}++fn options(ids: &[&str]) -> CacheValue {+ CacheValue::Object(BTreeMap::from([+ (+ "__typename".into(),+ string("GraphqlSelectOptionPropertyValue"),+ ),+ (+ "optionIds".into(),+ CacheValue::List(ids.iter().map(|id| string(id)).collect()),+ ),+ ]))+}++fn assignments(row: usize, extra: bool) -> CacheValue {+ let mut ids = vec![format!("status-{row}"), format!("note-{row}")];+ if extra {+ ids.push(format!("extra-{row}"));+ }+ CacheValue::List(ids.iter().map(|id| CacheValue::Ref(property(id))).collect())+}++async fn put(+ engine: &mut Engine<InMemoryStorage>,+ key: EntityKey<'static>,+ fields: Vec<(&str, CacheValue)>,+) {+ let fields = fields+ .into_iter()+ .map(|(field, value)| (field.to_owned(), value))+ .collect();+ engine+ .put_records_with_projections(None, vec![(key, Record { fields })], vec![])+ .await+ .unwrap();+}++fn revision(update: &QueryUpdate) -> CacheRevision {+ match update {+ QueryUpdate::Hit { revision, .. }+ | QueryUpdate::Patch { revision, .. }+ | QueryUpdate::Miss { revision } => revision.parse().unwrap(),+ }+}++fn micros(mut samples: Vec<Duration>) -> f64 {+ samples.sort();+ samples[samples.len() / 2].as_secs_f64() * 1e6+}++fn median(mut samples: Vec<usize>) -> usize {+ samples.sort();+ samples[samples.len() / 2]+}++/// One untimed change before a timed watched read.+enum Step {+ Put(EntityKey<'static>, &'static str, CacheValue),+ /// A journal barrier, as when another engine changed shared storage.+ Invalidate(EntityKey<'static>),+}++struct Watched {+ rows: usize,+ cursor: CacheRevision,+}++impl Watched {+ /// Applies `edit` untimed, then times one watched read and its encoding.+ async fn time(+ &mut self,+ engine: &mut Engine<InMemoryStorage>,+ case: &str,+ edit: impl Fn(usize) -> Vec<Step>,+ ) {+ let (mut reads, mut encodes, mut payloads, mut hits) =+ (Vec::new(), Vec::new(), Vec::new(), 0);+ for sample in 0..SAMPLES {+ for step in edit(sample) {+ match step {+ Step::Put(key, field, value) => put(engine, key, vec![(field, value)]).await,+ Step::Invalidate(key) => {+ engine.invalidate_keys([&key]).unwrap();+ }+ }+ }+ let start = Instant::now();+ let update = engine+ .watch_query(+ OP,+ PAGE,+ None,+ &variables(self.rows),+ &[],+ Some(self.cursor),+ )+ .await+ .unwrap();+ reads.push(start.elapsed());+ self.cursor = revision(&update);+ let start = Instant::now();+ let encoded = serde_json::to_string(&update).unwrap();+ encodes.push(start.elapsed());+ payloads.push(encoded.len());+ match update {+ QueryUpdate::Hit { .. } => hits += 1,+ QueryUpdate::Patch { .. } => {}+ QueryUpdate::Miss { .. } => panic!("{case}: seeded page must not miss"),+ }+ }+ let kind = match hits {+ 0 => "patch",+ SAMPLES => "hit",+ _ => "mixed",+ };+ println!(+ "| {} | {case} | {kind} | {:.1} µs | {:.1} µs | {} B |",+ self.rows,+ micros(reads),+ micros(encodes),+ median(payloads),+ );+ }++ /// Brings the subscriber up to date without timing.+ async fn sync(&mut self, engine: &mut Engine<InMemoryStorage>) {+ let update = engine+ .watch_query(+ OP,+ PAGE,+ None,+ &variables(self.rows),+ &[],+ Some(self.cursor),+ )+ .await+ .unwrap();+ self.cursor = revision(&update);+ }+}++#[test]+#[ignore = "prints timings; run in release mode"]+fn watch_query_costs() {+ println!("| rows | case | update | worker: watch_query | encode update | payload |");+ println!("|---:|---|---|---:|---:|---:|");+ let mut summary = Vec::new();+ for rows in [100, 500] {+ block_on(async {+ let mut engine = Engine::new(InMemoryStorage::new());+ let variables = variables(rows);+ engine+ .write_query(None, PAGE, None, &variables, &page(rows), None)+ .await+ .unwrap();+ for row in 0..rows {+ let id = format!("extra-{row}");+ put(+ &mut engine,+ property(&id),+ vec![+ ("__typename", string("GraphqlProperty")),+ ("id", string(&id)),+ ("propertyDefinitionId", string("extra")),+ ("displayName", string("Extra")),+ ("dataType", string("SELECT_STRING")),+ ("isMultiSelect", CacheValue::Bool(false)),+ ("value", options(&["added"])),+ ],+ )+ .await;+ }++ let mut reads = Vec::new();+ let mut encodes = Vec::new();+ for _ in 0..SAMPLES {+ let start = Instant::now();+ let result = engine+ .read_query(None, PAGE, None, &variables)+ .await+ .unwrap();+ reads.push(start.elapsed());+ let ReadResult::Hit { data } = result else {+ panic!("seeded page must hit");+ };+ let start = Instant::now();+ std::hint::black_box(serde_json::to_string(&data).unwrap());+ encodes.push(start.elapsed());+ }++ let mut initial = Vec::new();+ for sample in 0..INITIAL_SAMPLES {+ let op = 1_000 + sample as u64;+ let start = Instant::now();+ let update = engine+ .watch_query(op, PAGE, None, &variables, &[], None)+ .await+ .unwrap();+ initial.push(start.elapsed());+ drop(update);+ engine.teardown_operation(op);+ }+ let before = LIVE_BYTES.load(Ordering::Relaxed);+ let first = engine+ .watch_query(OP, PAGE, None, &variables, &[], None)+ .await+ .unwrap();+ let cursor = revision(&first);+ let hit_bytes = serde_json::to_string(&first).unwrap().len();+ drop(first);+ let retained = LIVE_BYTES.load(Ordering::Relaxed) - before;+ summary.push(format!(+ "| {rows} | {:.1} µs | {:.1} µs | {:.1} µs | {hit_bytes} B | {:.0} KiB |",+ micros(reads),+ micros(encodes),+ micros(initial),+ retained as f64 / 1024.0,+ ));++ let mut watched = Watched { rows, cursor };+ let row = |sample: usize| sample * 7 % rows;+ let rename = |key, prefix: &str, sample: usize| {+ Step::Put(+ key,+ "name",+ CacheValue::String(format!("{prefix} {sample}")),+ )+ };+ watched+ .time(&mut engine, "leaf: row field", |sample| {+ vec![rename(document(row(sample)), "Renamed", sample)]+ })+ .await;+ watched+ .time(&mut engine, "leaf: nested property", |sample| {+ let id = format!("status-{}", row(sample));+ let value = options(&[&format!("option-{sample}")]);+ vec![Step::Put(property(&id), "value", value)]+ })+ .await;+ watched+ .time(&mut engine, "unrelated record", |sample| {+ let key = EntityKey::entity("GraphqlSoupDocument", &["unrelated"]);+ vec![rename(key, "Unrelated", sample)]+ })+ .await;+ watched+ .time(&mut engine, "link: add / remove an assignment", |sample| {+ let target = row(sample / 2);+ let links = assignments(target, sample % 2 == 0);+ vec![Step::Put(document(target), "properties", links)]+ })+ .await;+ watched+ .time(&mut engine, "barrier: leaf edit + invalidation", |sample| {+ let key = document(row(sample));+ vec![+ rename(key.clone(), "Barrier", sample),+ Step::Invalidate(key),+ ]+ })+ .await;+ watched+ .time(&mut engine, "tombstone / restore an item", |sample| {+ let deleted = CacheValue::Bool(sample % 2 == 0);+ vec![Step::Put(document(row(sample / 2)), DELETED_FIELD, deleted)]+ })+ .await;+ put(+ &mut engine,+ document(0),+ vec![(DELETED_FIELD, CacheValue::Bool(true))],+ )+ .await;+ watched.sync(&mut engine).await;+ watched+ .time(+ &mut engine,+ "leaf: row field, list has a tombstone",+ |sample| {+ vec![rename(+ document(1 + row(sample) % (rows - 1)),+ "After",+ sample,+ )]+ },+ )+ .await;+ });+ }+ println!();+ println!(+ "| rows | full read_query | encode result | initial watch (Hit) | Hit payload | retained by first watch |"+ );+ println!("|---:|---:|---:|---:|---:|---:|");+ for line in summary {+ println!("{line}");+ }+}diff --git a/crates/client/cache-turso/src/storage/test/optimistic_atomicity.rs b/crates/client/cache-turso/src/storage/test/optimistic_atomicity.rsindex 1478ac0014..7193c2e8b3 100644--- a/crates/client/cache-turso/src/storage/test/optimistic_atomicity.rs+++ b/crates/client/cache-turso/src/storage/test/optimistic_atomicity.rs@@ -192,7 +192,7 @@ fn every_statement_failure_preserves_the_queue_and_live_view_until_retry() {.await.unwrap(){- QueryUpdate::Hit { data, .. } => assert_eq!(data, before),+ QueryUpdate::Hit { data, .. } => assert_eq!(*data, before),QueryUpdate::Patch { patches, .. } => assert!(patches.is_empty()),QueryUpdate::Miss { .. } => panic!("failed write lost the watched query"),}diff --git a/crates/client/cache-wasm/Cargo.toml b/crates/client/cache-wasm/Cargo.tomlindex 6cd59a8c56..0662858f26 100644--- a/crates/client/cache-wasm/Cargo.toml+++ b/crates/client/cache-wasm/Cargo.toml@@ -2,8 +2,8 @@edition = "2024"name = "cache-wasm"publish = false-# Rebuild to check watch patch values for unsafe integers.-version = "0.6.45"+# Rebuild for patched structural query changes and checked patch integers.+version = "0.6.47"[features]default = []diff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rsindex 68d5da4474..a5ad061cee 100644--- a/crates/client/cache-wasm/src/shell.rs+++ b/crates/client/cache-wasm/src/shell.rs@@ -1104,7 +1104,7 @@ fn query_update_values() -> Vec<&serde_json::Value> {use cache_core::engine::watch_query::QueryUpdate;match update {- QueryUpdate::Hit { data, .. } => vec![data],+ QueryUpdate::Hit { data, .. } => vec![data.as_ref()],QueryUpdate::Patch { patches, .. } => patches.iter().map(|patch| &patch.value).collect(),QueryUpdate::Miss { .. } => Vec::new(),}diff --git a/crates/client/cache-wasm/src/shell/test.rs b/crates/client/cache-wasm/src/shell/test.rsindex c73205615d..43e0afce67 100644--- a/crates/client/cache-wasm/src/shell/test.rs+++ b/crates/client/cache-wasm/src/shell/test.rs@@ -90,7 +90,7 @@ fn watch_patches_reject_unsafe_integers_like_hits() {use cache_core::engine::watch_query::QueryUpdate;let value = serde_json::json!({"nested": [{"value": 9_007_199_254_740_992_u64}]});let hit = QueryUpdate::Hit {- data: value.clone(),+ data: std::sync::Arc::new(value.clone()),revision: "1".into(),};let patch = QueryUpdate::Patch {