You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Zone schemas only model { zoneID } — enrich with sync/atomic metadata + create options #386
Follow-up to the zone endpoint tickets #43 (zones/list), #44 (zones/lookup), #45 (zones/modify), #48 (zones/changes) — all CLOSED. A gap review found every zone response models a zone as just { zoneID }, and there's no way to express zone-creation options.
Current state
ZonesListResponse, ZonesLookupResponse, ZonesModifyResponse, ZoneChangesResponse (openapi.yaml:1296-1340) each model a zone as { zoneID } only.
ZoneOperation (openapi.yaml:1215-1225) has no zone create options.
zones/modify request has no atomic flag.
What needs to be done
Add zone metadata to the response zone objects: syncToken, atomic, isEager.
Add zone create options to ZoneOperation (e.g. atomic).
Add an atomic flag to the zones/modify request.
⚠️ Needs live verification
webservices.md is abbreviated on zone payloads, so the exact field names/shape above should be confirmed against a live zones/list / zones/modify response before encoding them. Flagged for confirmation, not asserted as confirmed.
Implementation notes
Edit openapi.yaml only, then regenerate via ./Scripts/generate-openapi.sh. Never hand-edit Sources/MistKitOpenAPI/.
Map new fields onto the domain ZoneInfo / zone result types in Sources/MistKit/Models/Zones/.
Verified the proposed fields against Apple's archived CloudKit Web Services Reference before encoding them. Three of the five proposed changes could not be confirmed, so PR #427 implements only the confirmed subset.
Confirmed and implemented — the "Zone Dictionary" documents exactly three keys, and all four zone endpoints route their success payload through it:
zoneID
syncToken — "The current point in the zone's change history."
atomic — "A Boolean value indicating whether this zone supports atomic operations."
Not confirmed, omitted:
isEager — appears in no primary source. Not in the Zone Dictionary, nowhere in the archived reference, and absent from both .claude/docs/webservices.md and .claude/docs/cloudkitjs.md. If this came from an observed live response, please paste it and I'll model it; otherwise there's no basis for a name or type.
atomic on the zones/modify request — ModifyZones.html documents the body as operations only. Notably records/modifydoes document atomic, so the asymmetry appears deliberate.
Zone create options on ZoneOperation — same page: the operation's zone is "A dictionary representing the zone to modify. It has a single zoneID key."
Follow-ups found during verification (not in PR #427)
1. modifyZones drops per-zone failures. Apple documents a "Zone Fetch Error Dictionary" (zoneID, reason, serverErrorCode, retryAfter, redirectURL) returned inline for failed zones in zones/list, zones/lookup, and zones/modify. modifyZones returns [ZoneInfo] and silently discards those entries — the exact gap .claude/memory/feedback_record_result_pattern_throughout.md describes, previously fixed for records and subscriptions. Fix needs a ZoneOperationFailure schema, a oneOf response, and a return-type change (a source break), so it wants its own issue.
2. zones/changes may use the wrong token key.GetZoneChanges.html documents the request and response token as metaSyncToken; MistKit sends and reads syncToken. If the doc is right, fetchZoneChanges pagination is silently broken. Holding off because Apple's page contradicts itself — the moreComing description refers back to "the included syncToken key" — so this needs a live-response check, not a doc-driven change.
3. zones/changes is documented as deprecated in favor of changes/database.
The verification comment above narrowed #427 to the confirmed subset. Two things surfaced during that verification that are out of scope for #427 and are now tracked separately, so they don't get lost when this closes:
zones/changes may use metaSyncToken, not syncToken — pagination possibly broken #430 — zones/changes may use metaSyncToken, not syncToken. If Apple's field name is right, that endpoint's pagination has never worked. Not changed on evidence alone: Apple's own page contradicts itself, and openapi.yaml has the same split — the description reads "Get all changed zones relative to a meta-sync token" while the property is named syncToken. metaSyncToken appears nowhere in the repo. Needs a live response to settle.
ZoneID's owner key is ownerRecordName in Apple's archived reference, but ownerName in both MistKit's domain ZoneID and its wire schema. Left alone as out of scope, but if the wire name is genuinely ownerRecordName, then owner-qualified zone addressing — shared zones — would not work, which touches #146's shared-zone support. I did not verify which is correct; flagging it rather than asserting it. Say the word and I'll open an issue.
Also note the deliberate omissions in #427, so they aren't mistaken for oversights: isEager (appears in no primary source), atomic on the zones/modify request (Apple documents that body as operations only), and zone create options on ZoneOperation (documented as a single zoneID key, now pinned by a regression test). Each needs a doc update or a live payload before it can be added.
Resolved on v1.0.0-beta.4 via #427 (commit 5a65bf3). Shared Zone schema added and reused across all four zone responses; syncToken and atomic surfaced on ZoneInfo.
Scope note: only the fields confirmed against Apple's primary reference were implemented. isEager and the proposed zones/modify request options were not confirmed and were deliberately left out rather than guessed. The two follow-ups this surfaced are tracked separately in #430 (metaSyncToken on zones/changes) and #431 (modifyZones RecordResult pattern).
Activity
leogdion commentedon Aug 20, 2026
Moving from the v1.0.0-beta.3 milestone to v1.0.0-beta.4 — work not yet complete.
leogdion commentedon Aug 20, 2026
Verification results (PR #427)
Verified the proposed fields against Apple's archived CloudKit Web Services Reference before encoding them. Three of the five proposed changes could not be confirmed, so PR #427 implements only the confirmed subset.
Confirmed and implemented — the "Zone Dictionary" documents exactly three keys, and all four zone endpoints route their success payload through it:
zoneIDsyncToken— "The current point in the zone's change history."atomic— "A Boolean value indicating whether this zone supports atomic operations."Not confirmed, omitted:
isEager— appears in no primary source. Not in the Zone Dictionary, nowhere in the archived reference, and absent from both.claude/docs/webservices.mdand.claude/docs/cloudkitjs.md. If this came from an observed live response, please paste it and I'll model it; otherwise there's no basis for a name or type.atomicon thezones/modifyrequest — ModifyZones.html documents the body asoperationsonly. Notablyrecords/modifydoes documentatomic, so the asymmetry appears deliberate.ZoneOperation— same page: the operation'szoneis "A dictionary representing the zone to modify. It has a singlezoneIDkey."Follow-ups found during verification (not in PR #427)
1.
modifyZonesdrops per-zone failures. Apple documents a "Zone Fetch Error Dictionary" (zoneID,reason,serverErrorCode,retryAfter,redirectURL) returned inline for failed zones inzones/list,zones/lookup, andzones/modify.modifyZonesreturns[ZoneInfo]and silently discards those entries — the exact gap.claude/memory/feedback_record_result_pattern_throughout.mddescribes, previously fixed for records and subscriptions. Fix needs aZoneOperationFailureschema, aoneOfresponse, and a return-type change (a source break), so it wants its own issue.2.
zones/changesmay use the wrong token key. GetZoneChanges.html documents the request and response token asmetaSyncToken; MistKit sends and readssyncToken. If the doc is right,fetchZoneChangespagination is silently broken. Holding off because Apple's page contradicts itself — themoreComingdescription refers back to "the includedsyncTokenkey" — so this needs a live-response check, not a doc-driven change.3.
zones/changesis documented as deprecated in favor ofchanges/database.Record verified CloudKit Zone Dictionary facts in project memory
leogdion commentedon Aug 20, 2026
Two follow-ups split out of this issue
The verification comment above narrowed #427 to the confirmed subset. Two things surfaced during that verification that are out of scope for #427 and are now tracked separately, so they don't get lost when this closes:
zones/changesmay usemetaSyncToken, notsyncToken. If Apple's field name is right, that endpoint's pagination has never worked. Not changed on evidence alone: Apple's own page contradicts itself, andopenapi.yamlhas the same split — the description reads "Get all changed zones relative to a meta-sync token" while the property is namedsyncToken.metaSyncTokenappears nowhere in the repo. Needs a live response to settle.modifyZonessilently drops per-zone failures. It maps every response entry throughZoneInfo(fromZoneID:)with no failure branch, so a partially-failed batch reads as a short success array. This is the RecordResult-pattern gap. Best done after Add changes/database and changes/zone endpoints; deprecate zones/changes (#401, #47, #46) #429, which introducesZoneOperationFailureand the per-zone result types this would reuse.One more thing worth recording
ZoneID's owner key isownerRecordNamein Apple's archived reference, butownerNamein both MistKit's domainZoneIDand its wire schema. Left alone as out of scope, but if the wire name is genuinelyownerRecordName, then owner-qualified zone addressing — shared zones — would not work, which touches #146's shared-zone support. I did not verify which is correct; flagging it rather than asserting it. Say the word and I'll open an issue.Also note the deliberate omissions in #427, so they aren't mistaken for oversights:
isEager(appears in no primary source),atomicon thezones/modifyrequest (Apple documents that body asoperationsonly), and zone create options onZoneOperation(documented as a singlezoneIDkey, now pinned by a regression test). Each needs a doc update or a live payload before it can be added.🤖 Generated with Claude Code
Add confirmed zone metadata (syncToken, atomic) to zone schemas
Record verified CloudKit Zone Dictionary facts in project memory
Add confirmed zone metadata (syncToken, atomic) to zone schemas
Record verified CloudKit Zone Dictionary facts in project memory
Add confirmed zone metadata (syncToken, atomic) to zone schemas
Record verified CloudKit Zone Dictionary facts in project memory
leogdion commentedon Aug 28, 2026
Resolved on
v1.0.0-beta.4via #427 (commit 5a65bf3). SharedZoneschema added and reused across all four zone responses;syncTokenandatomicsurfaced onZoneInfo.Scope note: only the fields confirmed against Apple's primary reference were implemented.
isEagerand the proposedzones/modifyrequest options were not confirmed and were deliberately left out rather than guessed. The two follow-ups this surfaced are tracked separately in #430 (metaSyncTokenonzones/changes) and #431 (modifyZonesRecordResult pattern).