Versioning & Releases

The opensecstack ecosystem uses per-platform semantic versioning for independent release cadences and ecosystem release tags that pin a tested combination of platform versions for operators who want a single blessed configuration. This page covers the versioning rules, the compatibility matrix concept, the deprecation policy, and the post-quantum migration timeline. For how the platforms fit together structurally, see the Architecture overview.

Semantic versioning

Every platform follows semver.org. The rules are interpreted strictly:

When in doubt, bump the higher version — over-bumping is cheap; under-bumping erodes trust. A new database migration alone is not a breaking change; a migration that removes a column is.

Per-platform release tags follow a module-scoped convention:

citadel/v1.1.0
irflow/v1.0.2
sdk/v1.0.0
apiguard/v1.3.0

This lets a platform ship a security patch without forcing every other platform through the release cycle. It aligns with the Go monorepo convention and how go get resolves module versions.

Release types & cadence

The ecosystem ships in two modes:

Ecosystem releases are coordination events, not requirements. Individual platform upgrades between ecosystem releases are supported via the compatibility matrix. Emergency security patches bypass the cadence entirely and go directly to a tagged version with a GitHub Security Advisory.

An RC soak period precedes every final tag: 24 hours for patches, 3 business days for minor releases, 2 weeks for majors, and 4 weeks for ecosystem releases. The RC is deployed to a staging environment that mirrors production before the final tag is cut.

Compatibility matrix

The compatibility matrix is the authoritative answer to "can IRFlow 1.1 talk to CITADEL 1.0?" — the answer is in the table, not in a Slack thread. It has three dimensions: per-platform pair-wise compatibility, ecosystem release version pins, and support windows.

The current ecosystem releases are:

The compatibility rule across all platform pairs: minor versions are forward and backward compatible within the same major. SDK minor versions are forward and backward compatible within the same major; SDK 2.0 accompanies platform 2.0. Cross-major combinations are supported only during their explicit migration window.

Some cross-platform features require minimum versions on both sides:

HTTP APIs are versioned at the URL path level (/api/v1/..., /api/v2/...). When /api/v2/ lands, /api/v1/ continues to work for at least 12 months. A single server can expose multiple protocol versions during a transition window.

Support windows

In practice, two minor versions back always receive security fixes. Everything older is archived. Released versions are immutable — we never yank a published release, because auditors and regulators may reference a specific version. If a bug is found post-release, a patch release (1.1.0 → 1.1.1) is the fix path; downgrade to the previous version is always valid.

Deprecation policy

Any deprecated-then-removed feature passes through three phases before it disappears:

Changes that trigger the deprecation process include:

• HTTP endpoints removed or changed (e.g. DELETE /api/v1/incidents/archive → PATCH {status:"archived"})
• Request/response fields renamed or removed (e.g. incident.criticality → incident.severity)
• Config env vars renamed (e.g. IRFLOW_WEBHOOK_SECRET → IRFLOW_WEBHOOK_<SOURCE>_SECRET)
• SDK function signatures changed
• Event types renamed (e.g. citadel.marshal.refuse → citadel.marshal.decision)
• Default behaviour changes (e.g. webhook clock skew tolerance going from 10m to 5m)

Internal-only changes — unexported Go functions, private modules, undocumented behaviours — do not require the deprecation process. The contract is with documented interfaces only.

Experimental features — marked // Experimental at introduction — carry no deprecation obligation. They can change shape or disappear in any minor release. The marker must be user-visible in API docs and SDK function signatures. Experimental is not a loophole for insufficient design.

Post-quantum migration timeline

NIST finalised post-quantum standards (ML-KEM, ML-DSA, SLH-DSA) in August 2024. Quantum computers capable of breaking Ed25519 are plausibly 2030–2036. NIS3 (expected 2030–2032) is likely to mandate PQC migration for essential entities. Harvest-now-decrypt-later attacks are already active. OpenSecStack is migrating the CITADEL chain anchor signatures so historical audits remain attestable past the quantum threshold.

The components at risk are the Ed25519 chain anchor signatures in CITADEL and the X.509/ECDSA C2PA provenance in VertGuard's Module 1. HMAC-SHA256 webhooks and TripleHash integrity are safe — symmetric primitives have reduced margin but the core guarantee holds.

SDK clients verify webhook signatures (HMAC-SHA256, unaffected by quantum). The anchor verification path is only used when a consumer calls /worm/verify — and that endpoint returns the algorithm identifier, so SDK clients need only call the appropriate verification code path. Updated SDK versions ship alongside each CITADEL version.

VertGuard's Module 1 (C2PA) is currently X.509/ECDSA-based. The C2PA specification is developing its own PQC migration; VertGuard will track and support hybrid C2PA manifests when the spec lands (~2028).

For the full architectural rationale and per-tier deployment guidance, see docs/post-quantum-roadmap.md and ADR-011 (Post-Quantum Agility) in the opensecstack repository.