feat(vortex-edition): session-registered editions with declaration macros

Editions live on the session like encodings do: EditionSession is a
session variable holding the per-session registry of editions and
edition inclusions, populated explicitly at initialization time.
EditionSession::default() seeds the first-party declarations —
core2026.07.0 (a draft until its min_vortex_version is recorded, which
is the act of freezing) and the 32 inclusions for the encodings the
default writer emits — and any crate can declare further inclusions
into a session, so declarations can migrate next to each encoding's
registration.

Two proc macros produce compile-time-validated declarations without any
registration side effects: edition! parses a "family+year.month.version"
identifier into a pub const EditionId, and
edition_inclusion!("vortex.alp" in CORE_2026_07_0) expands to a
const-usable EditionInclusion value. The session computes everything
else: editions() lists the registry, encodings_in(edition) resolves an
edition's full set (membership is inherited by later editions of the
family), current(family) picks the newest frozen edition, and validate()
rejects undeclared references, drafts preceding frozen editions,
malformed versions, and members requiring a release newer than their
edition declares. The intended core2026.07.0 set is pinned by a golden
test.

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,8 @@ members = [
     "vortex-mask",
     "vortex-utils",
     "vortex-session",
+    "vortex-edition",
+    "vortex-edition-macros",
     "vortex-flatbuffers",
     "vortex-metrics",
     "vortex-io",
@@ -295,6 +297,8 @@ 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-edition-macros = { version = "0.1.0", path = "./vortex-edition-macros" }
 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,25 @@
+[package]
+name = "vortex-edition-macros"
+authors = { workspace = true }
+categories = { workspace = true }
+description = "Proc macros for declaring Vortex editions and edition inclusions"
+edition = { workspace = true }
+homepage = { workspace = true }
+include = { workspace = true }
+keywords = { workspace = true }
+license = { workspace = true }
+readme = { workspace = true }
+repository = { workspace = true }
+rust-version = { workspace = true }
+version = { workspace = true }
+
+[lints]
+workspace = true
+
+[lib]
+proc-macro = true
+
+[dependencies]
+proc-macro2 = { workspace = true }
+quote = { workspace = true }
+syn = { workspace = true }

vortex-edition-macros/Cargo.toml

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+//! Proc macros for declaring Vortex editions and edition inclusions.
+//!
+//! Use these through the re-exports in `vortex-edition`; the expansions reference
+//! `::vortex_edition` paths. The macros only produce validated declarations — registration
+//! happens explicitly against the session's `EditionSession`.
+
+use proc_macro::TokenStream;
+use quote::quote;
+use syn::Attribute;
+use syn::Ident;
+use syn::LitStr;
+use syn::Path;
+use syn::Token;
+use syn::Visibility;
+use syn::parse::Parse;
+use syn::parse::ParseStream;
+use syn::parse_macro_input;
+
+/// Declare an edition.
+///
+/// ```ignore
+/// vortex_edition::edition! {
+///     /// The first edition of the `core` family.
+///     pub CORE_2026_07_0 = "core2026.07.0";
+/// }
+/// ```
+///
+/// The identifier string is `family` + `year.month.version` and is parsed at compile time.
+/// Expands to a `const` `EditionId`; the edition itself is registered with
+/// `EditionSession::declare_edition`, where recording a `min_vortex_version` freezes it.
+#[proc_macro]
+pub fn edition(input: TokenStream) -> TokenStream {
+    let decl = parse_macro_input!(input as EditionDecl);
+    match expand_edition(decl) {
+        Ok(tokens) => tokens.into(),
+        Err(err) => err.to_compile_error().into(),
+    }
+}
+
+/// Declare that an encoding is included in an edition (and all later editions of the same
+/// family).
+///
+/// ```ignore
+/// vortex_edition::edition_inclusion!("vortex.alp" in CORE_2026_07_0);
+/// ```
+///
+/// An optional `required_vortex_release = "x.y.z"` records the earliest release able to
+/// read the encoding. The encoding ID is validated at compile time
+/// (`namespace.name`, lowercase). Expands to an `EditionInclusion` value, usable in const
+/// contexts; register it with `EditionSession::declare_inclusion`.
+#[proc_macro]
+pub fn edition_inclusion(input: TokenStream) -> TokenStream {
+    let decl = parse_macro_input!(input as InclusionDecl);
+    match expand_inclusion(decl) {
+        Ok(tokens) => tokens.into(),
+        Err(err) => err.to_compile_error().into(),
+    }
+}
+
+struct EditionDecl {
+    attrs: Vec<Attribute>,
+    vis: Visibility,
+    name: Ident,
+    id: LitStr,
+}
+
+impl Parse for EditionDecl {
+    fn parse(input: ParseStream<'_>) -> syn::Result<Self> {
+        let attrs = input.call(Attribute::parse_outer)?;
+        let vis: Visibility = input.parse()?;
+        let name: Ident = input.parse()?;
+        input.parse::<Token![=]>()?;
+        let id: LitStr = input.parse()?;
+        if input.peek(Token![;]) {
+            input.parse::<Token![;]>()?;
+        }
+        Ok(Self {
+            attrs,
+            vis,
+            name,
+            id,
+        })
+    }
+}
+
+fn expand_edition(decl: EditionDecl) -> syn::Result<proc_macro2::TokenStream> {
+    let (family, year, month, version) = parse_edition_id(&decl.id)?;
+
+    let EditionDecl {
+        attrs, vis, name, ..
+    } = decl;
+
+    Ok(quote! {
+        #(#attrs)*
+        #vis const #name: ::vortex_edition::EditionId =
+            ::vortex_edition::EditionId::new(#family, #year, #month, #version);
+    })
+}
+
+struct InclusionDecl {
+    encoding_id: LitStr,
+    edition: Path,
+    required_vortex_release: Option<LitStr>,
+}
+
+impl Parse for InclusionDecl {
+    fn parse(input: ParseStream<'_>) -> syn::Result<Self> {
+        let encoding_id: LitStr = input.parse()?;
+        input.parse::<Token![in]>()?;
+        let edition: Path = input.parse()?;
+        let mut required_vortex_release = None;
+        if input.peek(Token![,]) {
+            input.parse::<Token![,]>()?;
+            let key: Ident = input.parse()?;
+            if key != "required_vortex_release" {
+                return Err(syn::Error::new(
+                    key.span(),
+                    "expected `required_vortex_release`",
+                ));
+            }
+            input.parse::<Token![=]>()?;
+            required_vortex_release = Some(input.parse()?);
+        }
+        Ok(Self {
+            encoding_id,
+            edition,
+            required_vortex_release,
+        })
+    }
+}
+
+fn expand_inclusion(decl: InclusionDecl) -> syn::Result<proc_macro2::TokenStream> {
+    validate_encoding_id(&decl.encoding_id)?;
+    if let Some(release) = &decl.required_vortex_release {
+        validate_release(release)?;
+    }
+
+    let InclusionDecl {
+        encoding_id,
+        edition,
+        required_vortex_release,
+    } = decl;
+    let required = match required_vortex_release {
+        Some(release) => quote!(::core::option::Option::Some(#release)),
+        None => quote!(::core::option::Option::None),
+    };
+
+    Ok(quote! {
+        ::vortex_edition::EditionInclusion {
+            encoding_id: #encoding_id,
+            since: #edition,
+            required_vortex_release: #required,
+        }
+    })
+}
+
+/// Parse `family` + `year.month.version`, e.g. `core2026.07.0`.
+fn parse_edition_id(lit: &LitStr) -> syn::Result<(String, u16, u8, u8)> {
+    let value = lit.value();
+    let err = |msg: &str| syn::Error::new(lit.span(), format!("invalid edition id: {msg}"));
+
+    let family: String = value
+        .chars()
+        .take_while(|c| c.is_ascii_lowercase())
+        .collect();
+    if family.is_empty() {
+        return Err(err("must start with a lowercase family name, e.g. `core`"));
+    }
+
+    let rest = &value[family.len()..];
+    let parts: Vec<&str> = rest.split('.').collect();
+    let [year, month, version] = parts.as_slice() else {
+        return Err(err("expected `family` + `year.month.version`"));
+    };
+    if year.len() != 4 || month.len() != 2 {
+        return Err(err(
+            "expected a 4-digit year and 2-digit month, e.g. `core2026.07.0`",
+        ));
+    }
+    let year: u16 = year.parse().map_err(|_| err("year is not a number"))?;
+    let month: u8 = month.parse().map_err(|_| err("month is not a number"))?;
+    let version: u8 = version
+        .parse()
+        .map_err(|_| err("version is not a number"))?;
+    if month == 0 || month > 12 {
+        return Err(err("month must be 01-12"));
+    }
+    Ok((family, year, month, version))
+}
+
+/// Validate an encoding ID: lowercase `namespace.name` with `[a-z0-9._-]` characters.
+fn validate_encoding_id(lit: &LitStr) -> syn::Result<()> {
+    let value = lit.value();
+    let valid = !value.starts_with('.')
+        && !value.ends_with('.')
+        && value.contains('.')
+        && value
+            .chars()
+            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || "._-".contains(c));
+    if !valid {
+        return Err(syn::Error::new(
+            lit.span(),
+            "invalid encoding id: expected lowercase `namespace.name`, e.g. `vortex.alp`",
+        ));
+    }
+    Ok(())
+}
+
+/// Validate a `major.minor.patch` release string.
+fn validate_release(lit: &LitStr) -> syn::Result<()> {
+    let value = lit.value();
+    let valid = value.split('.').count() == 3
+        && value
+            .split('.')
+            .all(|part| !part.is_empty() && part.chars().all(|c| c.is_ascii_digit()));
+    if !valid {
+        return Err(syn::Error::new(
+            lit.span(),
+            "invalid release: expected `major.minor.patch`, e.g. `0.70.0`",
+        ));
+    }
+    Ok(())
+}

vortex-edition-macros/src/lib.rs

@@ -0,0 +1,25 @@
+[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-edition-macros = { workspace = true }
+vortex-session = { workspace = true }

vortex-edition/Cargo.toml

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+//! The first-party edition and inclusion declarations, seeded into
+//! [`EditionSession::default`](crate::EditionSession).
+//!
+//! The computed set of a frozen edition is pinned by a golden test in this crate, so any
+//! change to these declarations that alters a frozen set fails CI. New encodings are staged
+//! into the newest draft edition. Inclusions are declared centrally here for now; they are
+//! expected to migrate next to each encoding's registration.
+
+use crate::Edition;
+use crate::EditionInclusion;
+use crate::edition;
+use crate::edition_inclusion;
+
+edition! {
+    /// The first edition of the `core` family: the encodings the default file writer emits.
+    /// A draft until the release shipping it is published and its version is recorded.
+    pub CORE_2026_07_0 = "core2026.07.0";
+}
+
+/// The first-party editions.
+pub static DEFAULT_EDITIONS: &[Edition] = &[Edition {
+    id: CORE_2026_07_0,
+    // TODO(editions): freeze by setting this to the first release shipping this edition,
+    //  once it is published.
+    min_vortex_version: None,
+}];
+
+/// The first-party edition inclusions.
+pub static DEFAULT_INCLUSIONS: &[EditionInclusion] = &[
+    edition_inclusion!("vortex.null" in CORE_2026_07_0),
+    edition_inclusion!("vortex.bool" in CORE_2026_07_0),
+    edition_inclusion!("vortex.primitive" in CORE_2026_07_0),
+    edition_inclusion!("vortex.decimal" in CORE_2026_07_0),
+    edition_inclusion!("vortex.varbin" in CORE_2026_07_0),
+    edition_inclusion!("vortex.varbinview" in CORE_2026_07_0),
+    edition_inclusion!("vortex.list" in CORE_2026_07_0),
+    edition_inclusion!("vortex.listview" in CORE_2026_07_0),
+    edition_inclusion!("vortex.fixed_size_list" in CORE_2026_07_0),
+    edition_inclusion!("vortex.struct" in CORE_2026_07_0),
+    edition_inclusion!("vortex.variant" in CORE_2026_07_0),
+    edition_inclusion!("vortex.ext" in CORE_2026_07_0),
+    edition_inclusion!("vortex.chunked" in CORE_2026_07_0),
+    edition_inclusion!("vortex.constant" in CORE_2026_07_0),
+    edition_inclusion!("vortex.dict" in CORE_2026_07_0),
+    edition_inclusion!("vortex.masked" in CORE_2026_07_0),
+    edition_inclusion!("vortex.sparse" in CORE_2026_07_0),
+    edition_inclusion!("vortex.alp" in CORE_2026_07_0),
+    edition_inclusion!("vortex.alprd" in CORE_2026_07_0),
+    edition_inclusion!("vortex.bytebool" in CORE_2026_07_0),
+    edition_inclusion!("vortex.datetimeparts" in CORE_2026_07_0),
+    edition_inclusion!("vortex.decimal_byte_parts" in CORE_2026_07_0),
+    edition_inclusion!("vortex.fsst" in CORE_2026_07_0),
+    edition_inclusion!("vortex.pco" in CORE_2026_07_0),
+    edition_inclusion!("vortex.runend" in CORE_2026_07_0),
+    edition_inclusion!("vortex.sequence" in CORE_2026_07_0),
+    edition_inclusion!("vortex.zigzag" in CORE_2026_07_0),
+    edition_inclusion!("vortex.zstd" in CORE_2026_07_0),
+    edition_inclusion!("fastlanes.bitpacked" in CORE_2026_07_0),
+    edition_inclusion!("fastlanes.delta" in CORE_2026_07_0),
+    edition_inclusion!("fastlanes.for" in CORE_2026_07_0),
+    edition_inclusion!("fastlanes.rle" in CORE_2026_07_0),
+];