Skip to content
Enterium Developer Docs

Version lifecycle

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

Section titled “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

Section titled “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

Section titled “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

Section titled “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.