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
Seanaye/perf/scoped cache change (#7265)
Sean Aye40a7bb846e14
diff --git a/Cargo.lock b/Cargo.lockindex 583eae8407..004d677094 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -3312,7 +3312,7 @@ dependencies = [[[package]]name = "cache-wasm"-version = "0.6.32"+version = "0.6.33"dependencies = ["async-lock","cache-core",diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.test.tsindex b8b1a2e401..c9193b4297 100644--- a/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts@@ -566,6 +566,23 @@ describe('createTauriCacheHost', () => {});+ it.each(+ [[], ['note']].map((searchChangedBuckets) => ({ searchChangedBuckets }))+ )(+ 'forwards ordinary native writes and keeps resets conservative: $searchChangedBuckets',+ ({ searchChangedBuckets }) => {+ const host = createTauriCacheHost({ scope: 'scope-1' });+ const listener = vi.fn();+ host.onCacheChanged(listener);+ const notify = eventCallbacks.get('graphql-cache://cache-changed')!;+ notify({ payload: { revision: '7', searchChangedBuckets } });+ expect(listener).toHaveBeenLastCalledWith('7', { searchChangedBuckets });+ notify({ payload: { revision: '8', searchChangedBuckets, reset: true } });+ expect(listener).toHaveBeenLastCalledWith('8');+ host.dispose();+ }+ );+it('delivers cross-window hydration only to opted-in listeners', async () => {const host = createTauriCacheHost({ scope: 'scope-1' });const foreground = vi.fn();diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.tsindex d9c8f36fe6..fa0e535ef2 100644--- a/apps/web/src/lib/graphql-cache/host/tauri-host.ts+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.ts@@ -177,7 +177,17 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {if (event.payload.reset) {for (const cb of generationChangeSubscribers) cb({ storage: 'reset' });}- for (const cb of cacheChangeSubscribers) cb(revision);+ for (const cb of cacheChangeSubscribers) {+ if (+ event.payload.reset ||+ event.payload.searchChangedBuckets === undefined+ )+ cb(revision);+ else+ cb(revision, {+ searchChangedBuckets: event.payload.searchChangedBuckets,+ });+ }}).catch((error) => {console.warn('graphql cache change listener failed', error);return undefined;diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.test.tsindex 9e3afc4340..85c7a2f04a 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts@@ -1159,6 +1159,34 @@ describe('createWorkerCacheHost', () => {});+ it.each(+ [[], ['note']].map((searchChangedBuckets) => ({ searchChangedBuckets }))+ )(+ 'forwards query-write metadata and ignores it on reset: $searchChangedBuckets',+ async ({ searchChangedBuckets }) => {+ const host = createWorkerCacheHost({ scope: 'scope-1' });+ const listener = vi.fn();+ host.onCacheChanged(listener);+ await host.currentRevision();+ requireAdapter().push({+ kind: 'cache-changed',+ revision: INITIAL_CACHE_REVISION,+ searchChangedBuckets,+ });+ expect(listener).toHaveBeenLastCalledWith(INITIAL_CACHE_REVISION, {+ searchChangedBuckets,+ });+ requireAdapter().push({+ kind: 'cache-changed',+ revision: INITIAL_CACHE_REVISION,+ searchChangedBuckets,+ reset: true,+ });+ expect(listener).toHaveBeenLastCalledWith(INITIAL_CACHE_REVISION);+ host.dispose();+ }+ );+it('delivers hydration only to opted-in subscribers and cleans them up', async () => {const host = createWorkerCacheHost({ scope: 'scope-1' });const foreground = vi.fn();diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.tsindex a1d54b37f4..b42920d7f6 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts@@ -305,7 +305,14 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {for (const cb of generationChangeSubscribers)cb({ storage: 'reset' });}- for (const cb of cacheChangeSubscribers) cb(msg.revision);+ for (const cb of cacheChangeSubscribers) {+ if (msg.reset || msg.searchChangedBuckets === undefined)+ cb(msg.revision);+ else+ cb(msg.revision, {+ searchChangedBuckets: msg.searchChangedBuckets,+ });+ }return;}if (msg.kind === 'mutation-settled') {diff --git a/apps/web/src/lib/graphql-cache/protocol.test.ts b/apps/web/src/lib/graphql-cache/protocol.test.tsindex b97e9a369f..acb14629ee 100644--- a/apps/web/src/lib/graphql-cache/protocol.test.ts+++ b/apps/web/src/lib/graphql-cache/protocol.test.ts@@ -145,6 +145,16 @@ describe('cache worker message validators', () => {},{ kind: 'ops-affected', opIds: ['client:7'], keys: ['User:1'] },{ kind: 'cache-changed', revision: INITIAL_CACHE_REVISION },+ {+ kind: 'cache-changed',+ revision: INITIAL_CACHE_REVISION,+ searchChangedBuckets: [],+ },+ {+ kind: 'cache-changed',+ revision: INITIAL_CACHE_REVISION,+ searchChangedBuckets: ['note'],+ },{ kind: 'cache-hydrated', revision: INITIAL_CACHE_REVISION },{kind: 'cache-hydrated',@@ -195,6 +205,8 @@ describe('cache worker message validators', () => {{ kind: 'ops-affected', opIds: [7], keys: [] },{ kind: 'ops-affected', opIds: [], keys: [], extra: true },{ kind: 'cache-changed', keys: [] },+ { kind: 'cache-changed', revision: '1', searchChangedBuckets: 'note' },+ { kind: 'cache-changed', revision: '1', searchChangedBuckets: [1] },{ kind: 'cache-hydrated', revision: 1 },{ kind: 'cache-hydrated', revision: '1', extra: true },{ kind: 'cache-hydrated', revision: '1', searchChangedBuckets: 'note' },diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.tsindex 9ed4eb03c7..5fd8aa235f 100644--- a/apps/web/src/lib/graphql-cache/protocol.ts+++ b/apps/web/src/lib/graphql-cache/protocol.ts@@ -355,7 +355,7 @@ export type HydrationResult = HydrationSearchChanges &| { kind: 'void'; revision: CacheRevision });-export type WriteResult = {+export type WriteResult = HydrationSearchChanges & {/** Effective-view revision installed by this logical mutation. */revision: CacheRevision;/** Whether this write advanced `revision`. */@@ -632,7 +632,11 @@ export type CachePush =/** Changed entity keys, for diagnostics/advanced consumers. */keys: string[];}- | { kind: 'cache-changed'; revision: CacheRevision; reset?: boolean }+ | ({+ kind: 'cache-changed';+ revision: CacheRevision;+ reset?: boolean;+ } & HydrationSearchChanges)| ({kind: 'cache-hydrated';revision: CacheRevision;@@ -721,9 +725,16 @@ export function isCachePush(value: unknown): value is CachePush {);case 'cache-changed':return (- hasOnlyWireKeys(value, ['kind', 'revision', 'reset']) &&+ hasOnlyWireKeys(value, [+ 'kind',+ 'revision',+ 'reset',+ 'searchChangedBuckets',+ ]) &&isCacheRevision(value.revision) &&- (value.reset === undefined || typeof value.reset === 'boolean')+ (value.reset === undefined || typeof value.reset === 'boolean') &&+ (value.searchChangedBuckets === undefined ||+ isWireStringArray(value.searchChangedBuckets)));case 'cache-hydrated':return (diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.tsindex 39a600a75a..769c77ea7a 100644--- a/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.ts+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.ts@@ -12,6 +12,7 @@ export default defineConfig({'notification-projection.browser.e2e.ts','mail-projection.browser.e2e.ts','mail-tabs.browser.e2e.ts',+ 'query-write-scope.browser.e2e.ts',],timeout: 90_000,fullyParallel: false,diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/query-write-scope.browser.e2e.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/query-write-scope.browser.e2e.tsnew file mode 100644index 0000000000..b5a101d8c2--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/query-write-scope.browser.e2e.ts@@ -0,0 +1,23 @@+import { expect, test } from '@playwright/test';++test('query-page writes stay quiet while shared entity changes refresh readers', async ({+ page,+}) => {+ await page.goto('query-write-scope.html');+ const result = page.locator('#result');+ await expect(result).toHaveAttribute('data-status', 'ready');+ await page.getByRole('button', { name: 'Add unrelated query page' }).click();+ await expect(result).toHaveAttribute('data-status', 'passed');+ expect(JSON.parse((await result.textContent())!)).toEqual({+ affected: [],+ searchRefreshes: 0,+ names: ['Original', 'Original'],+ });+ await page.getByRole('button', { name: 'Rename shared document' }).click();+ await expect(result).toContainText('Renamed');+ expect(JSON.parse((await result.textContent())!)).toEqual({+ affected: [[1, 2]],+ searchRefreshes: 1,+ names: ['Renamed', 'Renamed'],+ });+});diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/query-write-scope.html b/apps/web/src/lib/graphql-cache/worker/browser-test/query-write-scope.htmlnew file mode 100644index 0000000000..b5e437a0ac--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/query-write-scope.html@@ -0,0 +1,10 @@+<!doctype html>+<html lang="en">+ <head><meta charset="utf-8" /><link rel="icon" href="data:," /><title>Query write scope regression</title></head>+ <body>+ <button id="page" disabled>Add unrelated query page</button>+ <button id="rename" disabled>Rename shared document</button>+ <pre id="result" data-status="loading"></pre>+ <script type="module" src="./query-write-scope.ts"></script>+ </body>+</html>diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/query-write-scope.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/query-write-scope.tsnew file mode 100644index 0000000000..b7a0e5f056--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/query-write-scope.ts@@ -0,0 +1,109 @@+// Production host + WASM/OPFS, with synthetic responses only. No auth or hosted+// data is required. Exercise the same scoped subscriber used by Quick Access.+import { subscribeToVisibleCacheChanges } from '@queries/subscribe-to-visible-cache-changes';+import { createRoot } from 'solid-js';+import { createWorkerCacheHost } from '../../host/worker-host';++const result = document.querySelector<HTMLPreElement>('#result')!;+const pageButton = document.querySelector<HTMLButtonElement>('#page')!;+const renameButton = document.querySelector<HTMLButtonElement>('#rename')!;+const host = createWorkerCacheHost({+ scope: `query-write-scope-${crypto.randomUUID()}`,+});+const query = `query Page($input: SoupInput!) { user { id soup(input: $input) { items { __typename id ... on GraphqlSoupDocument { name fileType } } } } }`;+const variables = (limit: number) => ({ input: { initial: { limit } } });+const data = (name: string) => ({+ user: {+ id: 'fixture-viewer',+ soup: {+ items: [+ {+ __typename: 'GraphqlSoupDocument',+ id: 'fixture-doc',+ name,+ fileType: 'md',+ },+ ],+ },+ },+});+const affected: number[][] = [];+const names = new Map<number, string>();+let searchRefreshes = 0;+let dispose = () => {};++function display(status: string) {+ result.dataset.status = status;+ result.textContent = JSON.stringify({+ affected,+ searchRefreshes,+ names: [...names.values()],+ });+}+async function read(opKey: number) {+ const response = await host.readQuery({+ opKey,+ query,+ variables: variables(opKey),+ });+ if (response.kind !== 'hit') throw new Error(`page ${opKey} missed`);+ const value = response.data as ReturnType<typeof data>;+ names.set(opKey, value.user.soup.items[0].name);+}+async function write(limit: number, name: string) {+ await host.writeQuery({+ query,+ variables: variables(limit),+ data: data(name),+ });+}+async function run(limit: number, name: string) {+ pageButton.disabled = renameButton.disabled = true;+ try {+ await write(limit, name);+ // Push callbacks are delivered before the write response. Re-read just the+ // operations the host invalidated, as the exchange would, not every page.+ for (const key of new Set(affected.flat())) await read(key);+ display('passed');+ } catch (error) {+ result.dataset.status = 'failed';+ result.textContent = String(error);+ } finally {+ pageButton.disabled = renameButton.disabled = false;+ }+}+try {+ await write(1, 'Original');+ await write(2, 'Original');+ await read(1);+ await read(2);+ host.onOpsAffected((keys) => affected.push(keys));+ createRoot((cleanup) => {+ const unsubscribe = subscribeToVisibleCacheChanges(+ host,+ () => {+ searchRefreshes++;+ },+ { searchBuckets: () => ['note'] }+ );+ dispose = () => {+ unsubscribe();+ cleanup();+ };+ });+ pageButton.addEventListener('click', () => void run(3, 'Original'));+ renameButton.addEventListener('click', () => void run(3, 'Renamed'));+ pageButton.disabled = renameButton.disabled = false;+ display('ready');+} catch (error) {+ result.dataset.status = 'failed';+ result.textContent = String(error);+}+window.addEventListener(+ 'pagehide',+ () => {+ dispose();+ host.dispose();+ },+ { once: true }+);diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.tsindex e4df0f10fd..9411ebabfa 100644--- a/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.ts+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.ts@@ -53,6 +53,7 @@ export default defineConfig(({ command }) => ({'cache-recovery.html','notification-projection.html','mail-projection.html',+ 'query-write-scope.html',].map((name) => [name.replace('.html', ''), resolve(directory, name)])),},diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.test.tsindex 7136a905c4..156d9e0cf5 100644--- a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts@@ -972,6 +972,46 @@ describe('CacheWorkerCore', () => {});});+ it.each([+ { searchChangedBuckets: [], reset: false },+ { searchChangedBuckets: ['note'], reset: false },+ { searchChangedBuckets: [], reset: true },+ ])(+ 'scopes ordinary writes but not resets: %j',+ async ({ searchChangedBuckets, reset }) => {+ loadCacheWasmMock.mockResolvedValue({+ openCache: vi.fn().mockResolvedValue({+ writeQuery: vi.fn().mockResolvedValue({+ revision: INITIAL_CACHE_REVISION,+ revisionAdvanced: true,+ changed: ['GraphqlUser:viewer'],+ affectedOps: [],+ reset,+ searchChangedBuckets,+ }),+ }),+ });+ const messages: unknown[] = [];+ const port = {+ postMessage: (message: unknown) => messages.push(message),+ };+ const core = new CacheWorkerCore();+ core.addPort(port);+ await core.handleRequest(port, { id: 1, kind: 'init', scope: 'scope-1' });+ await core.handleRequest(port, {+ id: 2,+ kind: 'write',+ query: '{ user { id } }',+ data: { user: { id: 'viewer' } },+ });+ expect(messages).toContainEqual({+ kind: 'cache-changed',+ revision: INITIAL_CACHE_REVISION,+ ...(reset ? { reset: true } : { searchChangedBuckets }),+ });+ }+ );+it('does not push cache changes for no-op writes', async () => {const writeResult = {revision: INITIAL_CACHE_REVISION,diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.tsindex 99a5914480..039b4c5385 100644--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts@@ -1040,6 +1040,9 @@ export class CacheWorkerCore {this.push({kind: 'cache-changed',revision: result.revision,+ ...(!result.reset && result.searchChangedBuckets !== undefined+ ? { searchChangedBuckets: result.searchChangedBuckets }+ : {}),...(result.reset ? { reset: true } : {}),});}diff --git a/apps/web/tauri/graphql_cache_plugin/src/commands.rs b/apps/web/tauri/graphql_cache_plugin/src/commands.rsindex e8ab6ea14d..3311366872 100644--- a/apps/web/tauri/graphql_cache_plugin/src/commands.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/commands.rs@@ -17,7 +17,8 @@ use crate::engine::{WriteResultWire,};use crate::{- CacheState, InitializedCache, emit_cache_changed, emit_mutation_settled, emit_ops_affected,+ CacheState, InitializedCache, emit_cache_changed, emit_cache_changed_with_search_changes,+ emit_mutation_settled, emit_ops_affected,};use cache_core::entity_resolver::EntityResolver;use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};@@ -191,7 +192,12 @@ pub async fn graphql_cache_write<R: Runtime>(.await?;emit_ops_affected(&app, &result.affected_ops, &result.changed);if result.revision_advanced {- emit_cache_changed(&app, &result.revision, result.reset);+ emit_cache_changed_with_search_changes(+ &app,+ &result.revision,+ result.reset,+ result.search_changed_buckets.as_ref(),+ );}Ok(result)}diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine.rs b/apps/web/tauri/graphql_cache_plugin/src/engine.rsindex df07d6769d..b861492ccf 100644--- a/apps/web/tauri/graphql_cache_plugin/src/engine.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/engine.rs@@ -59,6 +59,9 @@ pub struct WriteResultWire {pub revision: String,/// Whether this write advanced `revision`.pub revision_advanced: bool,+ /// Known search changes for query responses; absent for conservative refreshes.+ #[serde(skip_serializing_if = "Option::is_none")]+ pub search_changed_buckets: Option<std::collections::BTreeSet<String>>,/// Entity keys whose records changed.pub changed: Vec<String>,/// Registered operation ids affected by the change (origin excluded).@@ -365,6 +368,7 @@ fn wire_write_result(ops: &OpInterner, result: WriteResult) -> WriteResultWire {WriteResultWire {revision: result.revision.to_string(),revision_advanced: result.revision_advanced,+ search_changed_buckets: result.search_changed_buckets,changed: result.changed.into_iter()diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rsindex 6d2fa7f9c2..8081cf9383 100644--- a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs@@ -100,6 +100,7 @@ fn empty_write_result() -> WriteResultWire {WriteResultWire {revision: "0".to_string(),revision_advanced: false,+ search_changed_buckets: None,changed: Vec::new(),affected_ops: Vec::new(),reset: false,@@ -107,6 +108,40 @@ fn empty_write_result() -> WriteResultWire {}}+#[test]+fn query_writes_preserve_search_proof_and_viewer_field_scope_through_native_wire() {+ let handle = spawn_handle();+ write(&handle, None, soup_data(false), Some("viewer"));+ read(&handle, Some("client:1"));+ let mut other = variables();+ other.insert("input".into(), serde_json::json!({"limit":2}));+ let result = block_on(handle.write(WriteRequest {+ origin_op_id: None,+ registration: None,+ query: QUERY.into(),+ operation_name: Some("Soup".into()),+ variables: other,+ data: soup_data(false),+ identity: Some("viewer".into()),+ }))+ .unwrap();+ assert!(result.revision_advanced);+ assert!(result.affected_ops.is_empty());+ assert_eq!(+ serde_json::to_value(result).unwrap()["searchChangedBuckets"],+ serde_json::json!([])+ );+ let reset = write(&handle, None, soup_data(false), Some("new-viewer"));+ assert!(reset.reset);+ assert!(+ serde_json::to_value(reset)+ .unwrap()+ .get("searchChangedBuckets")+ .is_none()+ );+ handle.shutdown().unwrap();+}+#[test]fn tagged_wire_enum_fields_are_camel_case() {assert_eq!(diff --git a/apps/web/tauri/graphql_cache_plugin/src/lib.rs b/apps/web/tauri/graphql_cache_plugin/src/lib.rsindex 472ec23457..608695f472 100644--- a/apps/web/tauri/graphql_cache_plugin/src/lib.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/lib.rs@@ -57,6 +57,9 @@ pub struct OpsAffectedEvent {#[derive(Clone, Debug, Serialize)]#[serde(rename_all = "camelCase")]pub struct CacheChangedEvent {+ /// Known query-write changes; missing metadata requests a conservative refresh.+ #[serde(skip_serializing_if = "Option::is_none")]+ pub search_changed_buckets: Option<std::collections::BTreeSet<String>>,/// Effective-view revision installed by the logical mutation.pub revision: String,/// Present when the write cleared durable records and hydration must restart.@@ -113,9 +116,23 @@ fn emit_ops_affected<R: Runtime>(app: &AppHandle<R>, op_ids: &[String], keys: &[}fn emit_cache_changed<R: Runtime>(app: &AppHandle<R>, revision: &str, reset: bool) {+ emit_cache_changed_with_search_changes(app, revision, reset, None);+}++fn emit_cache_changed_with_search_changes<R: Runtime>(+ app: &AppHandle<R>,+ revision: &str,+ reset: bool,+ search_changed_buckets: Option<&std::collections::BTreeSet<String>>,+) {app.emit(CACHE_CHANGED_EVENT,CacheChangedEvent {+ search_changed_buckets: if reset {+ None+ } else {+ search_changed_buckets.cloned()+ },revision: revision.to_owned(),reset: reset.then_some(true),},diff --git a/crates/client/README.md b/crates/client/README.mdindex e06ac46d27..66eceedb2b 100644--- a/crates/client/README.md+++ b/crates/client/README.md@@ -68,6 +68,21 @@ generation, normalized entities, projection facts, queue and optimistic shadows.Subsequent opens only check the marker. There is no schema/namespace bump, reset,or VACUUM; freed pages can be reused without rewriting the whole database file.+## Query-write invalidation++Ordinary query responses carry optional `searchChangedBuckets`, using the same+composed-view comparison as hydration. An empty list proves that Quick Access+needs no refresh; missing metadata, mutations, subscriptions and identity resets+remain conservative. Both browser-worker and native hosts preserve this distinction.++Active queries track the canonical top-level fields they select on `GraphqlUser`,+including argument-qualified Soup pages. Query writes only wake readers of changed+viewer fields, while document/property/etc. changes still invalidate by record.+Normalization installs the same dependencies as cache reads, without another read.+Missing records, incomplete response registrations, explicit invalidations/deletions+and resets retain conservative behavior. Page-retention eviction wakes readers of+the removed page. This is in-memory dependency tracking, not a storage migration.+## Entity-rooted optimistic relationsLink recipes may use an optional `recordRoot` (`fragmentName`, `entityKey`).diff --git a/crates/client/cache-core/src/denormalize.rs b/crates/client/cache-core/src/denormalize.rsindex 47cecc5247..c8c7fe11c8 100644--- a/crates/client/cache-core/src/denormalize.rs+++ b/crates/client/cache-core/src/denormalize.rs@@ -7,6 +7,7 @@//! field is a cache miss (Phase 1: no partial results — nullability-based//! partials are a later phase; the metadata is already generated).+use crate::deps::DependencyTracker;use crate::document::{FieldNode, MissingVariable, Operation, Selection, resolve_args, resolved_args_key,};@@ -65,7 +66,7 @@ pub fn denormalize(op: &Operation,variables: &serde_json::Map<String, Json>,source: &impl RecordSource,- deps: &mut BTreeSet<EntityKey<'static>>,+ deps: &mut impl DependencyTracker,) -> Result<ReadOutcome, DenormalizeError> {denormalize_with_entity_resolvers(op,@@ -81,7 +82,7 @@ pub fn denormalize_with_entity_resolvers(op: &Operation,variables: &serde_json::Map<String, Json>,source: &impl RecordSource,- deps: &mut BTreeSet<EntityKey<'static>>,+ deps: &mut impl DependencyTracker,entity_resolvers: &EntityResolverLookup,) -> Result<ReadOutcome, DenormalizeError> {denormalize_record_with_entity_resolvers(@@ -102,7 +103,7 @@ pub fn denormalize_record(selections: &[Selection],variables: &serde_json::Map<String, Json>,source: &impl RecordSource,- deps: &mut BTreeSet<EntityKey<'static>>,+ deps: &mut impl DependencyTracker,) -> Result<ReadOutcome, DenormalizeError> {denormalize_record_with_entity_resolvers(key,@@ -121,7 +122,7 @@ fn denormalize_record_with_entity_resolvers(selections: &[Selection],variables: &serde_json::Map<String, Json>,source: &impl RecordSource,- deps: &mut BTreeSet<EntityKey<'static>>,+ deps: &mut impl DependencyTracker,entity_resolvers: &EntityResolverLookup,) -> Result<ReadOutcome, DenormalizeError> {let mut walk = Walk {@@ -149,17 +150,17 @@ fn denormalize_record_with_entity_resolvers(}}-struct Walk<'a, S: RecordSource> {+struct Walk<'a, S: RecordSource, D: DependencyTracker> {variables: &'a serde_json::Map<String, Json>,source: &'a S,- deps: &'a mut BTreeSet<EntityKey<'static>>,+ deps: &'a mut D,entity_resolvers: &'a EntityResolverLookup,missing_records: BTreeSet<EntityKey<'static>>,/// First field-level miss encountered.miss: Option<(EntityKey<'static>, String)>,}-impl<'a, S: RecordSource> Walk<'a, S> {+impl<'a, S: RecordSource, D: DependencyTracker> Walk<'a, S, D> {/// Reads a full record by key. Returns `None` when the outcome is/// already determined to be incomplete (missing record / miss noted).fn read_record(@@ -168,7 +169,7 @@ impl<'a, S: RecordSource> Walk<'a, S> {type_name: &str,selections: &[Selection],) -> Result<Option<Json>, DenormalizeError> {- self.deps.insert(key.clone());+ self.deps.record(key);let Some(record) = self.source.get(key) else {self.missing_records.insert(key.clone());return Ok(None);@@ -176,6 +177,7 @@ impl<'a, S: RecordSource> Walk<'a, S> {// Clone is cheap relative to the walk; keeps borrows simple.let record = record.clone();let concrete = record.typename().unwrap_or(type_name).to_string();+ self.deps.field(key, &concrete, "__typename");self.read_fields(key, &record.fields, &concrete, selections)}@@ -214,6 +216,7 @@ impl<'a, S: RecordSource> Walk<'a, S> {};let args_key = resolved_args_key(f, &arguments);let storage_key = field_key(&f.name, args_key.as_deref());+ self.deps.field(owner, concrete, &storage_key);if let Some(entity_resolver) = entity_resolver {let Some(target_key) = entity_resolver.entity_key(&arguments) else {diff --git a/crates/client/cache-core/src/deps.rs b/crates/client/cache-core/src/deps.rsindex b477a9635c..e3ddd45bac 100644--- a/crates/client/cache-core/src/deps.rs+++ b/crates/client/cache-core/src/deps.rs@@ -7,12 +7,19 @@use crate::value::EntityKey;use std::collections::{BTreeSet, HashMap, HashSet};+mod viewer;+pub use viewer::DependencyTracker;+pub(crate) use viewer::{+ QueryDependencies, ViewerFieldUpdate, ViewerFields, changed_viewer_fields,+};+pub type OpId = u64;#[derive(Debug, Default)]pub struct DepIndex {by_op: HashMap<OpId, BTreeSet<EntityKey<'static>>>,by_key: HashMap<EntityKey<'static>, HashSet<OpId>>,+ viewer_fields: HashMap<OpId, ViewerFields>,broad_ops: BTreeSet<OpId>,}@@ -30,6 +37,12 @@ impl DepIndex {self.by_op.insert(op, deps);}+ /// Installs viewer-field proof alongside ordinary record dependencies.+ pub(crate) fn set_query_deps(&mut self, op: OpId, deps: QueryDependencies) {+ self.set_op_deps(op, deps.records);+ self.viewer_fields.insert(op, deps.viewer_fields);+ }+/// Registers an operation conservatively against every visible change.pub fn set_op_broad(&mut self, op: OpId) {self.remove_op(op);@@ -40,6 +53,7 @@ impl DepIndex {/// Unregisters an operation (urql teardown).pub fn remove_op(&mut self, op: OpId) {self.broad_ops.remove(&op);+ self.viewer_fields.remove(&op);if let Some(old) = self.by_op.remove(&op) {for key in old {if let Some(set) = self.by_key.get_mut(&key) {@@ -71,6 +85,36 @@ impl DepIndex {out}+ /// Narrows viewer changes only when both the reader and writer have field+ /// proof. Missing records, legacy registrations and optimistic mutations+ /// retain the record-wide fallback through `ops_for_keys`.+ pub(crate) fn ops_for_changes(+ &self,+ keys: &BTreeSet<EntityKey<'static>>,+ viewer_changes: &ViewerFields,+ ) -> BTreeSet<OpId> {+ let mut out = BTreeSet::new();+ for key in keys {+ for op in self.by_key.get(key).into_iter().flatten() {+ let watched = self+ .viewer_fields+ .get(op)+ .and_then(|fields| fields.get(key));+ let affected = match (watched, viewer_changes.get(key)) {+ (Some(watched), Some(changed)) => !watched.is_disjoint(changed),+ _ => true,+ };+ if affected {+ out.insert(*op);+ }+ }+ }+ if !keys.is_empty() {+ out.extend(&self.broad_ops);+ }+ out+ }+/// Keys pinned by at least one active operation (future: eviction).pub fn pinned(&self) -> impl Iterator<Item = &EntityKey<'static>> {self.by_key.keys()diff --git a/crates/client/cache-core/src/deps/viewer.rs b/crates/client/cache-core/src/deps/viewer.rsnew file mode 100644index 0000000000..3a9fcb5384--- /dev/null+++ b/crates/client/cache-core/src/deps/viewer.rs@@ -0,0 +1,111 @@+//! Viewer fields own independent argument-qualified query entry points. Track+//! their top-level storage keys, not each embedded page member. Other entities+//! deliberately keep record-level invalidation.++use crate::page_retention::SOUP_PAGE_OWNER;+use crate::value::{EntityKey, Record};+use std::collections::{BTreeMap, BTreeSet};++/// Dependency sink shared by response normalization and cache reads.+/// Record-only callers retain the existing conservative behavior.+pub trait DependencyTracker {+ /// Record existence/content used by the query, including missing records.+ fn record(&mut self, key: &EntityKey<'static>);+ /// A selected storage field on its concrete owning type (aliases resolved).+ fn field(&mut self, key: &EntityKey<'static>, concrete: &str, field: &str);+}++impl DependencyTracker for BTreeSet<EntityKey<'static>> {+ fn record(&mut self, key: &EntityKey<'static>) {+ self.insert(key.clone());+ }++ fn field(&mut self, _: &EntityKey<'static>, _: &str, _: &str) {}+}++pub(crate) type ViewerFields = BTreeMap<EntityKey<'static>, BTreeSet<String>>;++#[derive(Debug, Default)]+pub(crate) struct QueryDependencies {+ pub records: BTreeSet<EntityKey<'static>>,+ pub viewer_fields: ViewerFields,+}++impl QueryDependencies {+ pub fn clear(&mut self) {+ self.records.clear();+ self.viewer_fields.clear();+ }+}++impl DependencyTracker for QueryDependencies {+ fn record(&mut self, key: &EntityKey<'static>) {+ self.records.insert(key.clone());+ }++ fn field(&mut self, key: &EntityKey<'static>, concrete: &str, field: &str) {+ if concrete == SOUP_PAGE_OWNER {+ self.viewer_fields+ .entry(key.clone())+ .or_default()+ .insert(field.to_owned());+ }+ }+}++/// Capture potential field changes before a merge without cloning page payloads.+/// Retention can also remove fields, so remember the original keys.+pub(crate) struct ViewerFieldUpdate {+ previous_keys: BTreeSet<String>,+ changed: BTreeSet<String>,+}++impl ViewerFieldUpdate {+ pub fn capture(before: &Record, update: &Record) -> Option<Self> {+ (before.typename() == Some(SOUP_PAGE_OWNER)).then(|| Self {+ previous_keys: before.fields.keys().cloned().collect(),+ changed: update+ .fields+ .iter()+ .filter(|(field, value)| before.fields.get(*field) != Some(*value))+ .map(|(field, _)| field.clone())+ .collect(),+ })+ }++ pub fn finish(mut self, after: &Record) -> Option<BTreeSet<String>> {+ if after.typename() != Some(SOUP_PAGE_OWNER) {+ return None;+ }+ self.changed.extend(+ self.previous_keys+ .into_iter()+ .filter(|field| !after.fields.contains_key(field)),+ );+ Some(self.changed)+ }+}++/// Optimistic overlays already provide full before/after views. Creation,+/// deletion and type changes return no proof and invalidate the whole record.+pub(crate) fn changed_viewer_fields(+ before: Option<&Record>,+ after: Option<&Record>,+) -> Option<BTreeSet<String>> {+ let (before, after) = (before?, after?);+ if before.typename() != Some(SOUP_PAGE_OWNER) || after.typename() != Some(SOUP_PAGE_OWNER) {+ return None;+ }+ Some(+ before+ .fields+ .keys()+ .chain(after.fields.keys())+ .filter(|field| before.fields.get(*field) != after.fields.get(*field))+ .cloned()+ .collect(),+ )+}++#[cfg(test)]+mod test;diff --git a/crates/client/cache-core/src/deps/viewer/test.rs b/crates/client/cache-core/src/deps/viewer/test.rsnew file mode 100644index 0000000000..94f4790179--- /dev/null+++ b/crates/client/cache-core/src/deps/viewer/test.rs@@ -0,0 +1,67 @@+use super::*;+use crate::deps::DepIndex;+use crate::value::CacheValue;++#[test]+fn field_proof_is_optional_and_replaced_on_registration() {+ let viewer = EntityKey::entity(SOUP_PAGE_OWNER, &["viewer"]);+ let document = EntityKey::entity("GraphqlSoupDocument", &["doc"]);+ let mut index = DepIndex::new();+ for (op, field) in [(1, "soup(a)"), (2, "soup(b)")] {+ let mut deps = QueryDependencies::default();+ deps.record(&viewer);+ deps.record(&document);+ deps.field(&viewer, SOUP_PAGE_OWNER, field);+ index.set_query_deps(op, deps);+ }+ index.set_op_deps(3, [viewer.clone()].into());+ index.set_op_broad(4);+ let changes = [(viewer.clone(), ["soup(a)".into()].into())].into();+ assert_eq!(+ index.ops_for_changes(&[viewer.clone()].into(), &changes),+ [1, 3, 4].into()+ );+ assert_eq!(+ index.ops_for_changes(&[document].into(), &changes),+ [1, 2, 4].into()+ );+ assert_eq!(+ index.ops_for_changes(&[viewer.clone()].into(), &ViewerFields::new()),+ [1, 2, 3, 4].into()+ );+ index.remove_op(1);+ index.set_op_deps(2, [viewer.clone()].into());+ assert_eq!(+ index.ops_for_changes(&[viewer].into(), &changes),+ [2, 3, 4].into()+ );+}++#[test]+fn captures_retention_removals_without_copying_page_payloads() {+ let before = Record {+ fields: [+ (+ "__typename".into(),+ CacheValue::String(SOUP_PAGE_OWNER.into()),+ ),+ ("soup(old)".into(), CacheValue::Null),+ ]+ .into(),+ };+ let update = Record {+ fields: [("soup(new)".into(), CacheValue::Null)].into(),+ };+ let capture = ViewerFieldUpdate::capture(&before, &update).unwrap();+ let mut after = before.clone();+ after.fields.remove("soup(old)");+ after.fields.extend(update.fields);+ let fields = capture.finish(&after).unwrap();+ assert_eq!(fields, ["soup(old)".into(), "soup(new)".into()].into());+ assert_eq!(+ changed_viewer_fields(Some(&before), Some(&after)),+ Some(fields)+ );+ assert_eq!(changed_viewer_fields(None, Some(&after)), None);+ assert_eq!(changed_viewer_fields(Some(&before), None), None);+}diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rsindex c50082dfd9..a6f2b5b5b5 100644--- a/crates/client/cache-core/src/engine.rs+++ b/crates/client/cache-core/src/engine.rs@@ -9,7 +9,9 @@ use crate::denormalize::{DenormalizeError, ReadOutcome, RecordSource, denormalize_record,denormalize_with_entity_resolvers,};-use crate::deps::{DepIndex, OpId};+use crate::deps::{+ DepIndex, OpId, QueryDependencies, ViewerFieldUpdate, ViewerFields, changed_viewer_fields,+};use crate::document::{Document, DocumentError, OperationKind};use crate::entity_resolver::{EntityResolver, EntityResolverError, EntityResolverLookup};use crate::link_patch::{@@ -141,6 +143,9 @@ pub struct WriteResult {pub revision: CacheRevision,/// Whether this write advanced [`Self::revision`].pub revision_advanced: bool,+ /// Search buckets changed by an ordinary query response. `None` keeps+ /// mutation/reset notifications conservative; an empty set proves no change.+ pub search_changed_buckets: Option<BTreeSet<String>>,/// Records whose contents changed.pub changed: BTreeSet<EntityKey<'static>>,/// Active operations depending on changed records (host re-executes@@ -156,6 +161,15 @@ pub struct WriteResult {pub revalidations: Vec<QueryRevalidation>,}+/// Internal durable deltas; viewer field proof is never sent across host boundaries.+struct PersistedChanges {+ changed: BTreeSet<EntityKey<'static>>,+ revision: CacheRevision,+ revision_advanced: bool,+ search_changed_buckets: BTreeSet<String>,+ viewer_fields: ViewerFields,+}+/// Result of hydrating a query while returning only non-`@cacheOnly` fields.#[derive(Debug)]pub struct HydrationWriteResult {@@ -444,6 +458,7 @@ impl<S: Storage> Engine<S> {Ok(WriteResult {revision,revision_advanced: true,+ search_changed_buckets: None,changed,affected_ops,reset: false,@@ -632,7 +647,7 @@ impl<S: Storage> Engine<S> {// to promote into the hot tier afterwards).let mut fetched_base: HashMap<EntityKey<'static>, Record> = HashMap::new();let mut known_absent: BTreeSet<EntityKey<'static>> = BTreeSet::new();- let mut deps = BTreeSet::new();+ let mut deps = QueryDependencies::default();let outcome = loop {deps.clear();@@ -697,11 +712,11 @@ impl<S: Storage> Engine<S> {for (key, record) in fetched_base {self.hot.put(key, record);}- for key in &deps {+ for key in &deps.records {let _ = self.hot.get(key);}if let Some(op_id) = op_id {- self.deps.set_op_deps(op_id, deps);+ self.deps.set_query_deps(op_id, deps);}Ok(outcome)}@@ -1136,6 +1151,7 @@ impl<S: Storage> Engine<S> {)),));}+ let is_query = op.kind == OperationKind::Query;let normalized = normalize_with_dependencies(op, variables, data, &entity_resolvers)?;let mut updates = normalized.updates;if !retain_pages {@@ -1174,8 +1190,13 @@ impl<S: Storage> Engine<S> {let before = effective_records(&bases, &self.optimistic, &candidates);Some((candidates, before))};- let (changed, mut revision, mut revision_advanced, mut search_changed_buckets) =- self.persist_updates(updates, projections).await?;+ let PersistedChanges {+ changed,+ mut revision,+ mut revision_advanced,+ mut search_changed_buckets,+ viewer_fields: mut viewer_changes,+ } = self.persist_updates(updates, projections).await?;if reset && !revision_advanced {revision = self.advance_revision()?;revision_advanced = true;@@ -1194,7 +1215,14 @@ impl<S: Storage> Engine<S> {// Compare the composed view: a hydration hidden beneath a pending// edit must not invalidate the search projection it did not change.search_changed_buckets.clear();+ viewer_changes.clear();for key in &candidates {+ if let Some(fields) = changed_viewer_fields(+ before.get(key).and_then(Option::as_ref),+ after.get(key).and_then(Option::as_ref),+ ) {+ viewer_changes.insert(key.clone(), fields);+ }collect_search_changes(key,before.get(key).and_then(Option::as_ref),@@ -1213,6 +1241,8 @@ impl<S: Storage> Engine<S> {let mut affected_ops = if reset {// Everything anyone had cached is gone: re-execute all ops.self.deps.all_ops()+ } else if is_query {+ self.deps.ops_for_changes(&visible_changed, &viewer_changes)} else {self.deps.ops_for_keys(visible_changed.iter())};@@ -1224,7 +1254,7 @@ impl<S: Storage> Engine<S> {&& self.optimistic.is_empty(){self.deps- .set_op_deps(registration.op_id, normalized.dependencies);+ .set_query_deps(registration.op_id, normalized.dependencies);} else {self.deps.set_op_broad(registration.op_id);}@@ -1233,6 +1263,8 @@ impl<S: Storage> Engine<S> {WriteResult {revision,revision_advanced,+ search_changed_buckets: (is_query && !reset)+ .then(|| search_changed_buckets.clone()),changed,affected_ops,reset,@@ -1317,15 +1349,7 @@ impl<S: Storage> Engine<S> {&mut self,updates: RecordUpdates,projections: Vec<ProjectionMutation>,- ) -> Result<- (- BTreeSet<EntityKey<'static>>,- CacheRevision,- bool,- BTreeSet<String>,- ),- EngineError<S::Error>,- > {+ ) -> Result<PersistedChanges, EngineError<S::Error>> {// Load current values (hot tier, then storage) so merges detect real// changes. Merges are staged in a plain map, NOT the LRU: a batch// larger than the hot capacity would otherwise evict its own@@ -1355,6 +1379,7 @@ impl<S: Storage> Engine<S> {let mut changed = BTreeSet::new();let mut search_changed_buckets = BTreeSet::new();+ let mut viewer_fields = ViewerFields::new();let mut to_persist: Vec<(EntityKey<'static>, Record)> = Vec::new();let mut touched = Vec::with_capacity(updates.len());for (key, update) in updates {@@ -1363,7 +1388,12 @@ impl<S: Storage> Engine<S> {// Compare only fields supplied by this partial response,// overlaid onto the existing row, without cloning its body.let before = snapshot_search_fields(&key, &existing);+ let viewer_update = ViewerFieldUpdate::capture(&existing, &update);let did_change = existing.merge(update);+ if let Some(fields) = viewer_update.and_then(|update| update.finish(&existing))+ {+ viewer_fields.insert(key.clone(), fields);+ }if did_change {collect_search_changes(&key,@@ -1409,7 +1439,13 @@ impl<S: Storage> Engine<S> {for (key, record) in touched {self.hot.put(key, record);}- Ok((changed, revision, revision_advanced, search_changed_buckets))+ Ok(PersistedChanges {+ changed,+ revision,+ revision_advanced,+ search_changed_buckets,+ viewer_fields,+ })}async fn projection_mutations_change(@@ -1676,6 +1712,7 @@ impl<S: Storage> Engine<S> {write_result: WriteResult {revision,revision_advanced: true,+ search_changed_buckets: None,changed,affected_ops,reset: false,@@ -2103,6 +2140,7 @@ impl<S: Storage> Engine<S> {Ok(WriteResult {revision,revision_advanced: true,+ search_changed_buckets: None,changed: durable_changed,affected_ops,reset: false,@@ -2189,6 +2227,7 @@ impl<S: Storage> Engine<S> {Ok(WriteResult {revision,revision_advanced: true,+ search_changed_buckets: None,changed: BTreeSet::new(),affected_ops,reset: false,@@ -2483,8 +2522,12 @@ impl<S: PredicateIndexStorage> Engine<S> {for (key, record) in entries {updates.entry(key).or_default().merge(record);}- let (changed, revision, revision_advanced, _) =- self.persist_updates(updates, projections).await?;+ let PersistedChanges {+ changed,+ revision,+ revision_advanced,+ ..+ } = self.persist_updates(updates, projections).await?;let mut affected_ops = self.deps.ops_for_keys(changed.iter());if let Some(origin_op) = origin_op {affected_ops.remove(&origin_op);@@ -2492,6 +2535,7 @@ impl<S: PredicateIndexStorage> Engine<S> {Ok(WriteResult {revision,revision_advanced,+ search_changed_buckets: None,changed,affected_ops,reset: false,diff --git a/crates/client/cache-core/src/engine/test.rs b/crates/client/cache-core/src/engine/test.rsindex 67a7ea77e2..6facddd13b 100644--- a/crates/client/cache-core/src/engine/test.rs+++ b/crates/client/cache-core/src/engine/test.rs@@ -2,6 +2,7 @@ use super::*;use crate::store::InMemoryStorage;mod hydration_search_changes;+mod query_search_changes;#[test]fn storage_generation_survives_reopening_and_preserves_existing_records() {diff --git a/crates/client/cache-core/src/engine/test/query_search_changes.rs b/crates/client/cache-core/src/engine/test/query_search_changes.rsnew file mode 100644index 0000000000..e08b3ac359--- /dev/null+++ b/crates/client/cache-core/src/engine/test/query_search_changes.rs@@ -0,0 +1,84 @@+use super::*;+use serde_json::json;++const QUERY: &str = include_str!("hydration_search_changes.graphql");++#[test]+fn ordinary_queries_report_search_changes_but_page_only_writes_do_not() {+ pollster::block_on(async {+ let mut engine = Engine::new(InMemoryStorage::new());+ let variables = serde_json::Map::new();+ let item = json!({"__typename": "GraphqlSoupDocument", "id": "doc", "name": "Note", "fileType": "md"});+ let response = |item| json!({"user": {"id": "viewer", "soup": {"items": [item]}}});+ let data = response(item.clone());+ let result = engine+ .write_query(None, QUERY, None, &variables, &data, None)+ .await+ .unwrap();+ assert_eq!(+ result.search_changed_buckets,+ Some(BTreeSet::from(["note".into()]))+ );+ // Exercise cold before-state comparison and a new argument-qualified page.+ let mut engine = Engine::new(engine.into_storage());+ let other_page = QUERY.replace("limit: 10", "limit: 20");+ let result = engine+ .write_query(None, &other_page, None, &variables, &data, None)+ .await+ .unwrap();+ assert!(result.revision_advanced);+ assert_eq!(result.search_changed_buckets, Some(BTreeSet::new()));+ assert_eq!(+ result.changed,+ BTreeSet::from([EntityKey::entity("GraphqlUser", &["viewer"])])+ );++ let mut renamed = item;+ renamed["name"] = json!("Renamed");+ let result = engine+ .write_query(None, QUERY, None, &variables, &response(renamed), None)+ .await+ .unwrap();+ assert_eq!(+ result.search_changed_buckets,+ Some(BTreeSet::from(["note".into()]))+ );+ });+}++#[test]+fn identity_resets_and_mutations_require_conservative_search_refreshes() {+ pollster::block_on(async {+ let mut engine = Engine::new(InMemoryStorage::new());+ let variables = serde_json::Map::new();+ for id in ["one", "two"] {+ let result = engine+ .write_query(+ None,+ "{ user { id } }",+ None,+ &variables,+ &json!({"user":{"id":id}}),+ Some(id),+ )+ .await+ .unwrap();+ if id == "two" {+ assert!(result.reset);+ assert_eq!(result.search_changed_buckets, None);+ }+ }+ let result = engine+ .write_query(+ None,+ "mutation { setEntityProperty { id } }",+ None,+ &variables,+ &json!({"setEntityProperty":{"id":"property"}}),+ None,+ )+ .await+ .unwrap();+ assert_eq!(result.search_changed_buckets, None);+ });+}diff --git a/crates/client/cache-core/src/normalize.rs b/crates/client/cache-core/src/normalize.rsindex 099039a27c..969b33e2cc 100644--- a/crates/client/cache-core/src/normalize.rs+++ b/crates/client/cache-core/src/normalize.rs@@ -1,5 +1,6 @@//! Write path: response JSON → normalized records.+use crate::deps::{DependencyTracker, QueryDependencies};use crate::document::{FieldNode, MissingVariable, Operation, OperationKind, Selection, resolve_args, resolve_args_key,};@@ -7,7 +8,7 @@ use crate::entity_resolver::EntityResolverLookup;use crate::meta::{self, FieldKind, TypeKind};use crate::value::{CacheValue, EntityKey, Record, field_key};use serde_json::Value as Json;-use std::collections::{BTreeMap, BTreeSet};+use std::collections::BTreeMap;use thiserror::Error;#[derive(Debug, Error)]@@ -49,12 +50,12 @@ pub(crate) enum DependencyCompleteness {/// Normalized updates and dependencies captured without reading records back.pub(crate) struct NormalizeResult {pub updates: RecordUpdates,- pub dependencies: BTreeSet<EntityKey<'static>>,+ pub dependencies: QueryDependencies,pub completeness: DependencyCompleteness,}struct DependencyCapture<'a> {- keys: BTreeSet<EntityKey<'static>>,+ keys: QueryDependencies,completeness: DependencyCompleteness,entity_resolvers: &'a EntityResolverLookup,}@@ -103,7 +104,7 @@ pub(crate) fn normalize_with_dependencies(let mut records = RecordUpdates::new();let mut root = Record::default();let mut dependencies = DependencyCapture {- keys: BTreeSet::new(),+ keys: QueryDependencies::default(),completeness: DependencyCompleteness::Exact,entity_resolvers,};@@ -295,7 +296,11 @@ fn write_object_fields(_ => type_name,};if let Some(owner) = owner {- context.dependencies.keys.insert(owner.clone());+ context.dependencies.keys.record(owner);+ context+ .dependencies+ .keys+ .field(owner, concrete, "__typename");}target.insert("__typename".to_string(),@@ -316,6 +321,12 @@ fn write_object_fields(})?;let args = resolve_args_key(f, context.variables)?;let storage_key = field_key(&f.name, args.as_deref());+ if let Some(owner) = owner {+ context+ .dependencies+ .keys+ .field(owner, concrete, &storage_key);+ }// GraphQL guarantees selected fields are present in data. Missing// fields are still tolerated, but an exact dependency set cannot be@@ -340,7 +351,7 @@ fn write_object_fields((Some(expected), Json::Object(_), CacheValue::Ref(actual))if expected == *actual =>{- context.dependencies.keys.insert(expected);+ context.dependencies.keys.record(&expected);}_ => context.dependencies.mark_broad(),}diff --git a/crates/client/cache-core/tests/fixtures/viewer_fields.graphql b/crates/client/cache-core/tests/fixtures/viewer_fields.graphqlnew file mode 100644index 0000000000..f0bb82827b--- /dev/null+++ b/crates/client/cache-core/tests/fixtures/viewer_fields.graphql@@ -0,0 +1,36 @@+query Page($input: SoupInput!) {+ user {+ id+ soup(input: $input) {+ items {+ __typename+ id+ ... on GraphqlSoupDocument { name }+ }+ }+ }+}++query AliasedPage($input: SoupInput!) {+ viewer: user {+ id+ page: soup(input: $input) {+ items {+ __typename+ id+ ... on GraphqlSoupDocument { name }+ }+ }+ }+}++query Viewer { user { id } }++query Group($input: GroupedSoupInput!) {+ user {+ id+ groupSoup(input: $input) {+ bins { key items { __typename id } }+ }+ }+}diff --git a/crates/client/cache-core/tests/viewer_fields.rs b/crates/client/cache-core/tests/viewer_fields.rsnew file mode 100644index 0000000000..42ead4e092--- /dev/null+++ b/crates/client/cache-core/tests/viewer_fields.rs@@ -0,0 +1,307 @@+use cache_core::engine::{+ BeginOptimisticWrite, Engine, NetworkWrite, QueryRegistration, ReadResult,+};+use cache_core::page_retention::MAX_SOUP_PAGES;+use cache_core::store::InMemoryStorage;+use cache_core::value::EntityKey;+use serde_json::{Value, json};+use std::collections::BTreeSet;++const QUERY: &str = include_str!("fixtures/viewer_fields.graphql");++fn variables(limit: usize) -> serde_json::Map<String, Value> {+ json!({"input":{"initial":{"limit":limit}}})+ .as_object()+ .unwrap()+ .clone()+}++fn page(id: &str, name: &str, aliased: bool) -> Value {+ let items = json!({"items":[{"__typename":"GraphqlSoupDocument","id":id,"name":name}]});+ if aliased {+ json!({"viewer":{"id":"viewer","page":items}})+ } else {+ json!({"user":{"id":"viewer","soup":items}})+ }+}++async fn write(+ engine: &mut Engine<InMemoryStorage>,+ op: &str,+ vars: &serde_json::Map<String, Value>,+ data: &Value,+ registration: Option<u64>,+) -> BTreeSet<u64> {+ engine+ .write_query_with_registration(+ None,+ registration.map(|op_id| QueryRegistration {+ op_id,+ entity_resolvers: &[],+ }),+ NetworkWrite {+ query: QUERY,+ operation_name: Some(op),+ variables: vars,+ data,+ identity: Some("viewer"),+ },+ )+ .await+ .unwrap()+ .affected_ops+}++#[test]+fn page_changes_only_wake_matching_fields_but_entity_changes_wake_all_readers() {+ pollster::block_on(async {+ for register_on_write in [false, true] {+ for cold in [false, true] {+ let mut engine = Engine::new(InMemoryStorage::new());+ let a = variables(1);+ let b = variables(2);+ let viewer = json!({"user":{"id":"viewer"}});+ for (id, op, vars, data) in [+ (1, "Page", &a, page("shared", "Original", false)),+ (2, "Page", &b, page("shared", "Original", false)),+ (3, "Viewer", &a, viewer),+ (4, "AliasedPage", &a, page("shared", "Original", true)),+ ] {+ write(+ &mut engine,+ op,+ vars,+ &data,+ register_on_write.then_some(id),+ )+ .await;+ }+ if cold {+ engine = Engine::with_capacity(engine.into_storage(), 1);+ }+ // Cold reopening intentionally loses active registrations; restore via reads.+ if !register_on_write || cold {+ for (id, op, vars) in [+ (1, "Page", &a),+ (2, "Page", &b),+ (3, "Viewer", &a),+ (4, "AliasedPage", &a),+ ] {+ assert!(matches!(+ engine+ .read_query(Some(id), QUERY, Some(op), vars)+ .await+ .unwrap(),+ ReadResult::Hit { .. }+ ));+ }+ }+ let changed_page = page("other", "Other", false);+ assert_eq!(+ write(&mut engine, "Page", &a, &changed_page, None).await,+ [1, 4].into(),+ "write={register_on_write}, cold={cold}"+ );+ // A different page can update the same document used by another query.+ let changed_entity = page("shared", "Renamed", false);+ assert_eq!(+ write(&mut engine, "Page", &a, &changed_entity, None).await,+ [1, 2, 4].into()+ );+ assert!(+ write(&mut engine, "Page", &a, &changed_entity, None)+ .await+ .is_empty()+ );+ engine.teardown_operation(4);+ assert_eq!(+ write(&mut engine, "Page", &a, &changed_page, None).await,+ [1].into()+ );+ }+ }+ });+}++#[test]+fn misses_grouped_pages_and_partial_registrations_keep_safe_dependencies() {+ pollster::block_on(async {+ let mut engine = Engine::new(InMemoryStorage::new());+ let a = variables(1);+ let b = variables(2);+ // An absent viewer must still wake when it first becomes available.+ assert!(matches!(+ engine+ .read_query(Some(1), QUERY, Some("Page"), &a)+ .await+ .unwrap(),+ ReadResult::Miss+ ));+ assert!(+ write(&mut engine, "Page", &a, &page("doc", "Doc", false), None)+ .await+ .contains(&1)+ );+ assert!(matches!(+ engine+ .read_query(Some(2), QUERY, Some("Page"), &b)+ .await+ .unwrap(),+ ReadResult::Miss+ ));+ assert!(+ !write(+ &mut engine,+ "Page",+ &a,+ &page("other", "Other", false),+ None+ )+ .await+ .contains(&2)+ );+ assert!(+ write(&mut engine, "Page", &b, &page("doc", "Doc", false), None)+ .await+ .contains(&2)+ );++ let group = json!({"user":{"id":"viewer","groupSoup":{"bins":[]}}});+ write(&mut engine, "Group", &a, &group, Some(3)).await;+ assert!(+ !write(&mut engine, "Group", &b, &group, None)+ .await+ .contains(&3)+ );+ assert!(+ !write(&mut engine, "Page", &a, &page("doc", "Doc", false), None)+ .await+ .contains(&3)+ );+ // An incomplete network response has no exact dependency proof.+ write(+ &mut engine,+ "Page",+ &a,+ &json!({"user":{"id":"viewer"}}),+ Some(4),+ )+ .await;+ assert!(+ write(+ &mut engine,+ "Page",+ &b,+ &page("other", "Other", false),+ None+ )+ .await+ .contains(&4)+ );+ });+}++#[test]+fn retention_eviction_invalidates_the_removed_page_not_other_pages() {+ pollster::block_on(async {+ let mut engine = Engine::new(InMemoryStorage::new());+ let data = page("shared", "Original", false);+ write(&mut engine, "Page", &variables(0), &data, Some(1)).await;+ for n in 1..MAX_SOUP_PAGES {+ assert!(+ write(&mut engine, "Page", &variables(n), &data, None)+ .await+ .is_empty()+ );+ }+ engine+ .read_query(Some(2), QUERY, Some("Page"), &variables(MAX_SOUP_PAGES - 1))+ .await+ .unwrap();+ assert_eq!(+ write(&mut engine, "Page", &variables(MAX_SOUP_PAGES), &data, None).await,+ [1].into()+ );+ assert!(matches!(+ engine+ .read_query(None, QUERY, Some("Page"), &variables(0))+ .await+ .unwrap(),+ ReadResult::Miss+ ));+ });+}++#[test]+fn query_updates_remain_scoped_while_an_optimistic_layer_is_pending() {+ pollster::block_on(async {+ let mut engine = Engine::new(InMemoryStorage::new());+ let a = variables(1);+ let data = page("shared", "Original", false);+ write(&mut engine, "Page", &a, &data, Some(1)).await;+ engine+ .begin_optimistic_write(+ None,+ BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000001",+ query: "mutation { setEntityProperty { id } }",+ operation_name: None,+ variables: &serde_json::Map::new(),+ data: &json!({"setEntityProperty":{"id":"pending-property"}}),+ link_patches: &[],+ revalidations: &[],+ created_at_ms: 1,+ },+ )+ .await+ .unwrap();+ let result = engine+ .write_query(None, QUERY, Some("Page"), &variables(2), &data, None)+ .await+ .unwrap();+ assert!(result.affected_ops.is_empty());+ assert_eq!(result.search_changed_buckets, Some(BTreeSet::new()));+ assert_eq!(+ write(+ &mut engine,+ "Page",+ &a,+ &page("shared", "Renamed", false),+ None+ )+ .await,+ [1].into()+ );+ });+}++#[test]+fn resets_and_invalidations_still_reexecute_all_affected_readers() {+ pollster::block_on(async {+ let mut engine = Engine::new(InMemoryStorage::new());+ let a = variables(1);+ let b = variables(2);+ write(&mut engine, "Page", &a, &page("doc", "Doc", false), Some(1)).await;+ write(&mut engine, "Page", &b, &page("doc", "Doc", false), Some(2)).await;+ let key = EntityKey::entity("GraphqlUser", &["viewer"]);+ assert_eq!(engine.invalidate_keys([&key]).unwrap().value, [1, 2].into());+ assert_eq!(+ engine.delete_keys(&[key]).await.unwrap().value,+ [1, 2].into()+ );+ let reset = engine+ .write_query(+ None,+ QUERY,+ Some("Viewer"),+ &a,+ &json!({"user":{"id":"other"}}),+ Some("other"),+ )+ .await+ .unwrap();+ assert!(reset.reset);+ assert_eq!(reset.affected_ops, [1, 2].into());+ assert_eq!(reset.search_changed_buckets, None);+ });+}diff --git a/crates/client/cache-wasm/Cargo.toml b/crates/client/cache-wasm/Cargo.tomlindex 51adbe3bae..bf6f2f0a36 100644--- a/crates/client/cache-wasm/Cargo.toml+++ b/crates/client/cache-wasm/Cargo.toml@@ -2,9 +2,8 @@edition = "2024"name = "cache-wasm"publish = false-# Rebuild for bucket-scoped Quick Access hydration notifications.-# Retains the storage-lifecycle fixes shipped in 0.6.31.-version = "0.6.32"+# Rebuild for scoped query-write notifications and viewer-field dependencies.+version = "0.6.33"[features]default = []diff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rsindex fc0c55d5bc..912228e93d 100644--- a/crates/client/cache-wasm/src/shell.rs+++ b/crates/client/cache-wasm/src/shell.rs@@ -151,6 +151,8 @@ struct JsQueryRegistration {struct JsWriteResult {revision: String,revision_advanced: bool,+ #[serde(skip_serializing_if = "Option::is_none")]+ search_changed_buckets: Option<std::collections::BTreeSet<String>>,changed: Vec<String>,affected_ops: Vec<String>,reset: bool,@@ -416,6 +418,7 @@ fn js_write_result(result: WriteResult, ops: &OpInterner) -> JsWriteResult {JsWriteResult {revision: result.revision.to_string(),revision_advanced: result.revision_advanced,+ search_changed_buckets: result.search_changed_buckets,changed: result.changed.into_iter()diff --git a/crates/client/cache-wasm/src/shell/test.rs b/crates/client/cache-wasm/src/shell/test.rsindex 78eccb5f98..c869cb1fe5 100644--- a/crates/client/cache-wasm/src/shell/test.rs+++ b/crates/client/cache-wasm/src/shell/test.rs@@ -213,6 +213,7 @@ fn empty_js_write_result() -> JsWriteResult {JsWriteResult {revision: "0".to_string(),revision_advanced: false,+ search_changed_buckets: None,changed: Vec::new(),affected_ops: Vec::new(),reset: false,diff --git a/docs/AGENT_GUIDE/navigation.md b/docs/AGENT_GUIDE/navigation.mdindex fbb028a286..77d6f1160b 100644--- a/docs/AGENT_GUIDE/navigation.md+++ b/docs/AGENT_GUIDE/navigation.md@@ -481,8 +481,12 @@ search cached entities without waiting for a server search. Background hydrationupdates an already-open menu only when a bucket it uses changes. Email/body/tag-onlyhydration must not reread History or the cached channel list; a newly hydrated noterefreshes History and matching menus, and a channel/DM refreshes channel consumers.-Renames, ownership/recency changes, and moves between buckets must still appear-without retyping. Older cache runtimes without bucket metadata refresh conservatively. For an empty search, scroll toward the end (or use+Ordinary query responses use the same bucket scoping. A project-search response+that only caches another viewer Soup page must not refresh History, channel lists,+or unrelated active query pages. Renames, ownership/recency changes, and moves+between buckets must still appear without retyping in every affected view.+Older cache runtimes without bucket metadata, mutations, and identity resets+refresh conservatively. For an empty search, scroll toward the end (or useDown); mentions offer **View all** for a category and then load more local pages.Counts describe loaded results, not the full server corpus. Scans throughincomplete or already-visible cache hits are bounded per action; continue