Unions

[philpax]

Closes #119.

A union is a set of competing readings of the same bytes. Two forms:

/// A value whose bytes have several competing readings.
#[copyable]
pub union Payload {
    /// Read as a signed integer.
    pub as_int: i32,
    pub as_float: f32,
    pub as_ptr: *mut void,
}

pub type Scratch {
    pub tag: u16,
    pub _reserved: unknown<0x6>,

    // inline; the field name supplies the generated item's name
    pub data: union {
        pub as_u64: u64,
        pub as_bytes: [u8; 8],
    },
}

Discriminant-driven member selection stays out of scope, per the issue. A union says what the bytes could be; the consumer decides which reading applies.

Design

A union is a new item kind, not a new kind of Region. Region carries no offset — a Vec<Region>'s order is the layout, and six independent accumulators recompute offsets by summing sizes (resolve.rs's Regions::push, the alignment sweep in type_definition/build.rs, generic folding in type_registry/aliases.rs, json/convert.rs, the LSP's field_offset, and the viewer's FieldSourceView). Teaching all six about overlapping regions is where the bugs would live. A self-contained UnionDefinition with its own size and alignment, held by a parent as one perfectly ordinary Region, leaves every one of those assumptions true — and being a distinct struct rather than TypeDefinition { is_union: true } turns each of the ~30 exhaustive match sites into a compile error rather than a silent fallthrough.

Inline unions become module-scope siblings named {Type}{Field}Union, mirroring the generated {Name}Vftable structs. A genuinely nested path isn't available: ResolutionContext::add_item resolves an item's parent directly against the module map, and declaring_module only learns nested paths through the grammar walks that populate item_scopes — so a generated nested item would be dropped from every module and reach no backend.

Alignment defaults differently from a type's. A type with no implied alignment falls back to the pointer size; a union of two u8s is genuinely 1-aligned, and widening it would inflate its size.

Lowering

• Rust — a real union, every member in ManuallyDrop<T> unconditionally (so a member's spelling doesn't depend on whether its type happens to be #[copyable]), with hand-written Debug and, under #[defaultable], Default. A union can derive neither; emitting them anyway is what keeps a containing struct's own #[derive(Debug, Default)] working.
• C++ — a native union, with alignas, #pragma pack, static_asserts on size and alignment, and deleted special members when #[pinned].
• JSON — a Union item kind at schema v12, every member at offset: 0.

Rejections

#[base], vftable blocks, #[address] on a member, a member named _, an empty body, a member larger than #[size], and nested declarations inside an inline union (whose item is synthesised after the walks that would register them — declare it in the enclosing type, or name the union).

Generated-name collisions (second commit)

Reviewing the union work turned up that this isn't a union problem — {Name}Vftable has the same hazard and predates it. This compiles today:

pub type FooVftable { pub sentinel: [u8; 64], }
pub type Foo { vftable { pub fn f(&mut self); }, }

The registry is a map, so the generated table loses the insert. Foo::vftable() hands back a pointer to the user's 64-byte struct, and nothing anywhere says so. The union case at least failed to compile, via a size-check transmute.

The check now lives in ResolutionContext::add_generated_item, which both synthesis sites use, so it covers {Name}Vftable and {Type}{Field}Union alike — a declared item, another generated one, two fields whose names differ only in underscores (b_c/b__c), or two types meeting in the middle (A+b_c and AB+c both give ABCUnion). docs/language.md gains a Generated names section, since the rule is now uniform.

No pyxis-defs project trips it.

#[size]/#[min_size] asking for more room than any member needs adds a whole-width _padding member: a union has no tail to pad, and without it both backends would emit a size assertion they cannot satisfy. Rounding up to the alignment needs no such help — Rust and C++ do that for a union themselves.

Surfaces

Parser, tokenizer, semantic IR, all three backends, pretty-printer, doc-link resolver, tree-sitter grammar (pushed to ferrobrew/tree-sitter-pyxis as 48eb1b7, with the submodule and extension.toml re-pinned), LSP (completion, hover, outline, references, navigation), the viewer, and docs/language.md / rust_backend.md / cpp_backend.md / json_backend.md.

Verification

• python test.py green, including the doxygen pass under nix-shell — the emitted Rust crate and C++ corpus both compile, cargo doc resolves doc links into union members, and pyxis fmt --check confirms the new corpus input is format-stable.
• 24 semantic unit tests covering layout, every attribute, and every rejection path.
• 23/23 tree-sitter corpus tests; parser regenerated at ABI 14, as Zed's bundled runtime requires.
• tools/check-pyxis-defs.py green for both rust and cpp across all four pyxis-defs projects — no project uses unions yet, so it's a pure regression check that the new item kind didn't disturb existing output.

Known limitation, pre-existing

A field cannot reference a nested type by name, bare or qualified — pub header: Outer::Header fails for a plain type too, not just a union. The corpus input works around it. Worth its own issue.