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.

feat(calendar-cache): expose calendarRange and calendarCommit on wasm, Tauri and TS hosts (#7677)

gbirman262cd270b404
diff --git a/Cargo.lock b/Cargo.lock
index 0f7d736468..0123649723 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3448,7 +3448,7 @@ dependencies = [
[[package]]
name = "cache-wasm"
-version = "0.6.40"
+version = "0.6.41"
dependencies = [
"async-lock",
"cache-core",
diff --git a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
index 2165df6d05..55dffdb0ad 100644
--- a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
@@ -313,6 +313,12 @@ function makeFakeHost(): FakeHost {
async entityFilter() {
return { kind: 'unsupported' };
},
+ async calendarRange() {
+ return { kind: 'unsupported' };
+ },
+ async calendarCommit() {
+ return { kind: 'unsupported' };
+ },
async writeQuery(args): Promise<WriteResult> {
host.writes.push({
opKey: args.opKey,
diff --git a/apps/web/src/lib/graphql-cache/host/noop-host.ts b/apps/web/src/lib/graphql-cache/host/noop-host.ts
index 9f217f71dd..95accf7f03 100644
--- a/apps/web/src/lib/graphql-cache/host/noop-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/noop-host.ts
@@ -43,6 +43,12 @@ export function createNoopCacheHost(): CacheHost {
async entityFilter() {
return { kind: 'unsupported' };
},
+ async calendarRange() {
+ return { kind: 'unsupported' };
+ },
+ async calendarCommit() {
+ return { kind: 'unsupported' };
+ },
async writeQuery(): Promise<WriteResult> {
return emptyWriteResult();
},
diff --git a/apps/web/src/lib/graphql-cache/host/retirable-host.ts b/apps/web/src/lib/graphql-cache/host/retirable-host.ts
index ee01320254..e86429e05d 100644
--- a/apps/web/src/lib/graphql-cache/host/retirable-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/retirable-host.ts
@@ -22,6 +22,8 @@ export function createRetirableCacheHost(inner: CacheHost): CacheHost {
readRecordsByKeys: (args) => current.readRecordsByKeys(args),
search: (args) => current.search(args),
entityFilter: (args) => current.entityFilter(args),
+ calendarRange: (args) => current.calendarRange(args),
+ calendarCommit: (args) => current.calendarCommit(args),
writeQuery: (args) => current.writeQuery(args),
hydrateQuery: (args) => current.hydrateQuery(args),
enqueueOptimisticMutation: (args, claim) =>
diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts
index 06f629f82d..e2acf6ae21 100644
--- a/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts
+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts
@@ -981,4 +981,120 @@ describe('createTauriCacheHost', () => {
await Promise.resolve();
expect(unlisten).toHaveBeenCalled();
});
+
+ describe('calendar ranges', () => {
+ const rangeArgs = { startMs: 0, endMs: 10, startDay: 0, endDay: 1 };
+ const range = {
+ kind: 'range',
+ revision: '4',
+ occurrenceKeys: ['GraphqlCalendarOccurrence:e1:k'],
+ gaps: [],
+ freshness: 'fresh',
+ uncertainEventKeys: [],
+ optimistic: false,
+ watermark: [{ linkId: 'l1', seq: '3' }],
+ };
+
+ it('reads ranges, commits, and forwards uncertain calendar events', async () => {
+ invokeMock.mockImplementation(async (command: string) => {
+ if (command === 'graphql_cache_calendar_range') return range;
+ if (command === 'graphql_cache_calendar_commit')
+ return {
+ revision: '5',
+ revisionAdvanced: true,
+ changed: ['GraphqlCalendarEvent:e2'],
+ affectedOps: [],
+ reset: false,
+ revalidations: [],
+ };
+ return null;
+ });
+ const host = createTauriCacheHost({ scope: 'calendar-native' });
+ try {
+ await expect(host.calendarRange(rangeArgs)).resolves.toEqual(range);
+ expect(invokeMock).toHaveBeenLastCalledWith(
+ 'graphql_cache_calendar_range',
+ { request: rangeArgs }
+ );
+ const commit = { deletedEventKeys: ['GraphqlCalendarEvent:e2'] };
+ await expect(host.calendarCommit(commit)).resolves.toEqual({
+ kind: 'committed',
+ revision: '5',
+ changed: ['GraphqlCalendarEvent:e2'],
+ });
+ expect(invokeMock).toHaveBeenLastCalledWith(
+ 'graphql_cache_calendar_commit',
+ { commit }
+ );
+ invokeMock.mockResolvedValue(null);
+ void host.enqueueOptimisticMutation(
+ {
+ query: 'mutation M { m }',
+ data: {},
+ uuid: '00000000-0000-4000-8000-000000000001',
+ uncertainCalendarEventKeys: ['GraphqlCalendarEvent:e1'],
+ },
+ { owner: 'runner', nowMs: 0, leaseExpiresAtMs: 1 }
+ );
+ await vi.waitFor(() =>
+ expect(invokeMock).toHaveBeenLastCalledWith(
+ 'graphql_cache_enqueue_optimistic_mutation',
+ expect.objectContaining({
+ uncertainCalendarEventKeys: ['GraphqlCalendarEvent:e1'],
+ })
+ )
+ );
+ } finally {
+ host.dispose();
+ }
+ });
+
+ it('reports old native binaries as unsupported and stops probing them', async () => {
+ invokeMock.mockImplementation(async (command: string) => {
+ if (command === 'graphql_cache_calendar_range')
+ throw 'Command graphql_cache_calendar_range not found';
+ if (command === 'graphql_cache_read') return { kind: 'miss' };
+ return null;
+ });
+ const host = createTauriCacheHost({ scope: 'old-native-calendar' });
+ try {
+ await expect(host.calendarRange(rangeArgs)).resolves.toEqual({
+ kind: 'unsupported',
+ });
+ await expect(host.calendarCommit({ reset: true })).resolves.toEqual({
+ kind: 'unsupported',
+ });
+ expect(
+ invokeMock.mock.calls.filter(([command]) =>
+ String(command).startsWith('graphql_cache_calendar_')
+ )
+ ).toHaveLength(1);
+ await expect(host.readQuery({ query: '{ x }' })).resolves.toEqual({
+ kind: 'miss',
+ });
+ } finally {
+ host.dispose();
+ }
+ });
+
+ it('does not mistake other calendar failures for a missing command', async () => {
+ invokeMock.mockImplementation(async (command: string) => {
+ if (command === 'graphql_cache_calendar_range')
+ throw 'invalid calendar cache key';
+ return null;
+ });
+ const host = createTauriCacheHost({ scope: 'calendar-error' });
+ try {
+ await expect(host.calendarRange(rangeArgs)).rejects.toThrow(
+ 'invalid calendar cache key'
+ );
+ invokeMock.mockImplementation(async (command: string) =>
+ command === 'graphql_cache_calendar_range' ? range : null
+ );
+ await expect(host.calendarRange(rangeArgs)).resolves.toEqual(range);
+ } finally {
+ host.dispose();
+ }
+ });
+ });
});
diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.ts
index e5f9dfd86d..78f9d37c7d 100644
--- a/apps/web/src/lib/graphql-cache/host/tauri-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.ts
@@ -15,6 +15,10 @@ import type {
CachedQueryInstanceWire,
CachedQueryVariantWire,
CacheRevision,
+ CalendarCommitArgs,
+ CalendarCommitCacheResult,
+ CalendarRangeCacheArgs,
+ CalendarRangeCacheResult,
ClaimedMutation,
CommitOptimisticWriteResult,
DeferOptimisticWriteResult,
@@ -90,6 +94,8 @@ export interface TauriHostOptions {
const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
const ENTITY_FILTER_COMMAND = 'graphql_cache_entity_filter';
+const CALENDAR_RANGE_COMMAND = 'graphql_cache_calendar_range';
+const CALENDAR_COMMIT_COMMAND = 'graphql_cache_calendar_commit';
const INSPECT_MUTATIONS_COMMAND = 'graphql_cache_inspect_mutations';
/** An OTA bundle cannot safely replay drafts using an older native queue API. */
@@ -121,6 +127,11 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
// no longer receive these OTA bundles. OTA updates cannot add Rust commands.
// Keep this per host so a new native binary is probed again after restarting.
let entityFilterUnavailable = false;
+ // Native binaries before the calendar range index answer `unsupported`, so
+ // the calendar keeps reading from the network until the app updates.
+ let calendarUnavailable = false;
+ const isMissingCommand = (error: unknown, command: string): boolean =>
+ error instanceof Error && error.message === `Command ${command} not found`;
// Revisions are monotonic for the native engine's lifetime. This also gates
// repeated no-op hydrations on older binaries without revisionAdvanced.
@@ -338,6 +349,47 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
}
},
+ async calendarRange(
+ args: CalendarRangeCacheArgs
+ ): Promise<CalendarRangeCacheResult> {
+ await ready;
+ if (calendarUnavailable) return { kind: 'unsupported' };
+ try {
+ const result = await request<CalendarRangeCacheResult>(
+ CALENDAR_RANGE_COMMAND,
+ { request: args }
+ );
+ return result.kind === 'unsupported'
+ ? result
+ : { ...result, revision: parseCacheRevision(result.revision) };
+ } catch (error) {
+ if (!isMissingCommand(error, CALENDAR_RANGE_COMMAND)) throw error;
+ calendarUnavailable = true;
+ return { kind: 'unsupported' };
+ }
+ },
+
+ async calendarCommit(
+ args: CalendarCommitArgs
+ ): Promise<CalendarCommitCacheResult> {
+ await ready;
+ if (calendarUnavailable) return { kind: 'unsupported' };
+ try {
+ const result = await request<WriteResult>(CALENDAR_COMMIT_COMMAND, {
+ commit: args,
+ });
+ return {
+ kind: 'committed',
+ revision: parseCacheRevision(result.revision),
+ changed: result.changed,
+ };
+ } catch (error) {
+ if (!isMissingCommand(error, CALENDAR_COMMIT_COMMAND)) throw error;
+ calendarUnavailable = true;
+ return { kind: 'unsupported' };
+ }
+ },
+
async writeQuery(args: CacheWriteArgs): Promise<WriteResult> {
await ready;
return await request<WriteResult>('graphql_cache_write', {
@@ -407,6 +459,7 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
revalidations: args.revalidations,
identityBindings: args.identityBindings,
clientMetadata: args.clientMetadata,
+ uncertainCalendarEventKeys: args.uncertainCalendarEventKeys,
createdAtMs: claim.nowMs,
owner: claim.owner,
nowMs: claim.nowMs,
diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.ts
index 0e0d725d3d..8f0f466102 100644
--- a/apps/web/src/lib/graphql-cache/host/types.ts
+++ b/apps/web/src/lib/graphql-cache/host/types.ts
@@ -14,6 +14,10 @@ import type {
CachedQueryVariantWire,
CacheReadPriority,
CacheRevision,
+ CalendarCommitArgs,
+ CalendarCommitCacheResult,
+ CalendarRangeCacheArgs,
+ CalendarRangeCacheResult,
ClaimedMutation,
CommitOptimisticWriteResult,
DeferOptimisticWriteResult,
@@ -80,6 +84,12 @@ export interface EnqueueOptimisticMutationArgs extends CacheWriteArgs {
linkPatches?: OptimisticLinkPatchWire[];
/** Revalidations for relevant cached fields that could not be patched. */
revalidations?: QueryRevalidationWire[];
+ /**
+ * `GraphqlCalendarEvent` keys whose occurrence set this mutation cannot
+ * predict (for example a recurrence edit); calendar ranges report them
+ * until the mutation settles.
+ */
+ uncertainCalendarEventKeys?: string[];
}
/** Lease request used for the claim attempted immediately after enqueue. */
@@ -125,6 +135,12 @@ export interface CacheHost {
search(args: SearchCacheArgs): Promise<SearchCachePage>;
/** Evaluates an exact initial Soup filter page over complete local projections. */
entityFilter(args: EntityFilterCacheArgs): Promise<EntityFilterCacheResult>;
+ /** Answers a calendar viewport from the local range index. */
+ calendarRange(
+ args: CalendarRangeCacheArgs
+ ): Promise<CalendarRangeCacheResult>;
+ /** Atomically applies calendar coverage, deletions, and sync state. */
+ calendarCommit(args: CalendarCommitArgs): Promise<CalendarCommitCacheResult>;
writeQuery(args: CacheWriteArgs): Promise<WriteResult>;
/**
* Stores a background query response and returns only fields not marked
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.ts
index 9d923b7992..3744369d09 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts
@@ -14,6 +14,10 @@ import {
type CacheRequest,
type CacheResponseErrorCode,
type CacheRevision,
+ type CalendarCommitArgs,
+ type CalendarCommitCacheResult,
+ type CalendarRangeCacheArgs,
+ type CalendarRangeCacheResult,
type ClaimedMutation,
type CommitOptimisticWriteResult,
type DeferOptimisticWriteResult,
@@ -951,6 +955,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
msg.kind === 'read-records-by-keys' ||
msg.kind === 'search' ||
msg.kind === 'entity-filter' ||
+ msg.kind === 'calendar-range' ||
msg.kind === 'inspect-mutations' ||
msg.kind === 'inspect-query' ||
msg.kind === 'inspect-query-variants'
@@ -1216,6 +1221,24 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
})) as EntityFilterCacheResult;
},
+ async calendarRange(
+ args: CalendarRangeCacheArgs
+ ): Promise<CalendarRangeCacheResult> {
+ return (await initializedRequest({
+ kind: 'calendar-range',
+ request: args,
+ })) as CalendarRangeCacheResult;
+ },
+
+ async calendarCommit(
+ args: CalendarCommitArgs
+ ): Promise<CalendarCommitCacheResult> {
+ return (await initializedRequest({
+ kind: 'calendar-commit',
+ commit: args,
+ })) as CalendarCommitCacheResult;
+ },
+
async writeQuery(args: CacheWriteArgs): Promise<WriteResult> {
if (args.registerDependencies && args.opKey !== undefined) {
trackActiveOperation(args.opKey);
@@ -1270,6 +1293,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
revalidations: args.revalidations,
identityBindings: args.identityBindings,
clientMetadata: args.clientMetadata,
+ uncertainCalendarEventKeys: args.uncertainCalendarEventKeys,
createdAtMs: claim.nowMs,
owner: claim.owner,
nowMs: claim.nowMs,
diff --git a/apps/web/src/lib/graphql-cache/index.ts b/apps/web/src/lib/graphql-cache/index.ts
index 43313810c2..2c3dbabdc1 100644
--- a/apps/web/src/lib/graphql-cache/index.ts
+++ b/apps/web/src/lib/graphql-cache/index.ts
@@ -63,6 +63,15 @@ export type {
CacheRequest,
CacheResponse,
CacheRevision,
+ CalendarCommitArgs,
+ CalendarCommitCacheResult,
+ CalendarFreshness,
+ CalendarLinkWatermarkWire,
+ CalendarRangeCacheArgs,
+ CalendarRangeCacheResult,
+ CalendarSpanKind,
+ CalendarSpanWire,
+ CalendarWatermarkUpdateWire,
EnqueueOptimisticMutationResult,
EntityFilterCacheArgs,
EntityFilterCacheResult,
diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.ts
index cf5d9771e8..4ff425b3a1 100644
--- a/apps/web/src/lib/graphql-cache/protocol.ts
+++ b/apps/web/src/lib/graphql-cache/protocol.ts
@@ -142,6 +142,91 @@ export type EntityFilterCacheResult =
| { kind: 'unsupported' }
| { kind: 'incomplete'; revision: CacheRevision };
+/** Unit of a calendar span: UTC milliseconds, or local days since 1970-01-01. */
+export type CalendarSpanKind = 'timed' | 'allDay';
+
+/** Half-open `[start, end)` calendar span. */
+export type CalendarSpanWire = {
+ kind: CalendarSpanKind;
+ start: number;
+ end: number;
+};
+
+/** Applied change-log position of one email link; `seq` is a decimal i64. */
+export type CalendarLinkWatermarkWire = { linkId: string; seq: string };
+
+export type CalendarFreshness = 'fresh' | 'stale' | 'unknown';
+
+/**
+ * One calendar viewport over both span kinds. Empty spans read only the sync
+ * state (freshness and watermark).
+ */
+export type CalendarRangeCacheArgs = {
+ startMs: number;
+ endMs: number;
+ startDay: number;
+ endDay: number;
+ /** Restricts occurrences to one `GraphqlCalendarEvent:{id}` key. */
+ eventKey?: string;
+};
+
+export type CalendarRangeCacheResult =
+ | {
+ kind: 'range';
+ revision: CacheRevision;
+ /** `GraphqlCalendarOccurrence` keys ordered by kind, start, and key. */
+ occurrenceKeys: string[];
+ /** Requested spans never fetched from the server. */
+ gaps: CalendarSpanWire[];
+ freshness: CalendarFreshness;
+ /** Events whose occurrence set is unknown until a pending mutation settles. */
+ uncertainEventKeys: string[];
+ /** Whether a pending optimistic mutation shaped this result. */
+ optimistic: boolean;
+ /** Null until a commit carries a watermark. */
+ watermark: CalendarLinkWatermarkWire[] | null;
+ }
+ /** The native host predates calendar ranges; read calendars from the network. */
+ | { kind: 'unsupported' };
+
+/**
+ * `merge` lowers each link to a page's pre-read watermark; `advance` moves
+ * links still at `since` to the delta's `to` and keeps concurrent lowerings.
+ */
+export type CalendarWatermarkUpdateWire =
+ | { kind: 'merge'; links: CalendarLinkWatermarkWire[] }
+ | {
+ kind: 'advance';
+ since: CalendarLinkWatermarkWire[];
+ to: CalendarLinkWatermarkWire[];
+ };
+
+/** One atomic change to calendar coverage, cached calendar records, and sync state. */
+export type CalendarCommitArgs = {
+ /** Spans whose occurrences were fully fetched and written. */
+ coverage?: CalendarSpanWire[];
+ /** Events whose cached occurrences outside `occurrenceKeys` are deleted. */
+ replacedEvents?: Array<{ eventKey: string; occurrenceKeys: string[] }>;
+ /** Events deleted with every cached occurrence. */
+ deletedEventKeys?: string[];
+ deletedCalendarKeys?: string[];
+ /** Links no longer visible: their occurrences, events, and calendars are deleted. */
+ removedLinkIds?: string[];
+ watermark?: CalendarWatermarkUpdateWire;
+ freshness?: 'fresh' | 'stale';
+ /** Deletes every cached occurrence, event, coverage span, and the watermark first. */
+ reset?: boolean;
+};
+
+export type CalendarCommitCacheResult =
+ | {
+ kind: 'committed';
+ revision: CacheRevision;
+ /** Records the commit deleted. */
+ changed: string[];
+ }
+ | { kind: 'unsupported' };
+
export type ReadRecordsByKeysArgs = {
/** Serialized generated fragment document. */
document: string;
@@ -237,6 +322,118 @@ export function isValidCacheSearchCursor(
);
}
+const hasOnlyCalendarKeys = (
+ value: Record<string, unknown>,
+ keys: readonly string[]
+): boolean => Object.keys(value).every((key) => keys.includes(key));
+
+const isCalendarSpanWire = (value: unknown): value is CalendarSpanWire =>
+ isRecord(value) &&
+ hasOnlyCalendarKeys(value, ['kind', 'start', 'end']) &&
+ (value.kind === 'timed' || value.kind === 'allDay') &&
+ Number.isSafeInteger(value.start) &&
+ Number.isSafeInteger(value.end);
+
+const isCalendarWatermarkWire = (
+ value: unknown
+): value is CalendarLinkWatermarkWire[] =>
+ Array.isArray(value) &&
+ value.every(
+ (link) =>
+ isRecord(link) &&
+ hasOnlyCalendarKeys(link, ['linkId', 'seq']) &&
+ typeof link.linkId === 'string' &&
+ link.linkId.length > 0 &&
+ typeof link.seq === 'string' &&
+ /^[0-9]{1,19}$/.test(link.seq)
+ );
+
+const isOptionalWireArray = (
+ value: unknown,
+ item: (entry: unknown) => boolean
+): boolean =>
+ value === undefined || (Array.isArray(value) && value.every(item));
+
+const isCalendarWatermarkUpdateWire = (value: unknown): boolean =>
+ isRecord(value) &&
+ ((value.kind === 'merge' &&
+ hasOnlyCalendarKeys(value, ['kind', 'links']) &&
+ isCalendarWatermarkWire(value.links)) ||
+ (value.kind === 'advance' &&
+ hasOnlyCalendarKeys(value, ['kind', 'since', 'to']) &&
+ isCalendarWatermarkWire(value.since) &&
+ isCalendarWatermarkWire(value.to)));
+
+/** Non-throwing calendar range validation for wire ingress. */
+export function isValidCalendarRangeArgs(
+ value: unknown
+): value is CalendarRangeCacheArgs {
+ return (
+ isRecord(value) &&
+ hasOnlyCalendarKeys(value, [
+ 'startMs',
+ 'endMs',
+ 'startDay',
+ 'endDay',
+ 'eventKey',
+ ]) &&
+ Number.isSafeInteger(value.startMs) &&
+ Number.isSafeInteger(value.endMs) &&
+ Number.isSafeInteger(value.startDay) &&
+ Number.isSafeInteger(value.endDay) &&
+ (value.startMs as number) <= (value.endMs as number) &&
+ (value.startDay as number) <= (value.endDay as number) &&
+ (value.eventKey === undefined || isValidNormalizedRecordKey(value.eventKey))
+ );
+}
+
+/**
+ * Non-throwing calendar commit shape validation for wire ingress. The engine
+ * still validates typenames, duplicates, and size bounds.
+ */
+export function isValidCalendarCommitArgs(
+ value: unknown
+): value is CalendarCommitArgs {
+ return (
+ isRecord(value) &&
+ hasOnlyCalendarKeys(value, [
+ 'coverage',
+ 'replacedEvents',
+ 'deletedEventKeys',
+ 'deletedCalendarKeys',
+ 'removedLinkIds',
+ 'watermark',
+ 'freshness',
+ 'reset',
+ ]) &&
+ isOptionalWireArray(value.coverage, isCalendarSpanWire) &&
+ isOptionalWireArray(
+ value.replacedEvents,
+ (event) =>
+ isRecord(event) &&
+ hasOnlyCalendarKeys(event, ['eventKey', 'occurrenceKeys']) &&
+ isValidNormalizedRecordKey(event.eventKey) &&
+ Array.isArray(event.occurrenceKeys) &&
+ event.occurrenceKeys.every(isValidNormalizedRecordKey)
+ ) &&
+ isOptionalWireArray(value.deletedEventKeys, isValidNormalizedRecordKey) &&
+ isOptionalWireArray(
+ value.deletedCalendarKeys,
+ isValidNormalizedRecordKey
+ ) &&
+ isOptionalWireArray(
+ value.removedLinkIds,
+ (linkId) => typeof linkId === 'string' && linkId.length > 0
+ ) &&
+ (value.watermark === undefined ||
+ isCalendarWatermarkUpdateWire(value.watermark)) &&
+ (value.freshness === undefined ||
+ value.freshness === 'fresh' ||
+ value.freshness === 'stale') &&
+ (value.reset === undefined || typeof value.reset === 'boolean')
+ );
+}
+
export function validateRecordSelectionKeys(keys: string[]): string[] {
if (keys.length > MAX_RECORD_SELECTION_PAGE_SIZE) {
throw new RangeError(
@@ -553,6 +750,7 @@ export type CacheRequest = { id: number } & (
revalidations?: QueryRevalidationWire[];
clientMetadata?: Record<string, unknown>;
identityBindings?: IdentityBindingWire[];
+ uncertainCalendarEventKeys?: string[];
createdAtMs: number;
owner: string;
nowMs: number;
@@ -607,6 +805,15 @@ export type CacheRequest = { id: number } & (
kind: 'entity-filter';
request: EntityFilterCacheArgs;
}
+ | {
+ kind: 'calendar-range';
+ request: CalendarRangeCacheArgs;
+ }
+ /** Atomically apply calendar coverage, deletions, and sync state. */
+ | {
+ kind: 'calendar-commit';
+ commit: CalendarCommitArgs;
+ }
| {
kind: 'inspect-query';
query: string;
diff --git a/apps/web/src/lib/graphql-cache/telemetry.ts b/apps/web/src/lib/graphql-cache/telemetry.ts
index bf12219d6a..f45e041bec 100644
--- a/apps/web/src/lib/graphql-cache/telemetry.ts
+++ b/apps/web/src/lib/graphql-cache/telemetry.ts
@@ -505,9 +505,10 @@ export function operationCategoryForRequest(
'read-records-by-keys',
'search',
'entity-filter',
+ 'calendar-range',
() => 'read' as const
)
- .with('write', 'hydrate', () => 'write' as const)
+ .with('write', 'hydrate', 'calendar-commit', () => 'write' as const)
.with(
'enqueue-optimistic-mutation',
'claim-next-mutation',
@@ -538,6 +539,7 @@ export function isStorageTransactionRequest(
return [
'write',
'hydrate',
+ 'calendar-commit',
'enqueue-optimistic-mutation',
'claim-next-mutation',
'defer-optimistic-write',
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts
index 3cab87f5c0..0d065c40b0 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts
@@ -263,6 +263,76 @@ describe('coordinator runtime protocol', () => {
expect(valid([{ ...entry, unexpected: true }])).toBe(false);
});
+ it('validates calendar range, commit, and uncertain-event requests', () => {
+ const range = { startMs: 0, endMs: 10, startDay: 0, endDay: 1 };
+ const rangeRequest = (request: unknown) =>
+ isCacheRequest({ id: 1, kind: 'calendar-range', request });
+ expect(rangeRequest(range)).toBe(true);
+ expect(
+ rangeRequest({ ...range, eventKey: 'GraphqlCalendarEvent:e1' })
+ ).toBe(true);
+ expect(rangeRequest({ ...range, endMs: -1 })).toBe(false);
+ expect(rangeRequest({ ...range, startDay: 0.5 })).toBe(false);
+ expect(rangeRequest({ ...range, eventKey: 'e1' })).toBe(false);
+ expect(rangeRequest({ ...range, extra: true })).toBe(false);
+
+ const commitRequest = (commit: unknown) =>
+ isCacheRequest({ id: 1, kind: 'calendar-commit', commit });
+ expect(commitRequest({})).toBe(true);
+ expect(
+ commitRequest({
+ coverage: [{ kind: 'allDay', start: 0, end: 7 }],
+ replacedEvents: [
+ {
+ eventKey: 'GraphqlCalendarEvent:e1',
+ occurrenceKeys: ['GraphqlCalendarOccurrence:e1:k'],
+ },
+ ],
+ deletedEventKeys: ['GraphqlCalendarEvent:e2'],
+ deletedCalendarKeys: ['GraphqlCalendar:c1'],
+ removedLinkIds: ['l2'],
+ watermark: {
+ kind: 'advance',
+ since: [{ linkId: 'l1', seq: '1' }],
+ to: [{ linkId: 'l1', seq: '9' }],
+ },
+ freshness: 'fresh',
+ reset: false,
+ })
+ ).toBe(true);
+ for (const invalid of [
+ { coverage: [{ kind: 'week', start: 0, end: 1 }] },
+ { deletedEventKeys: ['e2'] },
+ { removedLinkIds: [''] },
+ { watermark: { kind: 'merge', links: [{ linkId: 'l1', seq: 1 }] } },
+ { watermark: { kind: 'merge', links: [{ linkId: 'l1', seq: '-1' }] } },
+ { watermark: { kind: 'replace', links: [] } },
+ { freshness: 'unknown' },
+ { reset: 'yes' },
+ { extra: true },
+ ]) {
+ expect(commitRequest(invalid)).toBe(false);
+ }
+
+ const enqueue = (uncertainCalendarEventKeys: unknown) =>
+ isCacheRequest({
+ id: 1,
+ kind: 'enqueue-optimistic-mutation',
+ uuid: '00000000-0000-4000-8000-000000000001',
+ query: 'mutation M { m }',
+ data: {},
+ uncertainCalendarEventKeys,
+ createdAtMs: 0,
+ owner: 'runner',
+ nowMs: 0,
+ leaseExpiresAtMs: 1,
+ });
+ expect(enqueue(undefined)).toBe(true);
+ expect(enqueue(['GraphqlCalendarEvent:e1'])).toBe(true);
+ expect(enqueue(['e1'])).toBe(false);
+ expect(enqueue(Array(257).fill('GraphqlCalendarEvent:e1'))).toBe(false);
+ });
+
it('validates cache RPCs and rejects unknown fields or kinds', () => {
expect(isCacheRequest({ id: 0, kind: 'clear' })).toBe(true);
expect(isCacheRequest({ id: 1, kind: 'current-revision' })).toBe(true);
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
index 820b3395f6..0774828936 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
@@ -10,6 +10,8 @@ import {
isValidCacheSearchNowMs,
isValidCacheSearchProfile,
isValidCacheSearchQuery,
+ isValidCalendarCommitArgs,
+ isValidCalendarRangeArgs,
isValidNormalizedRecordKey,
isWorkerMessage,
MAX_RECONCILIATION_BASELINE,
@@ -556,12 +558,19 @@ export function isCacheRequest(value: unknown): value is CacheRequest {
'linkPatches',
'revalidations',
'identityBindings',
+ 'uncertainCalendarEventKeys',
'clientMetadata',
'createdAtMs',
'owner',
'nowMs',
'leaseExpiresAtMs',
]) &&
+ (value.uncertainCalendarEventKeys === undefined ||
+ (Array.isArray(value.uncertainCalendarEventKeys) &&
+ value.uncertainCalendarEventKeys.length <= 256 &&
+ value.uncertainCalendarEventKeys.every(
+ isValidNormalizedRecordKey
+ ))) &&
isOptionalString(value.originOpId) &&
isString(value.uuid) &&
isString(value.query) &&
@@ -737,6 +746,16 @@ export function isCacheRequest(value: unknown): value is CacheRequest {
)))
);
}
+ case 'calendar-range':
+ return (
+ hasOnlyKeys(value, ['id', 'kind', 'request']) &&
+ isValidCalendarRangeArgs(value.request)
+ );
+ case 'calendar-commit':
+ return (
+ hasOnlyKeys(value, ['id', 'kind', 'commit']) &&
+ isValidCalendarCommitArgs(value.commit)
+ );
case 'inspect-query':
return (
hasOnlyKeys(value, [
diff --git a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
index c3bf8f8a73..62b478828f 100644
--- a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
+++ b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
@@ -16,6 +16,9 @@ import type {
CachedQueryVariantWire,
CacheRevision,
CacheRevisionResult,
+ CalendarCommitArgs,
+ CalendarRangeCacheArgs,
+ CalendarRangeCacheResult,
ClaimedMutation,
CommitOptimisticWriteResult,
DeferOptimisticWriteResult,
@@ -95,6 +98,11 @@ export interface CacheEngine {
entityFilter(
request: EntityFilterCacheArgs
): Promise<EntityFilterCacheResult>;
+ calendarRange(
+ request: CalendarRangeCacheArgs
+ ): Promise<CalendarRangeCacheResult>;
+ /** Resolves like `writeQuery`: deleted records are reported as `changed`. */
+ calendarCommit(commit: CalendarCommitArgs): Promise<WriteResult>;
writeQuery(
context: {
originOpId?: string;
@@ -131,7 +139,8 @@ export interface CacheEngine {
leaseOwner: string,
nowMs: number,
leaseExpiresAtMs: number,
- clientMetadata?: Record<string, unknown>
+ clientMetadata?: Record<string, unknown>,
+ uncertainCalendarEventKeys?: string[]
): Promise<EnqueueOptimisticMutationResult>;
inspectQueryVariants(
query: string,
diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
index c4eb34279e..71d92648f9 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
@@ -556,6 +556,124 @@ describe('CacheWorkerCore', () => {
]);
});
+ it('keeps a calendar commit behind the hydration it covers and fans out its deletions', async () => {
+ const order: string[] = [];
+ let releaseBlocker!: () => void;
+ let markBlockerStarted!: () => void;
+ const blocker = new Promise<void>((resolve) => {
+ releaseBlocker = resolve;
+ });
+ const blockerStarted = new Promise<void>((resolve) => {
+ markBlockerStarted = resolve;
+ });
+ const range = {
+ kind: 'range' as const,
+ revision: '1',
+ occurrenceKeys: [],
+ gaps: [],
+ freshness: 'fresh' as const,
+ uncertainEventKeys: [],
+ optimistic: false,
+ watermark: null,
+ };
+ loadCacheWasmMock.mockResolvedValue({
+ openCache: vi.fn().mockResolvedValue({
+ readQuery: vi.fn(async () => {
+ order.push('read');
+ markBlockerStarted();
+ await blocker;
+ return { kind: 'miss' as const };
+ }),
+ hydrateQuery: vi.fn(async () => {
+ order.push('hydrate');
+ return {
+ revision: '1',
+ revisionAdvanced: true,
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ data: null,
+ };
+ }),
+ calendarRange: vi.fn(async () => {
+ order.push('calendar-range');
+ return range;
+ }),
+ calendarCommit: vi.fn(async () => {
+ order.push('calendar-commit');
+ return {
+ revision: '2',
+ revisionAdvanced: true,
+ changed: ['GraphqlCalendarOccurrence:e1:k'],
+ affectedOps: ['client:7'],
+ reset: false,
+ searchChangedBuckets: [],
+ };
+ }),
+ }),
+ });
+ const messages: unknown[] = [];
+ const port = { postMessage: vi.fn((message) => messages.push(message)) };
+ const core = new CacheWorkerCore();
+ core.addPort(port);
+ await core.handleRequest(port, { id: 1, kind: 'init', scope: 'scope-1' });
+
+ const running = core.handleRequest(port, {
+ id: 2,
+ kind: 'read',
+ query: 'query Blocker { blocker }',
+ });
+ await blockerStarted;
+ const hydration = core.handleRequest(port, {
+ id: 3,
+ kind: 'hydrate',
+ query: 'query CalendarOccurrences { occurrences }',
+ data: { occurrences: [] },
+ });
+ const commit = core.handleRequest(port, {
+ id: 4,
+ kind: 'calendar-commit',
+ commit: {
+ coverage: [{ kind: 'timed', start: 0, end: 10 }],
+ deletedEventKeys: ['GraphqlCalendarEvent:e1'],
+ },
+ });
+ const read = core.handleRequest(port, {
+ id: 5,
+ kind: 'calendar-range',
+ request: { startMs: 0, endMs: 10, startDay: 0, endDay: 1 },
+ });
+ releaseBlocker();
+ await Promise.all([running, hydration, commit, read]);
+
+ expect(order).toEqual([
+ 'read',
+ 'calendar-range',
+ 'hydrate',
+ 'calendar-commit',
+ ]);
+ expect(messages).toContainEqual({ id: 5, ok: true, result: range });
+ expect(messages).toContainEqual({
+ kind: 'ops-affected',
+ opIds: ['client:7'],
+ keys: ['GraphqlCalendarOccurrence:e1:k'],
+ });
+ expect(messages).toContainEqual({
+ kind: 'cache-changed',
+ revision: '2',
+ searchChangedBuckets: [],
+ });
+ expect(messages).toContainEqual({
+ id: 4,
+ ok: true,
+ result: {
+ kind: 'committed',
+ revision: '2',
+ changed: ['GraphqlCalendarOccurrence:e1:k'],
+ },
+ });
+ });
+
it('does not let stale hydration overwrite a newer queued write', async () => {
let releaseBlocker!: () => void;
let markBlockerStarted!: () => void;
diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
index 17084472a1..e6919a59e9 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
@@ -10,6 +10,8 @@ import type {
CacheRequest,
CacheResponse,
CacheRevisionResult,
+ CalendarCommitCacheResult,
+ CalendarRangeCacheResult,
EnqueueOptimisticMutationResult,
EntityFilterCacheResult,
HydrationResult,
@@ -111,7 +113,13 @@ function isOrderingBarrier(request: CacheRequest): boolean {
}
function isQueryDataWrite(request: CacheRequest): boolean {
- return request.kind === 'write' || request.kind === 'hydrate';
+ // A calendar commit records coverage for data written just before it, so it
+ // must never overtake that write or hydration.
+ return (
+ request.kind === 'write' ||
+ request.kind === 'hydrate' ||
+ request.kind === 'calendar-commit'
+ );
}
function revisionAdvancementCategory(
@@ -126,7 +134,12 @@ function revisionAdvancementCategory(
| 'clear'
| undefined {
return match(request.kind)
- .with('write', 'hydrate', () => 'authoritative-write' as const)
+ .with(
+ 'write',
+ 'hydrate',
+ 'calendar-commit',
+ () => 'authoritative-write' as const
+ )
.with('enqueue-optimistic-mutation', () => 'optimistic-enqueue' as const)
.with('commit-optimistic-write', () => 'optimistic-commit' as const)
.with('rollback-optimistic-write', () => 'optimistic-rollback' as const)
@@ -145,6 +158,7 @@ function requestPriority(request: CacheRequest): number {
}
if (
request.kind === 'write' ||
+ request.kind === 'calendar-commit' ||
request.kind === 'enqueue-optimistic-mutation' ||
request.kind === 'claim-next-mutation' ||
request.kind === 'commit-optimistic-write' ||
@@ -500,6 +514,26 @@ export class CacheWorkerCore {
? result
: { ...result, revision: parseCacheRevision(result.revision) };
})
+ .with({ kind: 'calendar-range' }, async (request) => {
+ const result: CalendarRangeCacheResult =
+ await this.requireEngine().calendarRange(request.request);
+ return result.kind === 'unsupported'
+ ? result
+ : { ...result, revision: parseCacheRevision(result.revision) };
+ })
+ .with({ kind: 'calendar-commit' }, async (request) => {
+ const result = await this.requireEngine().calendarCommit(
+ request.commit
+ );
+ result.revision = parseCacheRevision(result.revision);
+ this.fanOut(result, true);
+ const committed: CalendarCommitCacheResult = {
+ kind: 'committed',
+ revision: result.revision,
+ changed: result.changed,
+ };
+ return committed;
+ })
.with({ kind: 'write' }, async (request) => {
const engine = this.requireEngine();
const result = await engine.writeQuery(
@@ -567,7 +601,8 @@ export class CacheWorkerCore {
request.owner,
request.nowMs,
request.leaseExpiresAtMs,
- request.clientMetadata
+ request.clientMetadata,
+ request.uncertainCalendarEventKeys
);
result.revision = parseCacheRevision(result.revision);
this.fanOut(result, true);
diff --git a/apps/web/tauri/graphql_cache_plugin/src/commands.rs b/apps/web/tauri/graphql_cache_plugin/src/commands.rs
index 8933f08fe6..fc62e2ac71 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/commands.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/commands.rs
@@ -10,16 +10,17 @@
//! worker's `{ok: false, error}` responses.
use crate::engine::{
- AffectedOperationsResultWire, ClaimedMutationWire, CommitOptimisticWriteResultWire,
- DeferOptimisticWriteResultWire, EngineHandle, EnqueueOptimisticMutationResultWire,
- EntityFilterRequest, EntityFilterResult, MutationUpsertKindWire, ReadResultWire,
- RecordSelectionResultWire, RollbackOptimisticWriteResultWire, WriteRegistration, WriteRequest,
- WriteResultWire,
+ AffectedOperationsResultWire, CalendarRangeResultWire, ClaimedMutationWire,
+ CommitOptimisticWriteResultWire, DeferOptimisticWriteResultWire, EngineHandle,
+ EnqueueOptimisticMutationResultWire, EntityFilterRequest, EntityFilterResult,
+ MutationUpsertKindWire, ReadResultWire, RecordSelectionResultWire,
+ RollbackOptimisticWriteResultWire, WriteRegistration, WriteRequest, WriteResultWire,
};
use crate::{
CacheState, InitializedCache, emit_cache_changed, emit_cache_changed_with_search_changes,
emit_mutation_settled, emit_ops_affected,
};
+use cache_core::calendar::{CalendarCommit, CalendarRangeRequest};
use cache_core::entity_resolver::EntityResolver;
use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};
use cache_core::query_inspection::{CachedQueryInstance, CachedQueryVariant};
@@ -151,6 +152,36 @@ pub async fn graphql_cache_entity_filter(
engine_handle(&state)?.entity_filter(request).await
}
+/// Answers a calendar viewport from the native range index.
+#[tauri::command]
+pub async fn graphql_cache_calendar_range(
+ state: State<'_, CacheState>,
+ request: CalendarRangeRequest,
+) -> Result<CalendarRangeResultWire, String> {
+ engine_handle(&state)?.calendar_range(request).await
+}
+
+/// Applies fetched coverage, delta deletions, and sync state, then
+/// broadcasts the deleted records to every webview like a write.
+#[tauri::command]
+pub async fn graphql_cache_calendar_commit<R: Runtime>(
+ app: AppHandle<R>,
+ state: State<'_, CacheState>,
+ commit: CalendarCommit,
+) -> Result<WriteResultWire, String> {
+ let result = engine_handle(&state)?.calendar_commit(commit).await?;
+ emit_ops_affected(&app, &result.affected_ops, &result.changed);
+ if result.revision_advanced {
+ emit_cache_changed_with_search_changes(
+ &app,
+ &result.revision,
+ result.reset,
+ result.search_changed_buckets.as_ref(),
+ );
+ }
+ Ok(result)
+}
+
/// Active-query registration installed by a network write.
#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
@@ -304,6 +335,7 @@ pub async fn graphql_cache_enqueue_optimistic_mutation<R: Runtime>(
now_ms: i64,
lease_expires_at_ms: i64,
client_metadata: Option<serde_json::Value>,
+ uncertain_calendar_event_keys: Option<Vec<String>>,
) -> Result<EnqueueOptimisticMutationResultWire, String> {
let result = engine_handle(&state)?
.enqueue_optimistic_mutation(
@@ -321,6 +353,7 @@ pub async fn graphql_cache_enqueue_optimistic_mutation<R: Runtime>(
now_ms,
lease_expires_at_ms,
client_metadata,
+ uncertain_calendar_event_keys.unwrap_or_default(),
)
.await?;
emit_ops_affected(&app, &result.result.affected_ops, &result.result.changed);
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine.rs b/apps/web/tauri/graphql_cache_plugin/src/engine.rs
index 5b7f1471c4..dbdcf7d3d6 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine.rs
@@ -33,7 +33,9 @@ use std::collections::HashMap;
use std::sync::Arc;
use tokio::sync::Mutex;
+mod calendar;
mod soup;
+pub use calendar::CalendarRangeResultWire;
pub use soup::{
EntityFilterRequest, EntityFilterResult, PredicateBaselineEntry, PredicateFilterResult,
};
@@ -699,6 +701,7 @@ impl EngineHandle {
now_ms: i64,
lease_expires_at_ms: i64,
client_metadata: Option<serde_json::Value>,
+ uncertain_calendar_event_keys: Vec<String>,
) -> Result<EnqueueOptimisticMutationResultWire, String> {
let mut state = self.inner.lock().await;
let EngineState { engine, ops, .. } = &mut *state;
@@ -713,7 +716,7 @@ impl EngineHandle {
)
.await?;
let result = engine
- .enqueue_optimistic_mutation_with_projections(
+ .enqueue_optimistic_mutation_with_calendar(
origin,
BeginOptimisticWrite {
client_metadata: client_metadata.as_ref(),
@@ -733,6 +736,10 @@ impl EngineHandle {
lease_expires_at_ms,
},
projections,
+ uncertain_calendar_event_keys
+ .into_iter()
+ .map(|key| EntityKey(key.into()))
+ .collect(),
)
.await
.map_err(|error| error.to_string())?;
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine/calendar.rs b/apps/web/tauri/graphql_cache_plugin/src/engine/calendar.rs
new file mode 100644
index 0000000000..63515ea2cd
--- /dev/null
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/calendar.rs
@@ -0,0 +1,51 @@
+//! Calendar range reads and commits over the native range index.
+
+use super::{EngineHandle, EngineState, WriteResultWire, wire_write_result};
+use cache_core::calendar::{CalendarCommit, CalendarRangeRequest, CalendarRangeResult};
+use serde::Serialize;
+
+/// Mirrors the `range` variant of `CalendarRangeCacheResult` in
+/// `apps/web/src/lib/graphql-cache/protocol.ts`.
+#[derive(Debug, Serialize)]
+#[serde(tag = "kind", rename_all = "camelCase")]
+pub enum CalendarRangeResultWire {
+ /// The engine answered the viewport from its range index.
+ Range {
+ /// Revision observed by the read.
+ revision: String,
+ /// Keys, gaps, freshness, uncertainty, and watermark.
+ #[serde(flatten)]
+ result: CalendarRangeResult,
+ },
+}
+
+impl EngineHandle {
+ /// Answers a calendar viewport from cached occurrences.
+ pub async fn calendar_range(
+ &self,
+ request: CalendarRangeRequest,
+ ) -> Result<CalendarRangeResultWire, String> {
+ self.inner
+ .lock()
+ .await
+ .engine
+ .calendar_range(&request)
+ .await
+ .map(|result| CalendarRangeResultWire::Range {
+ revision: result.revision.to_string(),
+ result: result.value,
+ })
+ .map_err(|error| error.to_string())
+ }
+
+ /// Applies a calendar commit atomically.
+ pub async fn calendar_commit(&self, commit: CalendarCommit) -> Result<WriteResultWire, String> {
+ let mut state = self.inner.lock().await;
+ let EngineState { engine, ops, .. } = &mut *state;
+ let result = engine
+ .calendar_commit(&commit)
+ .await
+ .map_err(|error| error.to_string())?;
+ Ok(wire_write_result(ops, result))
+ }
+}
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
index cbc149492a..7a41cfd960 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
@@ -1,6 +1,7 @@
use super::*;
use pollster::block_on;
+mod calendar;
mod soup;
const QUERY: &str = r#"query Soup($input: SoupInput!) {
@@ -567,6 +568,7 @@ fn optimistic_layer_commits_durably() {
10,
1_000,
Some(serde_json::json!({"draftRevision": 10})),
+ vec![],
))
.unwrap();
assert_eq!(optimistic.result.affected_ops, vec!["client:1".to_string()]);
@@ -644,6 +646,7 @@ fn rollback_drops_optimistic_contribution() {
10,
1_000,
None,
+ vec![],
))
.unwrap();
let InitialMutationClaimWire::Claimed { mutation: claimed } = optimistic.initial_claim else {
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine/test/calendar.rs b/apps/web/tauri/graphql_cache_plugin/src/engine/test/calendar.rs
new file mode 100644
index 0000000000..af3e7058f8
--- /dev/null
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/test/calendar.rs
@@ -0,0 +1,83 @@
+use super::*;
+use cache_core::calendar::{CalendarCommit, CalendarRangeRequest};
+
+fn week() -> CalendarRangeRequest {
+ serde_json::from_value(serde_json::json!({
+ "startMs": 1_791_158_400_000_i64,
+ "endMs": 1_791_763_200_000_i64,
+ "startDay": 20_731,
+ "endDay": 20_738,
+ }))
+ .unwrap()
+}
+
+fn range(handle: &EngineHandle) -> serde_json::Value {
+ serde_json::to_value(block_on(handle.calendar_range(week())).unwrap()).unwrap()
+}
+
+#[test]
+fn calendar_range_and_commit_cross_the_ipc_boundary() {
+ let handle = spawn_handle();
+ let empty = range(&handle);
+ assert_eq!(empty["kind"], "range");
+ assert_eq!(empty["occurrenceKeys"], serde_json::json!([]));
+ assert_eq!(
+ empty["gaps"],
+ serde_json::json!([
+ { "kind": "timed", "start": 1_791_158_400_000_i64, "end": 1_791_763_200_000_i64 },
+ { "kind": "allDay", "start": 20_731, "end": 20_738 },
+ ])
+ );
+ assert_eq!(empty["watermark"], serde_json::Value::Null);
+
+ let commit: CalendarCommit = serde_json::from_value(serde_json::json!({
+ "coverage": empty["gaps"],
+ "watermark": { "kind": "merge", "links": [{ "linkId": "l1", "seq": "3" }] },
+ "freshness": "stale",
+ }))
+ .unwrap();
+ let committed = block_on(handle.calendar_commit(commit)).unwrap();
+ assert!(committed.revision_advanced);
+ assert!(committed.changed.is_empty());
+
+ block_on(handle.enqueue_optimistic_mutation(
+ None,
+ "00000000-0000-4000-8000-0000000000c1".to_string(),
+ QUERY.to_string(),
+ Some("Soup".to_string()),
+ variables(),
+ soup_data(false),
+ vec![],
+ vec![],
+ vec![],
+ 0,
+ "runner".to_string(),
+ 10,
+ 1_000,
+ None,
+ vec!["GraphqlCalendarEvent:e1".to_string()],
+ ))
+ .unwrap();
+ let covered = range(&handle);
+ assert_eq!(covered["gaps"], serde_json::json!([]));
+ assert_eq!(covered["freshness"], "stale");
+ assert_eq!(
+ covered["watermark"],
+ serde_json::json!([{ "linkId": "l1", "seq": "3" }])
+ );
+ assert_eq!(
+ covered["uncertainEventKeys"],
+ serde_json::json!(["GraphqlCalendarEvent:e1"])
+ );
+ assert_eq!(covered["optimistic"], true);
+}
+
+#[test]
+fn invalid_calendar_commits_are_rejected() {
+ let handle = spawn_handle();
+ let commit: CalendarCommit = serde_json::from_value(serde_json::json!({
+ "deletedEventKeys": ["GraphqlCalendar:c1"],
+ }))
+ .unwrap();
+ assert!(block_on(handle.calendar_commit(commit)).is_err());
+}
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine/test/soup.rs b/apps/web/tauri/graphql_cache_plugin/src/engine/test/soup.rs
index e76aceda2e..7bc608658f 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine/test/soup.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/test/soup.rs
@@ -268,6 +268,7 @@ fn enqueue_archive(handle: &EngineHandle, n: u16) -> (String, String) {
10,
1000,
None,
+ vec![],
))
.unwrap();
let InitialMutationClaimWire::Claimed { mutation } = result.initial_claim else {
diff --git a/apps/web/tauri/graphql_cache_plugin/src/lib.rs b/apps/web/tauri/graphql_cache_plugin/src/lib.rs
index e7b8b95e92..b2bbf7fd77 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/lib.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/lib.rs
@@ -23,11 +23,11 @@ pub mod commands;
mod engine;
pub use engine::{
- AffectedOperationsResultWire, ClaimedMutationWire, CommitOptimisticWriteResultWire,
- DeferOptimisticWriteResultWire, EngineHandle, EnqueueOptimisticMutationResultWire,
- EntityFilterRequest, EntityFilterResult, InitialMutationClaimWire, PredicateBaselineEntry,
- PredicateFilterResult, ReadResultWire, RecordSelectionResultWire,
- RollbackOptimisticWriteResultWire, WriteResultWire,
+ AffectedOperationsResultWire, CalendarRangeResultWire, ClaimedMutationWire,
+ CommitOptimisticWriteResultWire, DeferOptimisticWriteResultWire, EngineHandle,
+ EnqueueOptimisticMutationResultWire, EntityFilterRequest, EntityFilterResult,
+ InitialMutationClaimWire, PredicateBaselineEntry, PredicateFilterResult, ReadResultWire,
+ RecordSelectionResultWire, RollbackOptimisticWriteResultWire, WriteResultWire,
};
/// Broadcast event carrying [`OpsAffectedEvent`]: operations whose
diff --git a/apps/web/tauri/src-tauri/src/lib.rs b/apps/web/tauri/src-tauri/src/lib.rs
index 038caa1c91..5cd7a28c4e 100644
--- a/apps/web/tauri/src-tauri/src/lib.rs
+++ b/apps/web/tauri/src-tauri/src/lib.rs
@@ -276,6 +276,8 @@ pub fn run() {
graphql_cache_plugin::commands::graphql_cache_read_records_by_keys,
graphql_cache_plugin::commands::graphql_cache_search,
graphql_cache_plugin::commands::graphql_cache_entity_filter,
+ graphql_cache_plugin::commands::graphql_cache_calendar_range,
+ graphql_cache_plugin::commands::graphql_cache_calendar_commit,
graphql_cache_plugin::commands::graphql_cache_write,
graphql_cache_plugin::commands::graphql_cache_hydrate,
graphql_cache_plugin::commands::graphql_cache_enqueue_optimistic_mutation,
diff --git a/crates/client/cache-wasm/Cargo.toml b/crates/client/cache-wasm/Cargo.toml
index 7bc1c0f802..17a6b58579 100644
--- a/crates/client/cache-wasm/Cargo.toml
+++ b/crates/client/cache-wasm/Cargo.toml
@@ -4,7 +4,8 @@ name = "cache-wasm"
publish = false
# Rebuild for reminder return timestamps in the local Mail index.
# Rebuild with the calendar range index and the compatibility epoch 4 storage name.
-version = "0.6.40"
+# Expose calendarRange, calendarCommit, and uncertain calendar events on enqueue.
+version = "0.6.41"
[features]
default = []
diff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rs
index 078e30bac8..ce5b0374ea 100644
--- a/crates/client/cache-wasm/src/shell.rs
+++ b/crates/client/cache-wasm/src/shell.rs
@@ -40,6 +40,7 @@ use turso_opfs::{OpenResult, OpfsError, OpfsErrorKind, OpfsOwner};
use wasm_bindgen::prelude::*;
use wasm_bindgen_futures::{JsFuture, future_to_promise};
+mod calendar;
#[cfg(test)]
mod test;
#[cfg(test)]
@@ -1674,6 +1675,7 @@ impl CacheEngine {
now_ms: f64,
lease_expires_at_ms: f64,
client_metadata: JsValue,
+ uncertain_calendar_event_keys: JsValue,
) -> js_sys::Promise {
let state = self.state.clone();
let ops = self.ops.clone();
@@ -1688,6 +1690,8 @@ impl CacheEngine {
let revalidations: Vec<QueryRevalidation> = parse_vec(revalidations)?;
let identity_bindings: Vec<cache_core::identity::IdentityBinding> =
parse_vec(identity_bindings)?;
+ let uncertain_calendar_event_keys: Vec<EntityKey<'static>> =
+ parse_vec(uncertain_calendar_event_keys)?;
let created_at_ms = parse_timestamp(created_at_ms, "enqueue timestamp")?;
let mut projection_mutations = optimistic_projection_mutations(&data, created_at_ms);
projection_mutations.extend(
@@ -1747,7 +1751,7 @@ impl CacheEngine {
let origin = origin_op_id.map(|name| ops.borrow_mut().intern(&name));
let result = state
.engine_mut()?
- .enqueue_optimistic_mutation_with_projections(
+ .enqueue_optimistic_mutation_with_calendar(
origin,
BeginOptimisticWrite {
client_metadata: client_metadata.as_ref(),
@@ -1763,6 +1767,7 @@ impl CacheEngine {
},
claim,
projection_mutations,
+ uncertain_calendar_event_keys,
)
.await;
let result = state.engine_result(result)?;
diff --git a/crates/client/cache-wasm/src/shell/calendar.rs b/crates/client/cache-wasm/src/shell/calendar.rs
new file mode 100644
index 0000000000..176f32bce4
--- /dev/null
+++ b/crates/client/cache-wasm/src/shell/calendar.rs
@@ -0,0 +1,55 @@
+//! Calendar range reads and commits over the local range index.
+
+use super::{CacheEngine, err_js, js_write_result, to_js};
+use cache_core::calendar::{CalendarCommit, CalendarRangeRequest, CalendarRangeResult};
+use serde::Serialize;
+use wasm_bindgen::prelude::*;
+use wasm_bindgen_futures::future_to_promise;
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(super) struct JsCalendarRangeResult {
+ pub(super) kind: &'static str,
+ pub(super) revision: String,
+ #[serde(flatten)]
+ pub(super) result: CalendarRangeResult,
+}
+
+#[wasm_bindgen]
+impl CacheEngine {
+ /// Answers a calendar viewport from cached occurrences, reporting the
+ /// spans that were never fetched and the applied change watermark.
+ #[wasm_bindgen(js_name = calendarRange)]
+ pub fn calendar_range(&self, request: JsValue) -> js_sys::Promise {
+ let state = self.state.clone();
+ future_to_promise(async move {
+ let mut state = state.lock().await;
+ state.ensure_callable()?;
+ let request: CalendarRangeRequest =
+ serde_wasm_bindgen::from_value(request).map_err(err_js)?;
+ let result = state.engine_mut()?.calendar_range(&request).await;
+ let result = state.engine_result(result)?;
+ to_js(&JsCalendarRangeResult {
+ kind: "range",
+ revision: result.revision.to_string(),
+ result: result.value,
+ })
+ })
+ }
+
+ /// Atomically applies fetched coverage, delta deletions, and sync state.
+ /// Resolves like `writeQuery` so hosts fan out the deleted records.
+ #[wasm_bindgen(js_name = calendarCommit)]
+ pub fn calendar_commit(&self, commit: JsValue) -> js_sys::Promise {
+ let state = self.state.clone();
+ let ops = self.ops.clone();
+ future_to_promise(async move {
+ let mut state = state.lock().await;
+ state.ensure_callable()?;
+ let commit: CalendarCommit = serde_wasm_bindgen::from_value(commit).map_err(err_js)?;
+ let result = state.engine_mut()?.calendar_commit(&commit).await;
+ let result = state.engine_result(result)?;
+ to_js(&js_write_result(result, &ops.borrow()))
+ })
+ }
+}
diff --git a/crates/client/cache-wasm/src/shell/test.rs b/crates/client/cache-wasm/src/shell/test.rs
index 82edcd32bd..fbc6d79df3 100644
--- a/crates/client/cache-wasm/src/shell/test.rs
+++ b/crates/client/cache-wasm/src/shell/test.rs
@@ -1397,6 +1397,7 @@ async fn optimistic_v2_patch_is_filterable_after_enqueue_reopen_and_rollback() {
0.0,
100.0,
js(serde_json::json!({"draftRevision": 10})),
+ JsValue::UNDEFINED,
))
.await,
);
@@ -1540,6 +1541,7 @@ async fn queue_and_optimistic_layers_survive_preserve_reopen_in_id_order() {
0.0,
50.0,
JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
))
.await,
);
@@ -1563,6 +1565,7 @@ async fn queue_and_optimistic_layers_survive_preserve_reopen_in_id_order() {
0.0,
50.0,
JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
))
.await,
);
@@ -1668,6 +1671,7 @@ async fn optimistic_commit_reports_affected_ops_and_rejects_settled_or_malformed
10.0,
1_000.0,
JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
))
.await,
);
@@ -1768,6 +1772,7 @@ async fn destroy_recovery_wipes_records_and_queue() {
0.0,
100.0,
JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
))
.await;
resolved(engine.close()).await;
@@ -1986,6 +1991,7 @@ async fn storage_reset_errors_latch_and_block_hot_read_write_and_control_methods
0.0,
100.0,
JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
))
.await;
assert_reset_required(engine.bound_identity()).await;
@@ -2100,6 +2106,7 @@ async fn physical_reset_serializes_recreates_and_preserves_interner_registration
0.0,
100.0,
JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
))
.await;
@@ -2221,6 +2228,7 @@ async fn every_method_rejects_after_consuming_close() {
1.0,
2.0,
JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
))
.await;
assert_closed(engine.inspect_query_variants(
@@ -2573,6 +2581,7 @@ async fn queue_one_mutation(engine: &CacheEngine) {
0.0,
100.0,
JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
))
.await;
}
@@ -2713,3 +2722,88 @@ async fn stale_databases_are_removed_only_when_unused_and_empty() {
remove_opfs_pair(&queued).await;
remove_opfs_pair(&own).await;
}
+
+#[wasm_bindgen_test(async)]
+async fn calendar_ranges_report_gaps_watermarks_and_uncertain_events_across_the_js_boundary() {
+ const SCOPE: &str = "cache-wasm-calendar-range";
+ let engine = fresh_engine(SCOPE).await;
+ // 2026-10-05T00:00:00Z through 2026-10-12.
+ let week = serde_json::json!({
+ "startMs": 1_791_158_400_000_i64,
+ "endMs": 1_791_763_200_000_i64,
+ "startDay": 20_731,
+ "endDay": 20_738,
+ });
+ let week_spans = serde_json::json!([
+ { "kind": "timed", "start": 1_791_158_400_000_i64, "end": 1_791_763_200_000_i64 },
+ { "kind": "allDay", "start": 20_731, "end": 20_738 },
+ ]);
+
+ let empty: serde_json::Value = from_js(resolved(engine.calendar_range(js(week.clone()))).await);
+ assert_eq!(
+ empty,
+ serde_json::json!({
+ "kind": "range",
+ "revision": empty["revision"],
+ "occurrenceKeys": [],
+ "gaps": week_spans,
+ "freshness": "unknown",
+ "uncertainEventKeys": [],
+ "optimistic": false,
+ "watermark": null,
+ })
+ );
+
+ let commit: serde_json::Value = from_js(
+ resolved(engine.calendar_commit(js(serde_json::json!({
+ "coverage": week_spans,
+ "watermark": { "kind": "merge", "links": [{ "linkId": "l1", "seq": "7" }] },
+ "freshness": "fresh",
+ }))))
+ .await,
+ );
+ assert_eq!(commit["revisionAdvanced"], true);
+ assert_eq!(commit["changed"], serde_json::json!([]));
+
+ resolved(engine.enqueue_optimistic_mutation(
+ None,
+ "00000000-0000-4000-8000-0000000000c1".into(),
+ PROPERTY_MUTATION.into(),
+ Some("SetEntityProperty".into()),
+ js(mutation_variables()),
+ js(serde_json::json!({
+ "setEntityProperty": { "id": "prop-1", "displayName": "Moved" }
+ })),
+ JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
+ 0.0,
+ "runner".into(),
+ 0.0,
+ 100.0,
+ JsValue::UNDEFINED,
+ js(serde_json::json!(["GraphqlCalendarEvent:e1"])),
+ ))
+ .await;
+ let covered: serde_json::Value = from_js(resolved(engine.calendar_range(js(week))).await);
+ assert_eq!(covered["gaps"], serde_json::json!([]));
+ assert_eq!(covered["freshness"], "fresh");
+ assert_eq!(
+ covered["watermark"],
+ serde_json::json!([{ "linkId": "l1", "seq": "7" }])
+ );
+ assert_eq!(
+ covered["uncertainEventKeys"],
+ serde_json::json!(["GraphqlCalendarEvent:e1"])
+ );
+ assert_eq!(covered["optimistic"], true);
+
+ assert!(
+ JsFuture::from(engine.calendar_commit(js(serde_json::json!({
+ "deletedEventKeys": ["GraphqlCalendar:c1"],
+ }))))
+ .await
+ .is_err()
+ );
+ close_and_destroy(&engine, SCOPE).await;
+}
diff --git a/crates/client/cache-wasm/src/shell/test/mail_projection.rs b/crates/client/cache-wasm/src/shell/test/mail_projection.rs
index 9b454df95a..e4e1b0b678 100644
--- a/crates/client/cache-wasm/src/shell/test/mail_projection.rs
+++ b/crates/client/cache-wasm/src/shell/test/mail_projection.rs
@@ -32,6 +32,7 @@ fn enqueue(engine: &CacheEngine) -> js_sys::Promise {
1.0,
100.0,
JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
)
}
diff --git a/crates/client/cache-wasm/src/shell/test_storage.rs b/crates/client/cache-wasm/src/shell/test_storage.rs
index 4f1c3cea14..468851cdd2 100644
--- a/crates/client/cache-wasm/src/shell/test_storage.rs
+++ b/crates/client/cache-wasm/src/shell/test_storage.rs
@@ -1,3 +1,7 @@
+use cache_core::calendar::{
+ CalendarCommit, CalendarCommitOutcome, CalendarRangeRequest, CalendarRangeSnapshot,
+ CalendarRangeStorage,
+};
use cache_core::predicate::{
OptimisticShadowReconciliation, OptimisticUpsertReconciliation, PredicateIndexStorage,
PredicateQueryResult, ProjectionMutation, ProjectionState,
@@ -258,3 +262,19 @@ impl PredicateIndexStorage for BrowserStorage {
self.inner.query_predicate_index(query).await
}
}
+
+impl CalendarRangeStorage for BrowserStorage {
+ async fn query_calendar_ranges(
+ &self,
+ request: &CalendarRangeRequest,
+ ) -> Result<CalendarRangeSnapshot, Self::Error> {
+ self.inner.query_calendar_ranges(request).await
+ }
+
+ async fn calendar_commit(
+ &mut self,
+ commit: &CalendarCommit,
+ ) -> Result<CalendarCommitOutcome, Self::Error> {
+ self.inner.calendar_commit(commit).await
+ }
+}