feat: Schedule-Tag and etag support

Ref RFC 6638 §3.2-3.3

Schedule-Tag implementation:
- `save()` and `add_event()` capture the Schedule-Tag from the
  response header and stores it in `self.props` (same logic with etag).
- `save()` sends `If-Schedule-Tag-Match` or `If-Match`-header if
  etag or schedule-tag is set.
- raises `ScheduleTagMismatchError` or `ETagMismatchError` on 412.
- `_reply_to_invite_request()`: when the server auto-schedules the event
  into the attendee's calendar (`scheduling.auto-schedule` supported),
  search all attendee calendars first and update the existing copy in
  place to preserve the server-assigned Schedule-Tag.  Fall through to
  `add_event()` only for non-auto-schedule servers.
- Assume SEQUENCE:0 default when SEQUENCE property is absent (RFC 5546
  section 2.1.4 requires incrementing for significant changes).
  test: add failing tests for Schedule-Tag support (RFC 6638)

Also adds design docs:
- docs/design/TODO_SCHEDULE_TAG.md (analysis and implementation plan,
  refs #660)
- docs/design/TODO_COMPATIBILITY_HINTS.md (FeatureSet cleanup analysis,
  refs #659)

The schedule-tag logic was predominantly hand-written (with some
trivial bugfixing done by Claude).  Claude contributed with design
suggestions, which have been partly followed.  Test code is predominantly
AI-written.

prompt: (exact prompt is lost, but I was discussing the schedule-tags,
  and the output is in the new file docs/design/TODO_SCHEDULE_TAG.md)
prompt: Please write up test code (unit tests + integration tests) on the
schedule tags.  Don't fix the code yet.
prompt: Please write up test code (unit tests + integration tests) on the
  schedule tags.  Don't fix the code yet.
followup-prompts: (discussions on test breakages.  While debugging,
  Claude has been insisting on searching for the Schedule-Tag by using
  a PropFind if it wasn't included in the headers, but that does not
  make sense)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: tobixen

AI-POLICY.md

@@ -4,9 +4,25 @@
 
 The most important rule: be honest and inform about it!
 
-Also: keep a log of the prompts used - prompts may be included in the
+Keep a log of the prompts used - prompts should preferably be included in the
 git commits.
 
+Tools should generally be used for improving the quality of the
+project, not for rapidly adding new features.
+
+Keep a log of the prompts used - prompts should be included
+verbatimely in the git commits as long as it's possible without making
+the messages too messy.  When relevant, chat-output may also need to
+be included.  The `docs/design`-folder can be used for dumping
+AI-generated design documents, code reviews, prompts that are too
+large for being included in the commit message, etc.
+
+Keep it clear what is human-written vs what is AI-written.  In a
+feature-branch, separate AI-commits and human-commits is preferable.
+Those should most often be squashed together before including it in
+the main branch, with a notice in the commit message on what parts o
+the commit is AI-generated.
+
 ## Transparency matters
 
 If you've spent hours, perhaps a full day of your time writing up a
@@ -32,8 +48,7 @@ explain in details why I'm rejecting the pull request.
 
 It's fine to ask the AI for help to analyze a bug and create a fix for
 it.  By discovering the bug, reproducing it and testing it you're
-adding real value to the project - just be transparent about AI usage
-and do not take offence if the code changes are rejected, or completely
+adding real value to the project - just remember to be honest, if you have no clue what Claude did and why it solves the bug, then inform!  Do not take offence if the code changes are rejected, or completely
 rewritten.
 
 ## General rules

caldav/base_client.py

@@ -22,6 +22,9 @@
 
 log = logging.getLogger("caldav")
 
+## Common HTTP headers
+ICALH = {"Content-Type": 'text/calendar; charset="utf-8"'}
+
 
 class BaseDAVClient(ABC):
     """

caldav/calendarobjectresource.py

@@ -39,6 +39,7 @@
 
 from contextlib import contextmanager
 
+from .base_client import ICALH
 from .datastate import DataState, IcalendarState, NoDataState, RawDataState, VobjectState
 from .davobject import DAVObject
 from .elements import cdav, dav
@@ -95,6 +96,15 @@ class CalendarObjectResource(DAVObject):
     _state: DataState | None = None
     _borrowed: bool = False
 
+    # Schedule tag (ref https://github.com/python-caldav/caldav/issues/660 and docs/design/TODO-SCHEDULE.md)
+    @property
+    def schedule_tag(self) -> str | None:
+        return self.props.get(cdav.ScheduleTag.tag)
+
+    @property
+    def etag(self) -> str | None:
+        return self.props.get(dav.GetEtag.tag)
+
     @property
     def id(self) -> str | None:
         """Returns the UID of the calendar object.
@@ -410,7 +420,7 @@ def get_relatives(
         acceptable relation types in reltypes, or by passing a lambda
         function in relfilter.
 
-        TODO: Make it possible to  also check up reverse relationships
+        TODO: Make it possible to also check up reverse relationships
 
         TODO: this is partially overlapped by plann.lib._relships_by_type
         in the plann tool.  Should consolidate the code.
@@ -773,18 +783,34 @@ def _reply_to_invite_request(self, partstat, calendar) -> None:
         ## we need to modify the icalendar code, update our own participant status
         self.icalendar_instance.pop("METHOD")
         self.change_attendee_status(partstat=partstat)
-        self.get_property(cdav.ScheduleTag(), use_cached=True)
+        uid = self.id
+        ## On auto-scheduling servers the server already places the event in the attendee's
+        ## calendar with a Schedule-Tag set.  We must update that copy rather than creating a
+        ## new one via add_event() — a plain attendee PUT won't get a Schedule-Tag because
+        ## servers only assign it on organizer-originated scheduling operations.
+        if uid and self.client.features.is_supported("scheduling.auto-schedule"):
+            for cal in self.client.principal().calendars():
+                try:
+                    existing = cal.event_by_uid(uid)
+                    existing.load()
+                    existing.change_attendee_status(partstat=partstat)
+                    existing.save()
+                    return
+                except error.NotFoundError:
+                    pass
         try:
             calendar.add_event(self.data)
         except Exception:
-            ## TODO - TODO - TODO
-            ## RFC6638 does not seem to be very clear (or
-            ## perhaps I should read it more thoroughly) neither on
-            ## how to handle conflicts, nor if the reply should be
-            ## posted to the "outbox", saved back to the same url or
-            ## sent to a calendar.
+            ## add_event() failed — the event likely already exists (e.g. non-auto-scheduling
+            ## server that still rejects duplicate UIDs).  Reload self from the inbox so we have
+            ## fresh data (METHOD is restored), then retry via the outbox: posting an iTIP REPLY
+            ## to the outbox lets the server process the PARTSTAT update on our behalf, which is
+            ## the correct RFC 6638 mechanism when we cannot write directly to the calendar.
+            ## We intentionally do NOT do a separate PROPFIND for Schedule-Tag here: the tag must
+            ## be read atomically with the object data (a separate request could race with a
+            ## concurrent scheduling operation), and RFC 6638 requires the server to return it
+            ## as a response header on GET — so load() is sufficient if the server complies.
             self.load()
-            self.get_property(cdav.ScheduleTag(), use_cached=False)
             outbox = self.client.principal().schedule_outbox()
             if calendar.url != outbox.url:
                 self._reply_to_invite_request(partstat, calendar=outbox)
@@ -868,6 +894,7 @@ def load(self, only_if_unloaded: bool = False) -> Self:
         except Exception:
             return self.load_by_multiget()
 
+        ## consider refactoring - this is repeated many places now
         if "Etag" in r.headers:
             self.props[dav.GetEtag.tag] = r.headers["Etag"]
         if "Schedule-Tag" in r.headers:
@@ -997,10 +1024,25 @@ def _find_id_path(self, id=None, path=None) -> None:
         self.url = URL.objectify(path)
 
     def _put(self, retry_on_failure=True):
+        ## TODO: quite much overlapping with _async_put, should consolidate
+        ## TODO: this is low-level http-communication - shouldn't it be in the davclient file rather than in calendarobjectresource.py?
         ## SECURITY TODO: we should probably have a check here to verify that no such object exists already
-        r = self.client.put(self.url, self.data, {"Content-Type": 'text/calendar; charset="utf-8"'})
-        if r.status == 302:
-            path = [x[1] for x in r.headers if x[0] == "location"][0]
+        headers = {}  ## TODO: use some caseinsensitivedict
+        if self.schedule_tag:
+            headers["if-schedule-tag-match"] = self.schedule_tag
+        elif self.etag:
+            headers["if-match"] = self.etag
+        headers |= ICALH
+        r = self.client.put(self.url, self.data, headers)
+        if r.status == 412:
+            if self.schedule_tag:
+                raise error.ScheduleTagMismatchError(errmsg(r))
+            elif self.etag:
+                raise error.ETagMismatchError(errmsg(r))
+            else:
+                raise error.PutError(errmsg(r))
+        elif r.status == 302:
+            self.url = URL.objectify([x[1] for x in r.headers if x[0] == "location"][0])
         elif r.status not in (204, 201):
             if retry_on_failure:
                 try:
@@ -1014,14 +1056,14 @@ def _put(self, retry_on_failure=True):
                 return self._put(False)
             else:
                 raise error.PutError(errmsg(r))
+        if "Etag" in r.headers:
+            self.props[dav.GetEtag.tag] = r.headers["Etag"]
+        if r.headers and r.headers.get("schedule-tag"):
+            self.props[cdav.ScheduleTag.tag] = r.headers["schedule-tag"]
 
     async def _async_put(self, retry_on_failure=True):
         """Async version of _put for async clients."""
-        r = await self.client.put(
-            str(self.url),
-            str(self.data),
-            {"Content-Type": 'text/calendar; charset="utf-8"'},
-        )
+        r = await self.client.put(str(self.url), str(self.data), ICALH)
         if r.status == 302:
             path = [x[1] for x in r.headers if x[0] == "location"][0]
             self.url = URL.objectify(path)
@@ -1036,6 +1078,11 @@ async def _async_put(self, retry_on_failure=True):
                 return await self._async_put(False)
             else:
                 raise error.PutError(errmsg(r))
+        ## TODO: refactor - those code lines are repeated all over the place
+        if "Etag" in r.headers:
+            self.props[dav.GetEtag.tag] = r.headers["Etag"]
+        if r.headers and r.headers.get("schedule-tag"):
+            self.props[cdav.ScheduleTag.tag] = r.headers["schedule-tag"]
 
     def _create(self, id=None, path=None, retry_on_failure=True) -> None:
         ## TODO: Find a better method name
@@ -1120,7 +1167,6 @@ def save(
         no_create: bool = False,
         obj_type: str | None = None,
         increase_seqno: bool = True,
-        if_schedule_tag_match: bool = False,
         only_this_recurrence: bool = True,
         all_recurrences: bool = False,
     ) -> Self:
@@ -1137,8 +1183,7 @@ def save(
 
         The SEQUENCE should be increased when saving a new version of
         the object.  If this behaviour is unwanted, then
-        increase_seqno should be set to False.  Also, if SEQUENCE is
-        not set, then this will be ignored.
+        increase_seqno should be set to False.
 
         The behaviour when saving a single recurrence object to the
         server is as far as I can understand not defined in the RFCs,
@@ -1170,7 +1215,6 @@ def save(
                 no_create=no_create,
                 obj_type=obj_type,
                 increase_seqno=increase_seqno,
-                if_schedule_tag_match=if_schedule_tag_match,
                 only_this_recurrence=only_this_recurrence,
                 all_recurrences=all_recurrences,
             )
@@ -1285,19 +1329,17 @@ def _incorporate_recurrence_into_parent(self, obj, only_this_recurrence, all_rec
                 ici.add_component(self.icalendar_component)
 
     def _maybe_increment_sequence(self, increase_seqno):
-        """Increment SEQUENCE number if present and increase_seqno is True."""
+        """Increment SEQUENCE number if increase_seqno is True."""
         if increase_seqno and "SEQUENCE" in self.icalendar_component:
-            seqno = self.icalendar_component.pop("SEQUENCE", None)
-            if seqno is not None:
-                self.icalendar_component.add("SEQUENCE", seqno + 1)
+            seqno = self.icalendar_component.pop("SEQUENCE", 0)
+            self.icalendar_component.add("SEQUENCE", seqno + 1)
 
     async def _async_save(
         self,
         no_overwrite: bool = False,
         no_create: bool = False,
         obj_type: str | None = None,
         increase_seqno: bool = True,
-        if_schedule_tag_match: bool = False,
         only_this_recurrence: bool = True,
         all_recurrences: bool = False,
     ) -> Self:

caldav/collection.py

@@ -30,6 +30,7 @@
 from collections.abc import Iterable, Iterator, Sequence
 from typing import Literal
 
+from .base_client import ICALH
 from .calendarobjectresource import (
     CalendarObjectResource,
     Event,
@@ -509,17 +510,13 @@ def freebusy_request(self, dtstart, dtend, attendees) -> dict[str, FreeBusy]:
 
         caldavobj.add_organizer()
 
-        response = self.client.post(
-            outbox.url,
-            caldavobj.data,
-            headers={"Content-Type": "text/calendar; charset=utf-8"},
-        )
+        response = self.client.post(outbox.url, caldavobj.data, headers=ICALH)
         return response._parse_scheduling_response_objects(parent=self)
 
     async def _async_freebusy_request(self, outbox, fb_obj) -> dict:
         """Async implementation of freebusy_request() for async clients."""
         ## TODO: could we have common headers as global variable?
-        headers = {"Content-Type": "text/calendar; charset=utf-8"}
+        headers = ICALH
         outbox = await outbox
         ## TODO: it's really bad that arbitrary methods returns
         ## a coroutine in async mode.  It's needed to make it much
@@ -1957,35 +1954,51 @@ def __init__(
 
     def get_items(self):
         """
-        TODO: work in progress
-        TODO: perhaps this belongs to the super class?
+        Return all items currently in this scheduling mailbox (inbox or outbox).
+
+        Unlike regular calendars, schedule mailboxes contain raw iTIP messages
+        (METHOD:REQUEST, METHOD:REPLY, METHOD:CANCEL, …) rather than permanent
+        calendar objects.  Items should be processed and then deleted; they are
+        not meant to be kept indefinitely.
+
+        Servers often do not support the sync-collection REPORT (RFC 6578) on
+        schedule-inbox/outbox — the inbox is not a full calendar collection and
+        may not be indexed the same way.  We therefore attempt the sync-token
+        path first (efficient for repeat polling) but fall back transparently to
+        a plain PROPFIND depth-1 followed by individual GETs.  Both paths return
+        loaded CalendarObjectResource objects.
+
+        This method does NOT belong on the Calendar super-class: Calendar exposes
+        type-specific accessors (get_events, get_todos, …) and uses search()
+        internally.  The mailbox is a different beast — it holds transient,
+        mixed-type scheduling messages and must use children() as its fallback
+        because search() / REPORT queries against a mailbox URL are unreliable
+        across servers.
         """
+
+        def _load_from_children():
+            items = [CalendarObjectResource(url=x[0], client=self.client) for x in self.children()]
+            for x in items:
+                x.load()
+            return items
+
         if not self._items:
             try:
                 self._items = self.objects(load_objects=True)
             except Exception:
                 logging.debug(
-                    "caldav server does not seem to support a sync-token REPORT query on a scheduling mailbox"
+                    "sync-collection REPORT not supported on scheduling mailbox %s; "
+                    "falling back to PROPFIND depth-1",
+                    self.url,
                 )
-                error.assert_("google" in str(self.url))
-                self._items = [
-                    CalendarObjectResource(url=x[0], client=self.client) for x in self.children()
-                ]
-                for x in self._items:
-                    x.load()
+                self._items = _load_from_children()
         else:
             try:
                 self._items.sync()
             except Exception:
-                self._items = [
-                    CalendarObjectResource(url=x[0], client=self.client) for x in self.children()
-                ]
-                for x in self._items:
-                    x.load()
+                self._items = _load_from_children()
         return self._items
 
-    ## TODO: work in progress
-
 
 #    def get_invites():
 #        for item in self.get_items():