# 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.