Versioning

ArcFlow has one version. Every surface that reports a version reports the same string.

Convention — alpha-state (0.x)#

ArcFlow is in alpha. The version line is 0.x.y, following the SemVer convention for pre-1.0 unstable software. v1.0.0 is reserved for the first production-ready release and is operator-gated.

If you're wondering why a database in active use sits at 0.x rather than 1.x or higher: most projects ship a 0.x cycle, hit 1.0, and declare "production-ready." ArcFlow does the same — alpha lives at 0.x, production starts at 1.0. The convention is honest about where the project is.

Source of truth#

arcflow-core/Cargo.toml
  [workspace.package]
    version = "0.8.0"            ← The single source of truth
        │
        │ Cargo workspace inheritance — every crate
        ▼
  env!("CARGO_PKG_VERSION") in Rust source
        │
        ├──► arcflow --version              (CLI binary banner)
        ├──► arcflow status --json          (version field)
        ├──► SHOW SERVER_VERSION            (postgres-wire shim)
        ├──► CALL db.version                (WorldCypher procedure)
        ├──► libarcflow.dylib FFI symbol    (arcflow_version())
        └──► python/pyproject.toml          (lockstep with workspace)

  git tag v{X.Y.Z} = workspace version
        │
        │ release-binaries.yml workflow
        │ resolves RELEASE-MATRIX.toml "auto" sentinel via
        │ `git describe --tags --abbrev=0`
        ▼
  release-matrix.json
    engine.version: "0.8.0"
        │
        ├──► oz.com install matrix              (build-time fetch)
        ├──► install.sh (releases/latest)       (runtime resolve)
        ├──► arcflow-docs cookbook renders      (build-time substitution)
        └──► customer manifest consumers        (e.g. project-merlin)

The git tag is the authoritative release artifact. Everything else either inherits from the workspace Cargo.toml at build time or reads release-matrix.json at runtime.

What each call returns#

All surfaces converge on the same string.

Bump rules#

ArcFlow ships six contract-bearing layers (World Store, Query Engine, Live Surface, Event Bus, Behavior Engine, Algorithm Library). SemVer is keyed to which layer's surface changes, not to commit count or release cadence.

• Patch (0.7.1 → 0.8.0) — bug fix where the documented behavior was wrong. No surface change.
• Minor (0.7.x → 0.8.0) — additive surface in any layer (new CALL procedure, new algorithm, new RPC method, new release artifact). Existing surface unchanged. The 0.7.x → 0.8.0 cut shipped the World Graph substrate — the arcflow.worldgraph public module, virtual labels, register_virtual_partition FFI, the oz:// URI scheme, the ResidencyClass + TierBudget vocabulary, and the ARC1 hot-tier format. Legacy crate-root modules (mvcc, dense_store, column_store, csr) remain as canonical re-exports — no migration required.
• Major (0.x.y → 1.0.0 or later) — breaking change to a contract-bearing layer (query semantics, payload shape, FFI ABI, on-disk format, RPC signature). Requires migration dossier + pre-release -rc.N sequence + operator sign-off.
• Pre-release (X.Y.Z-rc.N) — sequenced ship-gate validation against consumers before a major bump or large-minor cut.

Programmatic lookup#

# Python — the version your application is running against
import arcflow
print(arcflow.__version__)        # → "0.8.0"
 
# Or via the FFI binding
from arcflow import ArcFlow
print(ArcFlow.version())          # → "0.8.0"

# Shell — the installed CLI
arcflow --version
# ArcFlow 0.8.0

// TypeScript — the SDK version
import { version } from "arcflow";
console.log(version);              // → "0.8.0"

For machine-consumable use across all surfaces, fetch release-matrix.json:

curl -fsSL https://github.com/ozinc/arcflow/releases/latest/download/release-matrix.json \
  | jq -r '.engine.version'
# 0.8.0

Pinning a version#

# Cookbook pyproject.toml
[project]
dependencies = [
    "oz-arcflow==0.8.0",
]

# Install script — pin to a specific tag
ARCFLOW_VERSION=0.8.0 curl -fsSL https://oz.com/install/arcflow | sh
 
# Or accept the latest (default — resolves via releases/latest redirect)
curl -fsSL https://oz.com/install/arcflow | sh

For coding agents#

1. Trust any of arcflow.__version__, ArcFlow.version(), or arcflow --version — all return the same string.
2. When generating install commands, read engine.version from release-matrix.json at the URL above rather than hardcoding a literal.
3. When pinning dependencies in cookbooks / project templates, match the value in release-matrix.json engine.version.
4. 0.x is alpha, not a downgrade. Earlier 1.x line numbers were a labelling convention; every fix and feature shipped under 1.x is present in the current 0.x release. The convention reversal makes the alpha boundary unambiguous; 1.0 is reserved for the first production-ready release.

See also#

• installation — install matrix and version selection
• reference/compatibility — GQL feature support
• RELEASE-MATRIX.toml in arcflow-core — manifest schema
• VERSIONING.md in arcflow-core — canonical bump-rule reference (this page mirrors it)