Clarify change-tracking endpoint coverage (changes/* vs records/changes + deprecated zones/changes)

[leogdion]

Summary

The roadmap, issues, and openapi.yaml use inconsistent naming for CloudKit's change-tracking endpoints, which led to #46 and #47 being closed as "completed" against the wrong operations. This issue documents the canonical Apple surface and what MistKit actually implements, so the spec and roadmap can be reconciled.

Apple's four change-tracking endpoints

Per the CloudKit Web Services Reference:

Apple endpoint	Purpose	Status
records/changes	Fetching Record Changes	current
zones/changes	Fetching Zone Changes	deprecated — Apple says use changes/database
changes/database	Fetching Database Changes — returns which zones changed	current (replacement for zones/changes)
changes/zone	Fetching Record Zone Changes — record changes within a zone	current

What MistKit implements today (openapi.yaml @ docs/sync-beta.2)

• ✅ records/changes → fetchRecordChanges
• ⚠️ zones/changes → fetchZoneChanges — this is the deprecated endpoint
• ❌ changes/database — not in the spec, no wrapper (tracked in Fetching Database Changes (changes/database) #46)
• ❌ changes/zone — not in the spec, no wrapper (tracked in Fetching Record Zone Changes (changes/zone) #47)

So no changes/* endpoint is implemented, and the only zone-level coverage we ship is the deprecated zones/changes.

Why this is confusing

• Fetching Database Changes (changes/database) #46 ("Fetching Database Changes (changes/database)") was closed after being mapped to records/changes — a different endpoint.
• Fetching Record Zone Changes (changes/zone) #47 ("Fetching Record Zone Changes (changes/zone)") was closed conflated with records/changes as well.
• The README roadmap lists both under Backlog / Post-beta using Apple's changes/* names, while the implemented operations use records/changes / zones/changes names — so it's not obvious what's actually shipped.

Proposed resolution

1. Spec: add changes/database and changes/zone to openapi.yaml (+ regenerate), and mark zones/changes / fetchZoneChanges as deprecated in favor of changes/database.
2. Service: add CloudKitService wrappers for the two new endpoints; decide whether to deprecate fetchZoneChanges.
3. Docs/roadmap: in README, list the four endpoints with both Apple names and MistKit method names, and reflect deprecation.
4. Keep Fetching Database Changes (changes/database) #46 / Fetching Record Zone Changes (changes/zone) #47 as the per-endpoint implementation trackers; this issue is the umbrella/clarification.

References

• Fetching Database Changes (changes/database): https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/FetchingDatabaseChanges(changeszone).html
• Fetching Record Zone Changes (changes/zone): https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/FetchingRecordZoneChanges(changeszone).html
• Fetching Zone Changes (zones/changes) — deprecated: https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/GetZoneChanges.html
• Fetching Record Changes (records/changes): https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/ChangeRecords.html

Related: #46, #47