calendar-plugin/requirements/recurrence_exceptions.md

Recurrence Exception Requirements

Purpose

Define normative behavior for recurring-event exception operations across admin UI, API, CalDAV, and ICS.

Scope

This document covers:

• Single-occurrence delete and edit semantics
• Exception storage model
• Merge/precedence rules for recurrence expansion
• Cross-surface consistency requirements

Core Principle

• A recurring event is one logical series keyed by stable series identity (event_id/UID).
• Exception operations modify occurrence behavior within that series.
• Exception operations must not split one series into multiple independent series unless explicitly invoked by a future "split series" feature.

Exception Types

• deleted_occurrence: one generated occurrence is suppressed.
• override_occurrence: one generated occurrence is replaced with modified instance values.

Delete-One-Occurrence Semantics

When a user deletes one occurrence of a recurring series:

• Add deleted_occurrence exception for the target occurrence key.
• Keep original series RRULE/repeat definition unchanged.
• Do not create a second series record.
• Future edits to series must still consider existing exceptions.

Edit-One-Occurrence Semantics

When a user edits one occurrence in a recurring series:

• Add/update override_occurrence exception for the target occurrence key.
• Override payload contains changed fields for that occurrence.
• Parent series remains the source for non-overridden fields.

Expansion Precedence Rules

Occurrence generation order:

1. Generate base occurrences from series rule.
2. Remove occurrences matching deleted_occurrence.
3. Apply override_occurrence records to matching occurrence keys.
4. Return sorted final set for window/query.

If both delete and override exist for the same occurrence key, the system must reject the conflicting write and require explicit conflict resolution.

Validation Rules

• Exception target must correspond to a valid generated occurrence in series context.
• Duplicate exception entries for same occurrence key are not allowed.
• Exception operations on non-recurring events are rejected.

CalDAV Representation

• Series remains same UID.
• Deleted occurrence represented with EXDATE and/or standards-compliant override pattern.
• Overridden occurrence represented with RECURRENCE-ID VEVENT override.
• Do not emit split UID sequences for single-occurrence deletes.

ICS Representation

• Export includes base RRULE for series.
• Deleted occurrences exported as exceptions.
• Overridden occurrences exported as recurrence-id overrides.
• Consumer synchronization should observe missing/changed occurrence without series duplication.

UI/API Behavior

• UI and API must expose "this occurrence only" actions distinctly from "entire series" actions.
• Confirmation messaging must clearly indicate operation scope.
• Audit records must capture actor, series, target occurrence key, and operation type.

Verification Requirements

Acceptance should verify:

• Delete-one-occurrence removes only target occurrence.
• Series remains unified in storage and output.
• Override-one-occurrence updates only target occurrence.
• CalDAV/ICS outputs reflect same exception semantics as admin/API views.