Repository navigation
Description
Summary
modifyZones returns [ZoneInfo] and has no way to report a per-zone failure. CloudKit's zones/modify returns results positionally, and an individual entry may be an error dictionary rather than a zone — so a batch where some zones succeed and others fail is currently reported to the caller as a partial success with no indication that anything went wrong.
This is the gap the project's standing "RecordResult pattern throughout the API" guidance describes: per-item modify failures should be surfaced with the success-or-failure pattern everywhere — subscriptions, zones — not just records.
Surfaced during #386 verification. Deliberately kept out of #427 because fixing it is a breaking return-type change, not a schema addition.
Current behavior
Sources/MistKit/CloudKitService/CloudKitService+ModifyZones.swift:90:
return try (zonesData.zones ?? []).map { try ZoneInfo(fromZoneID: $0.zoneID) }Every entry is mapped straight through as a success. There is no failure branch, so an errored entry either fails conversion (surfacing as an opaque whole-batch error that names no specific zone) or is dropped.
The schema can't express the alternative either — after #427, ZonesModifyResponse.zones is array of Zone, and Zone models only zoneID / syncToken / atomic. There is no error variant, so a per-zone error dictionary has nowhere to decode into.
Why it matters
zones/modify is a batch endpoint. The realistic failure is partial: creating five zones where one already exists, or deleting zones where one is missing. Today the caller gets a shorter-than-expected array and cannot tell which zone failed or why — the serverErrorCode and reason Apple returns are discarded.
Precedent already exists in the codebase for the right shape. #429 introduces exactly this for the new change-tracking endpoints:
ZoneChangeResult/ZoneRecordChangesResult— per-zone success-or-failureZoneOperationFailure— carriesidentifier,serverErrorCode,reasonDatabaseChangesResult.changedZones/.failuresaccessors
So ZoneOperationFailure already exists and is already rendered by CloudKitError. This issue is about applying the same treatment to modifyZones.
Proposed change
- Spec — give the
zones/modifyresponse items aoneOfover the zone shape and a zone error dictionary (serverErrorCode,reason, and the zone identifier), then regenerate. Verify the error shape against Apple's archived reference first — the "Zone Fetch Error Dictionary" is documented, but as with Zone schemas only model { zoneID } — enrich with sync/atomic metadata + create options #386 the payload docs are abbreviated, so confirm before encoding. - Service — change
modifyZonesto return per-zone results rather than[ZoneInfo], reusingZoneChangeResult/ZoneOperationFailurefrom Add changes/database and changes/zone endpoints; deprecate zones/changes (#401, #47, #46) #429 rather than introducing a parallel type. Provide.zones/.failuresaccessors mirroringDatabaseChangesResult. - Convenience wrappers —
createZone/deleteZoneoperate on a single zone and can keep throwing on failure; they should surface the specificZoneOperationFailureinstead of a generic error.
Compatibility
This breaks source compatibility for modifyZones callers — the return type changes. Best landed while still in beta. Examples/BushelCloud and Examples/CelestraCloud should be checked for call sites; note that changes isolated to those subrepos belong in their own repos.
Sequencing
Best done after #429 merges, so ZoneOperationFailure and the ZoneChangeResult pattern are already on the branch and this doesn't duplicate them.
Activity
modifyZones per-zone failures (#431) + zones/changes metaSyncToken (#430
modifyZones per-zone failures (#431) + zones/changes metaSyncToken (#430
v1.0.0 beta.4 (#439)
leogdion commentedon Aug 29, 2026
Fixed in #443 —
modifyZonesnow returns[ZoneChangeResult]with per-zone failure support.