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
fix(database): open drafts immediately and avoid refresh races (#7994)
Wolf Mermelstein44747a4609d6
diff --git a/apps/web/src/features/block-database/queries/table-rows.test.tsx b/apps/web/src/features/block-database/queries/table-rows.test.tsxindex c8a43f00c9..c3aeaf724d 100644--- a/apps/web/src/features/block-database/queries/table-rows.test.tsx+++ b/apps/web/src/features/block-database/queries/table-rows.test.tsx@@ -1316,6 +1316,7 @@ describe("another writer's change", () => {let name = 'Ada';const engineRead = engine(() => guests([{ id: 'record', name }]));const host = {+ readQuery: async () => ({ kind: 'miss' as const }),// The view's rerun must not wait on a cache notification.onCacheChanged: () => () => {},entityFilter: async () => ({ kind: 'unsupported' as const }),@@ -1325,7 +1326,7 @@ describe("another writer's change", () => {}),} satisfies Pick<CacheHost,- 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys'+ 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys' | 'readQuery'>;const since = vi.fn((_version: number) =>okAsync({diff --git a/apps/web/src/features/block-database/queries/table-rows.ts b/apps/web/src/features/block-database/queries/table-rows.tsindex d75ff1f22b..be8d9c339f 100644--- a/apps/web/src/features/block-database/queries/table-rows.ts+++ b/apps/web/src/features/block-database/queries/table-rows.ts@@ -618,8 +618,12 @@ export function createDatabaseRowsSource(props: {: undefined;},loading: () => !rowsQuery.outcome() && rowsQuery.error() === undefined,- refreshing: rowsQuery.loading,- error: rowsQuery.error,+ refreshing: () =>+ rowsQuery.loading() ||+ (retainedRowIds().length > 0 && retainedQuery.loading()),+ error: () =>+ rowsQuery.error() ??+ (retainedRowIds().length > 0 ? retainedQuery.error() : undefined),refresh,addOption: props.addOption,retain: (rowIds) => setRetainedIds(() => rowIds),diff --git a/apps/web/src/features/database/primitives/table-controller.test.ts b/apps/web/src/features/database/primitives/table-controller.test.tsindex 09e275c91c..82936a2232 100644--- a/apps/web/src/features/database/primitives/table-controller.test.ts+++ b/apps/web/src/features/database/primitives/table-controller.test.ts@@ -39,7 +39,10 @@ const offline: DatabaseWriteFailure = {error: { code: 'NETWORK_ERROR', message: 'Offline', refusal: null },};-function setup(onSaved?: Parameters<typeof createTableController>[1]) {+function setup(+ onSaved?: Parameters<typeof createTableController>[1],+ overrides: Partial<DatabaseRowsSource> = {}+) {const [snapshot, setSnapshot] = createSignal<StoredTable>({rows: [{ rowId: 'record', cells: { status: 'To do', title: 'Plan launch' } },@@ -59,6 +62,7 @@ function setup(onSaved?: Parameters<typeof createTableController>[1]) {),addOption: vi.fn<DatabaseRowsSource['addOption']>(() => okAsync(undefined)),retain: () => {},+ ...overrides,};let dispose!: () => void;const controller = createRoot((cleanup) => {@@ -76,6 +80,51 @@ const move: DatabaseRowMutation = {};describe('table controller', () => {+ it('clears a failed-refresh warning when a background schema read succeeds', async () => {+ const [refreshing, setRefreshing] = createSignal(false);+ const { controller, source, setSnapshot, dispose } = setup(undefined, {+ refreshing,+ });+ vi.mocked(source.refresh).mockReturnValue(+ errAsync({ kind: 'fetch', message: 'Offline' })+ );+ await controller.refresh();+ expect(controller.refreshWarning()).toBe(true);+ setRefreshing(true);+ setSnapshot({ version: 2, rows: [] });+ setRefreshing(false);+ expect(controller.refreshWarning()).toBe(false);+ dispose();+ });+ it('keeps the warning when background revalidation fails', async () => {+ const [refreshing, setRefreshing] = createSignal(false);+ const { controller, source, dispose } = setup(undefined, {+ refreshing,+ error: () => ({ kind: 'fetch', message: 'Offline' }),+ });+ vi.mocked(source.refresh).mockReturnValue(+ errAsync({ kind: 'fetch', message: 'Offline' })+ );+ await controller.refresh();+ setRefreshing(true);+ setRefreshing(false);+ expect(controller.refreshWarning()).toBe(true);+ dispose();+ });+ it('does not let an older failed refresh overwrite a newer success', async () => {+ const { controller, source, dispose } = setup();+ const old = deferred<Result<void, { kind: 'fetch'; message: string }>>();+ vi.mocked(source.refresh)+ .mockReturnValueOnce(new ResultAsync(old.promise))+ .mockReturnValueOnce(okAsync(undefined));+ const earlier = controller.refresh();+ await controller.refresh();+ old.resolve(err({ kind: 'fetch', message: 'Old failure' }));+ await earlier;+ expect(controller.refreshWarning()).toBe(false);+ dispose();+ });+it('serializes adding a group with row writes and uses the schema refresh version', async () => {const { controller, source, setSnapshot, snapshot, dispose } = setup();const option = deferred<Result<void, DatabaseOpsError>>();diff --git a/apps/web/src/features/database/primitives/table-controller.ts b/apps/web/src/features/database/primitives/table-controller.tsindex 697dbde945..78e1c3487c 100644--- a/apps/web/src/features/database/primitives/table-controller.ts+++ b/apps/web/src/features/database/primitives/table-controller.ts@@ -1,7 +1,14 @@import { Telemetry } from '@macro-inc/observability';import type { DatabaseOpsError } from '@service-storage/databases';import { err, ok, type Result } from 'neverthrow';-import { batch, createMemo, createSignal, onCleanup } from 'solid-js';+import {+ batch,+ createEffect,+ createMemo,+ createSignal,+ on,+ onCleanup,+} from 'solid-js';import type {DatabaseRowsSource,DatabaseWriteResult,@@ -93,6 +100,7 @@ export function createTableController(const [refreshWarning, setRefreshWarning] = createSignal(false);const [schemaPending, setSchemaPending] = createSignal(0);let sequence = 0;+ let refreshGeneration = 0;// A new column's type settles against the newest version this writer has// seen, read or written; row ops themselves carry no version.let lastWrittenVersion: number | undefined;@@ -264,11 +272,25 @@ export function createTableController(}async function refresh(reason: 'after-write' | 'refresh' = 'refresh') {+ const generation = ++refreshGeneration;const refreshed = await source.refresh(reason);+ if (generation !== refreshGeneration) return;setRefreshWarning(refreshed.isErr());if (refreshed.isOk()) pruneCommitted();}+ // Schema/cache revalidation can finish outside this controller's refresh.+ // A successful newer read clears an old warning; an older failure cannot restore it.+ createEffect(+ on(source.refreshing, (refreshing, previous) => {+ if (previous && !refreshing && !source.error() && source.snapshot()) {+ refreshGeneration++;+ setRefreshWarning(false);+ pruneCommitted();+ }+ })+ );+/** Schema changes share the row-write queue because both advance the table version. */async function addGroup(columnId: string,diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.test.tsx b/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.test.tsxindex 0788d2a8c7..45cb19a22a 100644--- a/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.test.tsx+++ b/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.test.tsx@@ -35,6 +35,7 @@ const control = vi.hoisted(() => ({mounts: 0,cleanups: 0,clicks: 0,+ deferSaved: false,}));vi.mock('@core/constant/featureFlags', () => ({enableDatabases: { key: 'enable-databases' },@@ -46,7 +47,10 @@ vi.mock('@app/lib/analytics/posthog', () => ({useFeatureFlag: () => () => ({ enabled: control.enabled() }),}));vi.mock('./LazyDecorator', () => ({- LazyDecorator: (props: { render: () => JSX.Element }) => props.render(),+ LazyDecorator: (props: {+ placeholder: JSX.Element;+ render: () => JSX.Element;+ }) => (control.deferSaved ? props.placeholder : props.render()),}));vi.mock('@app/features/database-query/database-query', () => ({DatabaseLiveQuestion: (props: { source: { displayMode: string } }) => {@@ -79,6 +83,41 @@ vi.mock('@app/features/database-query/database-query', () => ({}));describe('database answer rollout', () => {+ it('opens new drafts without waiting for the saved-answer viewport gate', async () => {+ control.enabled = () => true;+ control.deferSaved = true;+ const draft = render(() => (+ <DatabaseQuery+ key="draft"+ theme={{}}+ queryId=""+ prompt=""+ displayMode="scalar"+ />+ ));+ try {+ await waitFor(() =>+ expect(draft.getByText('Interactive answer')).toBeTruthy()+ );+ const saved = render(() => (+ <DatabaseQuery+ key="saved"+ theme={{}}+ queryId="saved"+ prompt=""+ displayMode="scalar"+ title="Saved answer"+ />+ ));+ expect(saved.getByText('Saved answer')).toBeTruthy();+ expect(saved.queryByText('Interactive answer')).toBeNull();+ saved.unmount();+ } finally {+ draft.unmount();+ control.deferSaved = false;+ }+ });+it('keeps the saved title without mounting live query wiring when disabled', async () => {const [enabled, setEnabled] = createSignal(false);control.enabled = enabled;diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.tsx b/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.tsxindex 5c6b9607dd..46d0fb8291 100644--- a/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.tsx+++ b/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.tsx@@ -141,23 +141,30 @@ export function DatabaseQuery(props: DatabaseQueryDecoratorProps) {node.remove();});};+ const liveAnswer = () => (+ <Suspense fallback={placeholder()}>+ <LiveQuestion+ source={source}+ onSave={canEdit() ? save : undefined}+ onDiscard={canEdit() ? discard : undefined}+ />+ </Suspense>+ );const answer = () => (- <LazyDecorator- placeholder={placeholder()}- render={() => (- <Suspense fallback={placeholder()}>- <LiveQuestion- source={source}- onSave={canEdit() ? save : undefined}- onDiscard={canEdit() ? discard : undefined}- />- </Suspense>- )}- />+ <Show+ when={!props.queryId}+ fallback={+ <LazyDecorator placeholder={placeholder()} render={liveAnswer} />+ }+ >+ {liveAnswer()}+ </Show>);const placeholder = () => (<span class="mx-0.5 rounded border border-edge-muted bg-hover px-1.5 py-0.5 text-sm text-ink">- {props.title || props.chart?.title || 'Database answer'}+ {props.title ||+ props.chart?.title ||+ (!props.queryId ? 'Opening database…' : 'Database answer')}</span>);return (diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/actions.ts b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/actions.tsindex 0b5db3921b..8c15c8f94c 100644--- a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/actions.ts+++ b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/actions.ts@@ -8,8 +8,10 @@ import { ListNode } from '@lexical/list';import { HeadingNode, QuoteNode } from '@lexical/rich-text';import { INSERT_TABLE_COMMAND, TableNode } from '@lexical/table';import {+ $createAwaitNode,$createDatabaseQueryNode,$createDocumentMentionNode,+ $isAwaitNode,AwaitNode,CustomCodeNode,DatabaseQueryNode,@@ -39,8 +41,8 @@ import TextH1 from '@phosphor/text-h-one.svg';import TextH3 from '@phosphor/text-h-three.svg';import TextH2 from '@phosphor/text-h-two.svg';import TextT from '@phosphor/text-t.svg';-import type { LexicalEditor } from 'lexical';-import { $insertNodes } from 'lexical';+import type { LexicalEditor, NodeKey } from 'lexical';+import { $getNodeByKey, $insertNodes } from 'lexical';import { nanoid } from 'nanoid';import { INSERT_HORIZONTAL_RULE_COMMAND } from '..';import {@@ -374,10 +376,30 @@ export const ACTIONS: Action[] = [action: (editor, context) => {if (!isFeatureEnabled(enableDatabases)) return;queueMicrotask(async () => {+ let placeholderKey: NodeKey | undefined;try {+ if (!editor.isEditable()) return;+ // Anchor and show feedback before the creation module downloads.+ editor.update(+ () => {+ const placeholder = $createAwaitNode({+ awaitId: nanoid(),+ text: 'Creating database…',+ });+ $insertNodes([placeholder]);+ placeholderKey = placeholder.getKey();+ },+ { discrete: true }+ );const { insertNewDatabase } = await import('./insert-database');- await insertNewDatabase(editor, context);+ await insertNewDatabase(editor, context, placeholderKey);} catch (error: unknown) {+ editor.update(() => {+ const placeholder = placeholderKey+ ? $getNodeByKey(placeholderKey)+ : null;+ if ($isAwaitNode(placeholder)) placeholder.remove();+ });Telemetry.error('database.insert.failed', { error: String(error) });toast.failure('The database could not be inserted. Try again.');}diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.test.ts b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.test.tsindex 4f40f8b5c5..64a7303960 100644--- a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.test.ts+++ b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.test.ts@@ -1,12 +1,17 @@import { registerRichText } from '@lexical/rich-text';import {+ $createAwaitNode,$isDocumentCardNode,+ AwaitNode,SupportedNodeTypes,} from '@macro-inc/lexical-core';import {$createParagraphNode,$createTextNode,+ $getNodeByKey,$getRoot,+ $insertNodes,+ $nodesOfType,createEditor,} from 'lexical';import { err, ok, type Result } from 'neverthrow';@@ -84,6 +89,63 @@ describe('creating a database in a document', () => {});});+ it('uses the placeholder already shown while the creation module loaded', async () => {+ const editor = documentEditor();+ let key!: string;+ editor.update(+ () => {+ const placeholder = $createAwaitNode({+ awaitId: 'pending',+ text: 'Creating database…',+ });+ $insertNodes([placeholder]);+ key = placeholder.getKey();+ },+ { discrete: true }+ );+ let finish!: (result: Result<string, unknown>) => void;+ mocks.create.mockReturnValue(+ new Promise((resolve) => {+ finish = resolve;+ })+ );+ const creating = insertNewDatabase(editor, undefined, key);+ expect(editor.read(() => $nodesOfType(AwaitNode))).toHaveLength(1);+ finish(ok('db-1'));+ await creating;+ expect(mocks.create).toHaveBeenCalledOnce();+ expect(+ editor.read(() => $getRoot().getChildren().filter($isDocumentCardNode))+ ).toHaveLength(1);+ });++ it.each(['removed', 'read-only'] as const)(+ 'does not create if the pending insert became %s while its module loaded',+ async (state) => {+ const editor = documentEditor();+ let key!: string;+ editor.update(+ () => {+ const placeholder = $createAwaitNode({+ awaitId: 'pending',+ text: 'Creating database…',+ });+ $insertNodes([placeholder]);+ key = placeholder.getKey();+ },+ { discrete: true }+ );+ if (state === 'removed')+ editor.update(() => $getNodeByKey(key)?.remove(), { discrete: true });+ else editor.setEditable(false);+ await insertNewDatabase(editor, undefined, key);+ expect(mocks.create).not.toHaveBeenCalled();+ expect(editor.read(() => $getRoot().getTextContent())).toBe(+ 'Before. After.'+ );+ }+ );+it('does not insert elsewhere when the placeholder was removed during creation', async () => {let finish!: (result: Result<string, unknown>) => void;mocks.create.mockReturnValue(diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.ts b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.tsindex d694b69cf7..e0b0e99148 100644--- a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.ts+++ b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.ts@@ -22,18 +22,31 @@ import type { ActionContext } from './types';/** Keep the insertion anchored while creation runs, even if the caret moves. */export async function insertNewDatabase(editor: LexicalEditor,- context?: ActionContext+ context?: ActionContext,+ placeholderKey?: NodeKey) {- if (!editor.isEditable()) return;- let placeholderKey: NodeKey | undefined;- editor.update(() => {- const placeholder = $createAwaitNode({- awaitId: nanoid(),- text: 'Creating database…',+ const pendingKey = placeholderKey;+ if (!editor.isEditable()) {+ if (pendingKey)+ editor.update(() => {+ const placeholder = $getNodeByKey(pendingKey);+ if ($isAwaitNode(placeholder)) placeholder.remove();+ });+ return;+ }+ if (pendingKey) {+ // The user can remove the pending insert while this module downloads.+ if (!editor.read(() => $isAwaitNode($getNodeByKey(pendingKey)))) return;+ } else {+ editor.update(() => {+ const placeholder = $createAwaitNode({+ awaitId: nanoid(),+ text: 'Creating database…',+ });+ $insertNodes([placeholder]);+ placeholderKey = placeholder.getKey();});- $insertNodes([placeholder]);- placeholderKey = placeholder.getKey();- });+ }let mentionUuid: string | undefined;let inserted = false;diff --git a/apps/web/src/lib/queries/database-sql/create-database-sql-query.test.ts b/apps/web/src/lib/queries/database-sql/create-database-sql-query.test.tsindex 9b61e6885b..87bdbddfa1 100644--- a/apps/web/src/lib/queries/database-sql/create-database-sql-query.test.ts+++ b/apps/web/src/lib/queries/database-sql/create-database-sql-query.test.ts@@ -11,6 +11,7 @@ import type { CacheHost } from '@graphql-cache/host/types';import type {CacheRevision,EntityFilterCacheResult,+ ReadResult,} from '@graphql-cache/protocol';import type { SoupQuery } from '@service-storage/graphql/generated/graphql';import {@@ -187,6 +188,18 @@ describe('createDatabaseSqlQuery', () => {{client: () => client,cacheHost: () => ({+ readQuery: async () =>+ cacheHit+ ? {+ kind: 'hit',+ data: {+ user: {+ id: 'macro|[email protected]',+ soup: { items: [acme], nextCursor: null },+ },+ },+ }+ : { kind: 'miss' },onCacheChanged: () => () => {},entityFilter: vi.fn(),readRecordsByKeys: vi.fn(),@@ -207,7 +220,7 @@ describe('createDatabaseSqlQuery', () => {else expect(query.outcome()).toBeUndefined();expect(query.error()).toBeUndefined();expect(query.loading()).toBe(true);- expect(policies).toEqual(['cache-only', 'network-only']);+ expect(policies).toEqual(['network-only']);expect(loadingStates).toEqual([true]);finishNetwork?.();await vi.waitFor(() =>@@ -220,6 +233,69 @@ describe('createDatabaseSqlQuery', () => {});+ it('lands an after-write refresh while its initial cache probe is still pending', async () => {+ let finishCache!: (result: ReadResult) => void;+ const readQuery = vi.fn(+ () =>+ new Promise<ReadResult>((resolve) => {+ finishCache = resolve;+ })+ );+ const policies: string[] = [];+ const exchange: Exchange = () => (incoming) =>+ pipe(+ incoming,+ mergeMap((operation) => {+ if (operation.kind === 'teardown') return empty;+ policies.push(operation.context.requestPolicy);+ return fromValue({+ operation,+ data: {+ user: {+ id: 'macro|[email protected]',+ soup: { items: [globex], nextCursor: null },+ },+ },+ stale: false,+ hasNext: false,+ });+ })+ );+ const client = createClient({+ url: 'http://test.invalid/graphql',+ exchanges: [exchange],+ });+ const query = createRoot((cleanup) => {+ dispose = cleanup;+ return createDatabaseSqlQuery(+ () => ({ schema, sql: 'SELECT name FROM crm.deals' }),+ {+ client: () => client,+ cacheHost: () => ({+ readQuery,+ onCacheChanged: () => () => {},+ entityFilter: vi.fn(),+ readRecordsByKeys: vi.fn(),+ }),+ people: async () => [],+ catalog: async () => catalog,+ open: names,+ }+ );+ });+ await vi.waitFor(() => expect(readQuery).toHaveBeenCalledOnce());+ expect((await query.refresh('after-write'))._unsafeUnwrap()).toEqual({+ landed: true,+ });+ finishCache({ kind: 'miss' });+ await new Promise((resolve) => setTimeout(resolve, 0));+ expect(query.error()).toBeUndefined();+ expect(query.outcome()?.rows).toEqual([+ [{ type: 'text', value: 'Globex' }],+ ]);+ expect(policies).toEqual(['network-only']);+ });+it('shows a row the cache learns about without reading the network again', async () => {const requests: Operation[] = [];const exchange: Exchange = () => (incoming) =>@@ -258,6 +334,15 @@ describe('createDatabaseSqlQuery', () => {async () => reconciled);const host = {+ readQuery: async () => ({+ kind: 'hit' as const,+ data: {+ user: {+ id: 'macro|[email protected]',+ soup: { items: [acme], nextCursor: null },+ },+ },+ }),onCacheChanged: (callback: (revision: CacheRevision) => void) => {cacheChanged = callback;return () => {};@@ -272,7 +357,7 @@ describe('createDatabaseSqlQuery', () => {}),} satisfies Pick<CacheHost,- 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys'+ 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys' | 'readQuery'>;const query = createRoot((cleanup) => {@@ -294,7 +379,7 @@ describe('createDatabaseSqlQuery', () => {);expect(requests.map((operation) => operation.context.requestPolicy)- ).toEqual(['cache-only', 'network-only']);+ ).toEqual(['network-only']);cacheChanged(revision);@@ -304,7 +389,7 @@ describe('createDatabaseSqlQuery', () => {[{ type: 'text', value: 'Acme' }],]));- expect(requests).toHaveLength(2);+ expect(requests).toHaveLength(1);expect(entityFilter).toHaveBeenCalledWith({filters: requests[0]?.variables?.input.initial.filters,sortMethod: 'CREATED_AT',@@ -486,6 +571,15 @@ describe('createDatabaseSqlQuery', () => {let cacheChanged = (_revision: CacheRevision) => {};// The cache has not heard of the refreshed rows yet.const host = {+ readQuery: async () => ({+ kind: 'hit' as const,+ data: {+ user: {+ id: 'macro|[email protected]',+ soup: { items: [acme], nextCursor: null },+ },+ },+ }),onCacheChanged: (callback: (revision: CacheRevision) => void) => {cacheChanged = callback;return () => {};@@ -505,7 +599,7 @@ describe('createDatabaseSqlQuery', () => {}),} satisfies Pick<CacheHost,- 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys'+ 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys' | 'readQuery'>;const query = createRoot((cleanup) => {dispose = cleanup;diff --git a/apps/web/src/lib/queries/database-sql/create-database-sql-query.ts b/apps/web/src/lib/queries/database-sql/create-database-sql-query.tsindex b69a7e4d87..b610fd916a 100644--- a/apps/web/src/lib/queries/database-sql/create-database-sql-query.ts+++ b/apps/web/src/lib/queries/database-sql/create-database-sql-query.ts@@ -76,7 +76,10 @@ type BuildCatalog = (schema: Schema, scope?: string) => Promise<Catalog>;export interface DatabaseSqlQueryCapabilities {client: () => Client;cacheHost: () =>- | Pick<CacheHost, 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys'>+ | Pick<+ CacheHost,+ 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys' | 'readQuery'+ >| undefined;people: () => Promise<Person[]>;/** The engine; the wasm module unless a test says otherwise. */@@ -191,6 +194,7 @@ export function createDatabaseSqlQuery(client: capabilities.client(),catalog: built,requestPolicy,+ cache: host,people: capabilities.people,membership: host ? { host, baselines, reconcile } : undefined,}),diff --git a/apps/web/src/lib/queries/database-sql/graphql-source.test.ts b/apps/web/src/lib/queries/database-sql/graphql-source.test.tsindex 25218b5529..3ff45f27c1 100644--- a/apps/web/src/lib/queries/database-sql/graphql-source.test.ts+++ b/apps/web/src/lib/queries/database-sql/graphql-source.test.ts@@ -1,13 +1,24 @@import { runDatabaseSql } from '@core/database-sql/driver';import { readTranscript, replay } from '@core/database-sql/tests/transcript';+import { normalizedCacheExchange } from '@graphql-cache/exchange/normalized-cache-exchange';+import type { CacheHost, CacheReadArgs } from '@graphql-cache/host/types';+import {+ INITIAL_CACHE_REVISION,+ type ReadResult,+} from '@graphql-cache/protocol';import type {DatabaseRowFieldsFragment,DatabaseRowsQuery,GroupSoupQuery,SoupPropertyValueFieldsFragment,} from '@service-storage/graphql/generated/graphql';-import { createClient, type Exchange, type Operation } from '@urql/core';-import { describe, expect, it } from 'vitest';+import {+ createClient,+ type Exchange,+ fetchExchange,+ type Operation,+} from '@urql/core';+import { describe, expect, it, vi } from 'vitest';import { empty, fromValue, mergeMap, pipe } from 'wonka';import { createGraphqlRowSource } from './graphql-source';@@ -370,3 +381,80 @@ describe('the GraphQL row source', () => {]);});});++describe('concurrent SQL cache and network reads', () => {+ it.each([+ ['cache-only', false],+ ['cache-first', false],+ ['cache-first', true],+ ] as const)(+ 'keeps a %s probe independent from a network refresh (hit: %s)',+ async (requestPolicy, cacheHit) => {+ const transcript = readTranscript('row-position');+ let finishCache!: (value: ReadResult) => void;+ const readQuery = vi.fn(+ (_args: CacheReadArgs) =>+ new Promise<ReadResult>((resolve) => {+ finishCache = resolve;+ })+ );+ const host = {+ readQuery,+ writeQuery: async () => ({+ revision: INITIAL_CACHE_REVISION,+ revisionAdvanced: true,+ changed: [],+ affectedOps: [],+ reset: false,+ }),+ teardown: async () => {},+ onMutationSettled: () => () => {},+ onOpsAffected: () => () => {},+ onCacheGenerationChanged: () => () => {},+ claimNextMutation: async () => undefined,+ } as unknown as CacheHost;+ const fetch = vi.fn(+ async () =>+ new Response(+ JSON.stringify({ data: soupPage([initech, globex, acme], null) }),+ {+ status: 200,+ headers: { 'content-type': 'application/json' },+ }+ )+ );+ const client = createClient({+ url: 'http://test.invalid/graphql',+ fetch,+ exchanges: [normalizedCacheExchange(host), fetchExchange],+ });+ const read = (policy: 'cache-only' | 'cache-first' | 'network-only') =>+ runDatabaseSql(transcript.catalog, transcript.sql, {+ source: createGraphqlRowSource({+ client,+ catalog: transcript.catalog,+ requestPolicy: policy,+ cache: host,+ people: noPeople,+ }),+ open: replay(transcript),+ });+ const probe = read(requestPolicy);+ await vi.waitFor(() => expect(readQuery).toHaveBeenCalledTimes(1));+ const refresh = read('network-only');+ // With a cache-only urql subscription this request joins the probe and+ // never reaches fetchExchange, even after the cache miss resolves.+ await vi.waitFor(() => expect(fetch).toHaveBeenCalledTimes(1));+ expect(readQuery.mock.calls[0][0].opKey).toBeUndefined();+ finishCache(+ cacheHit+ ? { kind: 'hit', data: soupPage([initech, globex, acme], null) }+ : { kind: 'miss' }+ );+ expect((await refresh)._unsafeUnwrap()).toEqual(transcript.outcome);+ const cached = await probe;+ if (requestPolicy === 'cache-only') expect(cached.isErr()).toBe(true);+ else expect(cached._unsafeUnwrap()).toEqual(transcript.outcome);+ }+ );+});diff --git a/apps/web/src/lib/queries/database-sql/graphql-source.ts b/apps/web/src/lib/queries/database-sql/graphql-source.tsindex d79f82af6e..0025847141 100644--- a/apps/web/src/lib/queries/database-sql/graphql-source.ts+++ b/apps/web/src/lib/queries/database-sql/graphql-source.ts@@ -44,7 +44,9 @@ import {import {type AnyVariables,type Client,+ createRequest,type DocumentInput,+ getOperationName,type RequestPolicy,stringifyDocument,} from '@urql/core';@@ -65,6 +67,8 @@ interface GraphqlRowSourceCapabilities {/** The statement's catalog, for the value kinds of grouped columns. */catalog: Catalog;requestPolicy: RequestPolicy;+ /** Probe the cache without subscribing to a shared urql operation. */+ cache?: Pick<CacheHost, 'readQuery'>;/** Everyone the viewer can see. */people: () => Promise<Person[]>;/**@@ -124,29 +128,63 @@ function graphqlQuery<Data, Variables extends AnyVariables>(variables: Variables,requestPolicy: RequestPolicy,name: string,- step: DatabaseSqlStepTrace+ step: DatabaseSqlStepTrace,+ cache?: Pick<CacheHost, 'readQuery'>): ResultAsync<Data, DatabaseSqlFetchFailure> {step.request(stringifyDocument(document), variables);- return ResultAsync.fromPromise(- client- .query(document, variables, {- requestPolicy,- fetchOptions: { headers: step.headers() },- })- .toPromise(),- thrownFetchFailure- ).andThen((result): Result<Data, DatabaseSqlFetchFailure> => {- if (result.error) return err(fetchFailure(result.error.message));- if (!result.data)- return err(fetchFailure(`the ${name} query returned no data`));- return ok(result.data);- });+ const network = () =>+ ResultAsync.fromPromise(+ client+ .query(document, variables, {+ requestPolicy:+ cache && requestPolicy === 'cache-first'+ ? 'network-only'+ : requestPolicy,+ fetchOptions: { headers: step.headers() },+ })+ .toPromise(),+ thrownFetchFailure+ ).andThen((result): Result<Data, DatabaseSqlFetchFailure> => {+ if (!result)+ return err(fetchFailure(`the ${name} query ended without data`));+ if (result.error) return err(fetchFailure(result.error.message));+ if (!result.data)+ return err(fetchFailure(`the ${name} query returned no data`));+ return ok(result.data);+ });+ // Cache probes must not register an urql operation: a simultaneous refresh+ // with the same key would join that probe and never send a network request.+ if (+ cache &&+ (requestPolicy === 'cache-only' || requestPolicy === 'cache-first')+ ) {+ return ResultAsync.fromPromise(+ cache.readQuery({+ query: stringifyDocument(document),+ operationName: getOperationName(+ createRequest(document, variables).query+ ),+ variables: variables || undefined,+ }),+ thrownFetchFailure+ )+ .orElse(() => okAsync({ kind: 'miss' as const }))+ .andThen((result) =>+ result.kind === 'hit'+ ? okAsync(result.data as Data)+ : requestPolicy === 'cache-only'+ ? errAsync(fetchFailure(`the ${name} query returned no data`))+ : network()+ );+ }+ return network();}export function createGraphqlRowSource({client,catalog,requestPolicy,+ cache,people,membership,}: GraphqlRowSourceCapabilities): RowSource {@@ -156,7 +194,7 @@ export function createGraphqlRowSource({.returnType<ResultAsync<Page, DatabaseSqlFetchFailure>>().with({ type: 'soup' }, (soup) =>soupInput(soup, cursor, limit).asyncAndThen((input) =>- soupPage(client, requestPolicy, input, membership, step)+ soupPage(client, requestPolicy, input, membership, step, cache))).with({ type: 'people' }, ({ ids }) => peoplePage(catalog, people, ids))@@ -168,7 +206,7 @@ export function createGraphqlRowSource({match(query).returnType<ResultAsync<Bin[], DatabaseSqlFetchFailure>>().with({ type: 'groupSoup' }, (grouped) =>- groupBins(client, requestPolicy, catalog, grouped, step)+ groupBins(client, requestPolicy, catalog, grouped, step, cache)).with({ type: P.union('soup', 'people') }, () =>errAsync(fetchFailure('only a grouped query has bins'))@@ -323,7 +361,8 @@ function soupPage(requestPolicy: RequestPolicy,input: SoupInput,membership: LocalMembership | undefined,- step: DatabaseSqlStepTrace+ step: DatabaseSqlStepTrace,+ cache?: Pick<CacheHost, 'readQuery'>): ResultAsync<Page, DatabaseSqlFetchFailure> {const evidence = input.initial ? JSON.stringify(input) : undefined;const local: ResultAsync<Page | undefined, DatabaseSqlFetchFailure> =@@ -339,7 +378,8 @@ function soupPage({ input },requestPolicy,'database rows',- step+ step,+ cache).andThen((data) => {const { items, nextCursor } = data.user.soup;if (evidence && membership && isNetworkRead(requestPolicy)) {@@ -477,7 +517,8 @@ function groupBins(requestPolicy: RequestPolicy,catalog: Catalog,{ table, propf, groupBy }: Extract<GqlQuery, { type: 'groupSoup' }>,- step: DatabaseSqlStepTrace+ step: DatabaseSqlStepTrace,+ cache?: Pick<CacheHost, 'readQuery'>): ResultAsync<Bin[], DatabaseSqlFetchFailure> {const kind = catalog.tables.find((candidate) => candidate.id === table)@@ -517,7 +558,8 @@ function groupBins(},requestPolicy,'grouped Soup',- step+ step,+ cache)).andThen((data) =>diff --git a/apps/web/src/lib/queries/storage/databases.test.ts b/apps/web/src/lib/queries/storage/databases.test.tsindex 68262b246a..67555a7127 100644--- a/apps/web/src/lib/queries/storage/databases.test.ts+++ b/apps/web/src/lib/queries/storage/databases.test.ts@@ -236,6 +236,32 @@ describe('creating a database', () => {});});+ it('returns the committed id while database discovery is still refreshing', async () => {+ mock.create.mockReturnValue(okAsync({ ...detail.database, id: 'new-db' }));+ let finish!: () => void;+ const invalidating = vi+ .spyOn(queryClient, 'invalidateQueries')+ .mockImplementationOnce(+ () =>+ new Promise<void>((resolve) => {+ finish = resolve;+ })+ );+ try {+ const created = await createDatabase({+ name: 'Untitled database',+ source: 'slash-menu',+ });+ expect(created._unsafeUnwrap()).toBe('new-db');+ expect(invalidating).toHaveBeenCalledWith({+ queryKey: databasesKeys.list.queryKey,+ });+ } finally {+ finish?.();+ invalidating.mockRestore();+ }+ });+it('hands a refusal back to the caller', async () => {mock.create.mockReturnValue(errAsync([{ code: 'INVALID_SCHEMA', message: 'name is empty' }])diff --git a/apps/web/src/lib/queries/storage/databases.ts b/apps/web/src/lib/queries/storage/databases.tsindex 2976770073..538cf6f170 100644--- a/apps/web/src/lib/queries/storage/databases.ts+++ b/apps/web/src/lib/queries/storage/databases.ts@@ -331,13 +331,14 @@ export function createDatabase(params: {}): ResultAsync<string, ResultError<DatabaseSchemaErrorCode>[]> {return storageServiceClient.databases.create({ name: params.name })- .map(async ({ id }) => {+ .map(({ id }) => {analytics.track('create_entity', {entityType: 'database',entityId: id,source: params.source,});- await queryClient.invalidateQueries({+ // Creation is committed. Refresh discovery without blocking the new editor.+ void queryClient.invalidateQueries({queryKey: databasesKeys.list.queryKey,});return id;diff --git a/docs/AGENT_GUIDE/databases.md b/docs/AGENT_GUIDE/databases.mdindex 88b121046d..c9d41d69bf 100644--- a/docs/AGENT_GUIDE/databases.md+++ b/docs/AGENT_GUIDE/databases.md@@ -9,6 +9,11 @@ match its name, including databases with no view history.Creating from Home immediately shows the table selector with its **+** menu, **Databaseactions**, and **AI** in the top bar; no reload is needed to use them.+`/database` immediately shows **Creating database…** at the insertion point while+the creation module loads. Moving the caret keeps that insertion anchored; removing+it before the module loads cancels creation.+A successful create opens its new editor while database discovery refreshes in+the background; a slow discovery refresh must not delay the new database card.Databases open at`/app/database/<uuid>`. A database contains tables; records belong to a table andits properties describe each record. The database name in the split header is an@@ -19,6 +24,9 @@ split header's `viewer` badge instead.Reopening a loaded table or view shows its cached rows while a background readchecks for changes. Wait for refreshing to finish before asserting serverreconciliation; visible rows alone do not mean the network read has completed.+Concurrent cache-only misses must not fail an outstanding network row read. A+successful background read clears an earlier refresh warning; a genuine failed+read keeps the warning and its Refresh action.**AI** in the split header opens an agent chat about the database. Its composerstarts with a mention of the database; the schema and table guidance go to the@@ -474,7 +482,9 @@ The same tools are exposed to agent sessions through the Macro MCP server.In a document, channel composer, or the task/document creation composer,`/query` → **Query** opens the question box with the AI prompt focused-immediately. The empty input rotates through example questions; a selected database+immediately. New draft questions bypass the saved-answer viewport gate; a cold+module load shows **Opening database…** until the question input is ready. Saved+answers still load when they approach the viewport. The empty input rotates through example questions; a selected databaseuses its actual table and column names. Typing hides these hints, and reduced-motionpreferences keep them static. Use the searchable source picker below the question tochoose a database; the entire chosen database is in scope, without a table