[aicayzer]

Summary

The Swift SDK now refills a stale working copy by itself while the app holds a changes() stream, so a copy keeps following after a device sleeps or is offline for longer than the instance keeps events (withmarfa/marfa-swift#371). This updates the Swift SDK page and the troubleshooting guide to say so, including when the SDK leaves the refill to the app and how the app's own hydrate waits for a refill. Merge after the Swift SDK release that includes withmarfa/marfa-swift#371.

Changes

• Swift SDK page, "Refill a stale copy": a held stream refills a stale copy over its slice when the follow finds the cursor aged out, and announces .refreshed(.hydrated); failed attempts announce .refreshed(.unfinished) and are retried further apart, up to five minutes. The streams are told .stopped(.copyExpired) instead when another instance answers (instance_changed) or the copy was already stale as the follow started (catchup_too_old), and a refused refill stops them with its error. A copy runs one hydration at a time: an app's hydrate waits for a running refill and returns its report when the refill already filled the same slice, and an app's catchUp waits for it and then catches up from the cursor the refill left. The refill section says the copy refills itself only when it expects the refill to be in place.
• Swift SDK page, "Follow changes": on a .copyExpired stop, read status().hydration; a .stale copy is filled again in place by hydrating the same slice, and any other expired copy is filled from scratch.
• Troubleshooting, the CLI's copy_expired entry: points an app on the Swift SDK to the refill section.

Testing

pnpm exec vitest run src/lib/content-lint.test.ts: 47 tests pass. Each statement was checked against the code in withmarfa/marfa-swift#371 (Feed.refill(), Feed.hydrate, Feed.catchUp, and the changes(), hydrate and catchUp documentation) and its tests. The site was not built locally.

Notes for reviewers

The CLI and the HTTP event stream are unchanged: the CLI still needs marfa device hydrate after catchup_too_old. Review depth: a prose check against the linked pull request.

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]

Replaced by #633, which carries this change merged with the other Swift SDK 0.0.32 pull requests into one page.