[aicayzer]

Summary

Describes two changes to working copies from withmarfa/marfa#2402. A hydration can be asked to fill a stale copy only in place, and it's refused copy_expired with a reason, changing nothing, where it can't be. If the instance itself refuses the credential or its reach during such a fill, the stale copy still ends, keeping its queued writes, and the copy's hydration state (stale or expired) tells the two apart. Writes queued against one instance are held blocked with the reason instance_changed once the copy is built from another instance, until they're released or withdrawn.

Part of withmarfa/marfa#2399.

Changes

• Devices: a paragraph and a reason table for a fill asked to happen only in place, and a paragraph on writes queued against another instance. The blocked reasons are now seven, with a row for instance_changed.
• Devices: a paragraph saying a fill only in place still ends the stale copy when the instance refuses the credential or its reach, and that an app reads the hydration state before offering to keep the copy, since both refusals can carry reach_changed.
• Troubleshooting: the copy_expired entry covers instance_changed, the writes it holds and --in-place-only, and now says marfa device status shows stale after a refused fill and expired after the instance refuses the credential or its reach. A new entry covers the not_stale message.

Testing

• Second round: rebased onto main (no conflicts). pnpm test passes (708 tests) but for src/lib/command-check.test.ts, which now flags four uses of --in-place-only, as expected before the sync. Checked the new wording against device/refill-in-place-only-keeps, device/refill-in-place-only-server-ends and device/stale-ends-refused in feat(core): refill a working copy only in place, and hold writes queued against another instance marfa#2402.
• First round: rebased onto main. The rebase met one conflict in devices.mdx, beside the wrong_schema paragraph that main had changed; it keeps main's wording of that paragraph and adds the new paragraphs before it.
• Ran pnpm exec vitest run src/lib/content-lint.test.ts src/lib/command-check.test.ts. The content lint passes. The command check fails only on the uses of --in-place-only, as expected before the sync.
• Checked each claim against the contract statements, the core and the CLI's copy_expired messages in feat(core): refill a working copy only in place, and hold writes queued against another instance marfa#2402, and against a run on two real servers.
• Not tested: a full pnpm build.

Notes for reviewers

• CI's command check fails until a Marfa release that carries feat(core): refill a working copy only in place, and hold writes queued against another instance marfa#2402 is synced. src/lib/command-check.test.ts doesn't yet know marfa device hydrate --in-place-only, because the command tree comes from the sync. The glossary's count of blocked reasons also arrives with that sync.
• The Swift SDK page isn't changed, because the SDK doesn't yet expose the option or the new blocked reason. That page changes with the Swift package.
• Merge after the marfa change is released and synced.

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]

Parked as a draft with its code change, withmarfa/marfa#2402, until withmarfa/marfa#2405 is decided. Merge the two together, or close both if #2405 goes the other way.