feat(vortex-edition): session-registered editions declared in the vortex facade

vortex-edition provides the editions machinery: the types (EditionId,
Edition, EditionInclusion, EditionDeclaration), the EditionSession
session variable holding the per-session registry (starts empty; clones
share the registry like other session registries), computation
(editions(), encodings_in() with membership inherited by later editions
of the family, current()), validation (identifier/version forms via
EditionId::validate and EditionInclusion::validate, plus whole-registry
checks: undeclared references, drafts-newest chronology, members
requiring a release newer than their edition declares), and the
validate!(session, EDITION) macro generating a per-edition unit test.
Encoding ids use the session's intern pool (registry::Id, the same
identifier space as ArrayId), and declaration blocks name encodings via
the AsEncodingId trait — an id string today, an encoding vtable once
vortex-array implements it.

The actual declarations live in the public vortex crate
(vortex::editions): two core editions declared block-wise with the
encodings each adds — core2026.01.0 with the 12 canonical encodings and
core2026.07.0 inheriting them plus the 20 container/compressed
encodings the default writer emits. Both are drafts until their
min_vortex_version is recorded, which is the act of freezing.
register_default_editions seeds them into the default session, golden
tests pin both sets, and transitivity/consistency tests cover
inheritance and the one-inclusion-per-encoding invariant.

Signed-off-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KdR42Svu74NcNzC7XJYwLr

Author: claude

Cargo.lock

@@ -8,6 +8,7 @@ members = [
     "vortex-mask",
     "vortex-utils",
     "vortex-session",
+    "vortex-edition",
     "vortex-flatbuffers",
     "vortex-metrics",
     "vortex-io",
@@ -295,6 +296,7 @@ vortex-compute = { version = "0.1.0", path = "./vortex-compute", default-feature
 vortex-datafusion = { version = "0.1.0", path = "./vortex-datafusion", default-features = false }
 vortex-datetime-parts = { version = "0.1.0", path = "./encodings/datetime-parts", default-features = false }
 vortex-decimal-byte-parts = { version = "0.1.0", path = "encodings/decimal-byte-parts", default-features = false }
+vortex-edition = { version = "0.1.0", path = "./vortex-edition", default-features = false }
 vortex-error = { version = "0.1.0", path = "./vortex-error", default-features = false }
 vortex-fastlanes = { version = "0.1.0", path = "./encodings/fastlanes", default-features = false }
 vortex-file = { version = "0.1.0", path = "./vortex-file", default-features = false }

Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "vortex-edition"
+authors.workspace = true
+description = "Definitions of Vortex editions: named, frozen sets of encodings with a read-compatibility guarantee"
+edition = { workspace = true }
+homepage = { workspace = true }
+categories = { workspace = true }
+include = { workspace = true }
+keywords = { workspace = true }
+license = { workspace = true }
+readme = { workspace = true }
+repository = { workspace = true }
+rust-version = { workspace = true }
+version = { workspace = true }
+
+[package.metadata.docs.rs]
+all-features = true
+
+[lints]
+workspace = true
+
+[dependencies]
+parking_lot = { workspace = true }
+vortex-session = { workspace = true }

vortex-edition/Cargo.toml

@@ -0,0 +1,292 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+//! Definitions of Vortex *editions*: named, frozen sets of encodings that a writer may put in
+//! a file, carrying a forever read-compatibility guarantee.
+//!
+//! Editions live on the session, like encodings do: [`EditionSession`] is the session
+//! variable holding the edition registry, populated at initialization time. Declarations
+//! are plain constants — an [`EditionId`] plus an [`Edition`] record, and one
+//! [`EditionInclusion`] per encoding stating that it is a member of an edition *and every
+//! later edition of the same family*. Any crate can register declarations into a session,
+//! so inclusions can live next to the encoding they describe.
+//!
+//! An edition is a **draft** until its [`Edition::min_vortex_version`] is recorded —
+//! recording it is the act of freezing. The per-edition encoding sets are computed from the
+//! registered declarations by [`EditionSession::encodings_in`], and correctness is enforced
+//! by unit tests: [`EditionSession::validate`] checks a whole registry, and
+//! [`validate!`](crate::validate) generates a test for a single edition.
+//!
+//! This crate defines only the types and the session variable; the first-party edition
+//! declarations live in the public `vortex` crate (`vortex::editions`), which seeds them
+//! into the default session. See the published spec at
+//! <https://docs.vortex.dev/specs/editions.html>.
+
+mod session;
+#[cfg(test)]
+mod tests;
+
+use std::error::Error;
+use std::fmt;
+use std::fmt::Debug;
+use std::fmt::Display;
+use std::fmt::Formatter;
+
+pub use session::EditionSession;
+pub use session::EditionSessionExt;
+use vortex_session::registry::Id;
+
+/// The identifier of an edition, e.g. `core2026.07.0`.
+///
+/// The `family` names an independently versioned, additive group of encodings (`core` is the
+/// set the default writer emits). The date components record when the edition was frozen and
+/// order editions chronologically *within* a family; there is no ordering across families.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct EditionId {
+    /// The edition family, e.g. `core`.
+    pub family: &'static str,
+    /// Year the edition was cut.
+    pub year: u16,
+    /// Month the edition was cut.
+    pub month: u8,
+    /// Distinguishes editions cut in the same month; normally `0`.
+    pub version: u8,
+}
+
+impl EditionId {
+    /// Create an edition identifier. Validated by [`EditionId::validate`], which the
+    /// [`validate!`](crate::validate) macro exercises per edition in unit tests.
+    pub const fn new(family: &'static str, year: u16, month: u8, version: u8) -> Self {
+        Self {
+            family,
+            year,
+            month,
+            version,
+        }
+    }
+
+    /// Returns true if `self` is the same edition as `other` or an earlier edition of the
+    /// same family. Editions of different families are never ordered.
+    pub fn is_at_or_before(&self, other: &EditionId) -> bool {
+        self.family == other.family
+            && (self.year, self.month, self.version) <= (other.year, other.month, other.version)
+    }
+
+    /// Validate the identifier's form: a non-empty lowercase family, a four-digit year,
+    /// and a month in 01-12. Checked for every declared edition by
+    /// [`EditionSession::validate`]; the [`validate!`](crate::validate) macro generates a
+    /// unit test covering a single edition.
+    pub fn validate(&self) -> Result<(), EditionError> {
+        if self.family.is_empty() || !self.family.chars().all(|c| c.is_ascii_lowercase()) {
+            return Err(EditionError::new(format!(
+                "edition {self} must have a non-empty lowercase family, e.g. `core`"
+            )));
+        }
+        if !(1000..=9999).contains(&self.year) {
+            return Err(EditionError::new(format!(
+                "edition {self} must have a four-digit year"
+            )));
+        }
+        if !(1..=12).contains(&self.month) {
+            return Err(EditionError::new(format!(
+                "edition {self} must have a month in 01-12"
+            )));
+        }
+        Ok(())
+    }
+}
+
+impl Display for EditionId {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "{}{}.{:02}.{}",
+            self.family, self.year, self.month, self.version
+        )
+    }
+}
+
+/// An edition: a named set of encodings with a read-compatibility guarantee, registered with
+/// [`EditionSession::declare_edition`]. The set itself is computed from the registered
+/// [`EditionInclusion`]s by [`EditionSession::encodings_in`].
+#[derive(Clone, Copy, Debug)]
+pub struct Edition {
+    /// The edition identifier. Also carries the freeze date: `core2026.07.0` freezes in
+    /// 2026-07.
+    pub id: EditionId,
+    /// The minimum Vortex version whose reader supports every encoding in this edition.
+    ///
+    /// Recording this is the act of freezing: an edition with `None` is a **draft** — being
+    /// assembled, carrying no guarantee, free to change, never the default write target.
+    /// Validated against the members' [`EditionInclusion::required_vortex_release`] values:
+    /// no member may require a version newer than the edition declares.
+    pub min_vortex_version: Option<&'static str>,
+}
+
+impl Edition {
+    /// A draft is an edition whose `min_vortex_version` has not been recorded yet.
+    pub fn is_draft(&self) -> bool {
+        self.min_vortex_version.is_none()
+    }
+}
+
+/// Declares that an encoding is a member of an edition — and of every later edition of the
+/// same family. Registered with [`EditionSession::declare_inclusion`].
+#[derive(Clone, Copy, Debug)]
+pub struct EditionInclusion {
+    /// The interned encoding id, e.g. `vortex.alp`. Globally unique across everything an
+    /// edition can cover: when layout encodings join editions, their ids must be distinct
+    /// from array encoding ids.
+    pub encoding_id: Id,
+    /// The first edition this encoding is a member of.
+    pub since: EditionId,
+    /// The earliest Vortex release able to read and execute this encoding, recorded from
+    /// evidence (e.g. compat-fixture history). `None` until recorded.
+    pub required_vortex_release: Option<&'static str>,
+}
+
+/// A source of an encoding id for edition declarations.
+///
+/// Implemented for raw id strings (`"vortex.alp"`) and interned [`Id`]s here; encoding
+/// vtables implement it where they are defined, so a declaration can name the vtable
+/// (`&Primitive`) instead of spelling its id.
+pub trait AsEncodingId: Debug + Send + Sync {
+    /// The interned encoding id.
+    fn encoding_id(&self) -> Id;
+}
+
+impl AsEncodingId for str {
+    #[expect(
+        clippy::disallowed_methods,
+        reason = "interning a dynamic encoding id at declaration time"
+    )]
+    fn encoding_id(&self) -> Id {
+        Id::new(self)
+    }
+}
+
+impl AsEncodingId for Id {
+    fn encoding_id(&self) -> Id {
+        *self
+    }
+}
+
+// `str` is unsized and cannot be a trait object, so declaration blocks (slices of
+// `&dyn AsEncodingId`) name encodings as `&"vortex.alp"` through this impl.
+impl AsEncodingId for &'static str {
+    fn encoding_id(&self) -> Id {
+        (**self).encoding_id()
+    }
+}
+
+/// Declares an edition together with the encodings that join the family at it, in one
+/// block. Registered with [`EditionSession::declare`], which derives each encoding's
+/// membership (`since` = the declared edition) from the block structure.
+#[derive(Clone, Copy, Debug)]
+pub struct EditionDeclaration {
+    /// The edition being declared.
+    pub edition: Edition,
+    /// The encodings that join the family at this edition, named by id string or by
+    /// vtable. Members of earlier editions are inherited and never restated.
+    pub added: &'static [&'static dyn AsEncodingId],
+}
+
+impl EditionInclusion {
+    /// Declare that an encoding is a member of `since` and every later edition of the same
+    /// family. The encoding can be named by id string or by vtable.
+    pub fn new<E: AsEncodingId + ?Sized>(encoding: &E, since: EditionId) -> Self {
+        Self {
+            encoding_id: encoding.encoding_id(),
+            since,
+            required_vortex_release: None,
+        }
+    }
+
+    /// Validate the declaration's form: a lowercase `namespace.name` encoding id and, if
+    /// recorded, a well-formed `major.minor.patch` release. Checked for every declared
+    /// inclusion by [`EditionSession::validate`].
+    pub fn validate(&self) -> Result<(), EditionError> {
+        let id = self.encoding_id.as_str();
+        let well_formed = !id.starts_with('.')
+            && !id.ends_with('.')
+            && id.contains('.')
+            && id
+                .chars()
+                .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || "._-".contains(c));
+        if !well_formed {
+            return Err(EditionError::new(format!(
+                "invalid encoding id {id:?}: expected lowercase `namespace.name`, e.g. \
+                 `vortex.alp`"
+            )));
+        }
+        if let Some(release) = self.required_vortex_release
+            && parse_release(release).is_none()
+        {
+            return Err(EditionError::new(format!(
+                "encoding {id} declares malformed required_vortex_release {release:?}"
+            )));
+        }
+        Ok(())
+    }
+}
+
+/// Generates a unit test asserting that the named edition is correctly declared: its
+/// identifier is well-formed, it is registered in the given [`EditionSession`], and that
+/// session's declarations as a whole validate.
+///
+/// The first argument is an expression producing the session to check, evaluated with the
+/// invoking module's names in scope:
+///
+/// ```ignore
+/// vortex_edition::validate!(edition_session(), CORE_2026_07_0);
+/// ```
+#[macro_export]
+macro_rules! validate {
+    ($editions:expr, $edition:ident) => {
+        #[expect(non_snake_case, reason = "test module named after the edition const")]
+        #[cfg(test)]
+        mod $edition {
+            #[test]
+            fn is_correctly_declared() {
+                use super::*;
+
+                let id = $edition;
+                id.validate().unwrap();
+
+                let editions: $crate::EditionSession = $editions;
+                assert!(
+                    editions.find(&id).is_some(),
+                    "{id} is not declared in the session",
+                );
+                editions.validate().unwrap();
+            }
+        }
+    };
+}
+
+/// Parse a `major.minor.patch` release string into a comparable key.
+pub(crate) fn parse_release(release: &str) -> Option<Vec<u64>> {
+    let parts: Vec<u64> = release
+        .split('.')
+        .map(|part| part.parse::<u64>().ok())
+        .collect::<Option<_>>()?;
+    (parts.len() == 3).then_some(parts)
+}
+
+/// Error raised when edition declarations are inconsistent.
+#[derive(Debug)]
+pub struct EditionError(String);
+
+impl EditionError {
+    pub(crate) fn new(msg: impl Into<String>) -> Self {
+        Self(msg.into())
+    }
+}
+
+impl Display for EditionError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+impl Error for EditionError {}