Zone payloads: `deleted`, `zoneType` unmodeled and `ownerRecordName` never decodes (confirmed live)

[leogdion]

Summary

A live zones/changes call against a real container returned zone objects that carry deleted and zoneType, neither of which MistKit models. deleted is the significant one: a caller currently cannot tell a deleted zone from a live one.

Evidence

POST zones/changes on iCloud.com.brightdigit.MistDemo / development / private DB, no sync token:

{
  "moreComing": false,
  "metaSyncToken": "AQAAAaBJidqD",
  "zones": [
    {
      "zoneID": {
        "zoneName": "WebChangeTest",
        "ownerRecordName": "_aca0fa3547ae9f9cd1f7e25fed948a20",
        "zoneType": "REGULAR_CUSTOM_ZONE"
      },
      "deleted": true
    }
  ]
}

Every zone in the response had "deleted": true and a zoneType inside zoneID.

Current state

After #427, the shared Zone schema in openapi.yaml models zoneID, syncToken, atomic. The domain ZoneInfo carries zoneName, ownerRecordName, capabilities, syncToken, atomic.

Neither deleted (zone level) nor zoneType (inside zoneID) is represented, so both are silently dropped on decode.

Note #427 deliberately implemented only the subset confirmed against Apple's archived reference and left unconfirmed fields out rather than guessing (see .claude/memory/reference_cloudkit_zone_dictionary.md). This issue supplies live confirmation for two more fields — the same standard of evidence, now from an actual response rather than the docs.

Why deleted matters

zones/changes is a change feed: a deleted zone is exactly the kind of change a sync client must observe. Returning it as an ordinary ZoneInfo indistinguishable from a live zone means a caller replaying changes will treat deletions as creations.

Worth checking whether changes/database (DatabaseChangedZone, the supported replacement per #401) carries the same field — it likely does, and that path is the one callers should be using.

What to do

1. Confirm the field set against changes/database as well as zones/changes before encoding — do not assume they match.
2. Add deleted: Bool? to the Zone schema (and DatabaseChangedZone if confirmed there), and zoneType to ZoneID, in openapi.yaml; regenerate via ./Scripts/generate-openapi.sh.
3. Surface them on the domain types. Consider whether deleted deserves better than Bool? on ZoneInfo — a change feed arguably wants a per-zone enum (changed vs deleted), which would be a larger design change.
4. zoneType observed value: REGULAR_CUSTOM_ZONE. Find the full set before modeling it as an enum rather than a string.

Found while verifying #430.

🤖 Generated with Claude Code

[leogdion]

Also confirmed: ownerRecordName vs ownerName — the zone owner never decodes

Verified against live zones/list and zones/changes responses on iCloud.com.brightdigit.MistDemo:

zones/list  zoneID keys: ['zoneName', 'ownerRecordName', 'zoneType']

But openapi.yaml:1338 declares:

ZoneID:
  type: object
  properties:
    zoneName:
      type: string
    ownerName:
      type: string

grep -c ownerRecordName openapi.yaml → 0. The string does not appear in the spec at all.

ZoneInfo.init(from:) maps ownerRecordName: zoneID.ownerName (Sources/MistKit/Models/Zones/ZoneInfo.swift:94), so for every zone read back from the server the owner decodes as nil — the field is silently dropped on the wire.

Why this matters beyond cosmetics

#146 / #426 chose ZoneID over a bare zoneName: String specifically because ZoneID carries the owner, and shared zones live in the owner's database and are unaddressable without it. If the owner never round-trips, that rationale doesn't hold up in practice: you cannot read a shared zone's owner back out of any zone response.

Not yet established: the request direction

I tried to determine whether CloudKit accepts ownerName or requires ownerRecordName in requests, but my hand-rolled zones/lookup body was malformed — all four variants (both spellings × valid/bogus owner) returned BAD_REQUEST, which tells us nothing about the key name. That question is still open and should be settled with MistKit itself (which knows the correct request envelope) rather than raw HTTP.

Both directions need checking before changing the spec: it is possible CloudKit accepts ownerName on input and emits ownerRecordName on output, in which case the fix is asymmetric.

Scope note

This is pre-existing and orthogonal to #430's metaSyncToken rename (PR #443) — deliberately left out of that PR. Grouping it here since it is the same class of finding: a zone-payload field that live responses carry and MistKit does not model correctly.