Section 07: Enum Representation Optimization

Context: Today, Ori enums use {i64 tag, [M x i64] payload} — every enum has a full i64 tag plus the maximum variant payload (padded to i64 word size). This wastes memory:

Option<int>: 16 bytes (i64 tag + i64 value) → could be 8 bytes via niche or tagged pointer
Option<bool>: 16 bytes (i64 tag + padded i1 value) → could be 1 byte (value 2 = None)
Option<str>: 32 bytes (i64 tag + 24-byte str payload) → could be 24 bytes (null ptr = None)
Option<[int]>: 32 bytes (i64 tag + 24-byte list payload) → remains 32 bytes (empty lists use null data ptr — no niche available)
All-unit enum with N variants: 8 bytes (i64 tag only, no payload) → could be 1 byte (i8 tag)

Rust’s niche optimization is the gold standard. We study and match it.

Reference implementations:

Rust compiler/rustc_abi/src/layout.rs: Niche struct with available(), reserve() — tracks invalid bit patterns per type
Rust compiler/rustc_abi/src/lib.rs: NaiveLayout, LayoutData, Variants::Multiple
Swift lib/IRGen/GenEnum.cpp: Multi-payload enum layout with spare bits analysis

Depends on: §04 (narrowed integer types create new niches — e.g., a narrowed i8 field with range [0, 2] has 253 unused values as niches), §05 (float-narrowed fields may have niche patterns — e.g., f32 has NaN spare bits usable for Option optimization, though the value must be checked carefully against IEEE 754 NaN semantics before use).

Terminology: This section uses “tag” and “discriminant” with the following distinction: the discriminant is the logical variant index (0, 1, 2, …) that identifies which variant an enum value holds. The tag is the physical encoding of the discriminant in memory — this may be an explicit integer field (EnumTag::Explicit), a niche value in an existing field (EnumTag::Niche), bits stolen from a pointer (EnumTag::Tagged), or absent entirely (EnumTag::None for single-variant enums). TagAccess abstracts over all tag encodings; it loads/stores discriminants regardless of how the tag is physically encoded.

07.0 Prerequisites: Codegen Consumer Inventory

Context: Changing the enum tag from i64 to a narrowed width (i8/i16) or a niche encoding requires updating EVERY codegen consumer that reads/writes enum tags or accesses variant payloads. Missing any one consumer causes silent data corruption. This is the same coordination problem as §06 field reordering.

Codegen consumers that emit/read enum tags (ALL must be updated for §07):

layout_resolver.rs → resolve_enum() — constructs the LLVM struct type. Currently {i64 tag, [M x i64] payload}. Must emit narrowed tag type (i8/i16/i32) for discriminant narrowing, and entirely different layouts for niche-optimized enums.
arc_emitter/construction.rs → emit_construct() — stores tag via const_i64(variant). Must use narrowed constant width and niche-based construction for niche-optimized enums.
arc_emitter/instr_dispatch.rs → ArcInstr::SetTag — stores tag via const_i64(*tag) + GEP to field 0. Must use narrowed width and write to niche location for niche-optimized enums.
arc_emitter/instr_dispatch.rs → ArcInstr::Project { field: 0 } — extracts tag as i64 from field 0. Must extract narrowed-width tag and decode niche.
arc_emitter/instr_dispatch.rs → ArcTerminator::Switch — emits LLVM switch on i64 scrutinee. Must switch on narrowed tag or niche-decoded discriminant.
arc_emitter/drop_enum.rs → emit_enum_drop() — loads i64 tag at field 0, switches on it, drops per-variant fields at i64-slot offsets. Must use narrowed tag and correct payload offsets.
arc_emitter/rc_helpers.rs → emit_inline_enum_inc/dec() — loads i64 tag, switches per-variant for field RC ops. Must use narrowed tag.
arc_emitter/rc_value_traversal.rs → emit_inline_enum_inc/dec() — same pattern as rc_helpers.
arc_emitter/builtins/option_result.rs — Option/Result-specific builtins hardcode {i64 tag, T payload} layout. Must handle niche-optimized layout.
arc_emitter/builtins/compound_traits.rs — Eq/Comparable/Debug etc. for Option/Result hardcode tag-first layout.
arc_emitter/builtins/compound_type_impls.rs — clone/hash/etc. for Option/Result.
arc_emitter/builtins/iterator_consumers.rs — constructs Option from iterator next.
arc_emitter/builtins/collections/list_builtins.rs — first()/last() return Option with hardcoded layout.
arc_emitter/variant_construction.rs — variant construction for Option/Result/Enum.
codegen/abi/mod.rs — ABI size computation references {i64 tag, payload}.
arc_emitter/operators/strategy.rs → emit_coalesce() — ?? operator extracts tag via extract_value(lhs, 0, "coal.tag") + compares with const_i64(0). Must use TagAccess for niche-aware tag comparison.

Strategy: Introduce a TagAccess helper in ori_llvm that encapsulates tag read/write/switch for a given EnumRepr. Codegen consumers call TagAccess::load_discriminant(), TagAccess::store_tag(), TagAccess::emit_switch() instead of hardcoding i64 GEP+load+switch. This localizes the tag encoding change to one place.

/// Encapsulates all tag encoding/decoding for a given enum layout.
/// Lives in `ori_llvm::codegen::arc_emitter::tag_access.rs`.
pub struct TagAccess<'a, 'll> {
    enum_repr: &'a EnumRepr,
    builder: &'a IrBuilder<'ll>,
}

impl<'a, 'll> TagAccess<'a, 'll> {
    /// Load the discriminant value from an enum pointer.
    /// For Explicit tags: GEP to field 0, load with narrowed width.
    /// For Niche tags: load the niche field, decode to discriminant.
    /// For None: returns a constant 0 (single-variant).
    pub fn load_discriminant(&self, enum_ptr: ValueId) -> ValueId;

    /// Store a tag for a given variant index.
    /// For Explicit: store narrowed-width constant at field 0.
    /// For Niche: store the niche value if this is the niche variant,
    ///            otherwise the payload write implicitly sets the tag.
    /// For None: no-op.
    pub fn store_tag(&self, enum_ptr: ValueId, variant_idx: u32);

    /// Emit an LLVM switch on the discriminant.
    /// For Explicit: switch on narrowed-width tag.
    /// For Niche: compare niche field against niche value, branch.
    /// For None: unconditional branch to the single variant.
    pub fn emit_switch(
        &self, enum_ptr: ValueId,
        cases: &[(u32, BlockId)],
        default: BlockId,
    );

    /// Get the LLVM type for the tag (i8/i16/i32/i64 or none).
    pub fn tag_llvm_type(&self) -> Option<BasicTypeEnum<'ll>>;

    /// Get the GEP offset to the payload for a given variant.
    /// For Explicit tags: always after the tag field.
    /// For Niche tags: offset 0 (payload IS the entire value).
    pub fn payload_offset(&self, variant_idx: u32) -> u32;
}

ABI module stale comments (abi/mod.rs): The abi_size_inner() function in codegen/abi/mod.rs has comments saying “1 byte tag” but the actual LLVM layout uses i64. The comments and size computation must be updated alongside the tag width change in §07.1. This is consumer #16 (not listed in the original inventory).

TagAccess data source: ArcIrEmitter already has repr_plan: Option<&ReprPlan> (line 214 in arc_emitter/mod.rs). TagAccess obtains EnumRepr via repr_plan.get_repr(type_idx) → match MachineRepr::Enum(e) → use e.tag to determine encoding strategy. For types without a ReprPlan entry (pre-§07 or when repr_plan is None), fall back to EnumTag::Explicit { width: IntWidth::I64 } (the current default). This fallback path ensures backward compatibility during incremental migration.

Evaluator is unaffected: ori_eval uses Value::Variant { tag, fields, ... } — a Rust-native enum representation with no concept of machine layout, niches, or tag widths. All §07 optimizations are LLVM-only. The evaluator does not need any changes, and dual-execution parity tests (interpreter vs LLVM) verify that the optimized layout produces identical observable behavior.

Audit ALL codegen consumers listed above and verify completeness. Found 16 direct consumers (items 1-16). Consumer #16 (operators/strategy.rs → emit_coalesce()) was discovered during audit — ?? operator extracts tag via extract_value(lhs, 0). Note: terminators.rs Switch already adapts to scrutinee width via const_int_matching(). compound_traits.rs delegates to compound_type_impls.rs (indirect). rc_value_traversal.rs delegates to rc_helpers.rs (indirect). (2026-03-30)
[BUG] abi/mod.rs:165-182 — abi_size_inner for TypeInfo::Enum returned 1 for all-unit enums but actual LLVM layout is { i64 } = 8 bytes. Fixed: all-unit enum size now returns 8. Stale “1 byte tag” comments replaced with “i64 tag”. Regression test all_unit_enum_abi_size_is_tag_size added. (2026-03-30)
Design TagAccess abstraction in compiler/ori_llvm/src/codegen/arc_emitter/tag_access/mod.rs (~150 lines). TagEncoding struct with pure encoding logic for Explicit/Niche/None tags. 11 methods: from_enum_repr, new, tag_width, tag_gep_index, variant_to_tag_value, payload_gep_index, needs_tag_store, is_niche, is_tagless, niche_field_index, niche_value. Wired into arc_emitter/mod.rs via pub(super) mod tag_access;. (2026-03-30)
Create empty files for new modules: compiler/ori_repr/src/layout/niche.rs (niche analysis) and compiler/ori_repr/src/layout/tagged_ptr.rs (tagged pointer analysis). Registered in layout/mod.rs via pub(crate) mod niche; and pub(crate) mod tagged_ptr;. Module docs added. (2026-03-30)
ARC IR tag width assumption: Documented in TagEncoding design. ArcTerminator::Switch already adapts to scrutinee width via const_int_matching(). ArcInstr::SetTag must be updated to use TagEncoding::variant_to_tag_value() + narrowed-width constant in §07.1. (2026-03-30)
Plan incremental migration: discriminant narrowing (§07.1) BEFORE niche filling (§07.2). Subsections already reordered by plan review. (2026-03-30)

§07.0 Tests (TDD — write before implementation):

Rust unit tests (compiler/ori_llvm/src/codegen/arc_emitter/tag_access/tests.rs): 22 tests covering all 3 EnumTag variants: Explicit {I64/I8/I16} (tag_width, tag_gep_index, variant_to_tag_value, payload_gep_index, needs_tag_store), Niche (field_index, niche_value, niche-vs-non-niche variant semantics), None (tagless, constant 0, no-op store). Plus from_enum_repr integration test. All pass. (2026-03-30)
ABI bug regression test (compiler/ori_llvm/src/codegen/abi/tests.rs): all_unit_enum_abi_size_is_tag_size asserts abi_size == 8 (not 1). enum_with_payload_abi_size asserts abi_size == 16. Both pass. (2026-03-30)
TDD verified: ABI regression test failed before fix (returned 1), passed after fix (returns 8). TagEncoding tests pass on initial implementation. (2026-03-30)

07.1 Discriminant Narrowing

File(s): compiler/ori_repr/src/enum_repr.rs (existing — add min_tag_width() here near EnumTag), compiler/ori_llvm/src/codegen/arc_emitter/tag_access.rs (new), compiler/ori_llvm/src/codegen/type_info/layout_resolver.rs (update resolve_enum()), compiler/ori_repr/src/canonical/type_repr.rs (update canonical_enum()/canonical_option()/canonical_result()), compiler/ori_llvm/src/codegen/abi/mod.rs (fix abi_size_inner())

Why first: Discriminant narrowing is the safest starting point because the tag remains an explicit field at offset 0 — only its width changes (i64 -> i8/i16/i32). The layout structure {tag, payload} is preserved. This makes it the ideal first consumer of the TagAccess abstraction from §07.0, validating the abstraction before niche filling changes the layout structure entirely.

The discriminant (tag) should use the minimum width needed.

Compute minimum tag width: (2026-03-30)

pub fn min_tag_width(variant_count: usize) -> IntWidth {
    match variant_count {
        0 | 1 => IntWidth::I8, // single variant or empty → minimal tag (or EnumTag::None)
        n => {
            // Bits needed = ceil(log2(n)), computed without floating point:
            // (n - 1).leading_zeros() counts unused high bits in usize;
            // usize::BITS - leading_zeros = bits needed.
            let bits_needed = usize::BITS - (n - 1).leading_zeros();
            match bits_needed {
                0..=8 => IntWidth::I8,    // up to 256 variants
                9..=16 => IntWidth::I16,  // up to 65536 variants
                17..=32 => IntWidth::I32, // up to 4 billion variants
                _ => IntWidth::I64,
            }
        }
    }
}

Tag narrowed from i64 to i8 for USER-DEFINED enums with ≤256 variants via resolve_enum(). (2026-03-30)
Option/Result tag narrowing — Option/Result keep i64 tags for ori_rt runtime compatibility.
For single-variant enums (newtypes), eliminate tag entirely (EnumTag::None) — implemented in §07.2 (canonical_enum emits EnumTag::None when variants.len() == 1, resolve_enum_tagless omits tag field). (2026-03-31)
Added min_tag_width() to compiler/ori_repr/src/enum_repr.rs with 7 boundary-value unit tests. (2026-03-30)
TagEncoding abstraction implemented in tag_access/mod.rs (§07.0). Consumer migration used const_int_matching + struct_field_type + const_int_for_struct_field helpers instead of full TagAccess LLVM emission — simpler and equally correct. (2026-03-30)
All 16 codegen consumers migrated from hardcoded const_i64/type_i64 to narrowed tag types. Changes across 15 files: construction.rs, instr_dispatch.rs, drop_enum.rs, rc_helpers.rs, variant_construction.rs, option_result.rs, compound_type_impls.rs, iterator_consumers.rs, list_builtins.rs, operators/strategy.rs, enum_eq.rs, enum_comparable.rs, enum_hashable.rs, abi/mod.rs, layout_resolver.rs. Key helpers added: IrBuilder::struct_field_type(), IrBuilder::const_int_for_struct_field(), IrBuilder::const_i16(), IrBuilder::i16_type(). (2026-03-30)
Updated resolve_enum() — uses min_tag_width(variants.len()) to emit narrowed i8/i16/i32/i64 tag type. (2026-03-30)
Updated abi_size_inner() — uses min_tag_width().size_bytes() for tag size. (2026-03-30)
Updated canonical_enum(), canonical_option(), canonical_result() — all use min_tag_width(). Non-unit enum sizes unchanged (LLVM [M x i64] padding absorbs the difference). All-unit enum sizes shrink from 8 to 1. (2026-03-30)
All-unit enum path preserved: resolve_enum() emits { i8 } (no payload array). (2026-03-30)
[BLOAT] compound_type_impls.rs (519→4 files): mod.rs (15), option.rs (102), result.rs (246), str_map.rs (91), tuple.rs (112). All under 500. (2026-03-30)
[BLOAT] list_builtins.rs (712→3 files): mod.rs (356), helpers.rs (157), sort_thunks.rs (229). All under 500. (2026-03-30)
./test-all.sh passes: 14,678 tests, 0 failures. Debug and release builds verified. (2026-03-30)

§07.1 Tests (TDD — write BEFORE implementation, verify they fail):

Rust unit tests: min_tag_width boundary tests (7 tests in layout/tests.rs), canonical_enum updated to expect I8 tag, canonical_option_int updated to expect I8 tag, all-unit enum size = 1, ABI tests updated. 22 TagEncoding tests. All pass. (2026-03-30)
Ori spec tests (tests/spec/types/sum/test_discriminant_narrowing.ori) — 12 tests: all-unit enum match, Option int/str match, Result match, for-yield with Option, closure capturing Option, ? on Result, nested enum match, Option predicates, Result predicates, unwrap_or, coalesce ??. All pass. (2026-03-30)
AOT tests (compiler/ori_llvm/tests/aot/enum_discriminant.rs) — 6 tests: IR inspection (all-unit enum { i8 } type, Option i64 runtime-compat), behavioral (all-unit match, Option match, Result match, RC payload enum). All pass. (2026-03-30)
Dual-execution parity: 14,666 tests pass in both interpreter and LLVM. (2026-03-30)
Leak check: Valgrind 87/90 pass (3 failures are pre-existing COW bugs BUG-05-001). diagnose-aot.sh on custom enum test: compilation pass, execution clean, leak check clean. No regressions from discriminant narrowing. (2026-03-30)
Subsection close-out (07.1) — Retrospective 07.1: no tooling gaps. The subsection’s work was a mechanical tag-width migration verified by IR-level AOT assertions (enum_discriminant.rs) and the full test suite. ir-dump.sh + existing AOT tests were sufficient. A forward-looking type-layout inspector would benefit §07.2/07.4 but was not a friction point for §07.1. Status updated to complete. (2026-04-09)

07.2 Niche Filling

File(s): compiler/ori_repr/src/layout/niche.rs (new, ~200 lines — Niche struct, find_niches(), find_enum_niches(), optimize_option_repr(), optimize_result_repr()), compiler/ori_repr/src/enum_repr.rs (add EnumTag::Niche support — already defined), compiler/ori_repr/src/canonical/type_repr.rs (update canonical_option()/canonical_result() to call niche optimization), compiler/ori_llvm/src/codegen/arc_emitter/tag_access/mod.rs (extend for niche encoding)

Depends on: §07.1 (the TagAccess abstraction must be implemented and validated with explicit narrowed tags before niche encoding changes the layout structure)

A “niche” is an invalid bit pattern in a type. If an enum variant’s payload has a niche, we can use it to encode a different variant, eliminating the explicit tag.

Layout boundary note: Internal runtime representations such as FatPointer, str, [T], {K:V}, Set<T>, closures, and ranges are exempt from §06 field reordering. They are represented by dedicated MachineRepr / TypeInfo variants, not by MachineRepr::Struct, so field_index: 2 on FatPointer is stable unless this section explicitly changes that dedicated runtime layout.

Define Niche struct in compiler/ori_repr/src/layout/niche.rs. Also extended EnumTag::Niche with niche_variant_idx: u32 to support niche at any variant position (not just last). Updated TagEncoding and all tests. (2026-03-31)

/// A niche (invalid bit pattern) discovered in a type's representation.
/// Used to eliminate explicit discriminant tags in enum layouts.
pub struct Niche {
    /// Which field contains the niche (for fat pointers: 2 = data ptr)
    pub field_index: u32,
    /// Byte offset within the field
    pub offset: u32,
    /// Number of available niche values
    pub available: u128,
    /// Starting value of the niche range
    pub start: u128,
}

Identify niches for each type (implemented as find_niches() in niche.rs — handles Bool, Ordering, Char, RcPointer, FatPointer(Str), nested Enum; conservatively skips Byte, Int, Float, collections): (2026-03-31)

pub fn find_niches(repr: &MachineRepr) -> Vec<Niche> {
    match repr {
        // bool: values 0 and 1 → niche at value 2..=255 (254 niches)
        MachineRepr::Bool => vec![Niche {
            field_index: 0, offset: 0, available: 254, start: 2,
        }],

        // Ordering: values 0,1,2 → niche at 3..=255 (253 niches)
        // MachineRepr::Ordering is a dedicated variant (NOT Int { I8 })
        MachineRepr::Ordering => vec![Niche {
            field_index: 0, offset: 0, available: 253, start: 3,
        }],

        // Byte: all 256 values valid → no niche (unless range-narrowed)
        MachineRepr::Byte => vec![],

        // Narrowed int i8 with known range [lo, hi] → niche at hi+1..=i8::MAX
        // or lo-1..=i8::MIN (requires range info from ReprPlan)
        MachineRepr::Int { width: IntWidth::I8, .. } => {
            // Must query ReprPlan for the actual value range.
            // Without range info, conservatively return empty.
            // The caller (optimize_enum_repr) passes range info separately.
            vec![]
        }

        // Reference/pointer: null (0) is never a valid heap pointer
        // (ori_rc_alloc guarantees non-null, min 8-byte aligned)
        MachineRepr::RcPointer(_) => vec![Niche {
            field_index: 0, offset: 0, available: 1, start: 0, // null = niche
        }],

        // Fat pointer — ONLY str has a null-ptr niche.
        // str uses SSO for empty strings (OriStr::EMPTY has SSO_FLAG set in
        // byte 23, making the data-pointer-slot always non-zero). Therefore
        // null data pointer (all-zero in bytes 16-23) is an invalid str.
        //
        // [T], {K:V}, Set<T> use {0, 0, null} for empty collections, so
        // null data pointer IS a valid value — NO niche available.
        MachineRepr::FatPointer(FatRepr::Str) => vec![Niche {
            field_index: 2, offset: 0, available: 1, start: 0,
        }],
        MachineRepr::FatPointer(FatRepr::Collection { .. })
        | MachineRepr::FatPointer(FatRepr::Map { .. }) => vec![],

        // Nested enum: if it has unused discriminant values
        MachineRepr::Enum(e) => find_enum_niches(e),

        // Char: 0x110000..=0xFFFFFFFF are invalid Unicode (huge niche space)
        // MachineRepr::Char is a dedicated variant (NOT Int { I32 })
        MachineRepr::Char => vec![Niche {
            field_index: 0, offset: 0,
            available: 0xFFFF_FFFF - 0x10_FFFF, start: 0x11_0000,
        }],

        _ => vec![],
    }
}

Implement find_enum_niches() for nested enums: handles Explicit (unused tag values), Niche (remaining capacity after one value consumed), and None (delegates to payload). Verified with Option<Option<bool>> → niche value 3. (2026-03-31)
Implement optimize_option_repr() in niche.rs. Wired into canonical_option() in type_repr.rs — delegates fully. Variant order matches type checker (None=0, Some=1). Uses niche_variant_idx: 0 for None. Falls back to explicit I64 tag for types without niches. (2026-03-31)
Apply niche to Result<T, E> via optimize_result_repr() in niche.rs. Wired into canonical_result() in type_repr.rs. Tries Ok’s niches first (Err encoded via Ok’s niche), then Err’s niches. Falls back to explicit I64 tag. (2026-03-31)
Update resolve_enum() in layout_resolver.rs to handle EnumTag::Niche AND EnumTag::None. Refactored into 4 methods: resolve_enum() (dispatcher), resolve_enum_explicit() (existing { tag, payload }), resolve_enum_tagless() (single-variant, payload only), resolve_enum_niche() (data variant payload only). Consults ReprPlan for tag encoding. (2026-03-31)
Single-variant enum (newtype) erasure: canonical_enum() emits EnumTag::None when variants.len() == 1. The LLVM layout via resolve_enum_tagless() omits the tag field. All 14,798 tests pass. (2026-03-31)
Pattern matching codegen for niche-encoded variants — implemented in terminators.rs via emit_niche_switch(): loads niche field, compares against niche_value (with ptrtoint for pointer niches), conditional branch to niche/data blocks. Project (field 0) in instr_dispatch.rs extracts niche field and records in niche_scrutinees map. SetTag handles niche/tagless/explicit paths. Gated by NICHE_CODEGEN_READY flag. (2026-03-31)
RC inc/dec for niche-encoded variants — implemented in rc_helpers.rs via shared emit_niche_enum_rc(): stores to alloca, loads niche field, compares against niche_value, conditionally skips RC for niche variant. Handles both pointer and integer niche fields. (2026-03-31)
Drop for niche-encoded variants — implemented in drop_enum.rs via emit_drop_enum_niche(): loads niche field, compares against niche_value, skips to done for niche variant, drops data variant fields at struct offset 0 (no tag field). (2026-03-31)
[BUG] Fixed Option variant ordering mismatch: canonical_option() was creating [None=0, Some=1] but type checker assigns [Some=0, None=1]. This would have caused niche_variant_idx to map to the wrong variant. Fixed: [Some=0, None=1] everywhere, niche_variant_idx: 1 for None. (2026-03-31)
Codegen consumers updated — all 4 remaining consumers are niche-aware: (2026-03-31)
- option_result.rs — Option builtins use niche field comparison for is_some/is_none/unwrap/unwrap_or; Result builtins use niche_variant_idx for is_ok/is_err
- operators/strategy.rs — emit_coalesce() is dead code (BUG-04-009 routes ?? through ARC IR control flow), no changes needed
- instr_dispatch.rs — try_emit_project_enum_payload() uses field - 1 for niche layout
- construction.rs — emit_niche_variant_construct() inserts payload at index 0, skips tag for data variant
- layout_resolver.rs — TypeInfo::Option and TypeInfo::Result check ReprPlan for niche, produce named struct with { payload } layout
- niche_is_sentinel() shared helper eliminates 4 inline ptrtoint+icmp patterns
- option_result_helpers.rs — niche helpers for unwrap/unwrap_err/unwrap_or/expect/expect_err now have tag guards (emit_unwrap_branch/emit_expect_branch) and inc_value_rc payload retain, mirroring the explicit-tag pattern from option_result.rs. Result unwrap/unwrap_err/unwrap_or are now separate arms (previously collapsed). New helpers: compute_option_is_some, compute_result_is_ok, compute_result_is_err. emit_result_niche signature gained receiver_ty: Idx for TypeInfo::Result lookup. Fixes BUG-04-019. Behavioral verification rides on  items below — when the gate flips, the existing niche spec tests will exercise these helpers end-to-end. Structural regression guard: 9 unit tests in compiler/ori_llvm/src/codegen/arc_emitter/builtins/option_result_helpers/tests.rs. (2026-04-07)
ABI layer niche awareness — abi/mod.rs updated: ReprPlan threaded through abi_size, compute_param_passing, compute_return_passing, compute_function_abi, compute_function_abi_with_ownership. Niche checks added for TypeInfo::Option, TypeInfo::Result, and TypeInfo::Enum (tagless/niche variants). All callers updated (function_compiler, define_phase, arc_emitter, derive_codegen). Also fixed populate_canonical() in ori_repr to canonicalize types with resolved variable children (was skipping Option<Var(T→str)> due to overly aggressive has_vars() check). Added dst_ty to BuiltinCtx for future niche-aware monadic dispatch. NICHE_CODEGEN_READY gate remains false — flipping it revealed ~154 AOT test failures from 8+ codegen consumers that construct explicit { i64, T } structs. These need niche-aware paths before the gate can be enabled: result_monadic.rs, option_result_monadic.rs, compound_type_impls/option.rs, compound_type_impls/result.rs, list_builtins/helpers.rs, map_builtins.rs. (2026-04-04)

§07.2 Tests (TDD — write BEFORE implementation, verify they fail):

Rust unit tests (compiler/ori_repr/src/layout/tests.rs): 22 niche tests covering all find_niches types (Bool/254, Ordering/253, Char/0x110000, Str/null-ptr, RcPointer/null, Byte/empty, Int/empty, Float/empty, Unit/empty, List/empty), find_enum_niches (4-variant i8 → 252), optimize_option_repr semantic pins (Bool→1 byte, Ordering→1 byte, Char→4 bytes, Str→24 bytes, RcPointer→8 bytes), negative pins (Int→explicit, List→explicit), nested niche (Option<Option>→1 byte with niche 3), and optimize_result_repr (Bool×Ordering→niche, Int×Int→explicit). Also 3 new TagEncoding tests for niche_variant_idx: 0. All pass. (2026-03-31)
Ori spec tests (tests/spec/types/enum/niche/): 8 test files, 62 tests total, all passing via interpreter. (2026-04-06)
- option_bool.ori: Some(true), Some(false), None match correctly; roundtrip through list, distinctness, predicates, unwrap_or
- option_ordering.ori: all four values (Some(Less), Some(Equal), Some(Greater), None) match correctly; all distinct
- option_char.ori: Some('a'), Some('\u{10FFFF}'), None match correctly (boundary: last valid Unicode)
- option_str.ori: Some("hello"), Some(""), None match correctly (empty string uses SSO, not null ptr); Some("") != None pin; map
- option_list.ori: Some([1,2]), Some([]), None all distinct (negative pin: no niche — uses len-based verification)
- option_option_bool.ori: all four values of Option<Option<bool>> are distinct; nested match
- result_niche.ori: Result<bool, Ordering> match with all 5 variant combinations; is_ok/is_err
- niche_rc.ori: Option<str> created in loop (RC correctness); shared references; None clone; list of mixed Some/None
- niche_cross_feature.ori: for…yield+match, closure capture Option, Option.map chaining, filter, and_then, ? on Result<str, Error>
AOT tests (compiler/ori_llvm/tests/aot/enum_niche.rs):
- LLVM IR inspection: Option<bool> compiles to i8 (not { i8, i8 })
- LLVM IR inspection: Option<str> compiles to %ori.str (not { i8, %ori.str })
- LLVM IR inspection: Option<[int]> still has explicit tag (negative pin)
- RC inc/dec for Option<str> includes null-ptr check before ori_str_rc_inc
Dual-execution parity: every Ori spec test must produce identical output in interpreter and LLVM
Leak check: ORI_CHECK_LEAKS=1 on all niche spec tests (critical — niche encoding changes RC paths)
Valgrind: ./diagnostics/valgrind-aot.sh on niche-related tests (niche encoding is a memory-safety-sensitive change)
Subsection close-out (07.2) — Retrospective 07.2: no tooling gaps. The subsection’s niche implementation and 62 spec tests were verified by the existing ./test-all.sh + AOT IR assertions. The ~154 AOT failures from the gate flip attempt were diagnosed by reading test output and tracing codegen consumer paths — a structural one-time migration, not a recurring debugging pattern. Subsection remains in-progress due to 4 blocked verification items (AOT tests, dual-exec parity, leak check, Valgrind) waiting on NICHE_CODEGEN_READY gate. (2026-04-09)

07.3 Tagged Pointers

File(s): compiler/ori_repr/src/layout/tagged_ptr.rs (new, ~100 lines — can_use_tagged_pointer(), is_taggable_pointer()), compiler/ori_llvm/src/codegen/arc_emitter/tag_access/mod.rs (extend TagAccess for tagged pointer encoding/decoding)

On 64-bit systems, heap pointers have alignment ≥8, meaning the low 3 bits are always zero. These bits can store a 3-bit tag (up to 8 variants).

Implement tagged pointer analysis layer (compiler/ori_repr/src/layout/tagged_ptr.rs): is_taggable_pointer() classifies single-word pointer payloads, can_use_tagged_pointer() checks enum eligibility (≤8 variants, all variants either unit or single single-word-pointer field, at least one pointer variant). Module-level constant MAX_TAG_VARIANTS = 8 documents the 3-bit tag limit. (2026-04-06)

/// Check if a variant payload is a single-word pointer suitable for tagging.
///
/// FatPointer (str, [T], {K:V}, Set<T>) is 24 bytes — NOT taggable.
/// Only single-word pointers (RcPointer, OpaquePtr, UnmanagedPtr) qualify.
fn is_taggable_pointer(repr: &MachineRepr) -> bool {
    matches!(repr,
        MachineRepr::RcPointer(_)
        | MachineRepr::OpaquePtr
        | MachineRepr::UnmanagedPtr
    )
}

pub fn can_use_tagged_pointer(enum_repr: &EnumRepr) -> bool {
    // At most 8 variants (3 bits for tag)
    if enum_repr.variants.len() > 8 {
        return false;
    }
    // Every non-unit variant must have exactly one single-word pointer field.
    // FatPointer/Closure/Struct/Tuple are excluded — they are multi-word.
    // The decode path uses `value & ~0x7` to recover the pointer, which
    // would corrupt non-pointer payloads (e.g., masking int(5) gives 0).
    // Unit variants (no fields) are fine — they carry no payload, just a tag.
    enum_repr.variants.iter().all(|v| {
        v.fields.is_empty()
            || (v.fields.len() == 1 && is_taggable_pointer(&v.fields[0]))
    })
    // At least one variant must have a pointer (otherwise no benefit)
    && enum_repr.variants.iter().any(|v| {
        v.fields.len() == 1 && is_taggable_pointer(&v.fields[0])
    })
}

Note: VariantRepr::is_pointer() (in enum_repr.rs) includes FatPointer which is correct for general “is this a pointer type?” queries but NOT correct for tagged pointer optimization. §07.3 uses is_taggable_pointer() (single-word only) instead.

Tagged pointer layout (codegen wiring): Implemented in §07.3.A — all codegen consumers wired, gate flipped, tests passing. (2026-04-06)
```
[63:3] pointer value  [2:0] tag
```
- Store pointer variant: ptr | tag (low 3 bits of ptr are 0 due to alignment)
- Load tag: value & 0x7
- Load pointer: value & ~0x7
- Unit variants: only the tag value matters, no payload to decode
Safety analysis documented in tagged_ptr.rs module doc:
- Only applicable when the runtime guarantees 8-byte aligned allocations (ori_rt already does: alignment is always ≥ 8)
- Non-pointer scalar payloads (int, bool, float) are excluded — their low bits carry data that & ~0x7 would destroy (enforced by is_taggable_pointer returning false for scalars)
- Future: could support scalar payloads by shifting them left 3 bits during encode and right 3 bits during decode, at the cost of reducing the usable range (61 bits instead of 64)

§07.3 Tests (TDD — write BEFORE implementation, verify they fail):

Rust unit tests (compiler/ori_repr/src/layout/tests.rs): 17 tagged_ptr tests, all passing. (2026-04-06)
- is_taggable_pointer: positive (RcPointer, OpaquePtr, UnmanagedPtr); negative pins (Str 24-byte fat pointer, [int] collection, int, bool, float, byte)
- can_use_tagged_pointer: positive (unit+RcPointer, two pointer variants, 8-variant max); negative pins (9 variants, int payload, str payload, all-unit, multi-field variant)
Ori spec tests (tests/spec/types/enum/tagged_ptr.ori):
- Deferred: An attempt to add this file (with both recursive and non-recursive cases) exposed BUG-04-043. The recursive case is now fixed via the cycle-marker exclusion in is_taggable_pointer, but a secondary JIT-runner hang remains for tagged-pointer spec tests under directory sweep. Pending investigation of the secondary hang. Behavioral contract is covered by the AOT integration test below.
AOT tests (compiler/ori_llvm/tests/aot/enum_tagged_ptr.rs): (2026-04-06)
- test_recursive_enum_falls_back_to_explicit_tag — recursive IntCell = Empty | Holds(IntCell) correctly falls back to explicit-tag encoding and executes via AOT (assert_aot_success runs the binary under ORI_CHECK_LEAKS=1). This is the most important pin: it locks in BUG-04-043’s workaround so a future regression that re-enables eligibility for the cycle marker is caught immediately.
Dual-execution parity: workspace ./test-all.sh runs both interpreter and LLVM-backend test sweeps after TAGGED_PTR_CODEGEN_READY = true was flipped; baseline preserved (16,817 passed, 0 failed, 158 skipped, 2653 LCFail). (2026-04-06)
Leak check: assert_aot_success runs the AOT-compiled binary under ORI_CHECK_LEAKS=1 and panics on any leaked allocation. The recursive negative-pin test exercises the explicit-tag fallback path. (2026-04-06)

07.3.A Tagged Pointer Codegen Wiring

The analysis layer (is_taggable_pointer / can_use_tagged_pointer) is complete. To enable tagged pointer optimization end-to-end, the following codegen wiring must land. Mirrors the NICHE_CODEGEN_READY pattern from §07.2 — analysis first, codegen integration second behind a feature gate.

Eligibility scope (current): Non-recursive enums where every variant is either unit or carries exactly one single-word pointer (OpaquePtr / UnmanagedPtr / non-cycle-marker RcPointer), with at most 8 variants. Recursive enums are excluded — see BUG-04-043 for the future extension that adds box-and-load codegen for the recursive case. In current Ori syntax, the realistic eligible types are channels (OpaquePtr) and iterator-typed payloads (UnmanagedPtr) — both rare in user code. The §07.3.A wiring is in place for when broader eligibility lands.

Iterator payload drop (TPR-07-008, 2026-04-06): iterator-typed tagged-pointer payloads are now correctly dropped via ori_iter_drop at scope exit. The fix flipped iterators from trivial to non-trivial at the ori_types::triviality SSOT and added a dedicated RcStrategy::Iterator dispatch path plus a Tag::Iterator arm in dec_value_rc_inner. See the TPR-07-008 resolution in §07.R for the full architectural change. Matrix coverage in compiler/ori_llvm/tests/aot/iterator_drop.rs.

Subsection close-out (07.3) — Retrospective 07.3: no tooling gaps. BUG-04-043 (recursive enum hang) was diagnosed with ORI_LOG=ori_arc=debug and IR dumps. TPR-07-008 (iterator payload drop) was traced with ori_arc::aims::realize=trace per-phase RC snapshot (added during §07 work). The codegen consumer audit (21 sites) was a manual grep — one-time per new EnumTag variant, not worth automating. Subsection status updated. Remaining blocked: Ori spec tests (BUG-04-043 secondary JIT hang). (2026-04-09)

07.4 Payload Compression

File(s): compiler/ori_repr/src/canonical/type_repr.rs (update canonical_enum() payload sizing), compiler/ori_llvm/src/codegen/type_info/enum_layout.rs (update resolve_enum() payload layout — refactored from layout_resolver.rs), compiler/ori_llvm/src/codegen/arc_emitter/drop_enum.rs (update compute_variant_field_offsets())

When variant payloads have different sizes, the current approach uses max(sizeof(variant)) for all, padded to i64 slot boundaries. §07.4 addresses the achievable payload optimizations.

All-unit variant detection (already implemented in resolve_enum): (2026-04-06)
- Verified end-to-end: compute_enum_payload_layout(&[]) → (0, 1), compute_explicit_tag_layout(I8, 0, 1) → (1, 1)
- All-unit enums correctly produce { i8 tag } (1 byte) after §07.1 narrowing
- Pinned with payload_layout_empty_fields_zero_size, explicit_tag_layout_all_unit_i8_one_byte, and tag-widening tests for i16/i32
Payload alignment optimization:
- Current layout pads every field to i64 slot boundary (size.div_ceil(8) * 8) in 4 locations: ori_repr/layout/mod.rs:compute_enum_payload_layout, ori_llvm/codegen/type_info/enum_layout.rs:resolve_enum_explicit, ori_arc enum_payload_size() / pool_type_store_size(), and ori_llvm/codegen/arc_emitter/drop_enum.rs:compute_variant_field_offsets. This is a LEAK:scattered-knowledge SSOT violation — §07.4.A consolidates all four into a single canonical layout query.
- With narrowed fields from §04/§05, variant payloads can use tighter packing
- Example: type Color = RGB(r: i8, g: i8, b: i8) | HSL(h: i16, s: i8, l: i8) — RGB payload = 3 bytes (not 24), HSL = 4 bytes (not 24)
- Tests pin the current i64-slot baseline (payload_layout_three_byte_fields_padded_to_slots, payload_layout_int_plus_byte_uses_two_slots) so that §07.4.A’s transition can be detected and verified.
Shared prefix optimization (future work — NOT in §07 scope):
- Sharing field prefixes across variants requires fundamentally different codegen (shared GEP paths) and complicates pattern matching
- Defer to a future section when benchmarks show the padding cost is significant
- Rust does implement this (Variants::Multiple { offsets }) but it’s one of their most complex codegen paths
Size-class bucketing (future work — NOT in §07 scope):
- Heap-allocating large variant payloads requires runtime changes (new allocation paths, drop function changes, RC interaction)
- The overhead of indirection (extra pointer chase + allocation) often exceeds the memory savings
- Rust chose NOT to implement this; Swift does (for multi-payload enums with spare bits exhausted)
- Defer until escape analysis (§08) can determine which enums are stack-only (where boxing hurts) vs heap-only (where boxing helps)

§07.4 Tests (TDD — write BEFORE implementation, verify they fail):

Rust unit tests (compiler/ori_repr/src/layout/tests.rs): 12 tests covering current i64-slot baseline. (2026-04-06)
- All-unit: payload_layout_empty_fields_zero_size, payload_layout_zero_sized_field_no_size (Unit), payload_layout_never_field_no_size
- i64-slot baseline pins: payload_layout_byte_field_padded_to_slot, payload_layout_three_byte_fields_padded_to_slots, payload_layout_int_plus_byte_uses_two_slots
- Single/multi int: payload_layout_single_int_field, payload_layout_two_int_fields
- End-to-end via compute_explicit_tag_layout: explicit_tag_layout_all_unit_i8_one_byte (1 byte), _i16_two_bytes, _i32_four_bytes, _with_int_payload
- §07.4.A will replace the i64-slot pins with natural-alignment pins as the layout migrates.
Ori spec tests (tests/spec/types/enum/payload_compression.ori):
- Mixed-size variant enum: construct each variant, match, verify values preserved
- Narrowed-field enum from §04: field values survive construction + match roundtrip
AOT tests (compiler/ori_llvm/tests/aot/enum_payload.rs):
- LLVM IR inspection: payload array uses narrowed element types, not [M x i64]
- Verify compute_variant_field_offsets() matches actual LLVM struct offsets
Dual-execution parity: every spec test produces identical output in interpreter and LLVM
Leak check: ORI_CHECK_LEAKS=1 on all payload compression spec tests

07.4.A Payload Compression Codegen Migration

The all-unit detection (item 1) is verified working. To enable mixed-variant payload compression, the i64-slot packing rule must be replaced with natural-alignment packing across four locations that currently maintain the same rule independently — a LEAK:scattered-knowledge SSOT violation. §07.4.A consolidates and migrates them.

07.5 Completion Checklist

Implementation order: §07.0 (prerequisites) → §07.1 (discriminant narrowing — safe, validates TagAccess) → §07.2 (niche filling — layout-changing, uses validated TagAccess) → §07.3 (tagged pointers — alternative encoding for pointer-heavy enums) → §07.4 (payload compression — padding reduction). Each subsection must pass ./test-all.sh before proceeding to the next.

Test matrix for §07 (write failing tests FIRST, verify they fail, then implement):

Phase 1 tests (§07.1 — discriminant narrowing only, no niche filling):

Type	Expected after §07.1	Semantic pin
All-unit enum `type Dir = North \| South \| East \| West`	`{ i8 tag }` — no payload, tag narrowed from i64	Yes — `sizeof == 1` (down from 8)
`Option<int>`	`{ i8 tag, i64 payload }` — 16 bytes (tag narrowed, padding between i8 tag and i64 payload)	Yes — tag is i8, not i64
`Option<bool>`	`{ i8 tag, i8 payload }` — 2 bytes (or padded to alignment)	Yes — smaller than current 16 bytes
Single-variant enum `type Wrapper(val: int)`	`EnumTag::None` — newtype erasure, same as `int`	Yes — `sizeof == 8`
Enum with 257 variants	`{ i16 tag, payload }` — tag auto-widens to i16	Yes — i16 not i8

Phase 2 tests (§07.2 — niche filling, builds on §07.1):

Type	Expected after §07.2	Semantic pin
`Option<bool>`	1 byte `i8`: `Some(false)=0`, `Some(true)=1`, `None=2`	Yes — `sizeof == 1`, no struct wrapper
`Option<Ordering>`	1 byte `i8`: `Some(Less)=0`, `Some(Equal)=1`, `Some(Greater)=2`, `None=3`	Yes — `sizeof == 1`
`Option<str>`	24 bytes (null data ptr niche for None, no tag field)	Yes — `sizeof == sizeof(str)`
`Option<[int]>`	32 bytes (i8 tag + 24-byte payload — no niche, empty lists use null ptr)	Yes — `sizeof == 32` (only tag narrowing i64->i8 from §07.1)
`Option<int>`	16 bytes (no niche available in i64 — must use explicit tag, narrowed to i8)	Yes — `sizeof == 16`
`Option<char>`	4 bytes (char niche: 0x110000+ encodes None)	Yes — `sizeof == 4`
`Result<bool, Ordering>`	1 byte (niche from bool payload covers Ordering variants)	Yes — niche across Result arms
Narrowed `i8` field with range `[0, 2]` after §04	253 niche values available	Yes — §04+§07 interaction
`f32`-typed field after §05	NaN niches conservatively skipped	Yes — no NaN-based niche
Pattern match on `Option<bool>` with niche repr	Correct values: `None` = 2, `Some(false)` = 0	Yes — match produces correct results
`Option<Option<bool>>`	1 byte (nested niche: `None(outer)` = 3, `Some(None)` = 2)	Yes — recursive niche
RC inc/dec on `Option<str>`	Correct: inc/dec only on Some, not on None (null ptr)	Yes — niche-aware RC
Drop on `Result<str, [int]>`	Correct per-variant cleanup with niche encoding	Yes — niche-aware drop

Phase 1 checkboxes (§07.1 — discriminant narrowing):

Write failing test matrix for §07.1 BEFORE implementation. Tests go in compiler/ori_repr/src/layout/tests.rs (Rust unit tests for min_tag_width() and canonical repr sizes) and tests/spec/types/enum/ (Ori spec tests for enum sizeof). Verify they fail with current i64 tags.
All-unit enums → tag-only (no payload), tag narrowed from i64 to i8 — verify resolve_enum all-unit path preserved with narrowed tag
Single-variant enums → newtype erasure (no tag) — EnumTag::None. Note: this changes MachineRepr::Enum(EnumRepr { tag: EnumTag::None, ... }) which downstream code must handle (codegen must skip tag read/write entirely)
Discriminant uses minimum width (i8 for <=256, i16 for <=65536) — this alone saves 7 bytes per non-niche enum
ALL 16 codegen consumers from §07.0 migrated to TagAccess and tested with narrowed tags
./test-all.sh green in both debug and release — no behavioral changes from narrowing alone

Phase 2 checkboxes (§07.2 — niche filling):

Cross-feature interaction tests (MANDATORY per CLAUDE.md §Interaction Testing):

These test enum representations interacting with other language features. Each must pass in both interpreter and LLVM.

Feature interaction	Test description	Where
Pattern matching + niche	`match opt_bool { Some(true) -> 1, Some(false) -> 2, None -> 3 }` all branches hit	`tests/spec/types/enum/niche/`
`?` operator + narrowed Result	`@f () -> Result<int, str> = { let $x = ok_or_err()?; Ok(x + 1) }` — narrowed tag on error propagation	`tests/spec/types/enum/`
for-yield + Option	`for x in [Some(1), None, Some(3)] yield match x { Some(v) -> v, None -> 0 }` = `[1, 0, 3]`	`tests/spec/types/enum/`
Closures + niche capture	Closure captures `Option<str>`, matches inside body — RC correct on capture/release	`tests/spec/types/enum/niche/`
Nested match + niche	`match opt_opt { Some(Some(v)) -> v, Some(None) -> 0, None -> -1 }`	`tests/spec/types/enum/niche/`
Generic functions + enum	`@identity<T> (x: T) -> T = x` called with `Option<bool>` — niche repr survives generic instantiation	`tests/spec/types/enum/`
List of niche-encoded enums	`[Option<bool>]` — push, iterate, collect, verify values preserved	`tests/spec/types/enum/niche/`
Map with niche-encoded keys	`{Option<char>: int}` — insert, lookup, verify (Hashable interaction)	`tests/spec/types/enum/niche/`
Derived traits + niche enum	`#derive(Eq, Clone, Debug)` on struct containing `Option<bool>` field	`tests/spec/types/enum/niche/`

Final checkboxes (all phases):

Exit Criteria: Option<bool> compiles to a single i8 in LLVM IR (no struct wrapper), with None = 2, Some(false) = 0, Some(true) = 1. Verified by inspecting LLVM IR and running all Option-related spec tests. All cross-feature interaction tests pass. Zero leaks under ORI_CHECK_LEAKS=1. Dual-execution parity confirmed.

07.R Third Party Review Findings

Dual-Source TPR Round (2026-04-09) — Architectural Review

Broad architectural review of §07 implementation + remaining repr-opt plan soundness. Codex (557s, 239 events) + Gemini (1646s, 137 events). All findings independently verified by Explore agent.

Resolution: These findings are systemic SSOT violations requiring cross-crate architectural work. A dedicated plan (plans/enum-layout-ssot/) is being created via /create-plan to resolve all findings architecturally.

Theme A — Scattered Enum Layout Knowledge (SSOT violation):

[TPR-07-001-codex][high] compiler/ori_llvm/src/codegen/arc_emitter/tag_access/mod.rs — TagAccess LEAK: builtins bypass abstraction. result_monadic.rs, option_result_monadic.rs, compound_type_impls/option.rs, compound_type_impls/result.rs, list_builtins/helpers.rs, map_builtins.rs all hardcode field 0/1 for enum tag/payload instead of using TagAccess. Niche stub paths (emit_option_niche, emit_result_niche) have #[expect(clippy::unused_self)] — unimplemented. Evidence: Verified by Explore agent. 15+ sites bypass TagAccess. Basis: direct_file_inspection. Confidence: high.
[TPR-07-002-codex][high] compiler/ori_llvm/src/codegen/derive_codegen/enum_bodies/enum_eq.rs:34 — Derive enum bodies don’t handle TaggedPtr. enum_eq.rs, enum_comparable.rs, enum_hashable.rs all assume {tag, payload} struct layout and hardcode extract_value(..., 0) for tag. No call to get_niche_encoding() or get_tagged_ptr_encoding() in any derive path. TAGGED_PTR_CODEGEN_READY is already true — a user enum eligible for tagged-pointer layout will produce wrong derive code. Evidence: Verified by Explore agent. Active miscompile surface. Basis: direct_file_inspection. Confidence: medium.
[TPR-07-003-codex][high] compiler/ori_llvm/src/codegen/arc_emitter/builtins/option_result_helpers.rs:309 — Option/Result runtime ABI contract LEAK. {i64 tag, T payload} struct constructed ad-hoc in option_result_helpers.rs, result_monadic.rs, option_result_monadic.rs, list_builtins/helpers.rs, map_builtins.rs. No single ABI query surface. Evidence: Verified by Explore agent. 5+ locations with hardcoded ABI. Basis: direct_file_inspection. Confidence: high.
[TPR-07-004-codex][high] compiler/ori_repr/src/layout/mod.rs:187 — i64-slot packing in 5+ locations. repr/layout/mod.rs, type_info/enum_layout.rs, abi/mod.rs, lower/control_flow/type_layout.rs, arc_emitter/drop_enum.rs, plus derive walkers (enum_eq.rs, enum_comparable.rs, enum_hashable.rs). All recompute size.div_ceil(8) * 8 independently. Evidence: Verified by Explore agent. At least 8 locations. Basis: direct_file_inspection. Confidence: high. Agreement: [TPR-07-002-gemini] (both reviewers flagged i64-slot SSOT)
[TPR-07-003-gemini][medium] compiler/ori_llvm/src/codegen/arc_emitter/builtins/option_result.rs:81 — 50+ hardcoded GEP index 0 sites. 60 matches for extract_value.*0|struct_gep.*0|insert_value.*0 in arc_emitter/. Mix of legitimate struct field 0 access and enum tag access — ~15 are actual field-access errors. Evidence: Verified by Explore agent. Confirmed 60 matches, ~15 actual bugs. Basis: direct_file_inspection. Confidence: high. Related: [TPR-07-001-codex]
[TPR-07-002-gemini][high] compiler/ori_arc/src/lower/control_flow/type_layout.rs:199 — i64-slot packing SSOT (same root cause as TPR-07-004-codex). ori_arc, ori_repr, ori_llvm all hardcode round_up_i64(field_size, 8). Evidence: Verified by Explore agent. Basis: direct_file_inspection. Confidence: high. Agreement: [TPR-07-004-codex]

Theme B — Take-Project Ownership Model Gaps:

[TPR-07-001-gemini][high] compiler/ori_arc/src/aims/emit_rc/take_project/mod.rs:250 — Memory leak for predecessor args in take-project classes. Variables in predecessor blocks enter in_class via union-find but may lack var_to_lineage entries. dead_cleanup.rs and edge_cleanup.rs skip all in_class vars, but is_bypass_safe_entry_for_var returns false without lineage → orphaned vars with no RC decrement. No assertion enforces in_class ⊆ var_to_lineage.keys(). Evidence: Verified by Explore agent. Confirmed potential leak path. Basis: direct_file_inspection. Confidence: high.
[TPR-07-005-codex][medium] compiler/ori_arc/src/aims/emit_rc/borrowed_defs.rs:50 — is_take_project iterator-only scope. Hardcoded to Tag::Iterator | Tag::DoubleEndedIterator. Future unique-owned types (Box, channels) will silently stay on borrow path → leak or double-free. Evidence: Verified by Explore agent. Correctly scoped today but no architectural hook for extension. Basis: direct_file_inspection. Confidence: high. Agreement: [TPR-07-004-gemini]
[TPR-07-004-gemini][low] compiler/ori_arc/src/aims/emit_rc/borrowed_defs.rs:45 — Same as TPR-07-005-codex. Suggest generalizing to check MachineRepr unique-owned bit. Evidence: Verified by Explore agent. Basis: direct_file_inspection. Confidence: medium. Agreement: [TPR-07-005-codex]

Theme C — Testing Gaps:

[TPR-07-006-codex][medium] compiler/ori_llvm/src/codegen/arc_emitter/builtins/option_result_helpers/tests.rs:1 — Niche-helper tests source-text only. include_str! + substring matching instead of IR emission tests. BUG-04-019 verification weaker than claimed. Evidence: Verified by Explore agent. Niche codegen is a stub (returns None); tests limited because feature incomplete. Basis: fresh_verification. Confidence: high.

07.RZ Resume Notes (2026-04-07)

This section captures the exact state needed to resume TPR-07-017 / TPR-07-018 closure across context boundaries. Update or delete when both findings are resolved.

Working tree state (uncommitted TPR-07-017 fix):

compiler/ori_arc/src/aims/emit_rc/take_project.rs — full rewrite (per-class partitioning, bypass_safe_entries, union-find, three new APIs).
compiler/ori_arc/src/aims/emit_rc/dead_cleanup.rs — source 1 in-class branch uses is_bypass_safe_entry_for_var with per-class dedup; source 2 skips in-class block params.
compiler/ori_arc/src/aims/emit_rc/edge_cleanup.rs — collect_branch_edge_decs and collect_invoke_edge_decs take take_move_facts: &TakeMoveFacts and skip in-class vars.
compiler/ori_arc/src/aims/realize/emit_unified.rs — threads take_move_facts through emit_edge_cleanup call.
compiler/ori_llvm/tests/aot/iterator_drop.rs — new test tpr_07_017_two_unrelated_take_projects_no_leak.
compiler/ori_llvm/tests/aot/fixtures/iterator_drop/two_unrelated_take_projects.ori — new fixture (two unrelated MaybeIter enums, conditional consume, returns count_b - count_b = 0).
plans/repr-opt/section-07-enum-repr.md — this update (TPR-07-016 marked resolved, TPR-07-017/018 expanded, this resume section added).

NOTE (2026-04-07, after iteration 2): the “uncommitted working tree” and “verification status” lists ABOVE are now historical — they describe the pre-iteration-1 state and have been superseded by commits 79124fc3 (TPR-07-017 landing), 04cf56fb (TPR-07-020 + TPR-07-021 + TPR-07-019 iteration-1 revert). Refer to the “Iteration 2 status (2026-04-07)” subsection at the bottom of this resume notes block for the current state and resume sequence.

Working tree state (UNRELATED, pre-existing, NOT mine):

.claude/skills/*.md, .claude/commands/tp-help.md — pre-existing skill doc updates from prior session, unrelated to TPR work.
Many plans/*/section-*.md files (~110) — pre-existing batch addition of /improve-tooling retrospective checkbox, unrelated to TPR work. Do NOT include these in the TPR-07-017 commit. Selective git add only the files listed in “Working tree state (TPR-07-017 fix)” above.

NOTE (2026-04-07, after iteration 2): BOTH the unrelated batch additions AND the impl-hygiene-review default fix landed in commit ba97de83 (docs(plans): improve section close-out checklist). The working tree is now clean of those pending changes.

Iteration 2 status (2026-04-07) — read this for the current state

Current commit chain on dev:

055b5a9b chore(ori_arc): per-phase post-walk RC tracing — surfaced by TPR-07-017 retrospective
79124fc3 fix(repr-opt): TPR-07-017 per-class take-project partitioning + bypass-safe entry edge
ba97de83 docs(plans): section close-out checklist improvements (impl-hygiene-review default + improve-tooling retrospective)
04cf56fb fix(repr-opt): TPR-07-020 + TPR-07-021 + TPR-07-019 iteration-1 revert
41592011 docs(repr-opt): refresh §07.RZ resume notes for iteration-2 closure
f7a04e63 test(aot): auto-rebuild workspace ori binary before AOT tests
4c070ad0 build(scripts): add cache-doctor.sh for cargo cache pollution detection
(pending iteration 3 tooling) build(diagnostics): add arc-dump.sh for ARC IR inspection — surfaced by TPR-07-019 retrospective
(pending iteration 3 fix) fix(repr-opt): TPR-07-019 per-source bypass-safe split — proper fix via lineage layer ← planned HEAD

TPR findings status (2026-04-07, iteration 3):

Finding	Severity	Status
TPR-07-017	originally medium	landed in 79124fc3, partially open until TPR-07-019 closes — iteration-3 fix below resolves the underlying union-find soundness gap
TPR-07-018	medium	not yet started — emitter-driven IR test for BUG-04-019. Has full implementation plan in §07.R `[TPR-07-018]`
TPR-07-019	high	iteration 3 implementation landed — membership-vs-lineage split via bidirectional Let / forward-only Jump alias graph, per-lineage intersection-then-entries. Pending Codex re-review. Detailed notes in §07.R `[TPR-07-019]` “Iteration 2 (proper fix landed)” subsection.
TPR-07-020	medium	resolved in 04cf56fb
TPR-07-021	low	resolved in 04cf56fb

Verification status (post-iteration-3, 2026-04-07):

✅ cargo b — clean
✅ cargo b --release — clean (FastISel parity verified)
✅ cargo test -p ori_arc take_project::tests — 10 new unit tests for membership/lineage helpers
✅ cargo test -p ori_llvm --test aot iterator_drop — 16 passed, 0 failed in BOTH debug and release (15 prior + new tpr_07_019_per_source_lineage_no_leak)
✅ ./test-all.sh — 16,853 passed, 0 failed (+12 from baseline 16,841: 10 unit tests + 1 AOT pin + 1)
✅ ./clippy-all.sh — clean
✅ ./fmt-all.sh — clean
⏳ /commit-push — pending (this iteration’s changes still uncommitted)
❌ /tpr-review re-run (iteration 3) — pending; will run after commit lands
❌ /impl-hygiene-review — blocked on TPR re-review being clean (CLAUDE.md gate)
➕ Bug filed: [BUG-07-005][low] orphan env vars ORI_NO_REPR_OPT / ORI_VERIFY_ARC — surfaced by diagnostics/check-debug-flags.sh during retrospective verification of the new arc-dump.sh. Unrelated to TPR-07-019 itself.

Tooling gaps surfaced during iteration 2 (for /improve-tooling retrospective):

Stale target/debug/ori binary masked a regression for ~30 minutes. The AOT test framework runs target/debug/ori (the workspace binary) to compile fixtures, but cargo test -p ori_llvm does NOT rebuild that binary — only cargo b does. A session that modifies ori_arc/ori_llvm/ori_rt and runs cargo test against an outdated ori binary will see ghost test results (passes that aren’t real, or failures that aren’t real). Iteration 2’s bisect of “which fix broke iterator_drop?” was confused for ~30 minutes by this. Fix options:
- (a) Make test-all.sh and the pre-commit hook invoke cargo b first.
- (b) Make the AOT test framework call cargo run --quiet -p oric --bin ori -- build instead of Command::new("target/debug/ori").
- (c) Add a build.rs to ori_llvm that depends on oric and forces a rebuild of the workspace ori binary.
- Recommendation: option (b) is the most surgical and removes the entire class of problem.
Root-owned cargo cache files in target/debug/.fingerprint/ori_llvm-d210d115c4eb315c/ from a March 1 sudo build. Cargo cannot update these fingerprints, producing erratic build behavior. Clean up with sudo rm -rf target/debug/.fingerprint/ori_llvm-d210d115c4eb315c (and check for other root-owned target files via find target -uid 0). Did not directly cause iteration 2’s failures but is a latent landmine.

Resume sequence (next session, post-iteration-2):

Re-read CLAUDE.md (mandatory per /continue-roadmap Step -1).
Read this entire §07.RZ Resume Notes “Iteration 2 status” subsection for the current state.
Read the §07.R [TPR-07-019] entry IN FULL — it documents the iteration-1 failure and the proper-fix design (membership class vs reachability set architectural split). The proper fix needs that exact split; do NOT re-attempt the iteration-1 narrow-union approach (it is documented as a forbidden path in take_project.rs::union_alias_edges).
Sanity check: cargo b 2>&1 | tail -3 — should compile clean. If you skip this, the AOT test framework will use a stale target/debug/ori and produce ghost results — see “Stale binary” gap above.
Verify baseline: timeout 150 cargo test -p ori_llvm --test aot iterator_drop 2>&1 | tail -10 — should report 15/15 passing (12 pre-existing + 3 from iteration 1/2: 07_017, 07_019, 07_020).
Implement TPR-07-019 proper fix in compiler/ori_arc/src/aims/emit_rc/take_project.rs:
- Change ClassInfo to track Vec<TpSourceInfo> where each TpSourceInfo { tp_block: usize, bypass_safe_blocks: FxHashSet<usize>, bypass_safe_entries: FxHashSet<usize> }.
- Compute per-source reachability instead of per-class.
- Add class_bypass_safe_entries(class_idx) -> FxHashSet<usize> returning the INTERSECTION of all sources’ bypass_safe_entries in that class (so if even one source contaminates a block, the whole-class drop must NOT fire there).
- is_bypass_safe_entry_for_var(var, blk) queries class_bypass_safe_entries(class_of(var)).
- Keep union_alias_edges UNCHANGED — the over-approximating union must remain so edge_cleanup’s is_in_class skip continues to work.
Add a regression fixture that ACTUALLY exercises the unsound case: it must produce two unrelated take-project sources whose alias chains genuinely meet at a phi-style block param AND whose bypass-safe regions differ in a way that the current over-approximation hides. The current tpr_07_019_phi_merge_take_projects.ori topology pin doesn’t exercise the unsoundness — design a tighter fixture that exposes it via leak detection on the bypass-side source.
Run iterator_drop tests — should still report 15/15 passing (or 16/16 if you added a new pin). Same tests in release.
Run ./test-all.sh — must report 16,842 passed (or 16,843 if you added a fixture). Zero failures.
Run ./clippy-all.sh — must be clean.
Commit via /commit-push — suggested message: fix(repr-opt): TPR-07-019 per-source bypass-safe split — proper fix after iteration-1 revert.
Re-run /tpr-review (iteration 3) — Codex must verify TPR-07-019 is now correctly resolved.
Run /impl-hygiene-review — only after TPR re-review is clean. CLAUDE.md gate.
Mark [TPR-07-019] [x] resolved in §07.R with the implementation note. Update third_party_review.updated to the resolution date. The section’s third_party_review.status can flip to resolved once TPR-07-018 is also closed.
Then handle TPR-07-018 as a separate fix per its existing implementation plan in §07.R.
Address the tooling gaps above as part of /improve-tooling retrospective at the end of section 07.

Tooling friction captured during TPR-07-017 debugging (for /improve-tooling retrospective, applies BOTH iteration 1 and iteration 2):

Iteration 1 pattern: bisecting which AIMS pipeline post-walk pass (emit_dead_invoke_dsts, emit_edge_cleanup, emit_project_escape_incs, coalesce_block_rc) modifies a specific block’s RC ops.
Iteration 1 fix: per-phase trace snapshots in emit_unified.rs::trace_phase_snapshot, activated via ORI_LOG=ori_arc::aims::realize=trace. Landed in commit 055b5a9b.
Iteration 2 NEW pattern: stale target/debug/ori masking regressions. The AOT framework runs the workspace binary, not a binary built by cargo test. Real fix is option (b) above (use cargo run from the test harness instead of Command::new against a fixed path).
Iteration 2 NEW pattern: cargo cache pollution from sudo builds. Real fix: detect and warn when target/ contains root-owned files, OR include a scripts/cache-doctor.sh that can clean them (with sudo) on demand.

Architectural concepts (worth preserving across sessions):

Take-project: a Project instruction whose source is a sum type (Enum/Option/Result) and whose projected payload is a unique-owned Box (Tag::Iterator or Tag::DoubleEndedIterator). Semantically, the source enum has given up ownership of its payload at this point — the projected variable now owns the Box and is responsible for freeing it.
Take-project alias class: the connected component of ArcVarIds that share storage with a take-project source via Let aliases (Let { dst, Var(src) } — bidirectional) and Jump-arg → block-param propagation (forward only). Two take-project sources are in the same class iff their alias chains intersect.
Bypass-safe block (per class): a block that is NEITHER forward- nor backward-reachable from any take-project block in that specific class. The source enum is still owned AND will never be consumed by this class’s take-projects on any reachable path.
Bypass-safe entry (per class): a bypass-safe block where at least one CFG predecessor is NOT bypass-safe (or the block has no predecessors). The unique “moment of escape” — the first block on each CFG path where the source enum becomes definitively unreachable from the take-project. THE ONLY place to emit a scope-exit drop for a class member.
Per-class partitioning: each take-project source connected component has its own tp_blocks and its own bypass_safe_blocks/bypass_safe_entries. Computed independently — class A’s reachability never touches class B’s. This is what makes two unrelated iterators in the same function compose correctly.
Source 1 vs Source 2: dead_cleanup::emit_dead_at_entry_decs has two emission sources. Source 1 walks state_map.block_entry_states(blk) (vars present in the lattice). Source 2 walks block.params (block params absent from entry_states entirely). The TPR-07-016/017 fix routes class-member drops through Source 1 only (at the bypass-safe entry); Source 2 SKIPS in-class block params entirely (their underlying value comes from the upstream entry).
Why edge cleanup must skip in-class: edge cleanup iterates exit_states and emits drops on dead-at-entry edges. In-class vars have alias siblings (e.g., %5 and its Let-alias %19), and edge cleanup would emit a dec for the sibling on a different edge from where source 1 emits the class drop. Both RcDec instructions invoke ori_iter_drop on the same tagged-pointer payload → glibc-detected double-free at runtime. The skip says “class drops belong exclusively to source 1’s bypass-safe entry branch; edge cleanup hands them off.”
Why source 1 emits BEFORE the use_info skip: alias-chain “uses” on bypass-safe entry blocks are SSA-only (Let alias / Jump-arg propagation through dead block params) and don’t dereference the value. The dec walks the tagged-pointer encoding (ori_iter_drop on the payload) without invalidating the source variable’s bit pattern, so subsequent alias reads stay safe. Take-project consuming uses are excluded by the bypass-safe predicate (the take-project block is in both the forward- and backward-reachable sets, so it’s not bypass-safe).
Why direct-emit instead of routing: TPR-07-016 first attempt routed through merge_edge_decs/route_merge_edge_decs/apply_edge_decs, which inserts trampoline blocks for multi-pred successors. The trampoline body emits RcDec %param_var where %param_var is the merge block’s param ID. The LLVM emitter resolves the param ID to a phi node → phi-dominance verifier failure. Direct-emit at the bypass-safe entry block (using whichever class member appears first in entry_states) avoids the trampoline path entirely; the LLVM emitter resolves the var via the entry block’s incoming SSA, which dominates by definition.
Why per-class dedup: entry_states may contain MULTIPLE alias-class members for the same class (e.g., %5 AND its Let alias %19 after RcDec hoisting). Each represents the same underlying value. Without classes_dec_emitted: FxHashSet<usize>, source 1 would emit a dec for each → N-way double-free. The dedup ensures one dec per class per block.