Working copies

How a device keeps a copy of part of an instance, reads it without a connection, and has the writes it queued judged by the instance when it reconnects.

A device is a program that keeps a working copy of part of an instance on the machine it runs on. It reads from that copy, and sends its writes from a queue when it can reach the server. An app built on the Swift SDK, the CLI's marfa device and a synced folder are devices. A device syncs only with the instance, the source of truth.

The working copy

A device chooses the slice it keeps: the types, tier and edge types it holds, and can pin an item to keep it regardless. The copy is one file, the store. A file system that can't lock files is refused invalid.

A hydration fills the copy with the slice, and the event stream then keeps it current:

Terminal
marfa device --db reading.db hydrate --type app.example.expense --tier library
marfa device --db reading.db catch-up
hydrated 2 item(s) and 0 edge(s) of app.example.expense at library in 1 page(s); cursor 7
applied 0 event(s), skipped 0; cursor 7

Reads need no connection. While the copy fills, it marks a list or search partial, and refuses an edge read or a read of an item that hasn't arrived, hydration_incomplete. A device holds a table only when an app asks, and keeps fetched files within a file budget (Keep files on a device).

When the copy falls behind

  • A copy away longer than the instance keeps events is stale: its reads say so until a hydration refills it.
  • A copy that finds another instance at the address, or a changed credential reach, has expired. It refuses reads and writes until a hydration, which empties the copy and keeps the queue and pins. After another instance, each waiting write is held blocked: instance_changed until an app releases or withdraws it.
  • A server put back to an earlier point expires the copy too. The next hydration queues, blocked server_restored, the work the copy held that the server lost (Restore a copy of the data directory).
  • A store made by a build of the core with another schema won't open. The refusal names the release that last saved it, the only build that can send the writes it holds.

Fix a working copy that can't catch up says what to run for each message.

A write made offline

A write shows in the copy at once and waits in the queue with the version it was based on, and survives the app being killed. A drain sends the queue in order, and the instance recognizes a retry, so none applies twice. A device sends every item update with conflict=auto, so the instance settles most collisions (Versions). Each answered write gets a verdict.

Verdicts

VerdictWhat happened
acceptedThe instance applied the write.
mergedIt collided, and the merge rule settled it.
conflictedIt collided. For an item, its value went into a conflicted copy.
refusedThe instance refused it. The content is kept to offer back.
blockedSomething must change before it can go.
deadIt failed five times, not counting network or server trouble.

The other four need an app's attention: the queue's verdicts say what to do.

The rules are in the contract's device, queue and verdicts and folder sync chapters.

On this page