feat: immutable editions

.github/workflows/ci.yml

@@ -651,6 +651,9 @@ jobs:
         with:
           sccache: s3
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          # check-editions compares against the merge base, so it needs real history.
+          fetch-depth: 0
       - uses: ./.github/actions/setup-prebuild
         with:
           enable-sccache: "true"
@@ -660,6 +663,16 @@ jobs:
         run: |
           cargo run --profile ci -p xtask -- generate-fbs
           cargo run --profile ci -p xtask -- generate-proto
+      - name: "regenerate the edition records"
+        run: |
+          cargo run --profile ci -p xtask -- generate-editions
+      - name: "check frozen edition records never change"
+        # Independent of the regeneration above: a stale record must not mask a frozen one
+        # being edited, nor the other way round.
+        if: "!cancelled()"
+        run: |
+          BASE="${{ github.event.pull_request.base.sha || 'HEAD^' }}"
+          cargo run --profile ci -p xtask -- check-editions --base "$BASE"
       - name: "regenerate FFI header file"
         run: |
           cargo +$NIGHTLY_TOOLCHAIN build --profile ci -p vortex-ffi

Cargo.toml

@@ -166,6 +166,7 @@ geo-types = "0.7.19"
 geoarrow = "0.8.0"
 geoarrow-cast = "0.8.0"
 get_dir = "0.5.0"
+git2 = { version = "0.21", default-features = false }
 glob = "0.3.2"
 goldenfile = "1"
 half = { version = "2.7.1", features = ["std", "num-traits"] }
@@ -274,6 +275,7 @@ tokio-stream = "0.1.17"
 tokio-util = "0.7.17"
 vortex-array-macros = { version = "0.1.0", path = "./vortex-array-macros" }
 # Pull these into non-public crates to support DF 58
+toml = "0.9"
 tpchgen = { version = "2.0.2", git = "https://github.com/clflushopt/tpchgen-rs.git", rev = "438e9c2dbc25b2fff82c0efc08b3f13b5707874f" }
 tpchgen-arrow = { version = "2.0.2", git = "https://github.com/clflushopt/tpchgen-rs.git", rev = "438e9c2dbc25b2fff82c0efc08b3f13b5707874f" }
 tracing = { version = "0.1.41", default-features = false }

docs/specs/editions.md

@@ -62,6 +62,19 @@ edition; each encoding's registry entry records the edition it joined in. In the
 encoding may be *deprecated*, meaning writers stop emitting it — but readers keep decoding it
 indefinitely, so deprecation never invalidates existing files.
 
+## The `unstable` family
+
+Alongside `core` there is an `unstable` family, holding encodings that are still being
+evaluated. It is the exception to everything above: every `unstable` edition is a permanent
+draft, so the family never freezes and carries no read-compatibility guarantee at all. A file
+written with these encodings is readable only by a build that knows them, and a future release
+may stop supporting one.
+
+Because of that, the writer only emits them when you opt in — the default session enables the
+newest `unstable` edition solely when the `unstable_encodings` cargo feature is selected.
+Encodings graduate by being declared in a new `core` edition, which is where they pick up the
+read-forever guarantee.
+
 ## Edition registry
 
 Coming soon..

vortex/src/editions/core/mod.rs → vortex-edition/src/declarations/core/mod.rs

@@ -6,6 +6,17 @@
 //! One module per edition, each declaring the edition and the encodings that join the
 //! family at it; members of earlier editions are inherited and never restated.
 
+use crate::EditionFamily;
+
+/// The `core` family: what the default writer may emit.
+pub static FAMILY: EditionFamily = EditionFamily {
+    name: "core",
+    doc: "The encodings the default file writer emits. Every core edition freezes, and a \
+frozen edition carries a read-forever guarantee: a file written with it stays readable by \
+every later Vortex release. New encodings join by being declared in a new edition; an \
+edition that has frozen never changes again.",
+};
+
 pub mod v2025_05;
 pub mod v2025_06;
 pub mod v2025_10;

vortex/src/editions/core/v2025_05.rs → vortex-edition/src/declarations/core/v2025_05.rs

@@ -3,9 +3,9 @@
 
 //! The baseline `core` edition: stable encodings writable by Vortex 0.36.0.
 
-use vortex_edition::Edition;
-use vortex_edition::EditionDeclaration;
-use vortex_edition::EditionId;
+use crate::Edition;
+use crate::EditionDeclaration;
+use crate::EditionId;
 
 /// The first edition of the `core` family, matching the first stable Vortex file release.
 pub const CORE_2025_05_0: EditionId = EditionId::new("core", 2025, 5, 0);

vortex/src/editions/core/v2025_06.rs → vortex-edition/src/declarations/core/v2025_06.rs

@@ -3,9 +3,9 @@
 
 //! The `core` edition adding stable encodings released through June 2025.
 
-use vortex_edition::Edition;
-use vortex_edition::EditionDeclaration;
-use vortex_edition::EditionId;
+use crate::Edition;
+use crate::EditionDeclaration;
+use crate::EditionId;
 
 /// The June 2025 edition of the `core` family.
 pub const CORE_2025_06_0: EditionId = EditionId::new("core", 2025, 6, 0);

vortex/src/editions/core/v2025_10.rs → vortex-edition/src/declarations/core/v2025_10.rs

@@ -3,9 +3,9 @@
 
 //! The `core` edition adding stable encodings released through October 2025.
 
-use vortex_edition::Edition;
-use vortex_edition::EditionDeclaration;
-use vortex_edition::EditionId;
+use crate::Edition;
+use crate::EditionDeclaration;
+use crate::EditionId;
 
 /// The October 2025 edition of the `core` family.
 pub const CORE_2025_10_0: EditionId = EditionId::new("core", 2025, 10, 0);

vortex/src/editions/core/v2026_07.rs → vortex-edition/src/declarations/core/v2026_07.rs

@@ -3,9 +3,9 @@
 
 //! The `core` edition adding stable encodings released through July 2026.
 
-use vortex_edition::Edition;
-use vortex_edition::EditionDeclaration;
-use vortex_edition::EditionId;
+use crate::Edition;
+use crate::EditionDeclaration;
+use crate::EditionId;
 
 /// The July 2026 edition of the `core` family.
 pub const CORE_2026_07_0: EditionId = EditionId::new("core", 2026, 7, 0);

vortex/src/editions/core/v2026_08.rs → vortex-edition/src/declarations/core/v2026_08.rs

@@ -3,9 +3,9 @@
 
 //! The August 2026 core edition adding the canonical Map encoding.
 
-use vortex_edition::Edition;
-use vortex_edition::EditionDeclaration;
-use vortex_edition::EditionId;
+use crate::Edition;
+use crate::EditionDeclaration;
+use crate::EditionId;
 
 /// The August 2026 core edition containing canonical Map arrays.
 pub const CORE_2026_08: EditionId = EditionId::new("core", 2026, 8, 0);

vortex-edition/src/declarations/mod.rs

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+//! The first-party Vortex edition declarations, one module per edition.
+//!
+//! These are plain constants naming encodings by id, so they depend on nothing but the types
+//! in this crate. That keeps them cheap to read: tooling that only needs to know what an
+//! edition contains — `cargo run -p xtask -- generate-editions`, for one — can depend on
+//! this crate alone rather than on the whole of `vortex`.
+//!
+//! The `vortex` facade re-exports everything here and owns the session wiring: registering
+//! the declarations and selecting which of them the default writer may emit.
+
+pub mod core;
+pub mod unstable;
+
+use crate::EditionDeclaration;
+use crate::EditionFamily;
+
+/// The first-party edition families. Every family must be declared before its editions.
+pub static EDITION_FAMILIES: &[&EditionFamily] = &[&core::FAMILY, &unstable::FAMILY];
+
+/// The first-party Vortex edition declarations.
+pub static EDITION_DECLARATIONS: &[&EditionDeclaration] = &[
+    &core::v2025_05::DECLARATION,
+    &core::v2025_06::DECLARATION,
+    &core::v2025_10::DECLARATION,
+    &core::v2026_07::DECLARATION,
+    &core::v2026_08::DECLARATION,
+    &unstable::v2025_05::DECLARATION,
+    &unstable::v2026_02::DECLARATION,
+    &unstable::v2026_04::DECLARATION,
+    &unstable::v2026_06::DECLARATION,
+];

vortex-edition/src/declarations/unstable/mod.rs

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+//! The `unstable` edition family: opt-in encodings without a frozen compatibility guarantee.
+//!
+//! One module per draft edition, each declaring the encodings that join the family at it.
+//! Members of earlier editions are inherited and never restated.
+
+use crate::EditionFamily;
+
+/// The `unstable` family: opt-in encodings with no compatibility guarantee.
+pub static FAMILY: EditionFamily = EditionFamily {
+    name: "unstable",
+    doc: "Opt-in encodings that are still being evaluated. Every unstable edition stays a \
+draft, so the family never freezes and carries no compatibility guarantee: a file written \
+with these encodings is readable only by a build that knows them, and a later release may \
+stop supporting one. The writer emits them only when the `unstable_encodings` feature is \
+selected. An encoding graduates by joining a core edition.",
+};
+
+pub mod v2025_05;
+pub mod v2026_02;
+pub mod v2026_04;
+pub mod v2026_06;
+
+pub use v2025_05::UNSTABLE_2025_05_0;
+pub use v2026_02::UNSTABLE_2026_02_0;
+pub use v2026_04::UNSTABLE_2026_04_0;
+pub use v2026_06::UNSTABLE_2026_06_0;

vortex/src/editions/unstable/v2025_05.rs → vortex-edition/src/declarations/unstable/v2025_05.rs

@@ -3,9 +3,9 @@
 
 //! The May 2025 `unstable` encoding cohort.
 
-use vortex_edition::Edition;
-use vortex_edition::EditionDeclaration;
-use vortex_edition::EditionId;
+use crate::Edition;
+use crate::EditionDeclaration;
+use crate::EditionId;
 
 /// The May 2025 draft edition of the `unstable` family.
 pub const UNSTABLE_2025_05_0: EditionId = EditionId::new("unstable", 2025, 5, 0);

vortex/src/editions/unstable/v2026_02.rs → vortex-edition/src/declarations/unstable/v2026_02.rs

@@ -3,9 +3,9 @@
 
 //! The February 2026 `unstable` encoding cohort.
 
-use vortex_edition::Edition;
-use vortex_edition::EditionDeclaration;
-use vortex_edition::EditionId;
+use crate::Edition;
+use crate::EditionDeclaration;
+use crate::EditionId;
 
 /// The February 2026 draft edition of the `unstable` family.
 pub const UNSTABLE_2026_02_0: EditionId = EditionId::new("unstable", 2026, 2, 0);

vortex/src/editions/unstable/v2026_04.rs → vortex-edition/src/declarations/unstable/v2026_04.rs

@@ -3,9 +3,9 @@
 
 //! The April 2026 `unstable` encoding cohort.
 
-use vortex_edition::Edition;
-use vortex_edition::EditionDeclaration;
-use vortex_edition::EditionId;
+use crate::Edition;
+use crate::EditionDeclaration;
+use crate::EditionId;
 
 /// The April 2026 draft edition of the `unstable` family.
 pub const UNSTABLE_2026_04_0: EditionId = EditionId::new("unstable", 2026, 4, 0);

vortex/src/editions/unstable/v2026_06.rs → vortex-edition/src/declarations/unstable/v2026_06.rs

@@ -3,9 +3,9 @@
 
 //! The June 2026 `unstable` encoding cohort.
 
-use vortex_edition::Edition;
-use vortex_edition::EditionDeclaration;
-use vortex_edition::EditionId;
+use crate::Edition;
+use crate::EditionDeclaration;
+use crate::EditionId;
 
 /// The June 2026 draft edition of the `unstable` family.
 pub const UNSTABLE_2026_06_0: EditionId = EditionId::new("unstable", 2026, 6, 0);