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
refactor(web): one default reactive query API per data shape (#7823)
teo440b65f52969
diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.mdindex 996c83193a..29c625fcf0 100644--- a/apps/web/AGENTS.md+++ b/apps/web/AGENTS.md@@ -66,6 +66,9 @@ Then trigger the interaction and read `window.__inst.log`. `'1,2,3' → '' → '- All API/network calls live in service-clients.- Shared server-state queries and mutations live in `src/lib/queries`; keepfeature-specific query orchestration with its owning feature.+- Reactive GraphQL reads use `createLiveQuery` for a document and+ `useSoupAstItemsQuery` (backed by `createSoupLiveQuery`) for Soup lists; see+ [choosing a reactive read](docs/graphql-normalized-cache-plan.md#choosing-a-reactive-read).- When adding or changing a feature flag, follow the `define-feature-flag` skill.- When adding or changing a view's feature tour, follow the `add-tour` skill.diff --git a/apps/web/docs/graphql-cache-testing.md b/apps/web/docs/graphql-cache-testing.mdindex 78a13d0576..d2de4e5983 100644--- a/apps/web/docs/graphql-cache-testing.md+++ b/apps/web/docs/graphql-cache-testing.md@@ -54,7 +54,8 @@ nix develop --command env -u SQLX_OFFLINE cargo test -p cache-tursoFrom `apps/web`:```sh-nix develop --command bunx vitest run src/lib/graphql-cache src/lib/urql-solid src/lib/queries/properties+nix develop --command bunx vitest run src/lib/graphql-cache src/lib/urql-solid src/lib/queries/properties \+ src/lib/queries/soup/graphql/create-predicate-query.test.ts src/lib/queries/soup/create-keyed-projection.test.ts```By default, Proptest generates 256 sequences and fast-check generates 250. Thediff --git a/apps/web/docs/graphql-normalized-cache-plan.md b/apps/web/docs/graphql-normalized-cache-plan.mdindex 7093572fae..728977afc7 100644--- a/apps/web/docs/graphql-normalized-cache-plan.md+++ b/apps/web/docs/graphql-normalized-cache-plan.md@@ -367,6 +367,7 @@ apps/web/tauri/graphql_cache_plugin/ # tauri commands + engine thread wrappingapps/web/src/lib/graphql-cache/ # JS gluehost/ # CacheHost interface + worker & tauri transportsexchange/ # urql normalizedCacheExchange+ solid/ # createLiveQuery, the reactive document queryworker/ # SharedWorker entry + worker core```@@ -545,6 +546,24 @@ benchmark were **skipped by decision**.## 8. Live query API+### Choosing a reactive read++Use one default per data shape:++| Data shape | Default | Notes |+| --- | --- | --- |+| GraphQL document | `createLiveQuery` from `@graphql-cache/solid/create-live-query` | Cursor-paginated documents use `createUrqlInfiniteQuery` from `@app/lib/urql-solid`. |+| Soup list | `createSoupLiveQuery` | Feature code reads it through `useSoupAstItemsQuery`, which adds the GraphQL Soup flag, REST fallback, grouping, and entity mapping. |++`createLiveQuery` is a document-first wrapper over `createUrqlQuery`: the+document and variables are arguments, other options pass through, and the result+and live projection path are the same. Existing `createUrqlQuery` call sites are+already live and need no migration; new single-document reads use+`createLiveQuery`. Soup's maintained-view binding and keyed row projection are+internal to `src/lib/queries/soup/`, not general query APIs.++### Usage+Use a generated document and reactive variables. The normal urql provider cansupply the client; pass `client` when using a service-specific client.@@ -557,13 +576,6 @@ const accountQuery = createLiveQuery(// Access inside a reactive computation or JSX; don't destructure store fields.const accounts = () => accountQuery.data?.user.emailLinks ?? [];--const soupPage = createLiveQuery(- SoupDocument,- () => ({ input: { initial: { limit: 100, sortMethod: 'UPDATED_AT' } } }),- () => ({ client: getGraphqlSoupClient() })-);-const items = () => soupPage.data?.user.soup.items ?? [];````undefined` variables pause a query. Changing variables creates a separate cache@@ -673,10 +685,11 @@ never starts a network request.The generic projection reflects cached GraphQL results. It does not infer serverresolver logic, authorization, aggregates, full-text ranking, or whether an entitybelongs in an arbitrary filtered/paginated list. Such changes need a declared-domain collection policy or server revalidation. An explicit Soup page above-retains its server-provided membership; the existing `createSoupLiveQuery` source-adds Soup's local membership, ordering, pagination and Mail policy through its-predicate adapter. That policy remains outside generic cache-core.+domain collection policy or server revalidation. A Soup page read as a plain+document would retain its server-provided membership, which is why Soup lists+use `createSoupLiveQuery`: it adds Soup's local membership, ordering, pagination+and Mail policy through its predicate adapter. That policy remains outside+generic cache-core.Network responses must provide the schema's identity fields (usually `id`, and`__typename` for abstract types) for normalization. They are not automaticallydiff --git a/apps/web/src/features/soup/collection/row-store.ts b/apps/web/src/features/soup/collection/row-store.tsindex cb41f7697b..7d02c58539 100644--- a/apps/web/src/features/soup/collection/row-store.ts+++ b/apps/web/src/features/soup/collection/row-store.ts@@ -1,4 +1,4 @@-import { createKeyedProjection } from '@app/lib/urql-solid/create-keyed-projection';+import { createKeyedProjection } from '@app/lib/queries/soup/create-keyed-projection';import type { Accessor } from 'solid-js';/** Stable row identity, with independent tracking and reconciliation per row. */diff --git a/apps/web/src/lib/graphql-cache/exchange/live-query.test.ts b/apps/web/src/lib/graphql-cache/exchange/live-query.test.tsindex b1afccca56..af804c277f 100644--- a/apps/web/src/lib/graphql-cache/exchange/live-query.test.ts+++ b/apps/web/src/lib/graphql-cache/exchange/live-query.test.ts@@ -2,7 +2,7 @@ import { gql } from '@urql/core';import fc from 'fast-check';import { createComputed, createRoot } from 'solid-js';import { describe, expect, it } from 'vitest';-import { createKeyedProjection } from '../../urql-solid/create-keyed-projection';+import { createKeyedProjection } from '../../queries/soup/create-keyed-projection';import { supportsStoreReconciliation } from '../../urql-solid/reactive-selection';import { LiveQuery, querySnapshot } from './live-query';import { applyQueryPatches } from './query-patches';diff --git a/apps/web/src/lib/graphql-cache/index.ts b/apps/web/src/lib/graphql-cache/index.tsindex a1cf25d2bf..cabaa3cacc 100644--- a/apps/web/src/lib/graphql-cache/index.ts+++ b/apps/web/src/lib/graphql-cache/index.ts@@ -1,6 +1,9 @@/*** Normalized GraphQL cache — JS glue.* Design doc: apps/web/docs/graphql-normalized-cache-plan.md+ *+ * The reactive document query, `createLiveQuery`, is imported from+ * `./solid/create-live-query`; it is not re-exported here.*/export {@@ -97,8 +100,3 @@ export {validateCacheSearchArgs,validateRecordSelectionKeys,} from './protocol';--export {- createLiveQuery,- type LiveQueryOptions,-} from './solid/create-live-query';diff --git a/apps/web/src/lib/graphql-cache/solid/create-live-query.ts b/apps/web/src/lib/graphql-cache/solid/create-live-query.tsindex f5187864be..7e37d7c78b 100644--- a/apps/web/src/lib/graphql-cache/solid/create-live-query.ts+++ b/apps/web/src/lib/graphql-cache/solid/create-live-query.ts@@ -1,3 +1,18 @@+/**+ * Reactive GraphQL reads have one default per data shape:+ *+ * - A GraphQL document: `createLiveQuery` (this module). Cursor-paginated+ * documents use `createUrqlInfiniteQuery` from `@app/lib/urql-solid`.+ * - A Soup list: `createSoupLiveQuery` is the GraphQL source. Feature code+ * reads it through `useSoupAstItemsQuery`, which adds the GraphQL Soup flag,+ * REST fallback, grouping, and entity mapping.+ *+ * `createLiveQuery` is a document-first wrapper over `createUrqlQuery`. Both+ * are live through the normalized-cache exchange, so existing `createUrqlQuery`+ * callers keep working without migration. See "8. Live query API" in+ * apps/web/docs/graphql-normalized-cache-plan.md.+ */+import type { AnyVariables, DocumentInput } from '@urql/core';import type { Accessor } from 'solid-js';import { createUrqlQuery } from '../../urql-solid/create-urql-query';diff --git a/apps/web/src/lib/graphql-cache/solid/create-query-signal.test.ts b/apps/web/src/lib/graphql-cache/solid/create-query-signal.test.tsdeleted file mode 100644index 80c8024e6f..0000000000--- a/apps/web/src/lib/graphql-cache/solid/create-query-signal.test.ts+++ /dev/null@@ -1,140 +0,0 @@-import { type Client, CombinedError, type OperationResult } from '@urql/core';-import { createRoot, createSignal } from 'solid-js';-import { afterEach, describe, expect, it } from 'vitest';-import { makeSubject } from 'wonka';-import { createQuerySignal, type QuerySignal } from './create-query-signal';--type FakeResult = Omit<Partial<OperationResult>, 'data'> & {- // GraphQL permits a root-level null response even though urql's operation- // result type models missing data as undefined.- data?: OperationResult['data'] | null;-};--/**- * Fake urql client: each `query()` call returns a fresh subject the test- * pushes results into, mimicking the long-lived sources the normalized- * cache exchange re-emits on.- */-function makeFakeClient() {- const executions: Array<{- variables: unknown;- next: (result: FakeResult) => void;- }> = [];- const client = {- query: (_document: unknown, variables: unknown) => {- const subject = makeSubject<FakeResult>();- executions.push({ variables, next: subject.next });- return subject.source;- },- } as unknown as Client;- return { client, executions };-}--const DOCUMENT = {} as never;--type Variables = { cursor: string | null };--// Note: signal writes and result pushes must happen OUTSIDE the createRoot-// body — solid batches the body, deferring effect re-runs until it returns.-function setup() {- const { client, executions } = makeFakeClient();- let query!: QuerySignal<unknown>;- let setVariables!: (v: Variables | undefined) => void;- const dispose = createRoot((dispose) => {- const [variables, setVars] = createSignal<Variables | undefined>({- cursor: null,- });- setVariables = setVars;- query = createQuerySignal({- client: () => client,- document: DOCUMENT,- variables,- });- return dispose;- });- return { executions, query, setVariables, dispose };-}--let dispose: (() => void) | undefined;-afterEach(() => {- dispose?.();- dispose = undefined;-});--describe('createQuerySignal', () => {- it('tracks results pushed over the operation lifetime', () => {- const harness = setup();- dispose = harness.dispose;- const { query, executions } = harness;-- expect(query.fetching()).toBe(true);- expect(query.data()).toBeUndefined();- expect(executions).toHaveLength(1);-- // Stale cache hit first…- executions[0]?.next({ data: { from: 'cache' }, stale: true });- expect(query.data()).toEqual({ from: 'cache' });- expect(query.stale()).toBe(true);- expect(query.fetching()).toBe(false);-- // …then the network result, then a cache-pushed re-execution.- executions[0]?.next({ data: { from: 'network' }, stale: false });- expect(query.data()).toEqual({ from: 'network' });- executions[0]?.next({ data: { from: 'optimistic' }, stale: false });- expect(query.data()).toEqual({ from: 'optimistic' });- });-- it('retains valid data and reports errors when GraphQL data is null', () => {- const harness = setup();- dispose = harness.dispose;- const { query, executions } = harness;- const error = new CombinedError({- graphQLErrors: ['root non-null field failed'],- });-- executions[0]?.next({ data: null, error });- expect(query.data()).toBeUndefined();- expect(query.error()).toBe(error);-- executions[0]?.next({ data: { page: 1 } });- executions[0]?.next({ data: null, error });- expect(query.data()).toEqual({ page: 1 });- expect(query.error()).toBe(error);- });-- it('resubscribes when variables change and ignores the old source', () => {- const harness = setup();- dispose = harness.dispose;- const { query, executions, setVariables } = harness;-- executions[0]?.next({ data: { page: 1 } });- expect(query.data()).toEqual({ page: 1 });-- setVariables({ cursor: 'next' });- expect(query.fetching()).toBe(true);- expect(executions).toHaveLength(2);- expect(executions[1]?.variables).toEqual({ cursor: 'next' });-- // The unsubscribed first execution must not clobber the signal.- executions[0]?.next({ data: { page: 'stale-old' } });- expect(query.data()).toEqual({ page: 1 });- executions[1]?.next({ data: { page: 2 } });- expect(query.data()).toEqual({ page: 2 });- });-- it('pauses on undefined variables, keeping the last data', () => {- const harness = setup();- dispose = harness.dispose;- const { query, executions, setVariables } = harness;-- executions[0]?.next({ data: { page: 1 } });- setVariables(undefined);- expect(query.fetching()).toBe(false);- expect(query.data()).toEqual({ page: 1 });- expect(executions).toHaveLength(1);-- // Old subscription is torn down: late results are ignored.- executions[0]?.next({ data: { page: 'late' } });- expect(query.data()).toEqual({ page: 1 });- });-});diff --git a/apps/web/src/lib/graphql-cache/solid/create-query-signal.ts b/apps/web/src/lib/graphql-cache/solid/create-query-signal.tsdeleted file mode 100644index aec335d428..0000000000--- a/apps/web/src/lib/graphql-cache/solid/create-query-signal.ts+++ /dev/null@@ -1,94 +0,0 @@-/**- * Minimal Solid binding over a urql query: signals that track the latest- * operation result for as long as the owner scope lives.- *- * Unlike an imperative `.toPromise()` call, the underlying source stays- * subscribed, so results *pushed* by the normalized cache exchange- * (optimistic mutations, sibling writes, other tabs) re-render consumers- * immediately — this is the primitive that lets UI flow through urql- * instead of TanStack invalidation.- *- * Deliberately kept out of `@graphql-cache/index`: it depends on solid-js,- * which the transport-level consumers of that barrel must not pull in.- */--import type { TypedDocumentNode } from '@graphql-typed-document-node/core';-import type {- AnyVariables,- Client,- CombinedError,- RequestPolicy,-} from '@urql/core';-import {- type Accessor,- batch,- createRenderEffect,- createSignal,- onCleanup,- untrack,-} from 'solid-js';-import { pipe, subscribe } from 'wonka';--export type QuerySignal<TData> = {- /** Latest result data; retains the previous value across re-executions. */- data: Accessor<TData | undefined>;- error: Accessor<CombinedError | undefined>;- /** True from (re)subscription until the first result arrives. */- fetching: Accessor<boolean>;- /** True while the emitted result is a stale cache hit being revalidated. */- stale: Accessor<boolean>;-};--export type CreateQuerySignalOptions<TData, TVariables extends AnyVariables> = {- client: Accessor<Client>;- document: TypedDocumentNode<TData, TVariables>;- /**- * Reactive variables; `undefined` pauses the query (unsubscribes and- * reports `fetching: false` while keeping the last data).- */- variables: Accessor<TVariables | undefined>;- requestPolicy?: RequestPolicy;-};--export function createQuerySignal<TData, TVariables extends AnyVariables>(- options: CreateQuerySignalOptions<TData, TVariables>-): QuerySignal<TData> {- const [data, setData] = createSignal<TData | undefined>(undefined);- const [error, setError] = createSignal<CombinedError | undefined>(undefined);- const [fetching, setFetching] = createSignal(false);- const [stale, setStale] = createSignal(false);-- // Render effect: subscribes synchronously so consumers created in the- // same reactive scope observe `fetching` immediately.- createRenderEffect(() => {- const variables = options.variables();- if (variables === undefined) {- setFetching(false);- return;- }- const client = options.client();- setFetching(true);- const subscription = untrack(() =>- pipe(- client.query(options.document, variables, {- requestPolicy: options.requestPolicy,- }),- subscribe((result) => {- batch(() => {- // GraphQL responses may contain `data: null` at runtime when a- // non-null field error propagates to the operation root, even- // though urql's static type only includes `undefined`. Keep the- // last valid result and expose the CombinedError to the caller.- if (result.data != null) setData(() => result.data);- setError(result.error);- setStale(result.stale);- setFetching(false);- });- })- )- );- onCleanup(subscription.unsubscribe);- });-- return { data, error, fetching, stale };-}diff --git a/apps/web/src/lib/urql-solid/create-keyed-projection.test.ts b/apps/web/src/lib/queries/soup/create-keyed-projection.test.tssimilarity index 100%rename from apps/web/src/lib/urql-solid/create-keyed-projection.test.tsrename to apps/web/src/lib/queries/soup/create-keyed-projection.test.tsdiff --git a/apps/web/src/lib/urql-solid/create-keyed-projection.ts b/apps/web/src/lib/queries/soup/create-keyed-projection.tssimilarity index 90%rename from apps/web/src/lib/urql-solid/create-keyed-projection.tsrename to apps/web/src/lib/queries/soup/create-keyed-projection.tsindex 1357b3bf62..9c8838e4e0 100644--- a/apps/web/src/lib/urql-solid/create-keyed-projection.ts+++ b/apps/web/src/lib/queries/soup/create-keyed-projection.ts@@ -36,7 +36,12 @@ function equalSnapshot(value: unknown, previous: unknown): boolean {);}-/** Tracks and reconciles each projected item independently, retaining keyed identity. */+/**+ * Tracks and reconciles each projected item independently, retaining keyed identity.+ *+ * Soup row projection over records a query has already read; it does not read+ * data itself. Soup list sources and `createSoupRowStore` use it.+ */export function createKeyedProjection<T, K, U>(items: Accessor<readonly T[]>,key: (item: T, index: number) => K,diff --git a/apps/web/src/lib/graphql-cache/solid/create-predicate-query.test.ts b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.tssimilarity index 96%rename from apps/web/src/lib/graphql-cache/solid/create-predicate-query.test.tsrename to apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.tsindex b2557c0ec5..b5bd3a1c4d 100644--- a/apps/web/src/lib/graphql-cache/solid/create-predicate-query.test.ts+++ b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.ts@@ -2,15 +2,18 @@ import type { TypedDocumentNode } from '@graphql-typed-document-node/core';import { gql } from '@urql/core';import { createComputed, createRoot, createSignal } from 'solid-js';import { afterEach, expect, it } from 'vitest';-import { selectRecords } from '../exchange/record-selection';-import { createNoopCacheHost } from '../host/noop-host';-import type { CacheChangeListener, CacheHost } from '../host/types';+import { selectRecords } from '../../../graphql-cache/exchange/record-selection';+import { createNoopCacheHost } from '../../../graphql-cache/host/noop-host';+import type {+ CacheChangeListener,+ CacheHost,+} from '../../../graphql-cache/host/types';import {type EntityFilterCacheArgs,type EntityFilterCacheResult,type LiveQueryUpdate,parseCacheRevision,-} from '../protocol';+} from '../../../graphql-cache/protocol';import { createPredicateQuery } from './create-predicate-query';type Row = {diff --git a/apps/web/src/lib/graphql-cache/solid/create-predicate-query.ts b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.tssimilarity index 94%rename from apps/web/src/lib/graphql-cache/solid/create-predicate-query.tsrename to apps/web/src/lib/queries/soup/graphql/create-predicate-query.tsindex 41ebb9f13b..7464bb750c 100644--- a/apps/web/src/lib/graphql-cache/solid/create-predicate-query.ts+++ b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.ts@@ -9,13 +9,13 @@ import {untrack,} from 'solid-js';import { createStore, produce, reconcile } from 'solid-js/store';-import type { RecordSelection } from '../exchange/record-selection';-import type { CacheHost } from '../host/types';+import type { RecordSelection } from '../../../graphql-cache/exchange/record-selection';+import type { CacheHost } from '../../../graphql-cache/host/types';import {type CacheRevision,type EntityFilterCacheArgs,parseCacheRevision,-} from '../protocol';+} from '../../../graphql-cache/protocol';/** A declared source and generated fragment; no mutation-specific query updates. */export type PredicateQueryRequest<T> = {@@ -44,7 +44,13 @@ type LiveQueryHost = Pick<'entityFilter' | 'onCacheChanged' | 'onCacheGenerationChanged'>;-/** Owns subscription, coalescing, generation recovery, and keyed Solid rows. */+/**+ * Binds one cache-engine maintained view for `createSoupLiveQuery`. Owns+ * subscription, coalescing, generation recovery, and keyed Solid rows.+ *+ * Internal to the Soup query layer, not a general reactive query API: GraphQL+ * documents use `createLiveQuery`, and Soup lists use `createSoupLiveQuery`.+ */export function createPredicateQuery<T extends object>(options: {host: Accessor<LiveQueryHost | undefined>;query: Accessor<PredicateQueryRequest<T> | undefined>;diff --git a/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts b/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.tsindex d8c8179718..37f8092db2 100644--- a/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts+++ b/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts@@ -19,7 +19,6 @@ import { querySnapshot } from '../../../graphql-cache/exchange/live-query';import { normalizedCacheResultMetadata } from '../../../graphql-cache/exchange/normalized-cache-exchange';import { selectRecords } from '../../../graphql-cache/exchange/record-selection';import type { CacheRevision } from '../../../graphql-cache/protocol';-import { createPredicateQuery } from '../../../graphql-cache/solid/create-predicate-query';import {ChannelListItemFieldsFragmentDoc,ChannelListSoupDocument,@@ -42,6 +41,7 @@ import { createUrqlInfiniteQuery } from '../../../urql-solid/create-urql-infinitimport type { UrqlInfiniteData } from '../../../urql-solid/types';import { registerChannelNotificationRefresh } from '../../channel/register-notification-refresh';import { registerGraphqlSoupRevalidations } from './active-queries';+import { createPredicateQuery } from './create-predicate-query';import { isCachedMailView } from './mail-view';import {usePendingGraphqlSoupDeleteIds,@@ -78,6 +78,8 @@ const hasSoupPage = (page: SoupQuery | ChannelListSoupQuery): boolean =>/** Owns network pages, live cache records, Mail cursors, and fallback selection.* Data is a non-suspending accessor of reactive GraphQL records, before UI mapping.+ * This is the one GraphQL Soup list source; feature code reads it through+ * `useSoupAstItemsQuery`.*/export function createSoupLiveQuery(request: Accessor<SoupLiveQueryInput | undefined>,diff --git a/apps/web/src/lib/queries/soup/graphql/grouped-projection.ts b/apps/web/src/lib/queries/soup/graphql/grouped-projection.tsindex 9a34ff166c..c2341b92cb 100644--- a/apps/web/src/lib/queries/soup/graphql/grouped-projection.ts+++ b/apps/web/src/lib/queries/soup/graphql/grouped-projection.ts@@ -5,7 +5,7 @@ import {type GraphqlSoupItem,mapGraphqlSoupItem,} from '../../../service-clients/service-storage/graphql-soup';-import { createKeyedProjection } from '../../../urql-solid/create-keyed-projection';+import { createKeyedProjection } from '../create-keyed-projection';import { makeGroupComparator, resolveGroupMetaForKey } from '../grouped/api';import type { GroupByField, GroupMeta } from '../grouped/types';import type { SoupAstItemsData } from '../items';diff --git a/apps/web/src/lib/queries/soup/graphql/items.ts b/apps/web/src/lib/queries/soup/graphql/items.tsindex 516adfc4e2..dfb0ed754f 100644--- a/apps/web/src/lib/queries/soup/graphql/items.ts+++ b/apps/web/src/lib/queries/soup/graphql/items.ts@@ -6,8 +6,8 @@ import {type GraphqlSoupItem,mapGraphqlSoupItem,} from '../../../service-clients/service-storage/graphql-soup';-import { createKeyedProjection } from '../../../urql-solid/create-keyed-projection';import { useInstructionsMdIdQuery } from '../../storage/instructions-md';+import { createKeyedProjection } from '../create-keyed-projection';import { soupQueryExcludesDone } from '../excludes-done';import type { SoupAstBody, SoupAstItemsData, SoupAstParams } from '../items';import { soupEntityTimestamp } from '../page-timestamp';diff --git a/apps/web/src/lib/queries/soup/grouped/graphql/create-graphql-grouped-soup-queries.ts b/apps/web/src/lib/queries/soup/grouped/graphql/create-graphql-grouped-soup-queries.tsindex d8531d30cf..95a4599bd8 100644--- a/apps/web/src/lib/queries/soup/grouped/graphql/create-graphql-grouped-soup-queries.ts+++ b/apps/web/src/lib/queries/soup/grouped/graphql/create-graphql-grouped-soup-queries.ts@@ -1,6 +1,6 @@import { createUrqlInfiniteQuery } from '@app/lib/urql-solid';-import { createKeyedProjection } from '@app/lib/urql-solid/create-keyed-projection';import type { EntityData } from '@entity';+import { createKeyedProjection } from '@queries/soup/create-keyed-projection';import {makeGraphqlGroupedSoupContinuationInput,makeGraphqlGroupedSoupInput,diff --git a/apps/web/src/lib/urql-solid/create-urql-query.ts b/apps/web/src/lib/urql-solid/create-urql-query.tsindex 433f472295..cb802df350 100644--- a/apps/web/src/lib/urql-solid/create-urql-query.ts+++ b/apps/web/src/lib/urql-solid/create-urql-query.ts@@ -4,7 +4,12 @@ import { createBaseQuery } from './create-base-query';import { createQueryObserver } from './query-observer';import type { UrqlQueryOptions, UrqlQueryResult } from './types';-/** Creates a live Solid binding over one urql query observer. */+/**+ * Creates a live Solid binding over one urql query observer.+ *+ * New single-document reads use `createLiveQuery`, a document-first wrapper+ * over this binding. Existing callers are already live and need no migration.+ */export function createUrqlQuery<QueryData = unknown,Variables extends AnyVariables = AnyVariables,diff --git a/crates/client/README.md b/crates/client/README.mdindex b131f1750f..bf4e12ce91 100644--- a/crates/client/README.md+++ b/crates/client/README.md@@ -130,6 +130,11 @@ invalidations and gaps in that bounded journal conservatively rebuild the view.Views are released on unsubscribe and bounded by an LRU; eviction is safe becausea subscriber with an unavailable cursor receives a full replacement.+Web code has one default reactive read per data shape: `createSoupLiveQuery` for+Soup lists, which feature code reaches through `useSoupAstItemsQuery`, and+`createLiveQuery` for other GraphQL documents. See+[choosing a reactive read](../../apps/web/docs/graphql-normalized-cache-plan.md#choosing-a-reactive-read).+For Soup, `createSoupLiveQuery` owns network fetching, server pagination, cachebaselines, and local fallback selection. Its non-suspending `data()` accessorreturns reactive GraphQL records; callers do not coordinate cache revisions:@@ -157,20 +162,10 @@ The legacy REST-shaped Soup facade translates its request and projects theserecords into UI entities through one keyed mapper. Fetched versions remainseparate from local display versions so pagination coverage cannot drift.-The lower-level Solid `createPredicateQuery` binding owns subscription, coalescing,-cleanup and engine-generation recovery, preserving keyed row stores and applying-patches in one batch. Its first source adapter is a reconciled flat Soup filter:--```ts-const items = createPredicateQuery({- host: getGraphqlSoupCacheHost,- query: () => ({- source: { filters: filters(), sortMethod: 'UPDATED_AT',- sortDirection: 'DESC', limit: 50, baseline: serverMembership() },- select: selectRecords(SoupItemFieldsFragmentDoc),- }),-});-```+Inside `createSoupLiveQuery`, a Soup-internal binding owns subscription,+coalescing, cleanup and engine-generation recovery, preserving keyed row stores+and applying patches in one batch. Its only source is a reconciled flat Soup+filter; it is not a general query API.Mutations still use ordinary GraphQL execution and the registered local resolver.The view requires no per-mutation update callback. This is an incremental row@@ -190,9 +185,11 @@ const accounts = createLiveQuery();```-This uses the existing urql query contract, with cache-core tracking selected-fields and returning response-path patches. Existing `createUrqlQuery` and-`createUrqlInfiniteQuery` consumers benefit from the same path automatically.+It is a document-first wrapper over `createUrqlQuery`, so it keeps the existing+urql query contract while cache-core tracks selected fields and returns+response-path patches. Existing `createUrqlQuery` and `createUrqlInfiniteQuery`+consumers benefit from the same path automatically and need no migration;+cursor-paginated documents use `createUrqlInfiniteQuery`.Aliases, fragment types, arguments, variable defaults and conditional selectionsare resolved by the core reader. Structural edits rebuild the projection;teardown, account resets and bounded retention discard obsolete bindings. See