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/mobile cache (#6840)

Sean Ayeeab69eda28e0
diff --git a/apps/web/package.json b/apps/web/package.json
index b7274ec4b4..c8bc862118 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -137,6 +137,7 @@
"exceljs": "4.4.0",
"fflate": "0.8.3",
"graphql-ws": "^6.1.0",
+ "jose": "^6.2.12",
"katex": "^0.16.22",
"lexical": "0.45.0",
"libheif-js": "^1.19.8",
@@ -196,6 +197,7 @@
"bebop": "3.1.3",
"bebop-tools": "3.1.3",
"concurrently": "^9.2.1",
+ "fake-indexeddb": "^6.2.5",
"graphql": "^16.9.0",
"jsdom": "^26.1.0",
"json-refs": "^3.0.15",
diff --git a/apps/web/src/features/block-email/EmailBlockAdapter.tsx b/apps/web/src/features/block-email/EmailBlockAdapter.tsx
index f6115d1284..6e908d55e7 100644
--- a/apps/web/src/features/block-email/EmailBlockAdapter.tsx
+++ b/apps/web/src/features/block-email/EmailBlockAdapter.tsx
@@ -1,4 +1,7 @@
-import type { EmailThreadHost } from '@app/features/email-thread/context/email-thread-context';
+import type {
+ EmailThreadHost,
+ EmailThreadSource,
+} from '@app/features/email-thread/context/email-thread-context';
import { URL_PARAMS } from '@app/features/email-thread/core/location';
import {
useCanAutofocusSplitContent,
@@ -16,13 +19,18 @@ import { blockHandleSignal } from '@core/signal/load';
import { useSearchParams } from '@solidjs/router';
import { type Accessor, createEffect, createSignal, onCleanup } from 'solid-js';
import { TopBar } from './component/TopBar';
-import { EmailThreadHostView } from './EmailThreadHostView';
+import {
+ EmailThreadHostView,
+ type EmailThreadHostViewProps,
+} from './EmailThreadHostView';
import { useEmailListNavigation } from './use-email-list-navigation';
import { registerEmailHotkeys } from './util/emailHotkeys';
export function EmailBlockAdapter(props: {
title: string;
threadId: Accessor<string>;
+ source: EmailThreadSource;
+ threadTransport: EmailThreadHostViewProps['threadTransport'];
}) {
const [params] = useSearchParams();
const rawTarget = params[URL_PARAMS.messageId];
@@ -80,6 +88,8 @@ export function EmailBlockAdapter(props: {
<EmailThreadHostView
title={props.title}
threadId={props.threadId}
+ source={props.source}
+ threadTransport={props.threadTransport}
host={host}
topBar={({ createTask }) => (
<TopBar
diff --git a/apps/web/src/features/block-email/EmailThreadHostView.tsx b/apps/web/src/features/block-email/EmailThreadHostView.tsx
index 4e81a57054..57ef3252f8 100644
--- a/apps/web/src/features/block-email/EmailThreadHostView.tsx
+++ b/apps/web/src/features/block-email/EmailThreadHostView.tsx
@@ -1,7 +1,13 @@
import { AskMacroButton } from '@app/features/chat/ChatWithAgentButton';
-import type { EmailThreadHost } from '@app/features/email-thread/context/email-thread-context';
+import type {
+ EmailThreadHost,
+ EmailThreadSource,
+} from '@app/features/email-thread/context/email-thread-context';
import { useEmailThreadState } from '@app/features/email-thread/context/email-thread-state-context';
-import { EmailThread } from '@app/features/email-thread/email-thread';
+import {
+ EmailThread,
+ type EmailThreadProps,
+} from '@app/features/email-thread/email-thread';
import { SidePanel } from '@components/app/side-panel';
import { useSplitLayout } from '@components/app/split-layout/layout';
import { buildMentionMarkdownString } from '@macro-inc/lexical-core';
@@ -18,6 +24,8 @@ export type EmailThreadHostViewContext = {
export type EmailThreadHostViewProps = {
title: string;
threadId: Accessor<string>;
+ source: EmailThreadSource;
+ threadTransport: EmailThreadProps['threadTransport'];
host: EmailThreadHost;
topBar?: (context: EmailThreadHostViewContext) => JSX.Element;
sidePanelHeaderToggle?: boolean;
@@ -54,6 +62,8 @@ export function EmailThreadHostView(props: EmailThreadHostViewProps) {
<EmailThread
title={props.title}
threadId={props.threadId}
+ source={props.source}
+ threadTransport={props.threadTransport}
host={props.host}
header={props.topBar?.({ createTask })}
actions={<ThreadActions title={props.title} onCreateTask={createTask} />}
diff --git a/apps/web/src/features/block-email/component/Block.tsx b/apps/web/src/features/block-email/component/Block.tsx
index f1de5b74c8..eb4b6a0ecc 100644
--- a/apps/web/src/features/block-email/component/Block.tsx
+++ b/apps/web/src/features/block-email/component/Block.tsx
@@ -1,4 +1,5 @@
import { displaySubject } from '@app/features/email-compose/core/subject-text';
+import { createEmailThreadSource } from '@app/features/email-thread/queries/thread-source';
import { useBlockEntityCommands } from '@app/features/next-soup/actions';
import { ContentLoading } from '@components/app/ContentLoading';
import { useGlobalNotificationSource } from '@components/app/GlobalAppState';
@@ -20,6 +21,7 @@ export default function BlockEmail() {
const threadQuery = useThreadQuery(threadId, () => ({
enabled: !!threadId(),
}));
+ const source = createEmailThreadSource(threadId, threadQuery);
// Email threads are absent from quick access, so the entity the block-level
// commands act on has to come from here. Gated on isSuccess so the
@@ -83,7 +85,12 @@ export default function BlockEmail() {
<Show when={threadId()}>
{(id) => (
<Suspense fallback={<ContentLoading />}>
- <EmailBlockAdapter title={title()} threadId={id} />
+ <EmailBlockAdapter
+ title={title()}
+ threadId={id}
+ source={source}
+ threadTransport={() => threadQuery.transport}
+ />
</Suspense>
)}
</Show>
diff --git a/apps/web/src/features/block-email/component/TopBar.tsx b/apps/web/src/features/block-email/component/TopBar.tsx
index 962964312f..cc4720d500 100644
--- a/apps/web/src/features/block-email/component/TopBar.tsx
+++ b/apps/web/src/features/block-email/component/TopBar.tsx
@@ -43,6 +43,7 @@ import NoiseIcon from '@phosphor/waveform.svg';
import CheckBoldIcon from '@phosphor-icons/core/bold/check-bold.svg?component-solid';
import ArrowCounterClockwise from '@phosphor-icons/core/regular/arrow-counter-clockwise.svg?component-solid';
import { useEmailLinksQuery } from '@queries/email/link';
+import { queryReadyGate } from '@queries/gate';
import { Button } from '@ui';
import { Show } from 'solid-js';
@@ -66,9 +67,8 @@ export function TopBar(props: {
const isOwnThread = () => {
const thread = emailCtx.thread();
- const links = linksQuery.data?.links;
- if (!thread || !links) return false;
- return links.some((link) => link.id === thread.link_id);
+ if (!thread || !queryReadyGate(linksQuery)) return false;
+ return linksQuery.data.links.some((link) => link.id === thread.link_id);
};
const isDone = () => emailCtx.isThreadDone();
diff --git a/apps/web/src/features/block-email/component/sidepanel/EmailSidePanelSections.test.tsx b/apps/web/src/features/block-email/component/sidepanel/EmailSidePanelSections.test.tsx
new file mode 100644
index 0000000000..355f2cd381
--- /dev/null
+++ b/apps/web/src/features/block-email/component/sidepanel/EmailSidePanelSections.test.tsx
@@ -0,0 +1,87 @@
+import { cleanup, render, screen, waitFor } from '@solidjs/testing-library';
+import {
+ QueryClient,
+ QueryClientProvider,
+ useQuery,
+} from '@tanstack/solid-query';
+import { type JSX, type ParentProps, Suspense } from 'solid-js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { EmailSidePanelSections } from './EmailSidePanelSections';
+
+const mocks = vi.hoisted(() => ({ references: vi.fn() }));
+vi.mock('@queries/storage/attachment-references', () => ({
+ useAttachmentReferencesQuery: () => mocks.references(),
+}));
+vi.mock(
+ '@app/features/email-thread/context/email-thread-state-context',
+ () => ({
+ useEmailThreadState: () => ({ permissions: () => ({ isOwner: true }) }),
+ })
+);
+vi.mock('@app/features/activity/views/entity-activity-section', () => ({
+ EntityActivitySectionConditional: () => null,
+}));
+vi.mock('@app/features/property/side-panel/properties', () => ({
+ EntityPropertiesSection: () => null,
+ EntityTagsSection: () => null,
+}));
+vi.mock('@core/component/References', () => ({
+ References: () => <div>Reference details</div>,
+}));
+vi.mock('@components/app/side-panel', () => ({
+ SidePanel: {
+ Section: (props: ParentProps<{ title: JSX.Element }>) => (
+ <section>
+ {props.title}
+ {props.children}
+ </section>
+ ),
+ CountTitle: (props: { label: string; count: number }) => (
+ <span>
+ {props.label} ({props.count})
+ </span>
+ ),
+ Loading: () => null,
+ },
+}));
+
+const clients: QueryClient[] = [];
+afterEach(() => {
+ cleanup();
+ for (const client of clients.splice(0)) client.clear();
+});
+
+describe('email optional references', () => {
+ it('does not suspend the email body while references load, then updates the count', async () => {
+ const response = Promise.withResolvers<unknown[]>();
+ const client = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ clients.push(client);
+ mocks.references.mockImplementation(() =>
+ useQuery(() => ({
+ queryKey: ['references-test'],
+ queryFn: () => response.promise,
+ }))
+ );
+ render(() => (
+ <QueryClientProvider client={client}>
+ <Suspense fallback={<div data-testid="loading" />}>
+ <div data-testid="email">
+ Cached body
+ <EmailSidePanelSections threadId="thread" title="Subject" />
+ </div>
+ </Suspense>
+ </QueryClientProvider>
+ ));
+ expect(screen.getByTestId('email').textContent).toContain('Cached body');
+ expect(screen.queryByTestId('loading')).toBeNull();
+ expect(screen.queryByText('Reference details')).toBeNull();
+ response.resolve([{}, {}]);
+ await waitFor(() =>
+ expect(screen.getByText('References (2)')).toBeTruthy()
+ );
+ expect(screen.getByText('Reference details')).toBeTruthy();
+ expect(screen.queryByTestId('loading')).toBeNull();
+ });
+});
diff --git a/apps/web/src/features/block-email/component/sidepanel/EmailSidePanelSections.tsx b/apps/web/src/features/block-email/component/sidepanel/EmailSidePanelSections.tsx
index b811ff94d9..ba952ae0ef 100644
--- a/apps/web/src/features/block-email/component/sidepanel/EmailSidePanelSections.tsx
+++ b/apps/web/src/features/block-email/component/sidepanel/EmailSidePanelSections.tsx
@@ -6,6 +6,7 @@ import {
} from '@app/features/property/side-panel/properties';
import { SidePanel } from '@components/app/side-panel';
import { References } from '@core/component/References';
+import { queryReadyGate } from '@queries/gate';
import { useAttachmentReferencesQuery } from '@queries/storage/attachment-references';
import { Show, Suspense } from 'solid-js';
@@ -59,7 +60,7 @@ function ReferencesSectionConditional(props: { threadId: string }) {
() => 'email'
);
- const count = () => references.data?.length ?? 0;
+ const count = () => (queryReadyGate(references) ? references.data.length : 0);
return (
<Show when={count() > 0}>
diff --git a/apps/web/src/features/block-md/component/MarkdownDocument.tsx b/apps/web/src/features/block-md/component/MarkdownDocument.tsx
index 8d1f959e24..8888a5c0a2 100644
--- a/apps/web/src/features/block-md/component/MarkdownDocument.tsx
+++ b/apps/web/src/features/block-md/component/MarkdownDocument.tsx
@@ -9,7 +9,7 @@ import {
} from '@macro-inc/collaboration/collab/snapshot-store';
import type {
InitialSync,
- TimeoutError,
+ SyncError,
} from '@macro-inc/collaboration/collab/source';
import {
BrowserWALStore,
@@ -143,7 +143,7 @@ async function ingestLocalSnapshot(
async function ingestRemoteSnapshot(
loroManager: MarkdownLoroManager,
- doInitialSync: () => ResultAsync<InitialSync, TimeoutError>
+ doInitialSync: () => ResultAsync<InitialSync, SyncError>
): Promise<SnapshotResult> {
const sync = await doInitialSync();
if (sync.isErr()) {
@@ -226,7 +226,7 @@ export function MarkdownDocument(props: ParentProps<MarkdownDocumentProps>) {
}
type MarkdownSnapshotIngestOptions = {
- doInitialSync?: () => ResultAsync<InitialSync, TimeoutError>;
+ doInitialSync?: () => ResultAsync<InitialSync, SyncError>;
optimisticSnapshot?: Uint8Array<ArrayBufferLike>;
loadCachedSnapshot?: () => Promise<Uint8Array | undefined>;
onDataReady?: () => void;
diff --git a/apps/web/src/features/block-md/component/ModalsProvider.tsx b/apps/web/src/features/block-md/component/ModalsProvider.tsx
index a9aed3b68c..1a72481968 100644
--- a/apps/web/src/features/block-md/component/ModalsProvider.tsx
+++ b/apps/web/src/features/block-md/component/ModalsProvider.tsx
@@ -5,6 +5,7 @@ import {
ShareDialogContext,
ShareModal,
} from '@core/component/TopBar/ShareButton';
+import { queryReadyGate } from '@queries/gate';
import { useDocumentMetadataQuery } from '@queries/storage/document-metadata';
import {
createSignal,
@@ -76,7 +77,9 @@ export function ModalsProvider(
itemType="document"
name={displayName() ?? ''}
userPermissions={permissions()}
- owner={metadataQuery.data?.owner}
+ owner={
+ queryReadyGate(metadataQuery) ? metadataQuery.data.owner : undefined
+ }
/>
</Suspense>
</ShareDialogContext.Provider>
diff --git a/apps/web/src/features/block-md/component/TaskDuplicateMatches.test.tsx b/apps/web/src/features/block-md/component/TaskDuplicateMatches.test.tsx
new file mode 100644
index 0000000000..b8bd49be74
--- /dev/null
+++ b/apps/web/src/features/block-md/component/TaskDuplicateMatches.test.tsx
@@ -0,0 +1,99 @@
+import type { TaskDuplicate } from '@service-storage/client';
+import { cleanup, render, screen, waitFor } from '@solidjs/testing-library';
+import {
+ QueryClient,
+ QueryClientProvider,
+ useQuery,
+} from '@tanstack/solid-query';
+import { type ParentProps, Suspense } from 'solid-js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { TaskDuplicateMatchPill } from './TaskDuplicateMatches';
+
+const mocks = vi.hoisted(() => ({ matches: vi.fn(), enabled: true }));
+vi.mock('@app/lib/analytics/posthog', () => ({
+ useFeatureFlag: () => () => ({ enabled: mocks.enabled }),
+}));
+vi.mock('@queries/storage/task-duplicates', () => ({
+ useTaskDuplicatesQuery: () => mocks.matches(),
+ useDismissTaskDuplicatesMutation: () => ({ mutateAsync: vi.fn() }),
+}));
+vi.mock('../context/markdown-document-context', () => ({
+ useMarkdownDocument: () => ({ documentId: () => 'doc' }),
+}));
+vi.mock('@components/app/side-panel', () => ({
+ SidePanel: { Section: (props: ParentProps) => props.children },
+}));
+vi.mock(
+ '@core/component/LexicalMarkdown/component/decorator/DocumentMention',
+ () => ({ DocumentMention: () => null })
+);
+vi.mock('@core/component/Toast/Toast', () => ({
+ toast: { success: vi.fn(), failure: vi.fn() },
+}));
+vi.mock('@ui', () => {
+ const Container = (props: ParentProps) => <div>{props.children}</div>;
+ return {
+ cn: () => '',
+ Button: Container,
+ Dropdown: Object.assign(Container, {
+ Trigger: Container,
+ Content: Container,
+ Group: Container,
+ }),
+ };
+});
+
+const clients: QueryClient[] = [];
+afterEach(() => {
+ cleanup();
+ for (const client of clients.splice(0)) client.clear();
+ mocks.enabled = true;
+});
+
+function mount() {
+ const response = Promise.withResolvers<TaskDuplicate[]>();
+ const client = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ clients.push(client);
+ mocks.matches.mockImplementation(() =>
+ useQuery(() => ({
+ queryKey: ['duplicates-test'],
+ queryFn: () => response.promise,
+ }))
+ );
+ render(() => (
+ <QueryClientProvider client={client}>
+ <Suspense fallback={<div data-testid="loading" />}>
+ <div data-testid="editor">
+ Cached body
+ <TaskDuplicateMatchPill />
+ </div>
+ </Suspense>
+ </QueryClientProvider>
+ ));
+ return response;
+}
+
+describe('optional task duplicate matches', () => {
+ it('does not suspend the editor while matches are pending and renders matches when ready', async () => {
+ const response = mount();
+ expect(screen.getByTestId('editor').textContent).toBe('Cached body');
+ expect(screen.queryByTestId('loading')).toBeNull();
+ response.resolve([
+ { id: 'match', taskId: 'task', taskName: 'Similar task', vectorScore: 1 },
+ ]);
+ await waitFor(() =>
+ expect(screen.getByTestId('editor').textContent).toContain(
+ 'Possible duplicate'
+ )
+ );
+ });
+
+ it('does not suspend when the duplicate feature is disabled', () => {
+ mocks.enabled = false;
+ mount();
+ expect(screen.getByTestId('editor').textContent).toBe('Cached body');
+ expect(screen.queryByTestId('loading')).toBeNull();
+ });
+});
diff --git a/apps/web/src/features/block-md/component/TaskDuplicateMatches.tsx b/apps/web/src/features/block-md/component/TaskDuplicateMatches.tsx
index 366193e79e..d3ddc075f6 100644
--- a/apps/web/src/features/block-md/component/TaskDuplicateMatches.tsx
+++ b/apps/web/src/features/block-md/component/TaskDuplicateMatches.tsx
@@ -5,13 +5,14 @@ import { toast } from '@core/component/Toast/Toast';
import { enableTaskDuplicates } from '@core/constant/featureFlags';
import CaretDownIcon from '@phosphor/caret-down.svg';
import WarningIcon from '@phosphor/warning.svg';
+import { queryReadyGate } from '@queries/gate';
import {
useDismissTaskDuplicatesMutation,
useTaskDuplicatesQuery,
} from '@queries/storage/task-duplicates';
import type { TaskDuplicate } from '@service-storage/client';
import { Button, cn, Dropdown } from '@ui';
-import { createMemo, createSignal, For, Show, Suspense } from 'solid-js';
+import { createSignal, For, Show, Suspense } from 'solid-js';
import { useMarkdownDocument } from '../context/markdown-document-context';
export function TaskDuplicateMatchPill() {
@@ -82,7 +83,7 @@ function useTaskDuplicateMatches() {
const matchesQuery = useTaskDuplicatesQuery(() => blockId);
const dismissMutation = useDismissTaskDuplicatesMutation(() => blockId);
- const matches = createMemo(() => matchesQuery.data ?? []);
+ const matches = () => (queryReadyGate(matchesQuery) ? matchesQuery.data : []);
const count = () => matches().length;
const dismiss = async (matchesToDismiss: TaskDuplicate[]) => {
diff --git a/apps/web/src/features/block-md/component/sidepanel/MarkdownSidePanelSections.tsx b/apps/web/src/features/block-md/component/sidepanel/MarkdownSidePanelSections.tsx
index 736d90a312..9deedbc14f 100644
--- a/apps/web/src/features/block-md/component/sidepanel/MarkdownSidePanelSections.tsx
+++ b/apps/web/src/features/block-md/component/sidepanel/MarkdownSidePanelSections.tsx
@@ -42,6 +42,7 @@ import {
getDefaultPinnedProperties,
SYSTEM_PROPERTY_IDS,
} from '@property/constants';
+import { queryReadyGate } from '@queries/gate';
import { useAttachmentReferencesQuery } from '@queries/storage/attachment-references';
import { useDocumentMetadataQuery } from '@queries/storage/document-metadata';
import {
@@ -606,7 +607,7 @@ function ReferencesSectionConditional(props: { documentId: string }) {
() => 'document'
);
- const count = createMemo(() => references.data?.length ?? 0);
+ const count = () => (queryReadyGate(references) ? references.data.length : 0);
return (
<Show when={count() > 0}>
diff --git a/apps/web/src/features/block-md/definition.ts b/apps/web/src/features/block-md/definition.ts
index 004b741225..3a6dfb3dd7 100644
--- a/apps/web/src/features/block-md/definition.ts
+++ b/apps/web/src/features/block-md/definition.ts
@@ -1,16 +1,6 @@
-import {
- defineBlock,
- type ExtractLoadType,
- LoadErrors,
- loadResult,
-} from '@core/block';
+import { defineBlock, type ExtractLoadType, LoadErrors } from '@core/block';
import { ENABLE_MARKDOWN_LIVE_COLLABORATION } from '@core/constant/featureFlags';
-import { ThrownResultError } from '@core/util/result';
-import {
- fetchDocumentLocation,
- waitForDocumentSyncServiceReady,
-} from '@queries/storage/document-location';
-import { fetchDocumentLoadBundle } from '@queries/storage/documentLoad/documentLoadBundle';
+import { fetchSyncDocumentOpenContext } from '@queries/storage/documentLoad/sync-document-context';
import { makeFileFromBlob } from '@service-storage/util/makeFileFromBlob';
import { createSyncServiceSource } from '@service-sync/source';
import { err, ok } from 'neverthrow';
@@ -54,86 +44,23 @@ export const definition = defineBlock({
registerDocumentSpan(documentId, rootSpan);
}
return rootSpan.span('doc.load', async (loadSpan) => {
- const loadBundle = () =>
- loadSpan.span('doc.load.bundle', async (bundleSpan) => {
- const result = await fetchDocumentLoadBundle(documentId);
- if (result.isErr()) {
- bundleSpan.error(new ThrownResultError(result.error));
- }
- return result;
- });
-
- // The location span covers the sync-service readiness wait too, so it
- // reflects when the document actually became loadable.
- const loadLocation = () =>
- loadSpan.span('doc.load.location', async (locationSpan) => {
- const result = await loadResult(
- fetchDocumentLocation({ documentId })
- );
- if (result.isErr()) {
- locationSpan.error(new ThrownResultError(result.error));
- return result;
- }
- let location = result.value;
- if (
- location.type === 'presignedUrl' &&
- location.content.state === 'pending'
- ) {
- location = await waitForDocumentSyncServiceReady({
- documentId,
- }).catch((error) => {
- console.error(
- 'Failed waiting for markdown sync-service location',
- error
- );
- return location;
- });
- locationSpan.setAttr('location.pending', true);
- return ok(location);
- }
- return ok(location);
- });
-
- const [maybeBundle, maybeLocation] = await Promise.all([
- loadBundle(),
- loadLocation(),
- ]);
- if (maybeBundle.isErr()) {
- loadSpan.error('load bundle failed');
- rootSpan.error('load bundle failed');
- endDocumentSpan(documentId);
- return err(maybeBundle.error);
- }
- const { token, documentMetadata, userAccessLevel } = maybeBundle.value;
-
- if (maybeLocation.isErr()) {
- loadSpan.error('load location failed');
- rootSpan.error('load location failed');
- endDocumentSpan(documentId);
- return err(maybeLocation.error);
- }
-
- const location = maybeLocation.value;
-
- // Markdown initialization and lifecycle persistence are backend-owned.
- // If a markdown document still resolves to object storage here, opening
- // it would require a backend repair/backfill path rather than a frontend
- // sync-service mutation that leaves DB content metadata inconsistent.
- if (location.type !== 'syncServiceContent') {
- console.error(
- 'Markdown document is not available in sync-service',
- documentId,
- location.content
- );
- loadSpan.error('markdown document not in sync-service');
- rootSpan.error('markdown document not in sync-service');
+ const context = await loadSpan.span('doc.load.context', () =>
+ fetchSyncDocumentOpenContext(documentId)
+ );
+ if (context.isErr()) {
+ loadSpan.error('load context failed');
+ rootSpan.error('load context failed');
endDocumentSpan(documentId);
- return LoadErrors.INVALID;
+ return err(context.error);
}
+ const { token, authorization, documentMetadata, userAccessLevel } =
+ context.value;
+ loadSpan.setAttr('doc.context.cached', context.value.fromCache);
const { source: syncSource, doInitialSync } = createSyncServiceSource(
source.id,
- token
+ token,
+ authorization
);
// HACK: unfortunately, most blocks still rely on a dssFile for things like
diff --git a/apps/web/src/features/block-md/queries/markdown-document.ts b/apps/web/src/features/block-md/queries/markdown-document.ts
index 50120f957e..f8ddbe64cd 100644
--- a/apps/web/src/features/block-md/queries/markdown-document.ts
+++ b/apps/web/src/features/block-md/queries/markdown-document.ts
@@ -1,8 +1,5 @@
-import {
- fetchDocumentLocation,
- waitForDocumentSyncServiceReady,
-} from '@queries/storage/document-location';
-import { fetchDocumentLoadBundle } from '@queries/storage/documentLoad/documentLoadBundle';
+import { throwOnErr } from '@core/util/result';
+import { fetchSyncDocumentOpenContext } from '@queries/storage/documentLoad/sync-document-context';
import type { AccessLevel } from '@service-storage/generated/schemas/accessLevel';
import type { DocumentMetadata } from '@service-storage/generated/schemas/documentMetadata';
import { createSyncServiceSource } from '@service-sync/source';
@@ -23,30 +20,8 @@ export type MarkdownDocumentData = ReturnType<
export async function loadMarkdownDocument(
documentId: string
): Promise<MarkdownDocumentData> {
- const [bundleResult, locationResult] = await Promise.all([
- fetchDocumentLoadBundle(documentId),
- fetchDocumentLocation({ documentId }),
- ]);
-
- if (bundleResult.isErr()) {
- throw new Error('Unable to load document metadata');
- }
- if (locationResult.isErr()) {
- throw new Error('Unable to load document content');
- }
-
- let location = locationResult.value;
- if (
- location.type === 'presignedUrl' &&
- location.content.state === 'pending'
- ) {
- location = await waitForDocumentSyncServiceReady({ documentId });
- }
- if (location.type !== 'syncServiceContent') {
- throw new Error('Document content is not available in sync-service');
- }
-
- const { documentMetadata, token, userAccessLevel } = bundleResult.value;
+ const { documentMetadata, token, authorization, userAccessLevel } =
+ await throwOnErr(() => fetchSyncDocumentOpenContext(documentId));
const permissions = match(userAccessLevel)
.with('owner', () => ({
canComment: true,
@@ -71,7 +46,7 @@ export async function loadMarkdownDocument(
.exhaustive();
return {
- ...createSyncServiceSource(documentId, token),
+ ...createSyncServiceSource(documentId, token, authorization),
metadata: documentMetadata,
userAccessLevel,
permissions,
diff --git a/apps/web/src/features/block-spreadsheet/definition.ts b/apps/web/src/features/block-spreadsheet/definition.ts
index 38efb3b3d7..f9a1c058fc 100644
--- a/apps/web/src/features/block-spreadsheet/definition.ts
+++ b/apps/web/src/features/block-spreadsheet/definition.ts
@@ -1,11 +1,5 @@
-import {
- defineBlock,
- type ExtractLoadType,
- LoadErrors,
- loadResult,
-} from '@core/block';
-import { fetchDocumentLocation } from '@queries/storage/document-location';
-import { fetchDocumentLoadBundle } from '@queries/storage/documentLoad/documentLoadBundle';
+import { defineBlock, type ExtractLoadType, LoadErrors } from '@core/block';
+import { fetchSyncDocumentOpenContext } from '@queries/storage/documentLoad/sync-document-context';
import { createSyncServiceSource } from '@service-sync/source';
import { err, ok } from 'neverthrow';
import { lazy } from 'solid-js';
@@ -24,20 +18,16 @@ export const definition = defineBlock({
if (!isSpreadsheetEnabledForCurrentUser()) return LoadErrors.UNAUTHORIZED;
if (source.type !== 'sync-service') return LoadErrors.INVALID;
if (intent === 'preload') return ok({ type: 'preload', origin: source });
- const [bundle, location] = await Promise.all([
- fetchDocumentLoadBundle(source.id),
- loadResult(fetchDocumentLocation({ documentId: source.id })),
- ]);
- if (bundle.isErr()) return err(bundle.error);
- if (location.isErr()) return err(location.error);
- if (location.value.type !== 'syncServiceContent') return LoadErrors.INVALID;
+ const context = await fetchSyncDocumentOpenContext(source.id);
+ if (context.isErr()) return err(context.error);
const { source: syncSource, doInitialSync } = createSyncServiceSource(
source.id,
- bundle.value.token
+ context.value.token,
+ context.value.authorization
);
return ok({
- documentMetadata: bundle.value.documentMetadata,
- userAccessLevel: bundle.value.userAccessLevel,
+ documentMetadata: context.value.documentMetadata,
+ userAccessLevel: context.value.userAccessLevel,
syncSource,
doInitialSync,
});
diff --git a/apps/web/src/features/block-spreadsheet/queries/spreadsheet-session.ts b/apps/web/src/features/block-spreadsheet/queries/spreadsheet-session.ts
index 1e6df481af..75063c962e 100644
--- a/apps/web/src/features/block-spreadsheet/queries/spreadsheet-session.ts
+++ b/apps/web/src/features/block-spreadsheet/queries/spreadsheet-session.ts
@@ -11,8 +11,8 @@ import {
import {
type InitialSync,
type LiveSyncSource,
+ type SyncError,
SyncSourceStatus,
- type TimeoutError,
} from '@macro-inc/collaboration/collab/source';
import {
BrowserWALStore,
@@ -39,7 +39,7 @@ export type SpreadsheetSessionOptions = {
userId?: string;
canEdit: Accessor<boolean>;
syncSource: LiveSyncSource;
- doInitialSync: () => ResultAsync<InitialSync, TimeoutError>;
+ doInitialSync: () => ResultAsync<InitialSync, SyncError>;
};
// Snapshot stores for successive mounts share one IndexedDB key. Finish an
diff --git a/apps/web/src/features/companies/crm/deal-stages.test.tsx b/apps/web/src/features/companies/crm/deal-stages.test.tsx
new file mode 100644
index 0000000000..582cee18d9
--- /dev/null
+++ b/apps/web/src/features/companies/crm/deal-stages.test.tsx
@@ -0,0 +1,189 @@
+import { SYSTEM_PROPERTY_IDS } from '@property/constants';
+import type { PropertyDefinitionResponse } from '@service-properties/generated/schemas/propertyDefinitionResponse';
+import type { PropertyDefinitionWithOptions } from '@service-properties/generated/schemas/propertyDefinitionWithOptions';
+import { cleanup, render, screen, waitFor } from '@solidjs/testing-library';
+import {
+ QueryClient,
+ QueryClientProvider,
+ useQuery,
+} from '@tanstack/solid-query';
+import { createMemo, Show, Suspense } from 'solid-js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { CRM_TEAM_STAGE_DEFINITION_NAME, useDealStages } from './deal-stages';
+
+const mocks = vi.hoisted(() => ({ definitions: vi.fn() }));
+vi.mock('@queries/properties/definitions', () => ({
+ useListPropertiesQuery: () => mocks.definitions(),
+}));
+vi.mock('./team-crm-config', () => ({
+ useTeamCrmConfig: () => ({ config: () => ({}), isLoading: () => false }),
+}));
+
+const customized: PropertyDefinitionWithOptions = {
+ definition: {
+ id: 'team-stages',
+ display_name: CRM_TEAM_STAGE_DEFINITION_NAME,
+ data_type: 'SELECT_STRING',
+ is_metadata: false,
+ is_multi_select: false,
+ is_system: false,
+ owner: { scope: 'team', team_id: 'team' },
+ created_at: '2026-01-01T00:00:00Z',
+ updated_at: '2026-01-01T00:00:00Z',
+ },
+ property_options: [
+ {
+ id: 'qualified',
+ property_definition_id: 'team-stages',
+ display_order: 0,
+ value: { type: 'string', value: 'Qualified' },
+ created_at: '2026-01-01T00:00:00Z',
+ updated_at: '2026-01-01T00:00:00Z',
+ },
+ ],
+};
+
+const clients: QueryClient[] = [];
+afterEach(() => {
+ cleanup();
+ for (const client of clients.splice(0)) client.clear();
+ vi.clearAllMocks();
+});
+
+function mount(consumeStages: boolean, providerOwned = false) {
+ const response = Promise.withResolvers<PropertyDefinitionResponse[]>();
+ const client = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ clients.push(client);
+ mocks.definitions.mockImplementation(() =>
+ useQuery(() => ({
+ queryKey: ['test-team-definitions'],
+ queryFn: () => response.promise,
+ }))
+ );
+ function View() {
+ const stages = useDealStages();
+ return consumeStages ? (
+ <div data-testid="stages">
+ {stages.stageDefinitionId()}:
+ {stages
+ .stages()
+ .map((stage) => stage.label)
+ .join(',')}
+ </div>
+ ) : (
+ <div data-testid="document">Cached document</div>
+ );
+ }
+ function ProviderOwnedView() {
+ // SoupViewContextProvider creates its stage source and grouping memo
+ // above the CRM child's boundary. SplitPanel wraps the provider itself.
+ const stages = useDealStages();
+ const group = createMemo(() => {
+ if (!consumeStages) return 'Cached document';
+ const stage = stages.resolveStage({
+ properties: [
+ {
+ definition: { id: 'team-stages' },
+ value: { type: 'SelectOption', value: ['qualified'] },
+ },
+ ],
+ });
+ return `${stages.stageDefinitionId()}:${stages
+ .stages()
+ .map((entry) => entry.label)
+ .join(',')}:${stage ?? 'Not set'}`;
+ });
+ return (
+ <Suspense fallback={<div data-testid="crm-loading" />}>
+ <div data-testid={consumeStages ? 'stages' : 'document'}>{group()}</div>
+ </Suspense>
+ );
+ }
+ render(() => (
+ <QueryClientProvider client={client}>
+ <div data-testid="split-chrome">Split chrome</div>
+ <Suspense fallback={<div data-testid="loading" />}>
+ <Show when={providerOwned} fallback={<View />}>
+ <ProviderOwnedView />
+ </Show>
+ </Suspense>
+ </QueryClientProvider>
+ ));
+ return { response, client };
+}
+
+describe('deal-stage projections in shared soup contexts', () => {
+ it('does not suspend an unrelated document while team definitions are pending', () => {
+ mount(false);
+ expect(screen.queryByTestId('loading')).toBeNull();
+ expect(screen.getByTestId('document').textContent).toBe('Cached document');
+ });
+
+ it('still suspends a CRM consumer until its team-specific stages are known', async () => {
+ const h = mount(true);
+ expect(screen.queryByTestId('stages')).toBeNull();
+ expect(screen.getByTestId('loading')).toBeTruthy();
+ h.response.resolve([customized]);
+ await waitFor(() =>
+ expect(screen.getByTestId('stages').textContent).toBe(
+ 'team-stages:Qualified'
+ )
+ );
+ expect(screen.queryByTestId('loading')).toBeNull();
+ h.client.setQueryData(
+ ['test-team-definitions'],
+ [
+ {
+ ...customized,
+ property_options: [
+ {
+ ...customized.property_options[0],
+ value: { type: 'string', value: 'Updated' },
+ },
+ ],
+ },
+ ]
+ );
+ await waitFor(() =>
+ expect(screen.getByTestId('stages').textContent).toBe(
+ 'team-stages:Updated'
+ )
+ );
+ });
+
+ it('keeps provider-owned grouping hidden under the split boundary until custom stages resolve', async () => {
+ const h = mount(true, true);
+ expect(screen.getByTestId('split-chrome')).toBeTruthy();
+ expect(screen.getByTestId('loading')).toBeTruthy();
+ expect(screen.queryByTestId('crm-loading')).toBeNull();
+ expect(screen.queryByTestId('stages')).toBeNull();
+ expect(screen.queryByText(/Not set/)).toBeNull();
+ h.response.resolve([customized]);
+ await waitFor(() =>
+ expect(screen.getByTestId('stages').textContent).toBe(
+ 'team-stages:Qualified:qualified'
+ )
+ );
+ expect(screen.queryByTestId('loading')).toBeNull();
+ });
+
+ it('does not suspend provider-owned document views on unused CRM queries', () => {
+ mount(false, true);
+ expect(screen.queryByTestId('loading')).toBeNull();
+ expect(screen.queryByTestId('crm-loading')).toBeNull();
+ expect(screen.getByTestId('document').textContent).toBe('Cached document');
+ });
+
+ it('uses system defaults only after resolving that the team has no custom definition', async () => {
+ const h = mount(true);
+ expect(screen.queryByTestId('stages')).toBeNull();
+ h.response.resolve([]);
+ await waitFor(() =>
+ expect(screen.getByTestId('stages').textContent).toContain(
+ SYSTEM_PROPERTY_IDS.STAGE
+ )
+ );
+ });
+});
diff --git a/apps/web/src/features/companies/crm/deal-stages.ts b/apps/web/src/features/companies/crm/deal-stages.ts
index 9af36b16dd..2ed98be6e8 100644
--- a/apps/web/src/features/companies/crm/deal-stages.ts
+++ b/apps/web/src/features/companies/crm/deal-stages.ts
@@ -15,7 +15,7 @@
// module loads inside soup-view-context's import chain, where the barrel
// can still be mid-initialization (circular import) and its re-exports
// undefined at module-eval time.
-import { soupPropertyToProperty } from '@entity/extractors-property';
+import { soupPropertyToProperty } from '@entity/extractors-property/property-helpers';
import { getCompanyStageOptionId } from '@entity/utils/company-properties';
import {
ALL_COMPANY_STAGE_OPTIONS,
@@ -31,7 +31,8 @@ import { useListPropertiesQuery } from '@queries/properties/definitions';
import type { PropertyDefinitionResponse } from '@service-properties/generated/schemas/propertyDefinitionResponse';
import type { PropertyDefinitionWithOptions } from '@service-properties/generated/schemas/propertyDefinitionWithOptions';
import type { PropertyOption } from '@service-properties/generated/schemas/propertyOption';
-import { type Accessor, createMemo } from 'solid-js';
+import { createLazyMemo } from '@solid-primitives/memo';
+import type { Accessor } from 'solid-js';
import { useTeamCrmConfig } from './team-crm-config';
// Canonical home is `@property/constants` (property pickers filter on it);
@@ -220,18 +221,23 @@ export function useDealStages(): DealStages {
}));
const teamCrmConfig = useTeamCrmConfig();
- const teamStageDefinition = createMemo(() =>
+ // Shared soup contexts also mount for documents and other non-CRM views.
+ // Only read the query when a stage consumer needs it; actual CRM consumers
+ // retain their Suspense behavior rather than treating pending data as defaults.
+ // Lazy memos keep their creation owner: SplitPanel wraps the soup provider
+ // itself in Suspense, covering provider-owned grouping as well as its children.
+ const teamStageDefinition = createLazyMemo(() =>
findTeamStageDefinition(teamDefinitionsQuery.data)
);
// Customized only once the team set actually has stages; an empty custom
// set keeps the system defaults active (see stages() below).
- const isCustomized = createMemo(() => {
+ const isCustomized = createLazyMemo(() => {
const definition = teamStageDefinition();
return !!definition && stagesFromDefinition(definition).length > 0;
});
- const stages = createMemo((): DealStage[] => {
+ const stages = createLazyMemo((): DealStage[] => {
const definition = teamStageDefinition();
if (!definition) return DEFAULT_STAGES;
const customStages = stagesFromDefinition(definition);
@@ -240,18 +246,18 @@ export function useDealStages(): DealStages {
return customStages.length > 0 ? customStages : DEFAULT_STAGES;
});
- const filterStages = createMemo((): DealStage[] =>
+ const filterStages = createLazyMemo((): DealStage[] =>
isCustomized() ? stages() : ALL_SYSTEM_STAGES
);
- const stageDefinitionId = createMemo(() => {
+ const stageDefinitionId = createLazyMemo(() => {
const definition = teamStageDefinition();
return definition && stagesFromDefinition(definition).length > 0
? definition.definition.id
: SYSTEM_PROPERTY_IDS.STAGE;
});
- const stageProperty = createMemo(() => {
+ const stageProperty = createLazyMemo(() => {
const definition = teamStageDefinition();
return buildStagePropertyStub(
definition && stagesFromDefinition(definition).length > 0
@@ -260,9 +266,9 @@ export function useDealStages(): DealStages {
);
});
- const stageIds = createMemo(() => new Set(stages().map((s) => s.id)));
+ const stageIds = createLazyMemo(() => new Set(stages().map((s) => s.id)));
- const labelById = createMemo(() => {
+ const labelById = createLazyMemo(() => {
const map = new Map<string, string>();
for (const stage of stages()) map.set(stage.id, stage.label);
return map;
@@ -297,7 +303,7 @@ export function useDealStages(): DealStages {
resolveStage,
stageLabel,
isLoading: () =>
- teamDefinitionsQuery.isLoading || teamCrmConfig.isLoading(),
+ teamDefinitionsQuery.isPending || teamCrmConfig.isLoading(),
isError: () =>
teamDefinitionsQuery.isError && teamDefinitionsQuery.data === undefined,
};
diff --git a/apps/web/src/features/email-thread/email-thread.test.tsx b/apps/web/src/features/email-thread/email-thread.test.tsx
new file mode 100644
index 0000000000..c8ce6f80ed
--- /dev/null
+++ b/apps/web/src/features/email-thread/email-thread.test.tsx
@@ -0,0 +1,117 @@
+import { cleanup, fireEvent, render, screen } from '@solidjs/testing-library';
+import { createSignal } from 'solid-js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { EmailComposeContextOptions } from '../email-compose/compose-adapter';
+import { createComposeContext } from '../email-compose/tests/capabilities';
+import { EmailThread } from './email-thread';
+import { createThreadContext, message, thread } from './tests/fixtures';
+import type { EmailThreadSurfaceProps } from './views/email-thread-surface';
+
+const mocks = vi.hoisted(() => ({
+ query: vi.fn(),
+ clearDraft: vi.fn(),
+ source: vi.fn(),
+ composeOptions: vi.fn<(options: EmailComposeContextOptions) => void>(),
+}));
+vi.mock('@queries/email/thread', () => ({ useThreadQuery: mocks.query }));
+vi.mock('@queries/email/draft-cache', () => ({
+ clearSavedDraftThreadCache: mocks.clearDraft,
+}));
+vi.mock('@components/app/GlobalAppState', () => ({
+ useGlobalNotificationSource: () => ({}),
+}));
+vi.mock('@notifications', () => ({
+ createEffectOnEntityTypeNotification: vi.fn(),
+}));
+vi.mock('@core/context/user', () => ({
+ useEmail: () => () => '[email protected]',
+ useUserContext: () => ({ isLoading: () => false }),
+}));
+vi.mock('@core/user', () => ({ useContacts: () => () => [] }));
+vi.mock('../email-compose/compose-adapter', () => ({
+ createEmailComposeContext: (options: EmailComposeContextOptions) => {
+ mocks.composeOptions(options);
+ return createComposeContext();
+ },
+}));
+vi.mock('../email-compose/compose-host-adapter', () => ({
+ createEmailComposeHost: () => ({}),
+}));
+vi.mock('../email-message/attachment-action-adapter', () => ({
+ createEmailAttachmentOpener: () => vi.fn(),
+}));
+vi.mock('../email-message/rendering-adapter', () => ({
+ createEmailRenderingContext: () => ({}),
+}));
+vi.mock('../email-message/sender-icon-adapter', () => ({
+ EmailSenderIcon: () => null,
+}));
+vi.mock('./thread-action-adapter', () => ({
+ createThreadActionAdapter: vi.fn(),
+}));
+vi.mock('./views/email-thread-surface', () => ({
+ EmailThreadSurface: (props: EmailThreadSurfaceProps) => {
+ const source = props.context.thread.source;
+ mocks.source(source);
+ return (
+ <div>
+ <span data-testid="body">
+ {source.thread()?.messages[0]?.body_text}
+ </span>
+ <button onClick={() => void source.fetchOlder()}>Older</button>
+ <button onClick={() => void source.refresh()}>Refresh</button>
+ </div>
+ );
+ },
+}));
+
+afterEach(() => {
+ cleanup();
+ vi.clearAllMocks();
+});
+
+describe('email thread query ownership', () => {
+ it('renders and observes the load gate source without starting another query', () => {
+ mocks.query.mockImplementation(() => {
+ throw new Error('Duplicate thread query');
+ });
+ const [snapshot, setSnapshot] = createSignal(
+ thread([message('first', { body_text: 'Cached body' })])
+ );
+ const [transport, setTransport] = createSignal<'graphql' | 'rest'>(
+ 'graphql'
+ );
+ const fetchOlder = vi.fn(async () => {});
+ const refresh = vi.fn(async () => {});
+ const source = createThreadContext({
+ thread: snapshot,
+ fetchOlder,
+ refresh,
+ }).source;
+ const view = render(() => (
+ <EmailThread
+ title="Subject"
+ threadId={source.id}
+ source={source}
+ threadTransport={transport}
+ />
+ ));
+ expect(screen.getByTestId('body').textContent).toBe('Cached body');
+ expect(mocks.source).toHaveBeenCalledWith(source);
+ expect(mocks.query).not.toHaveBeenCalled();
+ const options = mocks.composeOptions.mock.calls[0][0];
+ expect(options.threadTransport?.()).toBe('graphql');
+ setTransport('rest');
+ expect(options.threadTransport?.()).toBe('rest');
+ expect(mocks.query).not.toHaveBeenCalled();
+
+ setSnapshot(thread([message('first', { body_text: 'Updated body' })]));
+ expect(screen.getByTestId('body').textContent).toBe('Updated body');
+ fireEvent.click(screen.getByText('Older'));
+ fireEvent.click(screen.getByText('Refresh'));
+ expect(fetchOlder).toHaveBeenCalledOnce();
+ expect(refresh).toHaveBeenCalledOnce();
+ view.unmount();
+ expect(mocks.clearDraft).toHaveBeenCalledWith('thread');
+ });
+});
diff --git a/apps/web/src/features/email-thread/email-thread.tsx b/apps/web/src/features/email-thread/email-thread.tsx
index 6231c44c20..82c1b83425 100644
--- a/apps/web/src/features/email-thread/email-thread.tsx
+++ b/apps/web/src/features/email-thread/email-thread.tsx
@@ -5,8 +5,8 @@ import { isTouchDevice } from '@core/mobile/isTouchDevice';
import { useContacts } from '@core/user';
import { createEffectOnEntityTypeNotification } from '@notifications';
import { clearSavedDraftThreadCache } from '@queries/email/draft-cache';
-import { useThreadQuery } from '@queries/email/thread';
-import { createEffect, createMemo, onCleanup } from 'solid-js';
+import type { ThreadQueryTransport } from '@queries/email/thread';
+import { type Accessor, createEffect, createMemo, onCleanup } from 'solid-js';
import { createEmailComposeContext } from '../email-compose/compose-adapter';
import { createEmailComposeHost } from '../email-compose/compose-host-adapter';
import { convertContactInfoToEmailRecipient } from '../email-compose/core/recipient-conversion';
@@ -14,8 +14,10 @@ import { createEmailAttachmentOpener } from '../email-message/attachment-action-
import type { EmailMessage } from '../email-message/core/email-message';
import { createEmailRenderingContext } from '../email-message/rendering-adapter';
import { EmailSenderIcon } from '../email-message/sender-icon-adapter';
-import type { EmailThreadContext } from './context/email-thread-context';
-import { createEmailThreadSource } from './queries/thread-source';
+import type {
+ EmailThreadContext,
+ EmailThreadSource,
+} from './context/email-thread-context';
import { createThreadActionAdapter } from './thread-action-adapter';
import {
EmailThreadSurface,
@@ -25,19 +27,21 @@ import {
export type EmailThreadProps = Omit<
EmailThreadSurfaceProps,
'context' | 'emailRendering'
->;
+> & {
+ source: EmailThreadSource;
+ threadTransport: Accessor<ThreadQueryTransport>;
+};
/** App-facing composition. Import the surface or primitives for isolated tests. */
export function EmailThread(props: EmailThreadProps) {
- const query = useThreadQuery(props.threadId, () => ({
- enabled: !!props.threadId(),
- }));
- const source = createEmailThreadSource(props.threadId, query);
+ // The host's load gate already owns the live query. Reuse its source so
+ // mounting the body does not start a second disk read/network request.
+ const source = props.source;
const contacts = useContacts();
const viewerEmail = useEmail();
const user = useUserContext();
const compose = createEmailComposeContext({
- threadTransport: () => query.transport,
+ threadTransport: props.threadTransport,
});
const threadContext: EmailThreadContext = {
source,
diff --git a/apps/web/src/features/email-view/components/EmailDetailView.tsx b/apps/web/src/features/email-view/components/EmailDetailView.tsx
index cfdfef57ff..6d43096ef9 100644
--- a/apps/web/src/features/email-view/components/EmailDetailView.tsx
+++ b/apps/web/src/features/email-view/components/EmailDetailView.tsx
@@ -2,6 +2,7 @@ import { useListNavigationHotkeys } from '@app/components/entity-detail/use-list
import { ViewBreadcrumbs, ViewShell } from '@app/components/view-shell';
import { displaySubject } from '@app/features/email-compose/core/subject-text';
import type { EmailThreadHost } from '@app/features/email-thread/context/email-thread-context';
+import { createEmailThreadSource } from '@app/features/email-thread/queries/thread-source';
import { useBlockEntityCommands } from '@app/features/next-soup/actions';
import { createSearchParams, useRouteParams } from '@app/lib/split-router';
import { EmailThreadLoadGate } from '@block-email/component/EmailThreadLoadGate';
@@ -75,6 +76,7 @@ export function EmailDetailView(props: {
const threadQuery = useThreadQuery(threadId, () => ({
enabled: !!threadId(),
}));
+ const source = createEmailThreadSource(threadId, threadQuery);
const threadData = createMemo(
(previous: typeof threadQuery.data | undefined) =>
threadQuery.isSuccess || threadQuery.isError ? threadQuery.data : previous
@@ -206,6 +208,8 @@ export function EmailDetailView(props: {
<EmailThreadHostView
title={title()}
threadId={threadId}
+ source={source}
+ threadTransport={() => threadQuery.transport}
host={host}
sidePanelHeaderToggle={false}
shareOpen={shareOpen()}
diff --git a/apps/web/src/features/next-soup/actions/make-set-company-property-action.test.ts b/apps/web/src/features/next-soup/actions/make-set-company-property-action.test.ts
new file mode 100644
index 0000000000..0830ef763c
--- /dev/null
+++ b/apps/web/src/features/next-soup/actions/make-set-company-property-action.test.ts
@@ -0,0 +1,81 @@
+import type { CrmCompanyEntity } from '@entity/types/entity';
+import { SYSTEM_PROPERTY_IDS } from '@property/constants';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { makeSetCompanyPropertyAction } from './make-set-company-property-action';
+
+const mocks = vi.hoisted(() => ({
+ loading: true,
+ property: { propertyDefinitionId: 'custom-team-stage' },
+ open: vi.fn(),
+ defaults: vi.fn(),
+ stageProperty: vi.fn(),
+}));
+vi.mock('@app/features/property/editor/state/propertyEditor', () => ({
+ openPropertyEditor: mocks.open,
+}));
+vi.mock('@companies/crm/deal-stages', () => ({
+ useDealStages: () => ({
+ isLoading: () => mocks.loading,
+ stageProperty: mocks.stageProperty,
+ }),
+}));
+vi.mock('@entity/extractors-property', () => ({
+ buildCompanyDefaultProperties: mocks.defaults,
+}));
+
+const company: CrmCompanyEntity = {
+ type: 'crm_company',
+ id: 'company',
+ name: 'Company',
+ ownerId: 'owner',
+ teamId: 'team',
+ hidden: false,
+ domains: [],
+};
+
+beforeEach(() => {
+ mocks.loading = true;
+ vi.clearAllMocks();
+ mocks.stageProperty.mockReturnValue(mocks.property);
+ mocks.defaults.mockReturnValue([
+ { propertyDefinitionId: SYSTEM_PROPERTY_IDS.COMPANY_OWNER },
+ { propertyDefinitionId: SYSTEM_PROPERTY_IDS.REVENUE },
+ ]);
+});
+
+describe('company property actions with lazy stage metadata', () => {
+ it('does not open the editor with default stages while team definitions are pending', () => {
+ const action = makeSetCompanyPropertyAction();
+ expect(action.canExecute(company, 'stage')).toBe(false);
+ action.execute([company], 'stage');
+ expect(mocks.open).not.toHaveBeenCalled();
+ });
+
+ it.each([
+ ['owner', SYSTEM_PROPERTY_IDS.COMPANY_OWNER],
+ ['revenue', SYSTEM_PROPERTY_IDS.REVENUE],
+ ] as const)(
+ 'allows %s edits while stage metadata is pending',
+ (field, definitionId) => {
+ const action = makeSetCompanyPropertyAction();
+ expect(action.canExecute(company, field)).toBe(true);
+ action.execute([company], field);
+ expect(mocks.open).toHaveBeenCalledWith([company], 'direct', {
+ propertyDefinitionId: definitionId,
+ });
+ expect(mocks.stageProperty).not.toHaveBeenCalled();
+ }
+ );
+
+ it('uses the active team definition once it is ready', () => {
+ const action = makeSetCompanyPropertyAction();
+ mocks.loading = false;
+ expect(action.canExecute(company, 'stage')).toBe(true);
+ action.execute([company], 'stage');
+ expect(mocks.open).toHaveBeenCalledWith(
+ [company],
+ 'direct',
+ mocks.property
+ );
+ });
+});
diff --git a/apps/web/src/features/next-soup/actions/make-set-company-property-action.ts b/apps/web/src/features/next-soup/actions/make-set-company-property-action.ts
index 32b05bbe2f..ccf3244dc2 100644
--- a/apps/web/src/features/next-soup/actions/make-set-company-property-action.ts
+++ b/apps/web/src/features/next-soup/actions/make-set-company-property-action.ts
@@ -18,8 +18,9 @@ export type CompanyCrmField = 'stage' | 'owner' | 'revenue';
export const makeSetCompanyPropertyAction = () => {
const dealStages = useDealStages();
- const canExecute = (entity: EntityData): boolean =>
- entity.type === 'crm_company';
+ const canExecute = (entity: EntityData, field: CompanyCrmField): boolean =>
+ entity.type === 'crm_company' &&
+ (field !== 'stage' || !dealStages.isLoading());
const propertyFor = (field: CompanyCrmField): Property | undefined => {
// Stage resolves through the active deal-stage set (the team's own
@@ -35,6 +36,9 @@ export const makeSetCompanyPropertyAction = () => {
};
const execute = (entities: EntityData[], field: CompanyCrmField) => {
+ // Stages are lazy: don't open an editor against system defaults before
+ // the team's active definition has resolved.
+ if (field === 'stage' && dealStages.isLoading()) return;
const property = propertyFor(field);
if (property) openPropertyEditor(entities, 'direct', property);
};
diff --git a/apps/web/src/features/next-soup/actions/use-entity-action-hotkeys.ts b/apps/web/src/features/next-soup/actions/use-entity-action-hotkeys.ts
index 3ccc5b4da6..c0d44e3126 100644
--- a/apps/web/src/features/next-soup/actions/use-entity-action-hotkeys.ts
+++ b/apps/web/src/features/next-soup/actions/use-entity-action-hotkeys.ts
@@ -721,7 +721,12 @@ export const useEntityActionHotkeys = (
keyDownHandler: () => {
const entities = getEntitiesForAction();
if (entities.length === 0) return false;
- if (!entities.every(setCompanyPropertyAction.canExecute)) return false;
+ if (
+ !entities.every((entity) =>
+ setCompanyPropertyAction.canExecute(entity, field)
+ )
+ )
+ return false;
setCompanyPropertyAction.execute(entities, field);
return true;
},
@@ -730,7 +735,9 @@ export const useEntityActionHotkeys = (
const entities = getEntitiesForAction();
return (
entities.length > 0 &&
- entities.every(setCompanyPropertyAction.canExecute)
+ entities.every((entity) =>
+ setCompanyPropertyAction.canExecute(entity, field)
+ )
);
},
scopeId,
diff --git a/apps/web/src/features/soup/createSoupEntityActions.ts b/apps/web/src/features/soup/createSoupEntityActions.ts
index e1410456f5..73f5ac404b 100644
--- a/apps/web/src/features/soup/createSoupEntityActions.ts
+++ b/apps/web/src/features/soup/createSoupEntityActions.ts
@@ -473,24 +473,22 @@ export function createSoupEntityActions(): {
// selection, Hide / Unhide for a single company.
const crmItems: SoupEntityActionItem[] = [];
- if (canExecuteAll(setCompanyPropertyAction.canExecute)) {
- crmItems.push(
- {
- id: 'set-stage',
- label: 'Set stage',
- onClick: () => setCompanyPropertyAction.execute(entities, 'stage'),
- },
- {
- id: 'set-owner',
- label: 'Set owner',
- onClick: () => setCompanyPropertyAction.execute(entities, 'owner'),
- },
- {
- id: 'set-revenue',
- label: 'Set revenue',
- onClick: () => setCompanyPropertyAction.execute(entities, 'revenue'),
- }
- );
+ for (const [field, label] of [
+ ['stage', 'Set stage'],
+ ['owner', 'Set owner'],
+ ['revenue', 'Set revenue'],
+ ] as const) {
+ if (
+ !canExecuteAll((entity) =>
+ setCompanyPropertyAction.canExecute(entity, field)
+ )
+ )
+ continue;
+ crmItems.push({
+ id: `set-${field}`,
+ label,
+ onClick: () => setCompanyPropertyAction.execute(entities, field),
+ });
}
const singleEntity = entities.length === 1 ? entities[0] : undefined;
diff --git a/apps/web/src/lib/core/auth/logout.ts b/apps/web/src/lib/core/auth/logout.ts
index c5ef3b572d..58d4e5ea1c 100644
--- a/apps/web/src/lib/core/auth/logout.ts
+++ b/apps/web/src/lib/core/auth/logout.ts
@@ -8,6 +8,7 @@ import { queryClient } from '@queries/client';
import { emailKeys } from '@queries/email/keys';
import { propertiesKeys } from '@queries/properties/keys';
import { clearDocumentQueryCache } from '@queries/storage/document-cache';
+import { clearOfflineDocumentContexts } from '@queries/storage/documentLoad/offline-context-runtime';
import { authServiceClient } from '@service-auth/client';
import { raceTimeout } from '@solid-primitives/promise';
import { createCallback } from '@solid-primitives/rootless';
@@ -35,6 +36,7 @@ export async function clearLocalAuthSession() {
document.cookie =
'login=false; expires=Thu, 01 Jan 1970 00:00:00 UTC; max-age=0; path=/; SameSite=Lax';
syncLoginStorage(false);
+ const documentContextsCleared = clearOfflineDocumentContexts();
clearDocumentQueryCache(queryClient);
queryClient.setQueryData(authKeys.userInfo.queryKey, unauthenticatedUserInfo);
queryClient.removeQueries({ queryKey: emailKeys.links.queryKey });
@@ -42,7 +44,7 @@ export async function clearLocalAuthSession() {
// Queued mutations are user intent; never allow them to replay under a
// subsequent account sharing this anonymous device cache scope.
- await clearRegisteredCaches();
+ await Promise.all([documentContextsCleared, clearRegisteredCaches()]);
}
export function useLogout() {
diff --git a/apps/web/src/lib/core/block.ts b/apps/web/src/lib/core/block.ts
index d7cecaef55..2e77cb90a2 100644
--- a/apps/web/src/lib/core/block.ts
+++ b/apps/web/src/lib/core/block.ts
@@ -6,7 +6,7 @@ import type { IDocumentStorageServiceFile } from '@filesystem/file';
import type {
InitialSync,
LiveSyncSource,
- TimeoutError,
+ SyncError,
} from '@macro-inc/collaboration/collab/source';
import type { AccessLevel } from '@service-storage/generated/schemas/accessLevel';
import type { DocumentMetadata } from '@service-storage/generated/schemas/documentMetadata';
@@ -353,7 +353,7 @@ interface BlockComponentLoadData extends Record<BlockName, ObjectLike> {
md: DocumentBlockData &
DssFileData & {
syncSource: LiveSyncSource;
- doInitialSync: () => ResultAsync<InitialSync, TimeoutError>;
+ doInitialSync: () => ResultAsync<InitialSync, SyncError>;
};
code: DocumentBlockData;
project: ProjectBlockData;
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/ConnectApp.test.tsx b/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/ConnectApp.test.tsx
index fa42ebe1d9..590197c137 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/ConnectApp.test.tsx
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/ConnectApp.test.tsx
@@ -7,12 +7,28 @@ const mocks = vi.hoisted(() => ({
openAgentsPage: vi.fn(),
requestConnectApp: vi.fn(),
pipedreamSlugs: new Set<string>(),
- cursor: { isSuccess: true, isLoading: false, data: { registered: false } },
+ cursor: {
+ isSuccess: true,
+ isLoading: false,
+ get isPending(): boolean {
+ return this.isLoading;
+ },
+ data: { registered: false },
+ },
codex: {
isLoading: false,
+ get isPending(): boolean {
+ return this.isLoading;
+ },
data: { connected: false, environmentId: null as string | null },
},
- claude: { isLoading: false, data: { connected: false } },
+ claude: {
+ isLoading: false,
+ get isPending(): boolean {
+ return this.isLoading;
+ },
+ data: { connected: false },
+ },
}));
vi.mock('@app/features/agents-view/primitives/open-page', () => ({
openAgentsPage: mocks.openAgentsPage,
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/TagsMenu.test.tsx b/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/TagsMenu.test.tsx
new file mode 100644
index 0000000000..0423866e2c
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/TagsMenu.test.tsx
@@ -0,0 +1,86 @@
+import { cleanup, render, screen } from '@solidjs/testing-library';
+import {
+ QueryClient,
+ QueryClientProvider,
+ useQuery,
+} from '@tanstack/solid-query';
+import { createEditor } from 'lexical';
+import { type ParentProps, Suspense } from 'solid-js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createMenuOperations } from '../../shared/inlineMenu';
+import { TagsMenu } from './TagsMenu';
+
+const mocks = vi.hoisted(() => ({ team: vi.fn() }));
+vi.mock('@queries/team/teams', () => ({
+ useCurrentTeamQuery: () => mocks.team(),
+}));
+vi.mock('@queries/properties/tags', () => ({
+ useTagsQuery: () => ({ data: [] }),
+ useEnsureTagSetMutation: () => ({ isPending: false }),
+ invalidateTags: vi.fn(),
+}));
+vi.mock('@queries/properties/options', () => ({
+ useAddPropertyOptionMutation: () => ({ isPending: false }),
+}));
+vi.mock('./useMenuKeyboardNavigation', () => ({
+ useMenuKeyboardNavigation: vi.fn(),
+}));
+vi.mock('./InlineFollowupMenu', () => ({ InlineFollowupMenu: () => null }));
+vi.mock('@core/component/ScopedPortal', () => ({
+ ScopedPortal: (props: ParentProps) => props.children,
+}));
+vi.mock('../../directive/floatWithSelection', () => ({
+ floatWithSelection: vi.fn(),
+}));
+vi.mock('../../plugins', () => ({
+ CLOSE_INLINE_SEARCH_COMMAND: {},
+ REMOVE_INLINE_SEARCH_COMMAND: {},
+}));
+vi.mock('../../plugins/tags', () => ({ INSERT_TAG_MENTION_COMMAND: {} }));
+vi.mock('@property/tags/TagDot', () => ({ TagDot: () => null }));
+vi.mock('@ui', () => ({
+ Surface: (props: ParentProps) => <div>{props.children}</div>,
+}));
+
+const clients: QueryClient[] = [];
+afterEach(() => {
+ cleanup();
+ for (const client of clients.splice(0)) client.clear();
+});
+
+describe('closed inline tags menu', () => {
+ it.each([true, false])(
+ 'does not suspend its editor on missing team metadata (enabled=%s)',
+ (enabled) => {
+ const client = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ clients.push(client);
+ mocks.team.mockImplementation(() =>
+ useQuery(() => ({
+ queryKey: ['team-test'],
+ enabled,
+ queryFn: () => new Promise(() => {}),
+ }))
+ );
+ function Editor() {
+ const menu = createMenuOperations();
+ return (
+ <div data-testid="editor">
+ Cached body
+ <TagsMenu editor={createEditor()} menu={menu} />
+ </div>
+ );
+ }
+ render(() => (
+ <QueryClientProvider client={client}>
+ <Suspense fallback={<div data-testid="loading" />}>
+ <Editor />
+ </Suspense>
+ </QueryClientProvider>
+ ));
+ expect(screen.getByTestId('editor').textContent).toBe('Cached body');
+ expect(screen.queryByTestId('loading')).toBeNull();
+ }
+ );
+});
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/TagsMenu.tsx b/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/TagsMenu.tsx
index dbd3358f80..4c70bb745e 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/TagsMenu.tsx
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/TagsMenu.tsx
@@ -3,6 +3,7 @@ import clickOutside from '@core/directive/clickOutside';
import PlusIcon from '@phosphor/plus.svg';
import { TagDot } from '@property/tags/TagDot';
import { DEFAULT_TAG_COLOR, type TAG_COLORS } from '@property/tags/tagColors';
+import { queryReadyGate } from '@queries/gate';
import { useAddPropertyOptionMutation } from '@queries/properties/options';
import {
invalidateTags,
@@ -176,7 +177,10 @@ export function TagsMenu(props: {
createLabel().length >= 2 && !exactTagMatchExists();
const createRowIndex = () => items().length;
const itemCount = () => items().length + (showCreateRow() ? 1 : 0);
- const teamName = () => currentTeamQuery.data?.team.name?.trim() || 'Team';
+ const teamName = () =>
+ (queryReadyGate(currentTeamQuery) &&
+ currentTeamQuery.data?.team.name?.trim()) ||
+ 'Team';
const scopeOptions = createMemo<{ scope: TagScope; label: string }[]>(() => [
{ scope: 'team', label: `Shared with ${teamName()}` },
{ scope: 'user', label: 'Personal' },
diff --git a/apps/web/src/lib/queries/auth/user-info-cache.ts b/apps/web/src/lib/queries/auth/user-info-cache.ts
new file mode 100644
index 0000000000..0ff3bd25dd
--- /dev/null
+++ b/apps/web/src/lib/queries/auth/user-info-cache.ts
@@ -0,0 +1,12 @@
+/** A cached signed-out result is a logout marker, not identity for a later login. */
+export function hasCachedUserIdentity(data: unknown): boolean {
+ return (
+ typeof data === 'object' &&
+ data !== null &&
+ 'authenticated' in data &&
+ data.authenticated === true &&
+ 'id' in data &&
+ typeof data.id === 'string' &&
+ data.id.length > 0
+ );
+}
diff --git a/apps/web/src/lib/queries/auth/user-info.ts b/apps/web/src/lib/queries/auth/user-info.ts
index 3ace7462a6..63ad0ad772 100644
--- a/apps/web/src/lib/queries/auth/user-info.ts
+++ b/apps/web/src/lib/queries/auth/user-info.ts
@@ -4,8 +4,9 @@ import { hasLoginCookie } from '@core/util/cookies';
import { catchToResult, type ResultType, throwOnErr } from '@core/util/result';
import { authServiceClient } from '@service-auth/client';
import { useQuery } from '@tanstack/solid-query';
-import { queryClient } from '../client';
+import { queryClient, queryPersistence } from '../client';
import { authKeys } from './keys';
+import { hasCachedUserIdentity } from './user-info-cache';
export { authKeys } from './keys';
@@ -64,21 +65,32 @@ export function invalidateAllAfterLogin() {
return invalidated;
}
-/** Ensure user info is in the query cache. Fetches if not present. */
+/** Ensure signed-in identity is cached; signed-out markers require a fresh auth fetch. */
export async function prefetchUserInfo() {
// Skip prefetch if user doesn't appear to be authenticated.
// This prevents unnecessary auth requests during unauthenticated flows.
if (!hasLoginCookie()) return;
+ // IDB restoration is independent of an in-flight auth fetch. Await it first
+ // so an offline native launch can use restored identity without that fetch.
+ await queryPersistence.restoreQuery(authKeys.userInfo.queryKey);
+ if (!hasLoginCookie()) return;
+ if (
+ hasCachedUserIdentity(queryClient.getQueryData(authKeys.userInfo.queryKey))
+ )
+ return;
+
await catchToResult(
async () =>
- await queryClient.ensureQueryData({
+ await queryClient.fetchQuery({
queryKey: authKeys.userInfo.queryKey,
queryFn: async () =>
await throwOnErr(
async () => await authServiceClient.getLegacyUserPermissions()
),
networkMode: 'always',
+ // Even a fresh in-memory logout stub is not the new login's identity.
+ staleTime: 0,
})
);
}
diff --git a/apps/web/src/lib/queries/client.ts b/apps/web/src/lib/queries/client.ts
index 6a004c641d..5cd72ae6c4 100644
--- a/apps/web/src/lib/queries/client.ts
+++ b/apps/web/src/lib/queries/client.ts
@@ -44,7 +44,7 @@ if (isPlatform('ios')) {
const buster = import.meta.env.__APP_VERSION__ ?? 'dev';
-setupQueryPersistence({
+export const queryPersistence = setupQueryPersistence({
queryClient,
scopes: createQueryPersistenceScopes(buster),
});
diff --git a/apps/web/src/lib/queries/email/link-selection.test.tsx b/apps/web/src/lib/queries/email/link-selection.test.tsx
new file mode 100644
index 0000000000..f3695adaa0
--- /dev/null
+++ b/apps/web/src/lib/queries/email/link-selection.test.tsx
@@ -0,0 +1,106 @@
+import type { Link, ListLinksResponse } from '@service-email/generated/schemas';
+import { cleanup, render, screen, waitFor } from '@solidjs/testing-library';
+import { QueryClient, QueryClientProvider } from '@tanstack/solid-query';
+import { ok } from 'neverthrow';
+import { createSignal, Suspense } from 'solid-js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+ useEmailSignature,
+ useNonPrimaryEmailLinkIdHeader,
+ usePrimaryEmailLinkId,
+} from './link';
+
+const mocks = vi.hoisted(() => ({ getLinks: vi.fn() }));
+vi.mock('@service-email/client', () => ({
+ emailClient: { getLinks: mocks.getLinks },
+}));
+vi.mock('@queries/calendar/sync', () => ({ invalidateCalendarViews: vi.fn() }));
+vi.mock('@queries/auth/user-info', () => ({ invalidateUserInfo: vi.fn() }));
+vi.mock('@queries/soup/normalized-cache', () => ({
+ invalidateAllSoup: vi.fn(),
+}));
+vi.mock('@core/context/user', () => ({ useUserId: () => () => 'macro|self' }));
+vi.mock('@queries/client', () => ({ queryClient: {} }));
+
+const link = (id: string, owner: string, primary: boolean): Link => ({
+ id,
+ macro_id: owner,
+ is_primary: primary,
+ email_address: `${id}@example.com`,
+ calendar_disabled: false,
+ created_at: '2026-01-01T00:00:00Z',
+ updated_at: '2026-01-01T00:00:00Z',
+ fusionauth_user_id: owner,
+ has_calendar_data: false,
+ is_sync_active: true,
+ needs_calendar_permission: false,
+ needs_reauth: false,
+ provider: 'GMAIL',
+ sync_status: 'UP_TO_DATE',
+ settings: { signature: `<p>${id} signature</p>` },
+});
+
+const clients: QueryClient[] = [];
+afterEach(() => {
+ cleanup();
+ for (const client of clients.splice(0)) client.clear();
+ vi.clearAllMocks();
+});
+
+describe('non-suspending inbox metadata', () => {
+ it('does not hold a cached body for inbox metadata or silently default an explicit target inbox', async () => {
+ const response = Promise.withResolvers<ListLinksResponse>();
+ mocks.getLinks.mockImplementation(async () => ok(await response.promise));
+ const client = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ clients.push(client);
+ const [target, setTarget] = createSignal('shared');
+ function View() {
+ const primary = usePrimaryEmailLinkId();
+ const header = useNonPrimaryEmailLinkIdHeader();
+ const signature = useEmailSignature(target);
+ return (
+ <div data-testid="body">
+ <span data-testid="primary">{primary() ?? 'unknown'}</span>
+ <span data-testid="header">{header(target()) ?? 'default'}</span>
+ <span data-testid="signature">{signature() ?? 'unknown'}</span>
+ </div>
+ );
+ }
+ render(() => (
+ <QueryClientProvider client={client}>
+ <Suspense fallback={<div data-testid="loading" />}>
+ <View />
+ </Suspense>
+ </QueryClientProvider>
+ ));
+ expect(screen.getByTestId('body')).toBeTruthy();
+ expect(screen.queryByTestId('loading')).toBeNull();
+ expect(screen.getByTestId('primary').textContent).toBe('unknown');
+ expect(screen.getByTestId('header').textContent).toBe('shared');
+ expect(screen.getByTestId('signature').textContent).toBe('unknown');
+ setTarget('self-primary');
+ expect(screen.getByTestId('header').textContent).toBe('self-primary');
+
+ response.resolve({
+ links: [
+ link('delegated-primary', 'macro|other', true),
+ link('self-primary', 'macro|self', true),
+ link('shared', 'macro|self', false),
+ ],
+ });
+ await waitFor(() =>
+ expect(screen.getByTestId('primary').textContent).toBe('self-primary')
+ );
+ expect(screen.getByTestId('header').textContent).toBe('default');
+ expect(screen.getByTestId('signature').textContent).toBe(
+ '<p>self-primary signature</p>'
+ );
+ setTarget('shared');
+ expect(screen.getByTestId('header').textContent).toBe('shared');
+ expect(screen.getByTestId('signature').textContent).toBe(
+ '<p>shared signature</p>'
+ );
+ });
+});
diff --git a/apps/web/src/lib/queries/email/link.ts b/apps/web/src/lib/queries/email/link.ts
index 3239c640b3..a25bb02504 100644
--- a/apps/web/src/lib/queries/email/link.ts
+++ b/apps/web/src/lib/queries/email/link.ts
@@ -8,6 +8,7 @@ import { emailClient } from '@service-email/client';
import type { ListLinksResponse } from '@service-email/generated/schemas';
import { useMutation, useQuery } from '@tanstack/solid-query';
import { type Accessor, createMemo } from 'solid-js';
+import { queryReadyGate } from '../gate';
import { type MutationCallbacks, withCallbacks } from '../utils';
import { emailKeys } from './keys';
@@ -58,8 +59,8 @@ export function usePrimaryEmailLinkId() {
const userId = useUserId();
return createMemo(() => {
const uid = userId();
- if (!uid) return undefined;
- return linksQuery.data?.links.find(
+ if (!uid || !queryReadyGate(linksQuery)) return undefined;
+ return linksQuery.data.links.find(
(link) => link.is_primary && link.macro_id === uid
)?.id;
});
@@ -77,9 +78,9 @@ export function useEmailSignature(
const linksQuery = useEmailLinksQuery();
return createMemo(() => {
const id = linkId();
- if (!id) return undefined;
+ if (!id || !queryReadyGate(linksQuery)) return undefined;
return (
- linksQuery.data?.links.find((link) => link.id === id)?.settings
+ linksQuery.data.links.find((link) => link.id === id)?.settings
.signature ?? undefined
);
});
diff --git a/apps/web/src/lib/queries/gate.test.tsx b/apps/web/src/lib/queries/gate.test.tsx
new file mode 100644
index 0000000000..8adb98b56c
--- /dev/null
+++ b/apps/web/src/lib/queries/gate.test.tsx
@@ -0,0 +1,109 @@
+import { cleanup, render, screen, waitFor } from '@solidjs/testing-library';
+import {
+ onlineManager,
+ QueryClient,
+ QueryClientProvider,
+ type UseQueryResult,
+ useQuery,
+} from '@tanstack/solid-query';
+import { Suspense } from 'solid-js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { queryReadyGate } from './gate';
+
+const clients: QueryClient[] = [];
+afterEach(() => {
+ cleanup();
+ for (const client of clients.splice(0)) client.clear();
+ onlineManager.setOnline(true);
+});
+
+function mount(options: {
+ enabled?: boolean;
+ initialData?: string;
+ queryFn?: () => Promise<string>;
+}) {
+ const client = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ clients.push(client);
+ const request = options.queryFn ?? vi.fn(() => new Promise<string>(() => {}));
+ let query: UseQueryResult<string> | undefined;
+ function View() {
+ query = useQuery(() => ({
+ queryKey: ['gate-test'],
+ queryFn: request,
+ enabled: options.enabled,
+ initialData: options.initialData,
+ }));
+ const result = query;
+ return (
+ <div data-testid="content">
+ {queryReadyGate(result) ? result.data : 'pending'}
+ </div>
+ );
+ }
+ render(() => (
+ <QueryClientProvider client={client}>
+ <Suspense fallback={<div data-testid="suspended" />}>
+ <View />
+ </Suspense>
+ </QueryClientProvider>
+ ));
+ return { client, request, query: () => query! };
+}
+
+function expectContent(text: string) {
+ expect(screen.queryByTestId('suspended')).toBeNull();
+ expect(screen.getByTestId('content').textContent).toBe(text);
+}
+
+describe('queryReadyGate', () => {
+ it('does not suspend for an initially disabled query', () => {
+ const h = mount({ enabled: false });
+ expect(h.query().isPending).toBe(true);
+ expect(h.query().isLoading).toBe(false);
+ expectContent('pending');
+ expect(h.request).not.toHaveBeenCalled();
+ });
+
+ it('does not suspend for an offline/paused initial query', () => {
+ onlineManager.setOnline(false);
+ const h = mount({});
+ expect(h.query().fetchStatus).toBe('paused');
+ expect(h.query().isLoading).toBe(false);
+ expectContent('pending');
+ expect(h.request).not.toHaveBeenCalled();
+ });
+
+ it('renders immediately while loading, then updates when data arrives', async () => {
+ const response = Promise.withResolvers<string>();
+ mount({ queryFn: () => response.promise });
+ expectContent('pending');
+ response.resolve('loaded');
+ await waitFor(() => expectContent('loaded'));
+ });
+
+ it('keeps cached data visible during background refetch and after refetch failure', async () => {
+ const response = Promise.withResolvers<string>();
+ const h = mount({ initialData: 'cached', queryFn: () => response.promise });
+ expectContent('cached');
+ response.reject(new Error('Offline'));
+ await waitFor(() => expect(h.query().isError).toBe(true));
+ expectContent('cached');
+ });
+
+ it('returns no data after an initial failure without suspending the caller', async () => {
+ const h = mount({
+ queryFn: async () => {
+ throw new Error('Offline');
+ },
+ });
+ await waitFor(() => expect(h.query().isError).toBe(true));
+ expectContent('pending');
+ });
+
+ it('recognizes falsy cached values as available', () => {
+ mount({ enabled: false, initialData: '' });
+ expectContent('');
+ });
+});
diff --git a/apps/web/src/lib/queries/gate.ts b/apps/web/src/lib/queries/gate.ts
index 925cb81c4d..54957b8878 100644
--- a/apps/web/src/lib/queries/gate.ts
+++ b/apps/web/src/lib/queries/gate.ts
@@ -8,5 +8,7 @@ export function queryReadyGate<T>(
): query is
| (UseQueryResult<T, never> & { data: T })
| (UseInfiniteQueryResult<T, never> & { data: T }) {
- return !query.isLoading && query.data !== undefined;
+ // Disabled and paused queries are pending without being loading. Reading
+ // their data still suspends, so check the broader initial-pending state.
+ return !query.isPending && query.data !== undefined;
}
diff --git a/apps/web/src/lib/queries/persistence-scopes.ts b/apps/web/src/lib/queries/persistence-scopes.ts
index 0edcb431f8..3b3285f66a 100644
--- a/apps/web/src/lib/queries/persistence-scopes.ts
+++ b/apps/web/src/lib/queries/persistence-scopes.ts
@@ -2,6 +2,7 @@ import { isNativeMobilePlatform } from '@core/mobile/isNativeMobilePlatform';
import { hasLoginCookie } from '@core/util/cookies';
import { partialMatchKey, type QueryKey } from '@tanstack/query-core';
import { authKeys } from './auth/keys';
+import { hasCachedUserIdentity } from './auth/user-info-cache';
import { channelKeys } from './channel/keys';
import { createPersistenceKey, type PersistScope } from './persistence';
import { createPerQueryIDBStore } from './persistence/per-query-idb';
@@ -60,6 +61,9 @@ export function createQueryPersistenceScopes(
shouldPersist: (queryKey: QueryKey) =>
partialMatchKey(queryKey, authKeys.userInfo.queryKey),
shouldRestore: hasLoginCookie,
+ // Keep persisting logout to supersede the old identity, but never
+ // hydrate that marker into a new login (which would clear its cookie).
+ shouldRestoreData: hasCachedUserIdentity,
} satisfies PersistScope,
]
: []),
diff --git a/apps/web/src/lib/queries/persistence.test.ts b/apps/web/src/lib/queries/persistence.test.ts
index 531c795a84..5c2f523483 100644
--- a/apps/web/src/lib/queries/persistence.test.ts
+++ b/apps/web/src/lib/queries/persistence.test.ts
@@ -17,6 +17,7 @@ import {
vi.mock('@core/mobile/isNativeMobilePlatform', () => ({
isNativeMobilePlatform: () => true,
}));
+vi.mock('@core/util/cookies', () => ({ hasLoginCookie: () => true }));
function createMockStore(): PerQueryPersistence & {
entries: Map<string, PersistedQueryEntry>;
@@ -314,6 +315,112 @@ describe('setupQueryPersistence', () => {
expect(store.remove).not.toHaveBeenCalled();
});
+ it.each([
+ { id: '', authenticated: false },
+ { id: 'viewer', authenticated: false },
+ { id: '', authenticated: true },
+ { authenticated: true },
+ { id: 42, authenticated: true },
+ null,
+ ])(
+ 'does not hydrate a non-identity native user-info record: %j',
+ async (data) => {
+ const queryClient = new QueryClient();
+ const store = createMockStore();
+ const queryKey = authKeys.userInfo.queryKey;
+ const queryHash = JSON.stringify(queryKey);
+ const scope = createQueryPersistenceScopes('test').find((scope) =>
+ scope.shouldPersist(queryKey)
+ )!;
+ store.entries.set(queryHash, {
+ queryHash,
+ queryKey,
+ data,
+ dataUpdatedAt: Date.now(),
+ persistedAt: Date.now(),
+ buster: 'test',
+ });
+ const persistence = setupQueryPersistence({
+ queryClient,
+ scopes: [{ ...scope, store }],
+ });
+ await persistence.restoreQuery(queryKey);
+ expect(queryClient.getQueryData(queryKey)).toBeUndefined();
+ expect(store.remove).toHaveBeenCalledWith(queryHash);
+ expect(store.set).not.toHaveBeenCalled();
+ persistence.dispose();
+ queryClient.clear();
+ }
+ );
+
+ it('persists logout over the previous identity but treats that marker as a cache miss on restart', async () => {
+ const store = createMockStore();
+ const queryKey = authKeys.userInfo.queryKey;
+ const queryHash = JSON.stringify(queryKey);
+ const scope = {
+ ...createQueryPersistenceScopes('test').find((scope) =>
+ scope.shouldPersist(queryKey)
+ )!,
+ store,
+ };
+ const firstClient = new QueryClient();
+ const first = setupQueryPersistence({
+ queryClient: firstClient,
+ scopes: [scope],
+ });
+ firstClient.setQueryData(queryKey, {
+ id: 'old-viewer',
+ authenticated: true,
+ });
+ firstClient.setQueryData(queryKey, { id: '', authenticated: false });
+ expect(store.entries.get(queryHash)?.data).toEqual({
+ id: '',
+ authenticated: false,
+ });
+ first.dispose();
+ firstClient.clear();
+ const queryClient = new QueryClient();
+ const restarted = setupQueryPersistence({ queryClient, scopes: [scope] });
+ await restarted.restoreQuery(queryKey);
+ expect(queryClient.getQueryData(queryKey)).toBeUndefined();
+ expect(store.entries.has(queryHash)).toBe(false);
+ restarted.dispose();
+ queryClient.clear();
+ });
+
+ it('does not remove a new identity when an old logout marker finishes restoring', async () => {
+ const queryClient = new QueryClient();
+ const store = createMockStore();
+ const read = Promise.withResolvers<PersistedQueryEntry | undefined>();
+ store.get.mockReturnValue(read.promise);
+ const queryKey = authKeys.userInfo.queryKey;
+ const queryHash = JSON.stringify(queryKey);
+ const scope = createQueryPersistenceScopes('test').find((scope) =>
+ scope.shouldPersist(queryKey)
+ )!;
+ const persistence = setupQueryPersistence({
+ queryClient,
+ scopes: [{ ...scope, store }],
+ });
+ const restored = persistence.restoreQuery(queryKey);
+ const identity = { id: 'new-viewer', authenticated: true };
+ queryClient.setQueryData(queryKey, identity);
+ read.resolve({
+ queryHash,
+ queryKey,
+ data: { id: '', authenticated: false },
+ dataUpdatedAt: Date.now(),
+ persistedAt: Date.now(),
+ buster: 'test',
+ });
+ await restored;
+ expect(queryClient.getQueryData(queryKey)).toEqual(identity);
+ expect(store.entries.get(queryHash)?.data).toEqual(identity);
+ expect(store.remove).not.toHaveBeenCalled();
+ persistence.dispose();
+ queryClient.clear();
+ });
+
it('configures only native user-info persistence without an expiry', () => {
const scopes = createQueryPersistenceScopes('test');
const userInfoScope = scopes.find((scope) =>
@@ -362,7 +469,7 @@ describe('setupQueryPersistence', () => {
const store = createMockStore();
const scope = createScope(['channel'], store);
- const unsubscribe = setupQueryPersistence({
+ const persistence = setupQueryPersistence({
queryClient,
scopes: [scope],
});
@@ -370,12 +477,125 @@ describe('setupQueryPersistence', () => {
queryClient.setQueryData(['channel', 'a'], { value: 1 });
expect(store.set).toHaveBeenCalledTimes(1);
- unsubscribe();
+ persistence.dispose();
queryClient.setQueryData(['channel', 'b'], { value: 2 });
expect(store.set).toHaveBeenCalledTimes(1);
});
+ it('shares an awaitable restore without starting or waiting for a network fetch', async () => {
+ const queryClient = new QueryClient();
+ const store = createMockStore();
+ const read = Promise.withResolvers<PersistedQueryEntry | undefined>();
+ store.get.mockReturnValue(read.promise);
+ const persistence = setupQueryPersistence({
+ queryClient,
+ scopes: [createScope(['identity'], store)],
+ });
+ const queryKey = ['identity', 'user'];
+ const first = persistence.restoreQuery(queryKey);
+ const second = persistence.restoreQuery(queryKey);
+ expect(first).toBe(second);
+ expect(queryClient.getQueryState(queryKey)?.fetchStatus).toBe('idle');
+ void queryClient.prefetchQuery({
+ queryKey,
+ queryFn: () => new Promise(() => {}),
+ });
+ read.resolve({
+ queryHash: JSON.stringify(queryKey),
+ queryKey,
+ data: { id: 'viewer' },
+ dataUpdatedAt: Date.now(),
+ persistedAt: Date.now(),
+ buster: 'test',
+ });
+ await first;
+ expect(store.get).toHaveBeenCalledOnce();
+ expect(queryClient.getQueryData(queryKey)).toEqual({ id: 'viewer' });
+ expect(queryClient.getQueryState(queryKey)?.fetchStatus).toBe('fetching');
+ persistence.dispose();
+ queryClient.clear();
+ });
+
+ it.each([
+ 'removed',
+ 'recreated',
+ 'disposed',
+ 'logged-out',
+ 'denied',
+ ] as const)(
+ 'fences a pending restore when the query is %s',
+ async (change) => {
+ const queryClient = new QueryClient();
+ const store = createMockStore();
+ const read = Promise.withResolvers<PersistedQueryEntry | undefined>();
+ store.get
+ .mockReturnValueOnce(read.promise)
+ .mockImplementation(() => new Promise(() => {}));
+ let allowed = true;
+ const persistence = setupQueryPersistence({
+ queryClient,
+ scopes: [
+ createScope(['identity'], store, { shouldRestore: () => allowed }),
+ ],
+ });
+ const queryKey = ['identity', 'user'];
+ const pending = persistence.restoreQuery(queryKey);
+ if (change === 'removed' || change === 'recreated')
+ queryClient.removeQueries({ queryKey });
+ if (change === 'recreated')
+ queryClient.getQueryCache().build(queryClient, { queryKey });
+ if (change === 'disposed') persistence.dispose();
+ if (change === 'logged-out')
+ queryClient.setQueryData(queryKey, { authenticated: false });
+ if (change === 'denied') allowed = false;
+ read.resolve({
+ queryHash: JSON.stringify(queryKey),
+ queryKey,
+ data: { id: 'old-viewer' },
+ dataUpdatedAt: Date.now(),
+ persistedAt: Date.now(),
+ buster: 'test',
+ });
+ await pending;
+ expect(queryClient.getQueryData(queryKey)).toEqual(
+ change === 'logged-out' ? { authenticated: false } : undefined
+ );
+ expect(store.set).not.toHaveBeenCalledWith(
+ expect.objectContaining({ data: { id: 'old-viewer' } })
+ );
+ persistence.dispose();
+ queryClient.clear();
+ }
+ );
+
+ it('does not remove a newer persisted value when an old read has the wrong buster', async () => {
+ const queryClient = new QueryClient();
+ const store = createMockStore();
+ const read = Promise.withResolvers<PersistedQueryEntry | undefined>();
+ store.get.mockReturnValue(read.promise);
+ const persistence = setupQueryPersistence({
+ queryClient,
+ scopes: [createScope(['identity'], store)],
+ });
+ const queryKey = ['identity', 'user'];
+ const pending = persistence.restoreQuery(queryKey);
+ queryClient.setQueryData(queryKey, { id: 'new-viewer' });
+ read.resolve({
+ queryHash: JSON.stringify(queryKey),
+ queryKey,
+ data: { id: 'old-viewer' },
+ dataUpdatedAt: 1,
+ persistedAt: 1,
+ buster: 'old-buster',
+ });
+ await pending;
+ expect(queryClient.getQueryData(queryKey)).toEqual({ id: 'new-viewer' });
+ expect(store.remove).not.toHaveBeenCalled();
+ persistence.dispose();
+ queryClient.clear();
+ });
+
it('removes entry from store on query removal', () => {
const queryClient = new QueryClient();
const store = createMockStore();
diff --git a/apps/web/src/lib/queries/persistence.ts b/apps/web/src/lib/queries/persistence.ts
index 114439bdef..fbfc1d7f8b 100644
--- a/apps/web/src/lib/queries/persistence.ts
+++ b/apps/web/src/lib/queries/persistence.ts
@@ -2,11 +2,7 @@ import {
type ParsedDuration,
parsedDurationToMilliseconds,
} from '@core/util/dateSearch/dateParser';
-import type {
- Query,
- QueryCacheNotifyEvent,
- QueryKey,
-} from '@tanstack/query-core';
+import type { Query, QueryClient, QueryKey } from '@tanstack/query-core';
import type {
PerQueryPersistence,
PersistedQueryEntry,
@@ -29,20 +25,14 @@ export type PersistScope = Readonly<{
buster: string;
shouldPersist: (queryKey: QueryKey) => boolean;
shouldRestore?: (queryKey: QueryKey) => boolean;
+ /** Reject persisted values before publishing them to query observers. */
+ shouldRestoreData?: (data: unknown) => boolean;
}>;
-type QueryClientLike = {
- getQueryCache: () => {
- subscribe: (listener: (event: QueryCacheNotifyEvent) => void) => () => void;
- };
- getQueryState: (
- queryKey: QueryKey
- ) => { status: string; data: unknown; dataUpdatedAt: number } | undefined;
- setQueryData: (
- queryKey: QueryKey,
- data: unknown,
- options?: { updatedAt?: number }
- ) => void;
+export type QueryPersistence = {
+ /** Restore this query without starting or waiting for its network request. */
+ restoreQuery: (queryKey: QueryKey) => Promise<void>;
+ dispose: () => void;
};
/**
@@ -69,14 +59,15 @@ function validatePersistedEntry(
* a fresh fetch resolves before the IDB read completes.
*/
async function handleRestore(
- queryClient: QueryClientLike,
+ queryClient: QueryClient,
scope: PersistScope,
- query: Query
+ query: Query,
+ isCurrent: () => boolean
): Promise<void> {
if (scope.shouldRestore && !scope.shouldRestore(query.queryKey)) return;
- const state = queryClient.getQueryState(query.queryKey);
- if (state && state.status === 'success') return;
+ const state = query.state;
+ if (state.data !== undefined) return;
let entry: PersistedQueryEntry | undefined;
try {
@@ -86,19 +77,27 @@ async function handleRestore(
return;
}
- if (!entry) return;
+ // Removal/recreation, disposal, or a fresh update (including logout) fences
+ // an older IDB read even when the replacement query is pending or errored.
+ if (
+ !entry ||
+ !isCurrent() ||
+ query.state.dataUpdateCount !== state.dataUpdateCount ||
+ (scope.shouldRestore && !scope.shouldRestore(query.queryKey))
+ )
+ return;
const maxAgeMs = scope.maxAge
? parsedDurationToMilliseconds(scope.maxAge)
: undefined;
- if (validatePersistedEntry(entry, scope.buster, maxAgeMs) !== 'valid') {
+ if (
+ validatePersistedEntry(entry, scope.buster, maxAgeMs) !== 'valid' ||
+ (scope.shouldRestoreData && !scope.shouldRestoreData(entry.data))
+ ) {
scope.store.remove(query.queryHash);
return;
}
- const current = queryClient.getQueryState(query.queryKey);
- if (current && current.status === 'success') return;
-
queryClient.setQueryData(query.queryKey, entry.data, {
updatedAt: entry.dataUpdatedAt,
});
@@ -128,19 +127,45 @@ function handleUpdate(scope: PersistScope, query: Query): void {
* - On 'updated': writes the query's successful data to IDB.
* - On 'removed': deletes the query's entry from IDB.
*
- * Returns an unsubscribe function to stop listening.
+ * Restoration is shared with explicit callers; it never waits for the network.
+ * Dispose stops listening and fences unfinished restores.
*/
export function setupQueryPersistence(
params: Readonly<{
- queryClient: QueryClientLike;
+ queryClient: QueryClient;
scopes: readonly PersistScope[];
}>
-): () => void {
+): QueryPersistence {
const { queryClient, scopes } = params;
+ const restores = new WeakMap<Query, Promise<void>>();
+ let disposed = false;
const findScope = (queryKey: QueryKey) =>
scopes.find((s) => s.shouldPersist(queryKey));
+ async function restoreFromStore(query: Query, scope: PersistScope) {
+ try {
+ await handleRestore(
+ queryClient,
+ scope,
+ query,
+ () =>
+ !disposed &&
+ queryClient.getQueryCache().get(query.queryHash) === query
+ );
+ } catch {
+ console.error('[query] IDB restore failed');
+ }
+ }
+
+ const restore = (query: Query, scope: PersistScope): Promise<void> => {
+ const existing = restores.get(query);
+ if (existing) return existing;
+ const pending = restoreFromStore(query, scope);
+ restores.set(query, pending);
+ return pending;
+ };
+
const flushAll = () => {
for (const scope of scopes) {
void scope.store.flush();
@@ -161,9 +186,7 @@ export function setupQueryPersistence(
if (!scope) return;
if (type === 'added') {
- handleRestore(queryClient, scope, query).catch((err) => {
- console.error('[query] IDB restore failed', err);
- });
+ void restore(query, scope);
} else if (type === 'updated') {
handleUpdate(scope, query);
} else {
@@ -171,8 +194,21 @@ export function setupQueryPersistence(
}
});
- return () => {
- cacheUnsubscribe();
- document.removeEventListener('visibilitychange', onVisibilityChange);
+ return {
+ restoreQuery(queryKey) {
+ const scope = findScope(queryKey);
+ if (disposed || !scope) return Promise.resolve();
+ // Building a missing query emits `added`, starting the same restore that
+ // an observer would start, without issuing a request or needing a queryFn.
+ const query = queryClient
+ .getQueryCache()
+ .build(queryClient, { queryKey });
+ return restore(query, scope);
+ },
+ dispose() {
+ disposed = true;
+ cacheUnsubscribe();
+ document.removeEventListener('visibilitychange', onVisibilityChange);
+ },
};
}
diff --git a/apps/web/src/lib/queries/persistence/per-query-idb.test.ts b/apps/web/src/lib/queries/persistence/per-query-idb.test.ts
new file mode 100644
index 0000000000..faf2879c83
--- /dev/null
+++ b/apps/web/src/lib/queries/persistence/per-query-idb.test.ts
@@ -0,0 +1,87 @@
+import 'fake-indexeddb/auto';
+import { IDBObjectStore } from 'fake-indexeddb';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+ createPerQueryIDBStore,
+ type PersistedQueryEntry,
+} from './per-query-idb';
+
+const entry = (id: string): PersistedQueryEntry => ({
+ queryHash: id,
+ queryKey: [id],
+ data: id,
+ dataUpdatedAt: 1,
+ persistedAt: 1,
+ buster: 'test',
+});
+const store = () =>
+ createPerQueryIDBStore({
+ dbName: `query-clear-test-${crypto.randomUUID()}`,
+ debounceMs: 60_000,
+ });
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('clearable query persistence', () => {
+ it('fences pending puts and deletes', async () => {
+ const db = store();
+ db.set(entry('old'));
+ await db.flush();
+ db.set(entry('pending'));
+ db.remove('old');
+ await db.clear();
+ await db.flush();
+ expect(await db.get('old')).toBeUndefined();
+ expect(await db.get('pending')).toBeUndefined();
+ });
+
+ it('orders clear after old writes and before new-session writes', async () => {
+ const db = store();
+ db.set(entry('old'));
+ const flushing = db.flush();
+ const clearing = db.clear();
+ db.set(entry('new'));
+ const newWrite = db.flush();
+ await Promise.all([flushing, clearing, newWrite]);
+ expect(await db.get('old')).toBeUndefined();
+ expect(await db.get('new')).toEqual(entry('new'));
+ await db.clear();
+ });
+
+ it('waits for an already started transaction before clearing', async () => {
+ const db = store();
+ await db.clear();
+ const started = Promise.withResolvers<void>();
+ const put = IDBObjectStore.prototype.put;
+ vi.spyOn(IDBObjectStore.prototype, 'put').mockImplementationOnce(function (
+ this: IDBObjectStore,
+ value,
+ key
+ ) {
+ const request = put.call(this, value, key);
+ started.resolve();
+ return request;
+ });
+ db.set(entry('old'));
+ const flushing = db.flush();
+ await started.promise;
+ const clearing = db.clear();
+ await Promise.all([flushing, clearing]);
+ expect(await db.get('old')).toBeUndefined();
+ });
+
+ it('does not resurrect failed old writes after clear', async () => {
+ const db = store();
+ await db.clear();
+ let clearing: Promise<void> | undefined;
+ vi.spyOn(IDBObjectStore.prototype, 'put').mockImplementationOnce(() => {
+ clearing = db.clear();
+ throw new Error('Simulated storage failure');
+ });
+ db.set(entry('old'));
+ await db.flush();
+ await clearing;
+ await db.flush();
+ expect(await db.get('old')).toBeUndefined();
+ });
+});
diff --git a/apps/web/src/lib/queries/persistence/per-query-idb.ts b/apps/web/src/lib/queries/persistence/per-query-idb.ts
index 9832d0bf29..c78b36392a 100644
--- a/apps/web/src/lib/queries/persistence/per-query-idb.ts
+++ b/apps/web/src/lib/queries/persistence/per-query-idb.ts
@@ -16,6 +16,11 @@ export type PerQueryPersistence = {
flush: () => Promise<void>;
};
+export type ClearablePerQueryPersistence = PerQueryPersistence & {
+ /** Clear durable entries and fence pending/in-flight writes. */
+ clear: () => Promise<void>;
+};
+
type PerQueryPersistenceOptions = Readonly<{
dbName: string;
debounceMs?: number;
@@ -65,15 +70,36 @@ async function withStore<T>(
export function createPerQueryIDBStore(
options: PerQueryPersistenceOptions
-): PerQueryPersistence {
+): ClearablePerQueryPersistence {
const { dbName } = options;
const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
const pendingPuts = new Map<string, PersistedQueryEntry>();
const pendingDeletes = new Set<string>();
let timer: ReturnType<typeof setTimeout> | null = null;
+ let generation = 0;
+ let writes: Promise<void> = Promise.resolve();
+
+ async function settle(operation: Promise<unknown>): Promise<void> {
+ try {
+ await operation;
+ } catch {
+ // The caller handles failures; later transactions must still run.
+ }
+ }
+
+ function enqueueWrite(operation: () => Promise<void>): Promise<void> {
+ const previous = writes;
+ const next = (async () => {
+ await previous;
+ await operation();
+ })();
+ writes = settle(next);
+ return next;
+ }
const flush = async () => {
+ const currentGeneration = generation;
const puts = new Map(pendingPuts);
const deletes = new Set(pendingDeletes);
pendingPuts.clear();
@@ -82,23 +108,27 @@ export function createPerQueryIDBStore(
if (puts.size === 0 && deletes.size === 0) return;
try {
- const db = await openDB(dbName);
- const tx = db.transaction(STORE_NAME, 'readwrite');
- const store = tx.objectStore(STORE_NAME);
-
- for (const [hash, entry] of puts) {
- store.put(entry, hash);
- }
- for (const hash of deletes) {
- store.delete(hash);
- }
-
- await new Promise<void>((resolve, reject) => {
- tx.oncomplete = () => resolve();
- tx.onerror = () => reject(tx.error);
- tx.onabort = () => reject(tx.error);
+ await enqueueWrite(async () => {
+ const db = await openDB(dbName);
+ if (generation !== currentGeneration) return;
+ const tx = db.transaction(STORE_NAME, 'readwrite');
+ const store = tx.objectStore(STORE_NAME);
+
+ for (const [hash, entry] of puts) {
+ store.put(entry, hash);
+ }
+ for (const hash of deletes) {
+ store.delete(hash);
+ }
+
+ await new Promise<void>((resolve, reject) => {
+ tx.oncomplete = () => resolve();
+ tx.onerror = () => reject(tx.error);
+ tx.onabort = () => reject(tx.error);
+ });
});
} catch (err) {
+ if (generation !== currentGeneration) return;
for (const [hash, entry] of puts) {
if (!pendingPuts.has(hash)) pendingPuts.set(hash, entry);
}
@@ -118,10 +148,14 @@ export function createPerQueryIDBStore(
};
return {
- get: (queryHash) =>
- withStore<PersistedQueryEntry | undefined>(dbName, 'readonly', (store) =>
- store.get(queryHash)
- ),
+ get: async (queryHash) => {
+ await writes;
+ return withStore<PersistedQueryEntry | undefined>(
+ dbName,
+ 'readonly',
+ (store) => store.get(queryHash)
+ );
+ },
set: (entry) => {
pendingDeletes.delete(entry.queryHash);
@@ -141,6 +175,25 @@ export function createPerQueryIDBStore(
timer = null;
}
await flush();
+ await writes;
+ },
+
+ clear: async () => {
+ generation += 1;
+ if (timer) clearTimeout(timer);
+ timer = null;
+ pendingPuts.clear();
+ pendingDeletes.clear();
+ await enqueueWrite(async () => {
+ const db = await openDB(dbName);
+ const tx = db.transaction(STORE_NAME, 'readwrite');
+ tx.objectStore(STORE_NAME).clear();
+ await new Promise<void>((resolve, reject) => {
+ tx.oncomplete = () => resolve();
+ tx.onerror = () => reject(tx.error);
+ tx.onabort = () => reject(tx.error);
+ });
+ });
},
};
}
diff --git a/apps/web/src/lib/queries/storage/document-location.test.ts b/apps/web/src/lib/queries/storage/document-location.test.ts
new file mode 100644
index 0000000000..9140010430
--- /dev/null
+++ b/apps/web/src/lib/queries/storage/document-location.test.ts
@@ -0,0 +1,129 @@
+import { err, ok } from 'neverthrow';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { queryClient } from '../client';
+import {
+ waitForDocumentContentReady,
+ waitForDocumentPresignedUrlReady,
+ waitForDocumentSyncServiceReady,
+} from './document-location';
+import {
+ documentContext,
+ freshContext,
+ harness,
+} from './documentLoad/offline-context.test-helpers';
+
+const mocks = vi.hoisted(() => ({
+ getLocation: vi.fn(),
+ invalidate: vi.fn(),
+}));
+vi.mock('@service-storage/client', () => ({
+ storageServiceClient: {
+ getDocumentLocation: Object.assign(mocks.getLocation, {
+ invalidate: mocks.invalidate,
+ }),
+ },
+}));
+vi.mock('../client', async () => {
+ const { QueryClient } = await import('@tanstack/solid-query');
+ return {
+ queryClient: new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ }),
+ };
+});
+
+const pending = {
+ type: 'presignedUrl',
+ content: { state: 'pending' },
+} as const;
+const ready = {
+ type: 'syncServiceContent',
+ content: { state: 'ready' },
+} as const;
+const args = { documentId: 'doc-1', timeoutMs: 0 };
+
+beforeEach(() => vi.resetAllMocks());
+afterEach(() => queryClient.clear());
+
+describe('sync-service readiness', () => {
+ it('returns a ready sync-service location', async () => {
+ mocks.getLocation.mockResolvedValue(ok({ data: ready }));
+ expect(await waitForDocumentSyncServiceReady(args)).toEqual(ready);
+ });
+
+ it.each(['pending', 'unknown'] as const)(
+ 'reports a transient timeout when readiness expires in state %s',
+ async (state) => {
+ mocks.getLocation.mockResolvedValue(
+ ok({ data: { ...pending, content: { state } } })
+ );
+ await expect(waitForDocumentSyncServiceReady(args)).rejects.toMatchObject(
+ {
+ errors: [{ code: 'TIMEOUT' }],
+ }
+ );
+ }
+ );
+
+ it.each(['FORBIDDEN', 'NOT_FOUND', 'NETWORK_ERROR'])(
+ 'preserves a %s response after an earlier pending location',
+ async (code) => {
+ mocks.getLocation
+ .mockResolvedValueOnce(ok({ data: pending }))
+ .mockResolvedValue(err([{ code, message: 'Location request failed' }]));
+ await expect(
+ waitForDocumentSyncServiceReady({
+ ...args,
+ timeoutMs: 1000,
+ initialDelayMs: 0,
+ maxDelayMs: 0,
+ })
+ ).rejects.toMatchObject({ errors: [{ code }] });
+ }
+ );
+
+ it('returns a ready non-sync location for the caller to reject as invalid', async () => {
+ const location = { ...pending, content: { state: 'ready' } };
+ mocks.getLocation.mockResolvedValue(ok({ data: location }));
+ expect(await waitForDocumentSyncServiceReady(args)).toEqual(location);
+ });
+
+ it('retains cached authorization after timeout and allows a later successful retry', async () => {
+ const h = harness();
+ try {
+ await h.cache.write(h.cache.capture()!, documentContext);
+ h.loadRemote.mockImplementation(async () => {
+ await waitForDocumentSyncServiceReady(args);
+ return freshContext;
+ });
+ const opened = await h.loader.load('doc-1');
+ const invalidated = vi.fn();
+ const stop = opened.authorization!.onInvalidated(invalidated);
+ mocks.getLocation.mockResolvedValue(ok({ data: pending }));
+ await expect(opened.authorization!.getToken()).rejects.toMatchObject({
+ errors: [{ code: 'TIMEOUT' }],
+ });
+ expect(opened.authorization!.isCurrent()).toBe(true);
+ expect(opened.authorization!.canWrite()).toBe(false);
+ expect(invalidated).not.toHaveBeenCalled();
+ expect(await h.cache.read(h.cache.capture()!, 'doc-1')).toEqual(
+ documentContext
+ );
+
+ mocks.getLocation.mockResolvedValue(ok({ data: ready }));
+ expect(await opened.authorization!.getToken()).toBe(freshContext.token);
+ expect(opened.authorization!.canWrite()).toBe(true);
+ stop();
+ } finally {
+ await h.cache.clear();
+ }
+ });
+
+ it.each([waitForDocumentContentReady, waitForDocumentPresignedUrlReady])(
+ 'keeps the existing last-location fallback for non-sync waiters',
+ async (waitForReady) => {
+ mocks.getLocation.mockResolvedValue(ok({ data: pending }));
+ expect(await waitForReady(args)).toEqual(pending);
+ }
+ );
+});
diff --git a/apps/web/src/lib/queries/storage/document-location.ts b/apps/web/src/lib/queries/storage/document-location.ts
index 2d8873a62c..2747019d9b 100644
--- a/apps/web/src/lib/queries/storage/document-location.ts
+++ b/apps/web/src/lib/queries/storage/document-location.ts
@@ -2,6 +2,7 @@ import {
catchToResult,
type ResultError,
type ResultType,
+ ThrownResultError,
throwOnErr,
} from '@core/util/result';
import { storageServiceClient } from '@service-storage/client';
@@ -23,6 +24,7 @@ type DocumentLocation = ResultType<GetDocumentLocationResult>['data'];
type WaitForDocumentLocationOptions = {
target: string;
+ fallbackOnRequestError: boolean;
timeoutMs?: number;
initialDelayMs?: number;
maxDelayMs?: number;
@@ -137,7 +139,7 @@ async function waitForDocumentLocation(
if (error instanceof DocumentLocationNotReadyError) {
return error.location;
}
- if (lastLocation) return lastLocation;
+ if (options.fallbackOnRequestError && lastLocation) return lastLocation;
throw error;
}
}
@@ -152,6 +154,7 @@ export function waitForDocumentContentReady(
const { timeoutMs, initialDelayMs, maxDelayMs, ...locationArgs } = args;
return waitForDocumentLocation(locationArgs, {
target: 'content-ready',
+ fallbackOnRequestError: true,
timeoutMs,
initialDelayMs,
maxDelayMs,
@@ -160,7 +163,7 @@ export function waitForDocumentContentReady(
});
}
-export function waitForDocumentSyncServiceReady(
+export async function waitForDocumentSyncServiceReady(
args: DocumentLocationArgs & {
timeoutMs?: number;
initialDelayMs?: number;
@@ -168,8 +171,11 @@ export function waitForDocumentSyncServiceReady(
}
): Promise<DocumentLocation> {
const { timeoutMs, initialDelayMs, maxDelayMs, ...locationArgs } = args;
- return waitForDocumentLocation(locationArgs, {
+ const location = await waitForDocumentLocation(locationArgs, {
target: 'sync-service-ready',
+ // This result gates authorization. Do not hide a denial or network
+ // failure behind an earlier pending location.
+ fallbackOnRequestError: false,
timeoutMs,
initialDelayMs,
maxDelayMs,
@@ -177,6 +183,15 @@ export function waitForDocumentSyncServiceReady(
location.content.state === DocumentContentState.ready &&
location.type === 'syncServiceContent',
});
+ if (location.content.state !== DocumentContentState.ready) {
+ throw new ThrownResultError([
+ {
+ code: 'TIMEOUT',
+ message: 'Timed out waiting for sync-service document content',
+ },
+ ]);
+ }
+ return location;
}
export function waitForDocumentPresignedUrlReady(
@@ -189,6 +204,7 @@ export function waitForDocumentPresignedUrlReady(
const { timeoutMs, initialDelayMs, maxDelayMs, ...locationArgs } = args;
return waitForDocumentLocation(locationArgs, {
target: 'presigned-url-ready',
+ fallbackOnRequestError: true,
timeoutMs,
initialDelayMs,
maxDelayMs,
diff --git a/apps/web/src/lib/queries/storage/documentLoad/authorized-context.test.ts b/apps/web/src/lib/queries/storage/documentLoad/authorized-context.test.ts
new file mode 100644
index 0000000000..83eb8cfb4b
--- /dev/null
+++ b/apps/web/src/lib/queries/storage/documentLoad/authorized-context.test.ts
@@ -0,0 +1,68 @@
+import { base64url } from 'jose';
+import { describe, expect, it } from 'vitest';
+import { authorizedContext } from './authorized-context';
+import { freshContext } from './offline-context.test-helpers';
+
+const session = { userId: 'viewer-a', epoch: 'login-1', generation: 0 };
+const claims = {
+ user_id: session.userId,
+ document_id: 'doc-1',
+ access_level: 'edit',
+};
+const token = (payload: unknown) =>
+ `e30.${base64url.encode(JSON.stringify(payload))}.test-signature`;
+
+describe('fresh document authorization binding', () => {
+ it('accepts the current user and document', () => {
+ expect(
+ authorizedContext('doc-1', session, {
+ ...freshContext,
+ token: token(claims),
+ }).userAccessLevel
+ ).toBe('edit');
+ });
+
+ it.each([
+ { ...claims, user_id: 'another-viewer' },
+ { ...claims, document_id: 'another-document' },
+ { ...claims, user_id: null },
+ { ...claims, access_level: 'admin' },
+ ])('rejects a mismatched or unbound token', (payload) => {
+ expect(() =>
+ authorizedContext('doc-1', session, {
+ ...freshContext,
+ token: token(payload),
+ })
+ ).toThrow('Document authorization does not match');
+ });
+
+ it('rejects malformed tokens and metadata for a different document', () => {
+ expect(() => authorizedContext('doc-1', session, freshContext)).toThrow();
+ expect(() =>
+ authorizedContext('doc-1', session, {
+ ...freshContext,
+ token: token(claims),
+ documentMetadata: {
+ ...freshContext.documentMetadata,
+ documentId: 'other',
+ },
+ })
+ ).toThrow();
+ });
+
+ it('keeps the more restrictive grant when authorization changes between requests', () => {
+ expect(
+ authorizedContext('doc-1', session, {
+ ...freshContext,
+ token: token({ ...claims, access_level: 'view' }),
+ }).userAccessLevel
+ ).toBe('view');
+ expect(
+ authorizedContext('doc-1', session, {
+ ...freshContext,
+ userAccessLevel: 'comment',
+ token: token({ ...claims, access_level: 'owner' }),
+ }).userAccessLevel
+ ).toBe('comment');
+ });
+});
diff --git a/apps/web/src/lib/queries/storage/documentLoad/authorized-context.ts b/apps/web/src/lib/queries/storage/documentLoad/authorized-context.ts
new file mode 100644
index 0000000000..d99ca6a16a
--- /dev/null
+++ b/apps/web/src/lib/queries/storage/documentLoad/authorized-context.ts
@@ -0,0 +1,54 @@
+import { ThrownResultError } from '@core/util/result';
+import type { AccessLevel } from '@service-storage/generated/schemas/accessLevel';
+import { decodeJwt } from 'jose';
+import { z } from 'zod';
+import type { DocumentLoadBundle } from './documentLoadBundle';
+import type { DocumentCacheSession } from './offline-context-cache';
+
+const claimsSchema = z.object({
+ user_id: z.string(),
+ document_id: z.string(),
+ access_level: z.enum(['view', 'comment', 'edit', 'owner']),
+});
+const rank: Record<AccessLevel, number> = {
+ view: 0,
+ comment: 1,
+ edit: 2,
+ owner: 3,
+};
+
+/** Bind a freshly fetched HTTPS response to the captured viewer, not a stale user-info cache.
+ * This is not signature verification; sync-service still verifies the JWT itself.
+ */
+export function authorizedContext(
+ documentId: string,
+ session: DocumentCacheSession,
+ bundle: DocumentLoadBundle
+): DocumentLoadBundle {
+ const deny = () =>
+ new ThrownResultError([
+ {
+ code: 'UNAUTHORIZED',
+ message: 'Document authorization does not match the current session',
+ },
+ ]);
+ let claims: z.infer<typeof claimsSchema>;
+ try {
+ claims = claimsSchema.parse(decodeJwt(bundle.token));
+ } catch {
+ throw deny();
+ }
+ if (
+ claims.user_id !== session.userId ||
+ claims.document_id !== documentId ||
+ bundle.documentMetadata.documentId !== documentId
+ )
+ throw deny();
+ // Permissions can change between the two requests. Cache the more restrictive
+ // answer; never infer a broader local grant than the fresh token allows.
+ const userAccessLevel =
+ rank[claims.access_level] < rank[bundle.userAccessLevel]
+ ? claims.access_level
+ : bundle.userAccessLevel;
+ return { ...bundle, userAccessLevel };
+}
diff --git a/apps/web/src/lib/queries/storage/documentLoad/keys.ts b/apps/web/src/lib/queries/storage/documentLoad/keys.ts
index ad520ab948..5442f5de8c 100644
--- a/apps/web/src/lib/queries/storage/documentLoad/keys.ts
+++ b/apps/web/src/lib/queries/storage/documentLoad/keys.ts
@@ -4,4 +4,10 @@ export const documentLoadKeys = createQueryKeys('documentLoad', {
bundle: (documentId: string) => ({
queryKey: [documentId],
}),
+ offlineContext: (userId: string, epoch: string, documentId: string) => ({
+ queryKey: [userId, epoch, documentId],
+ }),
+ authorizedBundle: (userId: string, epoch: string, documentId: string) => ({
+ queryKey: [userId, epoch, documentId],
+ }),
});
diff --git a/apps/web/src/lib/queries/storage/documentLoad/offline-context-cache.test.ts b/apps/web/src/lib/queries/storage/documentLoad/offline-context-cache.test.ts
new file mode 100644
index 0000000000..3cc2d65320
--- /dev/null
+++ b/apps/web/src/lib/queries/storage/documentLoad/offline-context-cache.test.ts
@@ -0,0 +1,112 @@
+import { describe, expect, it, vi } from 'vitest';
+import { documentContext, harness } from './offline-context.test-helpers';
+
+describe('offline document context persistence', () => {
+ it('survives a new cache instance without persisting tokens or opaque metadata', async () => {
+ const h = harness();
+ const session = h.cache.capture()!;
+ const write = vi.spyOn(h.store, 'set');
+ const unsafe = {
+ ...documentContext,
+ token: 'credential-secret',
+ documentMetadata: {
+ ...documentContext.documentMetadata,
+ token: 'credential-secret',
+ modificationData: { signedUrl: 'credential-secret' },
+ documentBom: [{ id: 'part', path: 'credential-secret', sha: 'hash' }],
+ },
+ };
+ await h.cache.write(session, unsafe);
+ expect(JSON.stringify(write.mock.calls[0][0])).not.toContain(
+ 'credential-secret'
+ );
+ const restarted = h.restart();
+ expect(
+ await restarted.cache.read(restarted.cache.capture()!, 'doc-1')
+ ).toEqual(documentContext);
+ await h.cache.clear();
+ });
+
+ it('never exposes another user or login epoch', async () => {
+ const h = harness();
+ await h.cache.write(h.cache.capture()!, documentContext);
+ h.identify({ userId: 'viewer-b', epoch: 'login-1' });
+ expect(await h.cache.read(h.cache.capture()!, 'doc-1')).toBeUndefined();
+ h.identify({ userId: 'viewer-a', epoch: 'login-2' });
+ expect(await h.cache.read(h.cache.capture()!, 'doc-1')).toBeUndefined();
+ h.identify(undefined);
+ expect(h.cache.capture()).toBeUndefined();
+ await h.cache.clear();
+ });
+
+ it('fences pending reads and late writes after logout, including the same user signing back in', async () => {
+ const h = harness();
+ const session = h.cache.capture()!;
+ await h.cache.write(session, documentContext);
+ const blocked = Promise.withResolvers<void>();
+ const read = h.store.get;
+ vi.spyOn(h.store, 'get').mockImplementation(async (key) => {
+ await blocked.promise;
+ return read(key);
+ });
+ const pending = h.cache.read(session, 'doc-1');
+ await h.cache.clear();
+ await h.cache.write(session, documentContext);
+ blocked.resolve();
+ expect(await pending).toBeUndefined();
+ expect(await h.cache.read(h.cache.capture()!, 'doc-1')).toBeUndefined();
+ });
+
+ it('rejects mismatched, deleted, and incompatible records', async () => {
+ const h = harness();
+ const session = h.cache.capture()!;
+ const write = vi.spyOn(h.store, 'set');
+ await h.cache.write(session, documentContext);
+ const entry = write.mock.calls[0][0];
+ const invalid = [
+ { ...entry, buster: 'old-version' },
+ { ...entry, data: { ...documentContext, userAccessLevel: 'admin' } },
+ {
+ ...entry,
+ data: {
+ ...documentContext,
+ documentMetadata: {
+ ...documentContext.documentMetadata,
+ documentId: 'other-document',
+ },
+ },
+ },
+ {
+ ...entry,
+ data: {
+ ...documentContext,
+ documentMetadata: {
+ ...documentContext.documentMetadata,
+ deletedAt: new Date().toISOString(),
+ },
+ },
+ },
+ ];
+ for (const value of invalid) {
+ h.store.set(value);
+ await h.store.flush();
+ expect(await h.cache.read(session, 'doc-1')).toBeUndefined();
+ }
+ await h.cache.clear();
+ });
+
+ it('removes an older grant when metadata confirms deletion', async () => {
+ const h = harness();
+ const session = h.cache.capture()!;
+ await h.cache.write(session, documentContext);
+ await h.cache.write(session, {
+ ...documentContext,
+ documentMetadata: {
+ ...documentContext.documentMetadata,
+ deletedAt: new Date().toISOString(),
+ },
+ });
+ expect(await h.cache.read(session, 'doc-1')).toBeUndefined();
+ await h.cache.clear();
+ });
+});
diff --git a/apps/web/src/lib/queries/storage/documentLoad/offline-context-cache.ts b/apps/web/src/lib/queries/storage/documentLoad/offline-context-cache.ts
new file mode 100644
index 0000000000..6120e5fd32
--- /dev/null
+++ b/apps/web/src/lib/queries/storage/documentLoad/offline-context-cache.ts
@@ -0,0 +1,126 @@
+import type { AccessLevel } from '@service-storage/generated/schemas/accessLevel';
+import type { DocumentMetadata } from '@service-storage/generated/schemas/documentMetadata';
+import { getDocumentVersionResponse } from '@service-storage/generated/zod';
+import { z } from 'zod';
+import type { ClearablePerQueryPersistence } from '../../persistence/per-query-idb';
+import { documentLoadKeys } from './keys';
+
+const BUSTER = 'sync-document-open-v1';
+const contextSchema = z.object({
+ syncService: z.literal(true),
+ documentMetadata:
+ getDocumentVersionResponse.shape.data.shape.documentMetadata.omit({
+ documentBom: true,
+ modificationData: true,
+ }),
+ userAccessLevel: getDocumentVersionResponse.shape.data.shape.userAccessLevel,
+});
+
+/** Non-secret, last-authorized context for a ready sync-service document. */
+export type OfflineDocumentContext = {
+ syncService: true;
+ documentMetadata: DocumentMetadata;
+ userAccessLevel: AccessLevel;
+};
+
+export type DocumentCacheIdentity = Readonly<{ userId: string; epoch: string }>;
+export type DocumentCacheSession = DocumentCacheIdentity &
+ Readonly<{ generation: number }>;
+
+/** User/session-fenced persistence. Tokens and opaque binary metadata are excluded. */
+export function createOfflineDocumentContextCache(options: {
+ store: ClearablePerQueryPersistence;
+ identity: () => DocumentCacheIdentity | undefined;
+}) {
+ let generation = 0;
+ const capture = (): DocumentCacheSession | undefined => {
+ const identity = options.identity();
+ return identity ? { ...identity, generation } : undefined;
+ };
+ const isCurrent = (session: DocumentCacheSession) => {
+ const current = capture();
+ return (
+ current?.userId === session.userId &&
+ current.epoch === session.epoch &&
+ current.generation === session.generation
+ );
+ };
+ const key = (session: DocumentCacheSession, documentId: string) =>
+ documentLoadKeys.offlineContext(session.userId, session.epoch, documentId)
+ .queryKey;
+
+ return {
+ capture,
+ isCurrent,
+ async read(
+ session: DocumentCacheSession,
+ documentId: string
+ ): Promise<OfflineDocumentContext | undefined> {
+ if (!isCurrent(session)) return;
+ const queryKey = key(session, documentId);
+ const hash = JSON.stringify(queryKey);
+ try {
+ const entry = await options.store.get(hash);
+ if (
+ !isCurrent(session) ||
+ !entry ||
+ entry.buster !== BUSTER ||
+ entry.queryHash !== hash ||
+ JSON.stringify(entry.queryKey) !== hash
+ )
+ return;
+ const parsed = contextSchema.safeParse(entry.data);
+ if (
+ !parsed.success ||
+ parsed.data.documentMetadata.documentId !== documentId ||
+ parsed.data.documentMetadata.deletedAt != null
+ )
+ return;
+ return parsed.data;
+ } catch {
+ // A storage failure must not prevent an online open.
+ return;
+ }
+ },
+ async write(
+ session: DocumentCacheSession,
+ context: OfflineDocumentContext
+ ): Promise<void> {
+ if (!isCurrent(session)) return;
+ const data = contextSchema.parse(context);
+ const queryKey = key(session, data.documentMetadata.documentId);
+ if (data.documentMetadata.deletedAt != null) {
+ options.store.remove(JSON.stringify(queryKey));
+ await options.store.flush();
+ return;
+ }
+ const now = Date.now();
+ options.store.set({
+ queryHash: JSON.stringify(queryKey),
+ queryKey,
+ data,
+ dataUpdatedAt: now,
+ persistedAt: now,
+ buster: BUSTER,
+ });
+ await options.store.flush();
+ },
+ async remove(
+ session: DocumentCacheSession,
+ documentId: string
+ ): Promise<void> {
+ if (!isCurrent(session)) return;
+ options.store.remove(JSON.stringify(key(session, documentId)));
+ await options.store.flush();
+ },
+ clear(): Promise<void> {
+ // Fence old reads/network responses before waiting for IndexedDB.
+ generation += 1;
+ return options.store.clear();
+ },
+ };
+}
+
+export type OfflineDocumentContextCache = ReturnType<
+ typeof createOfflineDocumentContextCache
+>;
diff --git a/apps/web/src/lib/queries/storage/documentLoad/offline-context-runtime.ts b/apps/web/src/lib/queries/storage/documentLoad/offline-context-runtime.ts
new file mode 100644
index 0000000000..6cb630d88c
--- /dev/null
+++ b/apps/web/src/lib/queries/storage/documentLoad/offline-context-runtime.ts
@@ -0,0 +1,66 @@
+import { isNativeMobilePlatform } from '@core/mobile/isNativeMobilePlatform';
+import { hasLoginCookie } from '@core/util/cookies';
+import { authKeys } from '../../auth/keys';
+import type { UserInfoData } from '../../auth/user-info';
+import { queryClient } from '../../client';
+import { createPerQueryIDBStore } from '../../persistence/per-query-idb';
+import { createOfflineDocumentContextCache } from './offline-context-cache';
+
+const EPOCH_KEY = 'document-open-context:epoch';
+let persistenceAvailable = true;
+let volatileEpoch = crypto.randomUUID();
+let validatedEpoch: string | undefined;
+
+/** Fence native loads that begin before user-info hydration supplies an identity. */
+export function documentSessionEpoch(): string {
+ if (!persistenceAvailable) return volatileEpoch;
+ try {
+ const epoch = localStorage.getItem(EPOCH_KEY) ?? crypto.randomUUID();
+ // Probe once per epoch, not on every editor/status callback.
+ if (validatedEpoch !== epoch) {
+ localStorage.setItem(EPOCH_KEY, epoch);
+ validatedEpoch = epoch;
+ }
+ return epoch;
+ } catch {
+ // Keep source authorization session-bound even without durable storage.
+ return volatileEpoch;
+ }
+}
+
+export const offlineDocumentContextCache = createOfflineDocumentContextCache({
+ store: createPerQueryIDBStore({ dbName: 'native-document-open-persist-v1' }),
+ identity: () => {
+ if (!isNativeMobilePlatform() || !hasLoginCookie()) return;
+ const state = queryClient.getQueryState<UserInfoData>(
+ authKeys.userInfo.queryKey
+ );
+ if (!state?.data?.authenticated || !state.data.id) return;
+ return { userId: state.data.id, epoch: documentSessionEpoch() };
+ },
+});
+
+/** Rotate before asynchronous clearing so late work cannot restore a logged-out session. */
+export async function clearOfflineDocumentContexts(): Promise<void> {
+ if (!isNativeMobilePlatform()) return;
+ volatileEpoch = crypto.randomUUID();
+ try {
+ localStorage.setItem(EPOCH_KEY, volatileEpoch);
+ } catch {
+ persistenceAvailable = false;
+ }
+ try {
+ await offlineDocumentContextCache.clear();
+ } catch {
+ // The rotated epoch quarantines old entries even if IndexedDB cannot clear.
+ console.error('Failed to clear offline document contexts');
+ }
+}
+
+/** Notify sources when logout or an account change invalidates their captured identity. */
+export function onDocumentSessionChange(listener: () => void): () => void {
+ return queryClient.getQueryCache().subscribe((event) => {
+ if (event.query.queryHash === JSON.stringify(authKeys.userInfo.queryKey))
+ listener();
+ });
+}
diff --git a/apps/web/src/lib/queries/storage/documentLoad/offline-context.test-helpers.ts b/apps/web/src/lib/queries/storage/documentLoad/offline-context.test-helpers.ts
new file mode 100644
index 0000000000..0557d9af50
--- /dev/null
+++ b/apps/web/src/lib/queries/storage/documentLoad/offline-context.test-helpers.ts
@@ -0,0 +1,63 @@
+import 'fake-indexeddb/auto';
+import { vi } from 'vitest';
+import { createPerQueryIDBStore } from '../../persistence/per-query-idb';
+import {
+ createOfflineDocumentContextCache,
+ type DocumentCacheIdentity,
+ type OfflineDocumentContext,
+} from './offline-context-cache';
+import { createSyncDocumentContextLoader } from './sync-document-context-loader';
+
+export const documentContext: OfflineDocumentContext = {
+ syncService: true,
+ documentMetadata: {
+ documentId: 'doc-1',
+ documentName: 'Offline note',
+ documentVersionId: 1,
+ owner: 'another-owner',
+ fileType: 'md',
+ },
+ userAccessLevel: 'edit',
+};
+export const freshContext = {
+ ...documentContext,
+ token: 'fresh-test-credential',
+};
+
+export function harness() {
+ const dbName = `document-context-test-${crypto.randomUUID()}`;
+ let identity: DocumentCacheIdentity | undefined = {
+ userId: 'viewer-a',
+ epoch: 'login-1',
+ };
+ const listeners = new Set<() => void>();
+ const create = () => {
+ const store = createPerQueryIDBStore({ dbName, debounceMs: 60_000 });
+ const cache = createOfflineDocumentContextCache({
+ store,
+ identity: () => identity,
+ });
+ const loadRemote = vi.fn(async () => freshContext);
+ const hasLocalSnapshot = vi.fn(async () => true);
+ const loader = createSyncDocumentContextLoader({
+ cache,
+ loadRemote,
+ hasLocalSnapshot,
+ onSessionChange: (listener) => {
+ listeners.add(listener);
+ return () => {
+ listeners.delete(listener);
+ };
+ },
+ });
+ return { store, cache, loader, loadRemote, hasLocalSnapshot };
+ };
+ return {
+ ...create(),
+ restart: create,
+ identify(next: DocumentCacheIdentity | undefined) {
+ identity = next;
+ for (const listener of listeners) listener();
+ },
+ };
+}
diff --git a/apps/web/src/lib/queries/storage/documentLoad/sync-document-context-loader.test.ts b/apps/web/src/lib/queries/storage/documentLoad/sync-document-context-loader.test.ts
new file mode 100644
index 0000000000..126061c5f4
--- /dev/null
+++ b/apps/web/src/lib/queries/storage/documentLoad/sync-document-context-loader.test.ts
@@ -0,0 +1,167 @@
+import { ThrownResultError } from '@core/util/result';
+import { describe, expect, it, vi } from 'vitest';
+import {
+ documentContext,
+ freshContext,
+ harness,
+} from './offline-context.test-helpers';
+
+const failure = (code: string) =>
+ new ThrownResultError([{ code, message: 'Request failed' }]);
+
+describe('cache-first sync document open', () => {
+ it('opens after a restart while authorization is offline, retaining last-known edit permission', async () => {
+ const h = harness();
+ const online = await h.loader.load('doc-1');
+ expect(online.fromCache).toBe(false);
+ expect(online.token).toBeUndefined();
+ expect(await online.authorization!.getToken()).toBe(freshContext.token);
+ expect(h.loadRemote).toHaveBeenCalledTimes(1);
+
+ const restarted = h.restart();
+ restarted.loadRemote.mockRejectedValue(failure('NETWORK_ERROR'));
+ const offline = await restarted.loader.load('doc-1');
+ expect(offline.fromCache).toBe(true);
+ expect(offline.userAccessLevel).toBe('edit');
+ expect(offline.token).toBeUndefined();
+ expect(restarted.loadRemote).not.toHaveBeenCalled();
+ await expect(offline.authorization!.getToken()).rejects.toBeInstanceOf(
+ ThrownResultError
+ );
+ expect(
+ await restarted.cache.read(restarted.cache.capture()!, 'doc-1')
+ ).toEqual(documentContext);
+ await h.cache.clear();
+ });
+
+ it('reauthorizes every reconnect and persists updated permissions, never the token', async () => {
+ const h = harness();
+ await h.cache.write(h.cache.capture()!, documentContext);
+ const opened = await h.loader.load('doc-1');
+ h.loadRemote.mockResolvedValue({
+ ...freshContext,
+ userAccessLevel: 'view',
+ token: 'new-token',
+ });
+ expect(await opened.authorization!.getToken()).toBe('new-token');
+ expect(
+ (await h.cache.read(h.cache.capture()!, 'doc-1'))?.userAccessLevel
+ ).toBe('view');
+ h.loadRemote.mockRejectedValueOnce(failure('NETWORK_ERROR'));
+ await expect(opened.authorization!.getToken()).rejects.toBeInstanceOf(
+ ThrownResultError
+ );
+ expect(h.loadRemote).toHaveBeenCalledTimes(2);
+ await h.cache.clear();
+ });
+
+ it.each(['view', 'comment'] as const)(
+ 'blocks an active cached editor from sending edits after downgrade to %s',
+ async (userAccessLevel) => {
+ const h = harness();
+ await h.cache.write(h.cache.capture()!, documentContext);
+ const opened = await h.loader.load('doc-1');
+ expect(opened.authorization!.canWrite()).toBe(false);
+ h.loadRemote.mockResolvedValue({ ...freshContext, userAccessLevel });
+ await opened.authorization!.getToken();
+ expect(opened.authorization!.canWrite()).toBe(false);
+ h.loadRemote.mockResolvedValue(freshContext);
+ await opened.authorization!.getToken();
+ expect(opened.authorization!.canWrite()).toBe(true);
+ await h.cache.clear();
+ }
+ );
+
+ it.each(['FORBIDDEN', 'NOT_FOUND', 'INVALID'])(
+ 'evicts on definitive %s without opening a sync connection',
+ async (code) => {
+ const h = harness();
+ await h.cache.write(h.cache.capture()!, documentContext);
+ const opened = await h.loader.load('doc-1');
+ const invalidated = vi.fn();
+ const stop = opened.authorization!.onInvalidated(invalidated);
+ h.loadRemote.mockRejectedValue(failure(code));
+ await expect(opened.authorization!.getToken()).rejects.toBeInstanceOf(
+ ThrownResultError
+ );
+ expect(invalidated).toHaveBeenCalledOnce();
+ expect(opened.authorization!.isCurrent()).toBe(false);
+ expect(await h.cache.read(h.cache.capture()!, 'doc-1')).toBeUndefined();
+ stop();
+ await h.cache.clear();
+ }
+ );
+
+ it.each(['UNAUTHORIZED', 'NETWORK_ERROR', 'INTERNAL_SERVER_ERROR'])(
+ 'preserves cached access on an unconfirmed/transient %s',
+ async (code) => {
+ const h = harness();
+ await h.cache.write(h.cache.capture()!, documentContext);
+ const opened = await h.loader.load('doc-1');
+ h.loadRemote.mockRejectedValue(failure(code));
+ await expect(opened.authorization!.getToken()).rejects.toBeInstanceOf(
+ ThrownResultError
+ );
+ expect(opened.authorization!.isCurrent()).toBe(true);
+ expect(await h.cache.read(h.cache.capture()!, 'doc-1')).toEqual(
+ documentContext
+ );
+ await h.cache.clear();
+ }
+ );
+
+ it('does not bootstrap an empty editable document when the snapshot is missing', async () => {
+ const h = harness();
+ await h.cache.write(h.cache.capture()!, documentContext);
+ h.hasLocalSnapshot.mockResolvedValue(false);
+ h.loadRemote.mockRejectedValue(failure('NETWORK_ERROR'));
+ await expect(h.loader.load('doc-1')).rejects.toBeInstanceOf(
+ ThrownResultError
+ );
+ expect(h.loadRemote).toHaveBeenCalledOnce();
+ await h.cache.clear();
+ });
+
+ it('invalidates an open source on account switch and never reuses the other account context', async () => {
+ const h = harness();
+ await h.cache.write(h.cache.capture()!, documentContext);
+ const opened = await h.loader.load('doc-1');
+ const invalidated = vi.fn();
+ const stop = opened.authorization!.onInvalidated(invalidated);
+ h.identify({ userId: 'viewer-b', epoch: 'login-1' });
+ expect(invalidated).toHaveBeenCalledOnce();
+ await expect(opened.authorization!.getToken()).rejects.toBeInstanceOf(
+ ThrownResultError
+ );
+ expect(h.loadRemote).not.toHaveBeenCalled();
+ h.loadRemote.mockRejectedValue(failure('NETWORK_ERROR'));
+ await expect(h.loader.load('doc-1')).rejects.toBeInstanceOf(
+ ThrownResultError
+ );
+ stop();
+ await h.cache.clear();
+ });
+
+ it('discards a network result that completes after logout', async () => {
+ const h = harness();
+ const response = Promise.withResolvers<typeof freshContext>();
+ h.loadRemote.mockReturnValue(response.promise);
+ const loading = h.loader.load('doc-1');
+ await vi.waitFor(() => expect(h.loadRemote).toHaveBeenCalledOnce());
+ await h.cache.clear();
+ response.resolve(freshContext);
+ await expect(loading).rejects.toBeInstanceOf(ThrownResultError);
+ expect(await h.cache.read(h.cache.capture()!, 'doc-1')).toBeUndefined();
+ });
+
+ it('keeps the existing non-native network path without persisting context', async () => {
+ const h = harness();
+ h.identify(undefined);
+ const write = vi.spyOn(h.store, 'set');
+ const opened = await h.loader.load('doc-1');
+ expect(opened.token).toBe(freshContext.token);
+ expect(opened.authorization).toBeUndefined();
+ expect(write).not.toHaveBeenCalled();
+ await h.cache.clear();
+ });
+});
diff --git a/apps/web/src/lib/queries/storage/documentLoad/sync-document-context-loader.ts b/apps/web/src/lib/queries/storage/documentLoad/sync-document-context-loader.ts
new file mode 100644
index 0000000000..168e513fc1
--- /dev/null
+++ b/apps/web/src/lib/queries/storage/documentLoad/sync-document-context-loader.ts
@@ -0,0 +1,154 @@
+import { ThrownResultError, thrownResultErrorHasCode } from '@core/util/result';
+import type { DocumentSyncAuthorization } from '@service-sync/source/authorization';
+import type {
+ DocumentCacheSession,
+ OfflineDocumentContext,
+ OfflineDocumentContextCache,
+} from './offline-context-cache';
+
+export type FreshSyncDocumentContext = OfflineDocumentContext & {
+ token: string;
+};
+export type SyncDocumentOpenContext = OfflineDocumentContext & {
+ fromCache: boolean;
+ token?: string;
+ authorization?: DocumentSyncAuthorization;
+};
+
+function assertSession(
+ cache: OfflineDocumentContextCache,
+ session: DocumentCacheSession
+) {
+ if (!cache.isCurrent(session)) {
+ throw new ThrownResultError([
+ { code: 'UNAUTHORIZED', message: 'Document session changed' },
+ ]);
+ }
+}
+
+function accessDenied(error: unknown): boolean {
+ // A latched global refresh error can also appear as UNAUTHORIZED while
+ // offline. Global session confirmation/logout handles that; do not evict
+ // last-known document access for an unconfirmed session refresh failure.
+ return ['FORBIDDEN', 'NOT_FOUND', 'INVALID'].some((code) =>
+ thrownResultErrorHasCode(error, code)
+ );
+}
+
+/** Cache-first open, with network authority required independently for synchronization. */
+export function createSyncDocumentContextLoader(options: {
+ cache: OfflineDocumentContextCache;
+ loadRemote: (
+ documentId: string,
+ session?: DocumentCacheSession
+ ) => Promise<FreshSyncDocumentContext>;
+ hasLocalSnapshot: (documentId: string) => Promise<boolean>;
+ onSessionChange: (listener: () => void) => () => void;
+}) {
+ const { cache } = options;
+
+ async function persist(
+ session: DocumentCacheSession,
+ context: OfflineDocumentContext
+ ) {
+ assertSession(cache, session);
+ try {
+ await cache.write(session, context);
+ } catch {
+ console.error('Failed to persist offline document context');
+ }
+ assertSession(cache, session);
+ }
+
+ function authorization(
+ documentId: string,
+ session: DocumentCacheSession,
+ opened: OfflineDocumentContext,
+ initial?: FreshSyncDocumentContext
+ ): DocumentSyncAuthorization {
+ let first = initial;
+ let freshAccess = initial?.userAccessLevel;
+ let revoked = false;
+ const listeners = new Set<() => void>();
+ const isCurrent = () => !revoked && cache.isCurrent(session);
+ const notify = () => {
+ for (const listener of listeners) listener();
+ };
+ return {
+ isCurrent,
+ canWrite: () =>
+ isCurrent() &&
+ (freshAccess === 'owner' ||
+ freshAccess === 'edit' ||
+ (freshAccess === 'comment' && opened.userAccessLevel === 'comment')),
+ onInvalidated(listener) {
+ listeners.add(listener);
+ const unsubscribe = options.onSessionChange(() => {
+ if (!isCurrent()) notify();
+ });
+ if (!isCurrent()) listener();
+ return () => {
+ listeners.delete(listener);
+ unsubscribe();
+ };
+ },
+ async getToken() {
+ assertSession(cache, session);
+ if (revoked) throw new Error('Document access was revoked');
+ freshAccess = undefined;
+ try {
+ const initial = first;
+ first = undefined;
+ const response =
+ initial ?? (await options.loadRemote(documentId, session));
+ assertSession(cache, session);
+ if (!initial) await persist(session, response);
+ if (!response.token)
+ throw new Error('Document authorization returned no token');
+ freshAccess = response.userAccessLevel;
+ return response.token;
+ } catch (error) {
+ if (accessDenied(error)) {
+ revoked = true;
+ notify();
+ try {
+ await cache.remove(session, documentId);
+ } catch {
+ console.error('Failed to remove denied document context');
+ }
+ }
+ throw error;
+ }
+ },
+ };
+ }
+
+ return {
+ async load(documentId: string): Promise<SyncDocumentOpenContext> {
+ const session = cache.capture();
+ if (session) {
+ const cached = await cache.read(session, documentId);
+ assertSession(cache, session);
+ if (cached && (await options.hasLocalSnapshot(documentId))) {
+ assertSession(cache, session);
+ return {
+ ...cached,
+ fromCache: true,
+ authorization: authorization(documentId, session, cached),
+ };
+ }
+ assertSession(cache, session);
+ }
+ const fresh = await options.loadRemote(documentId, session);
+ if (!session) return { ...fresh, fromCache: false };
+ await persist(session, fresh);
+ return {
+ syncService: true,
+ documentMetadata: fresh.documentMetadata,
+ userAccessLevel: fresh.userAccessLevel,
+ fromCache: false,
+ authorization: authorization(documentId, session, fresh, fresh),
+ };
+ },
+ };
+}
diff --git a/apps/web/src/lib/queries/storage/documentLoad/sync-document-context.test.ts b/apps/web/src/lib/queries/storage/documentLoad/sync-document-context.test.ts
new file mode 100644
index 0000000000..7d43eb29d0
--- /dev/null
+++ b/apps/web/src/lib/queries/storage/documentLoad/sync-document-context.test.ts
@@ -0,0 +1,349 @@
+import 'fake-indexeddb/auto';
+import { render } from '@solidjs/testing-library';
+import { QueryClientProvider } from '@tanstack/solid-query';
+import { err, ok } from 'neverthrow';
+import { createComponent, createEffect } from 'solid-js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { authKeys } from '../../auth/keys';
+import { useUserInfoQuery } from '../../auth/user-info';
+import { queryClient } from '../../client';
+import type { PersistedQueryEntry } from '../../persistence/per-query-idb';
+import { documentContext, freshContext } from './offline-context.test-helpers';
+import {
+ clearOfflineDocumentContexts,
+ offlineDocumentContextCache,
+} from './offline-context-runtime';
+import { fetchSyncDocumentOpenContext } from './sync-document-context';
+
+const mocks = vi.hoisted(() => ({
+ native: true,
+ login: true,
+ restore: vi.fn(),
+ userInfo: vi.fn(),
+ snapshot: vi.fn(),
+ bundle: vi.fn(),
+ location: vi.fn(),
+}));
+vi.mock('@core/mobile/isNativeMobilePlatform', () => ({
+ isNativeMobilePlatform: () => mocks.native,
+}));
+vi.mock('@core/util/cookies', () => ({ hasLoginCookie: () => mocks.login }));
+vi.mock('@core/auth/push-registration-lifecycle', () => ({
+ syncPushRegistrations: vi.fn(),
+}));
+vi.mock('@core/context/user-info-gate', () => ({
+ enableUserInfoQuery: vi.fn(),
+}));
+vi.mock('@service-auth/client', () => ({
+ authServiceClient: { getLegacyUserPermissions: mocks.userInfo },
+}));
+vi.mock('@macro-inc/collaboration/collab/snapshot-store', () => ({
+ LORO_SNAPSHOT_DB_NAME: 'test-snapshots',
+ IDBSnapshotStore: class {
+ load = mocks.snapshot;
+ },
+}));
+vi.mock('./documentLoadBundle', () => ({
+ documentLoadQueryOptions: () => ({
+ queryKey: ['test-bundle'],
+ queryFn: mocks.bundle,
+ }),
+ fetchDocumentLoadBundle: async () => ok(await mocks.bundle()),
+}));
+vi.mock('../document-location', () => ({
+ fetchDocumentLocation: mocks.location,
+ waitForDocumentSyncServiceReady: vi.fn(),
+}));
+vi.mock('../../client', async () => {
+ const { QueryClient } = await import('@tanstack/solid-query');
+ const { setupQueryPersistence } = await import('../../persistence');
+ const { createQueryPersistenceScopes } = await import(
+ '../../persistence-scopes'
+ );
+ const { authKeys } = await import('../../auth/keys');
+ const userInfoScope = createQueryPersistenceScopes('test').find((scope) =>
+ scope.shouldPersist(authKeys.userInfo.queryKey)
+ )!;
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ const queryPersistence = setupQueryPersistence({
+ queryClient,
+ scopes: [
+ {
+ ...userInfoScope,
+ store: {
+ get: mocks.restore,
+ set: vi.fn(),
+ remove: vi.fn(),
+ flush: async () => {},
+ },
+ },
+ ],
+ });
+ return { queryClient, queryPersistence };
+});
+
+const identity = { id: 'viewer-a', authenticated: true };
+const entry: PersistedQueryEntry = {
+ queryKey: authKeys.userInfo.queryKey,
+ queryHash: JSON.stringify(authKeys.userInfo.queryKey),
+ data: identity,
+ dataUpdatedAt: 1,
+ persistedAt: 1,
+ buster: 'test',
+};
+
+beforeEach(async () => {
+ vi.resetAllMocks();
+ mocks.native = true;
+ mocks.login = true;
+ queryClient.clear();
+ await clearOfflineDocumentContexts();
+ queryClient.setQueryData(authKeys.userInfo.queryKey, identity);
+ await offlineDocumentContextCache.write(
+ offlineDocumentContextCache.capture()!,
+ documentContext
+ );
+ queryClient.removeQueries({ queryKey: authKeys.userInfo.queryKey });
+ mocks.restore.mockClear();
+ mocks.snapshot.mockResolvedValue(new Uint8Array([1]));
+});
+afterEach(async () => {
+ queryClient.clear();
+ await clearOfflineDocumentContexts();
+});
+
+const expectCachedOpen = async (
+ opening: ReturnType<typeof fetchSyncDocumentOpenContext>
+) => {
+ const result = await opening;
+ expect(result.isOk()).toBe(true);
+ expect(result._unsafeUnwrap().fromCache).toBe(true);
+ expect(mocks.bundle).not.toHaveBeenCalled();
+ expect(mocks.location).not.toHaveBeenCalled();
+};
+
+describe('native document identity bootstrap', () => {
+ it('waits for identity restoration without waiting for a stalled auth fetch', async () => {
+ const restored = Promise.withResolvers<PersistedQueryEntry | undefined>();
+ mocks.restore.mockReturnValue(restored.promise);
+ void queryClient.prefetchQuery({
+ queryKey: authKeys.userInfo.queryKey,
+ queryFn: () => new Promise(() => {}),
+ });
+ const opening = fetchSyncDocumentOpenContext('doc-1');
+ expect(mocks.snapshot).not.toHaveBeenCalled();
+ restored.resolve(entry);
+ await expectCachedOpen(opening);
+ expect(mocks.restore).toHaveBeenCalledOnce();
+ expect(mocks.userInfo).not.toHaveBeenCalled();
+ expect(
+ queryClient.getQueryState(authKeys.userInfo.queryKey)?.fetchStatus
+ ).toBe('fetching');
+ });
+
+ it('starts identity restoration even when no user-info observer has mounted', async () => {
+ mocks.restore.mockResolvedValue(entry);
+ await expectCachedOpen(fetchSyncDocumentOpenContext('doc-1'));
+ expect(mocks.userInfo).not.toHaveBeenCalled();
+ });
+
+ it.each(['missing', 'unreadable'] as const)(
+ 'fetches identity when persistence is %s',
+ async (state) => {
+ if (state === 'unreadable')
+ mocks.restore.mockRejectedValue(new Error('IDB unavailable'));
+ else mocks.restore.mockResolvedValue(undefined);
+ mocks.userInfo.mockResolvedValue(ok(identity));
+ await expectCachedOpen(fetchSyncDocumentOpenContext('doc-1'));
+ expect(mocks.userInfo).toHaveBeenCalledOnce();
+ }
+ );
+
+ it('does not publish a persisted logout stub or clear a new login cookie before fetching identity', async () => {
+ const signedOut = { id: '', authenticated: false };
+ const userInfo = ok(identity);
+ const response = Promise.withResolvers<typeof userInfo>();
+ mocks.restore.mockResolvedValue({ ...entry, data: signedOut });
+ mocks.userInfo.mockReturnValue(response.promise);
+ const restoredSignOut = vi.fn();
+ // Model Root's useSyncLoginCookie: a successful signed-out query result
+ // clears the cookie even if that result came from IDB, not the server.
+ const stop = queryClient.getQueryCache().subscribe(({ query }) => {
+ if (
+ query.queryHash === entry.queryHash &&
+ query.state.status === 'success' &&
+ queryClient.getQueryData<typeof signedOut>(authKeys.userInfo.queryKey)
+ ?.authenticated === false
+ ) {
+ restoredSignOut();
+ mocks.login = false;
+ }
+ });
+ try {
+ const opening = fetchSyncDocumentOpenContext('doc-1');
+ await vi.waitFor(() => expect(mocks.userInfo).toHaveBeenCalledOnce());
+ expect(mocks.login).toBe(true);
+ expect(restoredSignOut).not.toHaveBeenCalled();
+ expect(
+ queryClient.getQueryData(authKeys.userInfo.queryKey)
+ ).toBeUndefined();
+ response.resolve(userInfo);
+ await expectCachedOpen(opening);
+ expect(restoredSignOut).not.toHaveBeenCalled();
+ } finally {
+ stop();
+ response.resolve(userInfo);
+ }
+ });
+
+ it('fetches fresh identity instead of reusing an in-memory logout stub', async () => {
+ queryClient.setQueryData(authKeys.userInfo.queryKey, {
+ id: '',
+ authenticated: false,
+ });
+ mocks.userInfo.mockResolvedValue(ok(identity));
+ await expectCachedOpen(fetchSyncDocumentOpenContext('doc-1'));
+ expect(mocks.userInfo).toHaveBeenCalledOnce();
+ });
+
+ it('replaces an observed logout stub after a new login without clearing its cookie', async () => {
+ const signedOut = { id: '', authenticated: false };
+ const userInfo = ok(identity);
+ const response = Promise.withResolvers<typeof userInfo>();
+ mocks.login = false;
+ mocks.userInfo
+ .mockResolvedValueOnce(ok(signedOut))
+ .mockReturnValue(response.promise);
+ const view = render(() =>
+ createComponent(QueryClientProvider, {
+ client: queryClient,
+ get children() {
+ const query = useUserInfoQuery();
+ createEffect(() => {
+ if (query.isSuccess)
+ mocks.login = query.data.authenticated ?? false;
+ });
+ return null;
+ },
+ })
+ );
+ try {
+ await vi.waitFor(() =>
+ expect(
+ queryClient.getQueryState(authKeys.userInfo.queryKey)?.fetchStatus
+ ).toBe('idle')
+ );
+ expect(queryClient.getQueryData(authKeys.userInfo.queryKey)).toEqual(
+ signedOut
+ );
+ mocks.login = true;
+ const opening = fetchSyncDocumentOpenContext('doc-1');
+ await vi.waitFor(() => expect(mocks.userInfo).toHaveBeenCalledTimes(2));
+ expect(mocks.login).toBe(true);
+ response.resolve(userInfo);
+ await expectCachedOpen(opening);
+ } finally {
+ view.unmount();
+ response.resolve(userInfo);
+ }
+ });
+
+ it('fails closed when the fresh auth response confirms sign-out', async () => {
+ const signedOut = { id: '', authenticated: false };
+ mocks.restore.mockResolvedValue({ ...entry, data: signedOut });
+ mocks.userInfo.mockResolvedValue(ok(signedOut));
+ const result = await fetchSyncDocumentOpenContext('doc-1');
+ expect(mocks.userInfo).toHaveBeenCalledOnce();
+ expect(result.isErr()).toBe(true);
+ expect(mocks.snapshot).not.toHaveBeenCalled();
+ expect(queryClient.getQueryData(authKeys.userInfo.queryKey)).toEqual(
+ signedOut
+ );
+ });
+
+ it('keeps the fast path when identity is already available', async () => {
+ queryClient.setQueryData(authKeys.userInfo.queryKey, identity);
+ mocks.restore.mockClear();
+ await expectCachedOpen(fetchSyncDocumentOpenContext('doc-1'));
+ expect(mocks.restore).not.toHaveBeenCalled();
+ expect(mocks.userInfo).not.toHaveBeenCalled();
+ });
+
+ it.each([false, true])(
+ 'fences a load across logout (new login: %s)',
+ async (relogin) => {
+ const restored = Promise.withResolvers<PersistedQueryEntry | undefined>();
+ mocks.restore.mockReturnValue(restored.promise);
+ const opening = fetchSyncDocumentOpenContext('doc-1');
+ mocks.login = false;
+ await clearOfflineDocumentContexts();
+ queryClient.setQueryData(authKeys.userInfo.queryKey, {
+ authenticated: false,
+ });
+ if (relogin) {
+ mocks.login = true;
+ queryClient.setQueryData(authKeys.userInfo.queryKey, {
+ id: 'viewer-b',
+ authenticated: true,
+ });
+ }
+ restored.resolve(entry);
+ expect((await opening)._unsafeUnwrapErr()).toEqual([
+ { code: 'UNAUTHORIZED', message: 'Unauthorized access' },
+ ]);
+ expect(mocks.snapshot).not.toHaveBeenCalled();
+ expect(mocks.bundle).not.toHaveBeenCalled();
+ expect(queryClient.getQueryData(authKeys.userInfo.queryKey)).toEqual(
+ relogin
+ ? { id: 'viewer-b', authenticated: true }
+ : { authenticated: false }
+ );
+ }
+ );
+
+ it('fences a first-login auth request that completes after logout', async () => {
+ const userInfo = ok(identity);
+ const response = Promise.withResolvers<typeof userInfo>();
+ mocks.userInfo.mockReturnValue(response.promise);
+ const opening = fetchSyncDocumentOpenContext('doc-1');
+ await vi.waitFor(() => expect(mocks.userInfo).toHaveBeenCalledOnce());
+ mocks.login = false;
+ await clearOfflineDocumentContexts();
+ queryClient.setQueryData(authKeys.userInfo.queryKey, {
+ authenticated: false,
+ });
+ response.resolve(userInfo);
+ expect((await opening).isErr()).toBe(true);
+ expect(mocks.snapshot).not.toHaveBeenCalled();
+ expect(mocks.bundle).not.toHaveBeenCalled();
+ });
+
+ it('fails closed without a login cookie or a confirmed identity', async () => {
+ mocks.login = false;
+ expect((await fetchSyncDocumentOpenContext('doc-1')).isErr()).toBe(true);
+ expect(mocks.restore).not.toHaveBeenCalled();
+ expect(mocks.userInfo).not.toHaveBeenCalled();
+ mocks.login = true;
+ mocks.userInfo.mockResolvedValue(
+ err([{ code: 'NETWORK_ERROR', message: 'Offline' }])
+ );
+ expect((await fetchSyncDocumentOpenContext('doc-1')).isErr()).toBe(true);
+ expect(mocks.bundle).not.toHaveBeenCalled();
+ expect(mocks.snapshot).not.toHaveBeenCalled();
+ });
+
+ it('preserves the non-native network path without identity hydration', async () => {
+ mocks.native = false;
+ mocks.bundle.mockResolvedValue(freshContext);
+ mocks.location.mockResolvedValue(
+ ok({ type: 'syncServiceContent', content: { state: 'ready' } })
+ );
+ expect(
+ (await fetchSyncDocumentOpenContext('doc-1'))._unsafeUnwrap().fromCache
+ ).toBe(false);
+ expect(mocks.restore).not.toHaveBeenCalled();
+ expect(mocks.userInfo).not.toHaveBeenCalled();
+ });
+});
diff --git a/apps/web/src/lib/queries/storage/documentLoad/sync-document-context.ts b/apps/web/src/lib/queries/storage/documentLoad/sync-document-context.ts
new file mode 100644
index 0000000000..0b0e996e41
--- /dev/null
+++ b/apps/web/src/lib/queries/storage/documentLoad/sync-document-context.ts
@@ -0,0 +1,119 @@
+import { LoadErrors, loadResult } from '@core/block';
+import { isNativeMobilePlatform } from '@core/mobile/isNativeMobilePlatform';
+import {
+ catchToResult,
+ ThrownResultError,
+ throwOnErr,
+} from '@core/util/result';
+import type { RawUpdate } from '@macro-inc/collaboration/collab/shared';
+import {
+ IDBSnapshotStore,
+ LORO_SNAPSHOT_DB_NAME,
+} from '@macro-inc/collaboration/collab/snapshot-store';
+import { z } from 'zod';
+import { prefetchUserInfo } from '../../auth/user-info';
+import { queryClient } from '../../client';
+import {
+ fetchDocumentLocation,
+ waitForDocumentSyncServiceReady,
+} from '../document-location';
+import { authorizedContext } from './authorized-context';
+import {
+ documentLoadQueryOptions,
+ fetchDocumentLoadBundle,
+} from './documentLoadBundle';
+import { documentLoadKeys } from './keys';
+import type { DocumentCacheSession } from './offline-context-cache';
+import {
+ documentSessionEpoch,
+ offlineDocumentContextCache,
+ onDocumentSessionChange,
+} from './offline-context-runtime';
+import {
+ createSyncDocumentContextLoader,
+ type FreshSyncDocumentContext,
+} from './sync-document-context-loader';
+
+const pendingLocation = z.object({
+ type: z.literal('presignedUrl'),
+ content: z.object({ state: z.literal('pending') }),
+});
+const readyLocation = z.object({
+ type: z.literal('syncServiceContent'),
+ content: z.object({ state: z.literal('ready') }),
+});
+
+async function loadRemote(
+ documentId: string,
+ session?: DocumentCacheSession
+): Promise<FreshSyncDocumentContext> {
+ const [bundle, initialLocation] = await Promise.all([
+ session
+ ? queryClient.fetchQuery({
+ ...documentLoadQueryOptions(documentId),
+ queryKey: documentLoadKeys.authorizedBundle(
+ session.userId,
+ session.epoch,
+ documentId
+ ).queryKey,
+ // Authorization must not borrow a token from an earlier connection
+ // or an in-flight request belonging to a different signed-in user.
+ staleTime: 0,
+ })
+ : throwOnErr(() => fetchDocumentLoadBundle(documentId)),
+ throwOnErr(() => fetchDocumentLocation({ documentId })),
+ ]);
+ let location: unknown = initialLocation;
+ if (pendingLocation.safeParse(location).success) {
+ location = await waitForDocumentSyncServiceReady({ documentId });
+ }
+ // Initialization/repair belongs to the backend. Never fabricate readiness
+ // or preserve a presigned URL as an offline authorization credential.
+ if (!readyLocation.safeParse(location).success) {
+ throw new ThrownResultError([
+ {
+ code: 'INVALID',
+ message: 'Document content is not available in sync-service',
+ },
+ ]);
+ }
+ return {
+ syncService: true,
+ ...(session ? authorizedContext(documentId, session, bundle) : bundle),
+ };
+}
+
+const loader = createSyncDocumentContextLoader({
+ cache: offlineDocumentContextCache,
+ loadRemote,
+ async hasLocalSnapshot(documentId) {
+ // Metadata alone must never bootstrap an editable empty document when the
+ // cached body was evicted or never finished persisting.
+ const store = new IDBSnapshotStore<RawUpdate>(
+ LORO_SNAPSHOT_DB_NAME,
+ documentId
+ );
+ try {
+ const snapshot = await store.load();
+ return snapshot !== null && snapshot.byteLength > 0;
+ } catch {
+ return false;
+ }
+ },
+ onSessionChange: onDocumentSessionChange,
+});
+
+/** Open cached native documents before network work; authorize synchronization separately. */
+export async function fetchSyncDocumentOpenContext(documentId: string) {
+ if (isNativeMobilePlatform() && !offlineDocumentContextCache.capture()) {
+ const epoch = documentSessionEpoch();
+ await prefetchUserInfo();
+ if (
+ epoch !== documentSessionEpoch() ||
+ !offlineDocumentContextCache.capture()
+ ) {
+ return LoadErrors.UNAUTHORIZED;
+ }
+ }
+ return loadResult(catchToResult(() => loader.load(documentId)));
+}
diff --git a/apps/web/src/lib/service-clients/service-sync/source/authorization.ts b/apps/web/src/lib/service-clients/service-sync/source/authorization.ts
new file mode 100644
index 0000000000..7df7434e76
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/source/authorization.ts
@@ -0,0 +1,9 @@
+/** Captured document-session authority supplied by the query layer. */
+export type DocumentSyncAuthorization = {
+ /** Never returns a persisted token; every reconnect is freshly authorized. */
+ getToken: () => Promise<string>;
+ isCurrent: () => boolean;
+ /** Fresh grants must permit the edits the cached view allowed. */
+ canWrite: () => boolean;
+ onInvalidated: (listener: () => void) => () => void;
+};
diff --git a/apps/web/src/lib/service-clients/service-sync/source/guarded-source.test.ts b/apps/web/src/lib/service-clients/service-sync/source/guarded-source.test.ts
new file mode 100644
index 0000000000..bc5f863419
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/source/guarded-source.test.ts
@@ -0,0 +1,112 @@
+import {
+ type InitialSync,
+ type LiveSyncSource,
+ SyncSourceStatus,
+} from '@macro-inc/collaboration/collab/source';
+import { okAsync, ResultAsync } from 'neverthrow';
+import { describe, expect, it, vi } from 'vitest';
+import { guardDocumentSyncSource } from './guarded-source';
+
+function setup() {
+ const bytes = new Uint8Array([1]);
+ const initial: InitialSync = { snapshot: bytes, awareness: bytes };
+ let current = true;
+ let writable = true;
+ let invalidate = () => {};
+ const unsubscribe = vi.fn();
+ const source: LiveSyncSource = {
+ documentId: 'doc',
+ status: () => SyncSourceStatus.Connected,
+ listen: vi.fn(() => () => {}),
+ pushUpdate: vi.fn(async () => true),
+ pushAwareness: vi.fn(),
+ registerPeerId: vi.fn(),
+ requestSnapshot: vi.fn(() => okAsync(bytes)),
+ requestUpdatesSince: vi.fn(() => okAsync(bytes)),
+ reconnect: vi.fn(),
+ cleanup: vi.fn(),
+ };
+ const pending = Promise.withResolvers<InitialSync>();
+ const guarded = guardDocumentSyncSource(
+ source,
+ () => ResultAsync.fromSafePromise(pending.promise),
+ {
+ isCurrent: () => current,
+ canWrite: () => writable,
+ getToken: async () => 'test-token',
+ onInvalidated: (listener) => {
+ invalidate = listener;
+ return unsubscribe;
+ },
+ }
+ );
+ return {
+ source,
+ guarded,
+ pending,
+ initial,
+ unsubscribe,
+ revoke() {
+ current = false;
+ invalidate();
+ },
+ readonly() {
+ writable = false;
+ },
+ };
+}
+
+describe('document session source guard', () => {
+ it('blocks writes and closes the source on logout/account switch', async () => {
+ const h = setup();
+ h.revoke();
+ expect(await h.guarded.source.pushUpdate([new Uint8Array([1])])).toBe(
+ false
+ );
+ h.guarded.source.pushAwareness(new Uint8Array([1]));
+ h.guarded.source.registerPeerId(1n);
+ h.guarded.source.reconnect();
+ expect(h.source.pushUpdate).not.toHaveBeenCalled();
+ expect(h.source.pushAwareness).not.toHaveBeenCalled();
+ expect(h.source.registerPeerId).not.toHaveBeenCalled();
+ expect(h.source.reconnect).not.toHaveBeenCalled();
+ expect(h.source.cleanup).toHaveBeenCalledOnce();
+ expect(h.unsubscribe).toHaveBeenCalledOnce();
+ expect(h.guarded.source.status()).toBe(SyncSourceStatus.Disconnected);
+ h.guarded.source.cleanup();
+ expect(h.source.cleanup).toHaveBeenCalledOnce();
+ });
+
+ it('does not release a snapshot completing for a previous session', async () => {
+ const h = setup();
+ const result = h.guarded.doInitialSync();
+ h.revoke();
+ h.pending.resolve(h.initial);
+ expect((await result)._unsafeUnwrapErr().type).toBe('authorization_error');
+ expect(
+ (await h.guarded.source.requestSnapshot())._unsafeUnwrapErr().type
+ ).toBe('authorization_error');
+ expect(h.source.requestSnapshot).not.toHaveBeenCalled();
+ });
+
+ it('keeps queued edits unacknowledged when fresh permissions no longer allow them', async () => {
+ const h = setup();
+ h.readonly();
+ expect(await h.guarded.source.pushUpdate([new Uint8Array([1])])).toBe(
+ false
+ );
+ expect(h.source.pushUpdate).not.toHaveBeenCalled();
+ h.guarded.source.cleanup();
+ });
+
+ it('never places offline edits in the websocket send buffer before reauthorization', async () => {
+ const h = setup();
+ h.source.status = () => SyncSourceStatus.Disconnected;
+ expect(await h.guarded.source.pushUpdate([new Uint8Array([1])])).toBe(
+ false
+ );
+ expect(h.source.pushUpdate).not.toHaveBeenCalled();
+ expect(h.source.reconnect).toHaveBeenCalledOnce();
+ h.guarded.source.cleanup();
+ });
+});
diff --git a/apps/web/src/lib/service-clients/service-sync/source/guarded-source.ts b/apps/web/src/lib/service-clients/service-sync/source/guarded-source.ts
new file mode 100644
index 0000000000..a045b57c09
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/source/guarded-source.ts
@@ -0,0 +1,91 @@
+import {
+ type InitialSync,
+ type LiveSyncSource,
+ type SyncError,
+ SyncSourceStatus,
+} from '@macro-inc/collaboration/collab/source';
+import { errAsync, okAsync, type ResultAsync } from 'neverthrow';
+import type { DocumentSyncAuthorization } from './authorization';
+
+/** Prevent a document source from being reused by a later signed-in session. */
+export function guardDocumentSyncSource(
+ source: LiveSyncSource,
+ initialSync: () => ResultAsync<InitialSync, SyncError>,
+ authorization: DocumentSyncAuthorization
+): {
+ source: LiveSyncSource;
+ doInitialSync: () => ResultAsync<InitialSync, SyncError>;
+} {
+ let disposed = false;
+ let unsubscribe = () => {};
+ const current = () => !disposed && authorization.isCurrent();
+ const cleanup = () => {
+ if (disposed) return;
+ disposed = true;
+ unsubscribe();
+ source.cleanup();
+ };
+ unsubscribe = authorization.onInvalidated(cleanup);
+ if (disposed) unsubscribe();
+
+ function denied<T>(): ResultAsync<T, SyncError> {
+ return errAsync({
+ type: 'authorization_error',
+ reason: 'Document session is no longer authorized',
+ });
+ }
+ function read<T>(
+ operation: () => ResultAsync<T, SyncError>
+ ): ResultAsync<T, SyncError> {
+ if (!current()) {
+ cleanup();
+ return denied();
+ }
+ return operation().andThen((value) =>
+ current() ? okAsync(value) : denied<T>()
+ );
+ }
+
+ return {
+ doInitialSync: () => read(initialSync),
+ source: {
+ documentId: source.documentId,
+ status: () =>
+ current() ? source.status() : SyncSourceStatus.Disconnected,
+ listen: (listener) =>
+ current()
+ ? source.listen((event) => {
+ if (current()) listener(event);
+ })
+ : () => {},
+ pushUpdate: async (updates) => {
+ if (!current()) {
+ cleanup();
+ return false;
+ }
+ if (source.status() !== SyncSourceStatus.Connected) {
+ // User activity can revive an exhausted retry budget, but must not
+ // queue raw edits on a socket awaiting fresh authorization.
+ source.reconnect();
+ return false;
+ }
+ if (!authorization.canWrite()) return false;
+ const acknowledged = await source.pushUpdate(updates);
+ return current() && acknowledged;
+ },
+ pushAwareness: (value) => {
+ if (current()) source.pushAwareness(value);
+ },
+ registerPeerId: (value) => {
+ if (current()) source.registerPeerId(value);
+ },
+ requestSnapshot: () => read(source.requestSnapshot),
+ requestUpdatesSince: (version) =>
+ read(() => source.requestUpdatesSince(version)),
+ reconnect: () => {
+ if (current()) source.reconnect();
+ },
+ cleanup,
+ },
+ };
+}
diff --git a/apps/web/src/lib/service-clients/service-sync/source/helpers.test.ts b/apps/web/src/lib/service-clients/service-sync/source/helpers.test.ts
new file mode 100644
index 0000000000..5f2ee41b5f
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/source/helpers.test.ts
@@ -0,0 +1,99 @@
+import {
+ type UrlResolver,
+ WebsocketBuilder,
+ WebsocketConnectionState,
+} from '@macro-inc/collaboration/websocket';
+import { createWebsocketStateSignal } from '@macro-inc/collaboration/websocket/solid/state-signal';
+import { createRoot } from 'solid-js';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+ socket: vi.fn<(resolver: UrlResolver) => object>(() => ({})),
+}));
+vi.mock('@macro-inc/collaboration/sync-service/socket', () => ({
+ createSyncSocket: mocks.socket,
+}));
+vi.mock('@block-md/observability', () => ({
+ resumeDocumentSpan: () => undefined,
+}));
+vi.mock('@core/constant/servers', () => ({
+ SYNC_SERVICE_HOSTS: { ws: 'wss://sync.test' },
+}));
+vi.mock('@service-storage/client', () => ({ storageServiceClient: {} }));
+
+import {
+ createSyncServiceSocket,
+ createTokenRefreshingSocket,
+} from './helpers';
+
+function resolveUrl() {
+ const resolver = mocks.socket.mock.calls.at(-1)![0];
+ if (typeof resolver !== 'function')
+ throw new Error('Expected lazy URL resolver');
+ return resolver();
+}
+
+beforeEach(() => vi.clearAllMocks());
+
+describe('deferred document authorization', () => {
+ it('reports failed authorization as disconnected rather than waiting for a nonexistent close event', async () => {
+ const { ws, state, dispose } = createRoot((dispose) => {
+ const ws = new WebsocketBuilder(async () => {
+ throw new Error('Offline');
+ }).build();
+ return { ws, state: createWebsocketStateSignal(ws), dispose };
+ });
+ try {
+ await vi.waitFor(() =>
+ expect(state()).toBe(WebsocketConnectionState.Closed)
+ );
+ } finally {
+ ws.close();
+ dispose();
+ }
+ });
+
+ it('never connects without fresh authority or falls back to a previously fetched token', async () => {
+ const getToken = vi
+ .fn<() => Promise<string | undefined>>()
+ .mockRejectedValueOnce(new Error('Offline'))
+ .mockResolvedValueOnce('fresh-token')
+ .mockResolvedValueOnce(undefined);
+ createTokenRefreshingSocket('doc', undefined, getToken);
+ await expect(resolveUrl()).rejects.toThrow('Offline');
+ expect(new URL(await resolveUrl()).searchParams.get('token')).toBe(
+ 'fresh-token'
+ );
+ await expect(resolveUrl()).rejects.toThrow('Unable to authorize');
+ expect(getToken).toHaveBeenCalledTimes(3);
+ });
+
+ it('does not use a supplied initial token for a session-bound source', async () => {
+ const getToken = vi.fn(async () => 'authorized-token');
+ createSyncServiceSocket('doc', 'stale-token', {
+ getToken,
+ isCurrent: () => true,
+ canWrite: () => true,
+ onInvalidated: () => () => {},
+ });
+ expect(new URL(await resolveUrl()).searchParams.get('token')).toBe(
+ 'authorized-token'
+ );
+ expect(getToken).toHaveBeenCalledOnce();
+ });
+
+ it('preserves the existing initial-token path for other callers', async () => {
+ const getToken = vi
+ .fn<() => Promise<string | undefined>>()
+ .mockResolvedValue(undefined);
+ createTokenRefreshingSocket('doc', 'initial-token', getToken);
+ expect(new URL(await resolveUrl()).searchParams.get('token')).toBe(
+ 'initial-token'
+ );
+ expect(getToken).not.toHaveBeenCalled();
+ expect(new URL(await resolveUrl()).searchParams.get('token')).toBe(
+ 'initial-token'
+ );
+ expect(getToken).toHaveBeenCalledOnce();
+ });
+});
diff --git a/apps/web/src/lib/service-clients/service-sync/source/helpers.ts b/apps/web/src/lib/service-clients/service-sync/source/helpers.ts
index fb03b14042..4e671cc8df 100644
--- a/apps/web/src/lib/service-clients/service-sync/source/helpers.ts
+++ b/apps/web/src/lib/service-clients/service-sync/source/helpers.ts
@@ -3,6 +3,7 @@ import { SYNC_SERVICE_HOSTS } from '@core/constant/servers';
import type {
InitialSync,
LiveSyncSource,
+ SyncError,
TimeoutError,
} from '@macro-inc/collaboration/collab/source';
import {
@@ -17,6 +18,8 @@ import type { UrlResolver } from '@macro-inc/collaboration/websocket';
import { createWebsocketStateSignal } from '@macro-inc/collaboration/websocket/solid/state-signal';
import { storageServiceClient } from '@service-storage/client';
import type { ResultAsync } from 'neverthrow';
+import type { DocumentSyncAuthorization } from './authorization';
+import { guardDocumentSyncSource } from './guarded-source';
const SYNC_SERVICE_WS_URL = `${SYNC_SERVICE_HOSTS['ws']}/document`;
@@ -32,7 +35,7 @@ type GetToken = () => Promise<string | undefined>;
*/
export function createTokenRefreshingSocket(
documentId: string,
- initialToken: string,
+ initialToken: string | undefined,
getToken: GetToken,
traceparent?: () => string | undefined
): SyncWebsocket {
@@ -44,8 +47,11 @@ export function createTokenRefreshingSocket(
const trace = traceparent?.();
return trace ? `${url}&traceparent=${encodeURIComponent(trace)}` : url;
};
- let initialUrl: string | undefined = connectUrl(initialToken);
+ let initialUrl = initialToken ? connectUrl(initialToken) : undefined;
let fallbackUrl = initialUrl;
+ // A cached document has no initial credential. Require fresh authorization
+ // for every connection; never turn an offline open into stale-token replay.
+ const allowFallback = initialUrl !== undefined;
const getUrl: UrlResolver = async () => {
if (initialUrl) {
@@ -56,8 +62,8 @@ export function createTokenRefreshingSocket(
const token = await getToken();
if (!token) {
- console.error('failed to fetch sync connection token');
- return fallbackUrl;
+ if (allowFallback && fallbackUrl) return fallbackUrl;
+ throw new Error('Unable to authorize sync connection');
}
const refreshedUrl = connectUrl(token);
@@ -75,39 +81,44 @@ export function createTokenRefreshingSocket(
*/
export function createSyncServiceSocket(
documentId: string,
- initialToken: string
+ initialToken: string | undefined,
+ authorization?: DocumentSyncAuthorization
): SyncWebsocket {
return createTokenRefreshingSocket(
documentId,
- initialToken,
- async () => {
- const response =
- await storageServiceClient.permissionsTokens.createPermissionToken({
- document_id: documentId,
- });
- if (response.isErr()) {
- console.error('failed to fetch permission token', response);
- return undefined;
- }
- return response.value.token;
- },
+ authorization ? undefined : initialToken,
+ authorization?.getToken ??
+ (async () => {
+ const response =
+ await storageServiceClient.permissionsTokens.createPermissionToken({
+ document_id: documentId,
+ });
+ if (response.isErr()) {
+ console.error('failed to fetch permission token', response);
+ return undefined;
+ }
+ return response.value.token;
+ }),
() => resumeDocumentSpan(documentId)?.traceparent()
);
}
export const createSyncServiceSource = (
documentId: string,
- token: string
+ token: string | undefined,
+ authorization?: DocumentSyncAuthorization
): {
source: LiveSyncSource;
- doInitialSync: () => ResultAsync<InitialSync, TimeoutError>;
+ doInitialSync: () => ResultAsync<InitialSync, SyncError>;
} => {
- const ws = createSyncServiceSocket(documentId, token);
+ const ws = createSyncServiceSocket(documentId, token, authorization);
const state = createWebsocketStateSignal(ws);
const source = new SyncServiceSource(ws, documentId, {
status: () => mapToSyncStatus(state()),
});
- return { source, doInitialSync: source.doInitialSync };
+ return authorization
+ ? guardDocumentSyncSource(source, source.doInitialSync, authorization)
+ : { source, doInitialSync: source.doInitialSync };
};
/**
diff --git a/apps/web/tauri/Cargo.toml b/apps/web/tauri/Cargo.toml
index 129a1b5e89..60e5cb6867 100644
--- a/apps/web/tauri/Cargo.toml
+++ b/apps/web/tauri/Cargo.toml
@@ -16,6 +16,13 @@ members = [
package.edition = "2024"
resolver = "2"
+# Run the latency-critical SQL VM like production while keeping the app and
+# cache adapters debuggable. Turso's debug-only per-cell validation makes large
+# read-only temporary sets orders of magnitude slower than release execution.
+[profile.dev.package.turso_core]
+opt-level = 3
+debug-assertions = false
+
[workspace.dependencies]
pollster = "0.4"
reqwest = "0.13"
diff --git a/apps/web/tauri/src-tauri/README.md b/apps/web/tauri/src-tauri/README.md
index 2f7dde9712..f47e9442c0 100644
--- a/apps/web/tauri/src-tauri/README.md
+++ b/apps/web/tauri/src-tauri/README.md
@@ -32,6 +32,14 @@ focused diagnostic, not startup/performance measurements. Persistent-cache start
and explicit integrity checks are described in the
[cache guide](../../../../crates/client/README.md#startup-and-integrity-checks).
+The native workspace also optimizes the `turso_core` dependency in Debug builds
+and disables only that dependency's internal debug assertions. Its per-cell B-tree
+validation otherwise makes large read-only filter queries unrepresentative of
+release execution. The app and cache adapters remain debuggable, and their schema,
+codec, scope, and queued-write validation is unchanged. Root-workspace storage tests
+still exercise the ordinary Debug VM; native integration tests exercise this
+optimized dependency profile.
+
## iOS 27 scene lifecycle
Apps built with the iOS 27 SDK must use the scene lifecycle. Keep the
diff --git a/bun.lock b/bun.lock
index f2a43e5612..1bb5d9d046 100644
--- a/bun.lock
+++ b/bun.lock
@@ -102,6 +102,7 @@
"exceljs": "4.4.0",
"fflate": "0.8.3",
"graphql-ws": "^6.1.0",
+ "jose": "^6.2.12",
"katex": "^0.16.22",
"lexical": "0.45.0",
"libheif-js": "^1.19.8",
@@ -161,6 +162,7 @@
"bebop": "3.1.3",
"bebop-tools": "3.1.3",
"concurrently": "^9.2.1",
+ "fake-indexeddb": "^6.2.5",
"graphql": "^16.9.0",
"jsdom": "^26.1.0",
"json-refs": "^3.0.15",
@@ -2291,6 +2293,8 @@
"extract-zip": ["[email protected]", "", { "dependencies": { "debug": "^4.1.1", "get-stream": "^5.1.0", "yauzl": "^2.10.0" }, "optionalDependencies": { "@types/yauzl": "^2.9.1" }, "bin": { "extract-zip": "cli.js" } }, "sha512-GDhU9ntwuKyGXdZBUgTIe+vXnWj0fppUEtMDL0+idd5Sta8TGpHssn/eusA9mrPr9qNDym6SxAYZjNvCn/9RBg=="],
+ "fake-indexeddb": ["[email protected]", "", {}, "sha512-CGnyrvbhPlWYMngksqrSSUT1BAVP49dZocrHuK0SvtR0D5TMs5wP0o3j7jexDJW01KSadjBp1M/71o/KR3nD1w=="],
+
"fast-check": ["[email protected]", "", { "dependencies": { "pure-rand": "^8.0.0" } }, "sha512-7ms6T7SybUev/PQITciI0yLM2pOSFy5zpG8Ty7tQofcVaQUvrMXp6CBwqF6fThLCLOrfBtuHAtwq6Yu4XPCllg=="],
"fast-csv": ["[email protected]", "", { "dependencies": { "@fast-csv/format": "4.3.5", "@fast-csv/parse": "4.3.6" } }, "sha512-2RNSpuwwsJGP0frGsOmTb9oUF+VkFSM4SyLTDgwf2ciHWTarN0lQTC+F2f/t5J9QjW+c65VFIAAu85GsvMIusw=="],
@@ -2631,7 +2635,7 @@
"jiti": ["[email protected]", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ=="],
- "jose": ["[email protected]", "", {}, "sha512-YYVDInQKFJfR/xa3ojUTl8c2KoTwiL1R5Wg9YCydwH0x0B9grbzlg5HC7mMjCtUJjbQ/YnGEZIhI5tCgfTb4Hw=="],
+ "jose": ["[email protected]", "", {}, "sha512-9NiFmJEex0sy2Dk58j2UGBSHgUs2ypF9eZSu4L6vjOX3Dp96Sw1F3uL+H+D1sx02jZZdzUT0HgvCy59CuvXcWw=="],
"js-tokens": ["[email protected]", "", {}, "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ=="],
@@ -4003,6 +4007,8 @@
"livekit-client/@livekit/protocol": ["@livekit/[email protected]", "", { "dependencies": { "@bufbuild/protobuf": "^1.10.0" } }, "sha512-L1uggNQAqyY21smQY8AllyOYbcv9Me9TaxwuLytL1R8ck9nbYPmQLNwEDi3pOFGAMa5F8I2nUi2Jc59W5awxlA=="],
+ "livekit-client/jose": ["[email protected]", "", {}, "sha512-YYVDInQKFJfR/xa3ojUTl8c2KoTwiL1R5Wg9YCydwH0x0B9grbzlg5HC7mMjCtUJjbQ/YnGEZIhI5tCgfTb4Hw=="],
+
"locate-app/type-fest": ["[email protected]", "", {}, "sha512-OduNjVJsFbifKb57UqZ2EMP1i4u64Xwow3NYXUtBbD4vIwJdQd4+xl8YDou1dlm4DVrtwT/7Ky8z8WyCULVfxw=="],
"log-update/ansi-escapes": ["[email protected]", "", { "dependencies": { "environment": "^1.0.0" } }, "sha512-BvU8nYgGQBxcmMuEeUEmNTvrMVjJNSH7RgW24vXexN4Ven6qCvy4TntnvlnwnMLTVlcRQQdbRY8NKnaIoeWDNg=="],
diff --git a/crates/client/README.md b/crates/client/README.md
index 16d20787ab..13a551a916 100644
--- a/crates/client/README.md
+++ b/crates/client/README.md
@@ -31,6 +31,33 @@ scheduled automatically in the background. Failures latch the existing storage
health state without deleting records or pending mutations. Recovery/reset remains
an explicit caller decision after closing the storage.
+## Network refreshes
+
+Normalized refreshes persist only records whose merged contents changed. The hot
+tier is published after the atomic storage write succeeds, so failed writes cannot
+make retries incorrectly look unchanged. With no optimistic layers, the changed
+record keys also identify visible changes without duplicate before/after snapshots.
+Pending layers still use full effective-view comparison and rebasing.
+
+## Projection refreshes
+
+Hydration folds authoritative index mutations in order and writes only final
+states that differ from stored state. An updated normalized record does not force
+unchanged index facts to be deleted and reinserted. Pending optimistic projections
+are still rebased for every affected key, even when authority is unchanged.
+
+## Local filter execution
+
+Local SQL materializes Boolean result sets once, but enumerates a universe only
+within the requested profile and partition. Empty predicates do not enumerate
+cached documents. Conjunctions with an indexable positive term filter one scoped
+candidate set using document-leading fact probes, rather than materializing every
+residual posting list. Other negated conjunctions use set difference instead of
+first building a full complement. Optimistic facts also use document-leading
+primary-key probes rather than repeatedly scanning the materialized shadow set.
+These execution choices keep the same predicate, ordering, missing-fact, and
+shadow-suppression semantics.
+
## Tests
Run from the repository root:
diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rs
index b92ea2566f..9aca1f567f 100644
--- a/crates/client/cache-core/src/engine.rs
+++ b/crates/client/cache-core/src/engine.rs
@@ -1104,10 +1104,18 @@ impl<S: Storage> Engine<S> {
}
}
- let mut candidates = layer_keys(&self.optimistic);
- candidates.extend(updates.keys().cloned());
- let bases_before = self.load_bases(&candidates).await?;
- let before = effective_records(&bases_before, &self.optimistic, &candidates);
+ // Without optimistic layers, durable changes are exactly the visible
+ // changes. Avoid loading/cloning the whole batch again on both sides
+ // of an ordinary network refresh.
+ let optimistic_before = if self.optimistic.is_empty() {
+ None
+ } else {
+ let mut candidates = layer_keys(&self.optimistic);
+ candidates.extend(updates.keys().cloned());
+ let bases = self.load_bases(&candidates).await?;
+ let before = effective_records(&bases, &self.optimistic, &candidates);
+ Some((candidates, before))
+ };
let (changed, mut revision, mut revision_advanced) =
self.persist_updates(updates, projections).await?;
if reset && !revision_advanced {
@@ -1115,7 +1123,7 @@ impl<S: Storage> Engine<S> {
revision_advanced = true;
}
- if !self.optimistic.is_empty() {
+ let visible_changed = if let Some((mut candidates, before)) = optimistic_before {
let queued = self
.storage
.load_mutation_queue()
@@ -1123,13 +1131,15 @@ impl<S: Storage> Engine<S> {
.map_err(EngineError::Storage)?;
self.optimistic = self.rebuild_queued_layers(queued).await?;
candidates.extend(layer_keys(&self.optimistic));
- }
- let bases_after = self.load_bases(&candidates).await?;
- let after = effective_records(&bases_after, &self.optimistic, &candidates);
- let visible_changed: BTreeSet<EntityKey<'static>> = candidates
- .into_iter()
- .filter(|key| before.get(key) != after.get(key))
- .collect();
+ let bases_after = self.load_bases(&candidates).await?;
+ let after = effective_records(&bases_after, &self.optimistic, &candidates);
+ candidates
+ .into_iter()
+ .filter(|key| before.get(key) != after.get(key))
+ .collect()
+ } else {
+ changed.clone()
+ };
let mut affected_ops = if reset {
// Everything anyone had cached is gone: re-execute all ops.
@@ -1262,35 +1272,32 @@ impl<S: Storage> Engine<S> {
let mut changed = BTreeSet::new();
let mut to_persist: Vec<(EntityKey<'static>, Record)> = Vec::new();
+ let mut touched = Vec::with_capacity(updates.len());
for (key, update) in updates {
- let merged = match staging.remove(&key) {
+ let (merged, did_change) = match staging.remove(&key) {
Some(mut existing) => {
- if existing.merge(update) {
- changed.insert(key.clone());
- }
- existing
- }
- None => {
- changed.insert(key.clone());
- update
+ let did_change = existing.merge(update);
+ (existing, did_change)
}
+ None => (update, true),
};
- // Refresh the hot tier (eviction here is harmless: storage gets
- // the fully merged record below).
- self.hot.put(key.clone(), merged.clone());
- to_persist.push((key, merged));
+ if did_change {
+ changed.insert(key.clone());
+ to_persist.push((key.clone(), merged.clone()));
+ }
+ touched.push((key, merged));
}
- // Persist every touched record (idempotent for unchanged ones —
- // keeps storage authoritative even if the hot tier evicted them
- // between loads).
+ // Unchanged bases are already durable, including those fetched after
+ // hot-tier eviction. Still apply every projection mutation: a partial
+ // response can change projection authority without changing records.
let revision_advanced = if changed.is_empty() {
self.projection_mutations_change(&projections).await?
} else {
true
};
self.storage
- .put_batch_with_projections(to_persist.clone(), projections)
+ .put_batch_with_projections(to_persist, projections)
.await
.map_err(EngineError::Storage)?;
let revision = if revision_advanced {
@@ -1298,7 +1305,12 @@ impl<S: Storage> Engine<S> {
} else {
self.revision
};
- self.update_loaded_search_catalogs(&to_persist);
+ // Publish only after the atomic write succeeds. Otherwise a failed
+ // write could poison the hot tier and make its retry look unchanged.
+ self.update_loaded_search_catalogs(&touched);
+ for (key, record) in touched {
+ self.hot.put(key, record);
+ }
Ok((changed, revision, revision_advanced))
}
diff --git a/crates/client/cache-core/src/engine/test.rs b/crates/client/cache-core/src/engine/test.rs
index 69c89cc64e..1b2b8a20e1 100644
--- a/crates/client/cache-core/src/engine/test.rs
+++ b/crates/client/cache-core/src/engine/test.rs
@@ -1,6 +1,37 @@
use super::*;
use crate::store::InMemoryStorage;
+#[test]
+fn ordinary_network_refresh_loads_each_cold_batch_only_once() {
+ pollster::block_on(async {
+ let query = "query Page { user { id soup(input: {limit: 50}) { items { __typename id ... on GraphqlSoupDocument { name } } nextCursor } } }";
+ let data = serde_json::json!({"user": {"id": "viewer", "soup": {
+ "items": (0..12).map(|id| serde_json::json!({
+ "__typename": "GraphqlSoupDocument", "id": id.to_string(), "name": "Cached"
+ })).collect::<Vec<_>>(), "nextCursor": null
+ }}});
+ let variables = serde_json::Map::new();
+ let mut original = Engine::new(InMemoryStorage::new());
+ original
+ .write_query(None, query, Some("Page"), &variables, &data, None)
+ .await
+ .unwrap();
+ let storage = original.into_storage();
+ let before = storage.record_get_count();
+ let mut reopened = Engine::with_capacity(storage, 1);
+ let result = reopened
+ .write_query(None, query, Some("Page"), &variables, &data, None)
+ .await
+ .unwrap();
+ assert!(result.changed.is_empty());
+ assert!(!result.revision_advanced);
+ assert_eq!(reopened.storage().record_get_count() - before, 1);
+ assert!(
+ matches!(reopened.read_query(None, query, Some("Page"), &variables).await.unwrap(), ReadResult::Hit { data: read } if read == data)
+ );
+ });
+}
+
#[test]
fn revision_overflow_is_rejected_without_mutating_storage() {
pollster::block_on(async {
diff --git a/crates/client/cache-turso/src/storage.rs b/crates/client/cache-turso/src/storage.rs
index b6e3a006e2..7771e0abbd 100644
--- a/crates/client/cache-turso/src/storage.rs
+++ b/crates/client/cache-turso/src/storage.rs
@@ -1809,18 +1809,23 @@ fn write_projection_mutations(
.collect::<BTreeSet<_>>()
.into_iter()
.collect::<Vec<_>>();
+ let previous = load_projection_states(connection, &keys)?;
let mut states = keys
.iter()
.cloned()
- .zip(load_projection_states(connection, &keys)?)
+ .zip(previous.iter().cloned())
.filter_map(|(key, state)| state.map(|state| (key, state)))
.collect::<HashMap<_, _>>();
apply_authoritative_projection_mutations(&mut states, &mutations);
- // A snapshot can include many child contributions to the same parent.
- // Preserve mutation order in memory, but persist each final state only once.
- for key in &keys {
- write_projection_state(connection, key, states.get(key))?;
+ // Fold child contributions in order, then persist only changed final states.
+ // Refreshing unchanged authority must not delete/reinsert every index fact
+ // while the native engine lock blocks foreground reads and mutations.
+ for (key, previous) in keys.iter().zip(previous) {
+ let next = states.get(key);
+ if next != previous.as_ref() {
+ write_projection_state(connection, key, next)?;
+ }
}
if !keys.is_empty() {
// Network snapshots and realtime writes must rebase pending member edits
@@ -2576,7 +2581,11 @@ fn compile_predicate_selection(
// Keep every set-algebra CTE materialized. The pinned Turso planner otherwise
// re-enters compound-query coroutines for joined rows, repeatedly evaluating
// the same child sets (millions of VM steps even on a small local corpus).
-// This is generic query execution policy; application predicates remain in IR.
+// Probe optimistic facts by their document-leading primary keys: joining a
+// popular fact to the materialized optimistic set otherwise rescans that set
+// for every matching fact. Conjunctions keep one scoped positive seed and
+// point-probe residual facts instead of materializing every posting list.
+// Application predicates remain unchanged in the IR.
struct SqlPredicateCompiler {
ctes: Vec<String>,
parameters: Vec<Value>,
@@ -2594,11 +2603,9 @@ impl SqlPredicateCompiler {
)
};
Self {
- ctes: vec![
- "authoritative_documents(document_id, record_key, profile, partition) AS MATERIALIZED (SELECT d.id, d.record_key, d.profile, d.partition FROM index_documents AS d WHERE d.state = 0 AND NOT EXISTS (SELECT 1 FROM optimistic_index_documents AS o WHERE o.record_key = d.record_key))".to_owned(),
- format!("optimistic_documents(document_id, record_key, profile, partition) AS MATERIALIZED (SELECT o.id, o.record_key, o.profile, o.partition FROM optimistic_index_documents AS o WHERE o.state = 0{exclusion})"),
- "effective_documents(source, document_id, record_key, profile, partition) AS MATERIALIZED (SELECT 0, document_id, record_key, profile, partition FROM authoritative_documents UNION ALL SELECT 1, document_id, record_key, profile, partition FROM optimistic_documents)".to_owned(),
- ],
+ ctes: vec![format!(
+ "optimistic_documents(document_id, record_key, profile, partition) AS MATERIALIZED (SELECT o.id, o.record_key, o.profile, o.partition FROM optimistic_index_documents AS o WHERE o.state = 0{exclusion})"
+ )],
parameters: excluded_optimistic
.iter()
.copied()
@@ -2615,6 +2622,9 @@ impl SqlPredicateCompiler {
}
fn compile(&mut self, expr: &PredicateExpr, profile: &Profile, partition: &Token) -> String {
+ if let Some((seed, terms)) = conjunction::split(expr) {
+ return self.conjunction(seed, &terms, profile, partition);
+ }
if matches!(expr, PredicateExpr::Or(_, _))
&& let Some((attribute, values)) = alternatives::exact_alternatives(expr)
{
@@ -2625,7 +2635,7 @@ impl SqlPredicateCompiler {
PredicateExpr::None => {
let name = self.next_name();
self.ctes.push(format!(
- "{name}(source, document_id) AS MATERIALIZED (SELECT source, document_id FROM effective_documents WHERE 0)"
+ "{name}(source, document_id) AS MATERIALIZED (SELECT 0, 0 WHERE 0)"
));
name
}
@@ -2640,7 +2650,7 @@ impl SqlPredicateCompiler {
self.parameters.push(text(attribute.as_str()));
}
self.ctes.push(format!(
- "{name}(source, document_id) AS MATERIALIZED (SELECT 0, f.document_id FROM exact_facts AS f JOIN index_documents AS d ON d.id = f.document_id WHERE d.state = 0 AND NOT EXISTS (SELECT 1 FROM optimistic_index_documents AS o WHERE o.record_key = d.record_key) AND d.profile = ? AND d.partition = ? AND f.attribute = ? UNION SELECT 1, f.document_id FROM optimistic_exact_facts AS f JOIN optimistic_documents AS d ON d.document_id = f.document_id WHERE d.profile = ? AND d.partition = ? AND f.attribute = ?)"
+ "{name}(source, document_id) AS MATERIALIZED (SELECT 0, f.document_id FROM exact_facts AS f JOIN index_documents AS d ON d.id = f.document_id WHERE d.state = 0 AND NOT EXISTS (SELECT 1 FROM optimistic_index_documents AS o WHERE o.record_key = d.record_key) AND d.profile = ? AND d.partition = ? AND f.attribute = ? UNION SELECT 1, f.document_id FROM optimistic_documents AS d CROSS JOIN optimistic_exact_facts AS f INDEXED BY sqlite_autoindex_optimistic_exact_facts_1 ON f.document_id = d.document_id WHERE d.profile = ? AND d.partition = ? AND f.attribute = ?)"
));
name
}
@@ -2673,7 +2683,7 @@ impl SqlPredicateCompiler {
}
}
self.ctes.push(format!(
- "{name}(source, document_id) AS MATERIALIZED (SELECT 0, f.document_id FROM integer_facts AS f JOIN index_documents AS d ON d.id = f.document_id WHERE d.state = 0 AND NOT EXISTS (SELECT 1 FROM optimistic_index_documents AS o WHERE o.record_key = d.record_key) AND d.profile = ? AND d.partition = ? AND f.attribute = ?{range} UNION SELECT 1, f.document_id FROM optimistic_integer_facts AS f JOIN optimistic_documents AS d ON d.document_id = f.document_id WHERE d.profile = ? AND d.partition = ? AND f.attribute = ?{range})"
+ "{name}(source, document_id) AS MATERIALIZED (SELECT 0, f.document_id FROM integer_facts AS f JOIN index_documents AS d ON d.id = f.document_id WHERE d.state = 0 AND NOT EXISTS (SELECT 1 FROM optimistic_index_documents AS o WHERE o.record_key = d.record_key) AND d.profile = ? AND d.partition = ? AND f.attribute = ?{range} UNION SELECT 1, f.document_id FROM optimistic_documents AS d CROSS JOIN optimistic_integer_facts AS f INDEXED BY sqlite_autoindex_optimistic_integer_facts_1 ON f.document_id = d.document_id WHERE d.profile = ? AND d.partition = ? AND f.attribute = ?{range})"
));
name
}
@@ -2705,17 +2715,24 @@ impl SqlPredicateCompiler {
text(key.as_str()),
]);
}
- self.ctes.push(format!("{name}(source, document_id) AS MATERIALIZED (SELECT 0, f.document_id FROM sort_facts f JOIN index_documents d ON d.id = f.document_id WHERE d.state = 0 AND NOT EXISTS (SELECT 1 FROM optimistic_index_documents o WHERE o.record_key = d.record_key) AND d.profile = ? AND d.partition = ? AND f.attribute = ? AND (f.value {cmp} ? OR (f.value = ? AND d.record_key {tie} ?)) UNION SELECT 1, f.document_id FROM optimistic_sort_facts f JOIN optimistic_documents d ON d.document_id = f.document_id WHERE d.profile = ? AND d.partition = ? AND f.attribute = ? AND (f.value {cmp} ? OR (f.value = ? AND d.record_key {tie} ?)))"));
+ self.ctes.push(format!("{name}(source, document_id) AS MATERIALIZED (SELECT 0, f.document_id FROM sort_facts f JOIN index_documents d ON d.id = f.document_id WHERE d.state = 0 AND NOT EXISTS (SELECT 1 FROM optimistic_index_documents o WHERE o.record_key = d.record_key) AND d.profile = ? AND d.partition = ? AND f.attribute = ? AND (f.value {cmp} ? OR (f.value = ? AND d.record_key {tie} ?)) UNION SELECT 1, f.document_id FROM optimistic_documents d CROSS JOIN optimistic_sort_facts f INDEXED BY sqlite_autoindex_optimistic_sort_facts_1 ON f.document_id = d.document_id WHERE d.profile = ? AND d.partition = ? AND f.attribute = ? AND (f.value {cmp} ? OR (f.value = ? AND d.record_key {tie} ?)))"));
name
}
PredicateExpr::And(left, right) | PredicateExpr::Or(left, right) => {
+ // Every child set is already confined to this scope. Therefore
+ // A ∩ (U − B) = A − B: do not enumerate U for negated conjuncts.
+ let (left, right, operator) = match (expr, left.as_ref(), right.as_ref()) {
+ (PredicateExpr::And(_, _), left, PredicateExpr::Not(right)) => {
+ (left, right.as_ref(), "EXCEPT")
+ }
+ (PredicateExpr::And(_, _), PredicateExpr::Not(left), right) => {
+ (right, left.as_ref(), "EXCEPT")
+ }
+ (PredicateExpr::And(_, _), left, right) => (left, right, "INTERSECT"),
+ (_, left, right) => (left, right, "UNION"),
+ };
let left = self.compile(left, profile, partition);
let right = self.compile(right, profile, partition);
- let operator = if matches!(expr, PredicateExpr::And(_, _)) {
- "INTERSECT"
- } else {
- "UNION"
- };
let name = self.next_name();
self.ctes.push(format!(
"{name}(source, document_id) AS MATERIALIZED (SELECT source, document_id FROM {left} {operator} SELECT source, document_id FROM {right})"
@@ -2734,6 +2751,38 @@ impl SqlPredicateCompiler {
}
}
+ fn conjunction(
+ &mut self,
+ seed: &PredicateExpr,
+ terms: &[&PredicateExpr],
+ profile: &Profile,
+ partition: &Token,
+ ) -> String {
+ let seed = self.compile(seed, profile, partition);
+ let mut branches = Vec::new();
+ for (source, table, facts) in [
+ (0, "index_documents", conjunction::FactSource::Authority),
+ (
+ 1,
+ "optimistic_index_documents",
+ conjunction::FactSource::Optimistic,
+ ),
+ ] {
+ let condition = terms
+ .iter()
+ .map(|expr| conjunction::condition(expr, facts, &mut self.parameters))
+ .collect::<Vec<_>>()
+ .join(" AND ");
+ branches.push(format!("SELECT {source}, m.document_id FROM {seed} AS m CROSS JOIN {table} AS d ON d.id = m.document_id WHERE m.source = {source} AND ({condition})"));
+ }
+ let name = self.next_name();
+ self.ctes.push(format!(
+ "{name}(source, document_id) AS MATERIALIZED ({})",
+ branches.join(" UNION ALL ")
+ ));
+ name
+ }
+
fn exact(
&mut self,
attribute: &Token,
@@ -2758,17 +2807,22 @@ impl SqlPredicateCompiler {
);
}
self.ctes.push(format!(
- "{name}(source, document_id) AS MATERIALIZED (SELECT 0, f.document_id FROM exact_facts AS f JOIN index_documents AS d ON d.id = f.document_id WHERE d.state = 0 AND NOT EXISTS (SELECT 1 FROM optimistic_index_documents AS o WHERE o.record_key = d.record_key) AND d.profile = ? AND d.partition = ? AND f.attribute = ? AND f.value {condition} UNION SELECT 1, f.document_id FROM optimistic_exact_facts AS f JOIN optimistic_documents AS d ON d.document_id = f.document_id WHERE d.profile = ? AND d.partition = ? AND f.attribute = ? AND f.value {condition})"
+ "{name}(source, document_id) AS MATERIALIZED (SELECT 0, f.document_id FROM exact_facts AS f JOIN index_documents AS d ON d.id = f.document_id WHERE d.state = 0 AND NOT EXISTS (SELECT 1 FROM optimistic_index_documents AS o WHERE o.record_key = d.record_key) AND d.profile = ? AND d.partition = ? AND f.attribute = ? AND f.value {condition} UNION SELECT 1, f.document_id FROM optimistic_documents AS d CROSS JOIN optimistic_exact_facts AS f INDEXED BY sqlite_autoindex_optimistic_exact_facts_1 ON f.document_id = d.document_id WHERE d.profile = ? AND d.partition = ? AND f.attribute = ? AND f.value {condition})"
));
name
}
fn universe(&mut self, profile: &Profile, partition: &Token) -> String {
let name = self.next_name();
- self.parameters.push(text(profile.token().as_str()));
- self.parameters.push(text(partition.as_str()));
+ for _ in 0..2 {
+ self.parameters.push(text(profile.token().as_str()));
+ self.parameters.push(text(partition.as_str()));
+ }
+ // Apply scope before materialization, using the validated scope index.
+ // Any shadow still suppresses authority, including a shadow that moved
+ // outside this scope or whose facts are excluded as uncertain.
self.ctes.push(format!(
- "{name}(source, document_id) AS MATERIALIZED (SELECT source, document_id FROM effective_documents WHERE profile = ? AND partition = ?)"
+ "{name}(source, document_id) AS MATERIALIZED (SELECT 0, d.id FROM index_documents AS d INDEXED BY index_documents_scope_idx WHERE d.profile = ? AND d.partition = ? AND d.state = 0 AND NOT EXISTS (SELECT 1 FROM optimistic_index_documents AS o WHERE o.record_key = d.record_key) UNION ALL SELECT 1, d.document_id FROM optimistic_documents AS d WHERE d.profile = ? AND d.partition = ?)"
));
name
}
@@ -4779,6 +4833,7 @@ impl TursoStorage {
}
mod alternatives;
+mod conjunction;
mod integrity;
#[cfg(all(test, target_arch = "wasm32"))]
diff --git a/crates/client/cache-turso/src/storage/conjunction.rs b/crates/client/cache-turso/src/storage/conjunction.rs
new file mode 100644
index 0000000000..bda6850ccd
--- /dev/null
+++ b/crates/client/cache-turso/src/storage/conjunction.rs
@@ -0,0 +1,185 @@
+//! Point-probed residual predicates for a scoped, already-selected candidate set.
+
+use super::*;
+
+#[derive(Clone, Copy)]
+pub(super) enum FactSource {
+ Authority,
+ Optimistic,
+}
+
+#[derive(Clone, Copy)]
+enum FactKind {
+ Exact,
+ Integer,
+ Sort,
+}
+
+impl FactSource {
+ fn table(self, kind: FactKind) -> (&'static str, &'static str) {
+ match (self, kind) {
+ (Self::Authority, FactKind::Exact) => ("exact_facts", "sqlite_autoindex_exact_facts_1"),
+ (Self::Authority, FactKind::Integer) => {
+ ("integer_facts", "sqlite_autoindex_integer_facts_1")
+ }
+ (Self::Authority, FactKind::Sort) => ("sort_facts", "sqlite_autoindex_sort_facts_1"),
+ (Self::Optimistic, FactKind::Exact) => (
+ "optimistic_exact_facts",
+ "sqlite_autoindex_optimistic_exact_facts_1",
+ ),
+ (Self::Optimistic, FactKind::Integer) => (
+ "optimistic_integer_facts",
+ "sqlite_autoindex_optimistic_integer_facts_1",
+ ),
+ (Self::Optimistic, FactKind::Sort) => (
+ "optimistic_sort_facts",
+ "sqlite_autoindex_optimistic_sort_facts_1",
+ ),
+ }
+ }
+}
+
+/// Keep an indexable positive conjunct as the seed. Negation must not seed an
+/// unscoped universe; the remaining tests only inspect the selected documents.
+pub(super) fn split(expr: &PredicateExpr) -> Option<(&PredicateExpr, Vec<&PredicateExpr>)> {
+ if !matches!(expr, PredicateExpr::And(_, _)) {
+ return None;
+ }
+ fn flatten<'a>(expr: &'a PredicateExpr, terms: &mut Vec<&'a PredicateExpr>) {
+ match expr {
+ PredicateExpr::And(left, right) => {
+ flatten(left, terms);
+ flatten(right, terms);
+ }
+ _ => terms.push(expr),
+ }
+ }
+ let mut terms = Vec::new();
+ flatten(expr, &mut terms);
+ let index = terms.iter().position(|term| match term {
+ PredicateExpr::Exact { .. }
+ | PredicateExpr::ExactExists { .. }
+ | PredicateExpr::I64Range { .. }
+ | PredicateExpr::After { .. } => true,
+ PredicateExpr::Or(_, _) => alternatives::exact_alternatives(term).is_some(),
+ _ => false,
+ })?;
+ let seed = terms.remove(index);
+ Some((seed, terms))
+}
+
+fn exists(
+ source: FactSource,
+ kind: FactKind,
+ attribute: &Token,
+ condition: &str,
+ values: impl IntoIterator<Item = Value>,
+ parameters: &mut Vec<Value>,
+) -> String {
+ parameters.push(text(attribute.as_str()));
+ parameters.extend(values);
+ let (table, index) = source.table(kind);
+ format!(
+ "EXISTS (SELECT 1 FROM {table} AS f INDEXED BY {index} WHERE f.document_id = d.id AND f.attribute = ?{condition})"
+ )
+}
+
+pub(super) fn condition(
+ expr: &PredicateExpr,
+ source: FactSource,
+ parameters: &mut Vec<Value>,
+) -> String {
+ if matches!(expr, PredicateExpr::Or(_, _))
+ && let Some((attribute, values)) = alternatives::exact_alternatives(expr)
+ {
+ return exists(
+ source,
+ FactKind::Exact,
+ attribute,
+ &format!(" AND f.value IN ({})", vec!["?"; values.len()].join(", ")),
+ values
+ .iter()
+ .map(|value| Value::from_blob(value.as_bytes().to_vec())),
+ parameters,
+ );
+ }
+ match expr {
+ PredicateExpr::All => "1".into(),
+ PredicateExpr::None => "0".into(),
+ PredicateExpr::Exact { attribute, value } => exists(
+ source,
+ FactKind::Exact,
+ attribute,
+ " AND f.value = ?",
+ [Value::from_blob(value.as_bytes().to_vec())],
+ parameters,
+ ),
+ PredicateExpr::ExactExists { attribute } => {
+ exists(source, FactKind::Exact, attribute, "", [], parameters)
+ }
+ PredicateExpr::I64Range {
+ attribute,
+ lower,
+ upper,
+ } => {
+ let mut range = String::new();
+ let mut values = Vec::new();
+ for (bound, lower) in [(lower, true), (upper, false)] {
+ if let Some(bound) = bound {
+ let (operator, value) = sql_bound(*bound, lower);
+ range.push_str(&format!(" AND f.value {operator} ?"));
+ values.push(Value::from_i64(value));
+ }
+ }
+ exists(
+ source,
+ FactKind::Integer,
+ attribute,
+ &range,
+ values,
+ parameters,
+ )
+ }
+ PredicateExpr::After {
+ attribute,
+ value,
+ key,
+ direction,
+ tie_direction,
+ } => {
+ let order = if *direction == SortDirection::Asc {
+ ">"
+ } else {
+ "<"
+ };
+ let tie = if *tie_direction == SortDirection::Asc {
+ ">"
+ } else {
+ "<"
+ };
+ exists(
+ source,
+ FactKind::Sort,
+ attribute,
+ &format!(" AND (f.value {order} ? OR (f.value = ? AND d.record_key {tie} ?))"),
+ [
+ Value::from_i64(*value),
+ Value::from_i64(*value),
+ text(key.as_str()),
+ ],
+ parameters,
+ )
+ }
+ PredicateExpr::And(left, right) => format!(
+ "({} AND {})",
+ condition(left, source, parameters),
+ condition(right, source, parameters)
+ ),
+ PredicateExpr::Or(left, right) => format!(
+ "({} OR {})",
+ condition(left, source, parameters),
+ condition(right, source, parameters)
+ ),
+ PredicateExpr::Not(inner) => format!("NOT ({})", condition(inner, source, parameters)),
+ }
+}
diff --git a/crates/client/cache-turso/src/storage/test.rs b/crates/client/cache-turso/src/storage/test.rs
index 79e447c188..9f0cbcb9d6 100644
--- a/crates/client/cache-turso/src/storage/test.rs
+++ b/crates/client/cache-turso/src/storage/test.rs
@@ -1,6 +1,13 @@
use super::*;
+mod conjunction_cost;
+mod conjunction_semantics;
+mod engine_writes;
+mod fact_lookup_cost;
+mod filter_scope_cost;
+mod filter_scope_semantics;
mod predicate_cost;
+mod projection_writes;
mod startup;
use cache_core::normalize::RecordUpdates;
use pollster::block_on;
@@ -2196,19 +2203,16 @@ fn predicate_query_plan_uses_fact_indexes_and_never_scans_record_blobs() {
.any(|detail| detail.contains("exact_facts_lookup_idx")),
"{details:#?}"
);
- assert!(
- details
- .iter()
- .any(|detail| detail.contains("integer_facts_lookup_idx")),
- "{details:#?}"
- );
for index in [
- "optimistic_exact_facts_lookup_idx",
- "optimistic_integer_facts_lookup_idx",
+ "sqlite_autoindex_integer_facts_1",
+ "sqlite_autoindex_optimistic_exact_facts_1",
+ "sqlite_autoindex_optimistic_integer_facts_1",
] {
assert!(
- details.iter().any(|detail| detail.contains(index)),
- "missing {index}: {details:#?}"
+ details.iter().any(|detail| {
+ detail.contains(index) && detail.contains("(document_id=? AND attribute=?")
+ }),
+ "missing document-key fact lookup {index}: {details:#?}"
);
}
for index in [
diff --git a/crates/client/cache-turso/src/storage/test/conjunction_cost.rs b/crates/client/cache-turso/src/storage/test/conjunction_cost.rs
new file mode 100644
index 0000000000..f925c87933
--- /dev/null
+++ b/crates/client/cache-turso/src/storage/test/conjunction_cost.rs
@@ -0,0 +1,78 @@
+use super::*;
+use predicate_index::{ExactValue, IndexQuery, PartitionPredicate};
+
+#[test]
+fn sparse_conjunction_probes_candidates_instead_of_materializing_broad_facts() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("conjunction-probe-cost").unwrap();
+ let token = |value| Token::new(value).unwrap();
+ storage
+ .put_batch_with_projections(
+ Vec::new(),
+ (0..2_000)
+ .map(|n| {
+ let mut document = authoritative_projection(
+ &format!("Thing:{n:05}"),
+ if n < 8 { "selected" } else { "other" },
+ );
+ document.integer_facts.push(predicate_index::IntegerFact {
+ attribute: token("number"),
+ value: n,
+ });
+ ProjectionMutation::Replace(document)
+ })
+ .collect(),
+ )
+ .await
+ .unwrap();
+ let query = ValidatedIndexQuery::new(IndexQuery {
+ profile: Profile::new(token("profile-v1")),
+ partitions: vec![PartitionPredicate {
+ partition: token("thing"),
+ predicate: PredicateExpr::And(
+ Box::new(PredicateExpr::Exact {
+ attribute: token("owner"),
+ value: ExactValue::utf8("selected").unwrap(),
+ }),
+ Box::new(PredicateExpr::And(
+ Box::new(PredicateExpr::ExactExists {
+ attribute: token("server-relation"),
+ }),
+ Box::new(PredicateExpr::And(
+ Box::new(PredicateExpr::I64Range {
+ attribute: token("number"),
+ lower: Some(RangeBound::Inclusive(0)),
+ upper: None,
+ }),
+ Box::new(PredicateExpr::Not(Box::new(PredicateExpr::Exact {
+ attribute: token("owner"),
+ value: ExactValue::utf8("excluded").unwrap(),
+ }))),
+ )),
+ )),
+ ),
+ }],
+ sort_attribute: token("updated-at"),
+ sort_direction: SortDirection::Asc,
+ tie_break_direction: SortDirection::Asc,
+ limit: 100,
+ })
+ .unwrap();
+ let (sql, parameters) = compile_predicate_selection(&query, &[], true);
+ let mut statement = driver::prepare(&storage.connection(), &sql).unwrap();
+ let actual = driver::query_prepared(&mut statement, parameters)
+ .unwrap()
+ .iter()
+ .map(|row| required_text(row, 0).unwrap())
+ .collect::<Vec<_>>();
+ assert_eq!(
+ actual,
+ (0..8).map(|n| format!("Thing:{n:05}")).collect::<Vec<_>>()
+ );
+ let steps = statement.metrics().vm_steps;
+ assert!(
+ steps < 5_000,
+ "eight candidates required {steps} VM steps; residual facts must be point probes"
+ );
+ });
+}
diff --git a/crates/client/cache-turso/src/storage/test/conjunction_semantics.rs b/crates/client/cache-turso/src/storage/test/conjunction_semantics.rs
new file mode 100644
index 0000000000..44abb7341f
--- /dev/null
+++ b/crates/client/cache-turso/src/storage/test/conjunction_semantics.rs
@@ -0,0 +1,216 @@
+use super::*;
+use predicate_index::{ExactValue, IndexQuery, PartitionPredicate, evaluate_reference};
+
+fn token(value: &str) -> Token {
+ Token::new(value).unwrap()
+}
+fn exact(attribute: &str, value: &str) -> PredicateExpr {
+ PredicateExpr::Exact {
+ attribute: token(attribute),
+ value: ExactValue::utf8(value).unwrap(),
+ }
+}
+fn and(left: PredicateExpr, right: PredicateExpr) -> PredicateExpr {
+ PredicateExpr::And(Box::new(left), Box::new(right))
+}
+fn or(left: PredicateExpr, right: PredicateExpr) -> PredicateExpr {
+ PredicateExpr::Or(Box::new(left), Box::new(right))
+}
+fn not(inner: PredicateExpr) -> PredicateExpr {
+ PredicateExpr::Not(Box::new(inner))
+}
+
+fn documents() -> Vec<predicate_index::IndexDocument> {
+ (0..16)
+ .map(|n| {
+ let mut doc = authoritative_projection(
+ &format!("Thing:{n:02}"),
+ if n % 2 == 0 { "selected" } else { "other" },
+ );
+ for (divisor, value) in [(2, "red"), (3, "blue")] {
+ if n % divisor == 0 {
+ doc.exact_facts.push(predicate_index::ExactFact {
+ attribute: token("tag"),
+ value: ExactValue::utf8(value).unwrap(),
+ });
+ }
+ }
+ if n % 4 != 0 {
+ doc.integer_facts.push(predicate_index::IntegerFact {
+ attribute: token("number"),
+ value: if n == 15 { i64::MAX } else { n - 8 },
+ });
+ }
+ doc.sort_facts = if n == 6 {
+ Vec::new()
+ } else {
+ vec![predicate_index::IntegerFact {
+ attribute: token("updated-at"),
+ value: n / 3,
+ }]
+ };
+ doc
+ })
+ .collect()
+}
+
+fn residuals() -> Vec<PredicateExpr> {
+ let range = PredicateExpr::I64Range {
+ attribute: token("number"),
+ lower: Some(RangeBound::Exclusive(-6)),
+ upper: Some(RangeBound::Inclusive(5)),
+ };
+ let exists = PredicateExpr::ExactExists {
+ attribute: token("tag"),
+ };
+ let mut terms = vec![
+ PredicateExpr::All,
+ PredicateExpr::None,
+ exact("tag", "red"),
+ exists.clone(),
+ exact("missing", "no"),
+ not(exists.clone()),
+ not(exact("tag", "red")),
+ and(exact("tag", "red"), exact("tag", "blue")),
+ or(exact("tag", "red"), exact("tag", "blue")),
+ or(exact("tag", "blue"), exact("owner", "other")),
+ range.clone(),
+ not(range.clone()),
+ not(and(exists.clone(), range)),
+ not(not(or(exists, exact("missing", "no")))),
+ PredicateExpr::I64Range {
+ attribute: token("number"),
+ lower: None,
+ upper: None,
+ },
+ PredicateExpr::I64Range {
+ attribute: token("number"),
+ lower: Some(RangeBound::Inclusive(i64::MIN)),
+ upper: Some(RangeBound::Inclusive(i64::MAX)),
+ },
+ ];
+ for direction in [SortDirection::Asc, SortDirection::Desc] {
+ for tie_direction in [SortDirection::Asc, SortDirection::Desc] {
+ terms.push(PredicateExpr::After {
+ attribute: token("updated-at"),
+ value: 2,
+ key: PredicateRecordKey::new("Thing:07").unwrap(),
+ direction,
+ tie_direction,
+ });
+ }
+ }
+ terms
+}
+
+#[test]
+fn fused_conjunctions_match_reference_across_sources_scopes_missing_facts_and_keysets() {
+ block_on(async {
+ for optimistic in [false, true] {
+ let mut storage = TursoStorage::open_in_memory("conjunction-reference").unwrap();
+ let docs = documents();
+ let mut outside_profile = docs[0].clone();
+ outside_profile.record_key = PredicateRecordKey::new("Outside:profile").unwrap();
+ outside_profile.profile = Profile::new(token("other-profile"));
+ let mut outside_partition = docs[0].clone();
+ outside_partition.record_key = PredicateRecordKey::new("Outside:partition").unwrap();
+ outside_partition.partition = token("other-partition");
+ let all = [docs.clone(), vec![outside_profile, outside_partition]].concat();
+ let mut effective = all.clone();
+ storage
+ .put_batch_with_projections(
+ Vec::new(),
+ all.iter()
+ .cloned()
+ .map(ProjectionMutation::Replace)
+ .collect(),
+ )
+ .await
+ .unwrap();
+ if optimistic {
+ let mut shadows = Vec::new();
+ for n in [1_usize, 2, 3, 4, 5, 8] {
+ effective.retain(|doc| doc.record_key != docs[n].record_key);
+ let mut changed = docs[n].clone();
+ changed
+ .exact_facts
+ .retain(|fact| fact.attribute.as_str() != "owner");
+ changed.exact_facts.push(predicate_index::ExactFact {
+ attribute: token("owner"),
+ value: ExactValue::utf8("selected").unwrap(),
+ });
+ if n == 2 {
+ changed.partition = token("other-partition");
+ }
+ if n == 3 {
+ changed.profile = Profile::new(token("other-profile"));
+ }
+ let state = if n == 4 {
+ OptimisticProjectionState::Deleted {
+ record_key: changed.record_key.clone(),
+ profile: changed.profile.clone(),
+ partition: changed.partition.clone(),
+ }
+ } else {
+ OptimisticProjectionState::Complete(changed.clone())
+ };
+ let uncertainty = if n == 8 {
+ OptimisticUncertainty::Attributes([token("owner")].into())
+ } else {
+ OptimisticUncertainty::Attributes(BTreeSet::new())
+ };
+ if n != 4 && n != 8 {
+ effective.push(changed);
+ }
+ shadows.push(PendingOptimisticProjection { state, uncertainty });
+ }
+ let mut created = docs[0].clone();
+ created.record_key = PredicateRecordKey::new("Thing:created").unwrap();
+ effective.push(created.clone());
+ shadows.push(PendingOptimisticProjection {
+ state: OptimisticProjectionState::Complete(created),
+ uncertainty: OptimisticUncertainty::Attributes(BTreeSet::new()),
+ });
+ storage
+ .enqueue_mutation_with_shadow(queued("ConjunctionShadow"), shadows)
+ .await
+ .unwrap();
+ }
+ for residual in residuals() {
+ for commuted in [false, true] {
+ for direction in [SortDirection::Asc, SortDirection::Desc] {
+ for tie_direction in [SortDirection::Asc, SortDirection::Desc] {
+ let seed = exact("owner", "selected");
+ let predicate = if commuted {
+ and(residual.clone(), seed)
+ } else {
+ and(seed, residual.clone())
+ };
+ let query = ValidatedIndexQuery::new(IndexQuery {
+ profile: Profile::new(token("profile-v1")),
+ partitions: vec![PartitionPredicate {
+ partition: token("thing"),
+ predicate,
+ }],
+ sort_attribute: token("updated-at"),
+ sort_direction: direction,
+ tie_break_direction: tie_direction,
+ limit: 7,
+ })
+ .unwrap();
+ let expected = evaluate_reference(&query, &effective)
+ .into_iter()
+ .map(|hit| hit.record_key)
+ .collect::<Vec<_>>();
+ let actual = storage.reconcile_predicate_index(&query, &[]).await.unwrap_or_else(|error| panic!("{error:?}; {residual:?}; optimistic={optimistic}, commuted={commuted}, order={direction:?}/{tie_direction:?}"));
+ assert_eq!(
+ actual.keys, expected,
+ "{residual:?}; optimistic={optimistic}, commuted={commuted}, order={direction:?}/{tie_direction:?}"
+ );
+ }
+ }
+ }
+ }
+ }
+ });
+}
diff --git a/crates/client/cache-turso/src/storage/test/engine_writes.rs b/crates/client/cache-turso/src/storage/test/engine_writes.rs
new file mode 100644
index 0000000000..93a6d25d3c
--- /dev/null
+++ b/crates/client/cache-turso/src/storage/test/engine_writes.rs
@@ -0,0 +1,191 @@
+use super::*;
+use cache_core::engine::{Engine, NetworkWrite, ReadResult};
+use serde_json::{Value as Json, json};
+
+const FULL: &str = "query Full { user { id soup(input: {limit: 50}) { items { __typename id ... on GraphqlSoupDocument { value: name extra: ownerId } } nextCursor } } }";
+const PARTIAL: &str = "query Partial { user { id soup(input: {limit: 50}) { items { __typename id ... on GraphqlSoupDocument { value: name } } nextCursor } } }";
+
+fn page(count: usize) -> Json {
+ json!({"user": {"id": "viewer", "soup": {"items": (0..count).map(|id| json!({
+ "__typename": "GraphqlSoupDocument", "id": id.to_string(), "value": "original",
+ "extra": "owner".repeat(32),
+ })).collect::<Vec<_>>(), "nextCursor": null}}})
+}
+
+async fn assert_page(engine: &mut Engine<TursoStorage>, expected: &Json) {
+ let ReadResult::Hit { data } = engine
+ .read_query(None, FULL, Some("Full"), &serde_json::Map::new())
+ .await
+ .unwrap()
+ else {
+ panic!("expected cached page");
+ };
+ assert_eq!(&data, expected);
+}
+
+#[test]
+fn unchanged_network_records_do_not_write_even_after_hot_eviction() {
+ block_on(async {
+ let storage = TursoStorage::open_in_memory("unchanged-engine-records").unwrap();
+ let mut engine = Engine::with_capacity(storage, 2);
+ let data = page(12);
+ let variables = serde_json::Map::new();
+ engine
+ .write_query(None, FULL, Some("Full"), &variables, &data, None)
+ .await
+ .unwrap();
+ let before = engine.storage().connection().total_changes();
+ let result = engine
+ .write_query(None, FULL, Some("Full"), &variables, &data, None)
+ .await
+ .unwrap();
+ assert!(result.changed.is_empty());
+ assert!(!result.revision_advanced);
+ assert_eq!(engine.storage().connection().total_changes() - before, 0);
+ assert_page(&mut engine, &data).await;
+ });
+}
+
+#[test]
+fn mixed_partial_refresh_writes_only_the_changed_record() {
+ block_on(async {
+ let storage = TursoStorage::open_in_memory("partial-engine-records").unwrap();
+ let mut engine = Engine::with_capacity(storage, 2);
+ let mut full = page(12);
+ let variables = serde_json::Map::new();
+ engine
+ .write_query(None, FULL, Some("Full"), &variables, &full, None)
+ .await
+ .unwrap();
+ full["user"]["soup"]["items"][3]["value"] = json!("updated");
+ let mut partial = full.clone();
+ for node in partial["user"]["soup"]["items"].as_array_mut().unwrap() {
+ node.as_object_mut().unwrap().remove("extra");
+ }
+ let before = engine.storage().connection().total_changes();
+ let result = engine
+ .write_query(None, PARTIAL, Some("Partial"), &variables, &partial, None)
+ .await
+ .unwrap();
+ assert_eq!(result.changed, [key("GraphqlSoupDocument:3")].into());
+ // One normalized record and its compact search document.
+ assert_eq!(engine.storage().connection().total_changes() - before, 2);
+ assert_page(&mut engine, &full).await;
+ let mut reopened = Engine::new(engine.into_storage());
+ assert_page(&mut reopened, &full).await;
+ });
+}
+
+#[test]
+fn failed_refresh_keeps_hot_and_durable_data_old_until_retry_commits() {
+ block_on(async {
+ let storage = TursoStorage::open_in_memory("failed-engine-records").unwrap();
+ let mut engine = Engine::new(storage);
+ let original = page(2);
+ let variables = serde_json::Map::new();
+ engine
+ .write_query(None, FULL, Some("Full"), &variables, &original, None)
+ .await
+ .unwrap();
+ assert_page(&mut engine, &original).await;
+ let revision = engine.current_revision();
+ let mut updated = original.clone();
+ updated["user"]["soup"]["items"][0]["value"] = json!("updated");
+ engine.storage().arm_fault(TestFault::After {
+ site: TestFaultSite::Put,
+ index: 0,
+ });
+ assert!(
+ engine
+ .write_query(None, FULL, Some("Full"), &variables, &updated, None)
+ .await
+ .is_err()
+ );
+ assert_eq!(engine.current_revision(), revision);
+ assert_page(&mut engine, &original).await;
+ let result = engine
+ .write_query(None, FULL, Some("Full"), &variables, &updated, None)
+ .await
+ .unwrap();
+ assert_eq!(result.changed, [key("GraphqlSoupDocument:0")].into());
+ assert!(result.revision_advanced);
+ let mut reopened = Engine::new(engine.into_storage());
+ assert_page(&mut reopened, &updated).await;
+ });
+}
+
+#[test]
+fn failed_initial_write_does_not_publish_uncommitted_hot_records() {
+ block_on(async {
+ let storage = TursoStorage::open_in_memory("failed-initial-engine-records").unwrap();
+ let mut engine = Engine::new(storage);
+ let data = page(2);
+ let variables = serde_json::Map::new();
+ engine.storage().arm_fault(TestFault::After {
+ site: TestFaultSite::Put,
+ index: 0,
+ });
+ assert!(
+ engine
+ .write_query(None, FULL, Some("Full"), &variables, &data, None)
+ .await
+ .is_err()
+ );
+ assert!(matches!(
+ engine
+ .read_query(None, FULL, Some("Full"), &variables)
+ .await
+ .unwrap(),
+ ReadResult::Miss
+ ));
+ engine
+ .write_query(None, FULL, Some("Full"), &variables, &data, None)
+ .await
+ .unwrap();
+ let mut reopened = Engine::new(engine.into_storage());
+ assert_page(&mut reopened, &data).await;
+ });
+}
+
+#[test]
+fn unchanged_records_still_commit_projection_only_changes() {
+ block_on(async {
+ let storage = TursoStorage::open_in_memory("projection-only-engine-records").unwrap();
+ let mut engine = Engine::new(storage);
+ let data = page(2);
+ let variables = serde_json::Map::new();
+ engine
+ .write_query(None, FULL, Some("Full"), &variables, &data, None)
+ .await
+ .unwrap();
+ let projection = authoritative_projection("GraphqlSoupDocument:0", "owner");
+ let result = engine
+ .write_query_with_registration_and_projections(
+ None,
+ None,
+ NetworkWrite {
+ query: FULL,
+ operation_name: Some("Full"),
+ variables: &variables,
+ data: &data,
+ identity: None,
+ },
+ vec![ProjectionMutation::Replace(projection.clone())],
+ )
+ .await
+ .unwrap();
+ assert!(result.changed.is_empty());
+ assert!(result.revision_advanced);
+ assert_eq!(
+ engine
+ .storage()
+ .load_projection_states(
+ &[PredicateRecordKey::new("GraphqlSoupDocument:0").unwrap()]
+ )
+ .await
+ .unwrap(),
+ vec![Some(ProjectionState::Complete(projection))]
+ );
+ assert_page(&mut engine, &data).await;
+ });
+}
diff --git a/crates/client/cache-turso/src/storage/test/fact_lookup_cost.rs b/crates/client/cache-turso/src/storage/test/fact_lookup_cost.rs
new file mode 100644
index 0000000000..55c5cd8370
--- /dev/null
+++ b/crates/client/cache-turso/src/storage/test/fact_lookup_cost.rs
@@ -0,0 +1,101 @@
+use super::*;
+use predicate_index::{ExactValue, IndexQuery, PartitionPredicate};
+
+#[test]
+fn fact_joins_use_document_point_lookups_for_both_sources() {
+ block_on(async {
+ for optimistic in [false, true] {
+ let count = 300_u32;
+ let mut storage = TursoStorage::open_in_memory("fact-lookup-cost").unwrap();
+ let documents = (0..count)
+ .map(|n| {
+ let mut document =
+ authoritative_projection(&format!("Thing:{n:05}"), "owner-1");
+ document.integer_facts.push(predicate_index::IntegerFact {
+ attribute: Token::new("number").unwrap(),
+ value: i64::from(n),
+ });
+ document
+ })
+ .collect::<Vec<_>>();
+ if optimistic {
+ storage
+ .enqueue_mutation_with_shadow(
+ queued("FactLookupCost"),
+ documents
+ .into_iter()
+ .map(|document| PendingOptimisticProjection {
+ state: OptimisticProjectionState::Complete(document),
+ uncertainty: OptimisticUncertainty::Attributes(BTreeSet::new()),
+ })
+ .collect(),
+ )
+ .await
+ .unwrap();
+ } else {
+ storage
+ .put_batch_with_projections(
+ Vec::new(),
+ documents
+ .into_iter()
+ .map(ProjectionMutation::Replace)
+ .collect(),
+ )
+ .await
+ .unwrap();
+ }
+
+ for predicate in [
+ PredicateExpr::Exact {
+ attribute: Token::new("owner").unwrap(),
+ value: ExactValue::utf8("owner-1").unwrap(),
+ },
+ PredicateExpr::ExactExists {
+ attribute: Token::new("owner").unwrap(),
+ },
+ PredicateExpr::I64Range {
+ attribute: Token::new("number").unwrap(),
+ lower: Some(RangeBound::Inclusive(0)),
+ upper: Some(RangeBound::Inclusive(i64::from(count))),
+ },
+ PredicateExpr::After {
+ attribute: Token::new("updated-at").unwrap(),
+ value: 0,
+ key: PredicateRecordKey::new("Thing:00000").unwrap(),
+ direction: SortDirection::Asc,
+ tie_direction: SortDirection::Asc,
+ },
+ ] {
+ let query = ValidatedIndexQuery::new(IndexQuery {
+ profile: Profile::new(Token::new("profile-v1").unwrap()),
+ partitions: vec![PartitionPredicate {
+ partition: Token::new("thing").unwrap(),
+ predicate: predicate.clone(),
+ }],
+ sort_attribute: Token::new("updated-at").unwrap(),
+ sort_direction: SortDirection::Asc,
+ tie_break_direction: SortDirection::Asc,
+ limit: 100,
+ })
+ .unwrap();
+ let (sql, parameters) = compile_predicate_selection(&query, &[], true);
+ let mut statement = driver::prepare(&storage.connection(), &sql).unwrap();
+ let rows = driver::query_prepared(&mut statement, parameters).unwrap();
+ let actual = rows
+ .iter()
+ .map(|row| required_text(row, 0).unwrap())
+ .collect::<Vec<_>>();
+ let expected = (0..100)
+ .map(|n| format!("Thing:{n:05}"))
+ .collect::<Vec<_>>();
+ assert_eq!(actual, expected);
+ let steps = statement.metrics().vm_steps;
+ let budget = u64::from(count) * 300;
+ assert!(
+ steps < budget,
+ "{predicate:?}, optimistic={optimistic}: {steps} steps exceeds {budget}"
+ );
+ }
+ }
+ });
+}
diff --git a/crates/client/cache-turso/src/storage/test/filter_scope_cost.rs b/crates/client/cache-turso/src/storage/test/filter_scope_cost.rs
new file mode 100644
index 0000000000..516f441c40
--- /dev/null
+++ b/crates/client/cache-turso/src/storage/test/filter_scope_cost.rs
@@ -0,0 +1,126 @@
+use super::*;
+use predicate_index::{ExactValue, IndexQuery, PartitionPredicate};
+
+fn query(predicate: PredicateExpr) -> ValidatedIndexQuery {
+ ValidatedIndexQuery::new(IndexQuery {
+ profile: Profile::new(Token::new("profile-v1").unwrap()),
+ partitions: vec![PartitionPredicate {
+ partition: Token::new("thing").unwrap(),
+ predicate,
+ }],
+ sort_attribute: Token::new("updated-at").unwrap(),
+ sort_direction: SortDirection::Asc,
+ tie_break_direction: SortDirection::Asc,
+ limit: 100,
+ })
+ .unwrap()
+}
+
+fn exact_owner(owner: &str) -> PredicateExpr {
+ PredicateExpr::Exact {
+ attribute: Token::new("owner").unwrap(),
+ value: ExactValue::utf8(owner).unwrap(),
+ }
+}
+
+async fn populated_storage() -> TursoStorage {
+ let mut storage = TursoStorage::open_in_memory("filter-scope-cost").unwrap();
+ let mut projections = Vec::new();
+ for n in 0..12 {
+ projections.push(ProjectionMutation::Replace(authoritative_projection(
+ &format!("Thing:{n:04}"),
+ if n % 2 == 0 { "selected" } else { "excluded" },
+ )));
+ }
+ for n in 0..1_000 {
+ let mut document = authoritative_projection(&format!("Other:{n:04}"), "other");
+ if n % 2 == 0 {
+ document.profile = Profile::new(Token::new("other-profile").unwrap());
+ } else {
+ document.partition = Token::new("other-partition").unwrap();
+ }
+ projections.push(ProjectionMutation::Replace(document));
+ }
+ storage
+ .put_batch_with_projections(Vec::new(), projections)
+ .await
+ .unwrap();
+ storage
+}
+
+fn assert_bounded_selection(
+ storage: &TursoStorage,
+ query: &ValidatedIndexQuery,
+ expected: &[String],
+) {
+ let (sql, parameters) = compile_predicate_selection(query, &[], true);
+ let mut statement = driver::prepare(&storage.connection(), &sql).unwrap();
+ let rows = driver::query_prepared(&mut statement, parameters).unwrap();
+ let actual = rows
+ .iter()
+ .map(|row| required_text(row, 0).unwrap())
+ .collect::<Vec<_>>();
+ assert_eq!(actual, expected);
+ let steps = statement.metrics().vm_steps;
+ assert!(
+ steps < 10_000,
+ "selecting twelve scoped records touched unrelated cache rows: {steps} VM steps"
+ );
+}
+
+#[test]
+fn all_and_negated_filters_do_not_materialize_other_scopes() {
+ block_on(async {
+ let storage = populated_storage().await;
+ let all = (0..12).map(|n| format!("Thing:{n:04}")).collect::<Vec<_>>();
+ let selected = (0..12)
+ .filter(|n| n % 2 == 0)
+ .map(|n| format!("Thing:{n:04}"))
+ .collect::<Vec<_>>();
+ assert_bounded_selection(&storage, &query(PredicateExpr::All), &all);
+ assert_bounded_selection(
+ &storage,
+ &query(PredicateExpr::Not(Box::new(exact_owner("excluded")))),
+ &selected,
+ );
+ });
+}
+
+#[test]
+fn negated_conjunctions_and_empty_partitions_stay_scoped() {
+ block_on(async {
+ let storage = populated_storage().await;
+ let selected = (0..12)
+ .filter(|n| n % 2 == 0)
+ .map(|n| format!("Thing:{n:04}"))
+ .collect::<Vec<_>>();
+ for predicate in [
+ PredicateExpr::And(
+ Box::new(exact_owner("selected")),
+ Box::new(PredicateExpr::Not(Box::new(exact_owner("excluded")))),
+ ),
+ PredicateExpr::And(
+ Box::new(PredicateExpr::Not(Box::new(exact_owner("excluded")))),
+ Box::new(exact_owner("selected")),
+ ),
+ PredicateExpr::And(
+ Box::new(PredicateExpr::Not(Box::new(exact_owner("excluded")))),
+ Box::new(PredicateExpr::And(
+ Box::new(PredicateExpr::Not(Box::new(exact_owner("other")))),
+ Box::new(exact_owner("selected")),
+ )),
+ ),
+ ] {
+ let mut descriptor = query(predicate).as_query().clone();
+ descriptor.partitions.push(PartitionPredicate {
+ partition: Token::new("other-partition").unwrap(),
+ predicate: PredicateExpr::None,
+ });
+ assert_bounded_selection(
+ &storage,
+ &ValidatedIndexQuery::new(descriptor).unwrap(),
+ &selected,
+ );
+ }
+ });
+}
diff --git a/crates/client/cache-turso/src/storage/test/filter_scope_semantics.rs b/crates/client/cache-turso/src/storage/test/filter_scope_semantics.rs
new file mode 100644
index 0000000000..041283bcee
--- /dev/null
+++ b/crates/client/cache-turso/src/storage/test/filter_scope_semantics.rs
@@ -0,0 +1,165 @@
+use super::*;
+use predicate_index::{ExactValue, IndexQuery, PartitionPredicate, evaluate_reference};
+
+fn query(predicate: PredicateExpr) -> ValidatedIndexQuery {
+ ValidatedIndexQuery::new(IndexQuery {
+ profile: Profile::new(Token::new("profile-v1").unwrap()),
+ partitions: vec![PartitionPredicate {
+ partition: Token::new("thing").unwrap(),
+ predicate,
+ }],
+ sort_attribute: Token::new("updated-at").unwrap(),
+ sort_direction: SortDirection::Asc,
+ tie_break_direction: SortDirection::Asc,
+ limit: 100,
+ })
+ .unwrap()
+}
+
+fn owner() -> PredicateExpr {
+ PredicateExpr::Exact {
+ attribute: Token::new("owner").unwrap(),
+ value: ExactValue::utf8("selected").unwrap(),
+ }
+}
+
+#[test]
+fn conjunction_rewrites_match_reference_with_nested_negation_and_missing_facts() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("negated-conjunction-truth").unwrap();
+ let mut missing = authoritative_projection("Thing:missing", "selected");
+ missing
+ .exact_facts
+ .retain(|fact| fact.attribute.as_str() != "owner");
+ let documents = vec![
+ authoritative_projection("Thing:selected", "selected"),
+ authoritative_projection("Thing:other", "other"),
+ missing,
+ ];
+ storage
+ .put_batch_with_projections(
+ Vec::new(),
+ documents
+ .iter()
+ .cloned()
+ .map(ProjectionMutation::Replace)
+ .collect(),
+ )
+ .await
+ .unwrap();
+ let terms = [
+ PredicateExpr::All,
+ PredicateExpr::None,
+ owner(),
+ PredicateExpr::Not(Box::new(owner())),
+ PredicateExpr::Not(Box::new(PredicateExpr::Not(Box::new(owner())))),
+ PredicateExpr::ExactExists {
+ attribute: Token::new("owner").unwrap(),
+ },
+ PredicateExpr::Or(Box::new(owner()), Box::new(PredicateExpr::None)),
+ ];
+ for left in &terms {
+ for right in &terms {
+ let query = query(PredicateExpr::And(
+ Box::new(left.clone()),
+ Box::new(right.clone()),
+ ));
+ let expected = evaluate_reference(&query, &documents)
+ .into_iter()
+ .map(|hit| hit.record_key)
+ .collect::<Vec<_>>();
+ let actual = storage
+ .reconcile_predicate_index(&query, &[])
+ .await
+ .unwrap();
+ assert_eq!(actual.keys, expected, "left={left:?}, right={right:?}");
+ }
+ }
+ });
+}
+
+#[test]
+fn empty_predicates_accept_excluded_optimistic_ids_without_selecting_rows() {
+ let storage = TursoStorage::open_in_memory("empty-filter-exclusions").unwrap();
+ let (sql, parameters) = compile_predicate_selection(&query(PredicateExpr::None), &[1, 2], true);
+ assert!(
+ driver::query(&storage.connection(), &sql, parameters)
+ .unwrap()
+ .is_empty()
+ );
+}
+
+#[test]
+fn scoped_universe_never_reveals_authority_hidden_by_moved_or_uncertain_shadows() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("scoped-shadow-suppression").unwrap();
+ let documents = [
+ "kept",
+ "profile-moved",
+ "partition-moved",
+ "deleted",
+ "uncertain",
+ ]
+ .map(|id| authoritative_projection(&format!("Thing:{id}"), "selected"));
+ storage
+ .put_batch_with_projections(
+ Vec::new(),
+ documents
+ .iter()
+ .cloned()
+ .map(ProjectionMutation::Replace)
+ .collect(),
+ )
+ .await
+ .unwrap();
+ let mut profile_moved = documents[1].clone();
+ profile_moved.profile = Profile::new(Token::new("other-profile").unwrap());
+ let mut partition_moved = documents[2].clone();
+ partition_moved.partition = Token::new("other-partition").unwrap();
+ let complete = |document| PendingOptimisticProjection {
+ state: OptimisticProjectionState::Complete(document),
+ uncertainty: OptimisticUncertainty::Attributes(BTreeSet::new()),
+ };
+ storage
+ .enqueue_mutation_with_shadow(
+ queued("ScopeSuppression"),
+ vec![
+ complete(profile_moved),
+ complete(partition_moved),
+ PendingOptimisticProjection {
+ state: OptimisticProjectionState::Deleted {
+ record_key: documents[3].record_key.clone(),
+ profile: documents[3].profile.clone(),
+ partition: documents[3].partition.clone(),
+ },
+ uncertainty: OptimisticUncertainty::Attributes(BTreeSet::new()),
+ },
+ PendingOptimisticProjection {
+ state: OptimisticProjectionState::Complete(documents[4].clone()),
+ uncertainty: OptimisticUncertainty::Attributes(
+ [Token::new("owner").unwrap()].into(),
+ ),
+ },
+ complete(authoritative_projection("Thing:created", "selected")),
+ ],
+ )
+ .await
+ .unwrap();
+ let query = query(PredicateExpr::Not(Box::new(PredicateExpr::Exact {
+ attribute: Token::new("owner").unwrap(),
+ value: ExactValue::utf8("excluded").unwrap(),
+ })));
+ let result = storage
+ .reconcile_predicate_index(&query, &[])
+ .await
+ .unwrap();
+ assert_eq!(
+ result.keys,
+ vec![
+ PredicateRecordKey::new("Thing:created").unwrap(),
+ PredicateRecordKey::new("Thing:kept").unwrap(),
+ ]
+ );
+ assert!(result.optimistic);
+ });
+}
diff --git a/crates/client/cache-turso/src/storage/test/projection_writes.rs b/crates/client/cache-turso/src/storage/test/projection_writes.rs
new file mode 100644
index 0000000000..50404f707b
--- /dev/null
+++ b/crates/client/cache-turso/src/storage/test/projection_writes.rs
@@ -0,0 +1,160 @@
+use super::*;
+
+#[test]
+fn normalized_updates_do_not_rewrite_unchanged_projection_facts() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("unchanged-projection-write").unwrap();
+ let document = authoritative_projection("Thing:1", "owner-1");
+ storage
+ .put_batch_with_projections(
+ vec![(key("Thing:1"), record("before"))],
+ vec![ProjectionMutation::Replace(document.clone())],
+ )
+ .await
+ .unwrap();
+
+ let before = storage.connection().total_changes();
+ storage
+ .put_batch_with_projections(
+ vec![(key("Thing:1"), record("after"))],
+ vec![ProjectionMutation::Replace(document)],
+ )
+ .await
+ .unwrap();
+
+ // Only the normalized record changed. Rewriting its unchanged index
+ // would delete/reinsert every fact while blocking foreground reads.
+ assert_eq!(storage.connection().total_changes() - before, 1);
+ assert_eq!(
+ storage.get_batch(&[key("Thing:1")]).await.unwrap(),
+ vec![Some(record("after"))]
+ );
+ });
+}
+
+#[test]
+fn mixed_projection_batches_write_only_changed_authority() {
+ block_on(async {
+ let mut counts = Vec::new();
+ for include_unchanged in [false, true] {
+ let mut storage = TursoStorage::open_in_memory("mixed-projection-write").unwrap();
+ let unchanged = authoritative_projection("Thing:1", "owner-1");
+ let initial = authoritative_projection("Thing:2", "owner-1");
+ let changed = authoritative_projection("Thing:2", "owner-2");
+ storage
+ .put_batch_with_projections(
+ Vec::new(),
+ vec![
+ ProjectionMutation::Replace(unchanged.clone()),
+ ProjectionMutation::Replace(initial),
+ ],
+ )
+ .await
+ .unwrap();
+
+ let mut mutations = vec![ProjectionMutation::Replace(changed.clone())];
+ if include_unchanged {
+ mutations.push(ProjectionMutation::Replace(unchanged.clone()));
+ }
+ let before = storage.connection().total_changes();
+ storage
+ .put_batch_with_projections(Vec::new(), mutations)
+ .await
+ .unwrap();
+ counts.push(storage.connection().total_changes() - before);
+ assert_eq!(
+ storage
+ .load_projection_states(&[
+ PredicateRecordKey::new("Thing:1").unwrap(),
+ PredicateRecordKey::new("Thing:2").unwrap(),
+ ])
+ .await
+ .unwrap(),
+ vec![
+ Some(ProjectionState::Complete(unchanged)),
+ Some(ProjectionState::Complete(changed)),
+ ]
+ );
+ }
+ assert!(counts[0] > 0);
+ assert_eq!(counts[0], counts[1]);
+ });
+}
+
+#[test]
+fn ordered_mutations_with_unchanged_final_authority_do_not_write_facts() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("folded-projection-write").unwrap();
+ let original = authoritative_projection("Thing:1", "owner-1");
+ storage
+ .put_batch_with_projections(
+ Vec::new(),
+ vec![ProjectionMutation::Replace(original.clone())],
+ )
+ .await
+ .unwrap();
+ let before = storage.connection().total_changes();
+ storage
+ .put_batch_with_projections(
+ Vec::new(),
+ vec![
+ ProjectionMutation::Replace(authoritative_projection("Thing:1", "owner-2")),
+ ProjectionMutation::Replace(original),
+ ],
+ )
+ .await
+ .unwrap();
+ assert_eq!(storage.connection().total_changes(), before);
+ });
+}
+
+#[test]
+fn unchanged_authority_still_rebases_durable_optimistic_intent() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("unchanged-projection-rebase").unwrap();
+ let original = authoritative_projection("Thing:1", "owner-1");
+ let optimistic = authoritative_projection("Thing:1", "owner-2");
+ let projection_key = PredicateRecordKey::new("Thing:1").unwrap();
+ storage
+ .put_batch_with_projections(
+ Vec::new(),
+ vec![ProjectionMutation::Replace(original.clone())],
+ )
+ .await
+ .unwrap();
+
+ let mut mutation = queued("Pending");
+ mutation.optimistic.optimistic_data_json =
+ cache_core::queue::encode_optimistic_source(&cache_core::queue::OptimisticSource {
+ mutation_data: serde_json::json!({}),
+ link_patches: Vec::new(),
+ revalidations: Vec::new(),
+ projection_mutations: vec![predicate_index::OptimisticProjectionMutation::Replace(
+ optimistic.clone(),
+ )],
+ });
+ let owner = storage.enqueue_mutation(mutation).await.unwrap();
+ assert_eq!(
+ storage
+ .load_optimistic_projections(std::slice::from_ref(&projection_key))
+ .await
+ .unwrap(),
+ vec![None]
+ );
+
+ storage
+ .put_batch_with_projections(Vec::new(), vec![ProjectionMutation::Replace(original)])
+ .await
+ .unwrap();
+ let projections = storage
+ .load_optimistic_projections(&[projection_key])
+ .await
+ .unwrap();
+ let shadow = projections[0].as_ref().unwrap();
+ assert_eq!(shadow.owner, owner);
+ assert_eq!(
+ shadow.state,
+ OptimisticProjectionState::Complete(optimistic)
+ );
+ });
+}
diff --git a/docs/AGENT_GUIDE/documents.md b/docs/AGENT_GUIDE/documents.md
index 3a0578afb8..73e98a07ec 100644
--- a/docs/AGENT_GUIDE/documents.md
+++ b/docs/AGENT_GUIDE/documents.md
@@ -333,6 +333,37 @@ check that the inserted company mention points to the correct company. Also chec
searching by domain and that an open picker updates when companies finish hydrating.
Discard unsent test drafts rather than sending them.
+## Native offline reopening
+
+On native mobile, previously opened Markdown documents/tasks can reopen after an
+app restart using their cached body and last-known permissions. Warm the document
+online first, then restart with API traffic blocked: verify the existing body,
+make a disposable edit, and restart offline again to check local recovery.
+Restoring connectivity must reauthorize synchronization before queued edits reach
+the server; verify the server copy, not just the still-cached editor text.
+Also reconnect after the initial sync's 10-second timeout: a reconnect snapshot
+must release queued edits without requiring the document to reopen. A document
+content-readiness timeout is retryable and must not revoke its cached open
+context; explicit access denial still does.
+The body should not wait for unrelated CRM metadata, references, duplicate-task
+suggestions, closed sharing/tag menus, or disabled mention queries. With those
+requests pending, the cached editor remains visible; optional information can
+appear when its own request finishes.
+
+For a cold deep link or restored split, document loading waits for persisted
+user identity before capturing its offline session; a stalled auth request must
+not delay an identity already restored from IndexedDB. If no identity is cached,
+the normal auth query must succeed first. A previous logout marker is not a
+cached identity: after signing in again, it must trigger fresh authentication,
+not clear the new login cookie. Verify this restart/deep-link flow with a
+disposable account. Logout during the identity wait prevents the old load from
+opening under a subsequent login.
+
+Cached open context is scoped to the signed-in user and invalidated at logout;
+permission tokens are never persisted. A missing body snapshot still requires an
+online open—metadata alone must not produce an editable empty document. This path
+does not imply offline coverage for PDFs, attachments, or other binary files.
+
## Reference hover previews
The `@` menu includes `Recent agent sessions` after Channels and before
diff --git a/docs/AGENT_GUIDE/surfaces.md b/docs/AGENT_GUIDE/surfaces.md
index 2154c68b3e..487ec1998b 100644
--- a/docs/AGENT_GUIDE/surfaces.md
+++ b/docs/AGENT_GUIDE/surfaces.md
@@ -388,6 +388,12 @@ scrolls it into view, and briefly highlights it. For navigation regressions,
exercise both a recent message and one outside the first page. Open another
target while loading or highlighting: the previous request must not scroll the
new thread or clear its highlight. Closing the split cancels pending positioning.
+The load gate and message body share one live thread source in both hosts. Cached
+body rendering should not wait for a second thread fetch, optional References,
+or inbox metadata. Inbox-dependent actions stay gated while ownership is unknown;
+explicit inbox IDs must never silently route to primary while links are loading.
+Background refreshes and older-message loading still update the same thread.
+Verify with API traffic delayed and with previously opened bodies offline.
Collapsed thread cards use a compact text snippet; expanding mounts the message
body and its attachments. On phones, messages form flat rows with horizontal
separators and 16px side gutters; collapsed previews show one line. Desktop
@@ -714,6 +720,12 @@ Company and contact headers have `Copy link` beside the side-panel toggle.
It copies the record's direct URL and shows a confirmation toast; this is also
available in the embedded company and contact breadcrumb header.
+Company selection actions **Set owner** and **Set revenue** remain available
+while team deal-stage definitions are loading. **Set stage** waits for the active
+team definition rather than opening an editor with system defaults. Check both
+the entity actions menu and command menu with stage requests delayed; cancel the
+editors without changing hosted data.
+
`Collapse CRM sidebar` persists across visits; `Expand CRM sidebar` restores it.
At narrow widths, `Show CRM navigation` opens the same navigation in a menu.
The sidebar's Views and Lists sections can also collapse independently.
diff --git a/nix-support/node_modules-hashes.json b/nix-support/node_modules-hashes.json
index 973d8e68ed..0ae74a55ce 100644
--- a/nix-support/node_modules-hashes.json
+++ b/nix-support/node_modules-hashes.json
@@ -1,6 +1,6 @@
{
"nodeModules": {
- "x86_64-linux": "sha256-euQs05yQlRl3TE2TunEjX1dvQIAIAL+v16meI7VNa5A=",
- "aarch64-darwin": "sha256-FO99wNeI8e3GYKkNShok27bFcEQxUddMB8VKaCmGck8="
+ "aarch64-darwin": "sha256-bLsAw8kaWMvANGUwfsjPB5xmYjoBUg4l/dbfNJvzESo=",
+ "x86_64-linux": "sha256-pO1HxZJXyW4M7dhVcC8AY7POlqamBxWnI+G97WU/JT4="
}
}
diff --git a/packages/collaboration/src/collab/engine.ts b/packages/collaboration/src/collab/engine.ts
index 85c02921aa..6dbc0ae6c9 100644
--- a/packages/collaboration/src/collab/engine.ts
+++ b/packages/collaboration/src/collab/engine.ts
@@ -27,7 +27,7 @@ import { peerCounterAttr, telemetrySpan } from './telemetry';
// SnapshotStore in the engine is always Loro updates — RawUpdate.
type LoroSnapshotStore = SnapshotStore<RawUpdate>;
-import type { LiveSyncSource, SyncSourceEvent, TimeoutError } from './source';
+import type { LiveSyncSource, SyncError, SyncSourceEvent } from './source';
import type { WALSyncer } from './wal';
const SNAPSHOT_INTERVAL_MS = 5_000;
@@ -64,7 +64,7 @@ export type SyncEngineParams<S extends GenericRootSchema, D> = {
makeChatter?: (documentId: string) => Chatter;
};
-type SnapshotThunk = () => ResultAsync<Uint8Array, TimeoutError>;
+type SnapshotThunk = () => ResultAsync<Uint8Array, SyncError>;
export class SyncEngine<S extends GenericRootSchema, D> {
private _isRunning = false;
@@ -471,7 +471,7 @@ export type ReactiveSyncEngine<S extends GenericRootSchema, D> = {
start: () => void;
stop: () => void;
reset: (
- snapshotThunk?: () => ResultAsync<Uint8Array, TimeoutError>
+ snapshotThunk?: () => ResultAsync<Uint8Array, SyncError>
) => Promise<void>;
syncStateToLoro: (state: InferType<S>) => Promise<void>;
syncAwarenessToLoro: (awareness: D) => void;
diff --git a/packages/collaboration/src/collab/source.ts b/packages/collaboration/src/collab/source.ts
index 968d9fdc76..d115f14cde 100644
--- a/packages/collaboration/src/collab/source.ts
+++ b/packages/collaboration/src/collab/source.ts
@@ -77,8 +77,8 @@ export type LiveSyncSource = {
status: Accessor<SyncSourceStatus>;
requestUpdatesSince: (
version: VersionVector
- ) => ResultAsync<RawUpdate, TimeoutError>;
- requestSnapshot: () => ResultAsync<RawUpdate, TimeoutError>;
+ ) => ResultAsync<RawUpdate, SyncError>;
+ requestSnapshot: () => ResultAsync<RawUpdate, SyncError>;
reconnect: () => void;
cleanup: () => void;
};
diff --git a/packages/collaboration/src/sync-service/source.test.ts b/packages/collaboration/src/sync-service/source.test.ts
index d4cf39c2c4..69a9aaac1e 100644
--- a/packages/collaboration/src/sync-service/source.test.ts
+++ b/packages/collaboration/src/sync-service/source.test.ts
@@ -163,6 +163,81 @@ describe('SyncServiceSource', () => {
expect(ws.heartbeats).toBe(1);
});
+ it('recovers a first sync arriving after offline bootstrap timed out and acknowledges queued edits', async () => {
+ vi.useFakeTimers();
+ const ws = new FakeSocket();
+ const src = new SyncServiceSource(ws, 'doc1', { newId: () => 'late-op' });
+ try {
+ const events: SyncSourceEvent[] = [];
+ src.listen((event) => events.push(event));
+ await vi.advanceTimersByTimeAsync(TIMEOUTS.INITIAL_SYNC + 1);
+ expect((await src.doInitialSync()).isErr()).toBe(true);
+ expect(await src.pushUpdate([snap])).toBe(false);
+ ws.deliver(remote.initialSync(snap, aw));
+ expect(events).toEqual([
+ { type: 'reconnect', snapshot: snap, awareness: aw },
+ ]);
+ expect(ws.heartbeats).toBe(1);
+ const delivered = src.pushUpdate([snap]);
+ ws.deliver(remote.ack('late-op'));
+ expect(await delivered).toBe(true);
+ } finally {
+ src.cleanup();
+ vi.useRealTimers();
+ }
+ });
+
+ it('acknowledges queued edits when a reconnect waiter receives the first sync after bootstrap timed out', async () => {
+ vi.useFakeTimers();
+ const ws = new FakeSocket();
+ const src = new SyncServiceSource(ws, 'doc1', {
+ newId: () => 'reconnect-op',
+ });
+ try {
+ const events: SyncSourceEvent[] = [];
+ src.listen((event) => events.push(event));
+ await vi.advanceTimersByTimeAsync(TIMEOUTS.INITIAL_SYNC + 1);
+ expect((await src.doInitialSync()).isErr()).toBe(true);
+ expect(await src.pushUpdate([snap])).toBe(false);
+
+ ws.fireReconnect();
+ ws.deliver(remote.initialSync(snap, aw));
+ await vi.advanceTimersByTimeAsync(0);
+ expect(events).toEqual([
+ { type: 'reconnect', snapshot: snap, awareness: aw },
+ ]);
+ expect(ws.heartbeats).toBe(1);
+ const delivered = src.pushUpdate([snap]);
+ expect(ws.sent).toHaveLength(1);
+ ws.deliver(remote.ack('reconnect-op'));
+ expect(await delivered).toBe(true);
+ } finally {
+ src.cleanup();
+ vi.useRealTimers();
+ }
+ });
+
+ it('accepts a reconnect snapshot even after its waiter expired', async () => {
+ vi.useFakeTimers();
+ const ws = new FakeSocket();
+ const src = new SyncServiceSource(ws, 'doc1');
+ try {
+ ws.deliver(remote.initialSync(snap, aw));
+ await src.doInitialSync();
+ const events: SyncSourceEvent[] = [];
+ src.listen((event) => events.push(event));
+ ws.fireReconnect();
+ await vi.advanceTimersByTimeAsync(TIMEOUTS.INITIAL_SYNC + 1);
+ ws.deliver(remote.initialSync(snap, aw));
+ expect(events).toEqual([
+ { type: 'reconnect', snapshot: snap, awareness: aw },
+ ]);
+ } finally {
+ src.cleanup();
+ vi.useRealTimers();
+ }
+ });
+
it('maps RemoteUpdate to an update event', () => {
const ws = new FakeSocket();
const src = new SyncServiceSource(ws, 'doc1');
diff --git a/packages/collaboration/src/sync-service/source.ts b/packages/collaboration/src/sync-service/source.ts
index 502ebe80d1..036d908d0f 100644
--- a/packages/collaboration/src/sync-service/source.ts
+++ b/packages/collaboration/src/sync-service/source.ts
@@ -119,7 +119,6 @@ export class SyncServiceSource implements LiveSyncSource {
// `doInitialSync()` just returns the cached promise; if it's called late,
// it still resolves because the listener captured the message.
this.initialSyncPromise = this.awaitInitialSync().map((message) => {
- this.initialSyncReceived = true;
logSyncService({
documentId,
level: 'debug',
@@ -316,10 +315,21 @@ export class SyncServiceSource implements LiveSyncSource {
const message = event.data;
const syncEvent = syncEventForMessage(message);
if (syncEvent) this.emit(syncEvent);
- // Resolve every pending request whose predicate matches this message.
- for (const waiter of [...this.waiters]) {
- if (waiter.match(message)) waiter.resolve(message);
+ const waiting = [...this.waiters].filter((waiter) => waiter.match(message));
+ if (message.isRemoteInitialSync()) this.initialSyncReceived = true;
+ if (message.isRemoteInitialSync() && waiting.length === 0) {
+ // An offline bootstrap (or a slow reconnect) can outlive the initial
+ // waiter. Accept the eventual authorized connection and converge the
+ // locally seeded document instead of permanently blocking WAL replay.
+ this.ws.startHeartbeat();
+ const sync = message.value as InitialSync;
+ this.emit({
+ type: 'reconnect',
+ snapshot: sync.snapshot,
+ awareness: sync.awareness,
+ });
}
+ for (const waiter of waiting) waiter.resolve(message);
};
private onClose: WebsocketEventListener<
diff --git a/packages/collaboration/src/websocket/core/websocket.ts b/packages/collaboration/src/websocket/core/websocket.ts
index e9bcfc73a3..7f7283d064 100644
--- a/packages/collaboration/src/websocket/core/websocket.ts
+++ b/packages/collaboration/src/websocket/core/websocket.ts
@@ -403,6 +403,14 @@ export class Websocket<Send = WebsocketData, Receive = WebsocketData> {
if (this.binaryType !== undefined) {
this._underlyingWebsocket.binaryType = this.binaryType;
}
+ } catch {
+ // URL resolution can require online authorization. No native socket
+ // exists to emit a close event when that fails, so retry it here too.
+ if (!this._closedByUser) {
+ this.connectionState = WebsocketConnectionState.Closed;
+ this.dispatchEvent(WebsocketEvent.Error, new Event('error'));
+ this.scheduleConnectionRetryIfNeeded();
+ }
} finally {
this.connectPending = false;
}
diff --git a/packages/collaboration/src/websocket/solid/state-signal.ts b/packages/collaboration/src/websocket/solid/state-signal.ts
index bd27a57e34..5e3f6ab916 100644
--- a/packages/collaboration/src/websocket/solid/state-signal.ts
+++ b/packages/collaboration/src/websocket/solid/state-signal.ts
@@ -29,7 +29,8 @@ export function createWebsocketStateSignal(
setState(WebsocketConnectionState.Closed);
},
[WebsocketEvent.Error]: () => {
- setState(WebsocketConnectionState.Closing);
+ // URL/authorization failures have no native socket to emit Close.
+ setState(ws.connectionState);
},
[WebsocketEvent.Reconnect]: () => {
setState(WebsocketConnectionState.Reconnecting);
diff --git a/packages/collaboration/src/websocket/tests/websocket-resolver-retry.test.ts b/packages/collaboration/src/websocket/tests/websocket-resolver-retry.test.ts
new file mode 100644
index 0000000000..e8e341b10b
--- /dev/null
+++ b/packages/collaboration/src/websocket/tests/websocket-resolver-retry.test.ts
@@ -0,0 +1,66 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { WebSocketServer } from 'ws';
+import {
+ ConstantBackoff,
+ type Websocket,
+ WebsocketBuilder,
+ WebsocketEvent,
+} from '../';
+import { startServer, stopClient, stopServer } from './websocket-test-utils';
+
+describe('authorization URL resolution failures', () => {
+ let server: WebSocketServer | undefined;
+ let client: Websocket | undefined;
+ let url: string;
+
+ beforeEach(async () => {
+ server = await startServer(0, 5000);
+ const address = server.address();
+ if (!address || typeof address === 'string')
+ throw new Error('No test server address');
+ url = `ws://localhost:${address.port}`;
+ });
+ afterEach(async () => {
+ if (client?.underlyingWebsocket) await stopClient(client, 5000);
+ else client?.close();
+ await stopServer(server, 5000);
+ client = undefined;
+ });
+
+ it('retries rejected token requests without an unhandled rejection or an unauthorized socket', async () => {
+ const resolver = vi
+ .fn<() => Promise<string>>()
+ .mockRejectedValueOnce(new Error('Offline'))
+ .mockRejectedValueOnce(new Error('Offline'))
+ .mockResolvedValue(url);
+ const connections = vi.fn();
+ server!.on('connection', connections);
+ client = new WebsocketBuilder(resolver)
+ .withBackoff(new ConstantBackoff(10))
+ .withMaxRetries(3)
+ .build();
+ const errors = vi.fn();
+ client.addEventListener(WebsocketEvent.Error, errors);
+ await new Promise<void>((resolve) =>
+ client!.addEventListener(WebsocketEvent.Open, () => resolve(), {
+ once: true,
+ })
+ );
+ expect(errors).toHaveBeenCalledTimes(2);
+ expect(resolver).toHaveBeenCalledTimes(3);
+ expect(connections).toHaveBeenCalledOnce();
+ });
+
+ it('does not retry a pending authorization rejected after the source is disposed', async () => {
+ const pending = Promise.withResolvers<string>();
+ const resolver = vi.fn(() => pending.promise);
+ client = new WebsocketBuilder(resolver)
+ .withBackoff(new ConstantBackoff(10))
+ .build();
+ client.close();
+ pending.reject(new Error('Offline'));
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ expect(resolver).toHaveBeenCalledOnce();
+ expect(client.underlyingWebsocket).toBeUndefined();
+ });
+});