@forcecalendar/core 2.4.0 → 2.5.1

package/core/events/EventStore.js

@@ -5,6 +5,12 @@ import { PerformanceOptimizer } from '../performance/PerformanceOptimizer.js';
 import { ConflictDetector } from '../conflicts/ConflictDetector.js';
 import { TimezoneManager } from '../timezone/TimezoneManager.js';
 
+// Events are indexed and expanded on their own wall clock, which can differ
+// from the query timezone's by up to 26 hours (UTC-12 to UTC+14). Day
+// queries therefore look this many days beyond each edge before filtering
+// precisely in the query timezone.
+const TIMEZONE_PAD_DAYS = 2;
+
 /**
  * EventStore - Manages calendar events with efficient querying
  * Uses Map for O(1) lookups and spatial indexing concepts for date queries
@@ -98,13 +104,16 @@ export class EventStore {
 
   /**
    * Update an existing event
-   * @param {string} eventId - The event ID
+   *
+   * An occurrence id (see {@link Event.occurrenceId}) updates the recurring
+   * master the occurrence belongs to, i.e. the whole series.
+   * @param {string} eventId - Event id or occurrence id
    * @param {Partial<import('../types.js').EventData>} updates - Properties to update
-   * @returns {Event} The updated event
+   * @returns {Event} The updated event (the master for an occurrence id)
    * @throws {Error} If event not found
    */
   updateEvent(eventId, updates) {
-    const existingEvent = this.events.get(eventId);
+    const existingEvent = this.events.get(eventId) || this._resolveOccurrenceMaster(eventId);
     if (!existingEvent) {
       throw new Error(`Event with id ${eventId} not found`);
     }
@@ -145,6 +154,7 @@ export class EventStore {
     // Clear query and date range caches since results may have changed
     this.optimizer.queryCache.clear();
     this.optimizer.dateRangeCache.clear();
+    this._invalidateOccurrenceCache(replacement.id);
 
     // Re-index
     this._indexEvent(replacement);
@@ -152,11 +162,14 @@ export class EventStore {
 
   /**
    * Remove an event from the store
-   * @param {string} eventId - The event ID to remove
+   *
+   * An occurrence id (see {@link Event.occurrenceId}) removes the recurring
+   * master the occurrence belongs to, i.e. the whole series.
+   * @param {string} eventId - Event id or occurrence id
    * @returns {boolean} True if removed, false if not found
    */
   removeEvent(eventId) {
-    const event = this.events.get(eventId);
+    const event = this.events.get(eventId) || this._resolveOccurrenceMaster(eventId);
     if (!event) {
       return false;
     }
@@ -186,15 +199,40 @@ export class EventStore {
     this.optimizer.eventCache.delete(event.id);
     this.optimizer.queryCache.clear();
     this.optimizer.dateRangeCache.clear();
+    this._invalidateOccurrenceCache(event.id);
 
     // Remove from indices
     this._unindexEvent(event);
   }
 
+  /**
+   * Drop the recurrence engine's cached expansions of one series, or of
+   * every series when no id is given. The engine is pluggable, so both
+   * hooks are optional.
+   * @param {string} [eventId] - Series to invalidate; omit to clear everything
+   * @private
+   */
+  _invalidateOccurrenceCache(eventId = null) {
+    const engine = this.recurrenceEngine;
+    if (!engine) {
+      return;
+    }
+    if (eventId !== null && typeof engine.clearEventCache === 'function') {
+      engine.clearEventCache(eventId);
+    } else if (engine.occurrenceCache instanceof Map) {
+      engine.occurrenceCache.clear();
+    }
+  }
+
   /**
    * Get an event by ID
-   * @param {string} eventId - The event ID
-   * @returns {Event|null} The event or null if not found
+   *
+   * Occurrence ids produced by {@link EventStore#expandRecurringEvent}
+   * (`<masterId>_<startMs>`, see {@link Event.occurrenceId}) resolve to the
+   * stored recurring master they were derived from, so an id taken from view
+   * data can always be looked up. Occurrences themselves are never stored.
+   * @param {string} eventId - Event id or occurrence id
+   * @returns {Event|null} The stored event (the master for an occurrence id) or null
    */
   getEvent(eventId) {
     // Check cache first
@@ -209,9 +247,80 @@ export class EventStore {
     // Cache if found
     if (event) {
       this.optimizer.cache(eventId, event, 'event');
+      return event;
     }
 
-    return event;
+    return this._resolveOccurrenceMaster(eventId);
+  }
+
+  /**
+   * Resolve an occurrence id to the stored recurring master it belongs to.
+   * Not cached: the master's own cache entry is the one kept in sync.
+   * @param {string} eventId - Candidate occurrence id
+   * @returns {Event|null} The master event or null
+   * @private
+   */
+  _resolveOccurrenceMaster(eventId) {
+    const parsed = Event.parseOccurrenceId(eventId);
+    if (!parsed) {
+      return null;
+    }
+    const master = this.events.get(parsed.recurringEventId);
+    return master && master.recurring ? master : null;
+  }
+
+  /**
+   * Resolve an id taken from anywhere (store, view data, a drag or click
+   * handler) to the id of the stored event it refers to.
+   *
+   * Returns the id itself for a stored event, the master's id for an
+   * occurrence id (see {@link Event.occurrenceId}) whose master is a stored
+   * recurring event, and `null` when nothing stored matches. This is the
+   * same resolution {@link EventStore#getEvent}, updateEvent and removeEvent
+   * apply, exposed for consumers that only need the id.
+   *
+   * @example
+   * const masterId = store.resolveEventId(chip.dataset.eventId); // 'standup' for 'standup_1750028400000'
+   *
+   * @param {string} id - Event id or occurrence id
+   * @returns {string|null} Id of the stored event, or null
+   */
+  resolveEventId(id) {
+    const event = this.getEvent(id);
+    return event ? event.id : null;
+  }
+
+  /**
+   * Get the occurrence an occurrence id stands for, as an {@link Event}
+   * exactly like the ones {@link EventStore#expandRecurringEvent} returns.
+   *
+   * Returns `null` when the id is not an occurrence id, its master is not a
+   * stored recurring event, or the series has no occurrence starting at the
+   * encoded instant. A master id is never an occurrence, so it yields null
+   * too; use {@link EventStore#getEvent} for the master.
+   *
+   * @example
+   * const occurrence = store.getOccurrence('standup_1750028400000');
+   *
+   * @param {string} occurrenceId - Occurrence id (`<masterId>_<startMs>`)
+   * @param {string} [timezone] - Timezone for the expansion (defaults to the store timezone)
+   * @returns {Event|null} The occurrence, or null
+   */
+  getOccurrence(occurrenceId, timezone = null) {
+    const parsed = Event.parseOccurrenceId(occurrenceId);
+    const master = parsed ? this._resolveOccurrenceMaster(occurrenceId) : null;
+    if (!master || Number.isNaN(parsed.occurrenceStart.getTime())) {
+      return null;
+    }
+    // A DST adjustment can move an occurrence away from the stepped
+    // instant, so expand a day either side and match on the id
+    const occurrences = this.expandRecurringEvent(
+      master,
+      DateUtils.addDays(parsed.occurrenceStart, -1),
+      DateUtils.addDays(parsed.occurrenceStart, 1),
+      timezone
+    );
+    return occurrences.find(occurrence => occurrence.id === occurrenceId) || null;
   }
 
   /**
@@ -343,19 +452,112 @@ export class EventStore {
 
   /**
    * Get events for a specific date
+   *
+   * Recurring series are expanded for the day, so the result holds their
+   * occurrences (see {@link EventStore#expandRecurringEvent}) rather than the
+   * master events. When building a grid of days use
+   * {@link EventStore#getEventsByDate}, which expands once for the whole range.
    * @param {Date} date - The date to query
    * @param {string} [timezone] - Timezone for the query (defaults to store timezone)
    * @returns {Event[]} Events occurring on the date, sorted by start time
    */
   getEventsForDate(date, timezone = null) {
     timezone = timezone || this.defaultTimezone;
+    const dayStart = DateUtils.startOfDay(date);
+    const dayEnd = DateUtils.endOfDay(date);
+
+    const candidates = [];
+    for (const id of this._collectDateCandidateIds(date)) {
+      const event = this.events.get(id);
+      // Recurring masters are represented by their occurrences below
+      if (event && !event.recurring) {
+        candidates.push(event);
+      }
+    }
+
+    // Series are expanded on their own wall clock, so cover the offset
+    // spread and let _selectEventsForDay decide in the query timezone
+    const expandStart = DateUtils.addDays(dayStart, -TIMEZONE_PAD_DAYS);
+    const expandEnd = DateUtils.addDays(dayEnd, TIMEZONE_PAD_DAYS);
+    for (const id of this.indices.recurring) {
+      const event = this.events.get(id);
+      if (event) {
+        candidates.push(...this.expandRecurringEvent(event, expandStart, expandEnd, timezone));
+      }
+    }
+
+    return this._selectEventsForDay(candidates, dayStart, dayEnd, timezone);
+  }
+
+  /**
+   * Get the events for every day in a range, keyed by local date (YYYY-MM-DD)
+   *
+   * Recurring series are expanded once for the whole range rather than once
+   * per day, which is what a month or week grid needs. Every day in the range
+   * has an entry (an empty array when nothing occurs) and multi-day events
+   * appear under each day they span. Each array is sorted like
+   * {@link EventStore#getEventsForDate}.
+   *
+   * @example
+   * const byDate = store.getEventsByDate(gridStart, gridEnd);
+   * const events = byDate.get(DateUtils.getLocalDateString(cellDate)) || [];
+   *
+   * @param {Date} start - First day of the range
+   * @param {Date} end - Last day of the range
+   * @param {string} [timezone] - Timezone deciding which day an event falls on (defaults to store timezone)
+   * @returns {Map<string, Event[]>} Local date string -> events on that day
+   */
+  getEventsByDate(start, end, timezone = null) {
+    timezone = timezone || this.defaultTimezone;
+    const rangeStart = DateUtils.startOfDay(start);
+    const rangeEnd = DateUtils.endOfDay(end);
 
-    // Collect candidate event IDs from indices
+    /** @type {Map<string, Event[]>} */
+    const byDate = new Map();
+    for (const day of DateUtils.getDateRange(rangeStart, rangeEnd)) {
+      byDate.set(DateUtils.getLocalDateString(day), []);
+    }
+
+    // Query beyond each edge so events that fall on an edge day in the
+    // requested timezone are not lost to the range filter on event wall clocks.
+    const events = this.getEventsInRange(
+      DateUtils.addDays(rangeStart, -TIMEZONE_PAD_DAYS),
+      DateUtils.addDays(rangeEnd, TIMEZONE_PAD_DAYS),
+      true,
+      timezone
+    );
+
+    for (const event of events) {
+      const eventStart = event.getStartInTimezone(timezone);
+      const eventEnd = event.getEndInTimezone(timezone);
+      const lastDay = eventEnd < rangeEnd ? eventEnd : rangeEnd;
+      let day = DateUtils.startOfDay(eventStart > rangeStart ? eventStart : rangeStart);
+      while (day <= lastDay) {
+        byDate.get(DateUtils.getLocalDateString(day))?.push(event);
+        day = DateUtils.addDays(day, 1);
+      }
+    }
+
+    const compare = this._compareByStart(timezone);
+    for (const dayEvents of byDate.values()) {
+      dayEvents.sort(compare);
+    }
+
+    return byDate;
+  }
+
+  /**
+   * Collect the ids of stored events that may occur on a date.
+   * @param {Date} date - The date to query
+   * @returns {Set<string>} Candidate event ids
+   * @private
+   */
+  _collectDateCandidateIds(date) {
     const candidateIds = new Set();
 
     // Check byDate index for nearby dates (handles most events)
     const checkDate = new Date(date);
-    for (let offset = -1; offset <= 1; offset++) {
+    for (let offset = -TIMEZONE_PAD_DAYS; offset <= TIMEZONE_PAD_DAYS; offset++) {
       const tempDate = new Date(checkDate);
       tempDate.setDate(tempDate.getDate() + offset);
       const tempDateStr = DateUtils.getLocalDateString(tempDate);
@@ -374,35 +576,41 @@ export class EventStore {
       monthEventIds.forEach(id => candidateIds.add(id));
     }
 
-    // Filter candidates to events that actually overlap with the requested date
-    const allEvents = [];
-    const startOfDay = new Date(date);
-    startOfDay.setHours(0, 0, 0, 0);
-    const endOfDay = new Date(date);
-    endOfDay.setHours(23, 59, 59, 999);
+    return candidateIds;
+  }
 
-    for (const id of candidateIds) {
-      const event = this.events.get(id);
-      if (event) {
-        // Check if event actually occurs on the requested date in the given timezone
-        const eventStartLocal = event.getStartInTimezone(timezone);
-        const eventEndLocal = event.getEndInTimezone(timezone);
+  /**
+   * Keep the events that overlap a day in the given timezone, sorted by start.
+   * @param {Event[]} events - Candidate events
+   * @param {Date} dayStart - Start of the day
+   * @param {Date} dayEnd - End of the day
+   * @param {string} timezone - Timezone deciding whether an event falls on the day
+   * @returns {Event[]} Events on the day, sorted
+   * @private
+   */
+  _selectEventsForDay(events, dayStart, dayEnd, timezone) {
+    const onDay = events.filter(event => {
+      // Event overlaps with this day if it starts before end of day and ends after start of day
+      const eventStartLocal = event.getStartInTimezone(timezone);
+      const eventEndLocal = event.getEndInTimezone(timezone);
+      return eventStartLocal <= dayEnd && eventEndLocal >= dayStart;
+    });
 
-        // Event overlaps with this day if it starts before end of day and ends after start of day
-        if (eventStartLocal <= endOfDay && eventEndLocal >= startOfDay) {
-          allEvents.push(event);
-        }
-      }
-    }
+    return onDay.sort(this._compareByStart(timezone));
+  }
 
-    return allEvents.sort((a, b) => {
-      // Sort by start time in the specified timezone
-      const aStart = a.getStartInTimezone(timezone);
-      const bStart = b.getStartInTimezone(timezone);
-      const timeCompare = aStart - bStart;
+  /**
+   * Comparator ordering events by start time in a timezone, longer events first.
+   * @param {string} timezone - Timezone used for the start comparison
+   * @returns {(a: Event, b: Event) => number} Comparator
+   * @private
+   */
+  _compareByStart(timezone) {
+    return (a, b) => {
+      const timeCompare = a.getStartInTimezone(timezone) - b.getStartInTimezone(timezone);
       if (timeCompare !== 0) return timeCompare;
       return b.duration - a.duration; // Longer events first
-    });
+    };
   }
 
   /**
@@ -478,11 +686,19 @@ export class EventStore {
    * @returns {Array<Event[]>} Array of event groups that overlap
    */
   getOverlapGroups(date, timedOnly = true) {
-    let events = this.getEventsForDate(date);
+    return this.groupOverlappingEvents(this.getEventsForDate(date), timedOnly);
+  }
 
-    if (timedOnly) {
-      events = events.filter(e => !e.allDay);
-    }
+  /**
+   * Group a list of events into clusters of overlapping time slots
+   * Same result as {@link EventStore#getOverlapGroups} for events already fetched
+   * (for example one day of {@link EventStore#getEventsByDate}).
+   * @param {Event[]} events - Events to group; the array is not modified
+   * @param {boolean} [timedOnly=true] - Only include timed events (not all-day)
+   * @returns {Array<Event[]>} Array of event groups that overlap
+   */
+  groupOverlappingEvents(events, timedOnly = true) {
+    events = timedOnly ? events.filter(e => !e.allDay) : [...events];
 
     if (events.length === 0) return [];
 
@@ -644,6 +860,16 @@ export class EventStore {
 
   /**
    * Expand a recurring event into individual occurrences
+   *
+   * Returns every occurrence that overlaps the range, including ones that
+   * start before it but run into it (multi-day series). Each occurrence is an
+   * {@link Event} cloned from the master with:
+   * - `id` from {@link Event.occurrenceId} (`<masterId>_<startMs>`), stable
+   *   across ranges and resolvable with {@link EventStore#getEvent},
+   * - `isOccurrence: true`, `recurringEventId` and `occurrenceStart`,
+   * - `metadata.recurringEventId`, `metadata.occurrenceId` (same as `id`) and
+   *   `metadata.occurrenceIndex` (position within this expansion).
+   * Non-recurring events are returned as-is in a one-element array.
    * @param {Event} event - The recurring event
    * @param {Date} rangeStart - Start of the expansion range
    * @param {Date} rangeEnd - End of the expansion range
@@ -659,27 +885,142 @@ export class EventStore {
 
     // Expand in the event's timezone for accurate recurrence calculation
     const eventTimezone = event.timeZone || timezone;
-    const occurrences = this.recurrenceEngine.expandEvent(event, rangeStart, rangeEnd, {
+
+    // The engine selects occurrences by start, so look back one event
+    // duration to catch occurrences that began before the range but overlap it
+    const duration = Math.max(0, event.end - event.start);
+    const expandStart = new Date(rangeStart.getTime() - duration);
+    const occurrences = this.recurrenceEngine.expandEvent(event, expandStart, rangeEnd, {
       timezone: eventTimezone
     });
 
-    return occurrences.map((occurrence, index) => {
-      // Create a new event instance for each occurrence
-      const occurrenceEvent = event.clone({
-        id: `${event.id}_occurrence_${index}`,
-        start: occurrence.start,
-        end: occurrence.end,
-        timeZone: occurrence.timezone || eventTimezone,
-        metadata: {
-          ...event.metadata,
-          recurringEventId: event.id,
-          occurrenceId: occurrence.id,
-          occurrenceIndex: index
-        }
-      });
+    const expanded = [];
+    for (const occurrence of occurrences) {
+      if (occurrence.end < rangeStart || occurrence.start > rangeEnd) {
+        continue;
+      }
+      expanded.push(this._createOccurrence(event, occurrence, eventTimezone, expanded.length));
+    }
+
+    return expanded;
+  }
 
-      return occurrenceEvent;
+  /**
+   * Build the Event instance for one occurrence of a recurring master.
+   * @param {Event} event - The recurring master
+   * @param {{start: Date, end: Date, timezone?: string}} occurrence - Engine occurrence
+   * @param {string} eventTimezone - Timezone the series was expanded in
+   * @param {number} index - Position within the current expansion
+   * @returns {Event} Occurrence event
+   * @private
+   */
+  _createOccurrence(event, occurrence, eventTimezone, index) {
+    const occurrenceStart = new Date(occurrence.start);
+    const id = Event.occurrenceId(event.id, occurrenceStart);
+
+    const occurrenceEvent = event.clone({
+      id,
+      start: occurrenceStart,
+      end: new Date(occurrence.end),
+      timeZone: occurrence.timezone || eventTimezone,
+      metadata: {
+        ...event.metadata,
+        recurringEventId: event.id,
+        occurrenceId: id,
+        occurrenceIndex: index
+      }
     });
+
+    occurrenceEvent.isOccurrence = true;
+    occurrenceEvent.recurringEventId = event.id;
+    occurrenceEvent.occurrenceStart = new Date(occurrenceStart);
+
+    return occurrenceEvent;
+  }
+
+  /**
+   * Lazily iterate the occurrences of a stored event in chronological order.
+   *
+   * Occurrences come one at a time from the store's recurrence engine
+   * (RecurrenceEngineV2 by default), so taking the next few occurrences of
+   * an open-ended series does not expand the series. `after` and `before`
+   * are exclusive unless `inclusive` is set; see
+   * RecurrenceEngineV2.iterateOccurrences for the full semantics. The
+   * expansion timezone defaults to the event's, then the store's.
+   *
+   * @example
+   * for (const occurrence of store.iterateOccurrences('standup', { after: new Date() })) {
+   *   if (occurrence.start > deadline) break;
+   *   remind(occurrence);
+   * }
+   *
+   * @param {string} eventId - Event id or occurrence id (resolved to its master)
+   * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Window and expansion options
+   * @returns {Generator<import('../types.js').ExpandedOccurrence, void, undefined>} Occurrences in chronological order
+   * @throws {Error} If no event with the ID exists
+   */
+  iterateOccurrences(eventId, options = {}) {
+    const query = this._occurrenceQuery(eventId, options);
+    return this.recurrenceEngine.iterateOccurrences(query.event, query.options);
+  }
+
+  /**
+   * First occurrence of a stored event after an instant, or null when the
+   * series has no occurrence after it. `after` is exclusive unless
+   * `options.inclusive` is set.
+   *
+   * @example
+   * const upcoming = store.getNextOccurrence('standup', new Date());
+   *
+   * @param {string} eventId - Event id or occurrence id (resolved to its master)
+   * @param {Date|number} [after=null] - Instant to search from (defaults to the series start)
+   * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Further options
+   * @returns {import('../types.js').ExpandedOccurrence|null} The next occurrence, or null
+   * @throws {Error} If no event with the ID exists
+   */
+  getNextOccurrence(eventId, after = null, options = {}) {
+    const query = this._occurrenceQuery(eventId, options);
+    return this.recurrenceEngine.nextOccurrence(query.event, after, query.options);
+  }
+
+  /**
+   * The first `count` occurrences of a stored event inside a window,
+   * generated lazily. `count` is capped at the engine's
+   * MAX_OCCURRENCES_HARD_LIMIT.
+   *
+   * @example
+   * const nextFive = store.takeOccurrences('standup', 5, { after: new Date() });
+   *
+   * @param {string} eventId - Event id or occurrence id (resolved to its master)
+   * @param {number} count - Maximum number of occurrences to return (fractions are floored)
+   * @param {import('../types.js').ExpandedOccurrenceIteratorOptions} [options={}] - Window and expansion options
+   * @returns {import('../types.js').ExpandedOccurrence[]} Up to `count` occurrences in chronological order
+   * @throws {Error} If no event with the ID exists
+   */
+  takeOccurrences(eventId, count, options = {}) {
+    const query = this._occurrenceQuery(eventId, options);
+    return this.recurrenceEngine.takeOccurrences(query.event, count, query.options);
+  }
+
+  /**
+   * Resolve an occurrence query to the stored event and its options, with
+   * the timezone defaulted as expandRecurringEvent does
+   * @param {string} eventId - The event ID
+   * @param {Object} options - Caller options
+   * @returns {{ event: Event, options: Object }}
+   * @throws {Error} If no event with the ID exists
+   * @private
+   */
+  _occurrenceQuery(eventId, options) {
+    // Occurrence ids resolve to their master, as in getEvent
+    const event = this.getEvent(eventId);
+    if (!event) {
+      throw new Error(`Event with id ${eventId} not found`);
+    }
+    return {
+      event,
+      options: { ...options, timezone: options.timezone || event.timeZone || this.defaultTimezone }
+    };
   }
 
   /**
@@ -695,6 +1036,7 @@ export class EventStore {
     this.indices.byCategory.clear();
     this.indices.byStatus.clear();
     this.eventIndexRefs.clear();
+    this._invalidateOccurrenceCache();
 
     this._notifyChange({
       type: 'clear',
@@ -727,13 +1069,23 @@ export class EventStore {
    * - adds events whose id is not in the store (`add` change),
    * - removes stored events missing from the snapshot (`remove` change),
    *   unless `removeMissing` is `false`,
+   * - treats occurrences of a recurring series (entries with
+   *   `isOccurrence: true`, the plain object of such an occurrence, or an id
+   *   that {@link EventStore#getEvent} resolves to a stored recurring master)
+   *   as a reference to their master: the master is kept as unchanged and is
+   *   never replaced by an occurrence. An occurrence whose master is neither
+   *   stored nor in the snapshot is an error,
    * - emits a single `batch` notification listing those changes, or nothing at
    *   all when the snapshot matches the store. When called while a batch is
    *   already open the changes are queued on that batch instead.
    *
-   * Input is validated up front: invalid event data or duplicate ids throw
-   * before the store is modified. Any error raised while applying the diff
-   * rolls the store back to its previous state.
+   * Input is validated up front: invalid event data, duplicate ids and
+   * occurrences without a master throw before the store is modified. When
+   * reconcile opens the batch itself, any error raised while applying the
+   * diff rolls the store back to its previous state; inside a batch opened
+   * by the caller the changes applied so far stay queued on that batch, and
+   * it is the caller's rollbackBatch() that undoes them (a custom
+   * `isEquivalent` that throws is the usual way to get there).
    *
    * @example
    * // periodic server snapshot
@@ -759,7 +1111,13 @@ export class EventStore {
       // Normalize and validate everything before touching the store
       /** @type {Map<string, Event>} */
       const incoming = new Map();
+      const occurrenceRefs = [];
       for (const eventData of events) {
+        const masterId = this._occurrenceMasterId(eventData);
+        if (masterId !== null) {
+          occurrenceRefs.push({ id: eventData.id, masterId });
+          continue;
+        }
         const event = eventData instanceof Event ? eventData : new Event(eventData);
         if (incoming.has(event.id)) {
           throw new Error(`Duplicate event id in reconcile input: ${event.id}`);
@@ -767,6 +1125,22 @@ export class EventStore {
         incoming.set(event.id, event);
       }
 
+      // Stored masters that occurrence entries stand for: kept, not compared
+      /** @type {Set<string>} */
+      const retained = new Set();
+      for (const { id, masterId } of occurrenceRefs) {
+        if (incoming.has(masterId)) {
+          continue; // the master itself is in the snapshot
+        }
+        const stored = this.events.get(masterId);
+        if (!stored || !stored.recurring) {
+          throw new Error(
+            `Occurrence ${id} in reconcile input refers to recurring event ${masterId}, which is neither stored nor in the snapshot`
+          );
+        }
+        retained.add(masterId);
+      }
+
       /** @type {import('../types.js').ReconcileResult} */
       const result = { added: [], updated: [], removed: [], unchanged: [] };
 
@@ -779,7 +1153,7 @@ export class EventStore {
       try {
         if (removeMissing) {
           for (const existing of Array.from(this.events.values())) {
-            if (!incoming.has(existing.id)) {
+            if (!incoming.has(existing.id) && !retained.has(existing.id)) {
               this._detachEvent(existing);
               this._queueChange({ type: 'remove', event: existing, version: ++this.version });
               result.removed.push(existing);
@@ -787,6 +1161,10 @@ export class EventStore {
           }
         }
 
+        for (const masterId of retained) {
+          result.unchanged.push(this.events.get(masterId));
+        }
+
         for (const event of incoming.values()) {
           const existing = this.events.get(event.id);
           if (!existing) {
@@ -829,6 +1207,44 @@ export class EventStore {
     });
   }
 
+  /**
+   * Id of the recurring master a reconcile entry is an occurrence of, or
+   * null when the entry is an event in its own right. Recognises Event
+   * occurrences (isOccurrence), their toObject() form (occurrence markers
+   * in metadata) and ids that resolve to a stored recurring master.
+   * @param {Event|import('../types.js').EventData} eventData - Reconcile entry
+   * @returns {string|null} Master id or null
+   * @private
+   */
+  _occurrenceMasterId(eventData) {
+    if (!eventData || typeof eventData !== 'object') {
+      return null; // let the Event constructor report it
+    }
+    const parsed = Event.parseOccurrenceId(eventData.id);
+    if (eventData.isOccurrence === true) {
+      if (typeof eventData.recurringEventId === 'string' && eventData.recurringEventId) {
+        return eventData.recurringEventId;
+      }
+      if (parsed) {
+        return parsed.recurringEventId;
+      }
+      throw new Error(
+        `Occurrence ${eventData.id} in reconcile input has no recurringEventId and no occurrence id`
+      );
+    }
+    const metadata = eventData.metadata;
+    if (
+      metadata &&
+      typeof metadata === 'object' &&
+      typeof metadata.recurringEventId === 'string' &&
+      metadata.occurrenceId === eventData.id
+    ) {
+      return metadata.recurringEventId;
+    }
+    const master = parsed ? this._resolveOccurrenceMaster(eventData.id) : null;
+    return master ? master.id : null;
+  }
+
   /**
    * Subscribe to store changes
    * @param {Function} callback - Callback function
@@ -1069,10 +1485,6 @@ export class EventStore {
     }
   }
 
-  /**
-   * Notify listeners of changes
-   * @private
-   */
   /**
    * Deliver a change now, or queue it when a batch is open
    * @param {import('../types.js').EventStoreChange} change - Change to deliver
@@ -1086,6 +1498,12 @@ export class EventStore {
     }
   }
 
+  /**
+   * Deliver a change to every subscriber now, regardless of batch mode.
+   * A listener that throws is reported and does not stop the others.
+   * @param {import('../types.js').EventStoreChange} change - Change to deliver
+   * @private
+   */
   _notifyChange(change) {
     for (const listener of this.listeners) {
       try {
@@ -1354,12 +1772,13 @@ export class EventStore {
   }
 
   /**
-   * Clear all caches
+   * Clear all caches, including the recurrence engine's cached expansions
    */
   clearCaches() {
     this.optimizer.eventCache.clear();
     this.optimizer.queryCache.clear();
     this.optimizer.dateRangeCache.clear();
+    this._invalidateOccurrenceCache();
   }
 
   /**