chore(release): centralize workspace versioning + add cargo-release tooling

Bump the workspace to 0.2.0-alpha.5 and make all-at-once releases a single
operation instead of editing ~17 Cargo.toml files by hand.

- A. Centralize internal crate deps in root [workspace.dependencies] (path +
  version); members now depend via { workspace = true }. The version literal
  lives only in [workspace.package] version + that table.
- B. Add cargo-release (release.toml: shared-version, publish=false, push=false,
  tag v{version}) and Make targets: release-dry, release-version, release,
  publish-dry. CI still performs the actual crates.io publish on tag push.
- C. Release workflow: also match pre-release tags (v0.2.0-alpha.5, -rc.N), and
  add a workflow_dispatch dry_run mode that runs 'cargo package' (build+verify,
  no upload) so the publish path can be exercised safely. Exclude the two
  publish=false FFI crates from the dry-run packaging set.

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

Author: araujof

.github/workflows/release.yaml

@@ -17,7 +17,13 @@ on:
   push:
     tags:
       - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+-*"   # pre-releases: v0.2.0-alpha.5, v1.0.0-rc.1, …
   workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Package + verify all crates without uploading to crates.io"
+        type: boolean
+        default: true
 
 permissions:
   contents: read
@@ -68,8 +74,23 @@ jobs:
       - name: cargo publish (dependency order)
         env:
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+          # true only for a manual workflow_dispatch with dry_run left on.
+          # A real version-tag push has empty DRY_RUN → publishes for real.
+          DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run }}
         run: |
           set -euo pipefail
+          # Dry run: build + verify a .crate for every publishable member
+          # (cargo skips `publish = false` crates and resolves inter-member
+          # deps against each other's packaged versions) without uploading.
+          # This is how the workflow is exercised without a real release.
+          if [ "$DRY_RUN" = "true" ]; then
+            echo "::group::dry run — cargo package (no upload)"
+            # Verify the crates.io-published set only; the two publish=false
+            # FFI crates are not part of the registry release.
+            cargo package --workspace --locked --exclude cpex-ffi --exclude cpex-demo-ffi
+            echo "::endgroup::"
+            exit 0
+          fi
           # Leaf-first topological order. Each `cargo publish` blocks until the
           # crate is visible in the index before returning, so the next crate's
           # dependency resolves; the short sleep is extra slack for propagation.

Cargo.lock

@@ -1,7 +1,7 @@
 # Location: ./Cargo.toml
 # Copyright 2025
 # SPDX-License-Identifier: Apache-2.0
-# Authors: Teryl Taylor
+# Authors: Teryl Taylor, Fred Araujo
 #
 # Workspace root for the CPEX Rust crates.
 
@@ -58,7 +58,7 @@ default-members = [
 ]
 
 [workspace.package]
-version = "0.2.0"
+version = "0.2.0-alpha.5"
 edition = "2021"
 # MSRV — keep in sync with rust-toolchain.toml `channel` and clippy.toml `msrv`.
 rust-version = "1.96"
@@ -95,6 +95,29 @@ serde_bytes = "0.11"
 chrono = { version = "0.4", features = ["serde"] }
 regex = "1"
 
+# Internal workspace crates — single source of truth for their path + version
+# requirement. Members depend on these via `{ workspace = true }` so a version
+# bump touches only this table (plus `[workspace.package] version`). The
+# `version` is required because these crates publish to crates.io: at publish
+# time cargo substitutes it for the `path`. `cargo release` keeps these in sync
+# with the workspace version. Keys are package names (builtins differ from their
+# directory names), paths are workspace-root-relative.
+cpex-core                     = { path = "crates/cpex-core",                   version = "0.2.0-alpha.5" }
+cpex-orchestration            = { path = "crates/cpex-orchestration",          version = "0.2.0-alpha.5" }
+cpex-sdk                      = { path = "crates/cpex-sdk",                     version = "0.2.0-alpha.5" }
+cpex-builtins                 = { path = "crates/cpex-builtins",               version = "0.2.0-alpha.5" }
+apl-core                      = { path = "crates/apl-core",                    version = "0.2.0-alpha.5" }
+apl-cmf                       = { path = "crates/apl-cmf",                      version = "0.2.0-alpha.5" }
+apl-cpex                      = { path = "crates/apl-cpex",                     version = "0.2.0-alpha.5" }
+cpex-plugin-pii-scanner       = { path = "builtins/plugins/pii-scanner",       version = "0.2.0-alpha.5" }
+cpex-plugin-audit-logger      = { path = "builtins/plugins/audit-logger",      version = "0.2.0-alpha.5" }
+cpex-plugin-identity-jwt      = { path = "builtins/plugins/identity-jwt",      version = "0.2.0-alpha.5" }
+cpex-plugin-delegator-oauth   = { path = "builtins/plugins/delegator-oauth",   version = "0.2.0-alpha.5" }
+cpex-plugin-delegator-biscuit = { path = "builtins/plugins/delegator-biscuit", version = "0.2.0-alpha.5" }
+cpex-pdp-cedar-direct         = { path = "builtins/pdps/cedar-direct",         version = "0.2.0-alpha.5" }
+cpex-pdp-cel                  = { path = "builtins/pdps/cel",                   version = "0.2.0-alpha.5" }
+cpex-session-valkey           = { path = "builtins/session/valkey",            version = "0.2.0-alpha.5" }
+
 # Size-first release profile. The FFI artifact (libcpex_ffi.a) is linked
 # statically into host binaries, so its compiled size flows straight into
 # those images. The default release profile leaves symbols + debug info in

Cargo.toml

@@ -63,6 +63,13 @@ help:
 	@echo ""
 	@echo "End-to-end:"
 	@echo "  ci                Lint + tests + examples-build (CI gate)"
+	@echo ""
+	@echo "Release (version bump + tag locally; CI publishes on tag push):"
+	@echo "  release-dry       Preview the release (no changes)"
+	@echo "  release-version   Set the version everywhere (no commit/tag)"
+	@echo "  release           Bump + commit + tag (then: git push origin vX.Y.Z)"
+	@echo "  publish-dry       Local packaging dry-run (mirrors CI dry-run)"
+	@echo "                    Pass LEVEL=alpha|patch|minor|major|rc|release or VERSION=X.Y.Z"
 
 # =============================================================================
 # Build
@@ -253,3 +260,56 @@ examples-run: examples-build
 .PHONY: ci
 ci: lint test examples-build
 	@echo "✅  CI gate passed (lint + tests + examples)"
+
+# =============================================================================
+# Release
+# =============================================================================
+#
+# This workspace versions and releases every publishable crate together. The
+# version lives in ONE place — `[workspace.package] version` plus the
+# `[workspace.dependencies]` table in the root Cargo.toml — and cargo-release
+# keeps both in sync. Config (shared-version, tag name, publish=false) lives in
+# release.toml; the actual crates.io publish runs in CI on the pushed tag.
+#
+# Bump level (LEVEL) or explicit VERSION:
+#   make release-dry                 # preview, no changes (default LEVEL=alpha)
+#   make release LEVEL=patch         # 0.2.0 -> 0.2.1
+#   make release VERSION=0.2.0       # drop the pre-release suffix
+#   git push origin "v$(...)"        # push the tag to let CI publish
+
+LEVEL   ?= alpha
+VERSION ?=
+# Explicit VERSION wins over LEVEL when set.
+RELEASE_ARG = $(if $(VERSION),$(VERSION),$(LEVEL))
+
+.PHONY: release-tool
+release-tool:
+	@command -v cargo-release >/dev/null 2>&1 || $(CARGO) install cargo-release --locked
+
+# Preview only — cargo-release makes NO changes without --execute.
+.PHONY: release-dry
+release-dry: release-tool
+	@$(CARGO) release $(RELEASE_ARG) --workspace
+
+# Rewrite the version in [workspace.package] + [workspace.dependencies] only;
+# no commit, no tag. Useful for a manual, reviewed bump.
+.PHONY: release-version
+release-version: release-tool
+	@$(CARGO) release version $(RELEASE_ARG) --workspace --execute --no-confirm
+
+# Bump + commit + tag, then stop. --no-publish/--no-push enforce the
+# "CI publishes on tag push" model at the CLI level too (release.toml already
+# sets publish=false/push=false; this makes the guarantee not depend on config
+# parsing). Afterwards: `git push origin vX.Y.Z` to trigger the CI publish.
+.PHONY: release
+release: release-tool
+	@$(CARGO) release $(RELEASE_ARG) --workspace --no-publish --no-push --execute
+
+# Build + verify a .crate for every crates.io-published member without
+# uploading — the same check the release workflow's dry-run runs. The two
+# `publish = false` FFI crates are excluded (cpex-ffi ships as signed prebuilt
+# artifacts; cpex-demo-ffi is an example). CI runs this on a clean checkout;
+# --allow-dirty lets you run it locally with work in progress.
+.PHONY: publish-dry
+publish-dry:
+	@$(CARGO) package --workspace --locked --allow-dirty --exclude cpex-ffi --exclude cpex-demo-ffi

Makefile

@@ -26,7 +26,7 @@ categories.workspace = true
 rust-version.workspace = true
 
 [dependencies]
-apl-core = { path = "../../../crates/apl-core", version = "0.2.0" }
+apl-core = { workspace = true }
 # Permissive caret spec — `"4"` means "any 4.x that Cargo can find."
 #
 # Code-side note: we use `Request::new(...)` (added in 4.11 alongside
@@ -52,9 +52,9 @@ thiserror = { workspace = true }
 # dev-dep edges only exist for tests — the crate itself stays
 # apl-core-only at compile time so it can be used standalone (e.g. in a
 # custom orchestrator that doesn't go through apl-cpex at all).
-apl-cmf = { path = "../../../crates/apl-cmf", version = "0.2.0" }
-apl-cpex = { path = "../../../crates/apl-cpex", version = "0.2.0" }
-cpex-core = { path = "../../../crates/cpex-core", version = "0.2.0" }
+apl-cmf = { workspace = true }
+apl-cpex = { workspace = true }
+cpex-core = { workspace = true }
 tokio = { workspace = true, features = ["macros", "rt", "rt-multi-thread"] }
 # Minimal executor for the small-stack regression test (tests/small_stack_eval.rs):
 # drives the async `evaluate` without tokio's larger per-call stack footprint, so

builtins/pdps/cedar-direct/Cargo.toml

@@ -26,7 +26,7 @@ categories.workspace = true
 rust-version.workspace = true
 
 [dependencies]
-apl-core = { path = "../../../crates/apl-core", version = "0.2.0" }
+apl-core = { workspace = true }
 # The CEL interpreter from cel-rust/cel-rust (formerly
 # clarkmcc/cel-rust). Sync eval, comprehension macros (`has`, `all`,
 # `exists`, `map`, `filter`), custom functions. Caret spec tracks 0.x
@@ -55,9 +55,9 @@ tracing = { workspace = true }
 # edges only exist for tests — the crate itself stays apl-core-only at
 # compile time so it can be used standalone (e.g. in a custom orchestrator
 # that doesn't go through apl-cpex at all).
-apl-cmf = { path = "../../../crates/apl-cmf", version = "0.2.0" }
-apl-cpex = { path = "../../../crates/apl-cpex", version = "0.2.0" }
-cpex-core = { path = "../../../crates/cpex-core", version = "0.2.0" }
+apl-cmf = { workspace = true }
+apl-cpex = { workspace = true }
+cpex-core = { workspace = true }
 tokio = { workspace = true, features = ["macros", "rt", "rt-multi-thread"] }
 
 [lints]

builtins/pdps/cel/Cargo.toml

@@ -22,7 +22,7 @@ categories.workspace = true
 rust-version.workspace = true
 
 [dependencies]
-cpex-core = { path = "../../../crates/cpex-core", version = "0.2.0" }
+cpex-core = { workspace = true }
 
 async-trait = { workspace = true }
 chrono      = { workspace = true }

builtins/plugins/audit-logger/Cargo.toml

@@ -48,7 +48,7 @@ categories.workspace = true
 rust-version.workspace = true
 
 [dependencies]
-cpex-core = { path = "../../../crates/cpex-core", version = "0.2.0" }
+cpex-core = { workspace = true }
 
 # biscuit-auth v6 — current major. Maintained by Clever Cloud +
 # community. Ed25519 + Datalog. No default-features off needed; the

builtins/plugins/delegator-biscuit/Cargo.toml

@@ -43,7 +43,7 @@ categories.workspace = true
 rust-version.workspace = true
 
 [dependencies]
-cpex-core = { path = "../../../crates/cpex-core", version = "0.2.0" }
+cpex-core = { workspace = true }
 
 # `reqwest` for the HTTP POST to the IdP token endpoint. Default
 # features pull `rustls` for TLS — we explicitly disable the

builtins/plugins/delegator-oauth/Cargo.toml

@@ -29,7 +29,7 @@ categories.workspace = true
 rust-version.workspace = true
 
 [dependencies]
-cpex-core = { path = "../../../crates/cpex-core", version = "0.2.0" }
+cpex-core = { workspace = true }
 
 # `jsonwebtoken` is the de facto JWT library for Rust. Supports
 # RS256/RS384/RS512, ES256/ES384, EdDSA, HS256/HS384/HS512. Default