# Queue and verdicts (/reference/swift-sdk/queue)

Send a working copy's queued writes, read the instance's answer to each, and clear a write that stopped.



Every write a working copy makes waits in its queue, **kept across launches**, until a drain sends it. The server's answer to each write is its **verdict**. `copy.queue` reads and clears the queue. [Write in a working copy](/build/write-in-a-working-copy) explains when to drain and what to show.

## Drain [#drain]

`queue.drain()` sends what the queue holds once, in order, and records each verdict. It returns a `DrainReport`.

**Nothing drains on its own unless the app holds a stream:**

* A held `changes()` stream drains once when the server is back, and again after a drain left a write undelivered.
* A held `updates()` sequence drains again while the copy follows, after a drain left a write undelivered.

| `DrainReport` field | Holds |
| - | - |
| `answered` | Writes the server answered, whatever the answer. |
| `held` | Writes the pass held back. |
| `undelivered` | Writes that couldn't reach the server. They wait for the next drain. |
| `unsent` | Writes settled without a request. |
| `unmade` | Requests that couldn't be made, counted against their write. |
| `unavailable` | Why the drain ended before the queue was through. |
| `stopped` | The credential refusal that parked the queue. |
| `retryAfterSeconds` | The longest wait a rate limit asked for in the pass. |
| `verdicts` | A `DrainVerdict` for each write attempted or settled. |
| `unclaimedSources` | Sources the writes named that the key hasn't claimed, so a `credentialRefused` isn't read as a key that stopped working. |

A `DrainVerdict` has `id`, `kind`, `itemId` (an edge write's from end), `edgeId`, `verdict`, `refusals`, and `replayed`, which says the server answered from its record of the idempotency key rather than writing again.

## Read the queue [#read-the-queue]

`queue.all()` lists every queued write as a `QueuedWrite`:

| Field | Holds |
| - | - |
| `id`, `kind` | The write and its `WriteKind`, such as `createItem`, `replaceTags`, `uploadBlob` or `writeRows`. |
| `itemId`, `toId`, `edgeId` | The row written. For an edge write, `itemId` is the from end and `toId` the to end. |
| `namespace`, `tag`, `blob` | An extension's namespace, a tag, or an upload's hash. |
| `baseVersion`, `idempotencyKey` | The version written over, and the key minted when it was queued. |
| `dependsOn` | The writes this one can't go without, and is refused with. |
| `follows` | The write ahead of it to the same row, which it goes after. |
| `verdict` | **`nil` until the server answers.** |
| `waiting` | Held behind a write named in `dependsOn` or `follows` that has no answer. It goes once that one is answered. |
| `body`, `answer` | What the write sends, and the server's whole answer. |
| `refusals`, `environmentalStreak`, `lastFailure` | Refusals counted, drains in a row that met a failure that was no answer, and the last such failure's `status` and `text`. |
| `queuedAt`, `answeredAt` | When it was queued and answered. |

## Verdicts [#verdicts]

| `Verdict` | Means |
| - | - |
| `.accepted` | Written as sent. |
| `.merged(fields:)` | **Applied over changes made since,** field by field. |
| `.conflicted(siblingId:fields:conflicts:)` | The server kept its own value. An item's losing value went to the sibling `siblingId`. A table write names the cells it replaced in `conflicts`, each a `RowConflict` with `row` and `column`. |
| `.refused(Refusal)` | The server refused it. It is never sent again. |
| `.blocked(reason:refusal:)` | **Stopped until something outside the queue changes.** |
| `.dead` | Refused five times. Never sent again unless released. |

An accepted, merged or conflicted write is never sent again. [Conflicts](/use/conflicts) explains what a person sees.

### Refusals [#refusals]

| `Refusal` field | Holds |
| - | - |
| `reason` | The server's code, or a sentence naming the refused write this one waited on. |
| `code`, `message` | The server's code and message. |
| `fields` | Each property refused, as `field` and `message`. |
| `trashed` | **The row is in the bin and can be restored.** |
| `grant` | The permission the key lacks: `kind` (`.type`, `.edgeType` or `.extension`), `name` and `level` (`.read` or `.write`). |
| `requestLimit` | The write's `size` and the server's `limit` in bytes. |

**A write larger than the server's request limit is never sent.** The copy refuses it unsent with the code `over_request_limit` and both numbers in `requestLimit`, so the app can say how much to remove. The limit is the instance's `max_request_bytes`.

For example, a write to an item another device moved to the bin is refused with `reason` and `code` `item_not_found` and `trashed` set.

### Blocked writes [#blocked-writes]

| `BlockedReason` | Means | Clears |
| - | - | - |
| `.credentialRefused` | The server refused the key. | **By itself:** the next drain sends it again. |
| `.keySpent` | The server answered `422 idempotency_contract_changed`: the key went with another request. | Release, which sends it under a fresh key. |
| `.ancestorUnavailable` | The server answered `409 ancestor_unavailable`. | Release or withdraw. |
| `.conflictUnresolved` | The server answered `409 version_conflict`. A tag replace gets it when another writer changed the tags since the copy read them, and the copy keeps the person's tags. | Release, which sends a tag replace with no `read_tags`, so the tags become the copy's, or withdraw. |
| `.failingAlone` | **Set aside:** it keeps meeting a failure that is no answer while other writes go. `lastFailure` says what. | Release or withdraw. |
| `.instanceChanged` | Queued against an instance other than the one the copy is built from now. | Release, which sends it to the instance there, or withdraw. |
| `.recordUnread` | Carried from a store set aside where the record deciding how it is sent couldn't be read. | Release or withdraw. |
| `.serverRestored` | Queued to put back what the server lost when it was restored to an earlier point, and never sent. | Release, which keeps its key, or withdraw. |

A write held behind another isn't blocked: it has no verdict, and `waiting` is set.

## Clear a stopped write [#clear-a-stopped-write]

| Call | Does |
| - | - |
| `queue.release(_ id)` | Queues a blocked or dead write for the next drain, under its idempotency key unless it was blocked `keySpent`, `conflictUnresolved` or `ancestorUnavailable`, which get a fresh one. A row write goes with its whole batch. Returns whether it released one. |
| `queue.release(reason:)` | Releases every write blocked for one reason, and returns how many. |
| `queue.withdraw(_ id)` | **Takes a write that can never be sent out of the queue** and puts its row back as the server holds it. |
| `queue.discard(_ id)` | Takes a refused write, and the content it carried, out of the queue. |
| `queue.forgetAnswered()` | Clears answered writes, and returns how many. |
| `queue.forgetAnswered(ids:)` | Clears only the named answered writes. |
| `queue.takeAnswered()` | Clears what `forgetAnswered()` clears and returns each write, in one step. |

`withdraw` takes only a dead write or one blocked `ancestorUnavailable`, `conflictUnresolved`, `failingAlone`, `instanceChanged`, `recordUnread` or `serverRestored`. **It returns the ID of every write it took**, more than one where the write belonged to a batch, and an empty list for any other write. It reads the row from the server first, so it needs the server, and answers an empty list when the copy moved during the read: ask again. Writes waiting on it are refused unsent.

`discard` returns `false` for a write that isn't refused or that a waiting write depends on, and throws `notFound` for an ID the queue doesn't hold.

**The clearing calls keep what a person made:**

* A refused write that carried content stays, with its `body` readable, until `discard`.
* Blocked and dead writes stay until released or withdrawn.
* An answered write that a waiting write depends on stays.

Use `takeAnswered()` to act on answers: two callers never both get one answer, and none is cleared unread. Each clearing call tells held streams `.refreshed(.forgotten)` when it cleared something.

The rules are in the contract's [queue and verdicts](https://github.com/withmarfa/marfa/blob/main/conformance/spec/queue-and-verdicts.md) chapter.
