---
title: Version lifecycle
description: Immutable pipeline versions — why a change is always a new carve, never an edit, and how versions are promoted, pinned and rolled back.
locale: en
version: 0.2.0
canonical: https://enterium-developer-docs.pages.dev/developers/pipelines/versioning/
---

> Documentation index: https://enterium-developer-docs.pages.dev/developers/llms.txt — every page of this portal has a Markdown twin at <route>.md; the frozen API contract is at https://enterium-developer-docs.pages.dev/developers/api/openapi.json.

Pipeline code is **immutable per version**. Once `v3.1.16` exists, its folder
is never edited again — a change, however small, becomes a **new carve**: a
byte-copy of the previous version plus the changed files, registered in the
catalog under the next version number.

## Why immutability

- **Reproducibility.** A `pipeline_run` records the version it executed;
  because that version can never change under it, any past run can be
  re-read — or re-run — exactly as it happened.
- **Instant rollback.** Promotion is moving the `latest` pointer (and the
  daily-run pin). Rollback is moving it back. No code changes, no deploys of
  reverted files, no "mostly the same" ambiguity.
- **Safe parallel work.** Sessions working on the next version cannot
  destabilize the version production is pinned to.

## The lifecycle of a version

1. **Carve** — copy the current version's folder to the next version number,
   apply the change, update the version's `manifest.yaml` if the step list or
   contract changed.
2. **Register** — add the one-line entry in `pipelines/catalog.yaml`.
3. **Verify** — run it against real data in the dev contour; compare output
   quality against the incumbent version.
4. **Promote** — move `latest` to the new version and repin the daily-run.
   Promotion of a production default is an owner-gated decision.
5. **Keep the predecessor** — the previous version stays listed as the
   rollback target. Retired lines are deleted from the tree only by an
   explicit cleanup decision; history stays in git.

## Version numbering conventions

- Versions follow SemVer per pipeline (`vMAJOR.MINOR.PATCH`), independent of
  the platform's own module versions.
- **A major line marks an architectural generation.** Example: for Collect,
  the v3 line is the vector-recall generation (embedding-based candidate
  ranking); v1/v2 were the keyword-based generation. The two lines coexist in
  the catalog, and the older one remains the emergency fallback.
- A behavioural change with an unchanged manifest contract is a MINOR bump; a
  fix within the same behaviour is a PATCH.

## Pins

The nightly daily-run does not follow `latest` blindly: it pins explicit
versions for Collect and Generate. This creates a deliberate two-step
promotion — land the version, then move the pin — so a regression discovered
between the two steps never reaches the fleet.