feat: adopt the Vortex "editions" model (frozen encoding sets + writer edition guard)

[dfa1]

Context

Upstream merged vortex-data/vortex#8871, formalizing editions: frozen, additive, per-family sets of encoding IDs, each with a min_vortex_version read-compatibility floor. Spec: docs/specs/editions.md. It is wired but not yet public; a follow-up makes it the default write gate.

An edition is a frozen, named, additive set of encoding IDs carrying a forever read guarantee:

• Editions come in independently-versioned families: core (what the default writer emits) and unstable (opt-in, no guarantee). A writer targets at most one edition per family and may emit any encoding in their union.
• Each edition records a min_vortex_version — the earliest reader release supporting every encoding in it. Recording that version is the act of freezing; an edition with None is a mutable draft.
• Writer guarantee: if a write would emit an encoding outside the targeted edition, the write fails immediately — "edition violations never surface as someone else's read error later."
• Reader UX: an unknown-encoding error points at the registry, telling you which edition an ID joined and therefore which reader version you need.

Where vortex-java stands

We already implement every encoding in the core family through the latest frozen edition (core2026.07.0). So this is not about chasing encodings — it is about adopting the editions model itself (a frozen registry + a writer fail-fast guard + reader error UX), which we have no equivalent of today. Our WriteRegistry will emit any registered encoding, and our unknown-encoding read error carries no "which edition / which version" guidance.

Frozen core sets vs. our EncodingId.WellKnown:

Edition	min vortex	Adds	Supported?
core2025.05.0	0.36.0	23 baseline (primitive, bool, alp, fsst, dict, fastlanes.bitpacked/for, …)	✅ all
core2025.06.0	0.40.0	vortex.pco, vortex.sequence, vortex.zstd	✅ all
core2025.10.0	0.54.0	fastlanes.rle, vortex.fixed_size_list, vortex.listview, vortex.masked	✅ all
core2026.07.0	0.65.0	vortex.variant	✅ (ID present)
unstable (2025.05 → 2026.06)	draft	fastlanes.delta, vortex.patched, zstd_buffers, parquet.variant, tensor.*, onpair	partial (delta, patched)

Scope

1. Frozen edition registry (data + type). A small immutable model — EditionId (family/year/month/version, chronologically ordered within a family only) + Edition (minVortexVersion: Optional<String>, empty ⇒ draft) + additive membership data. Seed the four core and four unstable declarations from #8871. Membership is additive: an ID present in edition N is present in all later editions of the family. Back it with a golden test pinning each frozen edition's computed set (mirrors upstream's validate_edition harness) so a stray data edit fails CI.

2. Writer edition guard (the core value). Let WriteOptions target an edition (default: latest frozen core, possibly lagging by design). During encode, if the tree would contain an encoding outside the targeted edition's union, fail fast with a VortexException naming the offending ID and the edition — never silently write a file a conforming reader can't read. Support one edition per family (e.g. core + an unstable opt-in), plus an explicit "no edition / custom encodings" escape hatch.

3. Reader unknown-encoding UX. When ReadRegistry hits an unregistered ID (and allowUnknown is off), enrich the VortexException: if the ID is a known edition member, name the edition it joined and the min_vortex_version needed; if unknown to all editions, say so and point at allowUnknown. Mirrors the spec's "Resolving an unknown-encoding error" section.

Non-goals

• No new encodings (we already cover core). The unstable tensor/variant/zstd_buffers/onpair encodings stay out of scope — separate tickets if ever wanted.
• No ServiceLoader/auto-discovery — editions are registered explicitly on the builder, consistent with the existing registry design decision.
• Not blocking on upstream making editions public; we track the frozen data now and re-sync when their default flips.

Acceptance criteria

• Editions model + the 8 seeded declarations, with a golden test pinning frozen sets.
• WriteOptions.edition(...); writing an out-of-edition encoding throws a VortexException naming ID + edition; escape hatch tested.
• Reader unknown-encoding error names the edition + required version when applicable.
• Docs: docs/reference.md + docs/compatibility.md + CLAUDE.md design-decisions/module-map updated in the same PR; CHANGELOG entry.
• An adr/ note recording editions adoption and how it composes with ReadRegistry/WriteRegistry/allowUnknown.

Open questions

• Do we persist the targeted edition into file metadata, or is it write-time-only? (Upstream currently treats it as a writer constraint, not a file field.)
• Default target: latest frozen core vs. a deliberately-lagging one (upstream lags "by a few versions").

---

Upstream ref: vortex-data/vortex#8871 · editions spec

[dfa1]

Adopt the Vortex "editions" model (issue #301)

Context

Upstream Vortex (vortex-data/vortex PR #8871) formalized editions: frozen, named,
additive sets of encoding IDs, each carrying a forever read-compatibility guarantee. The
published spec (docs/specs/editions.md) documents the concept but its own "Edition
registry" section literally says "Coming soon" — the concrete data isn't public yet. I
fetched the actual ground truth directly from the Rust source in PR #8871
(vortex-edition/src/lib.rs, vortex/src/editions/{core,unstable}/*.rs) rather than
guess at it.

vortex-java already implements every encoding in every frozen core edition (100%
coverage through core2026.07.0). So this isn't about chasing new encodings — it's about
adopting the editions model itself: a frozen registry, a writer fail-fast guard ("never
write a file a conforming reader can't read"), and reader error UX that names which edition
an unknown encoding belongs to. We have no equivalent of any of this today.

Ground-truth data (from vortex-data/vortex PR #8871, verified against vortex-java's actual EncodingId.WellKnown)

core family (frozen, has min_vortex_version):

Edition	min vortex	Adds
core2025.05.0	0.36.0	23 baseline: fastlanes.bitpacked/for, vortex.alp/alprd/bool/bytebool/chunked/constant/datetimeparts/decimal/decimal_byte_parts/dict/ext/fsst/list/null/primitive/runend/sparse/struct/varbin/varbinview/zigzag
core2025.06.0	0.40.0	vortex.pco, vortex.sequence, vortex.zstd
core2025.10.0	0.54.0	fastlanes.rle, vortex.fixed_size_list, vortex.listview, vortex.masked
core2026.07.0	0.65.0	vortex.variant

unstable family (draft, min_vortex_version = none):

Edition	Adds	vortex-java implements?
unstable2025.05.0	fastlanes.delta	✅
unstable2026.02.0	vortex.zstd_buffers	❌
unstable2026.04.0	vortex.parquet.variant, vortex.patched, vortex.tensor.{cosine_similarity,inner_product,l2_denorm,l2_norm}	vortex.patched ✅, rest ❌
unstable2026.06.0	vortex.onpair	❌

All 31 core-family encodings already have an EncodingId.WellKnown constant. Of
unstable, only fastlanes.delta/vortex.patched do. The catalog stores membership as
Set<EncodingId> built via EncodingId.parse(rawId) — which already falls back to
EncodingId.Custom for ids with no WellKnown constant — so the catalog is a faithful,
future-proof mirror of upstream even for encodings we don't implement yet.

Design

New types — core/src/main/java/io/github/dfa1/vortex/core/model/

Rust's model has 4 types (EditionId, Edition, EditionInclusion, EditionDeclaration)
plus a mutable cross-crate registration session, because any Rust crate can register a
declaration. vortex-java's registries are explicit/closed (no ServiceLoader — matches the
existing ReadRegistry/WriteRegistry design decision), so this collapses to 3 types:

• EditionId — record EditionId(String family, int year, int month, int version).

  • toString(): family + year + "." + %02d(month) + "." + version (e.g.
    "core2025.05.0" — month zero-padded, version not, matching Rust's Display exactly).
  • isAtOrBefore(EditionId other): family.equals(other.family) && (year,month,version) <= (other's), lexicographic tuple compare. Cross-family is always false.
  • Compact constructor validates family (non-empty, lowercase ASCII), year (4-digit), month
    (1-12) via IllegalArgumentException — not VortexException: this is a
    programmer-error check on a value that never comes from untrusted file bytes (editions
    are a client-side write/read policy, not part of the wire format), so it doesn't fall
    under the "malformed input → VortexException" security contract.

• Edition — record Edition(EditionId id, Optional<String> minVortexVersion, Set<EncodingId> added).

  • Folds Rust's separate Edition/EditionDeclaration into one type (we don't need its
    decentralized-registration flexibility). added is only what joins at this edition,
    not cumulative — matches Rust's own field exactly.
  • isDraft() → minVortexVersion.isEmpty().
  • Compact constructor does added = Set.copyOf(added) (defensive immutability, matching
    codebase convention).
  • Plain public record, not sealed — a user can construct their own Edition for a
    private/custom encoding family later (consistent with "explicit code-level
    registration, no plugin system"). Documented as best-effort: a non-catalog Edition's
    cumulativeMembers is just its own added() (no known lineage to accumulate from).

• Editions — final utility class (private constructor), the catalog:

  • 8 public static final Edition constants (CORE_2025_05_0 … CORE_2026_07_0,
    UNSTABLE_2025_05_0 … UNSTABLE_2026_06_0), each built via EncodingId.parse(...)
    over the ground-truth id lists above.
  • public static final List<Edition> ALL in declared order (order matters for
    owningEdition).
  • static Set<EncodingId> cumulativeMembers(Edition edition): seed the result with
    edition.added() itself, then union in every ALL entry with the same family where
    .id().isAtOrBefore(edition.id()) — the seed step is what makes this correct for a
    user-supplied non-catalog Edition too, not just the 8 built-ins.
  • static Optional<Edition> owningEdition(EncodingId id): first entry in ALL (declared
    order) whose added() contains id — correct because membership is additive and each
    encoding belongs to exactly one family, so the first declaration listing it is
    unambiguously the "since" edition (mirrors how Rust itself derives this).

WriteOptions integration — writer/src/main/java/io/github/dfa1/vortex/writer/WriteOptions.java

Currently a plain 7-field record (chunkSize, enableZoneMaps, compressionRatioThreshold, allowedCascading, globalDict, enableZstd, globalDictMaxRetainedBytes) with defaults()/
cascading(int) factories and withXxx copy-methods, no compact constructor.

• Add 8th component: Map<String, Edition> editions (family → enabled edition; a Map
  makes "at most one edition per family" structural, not something to separately
  validate). Compact constructor does editions = Map.copyOf(editions).
• defaults() / cascading(int): populate with Map.of("core", Editions.CORE_2026_07_0).
  This is safe as a new default, not just a good idea — traced buildCascadeCodecs
  in VortexWriter.java (the candidate-encoder list every real default write uses): it
  does not include DeltaEncodingEncoder/PatchedEncodingEncoder (the only two
  unstable-family encoders vortex-java implements), so no default-config write today can
  emit an unstable encoding. vortex-java also already implements 100% of core, unlike
  upstream Rust (which lags "by a few versions" to hedge against readers not having caught
  up to encodings it just shipped) — so "latest frozen core" has no analogous risk here
  and avoids an arbitrary "how many versions to lag" choice.
• Add withEdition(Edition edition): copy with edition.id().family()'s map entry
  replaced (mirrors upstream: "enabling another edition from the same family replaces
  the earlier selection").
• Add withoutEditionGuard(): copy with an empty map — the explicit escape hatch (matches
  upstream's "opt out entirely" / "custom encodings" case). Preferred over overloading
  withEdition(null) — explicit over clever.
• Update the 4 existing withXxx methods' positional reconstruction to pass editions
  through unchanged.

Required companion fix — not optional, will break CI otherwise: three existing test
files deliberately write unstable-family encoders through
VortexWriter.create(channel, schema, WriteOptions.defaults(), List.of(encoder)) (the
4-arg overload with an explicit encoder list), which bypasses buildCascadeCodecs entirely
and does select the encoder from the explicit list:

• writer/src/test/java/io/github/dfa1/vortex/writer/DeltaEncodingTest.java (7 call sites)
• integration/src/test/java/io/github/dfa1/vortex/integration/JavaWritesRustReadsIntegrationTest.java (~L1049)
• integration/src/test/java/io/github/dfa1/vortex/integration/JavaRoundTripIntegrationTest.java (~L53)

Append .withoutEditionGuard() to the WriteOptions.defaults() at all 9 sites.

Mechanical fallout — the record's positional constructor: new WriteOptions(...) is
called directly (not via defaults()/cascading()) at 29 sites across 12 files
(calcite/integration/writer test modules + one performance benchmark). Adding an 8th
component breaks compilation at all of them (compiler-enforced, no silent drift). None of
these exercise unstable-family encodings, so the safe, explicit, zero-behavior-change
value to add at every one of these 29 sites is a literal Map.of() (no guard) — this
exactly preserves "no guard existed before" rather than trying to audit whether
core2026.07.0 happens to still cover each test's data. Only defaults()/cascading()
opt into the real default (Map.of("core", Editions.CORE_2026_07_0)).

Writer guard — writer/src/main/java/io/github/dfa1/vortex/writer/VortexWriter.java

writeSegment(...) produces an EncodeResult, then registerEncodingIds(result.rootNode())
(~L669) recursively walks the whole produced EncodeNode tree (~L703-708), registering
every encoding id actually emitted into the footer's encoding table — this already visits
every id a write will emit, at every nesting level (so a vortex.masked-wraps-vortex.fsst
tree gets both levels checked automatically, no extra work needed).

• In the constructor, precompute once (not per segment/call):
  Set<EncodingId> editionAllowed = union of Editions.cumulativeMembers(e) over
  all options.editions().values() (not just one family — a writer may enable both
  core and unstable simultaneously). Empty options.editions() ⇒ editionAllowed is
  empty ⇒ guard is off entirely.
• In registerEncodingIds, before/inside registering a node's id: if the guard is on and
  !editionAllowed.contains(id), throw VortexException(id, message). Proposed message
  (uses the attributed constructor, which already prefixes id.id() + ": " — don't repeat
  the id in the body):

  "outside the configured edition(s) [" + <configured edition ids, joined> + "]"
      + (Editions.owningEdition(id) is present
           ? "; it joins " + owning.id() + (owning.isDraft()
               ? " (draft, no compatibility guarantee)"
               : " (requires reader >= " + owning.minVortexVersion().get() + ")")
             + " — enable it via WriteOptions.withEdition(...)"
           : "; it is not part of any known edition")
      + ", or call WriteOptions.withoutEditionGuard() to opt out"
  

Reader UX — reader/src/main/java/io/github/dfa1/vortex/reader/ReadRegistry.java

Two throw sites currently say "no decoder registered for " + node.encodingId().id()"
using the plain-message VortexException constructor (not the attributed
(EncodingId, String) one): decode(DecodeContext) (~L127) and decodeAsSegment (~L140-141,
which also has no allowUnknown branch at all today — leave that gap alone, it's a separate
behavioral change, not in scope here).

• Both sites: switch to new VortexException(node.encodingId(), message) and drop the
  redundant id from the message body (the constructor already prefixes it). Consult
  Editions.owningEdition(node.encodingId()) first:

  present:  "no decoder registered (joined edition " + owning.id()
              + (owning.isDraft() ? ", draft — no compatibility guarantee yet"
                                   : ", requires reader >= " + owning.minVortexVersion().get())
              + "); register a decoder or enable ReadRegistry.Builder#allowUnknown()"
  absent:   "no decoder registered; unknown to all editions (custom/experimental encoding)"
              + " — register a decoder or enable ReadRegistry.Builder#allowUnknown()"
  

No wire-format changes

The targeted edition(s) are a write-time-only policy — resolves the issue's own open
question ("persist edition into file metadata, or write-time-only?"). Matches upstream's
model exactly ("stored on the writer's session," not a file field). No .fbs/.proto
schema touched anywhere in this feature.

Tests

• core/.../model/EditionIdTest.java — toString() format (2-digit month, non-padded
  version), isAtOrBefore ordering incl. cross-family always-false, constructor
  validation edge cases.
• core/.../model/EditionsTest.java — golden test pinning each of the 8 editions'
  cumulativeMembers() (mirrors upstream's own validate_edition harness; required by
  the issue's acceptance criteria so a stray data edit fails CI), plus owningEdition for a
  core id, an unstable id, and a genuinely-unknown custom id.
• writer/.../WriteOptionsTest.java — withEdition per-family-replace semantics (a second
  core edition replaces; a core + unstable combo keeps both), withoutEditionGuard()
  clears both.
• New writer/.../WriterEditionGuardTest.java — write data that would select a
  later-edition-only (or nested/wrapped) encoding with only an earlier edition enabled →
  VortexException naming id + edition; same write with withoutEditionGuard() → succeeds.
• reader/.../ReadRegistryTest.java (or wherever the existing unknown-encoding case lives)
  — both message branches, asserting the thrown exception carries the EncodingId.

Docs / ADR / CHANGELOG (same PR — per CLAUDE.md, docs are never a follow-up)

• New ADR adr/0023-vortex-editions-adoption.md (MADR template, matching
  adr/0014-variant-encoding-strategy.md/adr/0022-fsst-module-extraction.md style) +
  new row in adr/ADR.md's index.
• docs/reference.md: EditionId/Edition/Editions rows under
  ### Identity types; new ## Editions section (after ## Encoding registry) covering
  the 3 types + WriteOptions integration + the default-core2026.07.0 rationale; true up
  the already-stale ### WriteOptions field table (currently missing globalDict,
  enableZstd, globalDictMaxRetainedBytes, and now editions).
• docs/compatibility.md: rewrite ### Unknown encodings for the new message; add an
  edition-registry table (8 editions × members) near ## Encodings.
• CLAUDE.md: core.model line in Module structure gets EditionId, Edition, Editions;
  one new bullet under ## Design decisions stating editions are a client-side write/read
  policy, not part of the wire format.
• CHANGELOG.md: new ### Added entry under [Unreleased].

Verification

• ./mvnw verify -DskipTests (full reactor compile — will surface every one of the 29
  mechanical WriteOptions call-site breaks immediately).
• ./mvnw -pl core,writer,reader -am test (new EditionIdTest/EditionsTest/
  WriteOptionsTest/WriterEditionGuardTest/ReadRegistry cases, plus the existing
  DeltaEncodingTest suite to confirm the .withoutEditionGuard() fix works).
• ./mvnw verify -pl integration -am (JavaWritesRustReadsIntegrationTest,
  JavaRoundTripIntegrationTest — confirm the two updated call sites still round-trip).
• ./mvnw javadoc:javadoc -pl core must produce zero output (new public types have full
  Javadoc per the project's failOnError/failOnWarnings convention).
• Manual sanity via the CLI: write a file with WriteOptions.defaults() (guard on,
  succeeds normally), then force an unstable-only encoder through the explicit-encoder-list
  overload without withoutEditionGuard() and confirm the VortexException message reads
  as designed.

PR scoping

One PR. The 3 new core.model types, the WriteOptions field, the writer guard, and the
reader message enrichment are one coherent, small feature — splitting would leave an
intermediate PR with unused types or a field with no guard behind it. Docs/ADR/CHANGELOG
land in the same PR per this repo's explicit rule. The 29-call-site mechanical update is
compiler-forced and behavior-preserving (Map.of() everywhere) — called out clearly in the
PR description as "mechanical, no behavior change" for reviewer skimming, but not worth its
own PR.