@forcecalendar/core 2.5.0 → 2.5.1

package/core/calendar/Calendar.js

@@ -235,6 +235,35 @@ export class Calendar {
     return this.eventStore.getEvent(eventId);
   }
 
+  /**
+   * Resolve an event id or occurrence id to the id of the stored event it
+   * refers to: the id itself for a stored event, the master's id for an
+   * occurrence id taken from view data, `null` when nothing stored matches.
+   * See `EventStore.resolveEventId`.
+   *
+   * @example
+   * calendar.resolveEventId('standup_1750028400000'); // 'standup'
+   * calendar.resolveEventId('unknown'); // null
+   *
+   * @param {string} id - Event id or occurrence id
+   * @returns {string|null} Id of the stored event, or null
+   */
+  resolveEventId(id) {
+    return this.eventStore.resolveEventId(id);
+  }
+
+  /**
+   * Get the occurrence an occurrence id from view data stands for, as an
+   * {@link Event} like the ones the views hold, or `null` when the id is
+   * not an occurrence of a stored recurring series. See
+   * `EventStore.getOccurrence`.
+   * @param {string} occurrenceId - Occurrence id (`<masterId>_<startMs>`)
+   * @returns {Event|null} The occurrence, or null
+   */
+  getOccurrence(occurrenceId) {
+    return this.eventStore.getOccurrence(occurrenceId, this.config.timeZone);
+  }
+
   /**
    * Get all stored events (recurring masters, never their occurrences)
    * @returns {Event[]}
@@ -269,13 +298,14 @@ export class Calendar {
     if (options.reconcile) {
       return this.reconcileEvents(events, options);
     }
+    this._assertIterable(events, 'setEvents');
 
     const removed = this.getEvents();
     this.eventStore.loadEvents(events);
     const added = this.getEvents();
 
     /** @type {import('../types.js').EventsSetPayload} */
-    const payload = { events: added, added, updated: [], removed, unchanged: [] };
+    const payload = { events: this.getEvents(), added, updated: [], removed, unchanged: [] };
     this._emit('eventsSet', payload);
     return payload;
   }
@@ -305,9 +335,10 @@ export class Calendar {
    * @param {Array<import('../events/Event.js').Event|import('../types.js').EventData>} events - Complete snapshot of events
    * @param {import('../types.js').ReconcileOptions} [options={}] - Reconcile options
    * @returns {import('../types.js').EventsSetPayload} Resulting events and the applied change set
-   * @throws {Error} If an entry fails validation or two entries share an id
+   * @throws {Error} If `events` is not iterable, an entry fails validation or two entries share an id
    */
   reconcileEvents(events, options = {}) {
+    this._assertIterable(events, 'reconcileEvents');
     const { removeMissing, isEquivalent } = options;
     const prepared = [];
     for (const eventData of events) {
@@ -330,6 +361,18 @@ export class Calendar {
     return payload;
   }
 
+  /**
+   * Throw a clear error when a snapshot is not iterable
+   * @param {*} events - Candidate snapshot
+   * @param {string} method - Calling method, for the message
+   * @private
+   */
+  _assertIterable(events, method) {
+    if (!events || typeof events[Symbol.iterator] !== 'function') {
+      throw new Error(`${method}() expects an iterable of events`);
+    }
+  }
+
   /**
    * Get the event store's change counter
    *
@@ -402,7 +445,7 @@ export class Calendar {
    *   remind(occurrence);
    * }
    *
-   * @param {string} eventId - The event ID
+   * @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
@@ -419,7 +462,7 @@ export class Calendar {
    * @example
    * const upcoming = calendar.getNextOccurrence('standup', new Date());
    *
-   * @param {string} eventId - The event ID
+   * @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
@@ -436,8 +479,8 @@ export class Calendar {
    * @example
    * const nextFive = calendar.takeOccurrences('standup', 5, { after: new Date() });
    *
-   * @param {string} eventId - The event ID
-   * @param {number} count - Maximum number of occurrences to return
+   * @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
@@ -704,11 +747,19 @@ export class Calendar {
    * @private
    */
   _getDayViewData(date) {
+    const timezone = this.config.timeZone;
     const events = this.getEventsForDate(date);
 
-    // Separate all-day and timed events
+    // Separate all-day and timed events. Hour slots are placed on the
+    // calendar's wall clock, so timed events are compared in that timezone.
     const allDayEvents = events.filter(e => e.allDay);
-    const timedEvents = events.filter(e => !e.allDay);
+    const timedEvents = events
+      .filter(e => !e.allDay)
+      .map(event => ({
+        event,
+        start: event.getStartInTimezone(timezone),
+        end: event.getEndInTimezone(timezone)
+      }));
 
     // Create hourly slots for timed events
     const hours = [];
@@ -721,11 +772,13 @@ export class Calendar {
       hours.push({
         hour,
         time: DateUtils.formatTime(hourDate, this.state.get('locale')),
-        events: timedEvents.filter(event => {
-          // Check if event occurs during this hour (not just starts)
-          // Event occurs in this hour if it overlaps with the hour slot
-          return event.start < hourEnd && event.end > hourDate;
-        })
+        events: timedEvents
+          .filter(({ start, end }) => {
+            // Check if event occurs during this hour (not just starts)
+            // Event occurs in this hour if it overlaps with the hour slot
+            return start < hourEnd && end > hourDate;
+          })
+          .map(({ event }) => event)
       });
     }
 
@@ -787,14 +840,37 @@ export class Calendar {
 
   /**
    * Select an event
-   * @param {string} eventId - Event ID to select
+   *
+   * Accepts a stored event's id or an occurrence id taken from view data
+   * (see {@link Event.occurrenceId}). Either way the stored event is what
+   * gets selected: `selectedEventId` in the state holds its id, so it can
+   * always be looked up with {@link Calendar#getEvent}. The `eventSelect`
+   * payload carries the stored `event`, its `eventId`, and for an
+   * occurrence id also `occurrenceId` and the `occurrence` itself (an
+   * {@link Event} as in view data, or null when the series has no
+   * occurrence at that instant). Nothing happens for an unknown id.
+   *
+   * @example
+   * calendar.on('eventSelect', ({ event, occurrence }) => open(occurrence || event));
+   * calendar.selectEvent(chip.dataset.eventId);
+   *
+   * @param {string} eventId - Event id or occurrence id to select
    */
   selectEvent(eventId) {
     const event = this.getEvent(eventId);
-    if (event) {
-      this.state.selectEvent(eventId);
-      this._emit('eventSelect', { event });
+    if (!event) {
+      return;
     }
+    const isOccurrence = eventId !== event.id;
+    this.state.selectEvent(event.id);
+    /** @type {import('../types.js').EventSelectPayload} */
+    const payload = {
+      event,
+      eventId: event.id,
+      occurrenceId: isOccurrence ? eventId : null,
+      occurrence: isOccurrence ? this.getOccurrence(eventId) : null
+    };
+    this._emit('eventSelect', payload);
   }
 
   /**

package/core/events/Event.js

@@ -42,6 +42,33 @@ function deepEqual(a, b) {
   return true;
 }
 
+/**
+ * Timezone identifiers Intl has already accepted. Every Event construction
+ * (each clone, each occurrence of a recurring series) validates its
+ * timezone, and constructing an Intl.DateTimeFormat per event dominated
+ * the cost of expanding a month grid.
+ * @type {Set<string>}
+ */
+const validatedTimezones = new Set();
+
+/**
+ * Throw unless Intl accepts the timezone identifier
+ * @param {string} timezone - IANA timezone identifier
+ * @param {string} label - Field name for the error message
+ * @throws {Error} If the timezone is not valid
+ */
+function assertValidTimezone(timezone, label) {
+  if (validatedTimezones.has(timezone)) {
+    return;
+  }
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+  } catch (e) {
+    throw new Error(`Invalid ${label}: ${timezone}`, { cause: e });
+  }
+  validatedTimezones.add(timezone);
+}
+
 export class Event {
   // Field size limits
   static FIELD_LIMITS = {
@@ -204,22 +231,12 @@ export class Event {
       });
     }
 
-    // Validate timezone if provided
+    // Validate timezones if provided (memoised per identifier)
     if (data.timeZone) {
-      try {
-        new Intl.DateTimeFormat('en-US', { timeZone: data.timeZone });
-      } catch (e) {
-        throw new Error(`Invalid timezone: ${data.timeZone}`, { cause: e });
-      }
+      assertValidTimezone(data.timeZone, 'timezone');
     }
-
-    // Validate end timezone if provided
     if (data.endTimeZone) {
-      try {
-        new Intl.DateTimeFormat('en-US', { timeZone: data.endTimeZone });
-      } catch (e) {
-        throw new Error(`Invalid end timezone: ${data.endTimeZone}`, { cause: e });
-      }
+      assertValidTimezone(data.endTimeZone, 'end timezone');
     }
   }
 
@@ -660,6 +677,8 @@ export class Event {
    * Scalars are compared with strict equality, dates by timestamp and
    * structured fields (recurrence rule, organizer, attendees, reminders,
    * categories, attachments, conference data, metadata) structurally.
+   * The `color` shorthand is not listed: normalization copies it into
+   * `backgroundColor` and `borderColor`, which are compared instead.
    * @type {ReadonlyArray<string>}
    */
   static EQUIVALENCE_FIELDS = Object.freeze([
@@ -672,7 +691,6 @@ export class Event {
     'endTimeZone',
     'description',
     'location',
-    'color',
     'backgroundColor',
     'borderColor',
     'textColor',
@@ -704,6 +722,14 @@ export class Event {
    * describe the same event. Two events with different ids are never
    * equivalent.
    *
+   * Two things to know when building snapshots for `reconcile()`:
+   * - `attendees`, `reminders`, `categories` and `attachments` are compared
+   *   in order, so the same attendees listed in a different order count as
+   *   a change.
+   * - Only the top-level dates are normalized. Values inside `metadata` are
+   *   compared as given, so a `Date` and its ISO string are not equivalent
+   *   there; keep metadata in one representation.
+   *
    * This is the default comparator used by `EventStore.reconcile()` to decide
    * whether an incoming snapshot entry replaces the stored event.
    *
@@ -747,10 +773,15 @@ export class Event {
    * @param {string} recurringEventId - Id of the recurring master event
    * @param {Date|number|string} occurrenceStart - Start of the occurrence
    * @returns {string} Occurrence id
+   * @throws {TypeError} If occurrenceStart is not a valid date
    */
   static occurrenceId(recurringEventId, occurrenceStart) {
     const start = occurrenceStart instanceof Date ? occurrenceStart : new Date(occurrenceStart);
-    return `${recurringEventId}_${start.getTime()}`;
+    const startMs = start.getTime();
+    if (Number.isNaN(startMs)) {
+      throw new TypeError('Event.occurrenceId: occurrenceStart must be a valid Date or timestamp');
+    }
+    return `${recurringEventId}_${startMs}`;
   }
 
   /**

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
@@ -148,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);
@@ -192,11 +199,31 @@ 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
    *
@@ -242,6 +269,60 @@ export class EventStore {
     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;
+  }
+
   /**
    * Get all events
    * @returns {Event[]} Array of all events
@@ -394,10 +475,14 @@ export class EventStore {
       }
     }
 
+    // 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, dayStart, dayEnd, timezone));
+        candidates.push(...this.expandRecurringEvent(event, expandStart, expandEnd, timezone));
       }
     }
 
@@ -433,11 +518,11 @@ export class EventStore {
       byDate.set(DateUtils.getLocalDateString(day), []);
     }
 
-    // Query one day beyond each edge so events that fall on an edge day in
-    // the requested timezone are not lost to the UTC-based range filter.
+    // 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, -1),
-      DateUtils.addDays(rangeEnd, 1),
+      DateUtils.addDays(rangeStart, -TIMEZONE_PAD_DAYS),
+      DateUtils.addDays(rangeEnd, TIMEZONE_PAD_DAYS),
       true,
       timezone
     );
@@ -472,7 +557,7 @@ export class EventStore {
 
     // 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);
@@ -869,7 +954,7 @@ export class EventStore {
    *   remind(occurrence);
    * }
    *
-   * @param {string} eventId - The event ID
+   * @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
@@ -887,7 +972,7 @@ export class EventStore {
    * @example
    * const upcoming = store.getNextOccurrence('standup', new Date());
    *
-   * @param {string} eventId - The event ID
+   * @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
@@ -906,8 +991,8 @@ export class EventStore {
    * @example
    * const nextFive = store.takeOccurrences('standup', 5, { after: new Date() });
    *
-   * @param {string} eventId - The event ID
-   * @param {number} count - Maximum number of occurrences to return
+   * @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
@@ -927,7 +1012,8 @@ export class EventStore {
    * @private
    */
   _occurrenceQuery(eventId, options) {
-    const event = this.events.get(eventId);
+    // 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`);
     }
@@ -950,6 +1036,7 @@ export class EventStore {
     this.indices.byCategory.clear();
     this.indices.byStatus.clear();
     this.eventIndexRefs.clear();
+    this._invalidateOccurrenceCache();
 
     this._notifyChange({
       type: 'clear',
@@ -982,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
@@ -1014,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}`);
@@ -1022,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: [] };
 
@@ -1034,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);
@@ -1042,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) {
@@ -1084,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
@@ -1324,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
@@ -1341,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 {
@@ -1609,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();
   }
 
   /**