# Preview branch promotion

Source: https://stratadb.org/docs/reference/branch/preview

Preview promoting one branch into another, reporting conflicts without mutating either branch.

| | |
|---|---|
| Command | `branch.preview` |
| CLI | `strata branch preview` |
| Wire type | `branch_preview` |
| Python | `db.branches.preview(source: 'str', target: 'str', *, strategy: 'Any' = 'strict') -> 'Any'` |
| Access | read |
| Commit | no commit |
| Wire status | stable |

Previews promoting the `source` branch into the `target` branch: it derives the
branch point from the recorded fork lineage, runs a three-way comparison, and
reports the conflicts a promotion would hit - entries both branches changed
differently since the branch point. Preview is read-only: it mutates neither
branch.

Each conflict reports what the selected `strategy` would do - `strict` refuses
(`refused`), `source_wins` overwrites the target with the source value. A preview
with no conflicts is clean and a promotion under `strict` would apply. Preview
covers the capabilities a promotion applies - key-value, JSON, and vectors;
events and graphs are diff-only and never appear as promotion conflicts.
Branches with no shared fork lineage are rejected with
`invalid_argument.engine.branch_point`.

Status commands return a scalar or compact status payload and do not mutate database state.

## Examples

Preview promoting a fork into the branch it came from.

### CLI

```console
$ strata kv put config base
$ strata branch fork default experiment
$ strata command run --command-json '{"branch":"experiment","key":"Y29uZmln","type":"kv_put","value":"dHVuZWQ="}'  # change on the fork
$ strata branch preview experiment default --strategy strict  # a clean preview - no conflicting changes on default
```

### Wire

```json
{"key":"Y29uZmln","type":"kv_put","value":"YmFzZQ=="}
{"branch":"experiment","source":"default","type":"branch_fork_current"}
{"branch":"experiment","key":"Y29uZmln","type":"kv_put","value":"dHVuZWQ="}
{"source":"experiment","strategy":"strict","target":"default","type":"branch_preview"}
```

### Python

```python
_ = db.kv.put("config", "base")
_ = db.branches.fork("default", "experiment")
_ = db.at(branch="experiment").kv.put("config", "tuned")  # change on the fork
_ = db.branches.preview("experiment", "default", strategy="strict")  # a clean preview - no conflicting changes on default
```

## Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `source` | `string` | yes | The branch whose changes would be promoted. |
| `strategy` | `PromotionStrategy` | no | Conflict-resolution strategy to evaluate the preview under. One of: strict, source_wins. |
| `target` | `string` | yes | The branch that would receive the promotion. |

## Returns

`StatusResponse<BranchPreviewItem>`

- `data` (`BranchPreviewItem`)
- `type` (`string`)

## Errors

Recover by code, never by message.

| Code | Retry | Commit outcome |
|---|---|---|
| [`failed_precondition.engine.runtime_closed`](https://stratadb.org/e/failed_precondition.engine.runtime_closed) | never | not_started |
| [`not_found.engine.branch`](https://stratadb.org/e/not_found.engine.branch) | never | not_applicable |
| [`invalid_argument.engine.branch_name`](https://stratadb.org/e/invalid_argument.engine.branch_name) | never | not_started |
| [`invalid_argument.engine.branch_name_reserved`](https://stratadb.org/e/invalid_argument.engine.branch_name_reserved) | never | not_started |
| [`invalid_argument.engine.branch_point`](https://stratadb.org/e/invalid_argument.engine.branch_point) | never | not_started |

## Related

- [Create empty branch](https://stratadb.org/docs/reference/branch/create)
- [Delete branch](https://stratadb.org/docs/reference/branch/delete)
- [Compare branches](https://stratadb.org/docs/reference/branch/diff)
- [Fork branch from current head](https://stratadb.org/docs/reference/branch/fork)
- [Fork branch at timestamp](https://stratadb.org/docs/reference/branch/fork_at_timestamp)
- [Fork branch at version](https://stratadb.org/docs/reference/branch/fork_at_version)
- [Read one branch](https://stratadb.org/docs/reference/branch/get)
- [List branches](https://stratadb.org/docs/reference/branch/list)
- [Promote branch](https://stratadb.org/docs/reference/branch/merge)