Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
feat(calendar): expose calendarChanges and page watermarks over GraphQL (#7675)
gbirman1899b9e62fbd
diff --git a/crates/complete_graph/src/schema/test/calendar.rs b/crates/complete_graph/src/schema/test/calendar.rsindex e4dbd21bc1..c975dc99ce 100644--- a/crates/complete_graph/src/schema/test/calendar.rs+++ b/crates/complete_graph/src/schema/test/calendar.rs@@ -1,6 +1,7 @@use std::sync::{Arc, Mutex};use calendar_events::domain::{+ changes::{CalendarChangeQueryService, CalendarChangesPage, CalendarWatermark},models::{CalendarEvent, CalendarMentionPreview, CalendarMentionRequestItem, CalendarOccurrence,CalendarOccurrenceCursor, CalendarSyncStatus, EventReminders, EventStatus, EventTime,@@ -128,11 +129,30 @@ impl CalendarOccurrenceService for RecordingCalendarReads {}}+impl CalendarChangeQueryService for RecordingCalendarReads {+ async fn current_watermark(&self, requester_id: &str) -> Result<CalendarWatermark, Report> {+ self.viewers.lock().unwrap().push(requester_id.to_owned());+ Ok(CalendarWatermark::default())+ }++ async fn changes_since(+ &self,+ requester_id: &str,+ _since: CalendarWatermark,+ ) -> Result<CalendarChangesPage, Report> {+ self.viewers.lock().unwrap().push(requester_id.to_owned());+ Ok(CalendarChangesPage {+ reset_required: true,+ ..CalendarChangesPage::default()+ })+ }+}+#[tokio::test]async fn calendar_fields_read_through_request_data_for_the_viewer() {let harness = harness();let reads = Arc::new(RecordingCalendarReads::default());- let context = CalendarGraphqlContext::new(Arc::clone(&reads));+ let context = CalendarGraphqlContext::new(Arc::clone(&reads), Arc::clone(&reads));let id_only = harness.schema@@ -157,8 +177,9 @@ async fn calendar_fields_read_through_request_data_for_the_viewer() {start: "2026-10-05T00:00:00Z", end: "2026-10-12T00:00:00Z"}) {nodes { id eventId linkId event { id title } }- hasNextPage syncStatus+ hasNextPage syncStatus watermark { linkId seq }}+ calendarChanges(input: { since: [] }) { resetRequired }} }"#,authenticated_parts(),)@@ -174,10 +195,10 @@ async fn calendar_fields_read_through_request_data_for_the_viewer() {assert_eq!(node["id"], format!("{EVENT_ID}:2026-10-06T15:00:00+00:00"));assert_eq!(node["event"]["title"], "Planning");assert_eq!(user["calendarOccurrences"]["syncStatus"], "READY");- assert_eq!(- *reads.viewers.lock().unwrap(),- vec![VALID_USER_ID.to_owned(), VALID_USER_ID.to_owned()]- );+ assert_eq!(user["calendarChanges"]["resetRequired"], true);+ let viewers = reads.viewers.lock().unwrap();+ assert_eq!(viewers.len(), 4);+ assert!(viewers.iter().all(|viewer| viewer == VALID_USER_ID));}#[tokio::test]diff --git a/crates/complete_graph/src/sdl_test.rs b/crates/complete_graph/src/sdl_test.rsindex 3f14904080..ec0410b75d 100644--- a/crates/complete_graph/src/sdl_test.rs+++ b/crates/complete_graph/src/sdl_test.rs@@ -720,6 +720,10 @@ fn calendar_reads_hang_off_the_authenticated_user() {"calendarOccurrences(input: CalendarRangeInput!): GraphqlCalendarOccurrencePage!","union GraphqlEventTime = GraphqlTimedEventTime | GraphqlAllDayEventTime","watermark: [GraphqlCalendarLinkWatermark!]!",+ "calendarChanges(input: CalendarChangesInput!): GraphqlCalendarChanges!",+ "since: [CalendarLinkWatermarkInput!]!",+ "newWatermark: [GraphqlCalendarLinkWatermark!]!",+ "occurrences: [GraphqlCalendarOccurrence!]!","needsCalendarPermission: Boolean!","calendarDisabled: Boolean!","hasCalendarData: Boolean!",@@ -756,6 +760,7 @@ fn calendar_reads_hang_off_the_authenticated_user() {};assert!(!root.fields.contains_key("calendars"));assert!(!root.fields.contains_key("calendarOccurrences"));+ assert!(!root.fields.contains_key("calendarChanges"));}/// The exported SDL is a frontend contract: `schema.graphql` feeds the clientdiff --git a/crates/graphql_calendar/src/inputs.rs b/crates/graphql_calendar/src/inputs.rsindex 4d8ff6b2dd..d600035cde 100644--- a/crates/graphql_calendar/src/inputs.rs+++ b/crates/graphql_calendar/src/inputs.rs@@ -1,6 +1,10 @@-use async_graphql::InputObject;-use calendar_events::domain::models::{CalendarOccurrenceCursor, OccurrenceRange};+use async_graphql::{ID, InputObject};+use calendar_events::domain::{+ changes::{CalendarLinkWatermark, CalendarWatermark},+ models::{CalendarOccurrenceCursor, OccurrenceRange},+};use chrono::{DateTime, NaiveDate, NaiveTime, Utc};+use graphql_common::parse_id;use models_pagination::Base64Str;use crate::bad_input;@@ -106,3 +110,41 @@ fn default_end_date(end: DateTime<Utc>) -> Option<NaiveDate> {end.date_naive().succ_opt()}}++/// How far the client has applied one connected inbox's change log.+#[derive(InputObject, Clone, Debug)]+pub struct CalendarLinkWatermarkInput {+ /// Connected inbox identifier.+ pub link_id: ID,+ /// Last applied sequence, as the decimal string the server returned.+ pub seq: String,+}++/// A request for calendar changes after a watermark.+#[derive(InputObject, Clone, Debug)]+pub struct CalendarChangesInput {+ /// The client's watermark, one entry per tracked connected inbox. Empty+ /// returns only the current watermark.+ pub since: Vec<CalendarLinkWatermarkInput>,+}++impl CalendarChangesInput {+ pub(crate) fn into_watermark(self) -> async_graphql::Result<CalendarWatermark> {+ let links = self+ .since+ .into_iter()+ .map(|link| {+ let link_id = parse_id(link.link_id, "since.linkId")+ .map_err(|_| bad_input("since.linkId must be a UUID"))?;+ let seq = link+ .seq+ .parse::<i64>()+ .ok()+ .filter(|seq| *seq >= 0)+ .ok_or_else(|| bad_input("since.seq must be a non-negative integer"))?;+ Ok(CalendarLinkWatermark { link_id, seq })+ })+ .collect::<async_graphql::Result<Vec<_>>>()?;+ Ok(CalendarWatermark::from_links(links))+ }+}diff --git a/crates/graphql_calendar/src/lib.rs b/crates/graphql_calendar/src/lib.rsindex 522c9776a6..767dc44cac 100644--- a/crates/graphql_calendar/src/lib.rs+++ b/crates/graphql_calendar/src/lib.rs@@ -9,10 +9,11 @@ mod reads;mod test_fixtures;mod user_query;-pub use inputs::CalendarRangeInput;+pub use inputs::{CalendarChangesInput, CalendarLinkWatermarkInput, CalendarRangeInput};pub use objects::{GraphqlAllDayEventTime, GraphqlCalendar, GraphqlCalendarAttendee,- GraphqlCalendarAttendeeResponseStatus, GraphqlCalendarConferenceProvider, GraphqlCalendarEvent,+ GraphqlCalendarAttendeeResponseStatus, GraphqlCalendarChanges,+ GraphqlCalendarConferenceProvider, GraphqlCalendarEvent, GraphqlCalendarEventChange,GraphqlCalendarEventSource, GraphqlCalendarEventStatus, GraphqlCalendarEventTransparency,GraphqlCalendarEventType, GraphqlCalendarEventVisibility, GraphqlCalendarLinkWatermark,GraphqlCalendarOccurrence, GraphqlCalendarOccurrencePage, GraphqlCalendarReminderOverride,diff --git a/crates/graphql_calendar/src/objects.rs b/crates/graphql_calendar/src/objects.rsindex 355bb45d78..346365f45c 100644--- a/crates/graphql_calendar/src/objects.rs+++ b/crates/graphql_calendar/src/objects.rs@@ -1,9 +1,14 @@+use std::{collections::HashMap, sync::Arc};+use async_graphql::{Enum, ID, SimpleObject, Union};-use calendar_events::domain::models::{- AttendeeResponseStatus, CalendarAttendee, CalendarEvent, CalendarEventSourceContent,- CalendarOccurrence, CalendarSyncStatus, ConferenceProvider, EventReminderOverride,- EventReminders, EventStatus, EventTime, EventTransparency, EventType, EventVisibility,- OccurrenceListing, VisibleCalendar,+use calendar_events::domain::{+ changes::{CalendarChangesPage, CalendarEventChange, CalendarWatermark},+ models::{+ AttendeeResponseStatus, CalendarAttendee, CalendarEvent, CalendarEventSourceContent,+ CalendarOccurrence, CalendarSyncStatus, ConferenceProvider, EventReminderOverride,+ EventReminders, EventStatus, EventTime, EventTransparency, EventType, EventVisibility,+ OccurrenceException, OccurrenceListing, VisibleCalendar,+ },};use uuid::Uuid;@@ -437,7 +442,7 @@ pub struct GraphqlCalendarOccurrence {/// Connected inbox whose grant backs the event.link_id: ID,/// The series event.- event: GraphqlCalendarEvent,+ event: Arc<GraphqlCalendarEvent>,/// Stable key within the event.occurrence_key: String,/// Provider recurrence identifier, when applicable.@@ -459,14 +464,13 @@ pub struct GraphqlCalendarOccurrence {override_attendees: Option<Vec<GraphqlCalendarAttendee>>,}-impl From<OccurrenceListing> for GraphqlCalendarOccurrence {- fn from(listing: OccurrenceListing) -> Self {- let OccurrenceListing {- event,- occurrence,- link_id,- exception,- } = listing;+impl GraphqlCalendarOccurrence {+ fn new(+ event: Arc<GraphqlCalendarEvent>,+ link_id: Uuid,+ occurrence: CalendarOccurrence,+ exception: OccurrenceException,+ ) -> Self {let CalendarOccurrence {event_id,occurrence_key,@@ -478,7 +482,7 @@ impl From<OccurrenceListing> for GraphqlCalendarOccurrence {id: occurrence_id(event_id, &occurrence_key),event_id: id(event_id),link_id: id(link_id),- event: GraphqlCalendarEvent::new(event, link_id),+ event,occurrence_key,recurrence_id,time: time.into(),@@ -494,6 +498,29 @@ impl From<OccurrenceListing> for GraphqlCalendarOccurrence {}}+/// Map viewport listings, sharing one series event per event among its+/// occurrences.+pub(crate) fn occurrence_nodes(listings: Vec<OccurrenceListing>) -> Vec<GraphqlCalendarOccurrence> {+ let mut events: HashMap<Uuid, Arc<GraphqlCalendarEvent>> = HashMap::new();+ listings+ .into_iter()+ .map(|listing| {+ let OccurrenceListing {+ event,+ occurrence,+ link_id,+ exception,+ } = listing;+ let event = Arc::clone(+ events+ .entry(event.id)+ .or_insert_with(|| Arc::new(GraphqlCalendarEvent::new(event, link_id))),+ );+ GraphqlCalendarOccurrence::new(event, link_id, occurrence, exception)+ })+ .collect()+}+/// A calendar visible to the viewer.#[derive(SimpleObject, Clone, Debug, PartialEq, Eq)]pub struct GraphqlCalendar {@@ -550,6 +577,89 @@ pub struct GraphqlCalendarLinkWatermark {pub(crate) seq: String,}+pub(crate) fn watermark_entries(+ watermark: &CalendarWatermark,+) -> Vec<GraphqlCalendarLinkWatermark> {+ watermark+ .links()+ .map(|link| GraphqlCalendarLinkWatermark {+ link_id: id(link.link_id),+ seq: link.seq.to_string(),+ })+ .collect()+}++/// A changed event with its complete current set of visible occurrences.+/// Clients replace everything they hold for the event with it.+#[derive(SimpleObject, Clone, Debug, PartialEq, Eq)]+pub struct GraphqlCalendarEventChange {+ /// The series event.+ event: Arc<GraphqlCalendarEvent>,+ /// Every non-cancelled materialized occurrence, ordered by start.+ occurrences: Vec<GraphqlCalendarOccurrence>,+}++impl From<CalendarEventChange> for GraphqlCalendarEventChange {+ fn from(change: CalendarEventChange) -> Self {+ let CalendarEventChange {+ event,+ link_id,+ occurrences,+ } = change;+ let event = Arc::new(GraphqlCalendarEvent::new(event, link_id));+ Self {+ occurrences: occurrences+ .into_iter()+ .map(|instance| {+ GraphqlCalendarOccurrence::new(+ Arc::clone(&event),+ link_id,+ instance.occurrence,+ instance.exception,+ )+ })+ .collect(),+ event,+ }+ }+}++/// One bounded page of calendar changes after a watermark.+#[derive(SimpleObject, Clone, Debug, PartialEq, Eq)]+pub struct GraphqlCalendarChanges {+ /// Events created or changed, each with its full occurrence set.+ events: Vec<GraphqlCalendarEventChange>,+ /// Events that no longer exist or no longer have a visible occurrence.+ deleted_event_ids: Vec<ID>,+ /// Calendars created or changed.+ calendars: Vec<GraphqlCalendar>,+ /// Calendars that were removed.+ deleted_calendar_ids: Vec<ID>,+ /// Position after this page, one entry per currently visible connected+ /// inbox. An inbox missing here is no longer visible.+ new_watermark: Vec<GraphqlCalendarLinkWatermark>,+ /// Whether more changes follow `newWatermark`.+ has_more: bool,+ /// Whether the client must drop every calendar record and coverage it+ /// holds and refetch: its watermark fell behind retention, or an inbox+ /// became visible that it never tracked.+ reset_required: bool,+}++impl From<CalendarChangesPage> for GraphqlCalendarChanges {+ fn from(page: CalendarChangesPage) -> Self {+ Self {+ events: page.events.into_iter().map(Into::into).collect(),+ deleted_event_ids: page.deleted_event_ids.into_iter().map(id).collect(),+ calendars: page.calendars.into_iter().map(Into::into).collect(),+ deleted_calendar_ids: page.deleted_calendar_ids.into_iter().map(id).collect(),+ new_watermark: watermark_entries(&page.new_watermark),+ has_more: page.has_more,+ reset_required: page.reset_required,+ }+ }+}+/// One page of occurrences overlapping a viewport.#[derive(SimpleObject, Clone, Debug, PartialEq, Eq)]pub struct GraphqlCalendarOccurrencePage {diff --git a/crates/graphql_calendar/src/objects/test.rs b/crates/graphql_calendar/src/objects/test.rsindex 4370d3b05d..924069a0de 100644--- a/crates/graphql_calendar/src/objects/test.rs+++ b/crates/graphql_calendar/src/objects/test.rs@@ -12,7 +12,7 @@ fn occurrence_identity_composes_event_id_and_occurrence_key() {let listing = timed_listing(7);let key = listing.occurrence.occurrence_key.clone();- let occurrence = GraphqlCalendarOccurrence::from(listing);+ let occurrence = occurrence_nodes(vec![listing]).remove(0);assert_eq!(occurrence.id, ID(format!("{EVENT_ID}:{key}")));assert_eq!(occurrence.event_id, ID(EVENT_ID.to_string()));@@ -35,7 +35,7 @@ fn exception_stays_on_the_occurrence_and_the_event_keeps_series_content() {)]),};- let occurrence = GraphqlCalendarOccurrence::from(listing);+ let occurrence = occurrence_nodes(vec![listing]).remove(0);assert_eq!(occurrence.event.title, "Standup");assert_eq!(@@ -58,7 +58,7 @@ fn exception_stays_on_the_occurrence_and_the_event_keeps_series_content() {#[test]fn occurrence_without_exception_inherits_everything() {- let occurrence = GraphqlCalendarOccurrence::from(timed_listing(8));+ let occurrence = occurrence_nodes(vec![timed_listing(8)]).remove(0);assert_eq!(occurrence.override_title, None);assert_eq!(occurrence.override_status, None);diff --git a/crates/graphql_calendar/src/reads.rs b/crates/graphql_calendar/src/reads.rsindex ecb0108438..4b975c60ce 100644--- a/crates/graphql_calendar/src/reads.rs+++ b/crates/graphql_calendar/src/reads.rs@@ -1,6 +1,7 @@use std::{future::Future, pin::Pin, sync::Arc};use calendar_events::domain::{+ changes::{CalendarChangeQueryService, CalendarChangesPage, CalendarWatermark},models::{CalendarOccurrenceCursor, CalendarSyncStatus, OccurrenceListing, OccurrenceRange,VisibleCalendar,@@ -11,8 +12,8 @@ use rootcause::Report;pub(crate) type ReadFuture<'a, T> = Pin<Box<dyn Future<Output = Result<T, Report>> + Send + 'a>>;-/// Object-safe view of the calendar read service, so request data does not-/// carry the service's type parameters.+/// Object-safe view of the calendar read services, so request data does not+/// carry their type parameters.pub(crate) trait CalendarGraphqlReads: Send + Sync {fn list_occurrences(&self,@@ -25,28 +26,49 @@ pub(crate) trait CalendarGraphqlReads: Send + Sync {fn sync_status(&self, viewer: String) -> ReadFuture<'_, CalendarSyncStatus>;fn list_visible_calendars(&self, viewer: String) -> ReadFuture<'_, Vec<VisibleCalendar>>;++ fn current_watermark(&self, viewer: String) -> ReadFuture<'_, CalendarWatermark>;++ fn changes_since(+ &self,+ viewer: String,+ since: CalendarWatermark,+ ) -> ReadFuture<'_, CalendarChangesPage>;}-/// Type-erased calendar read service stored in GraphQL request data.+/// Type-erased calendar read services stored in GraphQL request data.#[derive(Clone)]pub struct CalendarGraphqlContext {pub(crate) reads: Arc<dyn CalendarGraphqlReads>,}impl CalendarGraphqlContext {- /// Erase `service` so request data does not carry its type parameters.- pub fn new<S: CalendarOccurrenceService>(service: Arc<S>) -> Self {+ /// Erase the occurrence and change-log services so request data does not+ /// carry their type parameters.+ pub fn new<S, C>(occurrences: Arc<S>, changes: Arc<C>) -> Self+ where+ S: CalendarOccurrenceService,+ C: CalendarChangeQueryService,+ {Self {- reads: Arc::new(OccurrenceServiceReads { service }),+ reads: Arc::new(ServiceReads {+ occurrences,+ changes,+ }),}}}-struct OccurrenceServiceReads<S> {- service: Arc<S>,+struct ServiceReads<S, C> {+ occurrences: Arc<S>,+ changes: Arc<C>,}-impl<S: CalendarOccurrenceService> CalendarGraphqlReads for OccurrenceServiceReads<S> {+impl<S, C> CalendarGraphqlReads for ServiceReads<S, C>+where+ S: CalendarOccurrenceService,+ C: CalendarChangeQueryService,+{fn list_occurrences(&self,viewer: String,@@ -55,17 +77,29 @@ impl<S: CalendarOccurrenceService> CalendarGraphqlReads for OccurrenceServiceRealimit: u16,) -> ReadFuture<'_, Vec<OccurrenceListing>> {Box::pin(async move {- self.service+ self.occurrences.list_occurrences(&viewer, range, cursor, limit).await})}fn sync_status(&self, viewer: String) -> ReadFuture<'_, CalendarSyncStatus> {- Box::pin(async move { self.service.sync_status(&viewer).await })+ Box::pin(async move { self.occurrences.sync_status(&viewer).await })}fn list_visible_calendars(&self, viewer: String) -> ReadFuture<'_, Vec<VisibleCalendar>> {- Box::pin(async move { self.service.list_visible_calendars(&viewer).await })+ Box::pin(async move { self.occurrences.list_visible_calendars(&viewer).await })+ }++ fn current_watermark(&self, viewer: String) -> ReadFuture<'_, CalendarWatermark> {+ Box::pin(async move { self.changes.current_watermark(&viewer).await })+ }++ fn changes_since(+ &self,+ viewer: String,+ since: CalendarWatermark,+ ) -> ReadFuture<'_, CalendarChangesPage> {+ Box::pin(async move { self.changes.changes_since(&viewer, since).await })}}diff --git a/crates/graphql_calendar/src/user_query.rs b/crates/graphql_calendar/src/user_query.rsindex 66eff77f69..110d85b9eb 100644--- a/crates/graphql_calendar/src/user_query.rs+++ b/crates/graphql_calendar/src/user_query.rs@@ -5,8 +5,11 @@ use rootcause::Report;use crate::{CalendarGraphqlContext, bad_input,- inputs::{CalendarRangeInput, encode_cursor},- objects::{GraphqlCalendar, GraphqlCalendarOccurrence, GraphqlCalendarOccurrencePage},+ inputs::{CalendarChangesInput, CalendarRangeInput, encode_cursor},+ objects::{+ GraphqlCalendar, GraphqlCalendarChanges, GraphqlCalendarOccurrencePage, occurrence_nodes,+ watermark_entries,+ },unavailable,};@@ -46,7 +49,8 @@ impl GraphqlCalendarQuery {}/// One page of occurrences overlapping the viewport, across owned and- /// delegated inboxes, ordered by start.+ /// delegated inboxes, ordered by start. `watermark` is read before the+ /// occurrences, so the page reflects at least every change it covers.#[tracing::instrument(skip_all, err(Debug))]async fn calendar_occurrences(&self,@@ -56,6 +60,10 @@ impl GraphqlCalendarQuery {let reads = &ctx.data::<CalendarGraphqlContext>()?.reads;let request = input.into_page_request()?;let page_size = usize::from(request.page_size);+ let watermark = reads+ .current_watermark(self.viewer())+ .await+ .map_err(|error| unavailable(error, "calendar occurrences are unavailable"))?;let (mut rows, sync_status) = futures::try_join!(reads.list_occurrences(self.viewer(),@@ -74,16 +82,30 @@ impl GraphqlCalendarQuery {))});Ok(GraphqlCalendarOccurrencePage {- nodes: rows- .into_iter()- .map(GraphqlCalendarOccurrence::from)- .collect(),+ nodes: occurrence_nodes(rows),has_next_page,end_cursor,sync_status: sync_status.into(),- watermark: Vec::new(),+ watermark: watermark_entries(&watermark),})}++ /// Changes to the viewer's calendars after `since`, one bounded page at a+ /// time. An empty `since` returns only the current watermark.+ #[tracing::instrument(skip_all, err(Debug))]+ async fn calendar_changes(+ &self,+ ctx: &Context<'_>,+ input: CalendarChangesInput,+ ) -> async_graphql::Result<GraphqlCalendarChanges> {+ let reads = &ctx.data::<CalendarGraphqlContext>()?.reads;+ let since = input.into_watermark()?;+ reads+ .changes_since(self.viewer(), since)+ .await+ .map(Into::into)+ .map_err(|error| unavailable(error, "calendar changes are unavailable"))+ }}fn occurrences_error(error: Report) -> async_graphql::Error {diff --git a/crates/graphql_calendar/src/user_query/test.rs b/crates/graphql_calendar/src/user_query/test.rsindex d69ec552e1..2b660d3277 100644--- a/crates/graphql_calendar/src/user_query/test.rs+++ b/crates/graphql_calendar/src/user_query/test.rs@@ -2,6 +2,10 @@ use std::sync::{Arc, Mutex};use async_graphql::{EmptyMutation, EmptySubscription, Schema};use calendar_events::domain::{+ changes::{+ CalendarChangeQueryService, CalendarChangesPage, CalendarEventChange,+ CalendarLinkWatermark, CalendarWatermark, EventOccurrence,+ },models::{CalendarMentionPreview, CalendarMentionRequestItem, CalendarOccurrenceCursor,CalendarSyncStatus, OccurrenceListing, OccurrenceRange, TeamOutOfOffice, VisibleCalendar,@@ -31,8 +35,12 @@ enum Failure {struct FakeReads {listings: Vec<OccurrenceListing>,calendars: Vec<VisibleCalendar>,+ watermark: CalendarWatermark,+ changes: CalendarChangesPage,failure: Failure,requests: Mutex<Vec<(String, Option<CalendarOccurrenceCursor>, u16)>>,+ calls: Mutex<Vec<&'static str>>,+ since: Mutex<Vec<CalendarWatermark>>,}impl FakeReads {@@ -59,6 +67,7 @@ impl CalendarOccurrenceService for FakeReads {.lock().unwrap().push((requester_id.to_owned(), cursor, limit));+ self.calls.lock().unwrap().push("occurrences");self.fail()?;Ok(self.listings@@ -106,6 +115,23 @@ impl CalendarOccurrenceService for FakeReads {}}+impl CalendarChangeQueryService for FakeReads {+ async fn current_watermark(&self, _viewer: &str) -> Result<CalendarWatermark, Report> {+ self.calls.lock().unwrap().push("watermark");+ Ok(self.watermark.clone())+ }++ async fn changes_since(+ &self,+ _viewer: &str,+ since: CalendarWatermark,+ ) -> Result<CalendarChangesPage, Report> {+ self.since.lock().unwrap().push(since);+ self.fail()?;+ Ok(self.changes.clone())+ }+}+const VIEWER: &str = "macro|[email protected]";async fn execute(reads: Arc<FakeReads>, query: &str) -> async_graphql::Response {@@ -114,7 +140,7 @@ async fn execute(reads: Arc<FakeReads>, query: &str) -> async_graphql::ResponseEmptyMutation,EmptySubscription,)- .data(CalendarGraphqlContext::new(reads))+ .data(CalendarGraphqlContext::new(Arc::clone(&reads), reads)).finish();schema.execute(query).await}@@ -159,6 +185,11 @@ async fn a_full_page_reports_a_cursor_and_requests_one_extra_row() {assert_eq!(page["hasNextPage"], true);assert_eq!(page["syncStatus"], "SYNCING");assert_eq!(page["watermark"], Value::Array(Vec::new()));+ assert_eq!(+ reads.calls.lock().unwrap()[..2],+ ["watermark", "occurrences"],+ "the watermark is captured before the page is read"+ );let cursor = page["endCursor"].as_str().unwrap().to_owned();let requests = reads.requests.lock().unwrap().clone();@@ -271,3 +302,165 @@ async fn infrastructure_failures_are_masked() {);}}++#[tokio::test]+async fn pages_report_the_watermark_as_decimal_strings() {+ let reads = Arc::new(FakeReads {+ listings: vec![timed_listing(6)],+ watermark: CalendarWatermark::from_links([CalendarLinkWatermark {+ link_id: LINK_ID,+ seq: 9_007_199_254_740_993,+ }]),+ ..Default::default()+ });++ let response = execute(reads, PAGE_QUERY).await;++ assert!(response.errors.is_empty(), "{:?}", response.errors);+ let data = response.data.into_json().unwrap();+ assert_eq!(+ data["calendarOccurrences"]["watermark"],+ serde_json::json!([{ "linkId": LINK_ID.to_string(), "seq": "9007199254740993" }])+ );+}++#[tokio::test]+async fn occurrences_of_one_event_share_the_series_event() {+ let reads = Arc::new(FakeReads {+ listings: vec![timed_listing(6), timed_listing(7)],+ ..Default::default()+ });++ let response = execute(reads, PAGE_QUERY).await;++ let data = response.data.into_json().unwrap();+ let nodes = data["calendarOccurrences"]["nodes"].as_array().unwrap();+ assert_eq!(nodes[0]["event"], nodes[1]["event"]);+}++const CHANGES_QUERY: &str = r#"{+ calendarChanges(input: { since: [{ linkId: "LINK", seq: "4" }] }) {+ events {+ event { __typename id linkId }+ occurrences { id eventId linkId event { id } }+ }+ deletedEventIds+ calendars { id }+ deletedCalendarIds+ newWatermark { linkId seq }+ hasMore+ resetRequired+ }+}"#;++fn changes_query() -> String {+ CHANGES_QUERY.replace("LINK", &LINK_ID.to_string())+}++#[tokio::test]+async fn changes_map_the_page_and_parse_the_watermark() {+ let listing = timed_listing(6);+ let deleted_event = uuid::Uuid::from_u128(0x99);+ let deleted_calendar = uuid::Uuid::from_u128(0x98);+ let reads = Arc::new(FakeReads {+ changes: CalendarChangesPage {+ events: vec![CalendarEventChange {+ event: listing.event.clone(),+ link_id: LINK_ID,+ occurrences: vec![EventOccurrence {+ occurrence: listing.occurrence.clone(),+ exception: listing.exception.clone(),+ }],+ }],+ deleted_event_ids: vec![deleted_event],+ calendars: Vec::new(),+ deleted_calendar_ids: vec![deleted_calendar],+ new_watermark: CalendarWatermark::from_links([CalendarLinkWatermark {+ link_id: LINK_ID,+ seq: 12,+ }]),+ has_more: true,+ reset_required: false,+ },+ ..Default::default()+ });++ let response = execute(Arc::clone(&reads), &changes_query()).await;++ assert!(response.errors.is_empty(), "{:?}", response.errors);+ let data = response.data.into_json().unwrap();+ let changes = &data["calendarChanges"];+ assert_eq!(+ changes["events"][0]["event"]["__typename"],+ "GraphqlCalendarEvent"+ );+ assert_eq!(changes["events"][0]["event"]["id"], EVENT_ID.to_string());+ let occurrence = &changes["events"][0]["occurrences"][0];+ assert_eq!(+ occurrence["id"],+ format!("{EVENT_ID}:2026-10-06T15:00:00+00:00")+ );+ assert_eq!(occurrence["event"]["id"], EVENT_ID.to_string());+ assert_eq!(changes["deletedEventIds"][0], deleted_event.to_string());+ assert_eq!(+ changes["deletedCalendarIds"][0],+ deleted_calendar.to_string()+ );+ assert_eq!(+ changes["newWatermark"],+ serde_json::json!([{ "linkId": LINK_ID.to_string(), "seq": "12" }])+ );+ assert_eq!(changes["hasMore"], true);+ assert_eq!(changes["resetRequired"], false);+ assert_eq!(+ *reads.since.lock().unwrap(),+ vec![CalendarWatermark::from_links([CalendarLinkWatermark {+ link_id: LINK_ID,+ seq: 4,+ }])]+ );+}++#[tokio::test]+async fn a_malformed_watermark_is_a_user_error() {+ for since in [+ r#"[{ linkId: "not-a-uuid", seq: "1" }]"#.to_owned(),+ format!(r#"[{{ linkId: "{LINK_ID}", seq: "-1" }}]"#),+ format!(r#"[{{ linkId: "{LINK_ID}", seq: "one" }}]"#),+ ] {+ let reads = Arc::new(FakeReads::default());+ let response = execute(+ Arc::clone(&reads),+ &format!("{{ calendarChanges(input: {{ since: {since} }}) {{ hasMore }} }}"),+ )+ .await;++ assert_eq!(+ response.errors[0]+ .extensions+ .as_ref()+ .unwrap()+ .get("code")+ .unwrap()+ .to_string(),+ "\"BAD_USER_INPUT\"",+ "{since}"+ );+ assert!(reads.since.lock().unwrap().is_empty());+ }+}++#[tokio::test]+async fn change_failures_are_masked() {+ let reads = Arc::new(FakeReads {+ failure: Failure::Internal,+ ..Default::default()+ });++ let response = execute(reads, &changes_query()).await;++ assert_eq!(+ response.errors[0].message,+ "calendar changes are unavailable"+ );+}diff --git a/services/document_storage_service/src/server.rs b/services/document_storage_service/src/server.rsindex c3156e4d01..ea2b141460 100644--- a/services/document_storage_service/src/server.rs+++ b/services/document_storage_service/src/server.rs@@ -1734,8 +1734,14 @@ pub async fn run() -> anyhow::Result<()> {let calendar_read_service = Arc::new(calendar_events::domain::service::CalendarService::new(calendar_events::outbound::pg::PgCalendarRepository::new(readonly_db.clone()),));- let graphql_calendar_context =- graphql_calendar::CalendarGraphqlContext::new(calendar_read_service.clone());+ let graphql_calendar_context = graphql_calendar::CalendarGraphqlContext::new(+ calendar_read_service.clone(),+ Arc::new(+ calendar_events::domain::changes::CalendarChangeService::new(+ calendar_events::outbound::pg::PgCalendarRepository::new(readonly_db.clone()),+ ),+ ),+ );let calendar_state =CalendarRouterState::new(calendar_read_service, authorization_state.clone());diff --git a/static_assets/schema.graphql b/static_assets/schema.graphqlindex 99c70ef430..f2cd7c5a25 100644--- a/static_assets/schema.graphql+++ b/static_assets/schema.graphql@@ -23,6 +23,31 @@ input ActivityOverviewInput {timeZone: String}+"""+A request for calendar changes after a watermark.+"""+input CalendarChangesInput {+ """+ The client's watermark, one entry per tracked connected inbox. Empty+ returns only the current watermark.+ """+ since: [CalendarLinkWatermarkInput!]!+}++"""+How far the client has applied one connected inbox's change log.+"""+input CalendarLinkWatermarkInput {+ """+ Connected inbox identifier.+ """+ linkId: ID!+ """+ Last applied sequence, as the decimal string the server returned.+ """+ seq: String!+}+"""A bounded occurrence viewport and page request."""@@ -1105,6 +1130,43 @@ enum GraphqlCalendarAttendeeResponseStatus {TENTATIVE}+"""+One bounded page of calendar changes after a watermark.+"""+type GraphqlCalendarChanges {+ """+ Events created or changed, each with its full occurrence set.+ """+ events: [GraphqlCalendarEventChange!]!+ """+ Events that no longer exist or no longer have a visible occurrence.+ """+ deletedEventIds: [ID!]!+ """+ Calendars created or changed.+ """+ calendars: [GraphqlCalendar!]!+ """+ Calendars that were removed.+ """+ deletedCalendarIds: [ID!]!+ """+ Position after this page, one entry per currently visible connected+ inbox. An inbox missing here is no longer visible.+ """+ newWatermark: [GraphqlCalendarLinkWatermark!]!+ """+ Whether more changes follow `newWatermark`.+ """+ hasMore: Boolean!+ """+ Whether the client must drop every calendar record and coverage it+ holds and refetch: its watermark fell behind retention, or an inbox+ became visible that it never tracked.+ """+ resetRequired: Boolean!+}+"""Conferencing system backing an event's join URL."""@@ -1247,6 +1309,21 @@ input GraphqlCalendarEventBinaryExpr {right: GraphqlCalendarEventExpr!}+"""+A changed event with its complete current set of visible occurrences.+Clients replace everything they hold for the event with it.+"""+type GraphqlCalendarEventChange {+ """+ The series event.+ """+ event: GraphqlCalendarEvent!+ """+ Every non-cancelled materialized occurrence, ordered by start.+ """+ occurrences: [GraphqlCalendarOccurrence!]!+}+"""A recursive `CalendarEventFilterExpr` filter expression."""@@ -7806,10 +7883,16 @@ type GraphqlUser {calendars: [GraphqlCalendar!]!"""One page of occurrences overlapping the viewport, across owned and- delegated inboxes, ordered by start.+ delegated inboxes, ordered by start. `watermark` is read before the+ occurrences, so the page reflects at least every change it covers."""calendarOccurrences(input: CalendarRangeInput!): GraphqlCalendarOccurrencePage!"""+ Changes to the viewer's calendars after `since`, one bounded page at a+ time. An empty `since` returns only the current watermark.+ """+ calendarChanges(input: CalendarChangesInput!): GraphqlCalendarChanges!+ """Labels across every owned or delegated inbox accessible to the authenticated user."""emailLabels: [GraphqlSoupEmailLabel!]!