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): add the calendar range index, coverage map and calendarRange/calendarCommit (#7676)

gbirman294e670fcdc9
diff --git a/Cargo.lock b/Cargo.lock
index 7284db5bca..0f7d736468 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3433,6 +3433,7 @@ name = "cache-turso"
version = "0.1.0"
dependencies = [
"cache-core",
+ "chrono",
"maybe_send",
"pollster",
"predicate-index",
@@ -3447,7 +3448,7 @@ dependencies = [
[[package]]
name = "cache-wasm"
-version = "0.6.39"
+version = "0.6.40"
dependencies = [
"async-lock",
"cache-core",
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 f51e380480..3cab87f5c0 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
@@ -725,13 +725,13 @@ describe('coordinator runtime protocol', () => {
});
it('derives the exact UTF-8 canonical turso-opfs lock name', () => {
- // The current versions keep the unversioned name, and so the lock that
- // builds before versioned names hold.
+ // The current versions moved past the unversioned name, so the lock
+ // names the versioned database that builds before them never held.
expect(databaseOwnerLockName('scope')).toBe(
- 'macro:turso-opfs:v1:19:graphql-cache:scope'
+ 'macro:turso-opfs:v1:29:graphql-cache:scope:s4.v3.t11'
);
expect(databaseOwnerLockName('é')).toBe(
- 'macro:turso-opfs:v1:16:graphql-cache:é'
+ 'macro:turso-opfs:v1:26:graphql-cache:é:s4.v3.t11'
);
});
@@ -781,13 +781,10 @@ describe('coordinator runtime protocol', () => {
const own = cacheDatabaseIdentity('a');
const versioned = (storage: number): string =>
`graphql-cache:a:s${schemaCompatibilityEpoch}.v${formatVersion}.t${storage}`;
- // The current versions still open the unversioned name.
- expect(own).toBe('graphql-cache:a');
+ // The current versions moved past the unversioned name.
+ expect(own).toBe(versioned(storageSchemaVersion));
expect(isStaleCacheDatabaseIdentity('a', own)).toBe(false);
- // Another spelling of this build's own versions is never opened again.
- expect(
- isStaleCacheDatabaseIdentity('a', versioned(storageSchemaVersion))
- ).toBe(true);
+ expect(isStaleCacheDatabaseIdentity('a', 'graphql-cache:a')).toBe(true);
expect(isStaleCacheDatabaseIdentity('a', 'graphql-cache:a:s1.v2.t3')).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 fdd6d87e14..820b3395f6 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
@@ -1328,7 +1328,7 @@ export function tabIdFromLivenessLockName(
* and the engine checks its WASM before touching storage.
*/
export const CACHE_STORAGE_VERSION = {
- schemaCompatibilityEpoch: 3,
+ schemaCompatibilityEpoch: 4,
formatVersion: 3,
storageSchemaVersion: 11,
} as const;
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-takeover.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-takeover.test.ts
index 305600b3a1..f56099eb7d 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-takeover.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-takeover.test.ts
@@ -26,7 +26,7 @@ describe('cache takeover messages', () => {
`graphql-cache-takeover:${cacheDatabaseIdentity('scope')}`
);
expect(cacheTakeoverChannelName('scope')).toBe(
- 'graphql-cache-takeover:graphql-cache:scope'
+ 'graphql-cache-takeover:graphql-cache:scope:s4.v3.t11'
);
});
diff --git a/apps/web/src/lib/queries/soup/backfill.test.tsx b/apps/web/src/lib/queries/soup/backfill.test.tsx
index 0fb75fca6c..a631c37391 100644
--- a/apps/web/src/lib/queries/soup/backfill.test.tsx
+++ b/apps/web/src/lib/queries/soup/backfill.test.tsx
@@ -103,7 +103,7 @@ function seedCheckpoint(overrides: Partial<SoupBackfillCheckpoint> = {}) {
...overrides,
};
localStorage.setItem(
- 'graphql-soup-backfill:v16:user-1:core-entities',
+ 'graphql-soup-backfill:v17:user-1:core-entities',
JSON.stringify(checkpoint)
);
}
@@ -790,7 +790,7 @@ describe('runSoupBackfills', () => {
rendered.unmount();
});
- it.each([13, 14, 15])(
+ it.each([13, 14, 15, 16])(
'does not reuse v%i backfill checkpoints',
(version) => {
localStorage.setItem(
@@ -819,7 +819,7 @@ describe('runSoupBackfills', () => {
'restarts the runner with %s storage semantics and ignores obsolete completions',
async (storage) => {
localStorage.setItem(
- 'graphql-soup-backfill:v16:user-1:core-entities',
+ 'graphql-soup-backfill:v17:user-1:core-entities',
JSON.stringify({
userId: 'user-1',
storageGeneration: 'storage-1',
@@ -893,7 +893,7 @@ describe('runSoupBackfills', () => {
const watermark = '2026-09-01T00:00:00.000Z';
for (const checkpointId of ['core-entities', 'email-thread-pages']) {
localStorage.setItem(
- `graphql-soup-backfill:v16:user-1:${checkpointId}`,
+ `graphql-soup-backfill:v17:user-1:${checkpointId}`,
JSON.stringify({
userId: 'user-1',
storageGeneration: 'storage-1',
diff --git a/apps/web/src/lib/queries/soup/backfill.ts b/apps/web/src/lib/queries/soup/backfill.ts
index 73f15282e5..9033176cf6 100644
--- a/apps/web/src/lib/queries/soup/backfill.ts
+++ b/apps/web/src/lib/queries/soup/backfill.ts
@@ -29,7 +29,7 @@ import { createEffect, createSignal, onCleanup } from 'solid-js';
// persisted cursors cannot retain an older hydration contract.
// Rehydrate raw file-type projections after retiring enum-normalized facts.
// Old cursors must not skip records when the cache compatibility epoch changes.
-const BACKFILL_VERSION = 16;
+const BACKFILL_VERSION = 17;
const PAGE_LIMIT = 100;
// Five threads × twenty messages reaches the backend's 100-message cap.
const EMAIL_CONTENT_PAGE_LIMIT = 5;
diff --git a/crates/client/cache-core/src/calendar.rs b/crates/client/cache-core/src/calendar.rs
new file mode 100644
index 0000000000..74a8bb457c
--- /dev/null
+++ b/crates/client/cache-core/src/calendar.rs
@@ -0,0 +1,546 @@
+//! Local calendar range projection.
+//!
+//! Cached occurrence records are projected into compact span rows so a
+//! viewport can be answered without decoding every occurrence. A coverage map
+//! records which spans were fully fetched from the server, and a per-link
+//! change watermark records how far the delta stream has been applied.
+
+mod coverage;
+mod watermark;
+
+pub use coverage::{coverage_gaps, merge_spans};
+pub use watermark::{
+ CalendarLinkWatermark, CalendarWatermarkUpdate, apply_watermark_update, parse_watermark,
+ serialize_watermark,
+};
+
+use crate::identity::{ALIAS_FIELD, DELETED_FIELD};
+use crate::store::Storage;
+use crate::value::{CacheValue, EntityKey, Record};
+use chrono::NaiveDate;
+use maybe_send::MaybeSend;
+use serde::{Deserialize, Serialize};
+use std::collections::{BTreeMap, BTreeSet, HashMap};
+use thiserror::Error;
+
+/// Normalized typename of one calendar occurrence.
+pub const OCCURRENCE_TYPENAME: &str = "GraphqlCalendarOccurrence";
+/// Normalized typename of one calendar event.
+pub const EVENT_TYPENAME: &str = "GraphqlCalendarEvent";
+/// Normalized typename of one visible calendar.
+pub const CALENDAR_TYPENAME: &str = "GraphqlCalendar";
+
+const TIMED_TYPENAME: &str = "GraphqlTimedEventTime";
+const ALL_DAY_TYPENAME: &str = "GraphqlAllDayEventTime";
+
+/// Revision of the derived range rows. Storage adapters rebuild existing rows
+/// from normalized records when this changes; records and coverage stay valid.
+pub const CALENDAR_PROJECTION_VERSION: u32 = 1;
+
+/// Maximum number of keys, spans, and links accepted by one commit.
+pub const MAX_CALENDAR_COMMIT_ITEMS: usize = 20_000;
+
+const MS_PER_DAY: i64 = 86_400_000;
+const SHORT_SPAN_DAYS: i64 = 7;
+
+/// Unit of a calendar span.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum CalendarSpanKind {
+ /// UTC instants in milliseconds since the Unix epoch.
+ Timed,
+ /// Local dates in days since 1970-01-01.
+ AllDay,
+}
+
+impl CalendarSpanKind {
+ /// Stable value persisted by relational storage.
+ pub const fn code(self) -> i64 {
+ match self {
+ Self::Timed => 0,
+ Self::AllDay => 1,
+ }
+ }
+
+ /// Decodes a persisted kind.
+ pub const fn from_code(code: i64) -> Option<Self> {
+ match code {
+ 0 => Some(Self::Timed),
+ 1 => Some(Self::AllDay),
+ _ => None,
+ }
+ }
+
+ /// Longest span kept on the bounded-start scan path. Longer rows are
+ /// scanned separately so a short-span lookup can bound its start column.
+ pub const fn max_short_span(self) -> i64 {
+ match self {
+ Self::Timed => SHORT_SPAN_DAYS * MS_PER_DAY,
+ Self::AllDay => SHORT_SPAN_DAYS,
+ }
+ }
+}
+
+/// Half-open `[start, end)` span of one kind.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CalendarSpan {
+ /// Unit of `start` and `end`.
+ pub kind: CalendarSpanKind,
+ /// Inclusive start.
+ pub start: i64,
+ /// Exclusive end.
+ pub end: i64,
+}
+
+impl CalendarSpan {
+ /// Whether two spans of the same kind share any point.
+ pub fn overlaps(&self, other: &CalendarSpan) -> bool {
+ self.kind == other.kind && self.start < other.end && self.end > other.start
+ }
+}
+
+/// Compact projection of one cached occurrence.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct CalendarRangeRow {
+ /// Normalized occurrence key.
+ pub record_key: EntityKey<'static>,
+ /// Normalized key of the owning event.
+ pub event_key: EntityKey<'static>,
+ /// Email link whose change log owns the occurrence.
+ pub link_id: String,
+ /// Occurrence span.
+ pub span: CalendarSpan,
+}
+
+impl CalendarRangeRow {
+ /// Whether the row is scanned on the unbounded long-span path.
+ pub fn is_long(&self) -> bool {
+ self.span.end - self.span.start > self.span.kind.max_short_span()
+ }
+}
+
+/// Projects a fully merged occurrence record into its range row.
+///
+/// `None` means the record is not a visible occurrence (another type, deleted,
+/// aliased, cancelled, or missing a field the projection needs). Storage
+/// deletes any old row in that case, in the same transaction as the record.
+pub fn project_calendar_range(key: &EntityKey<'_>, record: &Record) -> Option<CalendarRangeRow> {
+ if key.typename() != Some(OCCURRENCE_TYPENAME)
+ || matches!(
+ record.fields.get(DELETED_FIELD),
+ Some(CacheValue::Bool(true))
+ )
+ || record.fields.contains_key(ALIAS_FIELD)
+ || matches!(
+ record.fields.get("isCancelled"),
+ Some(CacheValue::Bool(true))
+ )
+ {
+ return None;
+ }
+ let event_id = string_field(record, "eventId")?;
+ let link_id = string_field(record, "linkId")?;
+ let Some(CacheValue::Object(time)) = record.fields.get("time") else {
+ return None;
+ };
+ let span = project_time(time)?;
+ Some(CalendarRangeRow {
+ record_key: key.clone().into_owned(),
+ event_key: EntityKey::entity(EVENT_TYPENAME, &[event_id]),
+ link_id: link_id.to_owned(),
+ span,
+ })
+}
+
+fn project_time(time: &BTreeMap<String, CacheValue>) -> Option<CalendarSpan> {
+ let typename = match time.get("__typename") {
+ Some(CacheValue::String(typename)) => Some(typename.as_str()),
+ _ => None,
+ };
+ let text = |field: &str| match time.get(field) {
+ Some(CacheValue::String(value)) => Some(value.as_str()),
+ _ => None,
+ };
+ let timed = || {
+ Some(CalendarSpan {
+ kind: CalendarSpanKind::Timed,
+ start: parse_instant_ms(text("startsAt")?)?,
+ end: parse_instant_ms(text("endsAt")?)?,
+ })
+ };
+ let all_day = || {
+ Some(CalendarSpan {
+ kind: CalendarSpanKind::AllDay,
+ start: parse_epoch_day(text("startDate")?)?,
+ end: parse_epoch_day(text("endDate")?)?,
+ })
+ };
+ let span = match typename {
+ Some(TIMED_TYPENAME) => timed()?,
+ Some(ALL_DAY_TYPENAME) => all_day()?,
+ Some(_) => return None,
+ None => timed().or_else(all_day)?,
+ };
+ (span.end > span.start).then_some(span)
+}
+
+fn string_field<'a>(record: &'a Record, field: &str) -> Option<&'a str> {
+ match record.fields.get(field) {
+ Some(CacheValue::String(value)) if !value.is_empty() => Some(value),
+ _ => None,
+ }
+}
+
+fn parse_instant_ms(value: &str) -> Option<i64> {
+ chrono::DateTime::parse_from_rfc3339(value)
+ .ok()
+ .map(|instant| instant.timestamp_millis())
+}
+
+fn parse_epoch_day(value: &str) -> Option<i64> {
+ let epoch = NaiveDate::from_ymd_opt(1970, 1, 1)?;
+ NaiveDate::parse_from_str(value, "%Y-%m-%d")
+ .ok()
+ .map(|date| (date - epoch).num_days())
+}
+
+/// Global freshness of the locally applied change stream.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum CalendarFreshness {
+ /// The last delta reached the server's current watermark.
+ Fresh,
+ /// A change was signalled and has not been applied yet.
+ Stale,
+ /// No delta has ever been committed.
+ #[default]
+ Unknown,
+}
+
+impl CalendarFreshness {
+ /// Stable value persisted by relational storage.
+ pub const fn as_str(self) -> &'static str {
+ match self {
+ Self::Fresh => "fresh",
+ Self::Stale => "stale",
+ Self::Unknown => "unknown",
+ }
+ }
+
+ /// Decodes a persisted freshness value.
+ pub fn parse(value: &str) -> Option<Self> {
+ match value {
+ "fresh" => Some(Self::Fresh),
+ "stale" => Some(Self::Stale),
+ "unknown" => Some(Self::Unknown),
+ _ => None,
+ }
+ }
+}
+
+/// One viewport read over both span kinds, optionally limited to one event.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CalendarRangeRequest {
+ /// Inclusive UTC start of timed occurrences, in milliseconds.
+ pub start_ms: i64,
+ /// Exclusive UTC end of timed occurrences, in milliseconds.
+ pub end_ms: i64,
+ /// Inclusive local start date of all-day occurrences, in epoch days.
+ pub start_day: i64,
+ /// Exclusive local end date of all-day occurrences, in epoch days.
+ pub end_day: i64,
+ /// Restricts occurrences to one `GraphqlCalendarEvent` key.
+ #[serde(default)]
+ pub event_key: Option<EntityKey<'static>>,
+}
+
+impl CalendarRangeRequest {
+ /// The requested span of each kind.
+ pub fn spans(&self) -> [CalendarSpan; 2] {
+ [
+ CalendarSpan {
+ kind: CalendarSpanKind::Timed,
+ start: self.start_ms,
+ end: self.end_ms,
+ },
+ CalendarSpan {
+ kind: CalendarSpanKind::AllDay,
+ start: self.start_day,
+ end: self.end_day,
+ },
+ ]
+ }
+
+ /// Whether a projected row belongs to this request.
+ pub fn includes(&self, row: &CalendarRangeRow) -> bool {
+ self.event_key
+ .as_ref()
+ .is_none_or(|event_key| *event_key == row.event_key)
+ && self.spans().iter().any(|span| span.overlaps(&row.span))
+ }
+
+ /// Rejects inverted spans and foreign event keys. An empty span is valid
+ /// and reads only sync state.
+ pub fn validate(&self) -> Result<(), CalendarError> {
+ if self.start_ms > self.end_ms || self.start_day > self.end_day {
+ return Err(CalendarError::InvalidSpan);
+ }
+ if self
+ .event_key
+ .as_ref()
+ .is_some_and(|key| key.typename() != Some(EVENT_TYPENAME))
+ {
+ return Err(CalendarError::InvalidKey);
+ }
+ Ok(())
+ }
+}
+
+/// Persisted sync state shared by every range read.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct CalendarSyncState {
+ /// Applied per-link watermark, or `None` before the first commit carrying one.
+ pub watermark: Option<Vec<CalendarLinkWatermark>>,
+ /// Freshness of the applied change stream.
+ pub freshness: CalendarFreshness,
+}
+
+/// Authoritative storage state for one range read, taken in one read transaction.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct CalendarRangeSnapshot {
+ /// Authoritative rows matching the request.
+ pub rows: Vec<CalendarRangeRow>,
+ /// Coverage spans that overlap or touch the requested spans.
+ pub coverage: Vec<CalendarSpan>,
+ /// Persisted sync state.
+ pub sync: CalendarSyncState,
+}
+
+/// Result of one local range read.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CalendarRangeResult {
+ /// Effective occurrence keys in the range, ordered by kind, start, and key.
+ pub occurrence_keys: Vec<EntityKey<'static>>,
+ /// Requested spans that were never fetched from the server.
+ pub gaps: Vec<CalendarSpan>,
+ /// Freshness of the applied change stream.
+ pub freshness: CalendarFreshness,
+ /// Events whose effective occurrence set is unknown until a pending
+ /// mutation settles (for example a recurrence edit).
+ pub uncertain_event_keys: Vec<EntityKey<'static>>,
+ /// Whether a pending optimistic mutation shaped this result.
+ pub optimistic: bool,
+ /// Applied per-link watermark, or `None` before the first commit carrying one.
+ pub watermark: Option<Vec<CalendarLinkWatermark>>,
+}
+
+/// The complete current occurrence set of one event.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CalendarReplacedEvent {
+ /// Normalized event key.
+ pub event_key: EntityKey<'static>,
+ /// Every occurrence key the event currently has. Cached occurrences of the
+ /// event outside this set are deleted.
+ pub occurrence_keys: Vec<EntityKey<'static>>,
+}
+
+/// One atomic change to calendar coverage, cached calendar records, and sync state.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CalendarCommit {
+ /// Spans whose occurrences were fully fetched and written.
+ #[serde(default)]
+ pub coverage: Vec<CalendarSpan>,
+ /// Events whose occurrence sets are replaced wholesale.
+ #[serde(default)]
+ pub replaced_events: Vec<CalendarReplacedEvent>,
+ /// Events deleted with every cached occurrence.
+ #[serde(default)]
+ pub deleted_event_keys: Vec<EntityKey<'static>>,
+ /// Calendars deleted from the cache.
+ #[serde(default)]
+ pub deleted_calendar_keys: Vec<EntityKey<'static>>,
+ /// Email links no longer visible: their occurrences, events, and calendars are deleted.
+ #[serde(default)]
+ pub removed_link_ids: Vec<String>,
+ /// Watermark change applied after the deletions.
+ #[serde(default)]
+ pub watermark: Option<CalendarWatermarkUpdate>,
+ /// New freshness, `Fresh` or `Stale`.
+ #[serde(default)]
+ pub freshness: Option<CalendarFreshness>,
+ /// Deletes every cached occurrence and event, all coverage, and the
+ /// watermark before applying the rest of the commit.
+ #[serde(default)]
+ pub reset: bool,
+}
+
+impl CalendarCommit {
+ /// Validates keys, spans, and sync values before storage is touched.
+ pub fn validate(&self) -> Result<(), CalendarError> {
+ let items = self.coverage.len()
+ + self.deleted_event_keys.len()
+ + self.deleted_calendar_keys.len()
+ + self.removed_link_ids.len()
+ + self
+ .replaced_events
+ .iter()
+ .map(|event| event.occurrence_keys.len() + 1)
+ .sum::<usize>()
+ + self
+ .watermark
+ .as_ref()
+ .map_or(0, CalendarWatermarkUpdate::len);
+ if items > MAX_CALENDAR_COMMIT_ITEMS {
+ return Err(CalendarError::TooLarge);
+ }
+ if self.coverage.iter().any(|span| span.start > span.end) {
+ return Err(CalendarError::InvalidSpan);
+ }
+ let is_typed = |key: &EntityKey<'_>, typename| {
+ key.typename() == Some(typename) && key.id().is_some_and(|id| !id.is_empty())
+ };
+ let mut replaced = BTreeSet::new();
+ for event in &self.replaced_events {
+ if !is_typed(&event.event_key, EVENT_TYPENAME)
+ || !replaced.insert(&event.event_key)
+ || !event
+ .occurrence_keys
+ .iter()
+ .all(|key| is_typed(key, OCCURRENCE_TYPENAME))
+ {
+ return Err(CalendarError::InvalidKey);
+ }
+ }
+ if !self
+ .deleted_event_keys
+ .iter()
+ .all(|key| is_typed(key, EVENT_TYPENAME))
+ || !self
+ .deleted_calendar_keys
+ .iter()
+ .all(|key| is_typed(key, CALENDAR_TYPENAME))
+ || self.removed_link_ids.iter().any(String::is_empty)
+ {
+ return Err(CalendarError::InvalidKey);
+ }
+ if self.freshness == Some(CalendarFreshness::Unknown) {
+ return Err(CalendarError::InvalidFreshness);
+ }
+ self.watermark
+ .as_ref()
+ .map_or(Ok(()), CalendarWatermarkUpdate::validate)
+ }
+}
+
+/// Sync state after applying `commit` to `stored`.
+pub fn next_sync_state(stored: &CalendarSyncState, commit: &CalendarCommit) -> CalendarSyncState {
+ let base = if commit.reset {
+ CalendarSyncState::default()
+ } else {
+ stored.clone()
+ };
+ let watermark = (commit.watermark.is_some() || base.watermark.is_some()).then(|| {
+ apply_watermark_update(
+ base.watermark.as_deref(),
+ commit.watermark.as_ref(),
+ &commit.removed_link_ids,
+ )
+ });
+ CalendarSyncState {
+ watermark,
+ freshness: commit.freshness.unwrap_or(base.freshness),
+ }
+}
+
+/// Records removed by one calendar commit.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct CalendarCommitOutcome {
+ /// Normalized records deleted from storage.
+ pub deleted_keys: Vec<EntityKey<'static>>,
+}
+
+/// Calendar request validation errors.
+#[derive(Clone, Copy, Debug, Error, PartialEq, Eq)]
+pub enum CalendarError {
+ /// A span ends before it starts.
+ #[error("calendar span ends before it starts")]
+ InvalidSpan,
+ /// A key does not name the expected calendar typename.
+ #[error("invalid calendar cache key")]
+ InvalidKey,
+ /// A watermark entry is malformed or duplicated.
+ #[error("invalid calendar watermark")]
+ InvalidWatermark,
+ /// Freshness can only be committed as fresh or stale.
+ #[error("calendar freshness must be fresh or stale")]
+ InvalidFreshness,
+ /// The commit exceeds [`MAX_CALENDAR_COMMIT_ITEMS`].
+ #[error("calendar commit has more than {MAX_CALENDAR_COMMIT_ITEMS} items")]
+ TooLarge,
+}
+
+/// Composes authoritative rows with the optimistic overlay.
+///
+/// `overlay` holds every occurrence key touched by an active optimistic layer,
+/// mapped to its effective row (`None` when the effective record is hidden).
+/// Overlaid keys replace their authoritative rows. Returns ordered keys and
+/// whether the overlay shaped the result.
+pub fn compose_calendar_rows(
+ request: &CalendarRangeRequest,
+ authoritative: Vec<CalendarRangeRow>,
+ overlay: &HashMap<EntityKey<'static>, Option<CalendarRangeRow>>,
+) -> (Vec<EntityKey<'static>>, bool) {
+ let mut optimistic = false;
+ let mut rows = Vec::with_capacity(authoritative.len());
+ for row in authoritative {
+ if overlay.contains_key(&row.record_key) {
+ optimistic = true;
+ } else {
+ rows.push(row);
+ }
+ }
+ for row in overlay.values().flatten() {
+ if request.includes(row) {
+ optimistic = true;
+ rows.push(row.clone());
+ }
+ }
+ rows.sort_by(|left, right| {
+ (left.span.kind, left.span.start, &left.record_key).cmp(&(
+ right.span.kind,
+ right.span.start,
+ &right.record_key,
+ ))
+ });
+ rows.dedup_by(|left, right| left.record_key == right.record_key);
+ (
+ rows.into_iter().map(|row| row.record_key).collect(),
+ optimistic,
+ )
+}
+
+/// Storage capability for the calendar range projection.
+///
+/// Implementations write range rows in the same transaction as every
+/// normalized record write and delete, exactly like search documents.
+pub trait CalendarRangeStorage: Storage {
+ /// Reads rows, coverage, and sync state for one request in one read transaction.
+ fn query_calendar_ranges(
+ &self,
+ request: &CalendarRangeRequest,
+ ) -> impl Future<Output = Result<CalendarRangeSnapshot, Self::Error>> + MaybeSend;
+
+ /// Applies a validated commit in one write transaction.
+ fn calendar_commit(
+ &mut self,
+ commit: &CalendarCommit,
+ ) -> impl Future<Output = Result<CalendarCommitOutcome, Self::Error>> + MaybeSend;
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/client/cache-core/src/calendar/coverage.rs b/crates/client/cache-core/src/calendar/coverage.rs
new file mode 100644
index 0000000000..6695faa011
--- /dev/null
+++ b/crates/client/cache-core/src/calendar/coverage.rs
@@ -0,0 +1,64 @@
+//! Pure interval math over fetched-range coverage.
+
+use super::CalendarSpan;
+
+/// Merges spans per kind into sorted, disjoint, non-adjacent spans. Empty
+/// spans are dropped.
+pub fn merge_spans(spans: impl IntoIterator<Item = CalendarSpan>) -> Vec<CalendarSpan> {
+ let mut spans = spans
+ .into_iter()
+ .filter(|span| span.end > span.start)
+ .collect::<Vec<_>>();
+ spans.sort();
+ let mut merged: Vec<CalendarSpan> = Vec::with_capacity(spans.len());
+ for span in spans {
+ match merged.last_mut() {
+ Some(last) if last.kind == span.kind && span.start <= last.end => {
+ last.end = last.end.max(span.end);
+ }
+ _ => merged.push(span),
+ }
+ }
+ merged
+}
+
+/// Returns the parts of `request` that no coverage span of the same kind covers.
+pub fn coverage_gaps(coverage: &[CalendarSpan], request: CalendarSpan) -> Vec<CalendarSpan> {
+ if request.end <= request.start {
+ return Vec::new();
+ }
+ let mut gaps = Vec::new();
+ let mut cursor = request.start;
+ for span in merge_spans(
+ coverage
+ .iter()
+ .copied()
+ .filter(|span| span.kind == request.kind),
+ ) {
+ if span.end <= cursor {
+ continue;
+ }
+ if span.start >= request.end {
+ break;
+ }
+ if span.start > cursor {
+ gaps.push(CalendarSpan {
+ kind: request.kind,
+ start: cursor,
+ end: span.start,
+ });
+ }
+ cursor = span.end;
+ if cursor >= request.end {
+ break;
+ }
+ }
+ if cursor < request.end {
+ gaps.push(CalendarSpan {
+ kind: request.kind,
+ start: cursor,
+ end: request.end,
+ });
+ }
+ gaps
+}
diff --git a/crates/client/cache-core/src/calendar/test.rs b/crates/client/cache-core/src/calendar/test.rs
new file mode 100644
index 0000000000..4c49e564b8
--- /dev/null
+++ b/crates/client/cache-core/src/calendar/test.rs
@@ -0,0 +1,497 @@
+use super::*;
+use std::collections::{BTreeMap, HashMap};
+
+fn key(value: &str) -> EntityKey<'static> {
+ EntityKey(value.to_owned().into())
+}
+
+fn text(value: &str) -> CacheValue {
+ CacheValue::String(value.into())
+}
+
+fn time(fields: &[(&str, &str)]) -> CacheValue {
+ CacheValue::Object(
+ fields
+ .iter()
+ .map(|(field, value)| ((*field).to_owned(), text(value)))
+ .collect::<BTreeMap<_, _>>(),
+ )
+}
+
+fn occurrence(time_value: CacheValue) -> Record {
+ let mut record = Record::default();
+ record
+ .fields
+ .insert("__typename".into(), text(OCCURRENCE_TYPENAME));
+ record.fields.insert("eventId".into(), text("e1"));
+ record.fields.insert("linkId".into(), text("l1"));
+ record
+ .fields
+ .insert("isCancelled".into(), CacheValue::Bool(false));
+ record.fields.insert("time".into(), time_value);
+ record
+}
+
+fn timed(starts_at: &str, ends_at: &str) -> CacheValue {
+ time(&[
+ ("__typename", "GraphqlTimedEventTime"),
+ ("startsAt", starts_at),
+ ("endsAt", ends_at),
+ ])
+}
+
+fn all_day(start_date: &str, end_date: &str) -> CacheValue {
+ time(&[
+ ("__typename", "GraphqlAllDayEventTime"),
+ ("startDate", start_date),
+ ("endDate", end_date),
+ ])
+}
+
+fn span(kind: CalendarSpanKind, start: i64, end: i64) -> CalendarSpan {
+ CalendarSpan { kind, start, end }
+}
+
+fn timed_span(start: i64, end: i64) -> CalendarSpan {
+ span(CalendarSpanKind::Timed, start, end)
+}
+
+fn link(link_id: &str, seq: i64) -> CalendarLinkWatermark {
+ CalendarLinkWatermark {
+ link_id: link_id.into(),
+ seq,
+ }
+}
+
+fn row(record_key: &str, event: &str, span: CalendarSpan) -> CalendarRangeRow {
+ CalendarRangeRow {
+ record_key: key(record_key),
+ event_key: EntityKey::entity(EVENT_TYPENAME, &[event]),
+ link_id: "l1".into(),
+ span,
+ }
+}
+
+fn request(start_ms: i64, end_ms: i64) -> CalendarRangeRequest {
+ CalendarRangeRequest {
+ start_ms,
+ end_ms,
+ start_day: 0,
+ end_day: 0,
+ event_key: None,
+ }
+}
+
+#[test]
+fn projects_timed_and_all_day_occurrences() {
+ let occurrence_key = key("GraphqlCalendarOccurrence:e1:2026-10-06T12:00:00+00:00");
+ let projected = project_calendar_range(
+ &occurrence_key,
+ &occurrence(timed(
+ "2026-10-06T12:00:00+00:00",
+ "2026-10-06T13:30:00+00:00",
+ )),
+ )
+ .unwrap();
+ assert_eq!(projected.record_key, occurrence_key);
+ assert_eq!(projected.event_key.as_ref(), "GraphqlCalendarEvent:e1");
+ assert_eq!(projected.link_id, "l1");
+ assert_eq!(
+ projected.span,
+ timed_span(1_791_288_000_000, 1_791_293_400_000)
+ );
+ assert!(!projected.is_long());
+
+ let projected = project_calendar_range(
+ &key("GraphqlCalendarOccurrence:e1:2026-10-06"),
+ &occurrence(all_day("2026-10-06", "2026-10-07")),
+ )
+ .unwrap();
+ assert_eq!(
+ projected.span,
+ span(CalendarSpanKind::AllDay, 20_732, 20_733)
+ );
+
+ // Offsets are normalized to UTC instants.
+ let projected = project_calendar_range(
+ &occurrence_key,
+ &occurrence(timed(
+ "2026-10-06T08:00:00-04:00",
+ "2026-10-06T09:00:00-04:00",
+ )),
+ )
+ .unwrap();
+ assert_eq!(projected.span.start, 1_791_288_000_000);
+}
+
+#[test]
+fn infers_the_time_kind_without_a_typename_and_flags_long_spans() {
+ let projected = project_calendar_range(
+ &key("GraphqlCalendarOccurrence:e1:k"),
+ &occurrence(time(&[
+ ("startDate", "2026-10-01"),
+ ("endDate", "2026-10-09"),
+ ])),
+ )
+ .unwrap();
+ assert_eq!(projected.span.kind, CalendarSpanKind::AllDay);
+ assert!(projected.is_long());
+
+ let projected = project_calendar_range(
+ &key("GraphqlCalendarOccurrence:e1:k"),
+ &occurrence(timed("2026-10-01T00:00:00Z", "2026-10-08T00:00:00Z")),
+ )
+ .unwrap();
+ assert!(!projected.is_long(), "exactly seven days stays short");
+}
+
+#[test]
+fn hidden_or_incomplete_occurrences_do_not_project() {
+ let occurrence_key = key("GraphqlCalendarOccurrence:e1:k");
+ let valid = occurrence(timed("2026-10-06T12:00:00Z", "2026-10-06T13:00:00Z"));
+ assert!(project_calendar_range(&occurrence_key, &valid).is_some());
+ assert!(project_calendar_range(&key("GraphqlCalendarEvent:e1"), &valid).is_none());
+
+ let hidden = [
+ (DELETED_FIELD, CacheValue::Bool(true)),
+ (ALIAS_FIELD, text("GraphqlCalendarOccurrence:server")),
+ ("isCancelled", CacheValue::Bool(true)),
+ ("eventId", CacheValue::Null),
+ ("linkId", text("")),
+ ("time", CacheValue::Null),
+ (
+ "time",
+ timed("2026-10-06T13:00:00Z", "2026-10-06T13:00:00Z"),
+ ),
+ ("time", timed("not a date", "2026-10-06T13:00:00Z")),
+ (
+ "time",
+ time(&[("__typename", "Unknown"), ("startDate", "2026-10-06")]),
+ ),
+ ];
+ for (field, value) in hidden {
+ let mut record = valid.clone();
+ record.fields.insert(field.into(), value);
+ assert!(
+ project_calendar_range(&occurrence_key, &record).is_none(),
+ "{field} should hide the occurrence"
+ );
+ }
+}
+
+#[test]
+fn merges_spans_per_kind_including_adjacent_spans() {
+ let merged = merge_spans([
+ timed_span(10, 20),
+ timed_span(0, 5),
+ timed_span(20, 30),
+ timed_span(4, 8),
+ timed_span(40, 40),
+ span(CalendarSpanKind::AllDay, 0, 10),
+ span(CalendarSpanKind::AllDay, 5, 6),
+ ]);
+ assert_eq!(
+ merged,
+ [
+ timed_span(0, 8),
+ timed_span(10, 30),
+ span(CalendarSpanKind::AllDay, 0, 10),
+ ]
+ );
+}
+
+#[test]
+fn gaps_are_the_uncovered_parts_of_the_request() {
+ let coverage = [
+ timed_span(10, 20),
+ timed_span(30, 40),
+ span(CalendarSpanKind::AllDay, 0, 100),
+ ];
+ assert_eq!(
+ coverage_gaps(&coverage, timed_span(0, 50)),
+ [timed_span(0, 10), timed_span(20, 30), timed_span(40, 50)]
+ );
+ assert_eq!(coverage_gaps(&coverage, timed_span(12, 18)), []);
+ assert_eq!(
+ coverage_gaps(&coverage, timed_span(15, 35)),
+ [timed_span(20, 30)]
+ );
+ assert_eq!(
+ coverage_gaps(&coverage, timed_span(40, 45)),
+ [timed_span(40, 45)]
+ );
+ assert_eq!(coverage_gaps(&coverage, timed_span(5, 5)), []);
+ assert_eq!(
+ coverage_gaps(&[], span(CalendarSpanKind::AllDay, 1, 2)),
+ [span(CalendarSpanKind::AllDay, 1, 2)]
+ );
+}
+
+#[test]
+fn page_watermarks_lower_each_link_and_adopt_new_links() {
+ let stored = [link("a", 10), link("b", 5)];
+ let merged = apply_watermark_update(
+ Some(&stored),
+ Some(&CalendarWatermarkUpdate::Merge {
+ links: vec![link("a", 7), link("b", 9), link("c", 3)],
+ }),
+ &[],
+ );
+ assert_eq!(merged, [link("a", 7), link("b", 5), link("c", 3)]);
+ let again = apply_watermark_update(
+ Some(&merged),
+ Some(&CalendarWatermarkUpdate::Merge {
+ links: vec![link("a", 7), link("b", 9), link("c", 3)],
+ }),
+ &[],
+ );
+ assert_eq!(again, merged, "re-delivery is idempotent");
+}
+
+#[test]
+fn deltas_advance_untouched_links_and_keep_concurrent_lowerings() {
+ let since = vec![link("a", 10), link("b", 5)];
+ let to = vec![link("a", 20), link("b", 8), link("c", 4)];
+ let advance = CalendarWatermarkUpdate::Advance {
+ since: since.clone(),
+ to,
+ };
+ assert_eq!(
+ apply_watermark_update(Some(&since), Some(&advance), &[]),
+ [link("a", 20), link("b", 8), link("c", 4)]
+ );
+
+ // A page lowered `a` while the delta was in flight: its change is replayed.
+ let lowered = [link("a", 3), link("b", 5)];
+ assert_eq!(
+ apply_watermark_update(Some(&lowered), Some(&advance), &[]),
+ [link("a", 3), link("b", 8), link("c", 4)]
+ );
+
+ // A delta from an empty watermark bootstraps every link.
+ let bootstrap = CalendarWatermarkUpdate::Advance {
+ since: Vec::new(),
+ to: vec![link("a", 2)],
+ };
+ assert_eq!(
+ apply_watermark_update(None, Some(&bootstrap), &[]),
+ [link("a", 2)]
+ );
+}
+
+#[test]
+fn removed_links_leave_the_watermark() {
+ assert_eq!(
+ apply_watermark_update(Some(&[link("a", 1), link("b", 2)]), None, &["a".to_owned()]),
+ [link("b", 2)]
+ );
+}
+
+#[test]
+fn watermark_seq_crosses_the_wire_as_a_decimal_string() {
+ let encoded = serialize_watermark(&[link("a", 9_007_199_254_740_993)]);
+ assert_eq!(encoded, r#"[{"linkId":"a","seq":"9007199254740993"}]"#);
+ assert_eq!(
+ parse_watermark(&encoded).unwrap(),
+ [link("a", 9_007_199_254_740_993)]
+ );
+ assert!(parse_watermark(r#"[{"linkId":"a","seq":"-1"}]"#).is_none());
+ assert!(parse_watermark(r#"[{"linkId":"a","seq":1}]"#).is_none());
+}
+
+#[test]
+fn sync_state_resets_before_applying_the_commit() {
+ let stored = CalendarSyncState {
+ watermark: Some(vec![link("a", 10), link("b", 4)]),
+ freshness: CalendarFreshness::Fresh,
+ };
+ let reset = CalendarCommit {
+ reset: true,
+ watermark: Some(CalendarWatermarkUpdate::Advance {
+ since: vec![link("a", 10)],
+ to: vec![link("a", 30)],
+ }),
+ ..CalendarCommit::default()
+ };
+ assert_eq!(
+ next_sync_state(&stored, &reset),
+ CalendarSyncState {
+ watermark: Some(vec![link("a", 30)]),
+ freshness: CalendarFreshness::Unknown,
+ }
+ );
+
+ let stale = CalendarCommit {
+ freshness: Some(CalendarFreshness::Stale),
+ ..CalendarCommit::default()
+ };
+ assert_eq!(
+ next_sync_state(&CalendarSyncState::default(), &stale),
+ CalendarSyncState {
+ watermark: None,
+ freshness: CalendarFreshness::Stale,
+ }
+ );
+}
+
+#[test]
+fn commits_reject_foreign_keys_and_invalid_sync_values() {
+ let valid = CalendarCommit {
+ coverage: vec![timed_span(0, 1)],
+ replaced_events: vec![CalendarReplacedEvent {
+ event_key: key("GraphqlCalendarEvent:e1"),
+ occurrence_keys: vec![key("GraphqlCalendarOccurrence:e1:k")],
+ }],
+ deleted_event_keys: vec![key("GraphqlCalendarEvent:e2")],
+ deleted_calendar_keys: vec![key("GraphqlCalendar:c1")],
+ removed_link_ids: vec!["l2".into()],
+ watermark: Some(CalendarWatermarkUpdate::Merge {
+ links: vec![link("l1", 1)],
+ }),
+ freshness: Some(CalendarFreshness::Fresh),
+ reset: false,
+ };
+ assert_eq!(valid.validate(), Ok(()));
+
+ let invalid = [
+ (
+ CalendarCommit {
+ coverage: vec![timed_span(2, 1)],
+ ..valid.clone()
+ },
+ CalendarError::InvalidSpan,
+ ),
+ (
+ CalendarCommit {
+ deleted_event_keys: vec![key("GraphqlCalendar:e2")],
+ ..valid.clone()
+ },
+ CalendarError::InvalidKey,
+ ),
+ (
+ CalendarCommit {
+ replaced_events: vec![CalendarReplacedEvent {
+ event_key: key("GraphqlCalendarEvent:e1"),
+ occurrence_keys: vec![key("GraphqlCalendarEvent:e1")],
+ }],
+ ..valid.clone()
+ },
+ CalendarError::InvalidKey,
+ ),
+ (
+ CalendarCommit {
+ freshness: Some(CalendarFreshness::Unknown),
+ ..valid.clone()
+ },
+ CalendarError::InvalidFreshness,
+ ),
+ (
+ CalendarCommit {
+ watermark: Some(CalendarWatermarkUpdate::Merge {
+ links: vec![link("l1", 1), link("l1", 2)],
+ }),
+ ..valid.clone()
+ },
+ CalendarError::InvalidWatermark,
+ ),
+ (
+ CalendarCommit {
+ coverage: vec![timed_span(0, 1); MAX_CALENDAR_COMMIT_ITEMS + 1],
+ ..valid.clone()
+ },
+ CalendarError::TooLarge,
+ ),
+ ];
+ for (commit, error) in invalid {
+ assert_eq!(commit.validate(), Err(error));
+ }
+}
+
+#[test]
+fn requests_validate_spans_and_event_filters() {
+ assert_eq!(request(0, 0).validate(), Ok(()));
+ assert_eq!(request(2, 1).validate(), Err(CalendarError::InvalidSpan));
+ let mut filtered = request(0, 10);
+ filtered.event_key = Some(key("GraphqlCalendarOccurrence:e1:k"));
+ assert_eq!(filtered.validate(), Err(CalendarError::InvalidKey));
+ filtered.event_key = Some(key("GraphqlCalendarEvent:e1"));
+ assert_eq!(filtered.validate(), Ok(()));
+}
+
+#[test]
+fn overlay_replaces_moves_hides_and_adds_rows() {
+ let request = request(0, 100);
+ let authoritative = vec![
+ row("GraphqlCalendarOccurrence:e1:a", "e1", timed_span(10, 20)),
+ row("GraphqlCalendarOccurrence:e1:b", "e1", timed_span(30, 40)),
+ row("GraphqlCalendarOccurrence:e2:c", "e2", timed_span(50, 60)),
+ ];
+ let (keys, optimistic) =
+ compose_calendar_rows(&request, authoritative.clone(), &HashMap::new());
+ assert!(!optimistic);
+ assert_eq!(
+ keys,
+ authoritative
+ .iter()
+ .map(|row| row.record_key.clone())
+ .collect::<Vec<_>>()
+ );
+
+ let overlay = HashMap::from([
+ // Moved earlier inside the range.
+ (
+ key("GraphqlCalendarOccurrence:e1:b"),
+ Some(row(
+ "GraphqlCalendarOccurrence:e1:b",
+ "e1",
+ timed_span(0, 5),
+ )),
+ ),
+ // Deleted.
+ (key("GraphqlCalendarOccurrence:e2:c"), None),
+ // Moved out of the range.
+ (
+ key("GraphqlCalendarOccurrence:e1:a"),
+ Some(row(
+ "GraphqlCalendarOccurrence:e1:a",
+ "e1",
+ timed_span(500, 600),
+ )),
+ ),
+ // Created.
+ (
+ key("GraphqlCalendarOccurrence:local:d"),
+ Some(row(
+ "GraphqlCalendarOccurrence:local:d",
+ "local",
+ timed_span(70, 80),
+ )),
+ ),
+ ]);
+ let (keys, optimistic) = compose_calendar_rows(&request, authoritative, &overlay);
+ assert!(optimistic);
+ assert_eq!(
+ keys,
+ [
+ key("GraphqlCalendarOccurrence:e1:b"),
+ key("GraphqlCalendarOccurrence:local:d"),
+ ]
+ );
+}
+
+#[test]
+fn event_filters_apply_to_overlay_rows() {
+ let mut request = request(0, 100);
+ request.event_key = Some(key("GraphqlCalendarEvent:e1"));
+ let overlay = HashMap::from([(
+ key("GraphqlCalendarOccurrence:e2:a"),
+ Some(row(
+ "GraphqlCalendarOccurrence:e2:a",
+ "e2",
+ timed_span(10, 20),
+ )),
+ )]);
+ let (keys, optimistic) = compose_calendar_rows(&request, Vec::new(), &overlay);
+ assert!(keys.is_empty());
+ assert!(!optimistic);
+}
diff --git a/crates/client/cache-core/src/calendar/watermark.rs b/crates/client/cache-core/src/calendar/watermark.rs
new file mode 100644
index 0000000000..d974792c65
--- /dev/null
+++ b/crates/client/cache-core/src/calendar/watermark.rs
@@ -0,0 +1,143 @@
+//! Per-link change watermark: how far each email link's server change log has
+//! been applied to the cached calendar.
+
+use super::CalendarError;
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+use std::collections::{BTreeMap, BTreeSet};
+
+/// Applied change-log position of one email link.
+#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CalendarLinkWatermark {
+ /// Email link id.
+ pub link_id: String,
+ /// Last applied change-log sequence, sent as a decimal string because it
+ /// is a 64-bit server counter.
+ #[serde(serialize_with = "serialize_seq", deserialize_with = "deserialize_seq")]
+ pub seq: i64,
+}
+
+fn serialize_seq<S: Serializer>(seq: &i64, serializer: S) -> Result<S::Ok, S::Error> {
+ serializer.serialize_str(&seq.to_string())
+}
+
+fn deserialize_seq<'de, D: Deserializer<'de>>(deserializer: D) -> Result<i64, D::Error> {
+ let value = String::deserialize(deserializer)?;
+ value
+ .parse::<i64>()
+ .ok()
+ .filter(|seq| *seq >= 0 && value.bytes().all(|byte| byte.is_ascii_digit()))
+ .ok_or_else(|| serde::de::Error::custom("watermark seq must be a non-negative integer"))
+}
+
+/// How a commit changes the persisted watermark.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "camelCase")]
+pub enum CalendarWatermarkUpdate {
+ /// A page read captured `links` before reading its rows. Each link is
+ /// lowered to the incoming value, so changes the page may predate are
+ /// replayed by the next delta; links without a value adopt it.
+ Merge {
+ /// Watermark captured by the page.
+ links: Vec<CalendarLinkWatermark>,
+ },
+ /// A delta computed from `since` applied every change up to `to`. A link
+ /// still at its `since` value advances to `to`; a link another commit
+ /// moved meanwhile keeps the lower of the two values.
+ Advance {
+ /// Watermark the delta was requested from.
+ since: Vec<CalendarLinkWatermark>,
+ /// Server watermark the delta reached.
+ to: Vec<CalendarLinkWatermark>,
+ },
+}
+
+impl CalendarWatermarkUpdate {
+ /// Number of link entries carried by the update.
+ pub fn len(&self) -> usize {
+ match self {
+ Self::Merge { links } => links.len(),
+ Self::Advance { since, to } => since.len() + to.len(),
+ }
+ }
+
+ /// Whether the update carries no link entries.
+ pub fn is_empty(&self) -> bool {
+ self.len() == 0
+ }
+
+ /// Rejects empty or duplicate link ids and negative sequences.
+ pub fn validate(&self) -> Result<(), CalendarError> {
+ let lists: &[&[CalendarLinkWatermark]] = match self {
+ Self::Merge { links } => &[links],
+ Self::Advance { since, to } => &[since, to],
+ };
+ for links in lists {
+ let mut seen = BTreeSet::new();
+ if links.iter().any(|link| {
+ link.link_id.is_empty() || link.seq < 0 || !seen.insert(link.link_id.as_str())
+ }) {
+ return Err(CalendarError::InvalidWatermark);
+ }
+ }
+ Ok(())
+ }
+}
+
+/// Applies an update to the stored watermark, then drops removed links.
+///
+/// A missing stored link places no bound on the incoming value. The result is
+/// ordered by link id.
+pub fn apply_watermark_update(
+ stored: Option<&[CalendarLinkWatermark]>,
+ update: Option<&CalendarWatermarkUpdate>,
+ removed_link_ids: &[String],
+) -> Vec<CalendarLinkWatermark> {
+ let mut current = stored
+ .unwrap_or_default()
+ .iter()
+ .map(|link| (link.link_id.clone(), link.seq))
+ .collect::<BTreeMap<_, _>>();
+ let lower = |current: Option<i64>, incoming: i64| current.map_or(incoming, |c| c.min(incoming));
+ match update {
+ None => {}
+ Some(CalendarWatermarkUpdate::Merge { links }) => {
+ for link in links {
+ let value = lower(current.get(&link.link_id).copied(), link.seq);
+ current.insert(link.link_id.clone(), value);
+ }
+ }
+ Some(CalendarWatermarkUpdate::Advance { since, to }) => {
+ let since = since
+ .iter()
+ .map(|link| (link.link_id.as_str(), link.seq))
+ .collect::<BTreeMap<_, _>>();
+ for link in to {
+ let stored = current.get(&link.link_id).copied();
+ let value = if stored == since.get(link.link_id.as_str()).copied() {
+ link.seq
+ } else {
+ lower(stored, link.seq)
+ };
+ current.insert(link.link_id.clone(), value);
+ }
+ }
+ }
+ for link_id in removed_link_ids {
+ current.remove(link_id);
+ }
+ current
+ .into_iter()
+ .map(|(link_id, seq)| CalendarLinkWatermark { link_id, seq })
+ .collect()
+}
+
+/// Encodes a watermark for persistence.
+pub fn serialize_watermark(watermark: &[CalendarLinkWatermark]) -> String {
+ serde_json::to_string(watermark).expect("watermark serializes")
+}
+
+/// Decodes a persisted watermark.
+pub fn parse_watermark(value: &str) -> Option<Vec<CalendarLinkWatermark>> {
+ serde_json::from_str(value).ok()
+}
diff --git a/crates/client/cache-core/src/codec.rs b/crates/client/cache-core/src/codec.rs
index e1c3db1609..8fb63fbd05 100644
--- a/crates/client/cache-core/src/codec.rs
+++ b/crates/client/cache-core/src/codec.rs
@@ -24,7 +24,8 @@ pub const CACHE_FORMAT_VERSION: u32 = 3;
/// fetched. Bump this epoch for incompatible changes to normalized identity,
/// field storage shape, or other schema-derived cache semantics.
// File-type facts now preserve raw server text instead of enum-normalizing it.
-pub const CACHE_SCHEMA_COMPATIBILITY_EPOCH: u32 = 3;
+// Calendar range tables index cached occurrences, so older caches lack rows.
+pub const CACHE_SCHEMA_COMPATIBILITY_EPOCH: u32 = 4;
#[derive(Debug, Error)]
pub enum CodecError {
@@ -169,20 +170,21 @@ mod tests {
fn namespace_uses_schema_compatibility_epoch_not_schema_hash() {
assert_eq!(
cache_namespace("client-token-1"),
- "graphql-cache:client-token-1:s3:v3"
+ "graphql-cache:client-token-1:s4:v3"
);
}
#[test]
fn database_name_separates_storage_versions() {
- // The versions of the last unversioned builds keep their file.
+ // The versions of the last unversioned builds kept their file; every
+ // later epoch embeds its versions, even at that storage schema.
assert_eq!(
cache_database_name("client-token-1", 11),
- "graphql-cache:client-token-1"
+ "graphql-cache:client-token-1:s4.v3.t11"
);
assert_eq!(
cache_database_name("client-token-1", 12),
- "graphql-cache:client-token-1:s3.v3.t12"
+ "graphql-cache:client-token-1:s4.v3.t12"
);
assert_eq!(
legacy_cache_database_name("client-token-1"),
diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rs
index 0e3c81ba4b..ad1825cdbe 100644
--- a/crates/client/cache-core/src/engine.rs
+++ b/crates/client/cache-core/src/engine.rs
@@ -2,9 +2,11 @@
//! and dependency tracking together behind the API the hosts (wasm worker /
//! Tauri) expose over RPC.
+mod calendar;
#[cfg(test)]
mod test;
+use crate::calendar::{CalendarError, EVENT_TYPENAME};
use crate::denormalize::{DenormalizeError, ReadOutcome, ReadPlans, ReadSession, RecordSource};
use crate::deps::{
DepIndex, OpId, QueryDependencies, ViewerFieldUpdate, ViewerFields, changed_viewer_fields,
@@ -80,6 +82,8 @@ pub enum EngineError<S: std::error::Error + 'static> {
RecordSelection(#[from] RecordSelectionError),
#[error(transparent)]
Search(#[from] SearchError),
+ #[error(transparent)]
+ Calendar(#[from] CalendarError),
#[error("unknown or already-settled optimistic transaction {0}")]
UnknownTransaction(OptimisticTransactionId),
#[error("stale claim for optimistic transaction {0}")]
@@ -304,6 +308,7 @@ struct OptimisticLayer {
link_patches: Vec<OptimisticLinkPatch>,
revalidations: Vec<QueryRevalidation>,
projection_mutations: Vec<OptimisticProjectionMutation>,
+ uncertain_calendar_event_keys: Vec<EntityKey<'static>>,
}
struct BegunOptimisticWrite {
@@ -336,6 +341,9 @@ enum IdentityState {
/// hardening-phase refinement).
pub const DEFAULT_HOT_CAPACITY: usize = 10_000;
+/// Bound on the uncertain calendar events one optimistic layer may declare.
+const MAX_UNCERTAIN_CALENDAR_EVENTS: usize = 256;
+
// Parsed plans contain no cached user data. Bound dynamic document churn while
// leaving room for the production operation catalog and fragment variants.
const DOCUMENT_CACHE_CAPACITY: usize = 128;
@@ -601,6 +609,11 @@ impl<S: Storage> Engine<S> {
link_patches: patches,
revalidations,
projection_mutations: source.projection_mutations,
+ uncertain_calendar_event_keys: source
+ .uncertain_calendar_event_keys
+ .into_iter()
+ .map(|key| identities.get(&key).cloned().unwrap_or(key))
+ .collect(),
});
}
Ok(layers)
@@ -1615,7 +1628,7 @@ impl<S: Storage> Engine<S> {
projection_mutations: Vec<OptimisticProjectionMutation>,
) -> Result<(OptimisticTransactionId, WriteResult), EngineError<S::Error>> {
let begun = self
- .upsert_optimistic_write(origin_op, input, projection_mutations)
+ .upsert_optimistic_write(origin_op, input, projection_mutations, Vec::new())
.await?;
Ok((begun.transaction_id, begun.write_result))
}
@@ -1625,6 +1638,7 @@ impl<S: Storage> Engine<S> {
origin_op: Option<OpId>,
input: BeginOptimisticWrite<'_>,
projection_mutations: Vec<OptimisticProjectionMutation>,
+ uncertain_calendar_event_keys: Vec<EntityKey<'static>>,
) -> Result<BegunOptimisticWrite, EngineError<S::Error>> {
let uuid = Uuid::parse_str(input.uuid)
.map_err(|_| EngineError::InvalidMutationUuid(input.uuid.to_owned()))?;
@@ -1642,6 +1656,13 @@ impl<S: Storage> Engine<S> {
identity_bindings,
} = input;
identity::validate(identity_bindings).map_err(EngineError::InvalidOptimisticProjection)?;
+ if uncertain_calendar_event_keys.len() > MAX_UNCERTAIN_CALENDAR_EVENTS
+ || uncertain_calendar_event_keys
+ .iter()
+ .any(|key| key.typename() != Some(EVENT_TYPENAME))
+ {
+ return Err(CalendarError::InvalidKey.into());
+ }
self.hydrate_optimistic().await?;
let queued = self
@@ -1697,6 +1718,7 @@ impl<S: Storage> Engine<S> {
link_patches: patches,
revalidations,
projection_mutations,
+ uncertain_calendar_event_keys,
};
let mut entry = NewQueuedMutation {
uuid,
@@ -1869,9 +1891,34 @@ impl<S: Storage> Engine<S> {
input: BeginOptimisticWrite<'_>,
claim: MutationClaimRequest,
projection_mutations: Vec<OptimisticProjectionMutation>,
+ ) -> Result<EnqueueOptimisticMutationResult<EngineError<S::Error>>, EngineError<S::Error>> {
+ self.enqueue_optimistic_mutation_with_calendar(
+ origin_op,
+ input,
+ claim,
+ projection_mutations,
+ Vec::new(),
+ )
+ .await
+ }
+
+ /// Durably enqueue optimism, projection overlays, and the calendar events
+ /// whose occurrence sets stay uncertain until the mutation settles.
+ pub async fn enqueue_optimistic_mutation_with_calendar(
+ &mut self,
+ origin_op: Option<OpId>,
+ input: BeginOptimisticWrite<'_>,
+ claim: MutationClaimRequest,
+ projection_mutations: Vec<OptimisticProjectionMutation>,
+ uncertain_calendar_event_keys: Vec<EntityKey<'static>>,
) -> Result<EnqueueOptimisticMutationResult<EngineError<S::Error>>, EngineError<S::Error>> {
let begun = self
- .upsert_optimistic_write(origin_op, input, projection_mutations)
+ .upsert_optimistic_write(
+ origin_op,
+ input,
+ projection_mutations,
+ uncertain_calendar_event_keys,
+ )
.await?;
let initial_claim = match self.claim_next_mutation(claim).await {
Ok(Some(claimed)) => InitialClaimOutcome::Claimed(Box::new(claimed)),
diff --git a/crates/client/cache-core/src/engine/calendar.rs b/crates/client/cache-core/src/engine/calendar.rs
new file mode 100644
index 0000000000..47f71c2a9e
--- /dev/null
+++ b/crates/client/cache-core/src/engine/calendar.rs
@@ -0,0 +1,113 @@
+//! Local calendar range reads and commits.
+
+use super::{Engine, EngineError, WriteResult, effective_records, layer_keys};
+use crate::calendar::{
+ CalendarCommit, CalendarRangeRequest, CalendarRangeResult, CalendarRangeRow,
+ CalendarRangeStorage, OCCURRENCE_TYPENAME, compose_calendar_rows, coverage_gaps,
+ project_calendar_range,
+};
+use crate::revision::Revisioned;
+use crate::value::EntityKey;
+use std::collections::{BTreeSet, HashMap};
+
+impl<S: CalendarRangeStorage> Engine<S> {
+ /// Answers a viewport from cached occurrences.
+ ///
+ /// Authoritative rows come from the storage range index. Occurrences
+ /// touched by an active optimistic layer are projected from their composed
+ /// records and replace their authoritative rows, so an optimistic move,
+ /// delete, or create is visible before the mutation settles.
+ pub async fn calendar_range(
+ &mut self,
+ request: &CalendarRangeRequest,
+ ) -> Result<Revisioned<CalendarRangeResult>, EngineError<S::Error>> {
+ request.validate()?;
+ self.hydrate_optimistic().await?;
+ let snapshot = self
+ .storage
+ .query_calendar_ranges(request)
+ .await
+ .map_err(EngineError::Storage)?;
+ let overlay = self.optimistic_calendar_overlay().await?;
+ let (occurrence_keys, overlaid) = compose_calendar_rows(request, snapshot.rows, &overlay);
+ let uncertain_event_keys = self
+ .optimistic
+ .iter()
+ .flat_map(|layer| layer.uncertain_calendar_event_keys.iter().cloned())
+ .filter(|key| {
+ request
+ .event_key
+ .as_ref()
+ .is_none_or(|event_key| event_key == key)
+ })
+ .collect::<BTreeSet<_>>()
+ .into_iter()
+ .collect::<Vec<_>>();
+ let gaps = request
+ .spans()
+ .into_iter()
+ .flat_map(|span| coverage_gaps(&snapshot.coverage, span))
+ .collect();
+ Ok(self.revisioned(CalendarRangeResult {
+ occurrence_keys,
+ gaps,
+ freshness: snapshot.sync.freshness,
+ optimistic: overlaid || !uncertain_event_keys.is_empty(),
+ uncertain_event_keys,
+ watermark: snapshot.sync.watermark,
+ }))
+ }
+
+ async fn optimistic_calendar_overlay(
+ &mut self,
+ ) -> Result<HashMap<EntityKey<'static>, Option<CalendarRangeRow>>, EngineError<S::Error>> {
+ let keys = layer_keys(&self.optimistic)
+ .into_iter()
+ .filter(|key| key.typename() == Some(OCCURRENCE_TYPENAME))
+ .collect::<BTreeSet<_>>();
+ if keys.is_empty() {
+ return Ok(HashMap::new());
+ }
+ let bases = self.load_bases(&keys).await?;
+ Ok(effective_records(&bases, &self.optimistic, &keys)
+ .into_iter()
+ .map(|(key, record)| {
+ let row = record.and_then(|record| project_calendar_range(&key, &record));
+ (key, row)
+ })
+ .collect())
+ }
+
+ /// Atomically applies coverage, occurrence-set replacements, deletions,
+ /// and sync state. Records the commit deletes are evicted and reported as
+ /// changed so dependent operations re-execute.
+ pub async fn calendar_commit(
+ &mut self,
+ commit: &CalendarCommit,
+ ) -> Result<WriteResult, EngineError<S::Error>> {
+ commit.validate()?;
+ self.ensure_revision_can_advance()?;
+ let outcome = self
+ .storage
+ .calendar_commit(commit)
+ .await
+ .map_err(EngineError::Storage)?;
+ let changed = outcome.deleted_keys.into_iter().collect::<BTreeSet<_>>();
+ for key in &changed {
+ self.hot.pop(key);
+ }
+ let affected_ops = self.deps.ops_for_keys(changed.iter());
+ let revision = self.advance_revision()?;
+ Ok(WriteResult {
+ identity_errors: Vec::new(),
+ revision,
+ revision_advanced: true,
+ search_changed_buckets: Some(BTreeSet::new()),
+ changed,
+ affected_ops,
+ reset: false,
+ revalidations: Vec::new(),
+ mutation_uuid: None,
+ })
+ }
+}
diff --git a/crates/client/cache-core/src/lib.rs b/crates/client/cache-core/src/lib.rs
index 5b1d82e04e..1893a6c412 100644
--- a/crates/client/cache-core/src/lib.rs
+++ b/crates/client/cache-core/src/lib.rs
@@ -2,6 +2,7 @@
//!
//! Design doc: `apps/web/docs/graphql-normalized-cache-plan.md`.
+pub mod calendar;
pub mod codec;
pub mod denormalize;
pub mod deps;
diff --git a/crates/client/cache-core/src/queue.rs b/crates/client/cache-core/src/queue.rs
index de9c1339c7..ee94008a6d 100644
--- a/crates/client/cache-core/src/queue.rs
+++ b/crates/client/cache-core/src/queue.rs
@@ -8,7 +8,7 @@
use crate::identity::IdentityBinding;
use crate::link_patch::{OptimisticLinkPatch, QueryRevalidation};
use crate::normalize::RecordUpdates;
-use crate::value::canonical_json;
+use crate::value::{EntityKey, canonical_json};
use predicate_index::OptimisticProjectionMutation;
use serde::{Deserialize, Serialize};
use serde_json::Value as Json;
@@ -98,6 +98,10 @@ pub struct OptimisticSource {
/// Ordered generic projection changes composed with this optimistic layer.
#[serde(default)]
pub projection_mutations: Vec<OptimisticProjectionMutation>,
+ /// Calendar events whose occurrence set this layer cannot predict, such
+ /// as a recurrence edit. Range reads report them until the layer settles.
+ #[serde(default)]
+ pub uncertain_calendar_event_keys: Vec<EntityKey<'static>>,
}
#[derive(Debug, Serialize, Deserialize)]
@@ -114,6 +118,8 @@ struct OptimisticSourceEnvelope {
#[serde(default)]
revalidations: Vec<QueryRevalidation>,
projection_mutations: Vec<OptimisticProjectionMutation>,
+ #[serde(default, skip_serializing_if = "Vec::is_empty")]
+ uncertain_calendar_event_keys: Vec<EntityKey<'static>>,
}
#[derive(Debug, Deserialize)]
@@ -138,6 +144,7 @@ pub fn encode_optimistic_source(source: &OptimisticSource) -> String {
link_patches: source.link_patches.clone(),
revalidations: source.revalidations.clone(),
projection_mutations: source.projection_mutations.clone(),
+ uncertain_calendar_event_keys: source.uncertain_calendar_event_keys.clone(),
})
.expect("optimistic source serializes"),
);
@@ -155,6 +162,7 @@ pub fn decode_optimistic_source(value: &str) -> Result<OptimisticSource, String>
link_patches: Vec::new(),
revalidations: Vec::new(),
projection_mutations: Vec::new(),
+ uncertain_calendar_event_keys: Vec::new(),
});
};
let value: Json = serde_json::from_str(envelope).map_err(|error| error.to_string())?;
@@ -174,6 +182,7 @@ pub fn decode_optimistic_source(value: &str) -> Result<OptimisticSource, String>
link_patches: envelope.link_patches,
revalidations: envelope.revalidations,
projection_mutations: Vec::new(),
+ uncertain_calendar_event_keys: Vec::new(),
})
}
version if version == u64::from(OPTIMISTIC_SOURCE_VERSION) => {
@@ -186,6 +195,7 @@ pub fn decode_optimistic_source(value: &str) -> Result<OptimisticSource, String>
link_patches: envelope.link_patches,
revalidations: envelope.revalidations,
projection_mutations: envelope.projection_mutations,
+ uncertain_calendar_event_keys: envelope.uncertain_calendar_event_keys,
})
}
version => Err(format!("unsupported optimistic source version {version}")),
diff --git a/crates/client/cache-core/src/store.rs b/crates/client/cache-core/src/store.rs
index 7d436c9d81..5ae709ae83 100644
--- a/crates/client/cache-core/src/store.rs
+++ b/crates/client/cache-core/src/store.rs
@@ -6,6 +6,7 @@
//! wasm — wasm futures aren't
//! `Send`.
+use crate::calendar::{CalendarRangeRow, CalendarSpan, CalendarSyncState, project_calendar_range};
use crate::predicate::reconciliation::{
PredicateBaselineEntry, PredicateMembership, PredicateReconciliation, predicate_membership,
reconcile_predicate_baseline,
@@ -31,6 +32,8 @@ use std::convert::Infallible;
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
+mod calendar;
+
/// Whether a storage implementation can provide queue diagnostics.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum QueueDiagnosticsAvailability {
@@ -286,6 +289,9 @@ pub struct InMemoryStorage {
search_catalog_load_count: Arc<AtomicUsize>,
search_catalog_rows_loaded: Arc<AtomicUsize>,
mutation_queue_load_count: Arc<AtomicUsize>,
+ calendar_ranges: HashMap<EntityKey<'static>, CalendarRangeRow>,
+ calendar_coverage: Vec<CalendarSpan>,
+ calendar_sync: CalendarSyncState,
}
#[derive(Clone, Debug)]
@@ -309,6 +315,33 @@ impl InMemoryStorage {
self.records.is_empty()
}
+ /// Writes one record with every derived row, like a relational write-through.
+ fn write_record(&mut self, key: EntityKey<'static>, record: Record) {
+ self.search_documents
+ .retain(|(_, existing_key), _| existing_key != &key);
+ for document in project_search_documents(&key, &record) {
+ self.search_documents
+ .insert((document.profile, key.clone()), document);
+ }
+ match project_calendar_range(&key, &record) {
+ Some(row) => {
+ self.calendar_ranges.insert(key.clone(), row);
+ }
+ None => {
+ self.calendar_ranges.remove(&key);
+ }
+ }
+ self.records.insert(key, record);
+ }
+
+ /// Deletes one record with every derived row.
+ fn remove_record(&mut self, key: &EntityKey<'static>) {
+ self.records.remove(key);
+ self.search_documents
+ .retain(|(_, existing_key), _| existing_key != key);
+ self.calendar_ranges.remove(key);
+ }
+
fn rebase_projections(&mut self, keys: &[PredicateRecordKey]) {
let sources = self
.mutations
@@ -378,13 +411,7 @@ impl Storage for InMemoryStorage {
entries: Vec<(EntityKey<'static>, Record)>,
) -> Result<(), Self::Error> {
for (key, record) in entries {
- self.search_documents
- .retain(|(_, existing_key), _| existing_key != &key);
- for document in project_search_documents(&key, &record) {
- self.search_documents
- .insert((document.profile, key.clone()), document);
- }
- self.records.insert(key, record);
+ self.write_record(key, record);
}
Ok(())
}
@@ -406,9 +433,7 @@ impl Storage for InMemoryStorage {
async fn delete_batch(&mut self, keys: &[EntityKey<'static>]) -> Result<(), Self::Error> {
for key in keys {
- self.records.remove(key);
- self.search_documents
- .retain(|(_, existing_key), _| existing_key != key);
+ self.remove_record(key);
}
Ok(())
}
@@ -679,13 +704,7 @@ impl Storage for InMemoryStorage {
return Ok(false);
}
for (key, record) in entries {
- self.search_documents
- .retain(|(_, existing_key), _| existing_key != &key);
- for document in project_search_documents(&key, &record) {
- self.search_documents
- .insert((document.profile, key.clone()), document);
- }
- self.records.insert(key, record);
+ self.write_record(key, record);
}
apply_in_memory_projection_mutations(&mut self.projections, projections);
self.mutations.remove(&id);
@@ -719,13 +738,7 @@ impl Storage for InMemoryStorage {
}
}
for (key, record) in entries {
- self.search_documents
- .retain(|(_, existing_key), _| existing_key != &key);
- for document in project_search_documents(&key, &record) {
- self.search_documents
- .insert((document.profile, key.clone()), document);
- }
- self.records.insert(key, record);
+ self.write_record(key, record);
}
apply_in_memory_projection_mutations(&mut self.projections, projections);
self.mutations.remove(&id);
@@ -795,6 +808,9 @@ impl Storage for InMemoryStorage {
self.projections.clear();
self.optimistic_projections.clear();
self.mutations.clear();
+ self.calendar_ranges.clear();
+ self.calendar_coverage.clear();
+ self.calendar_sync = CalendarSyncState::default();
Ok(())
}
}
diff --git a/crates/client/cache-core/src/store/calendar.rs b/crates/client/cache-core/src/store/calendar.rs
new file mode 100644
index 0000000000..98408f23bf
--- /dev/null
+++ b/crates/client/cache-core/src/store/calendar.rs
@@ -0,0 +1,119 @@
+//! In-memory calendar range projection used by engine tests.
+
+use super::InMemoryStorage;
+use crate::calendar::{
+ CALENDAR_TYPENAME, CalendarCommit, CalendarCommitOutcome, CalendarRangeRequest,
+ CalendarRangeSnapshot, CalendarRangeStorage, EVENT_TYPENAME, OCCURRENCE_TYPENAME, merge_spans,
+ next_sync_state,
+};
+use crate::value::{CacheValue, EntityKey};
+use std::collections::BTreeSet;
+
+impl CalendarRangeStorage for InMemoryStorage {
+ async fn query_calendar_ranges(
+ &self,
+ request: &CalendarRangeRequest,
+ ) -> Result<CalendarRangeSnapshot, Self::Error> {
+ let spans = request.spans();
+ Ok(CalendarRangeSnapshot {
+ rows: self
+ .calendar_ranges
+ .values()
+ .filter(|row| request.includes(row))
+ .cloned()
+ .collect(),
+ coverage: self
+ .calendar_coverage
+ .iter()
+ .filter(|covered| {
+ spans.iter().any(|span| {
+ covered.kind == span.kind
+ && covered.start <= span.end
+ && covered.end >= span.start
+ })
+ })
+ .copied()
+ .collect(),
+ sync: self.calendar_sync.clone(),
+ })
+ }
+
+ async fn calendar_commit(
+ &mut self,
+ commit: &CalendarCommit,
+ ) -> Result<CalendarCommitOutcome, Self::Error> {
+ let mut deleted = BTreeSet::new();
+ if commit.reset {
+ deleted.extend(
+ self.records
+ .keys()
+ .filter(|key| {
+ matches!(key.typename(), Some(OCCURRENCE_TYPENAME | EVENT_TYPENAME))
+ })
+ .cloned(),
+ );
+ self.calendar_coverage.clear();
+ }
+ for event in &commit.replaced_events {
+ let current = event.occurrence_keys.iter().collect::<BTreeSet<_>>();
+ deleted.extend(
+ self.calendar_ranges
+ .values()
+ .filter(|row| {
+ row.event_key == event.event_key && !current.contains(&row.record_key)
+ })
+ .map(|row| row.record_key.clone()),
+ );
+ }
+ for event_key in &commit.deleted_event_keys {
+ deleted.insert(event_key.clone());
+ deleted.extend(
+ self.calendar_ranges
+ .values()
+ .filter(|row| row.event_key == *event_key)
+ .map(|row| row.record_key.clone()),
+ );
+ }
+ deleted.extend(commit.deleted_calendar_keys.iter().cloned());
+ if !commit.removed_link_ids.is_empty() {
+ let removed = commit
+ .removed_link_ids
+ .iter()
+ .map(String::as_str)
+ .collect::<BTreeSet<_>>();
+ deleted.extend(
+ self.calendar_ranges
+ .values()
+ .filter(|row| removed.contains(row.link_id.as_str()))
+ .map(|row| row.record_key.clone()),
+ );
+ deleted.extend(
+ self.records
+ .iter()
+ .filter(|(key, record)| {
+ matches!(key.typename(), Some(EVENT_TYPENAME | CALENDAR_TYPENAME))
+ && matches!(
+ record.fields.get("linkId"),
+ Some(CacheValue::String(link_id)) if removed.contains(link_id.as_str())
+ )
+ })
+ .map(|(key, _)| key.clone()),
+ );
+ }
+ let deleted_keys = deleted
+ .into_iter()
+ .filter(|key| self.records.contains_key(key))
+ .collect::<Vec<EntityKey<'static>>>();
+ for key in &deleted_keys {
+ self.remove_record(key);
+ }
+ self.calendar_coverage = merge_spans(
+ self.calendar_coverage
+ .iter()
+ .chain(&commit.coverage)
+ .copied(),
+ );
+ self.calendar_sync = next_sync_state(&self.calendar_sync, commit);
+ Ok(CalendarCommitOutcome { deleted_keys })
+ }
+}
diff --git a/crates/client/cache-core/tests/calendar_range.rs b/crates/client/cache-core/tests/calendar_range.rs
new file mode 100644
index 0000000000..7c1f1d3714
--- /dev/null
+++ b/crates/client/cache-core/tests/calendar_range.rs
@@ -0,0 +1,828 @@
+use cache_core::calendar::{
+ CalendarCommit, CalendarFreshness, CalendarLinkWatermark, CalendarRangeRequest,
+ CalendarReplacedEvent, CalendarSpan, CalendarSpanKind, CalendarWatermarkUpdate,
+};
+use cache_core::engine::{BeginOptimisticWrite, Engine, InitialClaimOutcome};
+use cache_core::identity::IdentityBinding;
+use cache_core::queue::{MutationClaimRequest, MutationClaimToken};
+use cache_core::store::{InMemoryStorage, Storage};
+use cache_core::value::{CacheValue, EntityKey, Record};
+use pollster::block_on;
+use serde_json::{Value as Json, json};
+use std::collections::BTreeMap;
+
+const HOUR_MS: i64 = 3_600_000;
+const DAY_MS: i64 = 24 * HOUR_MS;
+// 2026-10-05T00:00:00Z
+const MONDAY_MS: i64 = 1_791_158_400_000;
+const MONDAY_DAY: i64 = 20_731;
+
+const MUTATION: &str = "mutation Save { setEntityProperty { __typename id displayName } }";
+const UUID: &str = "22222222-2222-4222-8222-222222222222";
+
+fn key(value: &str) -> EntityKey<'static> {
+ EntityKey(value.to_owned().into())
+}
+
+fn text(value: &str) -> CacheValue {
+ CacheValue::String(value.into())
+}
+
+fn iso(ms: i64) -> String {
+ chrono::DateTime::from_timestamp_millis(ms)
+ .unwrap()
+ .to_rfc3339()
+}
+
+fn date(day: i64) -> String {
+ (chrono::NaiveDate::from_ymd_opt(1970, 1, 1).unwrap() + chrono::Duration::days(day)).to_string()
+}
+
+fn time_object(fields: Vec<(&str, String)>) -> CacheValue {
+ CacheValue::Object(
+ fields
+ .into_iter()
+ .map(|(field, value)| (field.to_owned(), CacheValue::String(value)))
+ .collect::<BTreeMap<_, _>>(),
+ )
+}
+
+fn occurrence(event: &str, link: &str, time: CacheValue) -> Record {
+ let mut record = Record::default();
+ for (field, value) in [
+ ("__typename", text("GraphqlCalendarOccurrence")),
+ ("eventId", text(event)),
+ ("linkId", text(link)),
+ ("isCancelled", CacheValue::Bool(false)),
+ ("time", time),
+ ] {
+ record.fields.insert(field.into(), value);
+ }
+ record
+}
+
+fn timed(event: &str, link: &str, start_ms: i64, end_ms: i64) -> (EntityKey<'static>, Record) {
+ let start = iso(start_ms);
+ (
+ key(&format!("GraphqlCalendarOccurrence:{event}:{start}")),
+ occurrence(
+ event,
+ link,
+ time_object(vec![
+ ("__typename", "GraphqlTimedEventTime".into()),
+ ("startsAt", start),
+ ("endsAt", iso(end_ms)),
+ ]),
+ ),
+ )
+}
+
+fn all_day(event: &str, link: &str, start_day: i64, end_day: i64) -> (EntityKey<'static>, Record) {
+ (
+ key(&format!(
+ "GraphqlCalendarOccurrence:{event}:{}",
+ date(start_day)
+ )),
+ occurrence(
+ event,
+ link,
+ time_object(vec![
+ ("__typename", "GraphqlAllDayEventTime".into()),
+ ("startDate", date(start_day)),
+ ("endDate", date(end_day)),
+ ]),
+ ),
+ )
+}
+
+fn linked(typename: &str, id: &str, link: &str) -> (EntityKey<'static>, Record) {
+ let mut record = Record::default();
+ record.fields.insert("__typename".into(), text(typename));
+ record.fields.insert("id".into(), text(id));
+ record.fields.insert("linkId".into(), text(link));
+ (EntityKey::entity(typename, &[id]), record)
+}
+
+fn week() -> CalendarRangeRequest {
+ CalendarRangeRequest {
+ start_ms: MONDAY_MS,
+ end_ms: MONDAY_MS + 7 * DAY_MS,
+ start_day: MONDAY_DAY,
+ end_day: MONDAY_DAY + 7,
+ event_key: None,
+ }
+}
+
+fn week_coverage() -> Vec<CalendarSpan> {
+ vec![
+ CalendarSpan {
+ kind: CalendarSpanKind::Timed,
+ start: MONDAY_MS,
+ end: MONDAY_MS + 7 * DAY_MS,
+ },
+ CalendarSpan {
+ kind: CalendarSpanKind::AllDay,
+ start: MONDAY_DAY,
+ end: MONDAY_DAY + 7,
+ },
+ ]
+}
+
+fn link(link_id: &str, seq: i64) -> CalendarLinkWatermark {
+ CalendarLinkWatermark {
+ link_id: link_id.into(),
+ seq,
+ }
+}
+
+async fn seeded(entries: Vec<(EntityKey<'static>, Record)>) -> Engine<InMemoryStorage> {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ engine
+ .put_records_with_projections(None, entries, Vec::new())
+ .await
+ .unwrap();
+ engine
+}
+
+#[test]
+fn ranges_return_overlapping_occurrences_of_both_kinds() {
+ block_on(async {
+ let inside = timed(
+ "e1",
+ "l1",
+ MONDAY_MS + 9 * HOUR_MS,
+ MONDAY_MS + 10 * HOUR_MS,
+ );
+ let ends_at_start = timed("e2", "l1", MONDAY_MS - HOUR_MS, MONDAY_MS);
+ let starts_at_end = timed("e3", "l1", MONDAY_MS + 7 * DAY_MS, MONDAY_MS + 8 * DAY_MS);
+ let long = timed("e4", "l1", MONDAY_MS - 30 * DAY_MS, MONDAY_MS + HOUR_MS);
+ let holiday = all_day("e5", "l1", MONDAY_DAY + 6, MONDAY_DAY + 7);
+ let next_week = all_day("e6", "l1", MONDAY_DAY + 7, MONDAY_DAY + 8);
+ let mut engine = seeded(vec![
+ inside.clone(),
+ ends_at_start,
+ starts_at_end,
+ long.clone(),
+ holiday.clone(),
+ next_week,
+ ])
+ .await;
+
+ let result = engine.calendar_range(&week()).await.unwrap();
+ assert_eq!(
+ result.occurrence_keys,
+ [long.0.clone(), inside.0.clone(), holiday.0.clone()]
+ );
+ assert_eq!(result.gaps, week_coverage());
+ assert_eq!(result.freshness, CalendarFreshness::Unknown);
+ assert_eq!(result.watermark, None);
+ assert!(!result.optimistic);
+
+ let mut only_e1 = week();
+ only_e1.event_key = Some(key("GraphqlCalendarEvent:e1"));
+ assert_eq!(
+ engine
+ .calendar_range(&only_e1)
+ .await
+ .unwrap()
+ .occurrence_keys,
+ [inside.0]
+ );
+ });
+}
+
+#[test]
+fn coverage_and_watermarks_persist_across_commits() {
+ block_on(async {
+ let mut engine = seeded(Vec::new()).await;
+ let first = engine
+ .calendar_commit(&CalendarCommit {
+ coverage: week_coverage(),
+ watermark: Some(CalendarWatermarkUpdate::Merge {
+ links: vec![link("l1", 10), link("l2", 4)],
+ }),
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap();
+ assert!(first.revision_advanced);
+ let result = engine.calendar_range(&week()).await.unwrap();
+ assert!(result.gaps.is_empty());
+ assert_eq!(result.watermark, Some(vec![link("l1", 10), link("l2", 4)]));
+
+ let mut two_weeks = week();
+ two_weeks.end_ms += 7 * DAY_MS;
+ two_weeks.end_day += 7;
+ assert_eq!(
+ engine.calendar_range(&two_weeks).await.unwrap().gaps,
+ [
+ CalendarSpan {
+ kind: CalendarSpanKind::Timed,
+ start: MONDAY_MS + 7 * DAY_MS,
+ end: MONDAY_MS + 14 * DAY_MS,
+ },
+ CalendarSpan {
+ kind: CalendarSpanKind::AllDay,
+ start: MONDAY_DAY + 7,
+ end: MONDAY_DAY + 14,
+ },
+ ]
+ );
+
+ // A page captured before an older replica read lowers the watermark.
+ engine
+ .calendar_commit(&CalendarCommit {
+ watermark: Some(CalendarWatermarkUpdate::Merge {
+ links: vec![link("l1", 7)],
+ }),
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap();
+ engine
+ .calendar_commit(&CalendarCommit {
+ watermark: Some(CalendarWatermarkUpdate::Advance {
+ since: vec![link("l1", 7), link("l2", 4)],
+ to: vec![link("l1", 12), link("l2", 6)],
+ }),
+ freshness: Some(CalendarFreshness::Fresh),
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap();
+ let result = engine.calendar_range(&week()).await.unwrap();
+ assert_eq!(result.watermark, Some(vec![link("l1", 12), link("l2", 6)]));
+ assert_eq!(result.freshness, CalendarFreshness::Fresh);
+ });
+}
+
+#[test]
+fn commits_replace_occurrence_sets_and_delete_by_event_and_link() {
+ block_on(async {
+ let kept = timed("e1", "l1", MONDAY_MS + HOUR_MS, MONDAY_MS + 2 * HOUR_MS);
+ let moved_away = timed("e1", "l1", MONDAY_MS + DAY_MS, MONDAY_MS + DAY_MS + HOUR_MS);
+ let deleted_event = timed("e2", "l1", MONDAY_MS + 3 * HOUR_MS, MONDAY_MS + 4 * HOUR_MS);
+ let other_link = timed("e3", "l2", MONDAY_MS + 5 * HOUR_MS, MONDAY_MS + 6 * HOUR_MS);
+ let event_e2 = linked("GraphqlCalendarEvent", "e2", "l1");
+ let event_e3 = linked("GraphqlCalendarEvent", "e3", "l2");
+ let calendar_l1 = linked("GraphqlCalendar", "c1", "l1");
+ let calendar_l2 = linked("GraphqlCalendar", "c2", "l2");
+ let mut engine = seeded(vec![
+ kept.clone(),
+ moved_away.clone(),
+ deleted_event.clone(),
+ other_link.clone(),
+ event_e2.clone(),
+ event_e3.clone(),
+ calendar_l1.clone(),
+ calendar_l2.clone(),
+ ])
+ .await;
+
+ let result = engine
+ .calendar_commit(&CalendarCommit {
+ replaced_events: vec![CalendarReplacedEvent {
+ event_key: key("GraphqlCalendarEvent:e1"),
+ occurrence_keys: vec![kept.0.clone()],
+ }],
+ deleted_event_keys: vec![event_e2.0.clone()],
+ deleted_calendar_keys: vec![calendar_l1.0.clone()],
+ removed_link_ids: vec!["l2".into()],
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap();
+ assert_eq!(
+ result.changed.into_iter().collect::<Vec<_>>(),
+ [
+ calendar_l1.0.clone(),
+ calendar_l2.0.clone(),
+ event_e2.0.clone(),
+ event_e3.0.clone(),
+ deleted_event.0.clone(),
+ moved_away.0.clone(),
+ other_link.0.clone(),
+ ]
+ .into_iter()
+ .collect::<std::collections::BTreeSet<_>>()
+ .into_iter()
+ .collect::<Vec<_>>()
+ );
+ assert_eq!(
+ engine
+ .calendar_range(&week())
+ .await
+ .unwrap()
+ .occurrence_keys,
+ std::slice::from_ref(&kept.0)
+ );
+ let stored = engine
+ .storage()
+ .get_batch(&[
+ moved_away.0,
+ event_e2.0,
+ event_e3.0,
+ calendar_l1.0,
+ calendar_l2.0,
+ kept.0,
+ ])
+ .await
+ .unwrap();
+ assert_eq!(
+ stored.iter().map(Option::is_some).collect::<Vec<_>>(),
+ [false, false, false, false, false, true]
+ );
+ });
+}
+
+#[test]
+fn reset_drops_calendar_records_coverage_and_sync_state() {
+ block_on(async {
+ let occurrence = timed("e1", "l1", MONDAY_MS, MONDAY_MS + HOUR_MS);
+ let event = linked("GraphqlCalendarEvent", "e1", "l1");
+ let calendar = linked("GraphqlCalendar", "c1", "l1");
+ let mut engine = seeded(vec![occurrence.clone(), event.clone(), calendar.clone()]).await;
+ engine
+ .calendar_commit(&CalendarCommit {
+ coverage: week_coverage(),
+ watermark: Some(CalendarWatermarkUpdate::Merge {
+ links: vec![link("l1", 3), link("l2", 8)],
+ }),
+ freshness: Some(CalendarFreshness::Fresh),
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap();
+
+ engine
+ .calendar_commit(&CalendarCommit {
+ reset: true,
+ watermark: Some(CalendarWatermarkUpdate::Advance {
+ since: vec![link("l1", 3), link("l2", 8)],
+ to: vec![link("l1", 40)],
+ }),
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap();
+ let result = engine.calendar_range(&week()).await.unwrap();
+ assert!(result.occurrence_keys.is_empty());
+ assert_eq!(result.gaps, week_coverage());
+ assert_eq!(result.watermark, Some(vec![link("l1", 40)]));
+ assert_eq!(result.freshness, CalendarFreshness::Unknown);
+ let stored = engine
+ .storage()
+ .get_batch(&[occurrence.0, event.0, calendar.0])
+ .await
+ .unwrap();
+ assert_eq!(
+ stored.iter().map(Option::is_some).collect::<Vec<_>>(),
+ [false, false, true]
+ );
+ });
+}
+
+#[test]
+fn records_rewritten_out_of_range_or_cancelled_leave_the_index() {
+ block_on(async {
+ let (occurrence_key, mut record) =
+ timed("e1", "l1", MONDAY_MS + HOUR_MS, MONDAY_MS + 2 * HOUR_MS);
+ let mut engine = seeded(vec![(occurrence_key.clone(), record.clone())]).await;
+ record
+ .fields
+ .insert("isCancelled".into(), CacheValue::Bool(true));
+ engine
+ .put_records_with_projections(None, vec![(occurrence_key.clone(), record)], Vec::new())
+ .await
+ .unwrap();
+ assert!(
+ engine
+ .calendar_range(&week())
+ .await
+ .unwrap()
+ .occurrence_keys
+ .is_empty()
+ );
+ engine
+ .delete_keys(std::slice::from_ref(&occurrence_key))
+ .await
+ .unwrap();
+ assert!(
+ engine
+ .calendar_range(&week())
+ .await
+ .unwrap()
+ .occurrence_keys
+ .is_empty()
+ );
+ });
+}
+
+async fn enqueue_delete(
+ engine: &mut Engine<InMemoryStorage>,
+ occurrence_key: &EntityKey<'static>,
+ uncertain: Vec<EntityKey<'static>>,
+) -> (u64, MutationClaimToken) {
+ let result = engine
+ .enqueue_optimistic_mutation_with_calendar(
+ None,
+ BeginOptimisticWrite {
+ client_metadata: None,
+ uuid: UUID,
+ query: MUTATION,
+ operation_name: None,
+ variables: &Default::default(),
+ data: &json!({"setEntityProperty": {"__typename": "GraphqlProperty", "id": "p1", "displayName": "x"}}),
+ link_patches: &[],
+ revalidations: &[],
+ created_at_ms: 0,
+ identity_bindings: &[IdentityBinding {
+ local_key: occurrence_key.clone(),
+ delete_record: true,
+ response_path: vec![],
+ reference_fields: vec![],
+ revalidation_variables: vec![],
+ }],
+ },
+ MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 0,
+ lease_expires_at_ms: 100,
+ },
+ Vec::new(),
+ uncertain,
+ )
+ .await
+ .unwrap();
+ let InitialClaimOutcome::Claimed(claimed) = result.initial_claim else {
+ panic!("the only queued mutation is claimable");
+ };
+ (
+ result.transaction_id,
+ MutationClaimToken {
+ owner: "runner".into(),
+ generation: claimed.lease_generation,
+ },
+ )
+}
+
+#[test]
+fn optimistic_deletes_and_uncertain_events_shape_reads_until_rollback() {
+ block_on(async {
+ let deleted = timed("e1", "l1", MONDAY_MS + HOUR_MS, MONDAY_MS + 2 * HOUR_MS);
+ let kept = timed("e2", "l1", MONDAY_MS + 3 * HOUR_MS, MONDAY_MS + 4 * HOUR_MS);
+ let mut engine = seeded(vec![deleted.clone(), kept.clone()]).await;
+ let (transaction, claim) = enqueue_delete(
+ &mut engine,
+ &deleted.0,
+ vec![key("GraphqlCalendarEvent:e2")],
+ )
+ .await;
+
+ let result = engine.calendar_range(&week()).await.unwrap();
+ assert_eq!(result.occurrence_keys, std::slice::from_ref(&kept.0));
+ assert!(result.optimistic);
+ assert_eq!(
+ result.uncertain_event_keys,
+ [key("GraphqlCalendarEvent:e2")]
+ );
+ let mut only_e1 = week();
+ only_e1.event_key = Some(key("GraphqlCalendarEvent:e1"));
+ assert!(
+ engine
+ .calendar_range(&only_e1)
+ .await
+ .unwrap()
+ .uncertain_event_keys
+ .is_empty()
+ );
+
+ // The layer survives an engine restart over the same storage.
+ let mut engine = Engine::new(engine.into_storage());
+ assert_eq!(
+ engine
+ .calendar_range(&week())
+ .await
+ .unwrap()
+ .occurrence_keys,
+ std::slice::from_ref(&kept.0)
+ );
+
+ engine
+ .rollback_optimistic_write(transaction, claim)
+ .await
+ .unwrap();
+ let result = engine.calendar_range(&week()).await.unwrap();
+ assert_eq!(result.occurrence_keys, [deleted.0, kept.0]);
+ assert!(!result.optimistic);
+ assert!(result.uncertain_event_keys.is_empty());
+ });
+}
+
+#[test]
+fn committed_optimistic_deletes_retire_the_authoritative_row() {
+ block_on(async {
+ let deleted = timed("e1", "l1", MONDAY_MS + HOUR_MS, MONDAY_MS + 2 * HOUR_MS);
+ let mut engine = seeded(vec![deleted.clone()]).await;
+ let (transaction, claim) = enqueue_delete(&mut engine, &deleted.0, Vec::new()).await;
+ engine
+ .commit_optimistic_write(
+ transaction,
+ claim,
+ MUTATION,
+ None,
+ &Default::default(),
+ &json!({"setEntityProperty": {"__typename": "GraphqlProperty", "id": "p1", "displayName": "x"}}),
+ )
+ .await
+ .unwrap();
+ let result = engine.calendar_range(&week()).await.unwrap();
+ assert!(result.occurrence_keys.is_empty());
+ assert!(!result.optimistic);
+ });
+}
+
+#[test]
+fn uncertain_keys_must_name_calendar_events() {
+ block_on(async {
+ let occurrence = timed("e1", "l1", MONDAY_MS, MONDAY_MS + HOUR_MS);
+ let mut engine = seeded(vec![occurrence.clone()]).await;
+ let error = engine
+ .enqueue_optimistic_mutation_with_calendar(
+ None,
+ BeginOptimisticWrite {
+ client_metadata: None,
+ uuid: UUID,
+ query: MUTATION,
+ operation_name: None,
+ variables: &Default::default(),
+ data: &json!({"setEntityProperty": {"__typename": "GraphqlProperty", "id": "p1", "displayName": "x"}}),
+ link_patches: &[],
+ revalidations: &[],
+ created_at_ms: 0,
+ identity_bindings: &[],
+ },
+ MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 0,
+ lease_expires_at_ms: 100,
+ },
+ Vec::new(),
+ vec![occurrence.0],
+ )
+ .await;
+ assert!(error.is_err());
+ assert!(
+ engine
+ .storage()
+ .load_mutation_queue()
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ });
+}
+
+#[test]
+fn identity_changes_and_clears_wipe_calendar_state() {
+ const VIEWER: &str = "query Viewer { user { id } }";
+ block_on(async {
+ let occurrence = timed("e1", "l1", MONDAY_MS, MONDAY_MS + HOUR_MS);
+ let mut engine = seeded(vec![occurrence]).await;
+ engine
+ .write_query(
+ None,
+ VIEWER,
+ None,
+ &Default::default(),
+ &json!({"user": {"id": "u1"}}),
+ Some("u1"),
+ )
+ .await
+ .unwrap();
+ engine
+ .calendar_commit(&CalendarCommit {
+ coverage: week_coverage(),
+ watermark: Some(CalendarWatermarkUpdate::Merge {
+ links: vec![link("l1", 1)],
+ }),
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap();
+ let write = engine
+ .write_query(
+ None,
+ VIEWER,
+ None,
+ &Default::default(),
+ &json!({"user": {"id": "u2"}}),
+ Some("u2"),
+ )
+ .await
+ .unwrap();
+ assert!(write.reset);
+ let result = engine.calendar_range(&week()).await.unwrap();
+ assert!(result.occurrence_keys.is_empty());
+ assert_eq!(result.gaps, week_coverage());
+ assert_eq!(result.watermark, None);
+
+ engine
+ .calendar_commit(&CalendarCommit {
+ coverage: week_coverage(),
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap();
+ engine.clear().await.unwrap();
+ assert_eq!(
+ engine.calendar_range(&week()).await.unwrap().gaps,
+ week_coverage()
+ );
+ });
+}
+
+#[test]
+fn invalid_requests_and_commits_are_rejected_before_storage() {
+ block_on(async {
+ let mut engine = seeded(Vec::new()).await;
+ let mut inverted = week();
+ inverted.end_ms = inverted.start_ms - 1;
+ assert!(engine.calendar_range(&inverted).await.is_err());
+ let revision = engine.current_revision();
+ assert!(
+ engine
+ .calendar_commit(&CalendarCommit {
+ deleted_event_keys: vec![key("GraphqlCalendarOccurrence:e1:k")],
+ ..CalendarCommit::default()
+ })
+ .await
+ .is_err()
+ );
+ assert_eq!(engine.current_revision(), revision);
+ });
+}
+
+const OCCURRENCES: &str = r#"
+query CalendarOccurrences($input: CalendarRangeInput!) {
+ user {
+ id
+ calendarOccurrences(input: $input) {
+ nodes {
+ __typename
+ id
+ eventId
+ linkId
+ occurrenceKey
+ isCancelled
+ time {
+ __typename
+ ... on GraphqlTimedEventTime { startsAt endsAt timeZone }
+ ... on GraphqlAllDayEventTime { startDate endDate }
+ }
+ event { __typename id linkId title }
+ }
+ hasNextPage
+ endCursor
+ syncStatus
+ watermark { linkId seq }
+ }
+ }
+}
+"#;
+
+fn occurrence_node(
+ event: &str,
+ key: &str,
+ time: serde_json::Value,
+ cancelled: bool,
+) -> serde_json::Value {
+ json!({
+ "__typename": "GraphqlCalendarOccurrence",
+ "id": format!("{event}:{key}"),
+ "eventId": event,
+ "linkId": "l1",
+ "occurrenceKey": key,
+ "isCancelled": cancelled,
+ "time": time,
+ "event": { "__typename": "GraphqlCalendarEvent", "id": event, "linkId": "l1", "title": event },
+ })
+}
+
+fn occurrence_page(nodes: Vec<serde_json::Value>) -> serde_json::Value {
+ json!({
+ "user": {
+ "id": "u1",
+ "calendarOccurrences": {
+ "nodes": nodes,
+ "hasNextPage": false,
+ "endCursor": null,
+ "syncStatus": "READY",
+ "watermark": [{ "linkId": "l1", "seq": "4" }],
+ }
+ }
+ })
+}
+
+#[test]
+fn network_pages_are_indexed_through_normalization() {
+ block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ let Json::Object(variables) = json!({
+ "input": { "start": iso(MONDAY_MS), "end": iso(MONDAY_MS + 7 * DAY_MS) }
+ }) else {
+ unreachable!()
+ };
+ let standup = iso(MONDAY_MS + 9 * HOUR_MS);
+ let page = occurrence_page(vec![
+ occurrence_node(
+ "e1",
+ &standup,
+ json!({
+ "__typename": "GraphqlTimedEventTime",
+ "startsAt": standup,
+ "endsAt": iso(MONDAY_MS + 10 * HOUR_MS),
+ "timeZone": "America/New_York",
+ }),
+ false,
+ ),
+ occurrence_node(
+ "e2",
+ &date(MONDAY_DAY + 2),
+ json!({
+ "__typename": "GraphqlAllDayEventTime",
+ "startDate": date(MONDAY_DAY + 2),
+ "endDate": date(MONDAY_DAY + 3),
+ }),
+ false,
+ ),
+ occurrence_node(
+ "e3",
+ &date(MONDAY_DAY + 4),
+ json!({
+ "__typename": "GraphqlAllDayEventTime",
+ "startDate": date(MONDAY_DAY + 4),
+ "endDate": date(MONDAY_DAY + 5),
+ }),
+ true,
+ ),
+ ]);
+ engine
+ .write_query(None, OCCURRENCES, None, &variables, &page, Some("u1"))
+ .await
+ .unwrap();
+ let result = engine.calendar_range(&week()).await.unwrap();
+ assert_eq!(
+ result.occurrence_keys,
+ [
+ key(&format!("GraphqlCalendarOccurrence:e1:{standup}")),
+ key(&format!(
+ "GraphqlCalendarOccurrence:e2:{}",
+ date(MONDAY_DAY + 2)
+ )),
+ ]
+ );
+
+ // The delta rewrites e1 later in the week and commits its full set.
+ let moved = iso(MONDAY_MS + 2 * DAY_MS + 9 * HOUR_MS);
+ let moved_page = occurrence_page(vec![occurrence_node(
+ "e1",
+ &moved,
+ json!({
+ "__typename": "GraphqlTimedEventTime",
+ "startsAt": moved,
+ "endsAt": iso(MONDAY_MS + 2 * DAY_MS + 10 * HOUR_MS),
+ "timeZone": null,
+ }),
+ false,
+ )]);
+ engine
+ .write_query(None, OCCURRENCES, None, &variables, &moved_page, Some("u1"))
+ .await
+ .unwrap();
+ let commit = engine
+ .calendar_commit(&CalendarCommit {
+ replaced_events: vec![CalendarReplacedEvent {
+ event_key: key("GraphqlCalendarEvent:e1"),
+ occurrence_keys: vec![key(&format!("GraphqlCalendarOccurrence:e1:{moved}"))],
+ }],
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap();
+ assert_eq!(
+ commit.changed.into_iter().collect::<Vec<_>>(),
+ [key(&format!("GraphqlCalendarOccurrence:e1:{standup}"))]
+ );
+ let mut only_e1 = week();
+ only_e1.event_key = Some(key("GraphqlCalendarEvent:e1"));
+ assert_eq!(
+ engine
+ .calendar_range(&only_e1)
+ .await
+ .unwrap()
+ .occurrence_keys,
+ [key(&format!("GraphqlCalendarOccurrence:e1:{moved}"))]
+ );
+ });
+}
diff --git a/crates/client/cache-core/tests/mutation_queue.rs b/crates/client/cache-core/tests/mutation_queue.rs
index a167531f5d..ca2ebdc59e 100644
--- a/crates/client/cache-core/tests/mutation_queue.rs
+++ b/crates/client/cache-core/tests/mutation_queue.rs
@@ -51,6 +51,7 @@ fn optimistic_source_supports_versioned_and_legacy_json() {
}],
},
],
+ uncertain_calendar_event_keys: vec![EntityKey::entity("GraphqlCalendarEvent", &["e1"])],
};
assert_eq!(
decode_optimistic_source(&encode_optimistic_source(&source)).unwrap(),
@@ -81,9 +82,11 @@ fn optimistic_source_supports_versioned_and_legacy_json() {
assert!(legacy_v2.client_metadata.is_none());
let without_metadata = encode_optimistic_source(&OptimisticSource {
client_metadata: None,
+ uncertain_calendar_event_keys: Vec::new(),
..source
});
assert!(!without_metadata.contains("clientMetadata"));
+ assert!(!without_metadata.contains("uncertainCalendarEventKeys"));
assert!(
decode_optimistic_source(
r#"@macro-cache/optimistic-source:{"version":2,"mutationData":{},"projectionMutations":[]}"#,
diff --git a/crates/client/cache-turso/Cargo.toml b/crates/client/cache-turso/Cargo.toml
index a61dea026a..a07d86fe2e 100644
--- a/crates/client/cache-turso/Cargo.toml
+++ b/crates/client/cache-turso/Cargo.toml
@@ -23,6 +23,7 @@ turso_core = { workspace = true, features = ["fs", "pure-rust-crypto", "uuid"] }
turso_core = { workspace = true, features = ["fs", "pure-rust-crypto", "uuid"] }
[dev-dependencies]
+chrono = { workspace = true }
pollster = { workspace = true }
serde_json = { workspace = true }
diff --git a/crates/client/cache-turso/src/storage.rs b/crates/client/cache-turso/src/storage.rs
index 17d9af046a..0b6dff7f7d 100644
--- a/crates/client/cache-turso/src/storage.rs
+++ b/crates/client/cache-turso/src/storage.rs
@@ -846,7 +846,7 @@ impl Storage for TursoStorage {
require_changed(changed, 1)?;
self.fault_after(TestFaultSite::Put, index)?;
}
- write_search_documents(&connection, &entries)
+ write_derived_rows(&connection, &entries)
})
})();
self.latch_result(result)
@@ -877,7 +877,7 @@ impl Storage for TursoStorage {
)?;
self.fault_after(TestFaultSite::Put, index)?;
}
- write_search_documents(&connection, &entries)?;
+ write_derived_rows(&connection, &entries)?;
write_projection_mutations(&connection, projections)
})
})();
@@ -915,7 +915,7 @@ impl Storage for TursoStorage {
)?;
self.fault_after(TestFaultSite::Delete, index)?;
}
- Ok(())
+ calendar::delete_ranges(&connection, &keys)
})
})();
self.latch_result(result)
@@ -1307,7 +1307,7 @@ impl Storage for TursoStorage {
self.fault_after(TestFaultSite::Complete, index)?;
}
}
- write_search_documents(&connection, &entries)?;
+ write_derived_rows(&connection, &entries)?;
write_projection_mutations(&connection, projections)?;
require_changed(
driver::execute(
@@ -1363,7 +1363,7 @@ impl Storage for TursoStorage {
self.fault_after(TestFaultSite::Complete, index)?;
}
}
- write_search_documents(&connection, &entries)?;
+ write_derived_rows(&connection, &entries)?;
write_projection_mutations(&connection, projections)?;
require_changed(
driver::execute(
@@ -1464,6 +1464,7 @@ impl Storage for TursoStorage {
driver::execute(&connection, "DELETE FROM search_documents", Vec::new())?;
driver::execute(&connection, "DELETE FROM index_documents", Vec::new())?;
driver::execute(&connection, "DELETE FROM records", Vec::new())?;
+ calendar::clear(&connection)?;
self.fault_after(TestFaultSite::Clear, 2)?;
Ok(())
})
@@ -1575,6 +1576,7 @@ impl PredicateIndexStorage for TursoStorage {
key,
)?;
}
+ calendar::delete_ranges(&connection, &keys)?;
write_projection_mutations(&connection, projections)
})
})();
@@ -2897,7 +2899,7 @@ fn initialize(
enable_foreign_keys(connection).map_err(TursoStorageError::initialization)?;
if fresh {
driver::write_transaction(connection, || {
- for sql in CREATE_SCHEMA {
+ for sql in CREATE_SCHEMA.into_iter().chain(calendar::CREATE_SCHEMA) {
driver::execute(connection, sql, Vec::new())?;
}
driver::execute(
@@ -2916,6 +2918,7 @@ fn initialize(
vec![text(&STORAGE_SCHEMA_VERSION.to_string())],
)?;
save_search_projection_version(connection)?;
+ calendar::save_projection_version(connection)?;
page_retention::save_version(connection)?;
Ok(())
})
@@ -2984,13 +2987,17 @@ fn initialize(
] {
driver::validate(connection, sql).map_err(TursoStorageError::initialization)?;
}
- for sql in INDEX_FACTS_DELETE {
+ for sql in INDEX_FACTS_DELETE
+ .into_iter()
+ .chain(calendar::VALIDATED_SQL)
+ {
driver::validate(connection, sql).map_err(TursoStorageError::initialization)?;
}
validate_queue_consistency(connection)?;
validate_optimistic_shadow_consistency(connection)?;
page_retention::compact_legacy_pages(connection)?;
- ensure_search_projection_version(connection)
+ ensure_search_projection_version(connection)?;
+ calendar::ensure_projection_version(connection)
}
fn save_search_projection_version(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {
@@ -3565,7 +3572,8 @@ fn validate_frozen_schema(connection: &Arc<Connection>) -> Result<(), TursoStora
connection,
"optimistic_uncertain_attributes",
"optimistic_index_documents",
- )
+ )?;
+ calendar::validate_schema(connection)
}
const SQLITE_SEQUENCE_TABLE: &str = "sqlite_sequence";
@@ -3611,6 +3619,14 @@ fn validate_allowed_schema_objects(connection: &Arc<Connection>) -> Result<(), T
"search_documents_browse_idx",
"sort_facts_lookup_idx",
];
+ let expected = expected
+ .into_iter()
+ .chain(calendar::TABLES)
+ .collect::<Vec<_>>();
+ let named_indexes = named_indexes
+ .into_iter()
+ .chain(calendar::NAMED_INDEXES)
+ .collect::<Vec<_>>();
let support = [SQLITE_SEQUENCE_TABLE, TURSO_AUTOINCREMENT_TABLE];
let mut seen = vec![false; expected.len()];
let mut named_index_seen = vec![false; named_indexes.len()];
@@ -4496,6 +4512,7 @@ struct EncodedRecord {
key: RecordKey,
value: Vec<u8>,
search_documents: Vec<SearchDocument>,
+ calendar_range: Option<cache_core::calendar::CalendarRangeRow>,
}
fn prepare_records(
@@ -4508,6 +4525,7 @@ fn prepare_records(
key: RecordKey::from_entity(&key)?,
value: encode_record(&record),
search_documents: project_search_documents(&key, &record),
+ calendar_range: cache_core::calendar::project_calendar_range(&key, &record),
})
})
.collect()
@@ -4604,6 +4622,15 @@ fn upsert_search_documents_batch(
Ok(())
}
+/// Writes every derived row of upserted records in the records' transaction.
+fn write_derived_rows(
+ connection: &Arc<Connection>,
+ entries: &[EncodedRecord],
+) -> Result<(), TursoStorageError> {
+ write_search_documents(connection, entries)?;
+ calendar::write_ranges(connection, entries)
+}
+
fn write_search_documents(
connection: &Arc<Connection>,
entries: &[EncodedRecord],
@@ -4968,6 +4995,7 @@ impl TursoStorage {
mod alternatives;
mod bounded_selection;
+mod calendar;
mod conjunction;
mod integrity;
mod mutation_retry;
diff --git a/crates/client/cache-turso/src/storage/calendar.rs b/crates/client/cache-turso/src/storage/calendar.rs
new file mode 100644
index 0000000000..ef024a0b98
--- /dev/null
+++ b/crates/client/cache-turso/src/storage/calendar.rs
@@ -0,0 +1,662 @@
+//! Calendar range index, fetched-range coverage, and change-stream sync state.
+
+use super::*;
+use cache_core::calendar::{
+ CALENDAR_PROJECTION_VERSION, CALENDAR_TYPENAME, CalendarCommit, CalendarCommitOutcome,
+ CalendarFreshness, CalendarRangeRequest, CalendarRangeRow, CalendarRangeSnapshot,
+ CalendarRangeStorage, CalendarSpan, CalendarSpanKind, CalendarSyncState, EVENT_TYPENAME,
+ OCCURRENCE_TYPENAME, merge_spans, next_sync_state, parse_watermark, project_calendar_range,
+ serialize_watermark,
+};
+use cache_core::value::CacheValue;
+
+pub(super) const CREATE_SCHEMA: [&str; 5] = [
+ "CREATE TABLE calendar_ranges (record_key TEXT PRIMARY KEY, event_key TEXT NOT NULL, link_id TEXT NOT NULL, kind INTEGER NOT NULL, start INTEGER NOT NULL, end INTEGER NOT NULL, long INTEGER NOT NULL)",
+ "CREATE INDEX calendar_ranges_scan_idx ON calendar_ranges(kind, long, start, record_key)",
+ "CREATE INDEX calendar_ranges_event_idx ON calendar_ranges(event_key, record_key)",
+ "CREATE INDEX calendar_ranges_link_idx ON calendar_ranges(link_id, record_key)",
+ "CREATE TABLE calendar_coverage (kind INTEGER NOT NULL, start INTEGER NOT NULL, end INTEGER NOT NULL, PRIMARY KEY (kind, start))",
+];
+
+pub(super) const TABLES: [&str; 2] = ["calendar_coverage", "calendar_ranges"];
+pub(super) const NAMED_INDEXES: [&str; 3] = [
+ "calendar_ranges_event_idx",
+ "calendar_ranges_link_idx",
+ "calendar_ranges_scan_idx",
+];
+
+const RANGE_UPSERT: &str = "INSERT INTO calendar_ranges (record_key, event_key, link_id, kind, start, end, long) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7) ON CONFLICT (record_key) DO UPDATE SET event_key = excluded.event_key, link_id = excluded.link_id, kind = excluded.kind, start = excluded.start, end = excluded.end, long = excluded.long";
+const RANGE_DELETE: &str = "DELETE FROM calendar_ranges WHERE record_key = ?1";
+// A short row ends at most one short span after it starts, so its start is
+// bounded on both sides and the scan stays on the (kind, long, start) prefix.
+const RANGE_SHORT: &str = "SELECT record_key, event_key, link_id, kind, start, end FROM calendar_ranges INDEXED BY calendar_ranges_scan_idx WHERE kind = ?1 AND long = 0 AND start >= ?2 AND start < ?3 AND end > ?4";
+const RANGE_LONG: &str = "SELECT record_key, event_key, link_id, kind, start, end FROM calendar_ranges INDEXED BY calendar_ranges_scan_idx WHERE kind = ?1 AND long = 1 AND start < ?2 AND end > ?3";
+const RANGE_BY_EVENT: &str = "SELECT record_key, event_key, link_id, kind, start, end FROM calendar_ranges INDEXED BY calendar_ranges_event_idx WHERE event_key = ?1";
+const RANGE_KEYS_BY_EVENT: &str = "SELECT record_key FROM calendar_ranges INDEXED BY calendar_ranges_event_idx WHERE event_key = ?1";
+const RANGE_KEYS_BY_LINK: &str =
+ "SELECT record_key FROM calendar_ranges INDEXED BY calendar_ranges_link_idx WHERE link_id = ?1";
+const COVERAGE_SELECT: &str =
+ "SELECT kind, start, end FROM calendar_coverage WHERE kind = ?1 AND start <= ?3 AND end >= ?2";
+const COVERAGE_ALL: &str = "SELECT kind, start, end FROM calendar_coverage";
+const COVERAGE_INSERT: &str =
+ "INSERT INTO calendar_coverage (kind, start, end) VALUES (?1, ?2, ?3)";
+const META_SELECT: &str = "SELECT value FROM meta WHERE key = ?1";
+const META_UPSERT: &str = "INSERT INTO meta (key, value) VALUES (?1, ?2) ON CONFLICT (key) DO UPDATE SET value = excluded.value";
+const META_DELETE: &str = "DELETE FROM meta WHERE key = ?1";
+const WATERMARK_KEY: &str = "calendar_watermark";
+const FRESHNESS_KEY: &str = "calendar_freshness";
+const PROJECTION_VERSION_KEY: &str = "calendar_projection_version";
+
+pub(super) const VALIDATED_SQL: [&str; 13] = [
+ RANGE_UPSERT,
+ RANGE_DELETE,
+ RANGE_SHORT,
+ RANGE_LONG,
+ RANGE_BY_EVENT,
+ RANGE_KEYS_BY_EVENT,
+ RANGE_KEYS_BY_LINK,
+ COVERAGE_SELECT,
+ COVERAGE_ALL,
+ COVERAGE_INSERT,
+ META_SELECT,
+ META_UPSERT,
+ META_DELETE,
+];
+
+/// Writes or removes the range row of every occurrence entry, keeping the
+/// last entry for a key exactly like the record upsert does.
+pub(super) fn write_ranges(
+ connection: &Arc<Connection>,
+ entries: &[EncodedRecord],
+) -> Result<(), TursoStorageError> {
+ let mut last = HashMap::new();
+ for (index, entry) in entries.iter().enumerate() {
+ if entry.key.typename == OCCURRENCE_TYPENAME {
+ last.insert(entry.key.id.as_str(), index);
+ }
+ }
+ if last.is_empty() {
+ return Ok(());
+ }
+ let mut upsert = driver::prepare(connection, RANGE_UPSERT)?;
+ let mut delete = driver::prepare(connection, RANGE_DELETE)?;
+ let mut indexes = last.into_values().collect::<Vec<_>>();
+ indexes.sort_unstable();
+ for index in indexes {
+ let entry = &entries[index];
+ match &entry.calendar_range {
+ Some(row) => {
+ require_changed(driver::execute_prepared(&mut upsert, row_values(row))?, 1)?;
+ }
+ None => delete_row(&mut delete, &entity_key_text(&entry.key))?,
+ }
+ }
+ Ok(())
+}
+
+/// Removes the range rows of deleted occurrence records.
+pub(super) fn delete_ranges(
+ connection: &Arc<Connection>,
+ keys: &[RecordKey],
+) -> Result<(), TursoStorageError> {
+ let mut statement = None;
+ for key in keys
+ .iter()
+ .filter(|key| key.typename == OCCURRENCE_TYPENAME)
+ {
+ let statement = match statement.as_mut() {
+ Some(statement) => statement,
+ None => statement.insert(driver::prepare(connection, RANGE_DELETE)?),
+ };
+ delete_row(statement, &entity_key_text(key))?;
+ }
+ Ok(())
+}
+
+/// Removes every calendar row and sync value with the rest of the cache.
+pub(super) fn clear(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {
+ driver::execute(connection, "DELETE FROM calendar_ranges", Vec::new())?;
+ driver::execute(connection, "DELETE FROM calendar_coverage", Vec::new())?;
+ for key in [WATERMARK_KEY, FRESHNESS_KEY] {
+ driver::execute(connection, META_DELETE, vec![text(key)])?;
+ }
+ Ok(())
+}
+
+pub(super) fn save_projection_version(
+ connection: &Arc<Connection>,
+) -> Result<(), TursoStorageError> {
+ driver::execute(
+ connection,
+ META_UPSERT,
+ vec![
+ text(PROJECTION_VERSION_KEY),
+ text(&CALENDAR_PROJECTION_VERSION.to_string()),
+ ],
+ )?;
+ Ok(())
+}
+
+/// Rebuilds the disposable range rows from occurrence records when the
+/// projection changed, without touching records, coverage, or sync state.
+pub(super) fn ensure_projection_version(
+ connection: &Arc<Connection>,
+) -> Result<(), TursoStorageError> {
+ let versions = driver::query(connection, META_SELECT, vec![text(PROJECTION_VERSION_KEY)])?;
+ if let [row] = versions.as_slice()
+ && required_text(row, 0)? == CALENDAR_PROJECTION_VERSION.to_string()
+ {
+ return Ok(());
+ }
+ driver::write_transaction(connection, || {
+ driver::execute(connection, "DELETE FROM calendar_ranges", Vec::new())?;
+ let mut upsert = driver::prepare(connection, RANGE_UPSERT)?;
+ for_each_record(connection, OCCURRENCE_TYPENAME, |key, record| {
+ if let Some(row) = project_calendar_range(key, record) {
+ require_changed(driver::execute_prepared(&mut upsert, row_values(&row))?, 1)?;
+ }
+ Ok(())
+ })?;
+ save_projection_version(connection)
+ })
+}
+
+fn for_each_record(
+ connection: &Arc<Connection>,
+ typename: &str,
+ mut visit: impl FnMut(&EntityKey<'static>, &Record) -> Result<(), TursoStorageError>,
+) -> Result<(), TursoStorageError> {
+ let mut last_id: Option<String> = None;
+ loop {
+ let (sql, parameters) = match last_id.as_ref() {
+ Some(id) => (
+ SEARCH_REBUILD_RECORDS_AFTER,
+ vec![
+ text(typename),
+ text(id),
+ Value::from_i64(SEARCH_REBUILD_BATCH_SIZE),
+ ],
+ ),
+ None => (
+ SEARCH_REBUILD_RECORDS,
+ vec![text(typename), Value::from_i64(SEARCH_REBUILD_BATCH_SIZE)],
+ ),
+ };
+ let rows = driver::query(connection, sql, parameters)?;
+ if rows.is_empty() {
+ return Ok(());
+ }
+ for row in rows {
+ let key = RecordKey {
+ typename: typename.to_owned(),
+ id: required_text(&row, 0)?,
+ };
+ let record = decode_record(&required_blob(&row, 1)?)
+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::Codec))?;
+ last_id = Some(key.id.clone());
+ visit(&key.into_entity()?, &record)?;
+ }
+ }
+}
+
+fn row_values(row: &CalendarRangeRow) -> Vec<Value> {
+ vec![
+ text(row.record_key.as_ref()),
+ text(row.event_key.as_ref()),
+ text(&row.link_id),
+ Value::from_i64(row.span.kind.code()),
+ Value::from_i64(row.span.start),
+ Value::from_i64(row.span.end),
+ Value::from_i64(i64::from(row.is_long())),
+ ]
+}
+
+fn delete_row(statement: &mut turso_core::Statement, key: &str) -> Result<(), TursoStorageError> {
+ let changed = driver::execute_prepared(statement, vec![text(key)])?;
+ if (0..=1).contains(&changed) {
+ Ok(())
+ } else {
+ Err(invariant())
+ }
+}
+
+fn entity_key_text(key: &RecordKey) -> String {
+ format!("{}:{}", key.typename, key.id)
+}
+
+fn parse_row(row: &[Value]) -> Result<CalendarRangeRow, TursoStorageError> {
+ if row.len() != 6 {
+ return Err(invariant());
+ }
+ let entity = |index| -> Result<EntityKey<'static>, TursoStorageError> {
+ let value = required_text(row, index)?;
+ RecordKey::from_entity(&EntityKey(value.as_str().into()))
+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::Corruption))?
+ .into_entity()
+ };
+ Ok(CalendarRangeRow {
+ record_key: entity(0)?,
+ event_key: entity(1)?,
+ link_id: required_text(row, 2)?,
+ span: CalendarSpan {
+ kind: CalendarSpanKind::from_code(required_i64(row, 3)?).ok_or_else(invariant)?,
+ start: required_i64(row, 4)?,
+ end: required_i64(row, 5)?,
+ },
+ })
+}
+
+fn parse_span(row: &[Value]) -> Result<CalendarSpan, TursoStorageError> {
+ if row.len() != 3 {
+ return Err(invariant());
+ }
+ Ok(CalendarSpan {
+ kind: CalendarSpanKind::from_code(required_i64(row, 0)?).ok_or_else(invariant)?,
+ start: required_i64(row, 1)?,
+ end: required_i64(row, 2)?,
+ })
+}
+
+fn load_sync_state(connection: &Arc<Connection>) -> Result<CalendarSyncState, TursoStorageError> {
+ let value = |key: &str| -> Result<Option<String>, TursoStorageError> {
+ match driver::query(connection, META_SELECT, vec![text(key)])?.as_slice() {
+ [] => Ok(None),
+ [row] => required_text(row, 0).map(Some),
+ _ => Err(invariant()),
+ }
+ };
+ let watermark = value(WATERMARK_KEY)?
+ .map(|value| parse_watermark(&value).ok_or_else(invariant))
+ .transpose()?;
+ let freshness = value(FRESHNESS_KEY)?
+ .map(|value| CalendarFreshness::parse(&value).ok_or_else(invariant))
+ .transpose()?
+ .unwrap_or_default();
+ Ok(CalendarSyncState {
+ watermark,
+ freshness,
+ })
+}
+
+fn save_sync_state(
+ connection: &Arc<Connection>,
+ state: &CalendarSyncState,
+) -> Result<(), TursoStorageError> {
+ match &state.watermark {
+ Some(watermark) => driver::execute(
+ connection,
+ META_UPSERT,
+ vec![text(WATERMARK_KEY), text(&serialize_watermark(watermark))],
+ )?,
+ None => driver::execute(connection, META_DELETE, vec![text(WATERMARK_KEY)])?,
+ };
+ match state.freshness {
+ CalendarFreshness::Unknown => {
+ driver::execute(connection, META_DELETE, vec![text(FRESHNESS_KEY)])?
+ }
+ freshness => driver::execute(
+ connection,
+ META_UPSERT,
+ vec![text(FRESHNESS_KEY), text(freshness.as_str())],
+ )?,
+ };
+ Ok(())
+}
+
+fn query_rows(
+ connection: &Arc<Connection>,
+ request: &CalendarRangeRequest,
+) -> Result<Vec<CalendarRangeRow>, TursoStorageError> {
+ let rows = match &request.event_key {
+ Some(event_key) => {
+ driver::query(connection, RANGE_BY_EVENT, vec![text(event_key.as_ref())])?
+ }
+ None => {
+ let mut rows = Vec::new();
+ for span in request
+ .spans()
+ .into_iter()
+ .filter(|span| span.end > span.start)
+ {
+ let kind = Value::from_i64(span.kind.code());
+ rows.extend(driver::query(
+ connection,
+ RANGE_SHORT,
+ vec![
+ kind.clone(),
+ Value::from_i64(span.start.saturating_sub(span.kind.max_short_span())),
+ Value::from_i64(span.end),
+ Value::from_i64(span.start),
+ ],
+ )?);
+ rows.extend(driver::query(
+ connection,
+ RANGE_LONG,
+ vec![kind, Value::from_i64(span.end), Value::from_i64(span.start)],
+ )?);
+ }
+ rows
+ }
+ };
+ let mut parsed = Vec::with_capacity(rows.len());
+ for row in rows {
+ let row = parse_row(&row)?;
+ if request.includes(&row) {
+ parsed.push(row);
+ }
+ }
+ Ok(parsed)
+}
+
+fn query_coverage(
+ connection: &Arc<Connection>,
+ request: &CalendarRangeRequest,
+) -> Result<Vec<CalendarSpan>, TursoStorageError> {
+ let mut coverage = Vec::new();
+ for span in request.spans() {
+ for row in driver::query(
+ connection,
+ COVERAGE_SELECT,
+ vec![
+ Value::from_i64(span.kind.code()),
+ Value::from_i64(span.start),
+ Value::from_i64(span.end),
+ ],
+ )? {
+ coverage.push(parse_span(&row)?);
+ }
+ }
+ Ok(coverage)
+}
+
+fn record_keys(
+ connection: &Arc<Connection>,
+ sql: &str,
+ value: &str,
+) -> Result<Vec<String>, TursoStorageError> {
+ driver::query(connection, sql, vec![text(value)])?
+ .iter()
+ .map(|row| required_text(row, 0))
+ .collect()
+}
+
+fn collect_deleted_keys(
+ connection: &Arc<Connection>,
+ commit: &CalendarCommit,
+) -> Result<BTreeSet<String>, TursoStorageError> {
+ let mut deleted = BTreeSet::new();
+ for event in &commit.replaced_events {
+ let current = event
+ .occurrence_keys
+ .iter()
+ .map(|key| key.as_ref())
+ .collect::<BTreeSet<_>>();
+ deleted.extend(
+ record_keys(connection, RANGE_KEYS_BY_EVENT, event.event_key.as_ref())?
+ .into_iter()
+ .filter(|key| !current.contains(key.as_str())),
+ );
+ }
+ for event_key in &commit.deleted_event_keys {
+ deleted.insert(event_key.as_ref().to_owned());
+ deleted.extend(record_keys(
+ connection,
+ RANGE_KEYS_BY_EVENT,
+ event_key.as_ref(),
+ )?);
+ }
+ deleted.extend(
+ commit
+ .deleted_calendar_keys
+ .iter()
+ .map(|key| key.as_ref().to_owned()),
+ );
+ if !commit.removed_link_ids.is_empty() {
+ let removed = commit
+ .removed_link_ids
+ .iter()
+ .map(String::as_str)
+ .collect::<BTreeSet<_>>();
+ for link_id in &removed {
+ deleted.extend(record_keys(connection, RANGE_KEYS_BY_LINK, link_id)?);
+ }
+ for typename in [EVENT_TYPENAME, CALENDAR_TYPENAME] {
+ for_each_record(connection, typename, |key, record| {
+ if matches!(
+ record.fields.get("linkId"),
+ Some(CacheValue::String(link_id)) if removed.contains(link_id.as_str())
+ ) {
+ deleted.insert(key.as_ref().to_owned());
+ }
+ Ok(())
+ })?;
+ }
+ }
+ Ok(deleted)
+}
+
+fn reset_records(connection: &Arc<Connection>) -> Result<Vec<String>, TursoStorageError> {
+ let mut deleted = Vec::new();
+ for typename in [OCCURRENCE_TYPENAME, EVENT_TYPENAME] {
+ for row in driver::query(
+ connection,
+ "SELECT id FROM records WHERE __typename = ?1",
+ vec![text(typename)],
+ )? {
+ deleted.push(format!("{typename}:{}", required_text(&row, 0)?));
+ }
+ driver::execute(
+ connection,
+ "DELETE FROM records WHERE __typename = ?1",
+ vec![text(typename)],
+ )?;
+ }
+ driver::execute(connection, "DELETE FROM calendar_ranges", Vec::new())?;
+ driver::execute(connection, "DELETE FROM calendar_coverage", Vec::new())?;
+ Ok(deleted)
+}
+
+fn apply_commit(
+ connection: &Arc<Connection>,
+ commit: &CalendarCommit,
+) -> Result<CalendarCommitOutcome, TursoStorageError> {
+ let mut deleted_keys = if commit.reset {
+ reset_records(connection)?
+ } else {
+ Vec::new()
+ };
+ let doomed = collect_deleted_keys(connection, commit)?
+ .into_iter()
+ .map(|key| RecordKey::from_entity(&EntityKey(key.into())))
+ .collect::<Result<Vec<_>, _>>()?;
+ {
+ let mut record_statement = driver::prepare(connection, RECORD_DELETE)?;
+ for key in &doomed {
+ match driver::execute_prepared(
+ &mut record_statement,
+ vec![text(&key.typename), text(&key.id)],
+ )? {
+ 0 => {}
+ 1 => deleted_keys.push(entity_key_text(key)),
+ _ => return Err(invariant()),
+ }
+ }
+ }
+ delete_ranges(connection, &doomed)?;
+
+ if !commit.coverage.is_empty() {
+ let mut coverage = driver::query(connection, COVERAGE_ALL, Vec::new())?
+ .iter()
+ .map(|row| parse_span(row))
+ .collect::<Result<Vec<_>, _>>()?;
+ coverage.extend(commit.coverage.iter().copied());
+ driver::execute(connection, "DELETE FROM calendar_coverage", Vec::new())?;
+ let mut insert = driver::prepare(connection, COVERAGE_INSERT)?;
+ for span in merge_spans(coverage) {
+ require_changed(
+ driver::execute_prepared(
+ &mut insert,
+ vec![
+ Value::from_i64(span.kind.code()),
+ Value::from_i64(span.start),
+ Value::from_i64(span.end),
+ ],
+ )?,
+ 1,
+ )?;
+ }
+ }
+
+ let stored = load_sync_state(connection)?;
+ let next = next_sync_state(&stored, commit);
+ if next != stored {
+ save_sync_state(connection, &next)?;
+ }
+ deleted_keys.sort();
+ deleted_keys.dedup();
+ deleted_keys
+ .into_iter()
+ .map(|key| {
+ RecordKey::from_entity(&EntityKey(key.into()))
+ .map_err(|_| invariant())?
+ .into_entity()
+ })
+ .collect::<Result<Vec<_>, _>>()
+ .map(|deleted_keys| CalendarCommitOutcome { deleted_keys })
+}
+
+impl CalendarRangeStorage for TursoStorage {
+ async fn query_calendar_ranges(
+ &self,
+ request: &CalendarRangeRequest,
+ ) -> Result<CalendarRangeSnapshot, Self::Error> {
+ self.require_healthy()?;
+ let connection = self.connection();
+ let result = driver::read_transaction(&connection, || {
+ Ok(CalendarRangeSnapshot {
+ rows: query_rows(&connection, request)?,
+ coverage: query_coverage(&connection, request)?,
+ sync: load_sync_state(&connection)?,
+ })
+ });
+ self.latch_result(result)
+ }
+
+ async fn calendar_commit(
+ &mut self,
+ commit: &CalendarCommit,
+ ) -> Result<CalendarCommitOutcome, Self::Error> {
+ self.require_healthy()?;
+ let result = (|| {
+ commit
+ .validate()
+ .map_err(|_| TursoStorageError::InvalidInput)?;
+ let connection = self.connection();
+ driver::write_transaction(&connection, || apply_commit(&connection, commit))
+ })();
+ self.latch_result(result)
+ }
+}
+
+/// Validates the frozen calendar tables, their columns, and every index.
+pub(super) fn validate_schema(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {
+ let column = |name, declared_type, not_null, primary_key_position| ColumnSpec {
+ name,
+ declared_type,
+ not_null,
+ default_zero: false,
+ primary_key_position,
+ };
+ validate_table_columns(
+ connection,
+ "calendar_ranges",
+ &[
+ column("record_key", "TEXT", false, 1),
+ column("event_key", "TEXT", true, 0),
+ column("link_id", "TEXT", true, 0),
+ column("kind", "INTEGER", true, 0),
+ column("start", "INTEGER", true, 0),
+ column("end", "INTEGER", true, 0),
+ column("long", "INTEGER", true, 0),
+ ],
+ )?;
+ validate_table_columns(
+ connection,
+ "calendar_coverage",
+ &[
+ column("kind", "INTEGER", true, 1),
+ column("start", "INTEGER", true, 2),
+ column("end", "INTEGER", true, 0),
+ ],
+ )?;
+ validate_table_indexes(
+ connection,
+ "calendar_coverage",
+ &[(0, "kind"), (1, "start")],
+ )?;
+ let indexes = driver::query(
+ connection,
+ "PRAGMA index_list('calendar_ranges')",
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?;
+ let expected = [
+ (
+ "calendar_ranges_scan_idx",
+ &["kind", "long", "start", "record_key"][..],
+ ),
+ (
+ "calendar_ranges_event_idx",
+ &["event_key", "record_key"][..],
+ ),
+ ("calendar_ranges_link_idx", &["link_id", "record_key"][..]),
+ ];
+ if indexes.len() != expected.len() + 1
+ || !indexes.iter().any(|row| {
+ row.len() == 5
+ && required_i64(row, 2).ok() == Some(1)
+ && required_text(row, 3).ok().as_deref() == Some("pk")
+ })
+ {
+ return Err(compatibility());
+ }
+ for (index, expected_columns) in expected {
+ let Some(row) = indexes
+ .iter()
+ .find(|row| required_text(row, 1).ok().as_deref() == Some(index))
+ else {
+ return Err(compatibility());
+ };
+ if row.len() != 5
+ || required_i64(row, 2).ok() != Some(0)
+ || required_text(row, 3).ok().as_deref() != Some("c")
+ {
+ return Err(compatibility());
+ }
+ let columns = driver::query(
+ connection,
+ &format!("PRAGMA index_info('{index}')"),
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?;
+ if columns.len() != expected_columns.len()
+ || columns.iter().zip(expected_columns).enumerate().any(
+ |(position, (row, expected))| {
+ row.len() != 3
+ || required_i64(row, 0).ok() != i64::try_from(position).ok()
+ || required_text(row, 2).ok().as_deref() != Some(*expected)
+ },
+ )
+ {
+ return Err(compatibility());
+ }
+ }
+ for table in TABLES {
+ validate_table_constraints(connection, table, false)?;
+ validate_no_foreign_keys(connection, table)?;
+ }
+ Ok(())
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/client/cache-turso/src/storage/calendar/test.rs b/crates/client/cache-turso/src/storage/calendar/test.rs
new file mode 100644
index 0000000000..b5bc20af91
--- /dev/null
+++ b/crates/client/cache-turso/src/storage/calendar/test.rs
@@ -0,0 +1,501 @@
+use super::*;
+use cache_core::calendar::{CalendarLinkWatermark, CalendarReplacedEvent, CalendarWatermarkUpdate};
+use pollster::block_on;
+use std::collections::BTreeMap;
+
+const HOUR_MS: i64 = 3_600_000;
+const DAY_MS: i64 = 24 * HOUR_MS;
+// 2026-10-05T00:00:00Z
+const MONDAY_MS: i64 = 1_791_158_400_000;
+const MONDAY_DAY: i64 = 20_731;
+
+fn key(value: &str) -> EntityKey<'static> {
+ EntityKey(value.to_owned().into())
+}
+
+fn string(value: &str) -> CacheValue {
+ CacheValue::String(value.into())
+}
+
+fn iso(ms: i64) -> String {
+ chrono::DateTime::from_timestamp_millis(ms)
+ .unwrap()
+ .to_rfc3339()
+}
+
+fn date(day: i64) -> String {
+ (chrono::NaiveDate::from_ymd_opt(1970, 1, 1).unwrap() + chrono::Duration::days(day)).to_string()
+}
+
+fn occurrence(event: &str, link: &str, time: Vec<(&str, String)>) -> Record {
+ let mut record = Record::default();
+ for (field, value) in [
+ ("__typename", string(OCCURRENCE_TYPENAME)),
+ ("eventId", string(event)),
+ ("linkId", string(link)),
+ ("isCancelled", CacheValue::Bool(false)),
+ (
+ "time",
+ CacheValue::Object(
+ time.into_iter()
+ .map(|(field, value)| (field.to_owned(), CacheValue::String(value)))
+ .collect::<BTreeMap<_, _>>(),
+ ),
+ ),
+ ] {
+ record.fields.insert(field.into(), value);
+ }
+ record
+}
+
+fn timed(event: &str, link: &str, start_ms: i64, end_ms: i64) -> (EntityKey<'static>, Record) {
+ (
+ key(&format!("{OCCURRENCE_TYPENAME}:{event}:{}", iso(start_ms))),
+ occurrence(
+ event,
+ link,
+ vec![
+ ("__typename", "GraphqlTimedEventTime".into()),
+ ("startsAt", iso(start_ms)),
+ ("endsAt", iso(end_ms)),
+ ],
+ ),
+ )
+}
+
+fn all_day(event: &str, link: &str, start_day: i64, end_day: i64) -> (EntityKey<'static>, Record) {
+ (
+ key(&format!(
+ "{OCCURRENCE_TYPENAME}:{event}:{}",
+ date(start_day)
+ )),
+ occurrence(
+ event,
+ link,
+ vec![
+ ("__typename", "GraphqlAllDayEventTime".into()),
+ ("startDate", date(start_day)),
+ ("endDate", date(end_day)),
+ ],
+ ),
+ )
+}
+
+fn linked(typename: &str, id: &str, link: &str) -> (EntityKey<'static>, Record) {
+ let mut record = Record::default();
+ record.fields.insert("__typename".into(), string(typename));
+ record.fields.insert("linkId".into(), string(link));
+ (EntityKey::entity(typename, &[id]), record)
+}
+
+fn week() -> CalendarRangeRequest {
+ CalendarRangeRequest {
+ start_ms: MONDAY_MS,
+ end_ms: MONDAY_MS + 7 * DAY_MS,
+ start_day: MONDAY_DAY,
+ end_day: MONDAY_DAY + 7,
+ event_key: None,
+ }
+}
+
+fn week_coverage() -> Vec<CalendarSpan> {
+ week().spans().to_vec()
+}
+
+fn link(link_id: &str, seq: i64) -> CalendarLinkWatermark {
+ CalendarLinkWatermark {
+ link_id: link_id.into(),
+ seq,
+ }
+}
+
+fn keys(snapshot: &CalendarRangeSnapshot) -> Vec<String> {
+ let mut keys = snapshot
+ .rows
+ .iter()
+ .map(|row| row.record_key.as_ref().to_owned())
+ .collect::<Vec<_>>();
+ keys.sort();
+ keys
+}
+
+fn raw_execute(storage: &TursoStorage, sql: &str) {
+ driver::execute(&storage.connection(), sql, Vec::new()).unwrap();
+}
+
+fn row_count(storage: &TursoStorage) -> i64 {
+ let rows = driver::query(
+ &storage.connection(),
+ "SELECT COUNT(*) FROM calendar_ranges",
+ Vec::new(),
+ )
+ .unwrap();
+ required_i64(&rows[0], 0).unwrap()
+}
+
+#[test]
+fn range_rows_are_written_through_with_records() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("calendar-write-through").unwrap();
+ let inside = timed("e1", "l1", MONDAY_MS + HOUR_MS, MONDAY_MS + 2 * HOUR_MS);
+ let long = timed("e2", "l1", MONDAY_MS - 20 * DAY_MS, MONDAY_MS + HOUR_MS);
+ let before = timed("e3", "l1", MONDAY_MS - 2 * HOUR_MS, MONDAY_MS);
+ let holiday = all_day("e4", "l1", MONDAY_DAY + 3, MONDAY_DAY + 4);
+ storage
+ .put_batch(vec![
+ inside.clone(),
+ long.clone(),
+ before,
+ holiday.clone(),
+ linked(EVENT_TYPENAME, "e1", "l1"),
+ ])
+ .await
+ .unwrap();
+ assert_eq!(row_count(&storage), 4);
+ let mut expected = vec![
+ inside.0.as_ref().to_owned(),
+ long.0.as_ref().to_owned(),
+ holiday.0.as_ref().to_owned(),
+ ];
+ expected.sort();
+ assert_eq!(
+ keys(&storage.query_calendar_ranges(&week()).await.unwrap()),
+ expected
+ );
+
+ let mut cancelled = inside.1.clone();
+ cancelled
+ .fields
+ .insert("isCancelled".into(), CacheValue::Bool(true));
+ storage
+ .put_batch(vec![
+ (inside.0.clone(), inside.1.clone()),
+ (inside.0.clone(), cancelled),
+ ])
+ .await
+ .unwrap();
+ storage
+ .delete_batch(std::slice::from_ref(&holiday.0))
+ .await
+ .unwrap();
+ assert_eq!(
+ keys(&storage.query_calendar_ranges(&week()).await.unwrap()),
+ [long.0.as_ref().to_owned()]
+ );
+
+ let mut only_e2 = week();
+ only_e2.event_key = Some(key("GraphqlCalendarEvent:e2"));
+ assert_eq!(
+ keys(&storage.query_calendar_ranges(&only_e2).await.unwrap()),
+ [long.0.as_ref().to_owned()]
+ );
+ only_e2.start_ms = MONDAY_MS - 31 * DAY_MS;
+ only_e2.end_ms = MONDAY_MS - 30 * DAY_MS;
+ assert!(
+ storage
+ .query_calendar_ranges(&only_e2)
+ .await
+ .unwrap()
+ .rows
+ .is_empty()
+ );
+ });
+}
+
+#[test]
+fn range_lookups_use_the_scan_index_without_touching_unrelated_rows() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("calendar-scan-cost").unwrap();
+ storage
+ .put_batch(vec![timed("e1", "l1", MONDAY_MS, MONDAY_MS + HOUR_MS)])
+ .await
+ .unwrap();
+ let mut costs = Vec::new();
+ for unrelated in [0, 5_000] {
+ storage
+ .put_batch(
+ (0..unrelated)
+ .map(|index| {
+ let start = MONDAY_MS + (30 + index) * DAY_MS;
+ timed(&format!("far-{index}"), "l1", start, start + HOUR_MS)
+ })
+ .collect(),
+ )
+ .await
+ .unwrap();
+ let mut statement = driver::prepare(&storage.connection(), RANGE_SHORT).unwrap();
+ let rows = driver::query_prepared(
+ &mut statement,
+ vec![
+ Value::from_i64(0),
+ Value::from_i64(MONDAY_MS - 7 * DAY_MS),
+ Value::from_i64(MONDAY_MS + 7 * DAY_MS),
+ Value::from_i64(MONDAY_MS),
+ ],
+ )
+ .unwrap();
+ assert_eq!(rows.len(), 1);
+ costs.push(statement.metrics().vm_steps);
+ }
+ assert!(
+ costs[1] <= costs[0] + 50,
+ "VM steps grew with unrelated rows: {costs:?}"
+ );
+ for sql in [RANGE_SHORT, RANGE_LONG, RANGE_BY_EVENT, RANGE_KEYS_BY_LINK] {
+ let parameters = vec![
+ Value::from_i64(0);
+ driver::prepare(&storage.connection(), sql)
+ .unwrap()
+ .parameters_count()
+ ];
+ let plan = driver::query(
+ &storage.connection(),
+ &format!("EXPLAIN QUERY PLAN {sql}"),
+ parameters,
+ )
+ .unwrap()
+ .iter()
+ .filter_map(|row| required_text(row, 3).ok())
+ .collect::<Vec<_>>()
+ .join(" ");
+ assert!(plan.contains("calendar_ranges_"), "{sql}: {plan}");
+ }
+ });
+}
+
+#[test]
+fn commits_delete_records_merge_coverage_and_persist_sync_state() {
+ block_on(async {
+ let database = TursoMemoryDatabase::new("calendar-commit.db");
+ let mut storage = database.open("scope").unwrap();
+ let kept = timed("e1", "l1", MONDAY_MS + HOUR_MS, MONDAY_MS + 2 * HOUR_MS);
+ let stale = timed("e1", "l1", MONDAY_MS + DAY_MS, MONDAY_MS + DAY_MS + HOUR_MS);
+ let deleted = timed("e2", "l1", MONDAY_MS + 3 * HOUR_MS, MONDAY_MS + 4 * HOUR_MS);
+ let removed = timed("e3", "l2", MONDAY_MS + 5 * HOUR_MS, MONDAY_MS + 6 * HOUR_MS);
+ let removed_event = linked(EVENT_TYPENAME, "e3", "l2");
+ let removed_calendar = linked(CALENDAR_TYPENAME, "c2", "l2");
+ let kept_calendar = linked(CALENDAR_TYPENAME, "c1", "l1");
+ storage
+ .put_batch(vec![
+ kept.clone(),
+ stale.clone(),
+ deleted.clone(),
+ removed.clone(),
+ removed_event.clone(),
+ removed_calendar.clone(),
+ kept_calendar.clone(),
+ linked(EVENT_TYPENAME, "e2", "l1"),
+ ])
+ .await
+ .unwrap();
+ let outcome = storage
+ .calendar_commit(&CalendarCommit {
+ coverage: vec![CalendarSpan {
+ kind: CalendarSpanKind::Timed,
+ start: MONDAY_MS,
+ end: MONDAY_MS + 3 * DAY_MS,
+ }],
+ replaced_events: vec![CalendarReplacedEvent {
+ event_key: key("GraphqlCalendarEvent:e1"),
+ occurrence_keys: vec![kept.0.clone()],
+ }],
+ deleted_event_keys: vec![key("GraphqlCalendarEvent:e2")],
+ removed_link_ids: vec!["l2".into()],
+ watermark: Some(CalendarWatermarkUpdate::Merge {
+ links: vec![link("l1", 9), link("l2", 3)],
+ }),
+ freshness: Some(CalendarFreshness::Fresh),
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap();
+ let mut expected = vec![
+ removed_calendar.0.clone(),
+ key("GraphqlCalendarEvent:e2"),
+ removed_event.0.clone(),
+ deleted.0.clone(),
+ stale.0.clone(),
+ removed.0.clone(),
+ ];
+ expected.sort();
+ assert_eq!(outcome.deleted_keys, expected);
+ storage
+ .calendar_commit(&CalendarCommit {
+ coverage: vec![CalendarSpan {
+ kind: CalendarSpanKind::Timed,
+ start: MONDAY_MS + 3 * DAY_MS,
+ end: MONDAY_MS + 7 * DAY_MS,
+ }],
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap();
+ storage.try_close().unwrap();
+
+ let storage = database.open("scope").unwrap();
+ let snapshot = storage.query_calendar_ranges(&week()).await.unwrap();
+ assert_eq!(keys(&snapshot), [kept.0.as_ref().to_owned()]);
+ assert_eq!(
+ snapshot.coverage,
+ [CalendarSpan {
+ kind: CalendarSpanKind::Timed,
+ start: MONDAY_MS,
+ end: MONDAY_MS + 7 * DAY_MS,
+ }]
+ );
+ assert_eq!(
+ snapshot.sync,
+ CalendarSyncState {
+ watermark: Some(vec![link("l1", 9)]),
+ freshness: CalendarFreshness::Fresh,
+ }
+ );
+ assert_eq!(
+ storage
+ .get_batch(&[kept_calendar.0, removed_calendar.0])
+ .await
+ .unwrap()
+ .iter()
+ .map(Option::is_some)
+ .collect::<Vec<_>>(),
+ [true, false]
+ );
+ storage.try_close().unwrap();
+ });
+}
+
+#[test]
+fn reset_and_clear_drop_calendar_state() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("calendar-reset").unwrap();
+ let occurrence = timed("e1", "l1", MONDAY_MS, MONDAY_MS + HOUR_MS);
+ let event = linked(EVENT_TYPENAME, "e1", "l1");
+ let calendar = linked(CALENDAR_TYPENAME, "c1", "l1");
+ storage
+ .put_batch(vec![occurrence.clone(), event.clone(), calendar.clone()])
+ .await
+ .unwrap();
+ storage
+ .calendar_commit(&CalendarCommit {
+ coverage: week_coverage(),
+ watermark: Some(CalendarWatermarkUpdate::Merge {
+ links: vec![link("l1", 2)],
+ }),
+ freshness: Some(CalendarFreshness::Stale),
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap();
+ let outcome = storage
+ .calendar_commit(&CalendarCommit {
+ reset: true,
+ watermark: Some(CalendarWatermarkUpdate::Advance {
+ since: vec![link("l1", 2)],
+ to: vec![link("l1", 20)],
+ }),
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap();
+ let mut expected = vec![event.0.clone(), occurrence.0.clone()];
+ expected.sort();
+ assert_eq!(outcome.deleted_keys, expected);
+ let snapshot = storage.query_calendar_ranges(&week()).await.unwrap();
+ assert!(snapshot.rows.is_empty() && snapshot.coverage.is_empty());
+ assert_eq!(
+ snapshot.sync,
+ CalendarSyncState {
+ watermark: Some(vec![link("l1", 20)]),
+ freshness: CalendarFreshness::Unknown,
+ }
+ );
+ assert!(storage.get_batch(&[calendar.0]).await.unwrap()[0].is_some());
+
+ storage.put_batch(vec![occurrence]).await.unwrap();
+ storage
+ .calendar_commit(&CalendarCommit {
+ coverage: week_coverage(),
+ freshness: Some(CalendarFreshness::Fresh),
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap();
+ storage.clear().await.unwrap();
+ assert_eq!(row_count(&storage), 0);
+ assert_eq!(
+ storage.query_calendar_ranges(&week()).await.unwrap(),
+ CalendarRangeSnapshot::default()
+ );
+ });
+}
+
+#[test]
+fn reopen_rebuilds_range_rows_after_a_projection_change() {
+ block_on(async {
+ let database = TursoMemoryDatabase::new("calendar-projection.db");
+ let mut storage = database.open("scope").unwrap();
+ let entries = (0..300)
+ .map(|index| {
+ let start = MONDAY_MS + index * HOUR_MS;
+ timed(&format!("e{index:03}"), "l1", start, start + HOUR_MS)
+ })
+ .collect::<Vec<_>>();
+ storage.put_batch(entries).await.unwrap();
+ raw_execute(&storage, "DELETE FROM calendar_ranges");
+ raw_execute(
+ &storage,
+ "UPDATE meta SET value = '0' WHERE key = 'calendar_projection_version'",
+ );
+ storage.try_close().unwrap();
+
+ let storage = database.open("scope").unwrap();
+ assert_eq!(row_count(&storage), 300);
+ storage.try_close().unwrap();
+
+ // A normal reopen neither scans nor decodes occurrence records.
+ driver::arm_reset_failure(SEARCH_REBUILD_RECORDS);
+ let storage = database.open("scope").unwrap();
+ assert_eq!(row_count(&storage), 300);
+ storage.try_close().unwrap();
+ });
+}
+
+#[test]
+fn reopen_rejects_a_calendar_schema_drift() {
+ block_on(async {
+ let database = TursoMemoryDatabase::new("calendar-schema.db");
+ let storage = database.open("scope").unwrap();
+ raw_execute(&storage, "DROP INDEX calendar_ranges_link_idx");
+ storage.try_close().unwrap();
+ let Err(error) = database.open("scope") else {
+ panic!("a drifted calendar schema must not open");
+ };
+ assert_eq!(
+ error.physical_reset_reason(),
+ Some(PhysicalResetReason::Compatibility)
+ );
+ });
+}
+
+#[test]
+fn invalid_commits_never_open_a_transaction() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("calendar-invalid").unwrap();
+ let error = storage
+ .calendar_commit(&CalendarCommit {
+ deleted_calendar_keys: vec![key("GraphqlCalendarEvent:e1")],
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap_err();
+ assert!(!error.requires_physical_reset());
+ assert!(
+ storage
+ .query_calendar_ranges(&week())
+ .await
+ .unwrap()
+ .rows
+ .is_empty()
+ );
+ });
+}
diff --git a/crates/client/cache-turso/src/storage/test.rs b/crates/client/cache-turso/src/storage/test.rs
index 638b12898c..f2eb6496ba 100644
--- a/crates/client/cache-turso/src/storage/test.rs
+++ b/crates/client/cache-turso/src/storage/test.rs
@@ -491,7 +491,7 @@ fn fresh_schema_metadata_foreign_keys_quick_check_and_cascade_are_real() {
let mut storage = TursoStorage::open_in_memory("schema-scope").unwrap();
assert_eq!(raw_scalar(&storage, "PRAGMA foreign_keys"), 1);
storage.check_integrity().unwrap();
- assert_eq!(raw_scalar(&storage, "SELECT COUNT(*) FROM meta"), 5);
+ assert_eq!(raw_scalar(&storage, "SELECT COUNT(*) FROM meta"), 6);
let violation = driver::execute(
&storage.connection(),
diff --git a/crates/client/cache-turso/src/storage/test/projection_writes.rs b/crates/client/cache-turso/src/storage/test/projection_writes.rs
index a89f6f760a..9d4f5e0ef7 100644
--- a/crates/client/cache-turso/src/storage/test/projection_writes.rs
+++ b/crates/client/cache-turso/src/storage/test/projection_writes.rs
@@ -134,6 +134,7 @@ fn unchanged_authority_still_rebases_durable_optimistic_intent() {
projection_mutations: vec![predicate_index::OptimisticProjectionMutation::Replace(
optimistic.clone(),
)],
+ uncertain_calendar_event_keys: Vec::new(),
});
let owner = storage.enqueue_mutation(mutation).await.unwrap();
assert_eq!(
diff --git a/crates/client/cache-turso/tests/shared_conformance.rs b/crates/client/cache-turso/tests/shared_conformance.rs
index ca87868800..008ff794e4 100644
--- a/crates/client/cache-turso/tests/shared_conformance.rs
+++ b/crates/client/cache-turso/tests/shared_conformance.rs
@@ -1,5 +1,10 @@
#![cfg(not(target_arch = "wasm32"))]
+use cache_core::calendar::{
+ CalendarCommit, CalendarFreshness, CalendarLinkWatermark, CalendarRangeRequest,
+ CalendarRangeStorage, CalendarReplacedEvent, CalendarSpan, CalendarSpanKind, CalendarSyncState,
+ CalendarWatermarkUpdate,
+};
use cache_core::normalize::RecordUpdates;
use cache_core::queue::{
MutationClaimRequest, MutationClaimToken, MutationRequest, NewQueuedMutation,
@@ -12,7 +17,7 @@ use cache_turso::{TursoMemoryDatabase, TursoStorage, TursoStorageCloseOutcome};
use pollster::block_on;
trait BackendFactory: Sized {
- type Backend: Storage;
+ type Backend: CalendarRangeStorage;
fn create() -> (Self, Self::Backend);
fn reopen(&mut self, storage: Self::Backend) -> Self::Backend;
@@ -618,6 +623,163 @@ async fn clear_contract<S: Storage>(storage: &mut S) {
assert!(storage.load_mutation_queue().await.unwrap().is_empty());
}
+fn occurrence(event: &str, link: &str, time: &[(&str, &str)]) -> Record {
+ let mut record = Record::default();
+ for (field, value) in [
+ (
+ "__typename",
+ CacheValue::String("GraphqlCalendarOccurrence".into()),
+ ),
+ ("eventId", CacheValue::String(event.into())),
+ ("linkId", CacheValue::String(link.into())),
+ ("isCancelled", CacheValue::Bool(false)),
+ (
+ "time",
+ CacheValue::Object(
+ time.iter()
+ .map(|(field, value)| {
+ ((*field).to_owned(), CacheValue::String((*value).into()))
+ })
+ .collect(),
+ ),
+ ),
+ ] {
+ record.fields.insert(field.into(), value);
+ }
+ record
+}
+
+async fn calendar_contract<F: BackendFactory>(
+ factory: &mut F,
+ mut storage: F::Backend,
+) -> F::Backend {
+ // 2026-10-05T00:00:00Z through 2026-10-12, and the same dates for all-day rows.
+ let week = CalendarRangeRequest {
+ start_ms: 1_791_158_400_000,
+ end_ms: 1_791_763_200_000,
+ start_day: 20_731,
+ end_day: 20_738,
+ event_key: None,
+ };
+ let standup = key("GraphqlCalendarOccurrence:e1:2026-10-06T09:00:00+00:00");
+ let moved = key("GraphqlCalendarOccurrence:e1:2026-10-07T09:00:00+00:00");
+ let holiday = key("GraphqlCalendarOccurrence:e2:2026-10-09");
+ let other_link = key("GraphqlCalendarOccurrence:e3:2026-10-08T09:00:00+00:00");
+ let timed = |starts_at, ends_at| {
+ [
+ ("__typename", "GraphqlTimedEventTime"),
+ ("startsAt", starts_at),
+ ("endsAt", ends_at),
+ ]
+ };
+ storage
+ .put_batch(vec![
+ (
+ standup.clone(),
+ occurrence(
+ "e1",
+ "l1",
+ &timed("2026-10-06T09:00:00+00:00", "2026-10-06T09:30:00+00:00"),
+ ),
+ ),
+ (
+ moved.clone(),
+ occurrence(
+ "e1",
+ "l1",
+ &timed("2026-10-07T09:00:00+00:00", "2026-10-07T09:30:00+00:00"),
+ ),
+ ),
+ (
+ holiday.clone(),
+ occurrence(
+ "e2",
+ "l1",
+ &[
+ ("__typename", "GraphqlAllDayEventTime"),
+ ("startDate", "2026-10-09"),
+ ("endDate", "2026-10-10"),
+ ],
+ ),
+ ),
+ (
+ other_link.clone(),
+ occurrence(
+ "e3",
+ "l2",
+ &timed("2026-10-08T09:00:00+00:00", "2026-10-08T10:00:00+00:00"),
+ ),
+ ),
+ ])
+ .await
+ .unwrap();
+ let outcome = storage
+ .calendar_commit(&CalendarCommit {
+ coverage: week.spans().to_vec(),
+ replaced_events: vec![CalendarReplacedEvent {
+ event_key: key("GraphqlCalendarEvent:e1"),
+ occurrence_keys: vec![standup.clone()],
+ }],
+ removed_link_ids: vec!["l2".into()],
+ watermark: Some(CalendarWatermarkUpdate::Merge {
+ links: vec![CalendarLinkWatermark {
+ link_id: "l1".into(),
+ seq: 4,
+ }],
+ }),
+ freshness: Some(CalendarFreshness::Fresh),
+ ..CalendarCommit::default()
+ })
+ .await
+ .unwrap();
+ let mut expected_deleted = vec![moved, other_link];
+ expected_deleted.sort();
+ assert_eq!(outcome.deleted_keys, expected_deleted);
+
+ let storage = factory.reopen(storage);
+ let mut snapshot = storage.query_calendar_ranges(&week).await.unwrap();
+ snapshot
+ .rows
+ .sort_by(|left, right| left.record_key.cmp(&right.record_key));
+ assert_eq!(
+ snapshot
+ .rows
+ .iter()
+ .map(|row| (row.record_key.clone(), row.span))
+ .collect::<Vec<_>>(),
+ [
+ (
+ standup,
+ CalendarSpan {
+ kind: CalendarSpanKind::Timed,
+ start: 1_791_277_200_000,
+ end: 1_791_279_000_000,
+ }
+ ),
+ (
+ holiday,
+ CalendarSpan {
+ kind: CalendarSpanKind::AllDay,
+ start: 20_735,
+ end: 20_736,
+ }
+ ),
+ ]
+ );
+ assert_eq!(snapshot.coverage, week.spans());
+ assert_eq!(
+ snapshot.sync,
+ CalendarSyncState {
+ watermark: Some(vec![CalendarLinkWatermark {
+ link_id: "l1".into(),
+ seq: 4,
+ }]),
+ freshness: CalendarFreshness::Fresh,
+ }
+ );
+ storage
+}
+
async fn common_contract<F: BackendFactory>(
factory: &mut F,
mut storage: F::Backend,
@@ -626,8 +788,22 @@ async fn common_contract<F: BackendFactory>(
search_projection_contract(&mut storage).await;
let mut storage = reopen_contract(factory, storage).await;
queue_contract(&mut storage).await;
- let mut storage = retry_budget_contract(factory, storage).await;
+ let storage = retry_budget_contract(factory, storage).await;
+ let mut storage = calendar_contract(factory, storage).await;
clear_contract(&mut storage).await;
+ assert_eq!(
+ storage
+ .query_calendar_ranges(&CalendarRangeRequest {
+ start_ms: 0,
+ end_ms: i64::MAX,
+ start_day: 0,
+ end_day: i64::MAX,
+ event_key: None,
+ })
+ .await
+ .unwrap(),
+ Default::default()
+ );
storage
}
diff --git a/crates/client/cache-wasm/Cargo.toml b/crates/client/cache-wasm/Cargo.toml
index 3c9832f30c..7bc1c0f802 100644
--- a/crates/client/cache-wasm/Cargo.toml
+++ b/crates/client/cache-wasm/Cargo.toml
@@ -3,7 +3,8 @@ edition = "2024"
name = "cache-wasm"
publish = false
# Rebuild for reminder return timestamps in the local Mail index.
-version = "0.6.39"
+# Rebuild with the calendar range index and the compatibility epoch 4 storage name.
+version = "0.6.40"
[features]
default = []