Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

Seanaye/perf/scoped cache change (#7265)

Sean Aye40a7bb846e14
diff --git a/Cargo.lock b/Cargo.lock
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.html
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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 relations
Link 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.graphql
new file mode 100644
index 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.rs
new file mode 100644
index 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.toml
index 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.rs
index 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.rs
index 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.md
index 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 hydration
updates an already-open menu only when a bucket it uses changes. Email/body/tag-only
hydration must not reread History or the cached channel list; a newly hydrated note
refreshes 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 use
Down); mentions offer **View all** for a category and then load more local pages.
Counts describe loaded results, not the full server corpus. Scans through
incomplete or already-visible cache hits are bounded per action; continue