# Working copy (/reference/swift-sdk/working-copy)

Open, fill, pin, catch up and close a working copy, give it a new key, and recover a store it refuses.



`WorkingCopy` is the copy an app keeps on the device. It lives in one SQLite store, holds a slice of the instance and queues every write. [Devices](/build/devices) explains the slice, hydration and the queue; this page lists the calls.

## Open a copy [#open-a-copy]

```swift
import Marfa

let store = URL.applicationSupportDirectory.appending(path: "marfa.sqlite")
let server = try Server(url: URL(string: "https://marfa.example.com")!, key: key)
let copy = try await WorkingCopy.open(store: store, server: server)
```

`WorkingCopy.open(store:server:fileBudget:ifRefused:)` opens the store at `store`, and makes it when absent. **It makes no request.** Through a symbolic link, its lock and files sit beside the target. A new copy reads and queues writes before its first hydration.

| Parameter | Default | What it does |
| - | - | - |
| `store` | | The store's file URL. |
| `server` | `nil` | The server to hydrate from, catch up from and drain to. Without one the copy is local only. |
| `fileBudget` | `nil` | The budget of the [file cache](/reference/swift-sdk/files#the-file-cache), set before the call returns. `nil` keeps what the store holds. |
| `ifRefused` | `.keep` | What to do with a store another build of the core made. `.replace` replaces it with an empty store **only when it holds no unsent write**. |

A replaced store keeps its downloaded files and file budget. It loses its pins, its position in the server's events and its declared types, so hydrate it as a new copy.

| `open` throws | When |
| - | - |
| `MarfaError.wrongSchema` | Another build of the core made the store. `unsent` counts the writes the server hasn't taken. See [A store the copy refuses](#a-store-the-copy-refuses). |
| `MarfaError.storeDamaged` | SQLite can't read the store. |
| `MarfaError.store` | The lock file can't be opened for writing, or the store can't use write-ahead mode. |
| `MarfaError.invalid` | The store's file system doesn't lock files, as on a network share or WebDAV. |
| `MarfaError.readingHandle` | A second opener passed a `fileBudget`, or `.replace` found another process writing the store. |
| `SignInError.notSignedIn` | `server` was made from a credential the keychain no longer holds. |

**A store made against another address opens and keeps its writes.** The first call that reaches the server asks which instance answers. If it is the instance the store was made against, the store follows it to the new address. Otherwise the call throws `wrongServer` and sends nothing.

## The writer and readers [#the-writer-and-readers]

`copy.handle` is `.writer` or `.reader`. **The first process to open a store is its writer;** a second opener of the same store gets a reader.

* **A reader writes nothing.** It opens the store read-only, records no renewed credential and no new address, and its `changes()` stream hears each of the writer's saves. **A new stream on a reader first hears one `.saved`,** so it misses no save made as it started.
* **A reader can still send requests** from a moved address of the same instance, and leaves recording the address to the writer.
* **`WorkingCopy.openReader(store:)`** opens a reader that never takes the writer role, so a helper process started first can't lock the app out. It throws `invalid` when no store exists at the path yet.

## The copy's parts [#the-copys-parts]

| Property | Type | Page |
| - | - | - |
| `items` | `Items` | [Items, edges and tables](/reference/swift-sdk/items), and saved views on [Views and folders](/reference/swift-sdk/views-and-folders) |
| `edges` | `Edges` | [Items, edges and tables](/reference/swift-sdk/items#edges) |
| `tags`, `metadata`, `extensions` | `Tags`, `Metadata`, `Extensions` | [Items, edges and tables](/reference/swift-sdk/items#tags-and-extensions) |
| `tables` | `Tables` | [Items, edges and tables](/reference/swift-sdk/items#tables) |
| `blobs` | `Blobs` | [Files](/reference/swift-sdk/files) |
| `queue` | `Queue` | [Queue and verdicts](/reference/swift-sdk/queue) |
| `catalog` | `Catalog` | [Sign-in and server calls](/reference/swift-sdk/server-calls#types-and-the-catalog) |

## Fill the copy [#fill-the-copy]

```swift
let report = try await copy.hydrate(types: ["*"], tier: .all, edgeTypes: ["in-collection"])
```

`hydrate(types:tier:edgeTypes:inPlaceOnly:)` replaces the copy with every item of `types` at `tier`, with their tags and the edges going out from them. Each edge type in `edgeTypes` is held whole.

* **`types`** names types or patterns. `["*"]` alone is every type except `system.*`. Beside `system.*` types it adds them; beside any other type it throws `invalid`.
* **`tier`** is `.library`, `.feed` or `.all`.
* **An interrupted hydration resumes** from the page it reached when its slice is unchanged. The report says `resumed`, or why it `restarted`.
* **Reads during a fill answer what has arrived,** marked `.partial`. A read of a view throws `hydrationIncomplete`. `status()` shows progress in `itemsListed` against `itemsExpected`.
* **The copy runs one hydration at a time.** A second call waits, and returns the first one's report when it filled the same slice under the same key.
* **The call tells every `changes()` stream** `.refreshed(.hydrated)` when it completes, and `.refreshed(.unfinished)` when it fails or is canceled.

A copy whose cursor the server's event log let go has `status().hydration` of `.stale`. **Hydrating a stale copy refills it in place:** reads answer the rows it holds, marked `.stale`, and the report says `inPlace`. Until the refill completes, item writes are queued and edge writes throw `hydrationIncomplete`.

**`inPlaceOnly: true` refills or does nothing.** It never removes a row, an edge or a file, and throws before it changes anything when the hydration would clear the copy:

| Error | Reason | Why |
| - | - | - |
| `instanceChanged` | | The copy was built from another instance. |
| `copyExpired` | `not_stale` | The copy isn't stale. |
| `copyExpired` | `reach_changed` | The key or sign-in reaches other items. |
| `copyExpired` | `slice_changed` | The types, tier or edge types differ. |
| `copyExpired` | `head_past_log` | The server was restored behind the copy. |

Use it to ask whether to hydrate afresh or keep the copy stale. A server that refuses the credential or the reach of a stale copy ends it all the same: `.stale` is a copy kept, `.expired` a copy ended.

### The hydration report [#the-hydration-report]

| Field | Holds |
| - | - |
| `types`, `tier`, `edgeTypes` | The slice filled. |
| `items`, `edges` | What the copy holds now. |
| `pages`, `pagesTotal` | Pages read. |
| `resumed`, `restarted` | Whether it carried on, or why it started again. |
| `inPlace` | Whether it refilled a stale copy. |
| `cursor` | The position in the server's events it reached. |
| `registeredTypes`, `replacedTypes` | Declared types the instance lacked and now holds, or held at an older version. |
| `unregisteredTypes`, `unreplacedTypes` | Declared types the instance refused, each with `id`, `code` and `message`. |

## Declare types [#declare-types]

`declareTypes(_:)` replaces the app's declared types, each a type definition as a `JSONObject`. **Offline creates are checked against them before the first hydration,** and a hydration registers any the instance lacks. `declaredTypes()` reads them back with the empty `fields` and the `version` a registration needs. [Define a type](/build/define-a-type) shows a definition.

## Pin an item [#pin-an-item]

`pin(_:)` reads and holds one item whatever the slice says, and returns a `PinReport` with `pinned` and `wasPinned`. An item in the bin throws `notFound` with the code `trashed`; one the server doesn't hold throws `notFound` with `not_found`. `unpin(_:)` lets the item go unless queued writes still need it.

## Catch up [#catch-up]

`catchUp()` reads the type catalog again, then applies every event since the last hydration or catch-up. A held `changes()` stream does this by itself. It waits for a hydration that is running.

| `CatchUpReport` field | Holds |
| - | - |
| `applied` | Events applied. |
| `skipped` | Events the copy had no use for. |
| `cursor` | The position it reached. |
| `catalogChanged` | Whether the type catalog changed. |
| `readOnlyHeld` | **Rows whose `readOnly` changed.** No event brings these, and `applied` doesn't count them. |
| `changedTables` | Each held table it filled or changed, as `itemId` and `table`. |

**Every item carries `readOnly`:** whether a person's connector holds it read only, as the server last answered. It is advice for showing an item as not editable. **Neither the copy nor the server refuses a write for it.** The copy asks again at most every 15 minutes, and a change to the connector sends no event, so the value can be older. An item the server hasn't answered yet holds `false`.

## Status [#status]

`status()` returns a `Status`:

| Field | Holds |
| - | - |
| `serverOrigin`, `instanceId` | The server and instance the copy follows. |
| `sliceTypes`, `sliceTier`, `sliceEdgeTypes` | The slice. |
| `pinned` | Pinned item IDs. |
| `hydration` | `.never`, `.inProgress`, `.complete`, `.stale` or `.expired`. |
| `items`, `edges` | Rows held. |
| `itemsListed`, `itemsExpected` | A running hydration's progress; `itemsExpected` is `nil` where the server didn't count. |
| `eventCursor`, `catalogVersion` | Where the copy is in the server's events and its catalog. |
| `fileCache` | The [file cache](/reference/swift-sdk/files#the-file-cache). |
| `lastSynced` | When the copy last finished a pull without error, by the device's clock. |

## Search [#search]

`search(_:filters:limit:)` searches indexed fields and tags, best match first, and returns `Rows<SearchHit>`, each hit with `item`, `score` and `snippet`. `limit` defaults to 20. `SearchFilters` takes `types`, `states`, `allStates`, `tier`, `tags`, `occurredAfter`, `occurredBefore`, `filter` and `beneath`.

## Give the copy a new key [#give-the-copy-a-new-key]

`use(_:)` gives an open copy a new sign-in or key for the same server. The store reopens with the new token, and queued writes remain.

* **Call it after `signedOut` or `.keyRefused`,** even with the same credential.
* **During the change, every call throws `keyChanging`:** ask again. It waits for the slowest running call first.
* **A new reach shows as `.needsHydration`** on [`updates()`](/reference/swift-sdk/updates#copy-updates). Hydrate again.
* **Held `changes()` streams keep going,** and a follow the old key stopped starts again.

It throws `noServer` for a copy opened without a server, `wrongServer` for a server at another address, `SignInError.notSignedIn` for a credential the keychain no longer holds, and `closed`. In each, nothing changes.

## Close [#close]

`close()` releases the store once running calls finish. **A call made after it begins throws `closed` at once,** on the copy or its parts, and the last update on [`updates()`](/reference/swift-sdk/updates#copy-updates) is `.closed`. Closing twice does nothing.

## A store the copy refuses [#a-store-the-copy-refuses]

These static calls work on a store that is closed in this process. Each throws `readingHandle` while another process writes the store.

| Call | What it does |
| - | - |
| `WorkingCopy.check(store:)` | Reads every page and checks each index, changing nothing. Throws `storeDamaged` or `wrongSchema`. |
| `WorkingCopy.unsentWrites(in:)` | Lists the writes the server hasn't taken, from a damaged, refused or whole store, as `UnsentWrites`. |
| `WorkingCopy.remove(store:confirming:)` | Removes the store, its log, its fetched files and its lock, **losing exactly the writes it was shown**. |
| `WorkingCopy.setAsideDamaged(store:)` | Moves a damaged store to `<store>.damaged-<n>` and makes a new one carrying every write it could read. |
| `WorkingCopy.removeLosingAll(store:)` | Removes a damaged store, losing every unsent write, read or not. |

**A removal names what it loses.** Show the person `unsentWrites(in:)`, each `UnsentWrite` with `id`, `kind`, `itemId`, `body` and `verdict`, then pass the answer to `remove(store:confirming:)`. If its writes changed since, it throws `unsentDiffers` and removes nothing: read and ask again. It throws `invalid` for a folder's store. A reader doesn't stop a removal and shows the old copy until it reopens.

```swift
let unsent = try await WorkingCopy.unsentWrites(in: store)
// Show unsent.writes and ask the person.
try await WorkingCopy.remove(store: store, confirming: unsent)
```

**`setAsideDamaged(store:)` deletes nothing.** The new store holds no rows, so hydrate it, then drain to send what it carries. It throws `invalid` for a store that opens as it is or a folder's store, and a set-aside that stopped part way finishes when called again. Its `SetAside` answer:

| Field | Holds |
| - | - |
| `setAside` | Where the damaged store now is. |
| `carried` | Writes the new store carries. |
| `unread`, `unreadIds` | Writes that couldn't be read, and the IDs that could. |
| `whole` | Whether the old queue was read whole. Where not, the cache keeps every file until the old store is removed. |
| `held` | Carried writes blocked `instanceChanged`, because the old store didn't say its instance. |
| `recordUnread` | Carried writes blocked `recordUnread`, because a record that decides how each is sent couldn't be read. |

[Release](/reference/swift-sdk/queue#clear-a-stopped-write) a held write to send it. The rules are in the contract's [stores](https://github.com/withmarfa/marfa/blob/main/conformance/spec/stores.md) chapter, and [A working copy that can't catch up](/build/fix-a-working-copy) covers what a person sees.
