docs(swift-sdk): add batch reads and changes since a cursor

content/docs/(overview)/devices.mdx

@@ -13,7 +13,7 @@ A device chooses the **slice** of the instance it keeps: a list of types, a tier
 
 Reads come from the copy, with no connection needed. A file's bytes are there once the device has fetched them. The core also [reads saved views](/build/read-a-view), including sort order, groups and counts. **A view's item or group read needs the whole query held** and is refused with a reason if the copy cannot answer it completely.
 
-**While a device fills its copy, it answers direct item reads from what has arrived.** A list or search without a saved view returns the items the copy holds so far and marks the answer `partial`; once the copy is whole, the same read is marked `complete`. A read by ID answers for an item that has arrived, and is refused `hydration_incomplete` for one that hasn't. Until the copy is whole, edge reads are refused `hydration_incomplete`, because an edge's two ends can arrive on different pages. A write to an item that has arrived, or a new item, is queued against the version the copy holds and sent once the copy is whole. This includes a file added on its own or attached to an item that has arrived: the device keeps its bytes and uploads them with the rest of the queue. A write to an item that hasn't arrived, or a file attached to one, is refused `hydration_incomplete`, because there is no version to base it on, and a drain is refused `hydration_incomplete` until the copy is whole. **Edge writes are refused `hydration_incomplete` until the copy is whole**, because a page still to arrive can bring the instance's edge in place of the one a write was made against. An edit that changes an item's body is still queued, and the device reads the body's links and embeds and makes their edges once the server answers the edit. The device's status reports how many items the fill has brought so far and, where the instance counted them, how many the slice held when the fill began, so an app can show how far the fill has come. Compare those two figures, not the count of items the copy holds, which also includes pinned items and creates that are still queued. The Swift SDK returns these answers as `Rows` with a `completeness`.
+**While a device fills its copy, it answers direct item reads from what has arrived.** A list or search without a saved view returns the items the copy holds so far and marks the answer `partial`; once the copy is whole, the same read is marked `complete`. A read of one item by ID answers for an item that has arrived, and is refused `hydration_incomplete` for one that hasn't; a read of many by ID answers those that have arrived and marks the answer `partial`. Until the copy is whole, edge reads are refused `hydration_incomplete`, because an edge's two ends can arrive on different pages, and so is a read of what changed since a cursor. A write to an item that has arrived, or a new item, is queued against the version the copy holds and sent once the copy is whole. This includes a file added on its own or attached to an item that has arrived: the device keeps its bytes and uploads them with the rest of the queue. A write to an item that hasn't arrived, or a file attached to one, is refused `hydration_incomplete`, because there is no version to base it on, and a drain is refused `hydration_incomplete` until the copy is whole. **Edge writes are refused `hydration_incomplete` until the copy is whole**, because a page still to arrive can bring the instance's edge in place of the one a write was made against. An edit that changes an item's body is still queued, and the device reads the body's links and embeds and makes their edges once the server answers the edit. The device's status reports how many items the fill has brought so far and, where the instance counted them, how many the slice held when the fill began, so an app can show how far the fill has come. Compare those two figures, not the count of items the copy holds, which also includes pinned items and creates that are still queued. The Swift SDK returns these answers as `Rows` with a `completeness`.
 
 **A fill that stops partway resumes from the page it reached.** The device saves its place with each page, so a fill that was stopped, lost its connection or ended with the app keeps the items it has, and the next fill reads only the pages left. It then applies what changed on the instance while it was stopped, so the copy is as whole as one filled in a single run. The next fill **starts again from the first page** when resuming couldn't give a whole copy: the slice is different, another instance answers at the address, the credential reads other items, the instance's types changed, the event log no longer reaches back to where the fill began or ends before it, as after a restore, or the server refuses the page the device saved. The fill's report says whether it resumed, and if it started again, why. A fill that completed is never resumed: the next one reads every page.
 
@@ -31,7 +31,7 @@ On Apple platforms, the device keeps **each file it fetched out of backups**, in
 
 Sometimes a copy can't be brought up to date, and has to be filled again by a hydration. Its **queued writes survive** either way.
 
-**After the device was away longer than the instance keeps events, it fills the copy again in place.** This holds while the instance, the credential's reach and the slice are the ones the copy was built under. Until the hydration finishes, the device's status reports the copy's hydration as `stale`, and a list or search answers from the items the copy holds and marks the answer `stale`, because some may have changed or gone on the instance. A read by ID answers for an item the copy holds. Edge reads are refused `hydration_incomplete`. Writes are taken as during a first fill. A drain or a catch-up is refused `copy_expired` with the reason `catchup_too_old` until the hydration finishes. A follow started before the hydration is refused the same way, and one started while the hydration runs, or after it stopped part way, waits for it to finish. The hydration updates the items that changed and adds the new ones. Once it has read every page, it removes the items the instance no longer lists, except pinned items, items a queued write names, and the items at either end of an edge a queued write creates, moves or edits. A hydration that stops part way leaves the copy `stale`, removes nothing, and carries on in place when run again.
+**After the device was away longer than the instance keeps events, it fills the copy again in place.** This holds while the instance, the credential's reach and the slice are the ones the copy was built under. Until the hydration finishes, the device's status reports the copy's hydration as `stale`, and a list or search answers from the items the copy holds and marks the answer `stale`, because some may have changed or gone on the instance. A read by ID answers for an item the copy holds. Edge reads are refused `hydration_incomplete`, and so is a read of what changed since a cursor. Writes are taken as during a first fill. A drain or a catch-up is refused `copy_expired` with the reason `catchup_too_old` until the hydration finishes. A follow started before the hydration is refused the same way, and one started while the hydration runs, or after it stopped part way, waits for it to finish. The hydration updates the items that changed and adds the new ones. Once it has read every page, it removes the items the instance no longer lists, except pinned items, items a queued write names, and the items at either end of an edge a queued write creates, moves or edits. A hydration that stops part way leaves the copy `stale`, removes nothing, and carries on in place when run again.
 
 The hydration **empties the copy first** if the instance's event log now ends before the point the copy had reached, or before the point where a stopped hydration started, as it does on an instance restored from a backup, because the copy may hold versions the restored instance never had. It also does so if the hydration finds another instance at the address or a credential whose reach changed. The copy stops being `stale` at once, even if that hydration then fails, and it does the same when the instance refuses the hydration because the credential has ended or its reach changed, so it never answers rows the credential can no longer read. A hydration that fails for another reason, such as the instance being unavailable, leaves the copy `stale`.