Section 01: Representation IR & Decision Framework

Context: Today, ori_llvm::codegen::type_info::store.rs maps Tag to TypeInfo (e.g., Tag::Int → TypeInfo::Int) in compute_type_info_inner(), and info.rs maps TypeInfo to LLVM types (e.g., TypeInfo::Int → i64) in storage_type(), with companion methods size(), alignment(), and is_trivial(). To support narrowing, we need a centralized decision document that multiple analysis passes can populate and codegen can read.

Reference implementations:

Lean4 src/Lean/Compiler/LCNF/Types.lean: Phase-separated IR where semantic types and machine types are distinct data structures
Zig src/InternPool.zig: Layout information interned alongside types — each type has pre-computed size/alignment
Roc crates/compiler/mono/src/layout/intern.rs: STLayoutInterner maps type variables to concrete layouts after monomorphization

Depends on: Nothing — this is the foundation.

01.1 MachineRepr Enum & ReprPlan Data Structure

File(s): compiler/ori_repr/src/lib.rs (NEW crate), compiler/ori_repr/src/repr.rs

File layout (~1,674 production lines across 13 files, all under the 500-line limit):

File	Contents	Lines
`lib.rs`	Module declarations, `pub use` re-exports, `compute_repr_plan()`, pass stubs	156
`repr.rs`	`MachineRepr` enum, `IntWidth`, `FloatWidth`	94
`struct_repr.rs`	`StructRepr`, `TupleRepr`, `FieldRepr`, `RcRepr`, `FatRepr`, `ClosureRepr`	134
`enum_repr.rs`	`EnumRepr`, `EnumTag`, `VariantRepr` (+ `VariantRepr::is_pointer`)	67
`plan.rs`	`ReprPlan` struct + builder + writer methods (`set_repr`, `set_var_ranges`, `set_escape_info`, `set_rc_strategy`)	224
`plan/query.rs`	`NarrowingPolicy`, `RcStrategy`, ergonomic query methods (`int_width`, `float_width`, `is_trivial`, `escapes`, `rc_strategy`) + tracing	141
`plan/decision.rs`	`ReprDecision`, `DecisionSource`, `DecisionReason`	83
`plan/repr_attr.rs`	`ReprAttribute` enum	24
`canonical/mod.rs`	`populate_canonical()`, `canonical_cached()`, pool traversal	298
`canonical/type_repr.rs`	Per-tag canonical mapping helpers (`canonical_collection`, `canonical_map`, etc.)	257
`layout.rs`	Layout utilities (`is_trivial_repr`, `field_size`, `field_align`, `compute_field_layout`, etc.)	174
`range/mod.rs`	Placeholder only in §01 — exports `pub struct ValueRange;` so `DecisionReason::RangeFits` compiles. Replaced in §03.	11
`escape/mod.rs`	Placeholder only in §01 — exports `pub struct EscapeInfo;` so `ReprPlan::escape_info` compiles. Replaced in §08.	11
`tests.rs`	All tests (sibling to `lib.rs` — tests exempt from 500-line limit)	2696

The MachineRepr enum captures the physical representation chosen for each type. It must be rich enough to express all optimizations in §02-§11 but simple enough that codegen can pattern-match exhaustively.

Create new crate ori_repr with Cargo.toml entry
- Dependencies from §01: ori_types (for Pool, Idx, Tag), ori_ir (for Name — the interned function identifier), ori_arc (for ArcFunction, ArcVarId — needed immediately for compute_repr_plan() signature and escapes() query), rustc-hash (workspace dep — for FxHashMap/FxHashSet), tracing (workspace dep — for tracing::trace! in query methods)
- No dependency on ori_llvm — this is backend-independent
- No dependency on ori_eval — this is evaluation-independent
- Architecture: ori_types → ori_arc → ori_repr → ori_llvm (no cycle — ori_repr reads from ori_arc IR types but ori_arc does not depend on ori_repr)
- Verified: ori_types has Pool, Idx, Tag in its pub API; rustc-hash is a workspace dep used by ori_types, ori_arc, and ori_llvm
- Add #![deny(unsafe_code)] to ori_repr/src/lib.rs (pure analysis crate, same as ori_ir, ori_types, ori_lexer)

Define MachineRepr enum:

/// The physical representation of a type in generated code.
/// Every Idx in the Pool maps to exactly one MachineRepr.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum MachineRepr {
    /// Fixed-width integer (narrowed from semantic i64)
    Int { width: IntWidth, signed: bool },
    /// Fixed-width float (narrowed from semantic f64)
    Float { width: FloatWidth },
    /// Boolean (always i1)
    Bool,
    /// Unicode scalar value (always i32 — 0..=0x10FFFF)
    Char,
    /// 8-bit unsigned byte (always i8)
    Byte,
    /// Duration in nanoseconds (always i64)
    Duration,
    /// Memory size in bytes (always i64)
    Size,
    /// Comparison ordering (always i8: Less=0, Equal=1, Greater=2)
    Ordering,
    /// Unit (zero-sized in memory, i64(0) as value)
    Unit,
    /// Never (uninhabited)
    Never,
    /// Struct with optimized field layout
    Struct(StructRepr),
    /// Enum with optimized discriminant and payload
    Enum(EnumRepr),
    /// Tuple (treated as anonymous struct)
    Tuple(TupleRepr),
    /// Heap-allocated reference-counted value
    RcPointer(RcRepr),
    /// Fat pointer (ptr + metadata) — used for str, [T], {K:V}, Set<T>
    FatPointer(FatRepr),
    /// Function pointer (fn ptr + optional env ptr)
    Closure(ClosureRepr),
    /// Range (always {i64 start, i64 end, i64 step, i64 inclusive})
    Range,
    /// Stack-promoted value (was heap, promoted by escape analysis).
    /// `had_rc` records whether the original heap allocation used RC headers —
    /// needed so drop codegen knows whether to emit a stack-local destructor.
    StackPromoted { inner: Box<MachineRepr>, had_rc: bool },
    /// Opaque pointer (iterator, channel — runtime-managed)
    OpaquePtr,
}
// NOTE: Box<MachineRepr> in StackPromoted, FatRepr::Collection,
// RcRepr::inner, and ClosureRepr::ret causes heap allocation per type.
// Acceptable: MachineRepr is computed once per type during ReprPlan
// construction (not per-expression), the plan is immutable after
// construction, and recursive types require indirection. If profiling
// shows this matters, consider interning via MachineReprId indices.
//
// Add after implementation:
//   const _: () = assert!(std::mem::size_of::<MachineRepr>() <= 48);

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum IntWidth { I8, I16, I32, I64 }

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum FloatWidth { F32, F64 }

Implement canonical(tag: Tag, pool: &Pool, idx: Idx) -> MachineRepr for ALL Tag variants (this is the most critical part of §01 — it defines what “canonical” means for every Tag variant, ensuring the ReprPlan starts correct before any optimization runs):

Primitives (0-11):

Tag	Canonical MachineRepr	LLVM Type	Notes
`Int`	`Int { width: I64, signed: true }`	`i64`
`Float`	`Float { width: F64 }`	`double`
`Bool`	`Bool`	`i1`
`Str`	`FatPointer(FatRepr::Str)`	`{i64, i64, ptr}`	len + cap + data
`Char`	`Char`	`i32`	Unicode scalar
`Byte`	`Byte`	`i8`	Unsigned
`Unit`	`Unit`	`i64`	LLVM void workaround
`Never`	`Never`	`i64`	LLVM void workaround
`Error`	Panic/unreachable	—	Should never reach codegen
`Duration`	`Duration`	`i64`	Nanoseconds
`Size`	`Size`	`i64`	Bytes
`Ordering`	`Ordering`	`i8`	0/1/2

Simple containers (16-22):

Tag	Canonical MachineRepr	LLVM Type	Notes
`List`	`FatPointer(FatRepr::Collection)`	`{i64, i64, ptr}`	len + cap + data
`Option`	`Enum(...)`	`{i64, payload}`	Recurse into inner
`Set`	`FatPointer(FatRepr::Collection)`	`{i64, i64, ptr}`	len + cap + data
`Channel`	`OpaquePtr`	`ptr`	Runtime-managed
`Range`	`Range`	`{i64, i64, i64, i64}`	start/end/step/incl
`Iterator`	`OpaquePtr`	`ptr`	Runtime-managed
`DoubleEndedIterator`	`OpaquePtr`	`ptr`	Runtime-managed

Two-child containers (32-34):

Tag	Canonical MachineRepr	LLVM Type	Notes
`Map`	`FatPointer(FatRepr::Map)`	`{i64, i64, ptr}`	len + cap + data; retains key/value reprs
`Result`	`Enum(...)`	`{i64, max(ok,err)}`	Recurse into ok/err
`Borrowed`	Reserved — error if reached	—	Future use

Complex types (48-51):

Tag	Canonical MachineRepr	Notes
`Function`	`Closure(ClosureRepr)`	fn ptr + optional env ptr
`Tuple`	`Tuple(TupleRepr)`	Recurse into elements
`Struct`	`Struct(StructRepr)`	Recurse into fields
`Enum`	`Enum(EnumRepr)`	Recurse into variants

Named/resolved types (80-82):

Tag	Canonical MachineRepr	Notes
`Named`	`pool.resolve_fully(idx)` → recurse	Must resolve first — includes newtypes (`type UserId = int`) and FFI types (`CPtr`, `c_int`)
`Applied`	`pool.resolve_fully(idx)` → recurse	Must resolve first
`Alias`	`pool.resolve_fully(idx)` → recurse	Must resolve first

Newtype handling: type UserId = int uses Tag::Named in the Pool. resolve_fully() follows the Named→concrete chain, so canonical() transparently handles newtypes by recursing into the underlying type. The TypeRegistry stores TypeKind::Newtype { underlying } for semantic purposes (.inner access), but canonical() only needs the Pool-level resolution. No special case needed.

FFI types: CPtr, JsValue, c_int, c_char, etc. are named types in the FFI prelude, not Pool primitives. They resolve via Tag::Named → concrete. CPtr resolves to an opaque pointer (MachineRepr::OpaquePtr). C numeric types resolve to their corresponding primitives. No special case needed.

Type variables (96-98) — MUST NOT reach canonical:

Tag	Behavior	Notes
`Var`	Follow link chain via `pool.resolve_fully()`	If unresolved → panic (typeck bug)
`BoundVar`	Error — should be monomorphized	Typeck bug if reached
`RigidVar`	Error — should be monomorphized	Typeck bug if reached

Scheme/Special (112, 240-255) — MUST NOT reach canonical:

Tag	Behavior
`Scheme`	Error — should be instantiated
`Projection`	Error — should be resolved
`ModuleNs`	Error — not a value type
`Infer`	Error — should be resolved
`SelfType`	Error — should be resolved

Validation: The canonical mapping MUST produce the same LLVM types as the existing TypeInfo::storage_type() → compute_type_info_inner() pipeline. The parity test is implemented in §01.9 (storage type equivalence test, 29-type matrix) — not in this subsection. See §01.9 for the full coverage matrix and test requirements.

Define FatRepr to distinguish collection/string fat pointers:

#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum FatRepr {
    /// String: {i64 len, i64 cap, ptr data}
    Str,
    /// Collection ([T], {K:V}, Set<T>): {i64 len, i64 cap, ptr data}
    Collection { element_repr: Box<MachineRepr> },
}

Define ClosureRepr:

#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct ClosureRepr {
    /// Parameter representations
    pub params: Vec<MachineRepr>,
    /// Return representation
    pub ret: Box<MachineRepr>,
}

[TPR-01-005] Fix repr_size()/repr_align() for Unit/Never in aggregate layouts (2026-03-23):
- Split into field_size()/field_align() (Unit/Never = 0/1) and repr_size()/repr_align() (Unit/Never = 8/8 for ABI)
- compute_field_layout(), compute_payload_layout(), canonical_option(), canonical_result() all use field_size/field_align
- Semantic pin tests: ((), bool) = 1 byte, (bool, (), int) = 16 bytes, Option<()> = 8 bytes, struct(bool, unit) = 1 byte, (int, Never) = 8 bytes
[TPR-01-007] Fix canonical_panics_on_bound_var test (2026-03-23): constructs a real BoundVar via pool.intern(Tag::BoundVar, 0) and asserts panic. Separate canonical_panics_on_rigid_var test already existed.
[TPR-01-015] Add cycle detection to canonical() for recursive user types (2026-03-23):
- Public canonical() wraps canonical_inner() with visiting: &mut FxHashSet<Idx> cycle detection
- Recursive positions return MachineRepr::RcPointer(RcRepr { rc_width: I64, atomic: true, inner: OpaquePtr, stack_promotable: false })
- All helper functions (canonical_collection, canonical_map, canonical_function, canonical_tuple, canonical_struct, canonical_enum) thread the visiting set
- Tests: type Tree = Leaf(int) | Node(Tree, Tree) — no stack overflow, Node fields are RcPointer; type IntList = Nil | Cons(int, IntList) — semantic pin on RcPointer properties; repeated non-recursive type is NOT treated as cycle
[TPR-01-016] Make is_trivial_repr() recursive for compound types (2026-03-23):
- Struct(s) → s.trivial, Tuple(t) → t.trivial, Enum(e) → check all variant fields recursively
- FatPointer, Closure, RcPointer, OpaquePtr, StackPromoted → always false
- Tests: struct containing (int, bool) is trivial; struct containing (int, str) is not; all-unit enum trivial; scalar-payload enum in struct trivial

Derive requirement: ALL sub-repr types (StructRepr, EnumRepr, TupleRepr, FieldRepr, EnumTag, VariantRepr, RcRepr, FatRepr, ClosureRepr) MUST derive Debug, Clone, PartialEq, Eq, Hash to match MachineRepr’s derives. Code blocks below include them explicitly.

File placement: TupleRepr, StructRepr, FieldRepr, RcRepr, FatRepr, ClosureRepr → compiler/ori_repr/src/struct_repr.rs. EnumRepr, EnumTag, VariantRepr → compiler/ori_repr/src/enum_repr.rs. MachineRepr, IntWidth, FloatWidth → compiler/ori_repr/src/repr.rs. ReprPlan + builders → plan.rs with sub-modules plan/query.rs, plan/decision.rs, plan/repr_attr.rs. Canonical mapping split into canonical/mod.rs (pool traversal) + canonical/type_repr.rs (per-tag helpers). Layout utilities in layout.rs. All files under 500 lines.

Define TupleRepr:

#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct TupleRepr {
    /// Element representations in optimized memory order
    pub elements: Vec<FieldRepr>,
    pub size: u32,
    pub align: u32,
    pub trivial: bool,
}

Define StructRepr:

#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct StructRepr {
    /// Fields in optimized memory order (may differ from declaration order)
    pub fields: Vec<FieldRepr>,
    /// Total size in bytes (including padding)
    pub size: u32,
    /// Alignment requirement
    pub align: u32,
    /// Whether all fields are trivial (no RC needed)
    pub trivial: bool,
}

#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct FieldRepr {
    /// Original field name (interned via Name from ori_ir).
    /// Required by §06 for: (1) debug symbol emission (DWARF needs names),
    /// (2) C-ABI verification (declaration order must match for #repr("c")),
    /// (3) tracing output (audit trail logs field names, not indices).
    pub name: Name,
    /// Original field index in declaration order (0-based).
    /// `fields[i].original_index` tells codegen the source order after
    /// §06 may have reordered `fields` by alignment/size.
    pub original_index: u32,
    /// Offset in bytes from struct start (set by §06 layout algorithm)
    pub offset: u32,
    /// Machine representation of this field
    pub repr: MachineRepr,
}

Define EnumRepr:

#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct EnumRepr {
    /// Discriminant representation
    pub tag: EnumTag,
    /// Per-variant payload representations
    pub variants: Vec<VariantRepr>,
    /// Total size including tag and padding
    pub size: u32,
    pub align: u32,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum EnumTag {
    /// Explicit tag field at offset 0
    Explicit { width: IntWidth },
    /// Niche — tag stored in invalid bit pattern of a field
    Niche { field_index: u32, niche_value: u64 },
    /// No tag needed (single inhabited variant, e.g. newtype)
    None,
}

Define VariantRepr:

#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct VariantRepr {
    /// Variant name (interned)
    pub name: Name,
    /// Field representations (empty for unit variants)
    pub fields: Vec<MachineRepr>,
    /// Size of this variant's payload (excluding tag)
    pub size: u32,
    /// Alignment of this variant's payload
    pub alignment: u32,
}

impl VariantRepr {
    /// Whether this variant is a pointer type (for tagged pointer optimization)
    pub fn is_pointer(&self) -> bool {
        self.fields.len() == 1
            && matches!(
                &self.fields[0],
                MachineRepr::RcPointer(_) | MachineRepr::FatPointer(_) | MachineRepr::OpaquePtr
            )
    }
}

Define RcRepr:

#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct RcRepr {
    /// Width of the reference count header
    pub rc_width: IntWidth,
    /// Whether RC operations are atomic
    pub atomic: bool,
    /// The inner data representation
    pub inner: Box<MachineRepr>,
    /// Whether this is stack-promotable (escape analysis)
    pub stack_promotable: bool,
}

01.2 ReprDecision Tracking

File(s): compiler/ori_repr/src/plan.rs

Each narrowing decision should be recorded with its justification, so that:

Debug output can explain why a type was narrowed
Bugs can be traced to the specific analysis that made the decision
Later passes can query upstream decisions

Define ReprDecision:

#[derive(Debug, Clone)]
pub struct ReprDecision {
    /// Which analysis pass made this decision
    pub source: DecisionSource,
    /// The semantic type this applies to
    pub type_idx: Idx,
    /// The chosen machine representation
    pub repr: MachineRepr,
    /// Why this representation was chosen (for tracing)
    pub reason: DecisionReason,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum DecisionSource {
    /// §02: Transitive triviality analysis
    Triviality,
    /// §03/§04: Value range → integer narrowing
    IntegerNarrowing,
    /// §03/§05: Precision analysis → float narrowing
    FloatNarrowing,
    /// §06: Struct field reordering
    StructLayout,
    /// §07: Enum niche/discriminant
    EnumRepr,
    /// §08: Escape analysis
    EscapeAnalysis,
    /// §09: ARC header compression
    ArcHeader,
    /// §10: Thread-local ARC
    ThreadLocal,
    /// §11: Collection specialization
    CollectionSpec,
    /// Default: canonical representation (no optimization)
    Canonical,
}

/// Reason for a narrowing decision — used in audit trail and debug tracing.
///
/// NOTE: `ValueRange` is defined in §03 (`ori_repr/src/range/mod.rs`).
/// Until §03 is implemented, `ori_repr/src/range/mod.rs` must export a
/// placeholder: `pub struct ValueRange;` (or `pub type ValueRange = ();`).
/// `DecisionReason::RangeFits` MUST compile from day one so the crate builds.
/// The placeholder is replaced by the real type in §03. See §01.10 checklist
/// item "ValueRange placeholder" for the required stub.
#[derive(Debug, Clone)]
pub enum DecisionReason {
    /// Type is canonically this width (no narrowing applied)
    Canonical,
    /// Value range fits in narrower type.
    /// `range` is the computed ValueRange from §03; `min_width` is the
    /// narrowest IntWidth that covers the range.
    RangeFits { range: ValueRange, min_width: IntWidth },
    /// All fields are trivial, no RC needed
    TransitivelyTrivial,
    /// Value never escapes function scope (from §08 escape analysis)
    DoesNotEscape,
    /// Sharing bound is within RC width (from §09 sharing analysis)
    BoundedSharing { max_refs: u32 },
    /// Niche available in field (from §07 enum niche analysis)
    NicheAvailable { field: u32, niche: u64 },
    /// Custom reason (for tracing)
    Custom(String),
}

Define ReprPlan — the central data structure:

// FxHashMap from `rustc-hash` crate (workspace dep): `use rustc_hash::FxHashMap;`
// Functions are identified by Name (from ori_ir), not FunctionId (ori_llvm-specific).
pub struct ReprPlan {
    /// Per-type decisions (indexed by Pool Idx)
    decisions: FxHashMap<Idx, ReprDecision>,
    /// Per-type #repr attributes (only for structs/enums with explicit attrs)
    /// See §01.7 for ReprAttribute enum definition.
    repr_attrs: FxHashMap<Idx, ReprAttribute>,
    /// Per-function escape info (indexed by function Name)
    /// NOTE: EscapeInfo is defined in §08 (escape/mod.rs). This field is
    /// empty until §08 populates it. Initially use `type EscapeInfo = ();`
    /// as a placeholder, replaced when §08 is implemented.
    escape_info: FxHashMap<Name, EscapeInfo>,
    /// Per-function, per-variable ranges from §03 range analysis.
    /// Key: function Name → (ArcVarId → ValueRange).
    /// Populated by §03, consumed by §04 (integer narrowing for locals/fields).
    /// NOTE: ValueRange is defined in §03 (range/mod.rs). Use `type ValueRange = ();`
    /// as a placeholder until §03 is implemented.
    function_var_ranges: FxHashMap<Name, FxHashMap<ArcVarId, ValueRange>>,
    /// Audit trail — all decisions in order
    audit: Vec<ReprDecision>,
}

Implement builder pattern for populating ReprPlan:

impl ReprPlan {
    pub fn new() -> Self { ... }

    /// Record a narrowing decision. Later decisions override earlier ones
    /// for the same type, but the audit trail preserves both.
    pub fn set_repr(&mut self, idx: Idx, decision: ReprDecision) { ... }

    /// Query the representation for a type
    pub fn get_repr(&self, idx: Idx) -> Option<&MachineRepr> { ... }

    /// Get the canonical (un-narrowed) representation for a tag
    pub fn canonical(tag: Tag) -> MachineRepr { ... }

    /// Record per-variable range analysis results for a function (§03 output).
    /// Called after `range_fixpoint()` completes for a function.
    pub fn set_var_ranges(
        &mut self,
        func: Name,
        ranges: FxHashMap<ArcVarId, ValueRange>,
    ) { ... }

    /// Get the range for a variable in a function (from §03 range analysis).
    /// Returns the "unknown / unconstrained" range if no range was recorded.
    /// In §01's placeholder, this returns the default `ValueRange` value.
    /// In §03's real implementation, this returns `ValueRange::Top` (no constraints).
    pub fn var_range(&self, func: Name, var: ArcVarId) -> ValueRange { ... }

    /// Dump the audit trail for debugging
    pub fn dump_audit(&self, pool: &Pool) -> String { ... }
}

Tests required for §01.2 (add to tests.rs, write failing tests BEFORE implementing):

set_repr / get_repr round-trip: set a decision for Tag::Int, retrieve it, assert the MachineRepr matches.
Override behavior: call set_repr twice for the same Idx; verify get_repr returns the second decision’s repr.
Audit trail preservation: after the override above, verify dump_audit() contains BOTH entries in insertion order.
get_repr on unknown Idx returns None (not a panic, not a default).
var_range on a function with no recorded ranges returns the default/top value (not a panic).
set_var_ranges / var_range round-trip: record ranges for two functions, verify each function’s var_range query is isolated.
dump_audit output is non-empty after decisions are recorded and contains the type tag and source in its string representation.

01.3 Pipeline Integration Point

File(s): compiler/ori_llvm/src/codegen/type_info/mod.rs (TypeLayoutResolver), compiler/ori_llvm/src/codegen/type_info/store.rs (TypeInfoStore — Tag→TypeInfo mapping), compiler/ori_llvm/src/codegen/function_compiler/mod.rs (FunctionCompiler), compiler/ori_llvm/src/evaluator/compile.rs (JIT entry point), compiler/oric/src/commands/codegen_pipeline.rs (AOT entry point — run_codegen_pipeline()), compiler/oric/src/commands/build_options/mod.rs + build_options/parse_args.rs, compiler/oric/src/commands/build/mod.rs (for --no-repr-opt CLI flag)

The ReprPlan must be computed AFTER type checking and BEFORE LLVM codegen. The codegen must consume ReprPlan instead of computing representations inline.

Add ori_repr dependency to ori_llvm/Cargo.toml

Create the ReprPlan computation entry point:

// In ori_repr/src/lib.rs
//
// `arc_functions`: all ArcFunction values from the ARC pipeline — needed by
//   §03 (range analysis per ArcFunction) and §08 (escape analysis per ArcFunction).
//   §01 itself does not use them, but the signature must be established now so
//   later sections can add their passes without changing the call sites in oric.
//
// `policy`: from --no-repr-opt / ORI_NO_REPR_OPT — see NarrowingPolicy in §01.4.
pub fn compute_repr_plan(
    pool: &Pool,
    arc_functions: &[ArcFunction],
    policy: NarrowingPolicy,
) -> ReprPlan {
    let mut plan = ReprPlan::new(policy);

    // Phase 1: Set canonical representations for all types (§01)
    populate_canonical(&mut plan, pool);

    // Phase 2: Triviality analysis (§02)
    // Stub: analyze_triviality(&mut plan, pool);
    // Added in §02 — see analyze_triviality() in ori_repr/src/triviality/mod.rs

    // Phase 3: Range analysis (§03) → Integer narrowing (§04)
    //   → Float narrowing (§05)
    // Stub: analyze_ranges(&mut plan, pool, arc_functions);
    //       apply_integer_narrowing(&mut plan, pool);
    //       apply_float_narrowing(&mut plan, pool);
    // Added in §03, §04, §05

    // Phase 4: Struct layout (§06), Enum repr (§07)
    // Stub: compute_struct_layouts(&mut plan, pool);
    //       compute_enum_reprs(&mut plan, pool);
    // Added in §06, §07

    // Phase 5: Escape analysis (§08) → ARC header (§09)
    //   → Thread-local (§10)
    // Stub: analyze_escape(&mut plan, pool, arc_functions);
    //       compress_arc_headers(&mut plan, pool);
    //       apply_thread_local_arc(&mut plan, pool, arc_functions);
    // Added in §08, §09, §10

    // Phase 6: Collection specialization (§11)
    // Stub: specialize_collections(&mut plan, pool);
    // Added in §11

    plan
}

Stub function requirement: To keep ori_repr immediately compilable and allow §02-§11 to be developed independently, §01 must provide empty stub functions for each pass that compute_repr_plan() will eventually call. Each stub lives in its own module (created by the corresponding section). For §01, add these to lib.rs or the module root with #[allow(dead_code)]:

// Stubs — replaced by real implementations in §02-§11
fn analyze_triviality(_plan: &mut ReprPlan, _pool: &Pool) {}
fn analyze_ranges(_plan: &mut ReprPlan, _pool: &Pool, _fns: &[ArcFunction]) {}
fn apply_integer_narrowing(_plan: &mut ReprPlan, _pool: &Pool) {}
fn apply_float_narrowing(_plan: &mut ReprPlan, _pool: &Pool) {}
fn compute_struct_layouts(_plan: &mut ReprPlan, _pool: &Pool) {}
fn compute_enum_reprs(_plan: &mut ReprPlan, _pool: &Pool) {}
fn analyze_escape(_plan: &mut ReprPlan, _pool: &Pool, _fns: &[ArcFunction]) {}
fn compress_arc_headers(_plan: &mut ReprPlan, _pool: &Pool) {}
fn apply_thread_local_arc(_plan: &mut ReprPlan, _pool: &Pool, _fns: &[ArcFunction]) {}
fn specialize_collections(_plan: &mut ReprPlan, _pool: &Pool) {}

Modify TypeLayoutResolver in ori_llvm to accept &ReprPlan:
- Currently: TypeLayoutResolver::new(store, scx, interner) where store: &TypeInfoStore, scx: &SimpleCx, interner: Option<&StringInterner> → reads TypeInfo from store (which reads Tag from Pool)
- Target: TypeLayoutResolver::new(store, scx, interner, repr_plan) → reads MachineRepr from plan when available, falling back to TypeInfo for unoptimized types
- Initially, ReprPlan returns canonical representations (zero behavioral change)
Wire ReprPlan through the LLVM codegen entry points:
- JIT path: OwnedLLVMEvaluator::compile_module_with_tests() (in evaluator/compile.rs) creates ReprPlan. Add narrowing_policy: NarrowingPolicy as a new last parameter (after arc_cache) — callers pass NarrowingPolicy::Aggressive by default or NarrowingPolicy::Disabled when the test runner sets ORI_NO_REPR_OPT.
- AOT path: run_codegen_pipeline() in compiler/oric/src/commands/codegen_pipeline.rs creates ReprPlan before constructing FunctionCompiler. Add narrowing_policy: NarrowingPolicy as a new last parameter. This function is called from compile_common.rs::compile_to_llvm() and compile_to_llvm_with_imports() — both callers must thread the policy through from BuildOptions.narrowing_policy.
- codegen_pipeline.rs creates TypeLayoutResolver with Some(&repr_plan) before constructing FunctionCompiler. FunctionCompiler accesses the plan indirectly via its type_resolver: &TypeLayoutResolver field — no direct repr_plan field was added to FunctionCompiler. Same pattern in the JIT path.
Add --no-repr-opt flag to the ori build CLI (compiler/oric/src/commands/build_options/mod.rs for the flag definition, build_options/parse_args.rs for parse_single_arg(), compiler/oric/src/commands/build/mod.rs for CLI integration, compiler/oric/src/commands/codegen_pipeline.rs for enforcement):
- Add narrowing_policy: NarrowingPolicy field to BuildOptions (import NarrowingPolicy from ori_repr); default to NarrowingPolicy::Aggressive
- Parse --no-repr-opt in parse_build_options() → set options.narrowing_policy = NarrowingPolicy::Disabled
- Thread BuildOptions.narrowing_policy through compile_common.rs → run_codegen_pipeline() (the new last parameter added above)
- When narrowing_policy == NarrowingPolicy::Disabled, compute_repr_plan() returns after populate_canonical() (canonical-only plan — zero behavioral change vs today)
- This flag is required by §12.2 for dual-execution comparison: AOT without optimizations vs. AOT with optimizations
- Add ORI_NO_REPR_OPT=1 environment variable as an alternative (same effect as --no-repr-opt); check it in run_codegen_pipeline() alongside the policy parameter
- Do NOT use repr_opt_disabled: bool — use NarrowingPolicy so future conservative mode is also expressible
- Hygiene fix while touching this file: build_options.rs line 15 uses #[allow(clippy::struct_excessive_bools, reason = ...)] — change to #[expect(clippy::struct_excessive_bools, reason = ...)] per lint discipline rules
Keep ori_repr tracing compatible with the existing generic ORI_LOG / RUST_LOG filter in compiler/oric/src/tracing_setup.rs:
- No tracing registry change is needed today — tracing_setup.rs already forwards arbitrary targets through EnvFilter
- Emit tracing events from the new crate under target ori_repr
- Add a smoke test or manual verification step showing ORI_LOG=ori_repr=trace ori build ... surfaces ori_repr events without extra CLI wiring

Tests required for §01.3 (write failing tests BEFORE implementing):

--no-repr-opt CLI flag: ori build --no-repr-opt tests/benchmarks/bench_small.ori succeeds with exit code 0. Verified via compute_repr_plan_disabled_policy_skips_stubs unit test + ./test-all.sh green.
ORI_NO_REPR_OPT=1 env var: env var checked in both parse_build_options() and JIT path. Unit test compute_repr_plan_zero_behavioral_change_with_disabled verifies identical canonical output.
NarrowingPolicy::Aggressive is the default: unit test compute_repr_plan_aggressive_is_default_behavior verifies Aggressive policy + canonical I64 int.
Zero behavioral change: unit test compute_repr_plan_zero_behavioral_change_with_disabled verifies identical canonical representations for all 11 primitives regardless of policy. ./test-all.sh (13,729 tests) green.
Phase A fallback: TypeLayoutResolver stores repr_plan but does not read it yet (Phase A dead_code annotation). When ReprPlan has canonical-only entries, all existing tests pass unchanged (13,729 green). Full routing in §01.8.
All existing tests pass: ./test-all.sh green. ./llvm-test.sh green.

01.4 ReprPlan Query Interface

File(s): compiler/ori_repr/src/plan/query.rs

Provide ergonomic query methods that later sections will use:

Phase boundary: ori_repr must NEVER import from ori_llvm or ori_eval. LLVM-specific convenience methods (e.g., llvm_int_type(plan, idx, ctx)) belong in ori_llvm as an extension trait (impl ReprPlanExt for ReprPlan), not in ori_repr.

Width and triviality queries:

impl ReprPlan {
    /// Get the machine integer width for a type (defaults to I64).
    /// Used by §04 (integer narrowing) and §06 (struct layout).
    pub fn int_width(&self, idx: Idx) -> IntWidth { ... }

    /// Get the machine float width for a type (defaults to F64).
    /// Used by §05 (float narrowing) and §07 (enum niche analysis).
    pub fn float_width(&self, idx: Idx) -> FloatWidth { ... }

    // NOTE: LLVM-specific methods like `llvm_int_type(idx, ctx) -> IntType`
    // belong in ori_llvm (e.g., as an extension trait or helper), not in
    // ori_repr, since ori_repr must remain backend-independent.

    /// Is this type trivial (no RC needed)?
    /// Used by §02 (triviality), §08 (escape), §09 (header compression).
    pub fn is_trivial(&self, idx: Idx) -> bool { ... }

    /// Does this value escape its defining function?
    /// `var` is an `ArcVarId` from `ori_arc::ir` — `ori_repr` depends on
    /// `ori_arc` already (for ArcFunction), so this import is clean.
    /// Used by §08 (escape analysis) and §09 (header compression).
    ///
    /// NOTE: §01 implementation hardcodes `true` (safe default — never
    /// stack-promotes). §08 MUST update the query body to consult
    /// `self.escape_info` — calling `set_escape_info()` alone is NOT
    /// sufficient; the query method itself must be changed to read from
    /// the stored data.
    pub fn escapes(&self, func: Name, var: ArcVarId) -> bool { ... }

    /// What RC strategy should be used for this allocation?
    /// Populated by §09 (ARC header compression) and §10 (thread-local ARC).
    /// Returns `RcStrategy::Atomic { width: I64 }` if no decision recorded.
    pub fn rc_strategy(&self, idx: Idx) -> RcStrategy { ... }
}

/// Plan-level narrowing policy — set via `--no-repr-opt` or `ORI_NO_REPR_OPT`.
/// Stored in `ReprPlan` at construction time; every analysis pass checks it.
/// §04 uses `NarrowingPolicy::Disabled` to skip integer narrowing.
/// §05 uses it to skip float narrowing.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NarrowingPolicy {
    /// All narrowing optimizations enabled (default)
    Aggressive,
    /// Conservative: only narrow when provably safe, no field narrowing
    Conservative,
    /// All narrowing disabled (--no-repr-opt / ORI_NO_REPR_OPT)
    Disabled,
}

/// RC strategy for an allocation, set by §09 and §10.
/// Default (no decision recorded): `Atomic { width: I64 }` — matches
/// current `ori_rt` behavior exactly, so §01 is a zero-behavioral-change pass.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RcStrategy {
    /// No RC needed (trivial or stack-promoted)
    None,
    /// Atomic RC with given header width (thread-shared allocations)
    Atomic { width: IntWidth },
    /// Non-atomic RC (thread-local proven by §10)
    NonAtomic { width: IntWidth },
}

Add narrowing_policy field to ReprPlan and expose via constructor:

pub struct ReprPlan {
    // ... existing fields ...
    /// Narrowing policy — set from --no-repr-opt / ORI_NO_REPR_OPT.
    /// Every analysis pass that performs narrowing MUST check this first.
    narrowing_policy: NarrowingPolicy,
}

impl ReprPlan {
    pub fn new(policy: NarrowingPolicy) -> Self { ... }
    pub fn narrowing_policy(&self) -> NarrowingPolicy { self.narrowing_policy }
}

Tests required for §01.4 (write failing tests BEFORE implementing):

int_width default: plan.int_width(int_idx) returns IntWidth::I64 when no decision has been recorded for that type.
float_width default: plan.float_width(float_idx) returns FloatWidth::F64 when no decision recorded.
is_trivial default: plan.is_trivial(any_idx) returns false when no triviality decision recorded (safe default — never elides RC it shouldn’t).
escapes default: plan.escapes(func, var) returns true when no escape info recorded (safe default — never stack-promotes when unsure).
rc_strategy default: plan.rc_strategy(any_idx) returns RcStrategy::Atomic { width: IntWidth::I64 } when no decision recorded (matches current ori_rt behavior exactly).
After set_rc_strategy(idx, RcStrategy::None, DecisionSource::Triviality), rc_strategy(idx) returns RcStrategy::None (write→read round-trip, distinct from default).
narrowing_policy round-trip: ReprPlan::new(NarrowingPolicy::Disabled).narrowing_policy() returns NarrowingPolicy::Disabled.
Semantic pin: rc_strategy default must return Atomic { I64 } — NOT None and NOT NonAtomic. This test must fail if the default is changed. Ensures that §01 alone causes zero behavioral change.

Add writer methods for escape info and RC strategy (called by §08 and §09):

impl ReprPlan {
    /// Record escape info for a function's variables (called by §08).
    /// Replaces the previously empty `escape_info` entry for this function.
    pub fn set_escape_info(&mut self, func: Name, info: EscapeInfo) { ... }

    /// Record the RC strategy for a type (called by §09, §10).
    /// Stores by updating the `MachineRepr::RcPointer` entry for `idx` and
    /// recording a `ReprDecision` with source ArcHeader or ThreadLocal.
    pub fn set_rc_strategy(&mut self, idx: Idx, strategy: RcStrategy, source: DecisionSource) { ... }
}

Tracing integration — public query APIs must emit trace events (TPR-01-033) (2026-03-24):
- Route int_width, float_width, is_trivial, escapes, rc_strategy through traced wrappers or add inline tracing::trace! calls.
- Remove or wire get_repr_traced() — removed (zero callers; query methods now have inline tracing).
- Verify: ORI_LOG=ori_repr=debug shows populated canonical representations event. Query-level trace events (int_width, float_width, etc.) will fire when consumers call query methods (§02+).
[TPR-01-034] Fix BuildOptions::merge() dropping link_mode and jobs (2026-03-24):
- Add link_mode merge logic to BuildOptions::merge() — only override if parsed value differs from default (LinkMode::Static).
- Add jobs merge logic to BuildOptions::merge() — if other.jobs.is_some() { self.jobs = other.jobs; }.
- Regression tests: ori build foo.ori --link=dynamic → verify link_mode == Dynamic survives merge.
- Regression tests: ori build foo.ori --jobs=4 → verify jobs == Some(4) survives merge.
- Regression tests: multi-arg accumulation: ori build foo.ori --link=dynamic --jobs=4 --release → all three fields survive.
[TPR-01-035] Replace no_repr_opt: bool with NarrowingPolicy end-to-end (2026-03-24):
- Replace BuildOptions.no_repr_opt: bool with BuildOptions.narrowing_policy: NarrowingPolicy (default Aggressive).
- Update parse_build_options(): --no-repr-opt → NarrowingPolicy::Disabled, add --repr-opt=aggressive|conservative|disabled.
- Update BuildOptions::merge(): merge narrowing_policy field (non-default overrides).
- Update compile_to_llvm() in compile_common.rs: accept NarrowingPolicy instead of bool.
- Update run_codegen_pipeline() in codegen_pipeline.rs: accept NarrowingPolicy directly (remove bool→enum conversion).
- Update JIT path compile_module_with_tests() in ori_llvm/src/evaluator/compile.rs: accept optional NarrowingPolicy parameter.
- Update env var fallback: NarrowingPolicy::env_disabled() remains for JIT when no parameter provided.
- Regression tests: --no-repr-opt → Disabled, --repr-opt=conservative → Conservative, default → Aggressive.
- Regression tests: NarrowingPolicy survives the full AOT path from CLI to compute_repr_plan().

01.5 Generic Type Handling

File(s): compiler/ori_repr/src/plan.rs, compiler/ori_repr/src/lib.rs

ReprPlan operates on monomorphized types only. Generic types (containing Var, BoundVar, RigidVar) cannot be mapped to concrete machine representations.

Enforce monomorphization precondition (2026-03-24, pre-existing):
- compute_repr_plan() must be called AFTER monomorphization (all type variables resolved)
- canonical() must assert/panic on Tag::Var, Tag::BoundVar, Tag::RigidVar, Tag::Scheme, Tag::Infer
- For Tag::Named/Tag::Applied/Tag::Alias: always resolve via pool.resolve_fully() first — if resolution yields a type variable, it’s a monomorphization bug
Handle Option<T> and Result<T, E> generically (2026-03-24, pre-existing):
- After monomorphization, Option<int> is a concrete type with Tag::Option and inner Idx pointing to Tag::Int
- The canonical() function recurses: Option<int> → Enum(EnumRepr { variants: [Some(Int{I64}), None] })
- This works because Pool interning deduplicates: Option<int> at two call sites shares the same Idx
Monomorphization boundary (2026-03-24, pre-existing):
- Currently, Ori does NOT have explicit monomorphization pass — type checker infers concrete types, and Pool stores them
- The pool.resolve_fully() chain handles substitution transparently
- ReprPlan must call pool.resolve_fully(idx) before computing canonical for ANY type to ensure all variables are resolved
- If resolve_fully() returns a variable → skip this type (it’s dead code or a typeck bug)
[TPR-01-021] Fix canonical() mutual recursion contract violation (2026-03-24):
- Fixed: Added shared memoization cache (FxHashMap<Idx, MachineRepr>) to canonical_inner() that persists across populate_canonical(). Completed types are cached; subsequent calls return the cached result regardless of traversal order. try_canonical_cached() snapshots cache before catch_unwind to prevent partial entries on panic.
- Verify: canonical_mutual_recursion_consistent test passes — nested B inside A matches standalone B.

Tests required for §01.5 (write failing tests BEFORE implementing):

canonical() on Tag::Var (unresolved) panics with a message identifying it as a typeck bug (pre-existing: canonical_panics_on_var).
canonical() on Tag::BoundVar panics (pre-existing: canonical_panics_on_bound_var).
canonical() on Tag::RigidVar panics (pre-existing: canonical_panics_on_rigid_var).
canonical() on Tag::Scheme panics (2026-03-24: canonical_panics_on_scheme).
canonical() on Tag::Infer panics (2026-03-24: canonical_panics_on_infer).
pool.resolve_fully() round-trip: Named→Int resolves to Int { I64, true } (2026-03-24: canonical_named_resolves_to_int).
Option<int> after resolution produces a 2-variant Enum repr (pre-existing: canonical_option_int).
Edge case: Named chain A→B→Int resolves to Int { I64, true } (2026-03-24: canonical_alias_chain_resolves).

01.6 Salsa Integration Strategy

File(s): compiler/ori_repr/src/lib.rs, compiler/oric/src/commands/codegen_pipeline.rs

The ReprPlan must integrate with the existing Salsa-based compilation model.

ReprPlan is NOT a Salsa tracked struct — it is computed imperatively:
- Salsa works best for demand-driven, memoizable queries (parsing, type checking)
- ReprPlan computation is a forward pass that mutates state across multiple analysis phases (triviality → range → narrowing → layout)
- Making each phase a Salsa query would create artificial dependencies and complicate the multi-pass mutation pattern
- Instead: compute ReprPlan once, pass it as &ReprPlan to codegen (same model as how TypeInfoStore works today)
- Verified: compute_repr_plan() is a pure function in lib.rs:52, not #[salsa::tracked]. AOT path at codegen_pipeline.rs:317, JIT path at evaluator/compile.rs:169. (2026-03-24)
Invalidation model:
- ReprPlan is invalidated when the Pool changes (new/modified types)
- In the current compilation model, this means: recompute ReprPlan on every compilation
- Future optimization: if Pool didn’t change (Salsa cache hit on type checking), reuse previous ReprPlan
- This can be implemented as a Salsa query that takes Pool hash → ReprPlan, memoized by Pool identity
- Verified: both AOT and JIT paths call compute_repr_plan() fresh on each compilation — no caching. Documented in plan.rs and lib.rs module docs. (2026-03-24)
JIT hot-reload compatibility:
- JIT recompiles individual functions — the ReprPlan for unchanged functions is stable
- When a function’s type signature changes, only that function’s entries need recomputation
- For now: recompute entire ReprPlan per JIT invocation (same as TypeInfoStore today)
- Future: incremental ReprPlan updates keyed by function-level Merkle hashes
- Verified: OwnedLLVMEvaluator::compile_module_with_tests() at evaluator/compile.rs:169 recomputes ReprPlan per invocation. (2026-03-24)
Thread safety:
- ReprPlan is immutable after computation — &ReprPlan is Send + Sync
- No interior mutability needed (unlike TypeInfoStore which uses RefCell for lazy population)
- All analysis passes write to a &mut ReprPlan during computation, then freeze it for codegen
- Verified: compile-time Send + Sync assertion added to plan.rs. All fields are FxHashMap/Vec — zero RefCell/Mutex. Contrasts with TypeInfoStore which has 4 RefCell fields. (2026-03-24)

01.7 `#repr` Attribute Integration

File(s): compiler/ori_repr/src/plan/repr_attr.rs, compiler/ori_ir/src/ast/items/types.rs (TypeDecl — needs new field), compiler/ori_parse/src/grammar/item/type_decl.rs (parser — needs to wire attrs.repr), compiler/ori_types/src/check/registration/user_types.rs (needs to propagate repr through type registration)

The spec (Clause 26 — FFI) defines layout attributes that override the canonical representation:

#repr("c") — C-compatible layout, no field reordering
#repr("packed") — No padding, alignment = 1
#repr("transparent") — Same layout as single field (newtypes)
#repr("aligned", N) — Minimum N-byte alignment (power of two)

These must be threaded into ReprPlan to prevent optimizations from violating user intent.

Current state — PIPELINE GAP: ori_parse parses #repr into ParsedAttrs.repr: Option<ReprAttr> (defined in compiler/ori_parse/src/grammar/attr/mod.rs). However, the parser does NOT store repr in TypeDecl (only derives is wired). TypeDecl in compiler/ori_ir/src/ast/items/types.rs has no repr field. The ReprAttr enum carries #[allow(dead_code, reason = "variants used when codegen consumes repr attributes")] — confirming the gap. §01.7 must close this gap end-to-end before populate_canonical() can read repr attributes.

Ordering constraint: The three GAP-CLOSE steps below modify ori_ir, ori_parse, and ori_types — crates that ori_repr will depend on. Implement and cargo check these steps BEFORE creating the ori_repr crate. If ori_repr is created first without TypeDecl.repr present, populate_canonical() cannot query repr attributes and its implementation will be incomplete from day one.

Pipeline gap steps required (before the ReprPlan steps below):

[GAP-CLOSE] Add repr: Option<ReprAttrKind> to TypeDecl in compiler/ori_ir/src/ast/items/types.rs (2026-03-24): Defined ReprAttrKind enum in ori_ir (parallel to ori_parse::ReprAttr) to avoid inverting the dependency. The parser converts via convert_repr_attr() during AST construction.
- Hygiene fix: Removed #[allow(dead_code)] entirely from ReprAttr — no longer dead code since convert_repr_attr() consumes all variants.
[GAP-CLOSE] Wire attrs.repr through the parser in compiler/ori_parse/src/grammar/item/type_decl.rs (2026-03-24): attrs.repr.as_ref().map(convert_repr_attr) converts and stores in TypeDecl.repr. Incremental copier also updated.
[GAP-CLOSE] Flow TypeDecl.repr through ori_types type registration (2026-03-24): Added repr: Option<ReprAttrKind> to TypeEntry. Wired through register_struct(), register_enum(), register_newtype(). Codegen pipeline extracts from TypedModule.types and passes to compute_repr_plan(). Both AOT and JIT paths updated.
Define ReprAttribute enum in ori_repr (pre-existing from §01.2): Already defined in plan/repr_attr.rs with 6 variants: Default, C, Packed, Transparent, Aligned(u32), CAligned(u32).
Store ReprAttribute per struct/enum in ReprPlan (pre-existing from §01.2): repr_attrs: FxHashMap<Idx, ReprAttribute> with set_repr_attr()/repr_attr() methods.
Gate optimization passes on ReprAttribute (2026-03-24): Contract established: ReprAttribute stored in ReprPlan.repr_attrs, queryable via plan.repr_attr(idx). Actual gating is §06/§07 work — §01 establishes the storage and query contract only.
Populate during compute_repr_plan() (2026-03-24): Added repr_attrs: &[(Idx, ReprAttrKind)] parameter to compute_repr_plan(). Conversion from ReprAttrKind → ReprAttribute via convert_repr_attr_kind(). Stored in plan before populate_canonical().
- Validation added in ori_types register_type_decl() (E2041):
  - #repr("transparent") requires exactly one field
  - #repr("aligned", N) requires N > 0 and power of two
- Combination validation (packed+c, packed+aligned): parser stores only one #repr — combinations cannot be specified yet

Tests required for §01.7 (write failing tests BEFORE implementing — matrix covers all 4 valid attrs + invalid combos):

01.8 Migration Strategy: TypeInfoStore → ReprPlan

File(s): compiler/ori_llvm/src/codegen/type_info/store.rs, compiler/ori_llvm/src/codegen/type_info/info.rs

The existing TypeInfoStore and TypeInfo enum must coexist with ReprPlan during migration. The goal is gradual adoption, not a big-bang replacement.

Phase A — Parallel operation (§01 scope): (2026-03-24)
- TypeLayoutResolver accepts optional &ReprPlan (wired in §01.3)
- resolve_inner() consults ReprPlan first via try_repr_to_llvm_type() for non-recursive types; falls back to TypeInfoStore for recursive types (Struct/Enum/Tuple) and when no decision exists
- When ReprPlan is None, uses TypeInfoStore exclusively
- Zero behavioral change verified: 13,786 tests pass, 5 new Phase A tests confirm equivalence
- try_repr_to_llvm_type() handles all MachineRepr variants: Int (all widths), Float (F32/F64), Bool, Char, Byte, Duration, Size, Ordering, Unit, Never, Range, FatPointer, OpaquePtr, RcPointer, Closure
- Added type_i16() and type_f32() to SimpleCx for narrowed width support
Phase B — Triviality unification (§02 scope): (2026-03-25)
- TypeInfoStore::new_with_plan() constructor pre-computes triviality from ReprPlan at construction
- TypeInfoStore::is_trivial() uses cache (populated from plan in production, lazy-computed in tests)
- Production paths (JIT + AOT) use new_with_plan() — classify_trivial() is never called
- classify_trivial() and cache fields retained as fallback for ~100 test call sites using new()
- 13,979 tests pass in debug; release build clean
Phase C — Full migration (§06/§07 scope): Deferred to §07 implementation. §01 own work is complete; Phase C is a consumer-side migration that will be executed as part of §07’s codegen work when enum repr lands. Tracked as a §07 prerequisite, not §01 remaining work. (2026-03-30)
- TypeLayoutResolver::storage_type() reads from ReprPlan for ALL types
- TypeInfoStore::compute_type_info_inner() is no longer called from production code
- TypeInfo enum is retained only as a compatibility adapter for tests that don’t use ReprPlan
- Eventually, TypeInfo becomes #[cfg(test)] only
Validation at each phase: (2026-03-24, Phase A validated)
- Phase A: 5 tests verify ReprPlan→LLVM type equivalence for primitives and composites, including override verification (i32 narrowing proves ReprPlan path exercised) and semantic pin (empty plan = no plan)
- Phase B: same split + assert_eq!(repr_plan.is_trivial(idx), type_info_store.is_trivial(idx))
- Phase C: remove TypeInfoStore from production; tests use ReprPlan directly — divergence disappears

Tests required for §01.8 Phase A (write failing tests BEFORE implementing):

Phase A fallback for each of the 12 primitive tags (2026-03-24). Rust test: phase_a_fallback_primitives.
Phase A fallback for composite types (Option, Result, Tuple, Struct, Enum) (2026-03-24). Rust test: phase_a_fallback_composites. Named structs compared by field count due to LLVM name uniquification.
Phase A override: populate ReprPlan with a narrowed I32 decision for Tag::Int. Verifies the ReprPlan path produces i32 (not i64), proving the override mechanism works (2026-03-24). Rust test: phase_a_override_uses_repr_plan.
Phase A with None ReprPlan: backward-compatibility test (2026-03-24). Rust test: phase_a_none_repr_plan_backward_compat.
Semantic pin: empty ReprPlan produces IDENTICAL output to no ReprPlan for all resolvable types (primitives + Option, List, Range, Function, Tuple) (2026-03-24). Rust test: phase_a_semantic_pin_empty_plan_equals_no_plan.

01.9 Canonical Representation Tests

File(s): compiler/ori_repr/src/tests.rs (sibling to lib.rs — #[cfg(test)] mod tests; declaration in lib.rs, no inline test modules)

Canonical representations are the foundation — if they’re wrong, every optimization built on them is wrong.

TDD ordering: Write ALL tests in this section BEFORE writing any production code for §01. All tests must fail (crate does not exist). Implement the crate, verify tests pass unchanged. If any test requires modification to pass, the implementation is wrong — fix the implementation, not the test.

Debug AND release: After initial passing in debug, run cargo test -p ori_repr --release to confirm all tests pass in release mode as well.

01.R Third Party Review Findings

01.10 Completion Checklist

TDD ordering: Write ALL tests from §01.2, §01.3, §01.4, §01.5, §01.7, §01.8, and §01.9 BEFORE creating the ori_repr crate. All tests must fail (crate does not exist). Create the crate, implement the types, verify tests pass unchanged. Only then proceed to wiring into the pipeline (§01.3). If any test requires modification to pass, the implementation is wrong — fix the implementation, not the test.

Implementation sequence (must follow this order):

Close the #repr pipeline gap (§01.7 GAP-CLOSE steps) — these modify ori_ir, ori_parse, ori_types
cargo check --workspace green after GAP-CLOSE (before creating ori_repr)
Create ori_repr crate + implement types + tests
Add ori_repr to workspace + add ori_llvm/Cargo.toml dep
Wire ReprPlan through codegen pipeline
Final test run

Hygiene fixes to apply along the way (found during §01 codebase scan):

[TPR-01-053] Full conditional-attribute matrix — parser/IR/formatter completeness for spec §25:

[TPR-01-054] Item-level conditional attributes — thread #target/#cfg through AST nodes, formatter, and tests:

IR: Add target_attr: Option<TargetAttr> and cfg_attr: Option<CfgAttr> fields to Function in ori_ir/src/ast/items/function.rs (2026-03-25). Spec §25.4 docs added.
IR: Add target_attr: Option<TargetAttr> and cfg_attr: Option<CfgAttr> fields to TypeDecl in ori_ir/src/ast/items/types.rs (2026-03-25). Import TargetAttr/CfgAttr added.
Parser: Copy attrs.target and attrs.cfg into Function during construction in compiler/ori_parse/src/grammar/item/function/mod.rs (2026-03-25). Also updated incremental copier.
Parser: Copy attrs.target and attrs.cfg into TypeDecl during construction in compiler/ori_parse/src/grammar/item/type_decl.rs (2026-03-25). Also updated incremental copier.
Formatter: Emit item-level #target/#cfg in format_function() and format_type_decl() (2026-03-25). Added emit_item_target_attr()/emit_item_cfg_attr() helpers in mod.rs. Emitted before #derive/pub per canonical attr order.
Phase tests: 7 new tests in compiler/oric/tests/phases/parse/file_attr.rs (2026-03-25). Item-level #target and #cfg on functions and types, multi-field target, no-attrs baseline.
Spec tests: 3 .ori spec tests in tests/spec/declarations/conditional/ (2026-03-25): item_target_function, item_cfg_function, item_target_type.
./test-all.sh green (2026-03-25). 13,903 passed, 0 failed.
./clippy-all.sh green (2026-03-25).

[TPR-01-055] Feature name identifier validation — enforce spec §25.3.2 identifier constraint:

Parser: Add is_valid_feature_name() validator in compiler/ori_parse/src/grammar/attr/conditional.rs (2026-03-25). Checks first char is ASCII alphabetic/underscore, rest are ASCII alphanumeric/underscore. Empty strings rejected.
Parser: Add parse_feature_name_value() and parse_feature_name_list() in conditional.rs (2026-03-25). These wrap parse_attr_string_value/parse_attr_string_list with identifier validation. feature:, not_feature:, any_feature: now route through these. Emit E0932 on invalid names.
Phase tests: 11 new tests in compiler/oric/tests/phases/parse/file_attr.rs (2026-03-25). Valid names: ssl, _private_feat, Feature123. Invalid names: hyphen, digit-start, special chars, dot, empty string. Coverage for feature:, not_feature:, any_feature: contexts.
Spec tests: 2 valid-feature-name .ori spec tests in tests/spec/declarations/conditional/ (2026-03-25). Parse-level errors cannot use #compile_fail (file-level attribute errors precede test function discovery); negative cases covered by Rust phase tests.
./test-all.sh green (2026-03-25). 13,896 passed, 0 failed.
./clippy-all.sh green (2026-03-25).

[TPR-01-057] Attribute placement validation — reject unsupported attrs on imports, constants, impls, traits, extends, extern:

Parser: Add ParsedAttrs::has_non_conditional_attrs() and non_conditional_attr_names() helpers (2026-03-25).
Parser: Add E1006 validation in dispatch_declaration() for impls, constants, traits, def impls, extends, extern blocks (2026-03-25).
Parser: Add E1006 validation in parse_imports() for import statements (2026-03-25).
Phase tests: 19 tests in compiler/oric/tests/phases/parse/attr_validation.rs (2026-03-25). Covers reject + accept + semantic pin for all item kinds.
./test-all.sh green (2026-03-25). 13,933 passed, 0 failed.

[TPR-01-058] Formatter attr preservation — fix destructive formatting for impl attrs and #repr:

Formatter: Add #target/#cfg emission to format_impl_with_comments() matching format_impl() (2026-03-25).
Formatter: Add emit_repr_attr() helper to ModuleFormatter for all ReprAttrKind variants (2026-03-25).
Formatter: Add #repr emission to format_type_decl() between #cfg and #derive per canonical order (2026-03-25).
Golden tests: 4 files: types/repr_attr.ori, types/repr_with_target.ori, impls/conditional_attrs.ori, comments/edge/impl_conditional_attrs.ori (2026-03-25).
./test-all.sh green (2026-03-25). 13,933 passed, 0 failed.
/tpr-review passed (2026-03-28) — TPR-01-065 found and fixed (layout_resolver.rs file size). Re-run confirmed clean: no new findings. 14,341 tests pass.
/impl-hygiene-review passed — implementation hygiene review clean (phase boundaries, SSOT, algorithmic DRY, naming). MUST run AFTER /tpr-review is clean. (2026-03-31)
/improve-tooling retrospective — N/A: section was closed before the retrospective gate was added on 2026-04-07. Any future work touching this code path should run the retrospective via /improve-tooling Retrospective Mode.

Exit Criteria: ori_repr crate exists, ReprPlan is threaded through the entire LLVM codegen pipeline, all existing tests pass with identical behavior, cargo test -p ori_repr --release passes, and ORI_LOG=ori_repr=trace ori build tests/benchmarks/bench_small.ori shows ReprPlan query events for every type in the program.