# `Reason`

> Contract 2.0.0 · package sha256 `a857eca95b35921109faf997094bb4192f12527d9d0fcd4be7e97f06425bad6e` · generated from `configurator-runtime.d.ts` by `services/onsite-scripter/scripts/build-contract-docs.mjs`; edit the source, not this file.

Type · `import type { Reason } from '@holostep-configurators/runtime-client/contract';` · stable · since 2.0.0 · section 2. Operations, reports, causes, problems

Why an operation did not commit.
- 'conflict': `expectRevision` did not match, the `expectGroup` you passed was not open at the
  call, an [`applyPatch`](Writer.applyPatch.md) 'test' failed, or a queued [`applyPatch`](Writer.applyPatch.md) path or [`select`](Writer.select.md) group or
  material that resolved at the call no longer resolves at the write's turn (spec section 6.4).
- 'busy': `expectRevision` was given while a transaction was open or queued ahead of the write,
  or a recorded write was pending ahead of it in the write queue (pending look-only writes such
  as [`apply`](Writer.apply.md), and dry runs, open or queued, don't count).
- 'timeout': `timeoutMs` passed without progress, or the hold cap was reached.
- 'enlisted-failed': an operation started through the `tx` failed and `work` never observed it.
- 'empty': undo or redo had nothing to do.
- 'no-candidate', 'occupied', 'rejected', 'not-loaded': an attach that changed nothing (spec
  section 6.12, rule A2).
- 'internal-error': applying a state write, recorded or look-only, through `session` or a `tx`,
  failed inside the runtime before its commit point; that write, or the transaction holding it,
  rolled back and lists 'sync-failed' in `problems` (spec section 6.4).
- 'disposed': a new write through a disposed collection or naming one as its `owner`, or
  through a part that reads `exists: false` (never a [`node()`](Writer.node.md) handle); nothing ran, `matched`
  is 0 without 'target-unmatched', and `problems` holds 'handle-disposed' (spec section 3.4).

## Reasons

| Code | Summary |
| --- | --- |
| [`'conflict'`](../reasons/conflict.md) | `expectRevision` did not match, the `expectGroup` you passed was not open at the call, an [`applyPatch`](Writer.applyPatch.md) 'test' failed, or a queued [`applyPatch`](Writer.applyPatch.md) path or [`select`](Writer.select.md) group or material that resolved at the call no longer resolves at the write's turn (spec section 6.4). |
| [`'busy'`](../reasons/busy.md) | `expectRevision` was given while a transaction was open or queued ahead of the write, or a recorded write was pending ahead of it in the write queue (pending look-only writes such as [`apply`](Writer.apply.md), and dry runs, open or queued, don't count). |
| [`'timeout'`](../reasons/timeout.md) | `timeoutMs` passed without progress, or the hold cap was reached. |
| [`'enlisted-failed'`](../reasons/enlisted-failed.md) | an operation started through the `tx` failed and `work` never observed it. |
| [`'empty'`](../reasons/empty.md) | undo or redo had nothing to do. |
| [`'no-candidate'`](../reasons/no-candidate.md) | an attach that changed nothing (spec section 6.12, rule A2). |
| [`'occupied'`](../reasons/occupied.md) | an attach that changed nothing (spec section 6.12, rule A2). |
| [`'rejected'`](../reasons/rejected.md) | an attach that changed nothing (spec section 6.12, rule A2). |
| [`'not-loaded'`](../reasons/not-loaded.md) | an attach that changed nothing (spec section 6.12, rule A2). |
| [`'internal-error'`](../reasons/internal-error.md) | applying a state write, recorded or look-only, through `session` or a `tx`, failed inside the runtime before its commit point; that write, or the transaction holding it, rolled back and lists 'sync-failed' in `problems` (spec section 6.4). |
| [`'disposed'`](../reasons/disposed.md) | a new write through a disposed collection or naming one as its `owner`, or through a part that reads `exists: false` (never a [`node()`](Writer.node.md) handle); nothing ran, `matched` is 0 without 'target-unmatched', and `problems` holds 'handle-disposed' (spec section 3.4). |

The set is open: a code newer than your declared contract arrives as `'other'`.

## Declaration

```ts
export type Reason = 'conflict' | 'busy' | 'timeout' | 'enlisted-failed' | 'empty' | 'no-candidate' | 'occupied' | 'rejected' | 'not-loaded' | 'internal-error' | 'disposed' | 'other';
```

## Generic-API test (spec 3.1)

| Rule | Result |
| --- | --- |
| 1. Neutral name | pass: `Reason` names no product |
| 2. A precedent | not recorded: no ledger row (coverage.json) names this member or its owner |
| 3. Two apps, or labs | not recorded: no ledger row names this member or its owner |
| 4. The cheaper fix first | not recorded per member (Appendix B decides it per need) |