# Devices (/build/devices)

How an app keeps a copy of someone's data on a phone or a Mac, works without a connection, and sends its changes when it can.



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](/reference/swift-sdk) is a device, and so is the [CLI](/reference/cli)'s `marfa device`. A device syncs only with the instance, the [source of truth](/build/architecture#the-instance), never with another device.

## The working copy [#the-working-copy]

A device chooses the **slice** it keeps: the types, tier and edge types it holds. `*` alone holds every type except `system.*`. It can also **pin** an item to keep it whatever the slice says.

The copy is one file, the **store**, on a file system that locks files: one on a network share or WebDAV is refused `invalid`. Reached through a symbolic link, its lock and files sit beside the file the link leads to.

The device fills its copy once, by a **hydration** that reads every item in the slice, then keeps it current from the [event stream](/build/events):

```bash
marfa device --db reading.db hydrate --type core.bookmark --tier library
marfa device --db reading.db catch-up
```

Output:

```text
hydrated 1 item(s) and 0 edge(s) of core.bookmark at library in 1 page(s); cursor 32
applied 0 event(s), skipped 0; cursor 32
```

**A sign-in that expires during a long read is renewed,** and the read goes on from its last event. Only a key or an ended sign-in ends it `credential_ended`.

Reads need no connection, [saved views](/build/read-a-view#read-a-view-from-a-working-copy) included. **While the copy fills, it answers from what has arrived**, marking a list or a search `partial`. An edge read or write, and a read or write of an item that hasn't arrived, are refused `hydration_incomplete`.

Other processes can read the copy while one writes: see [the writer and readers](/reference/swift-sdk/working-copy#the-writer-and-readers).

### Tables and files [#tables-and-files]

**A device holds a [table](/build/tables) only when an app asks**, so a phone can hold a step counter without ten years of its readings. A table too large to hold is read from the server, by the [table rules](https://github.com/withmarfa/marfa/blob/main/conformance/spec/device.md#tables-a-device-holds).

A device keeps fetched files within a **file budget**, dropping the least recently read: see [Keep files on a device](/build/keep-files-on-a-device).

## When the copy falls behind [#when-the-copy-falls-behind]

A copy sometimes needs filling again, and its **queued writes wait**.

* **After a device was away longer than the instance keeps events**, its copy is `stale`: it answers reads marked `stale`, and refuses edge reads, until a hydration refills it in place.
* **When another instance answers at the address, or the credential's reach changed**, the copy has expired. The device confirms its instance before each call that sends what the copy holds. The copy refuses reads and writes until a hydration, which empties it first.
* **When the server was put back to an earlier point,** as from a disk snapshot, it expires too. The next hydration queues what the server lost, blocked `server_restored`, as [Restore a copy of the data directory](/run/restore-the-data-directory#settle-the-work-each-device-kept) shows.

[Fix a working copy that can't catch up](/build/fix-a-working-copy) says what to run for each message.

## A write made offline [#a-write-made-offline]

A write made offline shows in the copy at once, and waits in the queue with the version it was based on. **A queued write survives the app being killed.** On Linux it also survives a power cut; on a Mac, iPhone or iPad, a power cut can lose the last writes, but the store stays whole. Sending the queue is a **drain**. A drain sends them in order, or leaves them queued while it can't reach the server, and the instance recognizes a retry, so none applies twice. Each answered write gets a verdict, and the copy takes what the instance now holds.

A device sends every update with `conflict=auto`, so the instance settles most collisions, as [Versions](/build/versions#when-two-apps-write-the-same-item) explains.

## Verdicts [#verdicts]

Each settled write gets one of six verdicts:

| Verdict | What happened |
| - | - |
| `accepted` | The instance applied the write. |
| `merged` | The write collided with a change to the same field, and the type's merge rule settled it. |
| `conflicted` | The write collided, and the type's merge rule put its value in a conflicted copy. |
| `refused` | The instance refused the write, whose content is kept to offer back. |
| `blocked` | Something must change before the write can go. |
| `dead` | The write failed five times, not counting network or server trouble. |

Only the last three need an **app's attention**: [blocked writes](/reference/swift-sdk/queue#blocked-writes) lists how each reason a write is `blocked` clears.

A **release** resends the write under its idempotency key, so the instance answers an attempt that may have applied from its record. Only a write blocked `key_spent`, `conflict_unresolved` or `ancestor_unavailable` gets a fresh key, because the old one applied none of it. A **withdrawal** removes it and resets the copy to what the instance holds.

A working copy can also be **a folder** of files: see [Sync a folder](/use/sync-a-folder).

The rules behind this page are in the [device](https://github.com/withmarfa/marfa/blob/main/conformance/spec/device.md), [queue and verdicts](https://github.com/withmarfa/marfa/blob/main/conformance/spec/queue-and-verdicts.md) and [folder sync](https://github.com/withmarfa/marfa/blob/main/conformance/spec/folder-sync.md) chapters of the contract.
