[aicayzer]

Summary

The Swift SDK page now covers the batch reads and following changes with a cursor, which withmarfa/marfa-swift#389 adds: items.get(_:includingBin:) for many IDs, edges.get(_:) for one ID or many, items.links(in:) for many items, and changes(since:most:). The devices page now says how a read of many items and a read of changes behave during a fill. Merge this once withmarfa/marfa-swift#389 is released.

Changes

• /swift-sdk:
  • The reads tables and the list of calls refused with hydrationIncomplete include the new calls.
  • A new subsection, "Reread only what changed", under "Follow changes", with a Swift example. It covers when the answer is .everything, what ChangedRows holds, why a name can change nothing on screen, when to read body links again, keeping the cursor through a refusal, and keeping a cursor across launches. The ChangedRows bullet and the example's comment say that an ID a reread leaves out has gone to the bin only when the reread isn't .partial, since a hydration started after changes(since:) answered can leave an item not yet arrived.
  • The .refreshed and .saved row links to the new subsection.
  • The fake's supported and unsupported calls include the new reads.
  • The unreadableProperties bullet says which stored properties read as unreadable: those that aren't JSON, aren't an object, or nest more than 64 levels deep, counting the properties object.
• /devices: a read of many items by ID answers those that have arrived and marks the answer partial, and a read of what changed since a cursor is refused until the copy is whole.

Testing

• pnpm test: 39 files and 709 tests passed, including the content lint, after the review fixes.
• The depth rule was checked against split_properties and MAX_JSON_DEPTH in the core and against the Swift package's reader, which both count the properties object as level 1.
• Every rule on the page was checked against Core::changes_since and refuse_unless_usable in withmarfa/marfa (core at 2b09fc8, the merge of perf(core): pack a Swift listing's items into one buffer marfa#2475, which marfa-swift#389 now pins) and against the Swift package's public API.
• CI's build and type-check passed on the latest commit.
• Not tested: the rendered page.

Notes for reviewers

• Draft pull requests docs(devices): describe fills only in place and writes held for another instance #632 (devices) and docs: cover the MCP server, plugin and operations since v0.0.45 #687 (swift-sdk) touch the same pages; whichever merges second resolves a small conflict.
• Review depth: standard, as a check of each rule against the core.

Checklist

• The title is a scoped Conventional Commit.
• New behavior has a test that was seen failing first, or no test was needed and the reason is above.
• Docs, comments and the contract still say what is true after this change.

[aicayzer]

Review: ready to merge

Summary. Documents the Swift package's batch reads, batched body links and reads of what changed since a cursor; every name, signature and behaviour matches the package and the contract.

First draft: 4/5. Nothing blocking; two sentences that would have misled a reader were corrected by the reviewer.

Checked.

• True: items.get(_:includingBin:), edges.get, items.links(in:), changes(since:most:), ChangedRows and ChangeCursor against marfa-swift at de2b7b1, and the device/bulk-get-*, device/edge-get, device/bulk-links-* and device/changed-* statements, including the stated limit on links that resolve differently only because another item changed.
• Neighbours: the devices overview, the read-while-filling list, the throws list and the fake's sections.

Quick fixes. 2 applied by the reviewer: a stale copy also refuses a read of what changed (device/changed-partial-refused), and an item left out of a reread may have been removed, not only binned.

---

Reviewed by withmarfa-reviewer on Claude Sonnet 5.5. This review may contain mistakes.