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#

the engine's 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 eight contract-bearing layers (World Store, Perception Lake, World Graph, 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.8.1 → 0.8.2) — bug fix where the documented behavior was wrong. No surface change.
• Minor (0.8.x → 0.9.0) — additive surface in any layer (new CALL procedure, new algorithm, new RPC method, new release artifact). Existing surface unchanged.
• 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 "@ozinc/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://staging.oz.com/install/arcflow | sh
 
# Or accept the latest (default — resolves via releases/latest redirect)
curl -fsSL https://staging.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. 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 — release manifest schema
• VERSIONING.md — canonical bump-rule reference