> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frayme.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> Every save bumps a version. Older versions remain addressable for replay; the active version handles new events.

Workflows are versioned with monotonic integers. The latest version is the **active** one (assuming `status: active`); older versions are kept addressable for replay and audit.

## Version anatomy

| Field           | Notes                                                                                |
| --------------- | ------------------------------------------------------------------------------------ |
| `version`       | Integer, bumped on every save. Starts at 1.                                          |
| `status`        | `draft` (not in service) / `active` (handling events) / `archived` (no longer used). |
| `createdAt`     | Original creation timestamp.                                                         |
| `updatedAt`     | Last save timestamp.                                                                 |
| `createdBy`     | The user who first created the workflow.                                             |
| `_lastEditedBy` | The user who made the most recent save (optional).                                   |

## Promotion flow

<Steps>
  <Step title="Duplicate as draft">
    From the active workflow, "Duplicate as draft" creates a sibling with the latest definition copied over. Its `status: draft` keeps it out of service.
  </Step>

  <Step title="Edit + test">
    Use the test pane (see [Testing](/workflows/testing)) against fixtures and historical runs.
  </Step>

  <Step title="Promote">
    Flip the draft's `status` to `active` and archive the prior version (`status: archived`). The prior version remains readable at its `version` for replay.
  </Step>

  <Step title="Cut over">
    The engine picks up the new active version on the next event. In-flight runs against the prior version continue to completion under their original version.
  </Step>
</Steps>

## Replay against an updated version

Frayme replays historical runs against the **current active version** — letting you see how a past case would resolve under today's logic.

```text theme={null}
POST /api/workflows/:id/replay
{ "run_id": "run_..." }
```

The replay reads the original input from history and runs it through the current graph. Side-by-side diff shows which nodes route differently.

<Warning>
  **Input-schema drift.** The replay assumes the original input still satisfies the current workflow's input schema. If you've added or removed required fields between versions, replay against an older run will fail validation. Make schema-breaking changes in a coordinated migration: bump the version, and either (a) keep the old version active for replays of old runs, or (b) ship an input adapter that translates old inputs into the new shape before re-running.
</Warning>

Replaying against an old version is also supported (via `?version=N`) — useful when you specifically want to reproduce historical behaviour rather than see how new logic would have decided.

## Comparing versions

The editor's **Versions** panel shows the change log per version with an auto-extracted summary plus the human-written description.

## Best practice

<Check>Treat the workflow definition like code: every save is a commit, every active workflow has a reviewer.</Check>
<Check>Use draft duplicates for experimentation; never edit the active version directly.</Check>
<Check>Keep workflow descriptions current — they're surfaced as the "what does this do" tooltip in the queue, the decision console, and the audit-export bundles.</Check>