Still polishing a few details here

@Turupawn I just did another push, hopefully this is pretty close to what gets merged

@sbillig @Turupawn ah wait, just kidding, a few more things to do. I'll let you know when it's ready to look at.

Okay, better now! c.c. @Turupawn @sbillig

@codex review

@Turupawn here's some info on where things landed and some ideas for integrating #1211:

Seq-Based Iteration: Architecture Report & Future Integration Guide

Summary

The seq-iteration branch implements a unified iteration system where all for-loops flow through the Seq<T> trait. Ranges are "just another Seq implementor," and the ForLoopSeq metadata serves as the stable contract between type checking and MIR lowering.

This report covers the current architecture, considerations for integrating codegen-focused features, and some longer-term design explorations.

Part 1: Current Architecture

1.1 Unified Iteration via Seq + ForLoopSeq

The central design decision: all for .. in .. loops follow the same path.

for x in iterable { body }
         |
         v
  HIR type-checking resolves Seq<T> implementation
         |
         v
  ForLoopSeq captures resolved len/get callables
         |
         v
  MIR desugars via lower_for_seq() -> while-loop

There's no range-specific for-loop lowering — Range implements Seq like any other sequence type. This simplifies the compiler and means new Seq implementors automatically work with for-loops.

Pattern binding is handled uniformly: the loop element always flows through bind_pat_value, so destructuring patterns like for Point { x, y } in points work correctly.

Reference: crates/mir/src/lower/expr.rs:1535, crates/hir/src/analysis/ty/ty_check/stmt.rs

1.2 Range Type System

The Range type uses type-level encoding for memory optimization:

pub trait Bound {
    type Repr  // () for Known (ZST), usize for Unknown
}

pub struct Known<const N: usize> {}
pub struct Unknown {}

pub struct Range<S: Bound, E: Bound> {
    pub start: <S as Bound>::Repr,
    pub end: <E as Bound>::Repr,
}

Note: "word" here means layout.word_size_bytes from TargetDataLayout. Fe's memory layout is packed bytes (not Solidity-style 32-byte slots), though usize is word-sized on EVM.

Layout invariants around ZST fields are enforced in MIR lowering and transforms, preventing out-of-bounds writes.

Reference: crates/mir/src/layout.rs, crates/mir/src/lower/expr.rs, crates/mir/src/transform.rs

1.3 Range::len() Semantics

Range::len() clamps to 0 when end < start, making behavior well-defined without requiring saturating_sub. Conceptually:

fn len(self) -> usize {
    if end > start { end - start } else { 0 }
}

This logic is implemented across the four Seq impls (const/const, const/runtime, runtime/const, runtime/runtime), each accessing bounds appropriately for its type signature.

Reference: library/core/src/range.fe

1.4 Core Type Resolution

Range type discovery is centralized via resolve_core_range_types(), which returns the Range, Known, and Unknown types in one call. This avoids scattering path strings throughout the codebase.

Reference: crates/hir/src/analysis/ty/corelib.rs:76

1.5 TargetDataLayout

Codegen now receives a TargetDataLayout, providing a path toward multi-backend support. Size-dependent decisions (like inline vs data section thresholds) can query the layout rather than assuming EVM-specific values:

// Query the layout
let word_size = layout.word_size_bytes;

// Rather than hardcoding
// if size > 32 { ... }

Reference: crates/codegen/src/yul/emitter/module.rs

Part 2: Integrating Codegen Features

2.1 Loop Unrolling

The natural integration point is lower_for() in crates/mir/src/lower/expr.rs:1535, where ForLoopSeq is available.

A subtlety worth noting: Known<const N> doesn't necessarily mean the trip count is a compile-time literal. The const parameter could itself be a generic that requires monomorphization to resolve. Today, Known<N> is inferred only from integer literals (no const arithmetic yet), so a conservative first implementation can key off the same literal detection used for bound inference.

Semantic considerations: Unrolled loops need to preserve break/continue/return semantics and respect the effect args captured in ForLoopSeq. The resolved callables represent the actual methods that should be invoked.

An alternative structure: Implementing unrolling as a MIR transform pass (post-lowering) rather than during lowering has some appeal — it separates semantic lowering from optimization, and makes it easier to gate by optimization level.

2.2 Data Regions

The concept of storing large constant arrays/strings in data sections (rather than inlining them) is valuable for EVM targets.

Backend neutrality: The MIR representation benefits from being backend-agnostic. A DataRegionId + bytes representation lets each backend choose its own labeling and emission scheme. Avoid baking Yul label strings directly into MIR — this is the main portability footgun.

Existing infrastructure: Fe already has code region plumbing (CodeRegionOffset/CodeRegionLen intrinsics) that drives dataoffset()/datasize() patterns. Data region work can follow a similar style rather than building parallel machinery.

Reference: crates/codegen/src/yul/emitter/module.rs

Design Note: Core/Std Relevance

Data regions are the simplest instance of a broader "data lives somewhere" story (code section, calldata, memory, storage, etc.). Even if the immediate work is EVM/Yul-focused, it's worth shaping the implementation so it doesn't pre-commit Fe's future core/std interfaces.

Concretely: keep the compiler's representation backend-neutral, keep size/threshold policy layout-driven, and avoid encoding backend naming/labeling decisions into MIR. This keeps the door open for future library-level "region/handle" traits without forcing the design today.

Future-proofing checklist (for any data-region PR):

• MIR carries DataRegionId + bytes (or equivalent), not Yul label strings / dataoffset("...") names
• Inline-vs-section (or similar) decisions consult TargetDataLayout / target policy (no hardcoded 32)
• Reuse the existing "code region" collection/emission pattern where possible (avoid parallel bespoke machinery)
• Keep any core/std hooks centralized (avoid scattered path/name checks), so refactors don't become invasive later

Part 3: Design Exploration — DataLoc/StaticSeq

Note: This section explores a potential future direction. It's speculative and implies compiler intrinsics and language-surface decisions that would need their own design process.

3.1 The Pattern

Following the Known/Unknown pattern, data storage location could be encoded at the type level:

pub trait DataLoc {
    type Handle  // () for compile-time resolved locations
}

pub struct Inline {}    // Small data in bytecode
pub struct CodeData {}  // Large data in data section

impl DataLoc for Inline { type Handle = () }
impl DataLoc for CodeData { type Handle = () }

3.2 StaticSeq Sketch

pub struct StaticSeq<T, const N: usize, L: DataLoc> {
    _handle: <L as DataLoc>::Handle  // ZST for both Inline and CodeData
}

impl<T, const N: usize> Seq<T> for StaticSeq<T, N, CodeData> {
    fn len(self) -> usize { N }
    fn get(self, i: usize) -> T { /* intrinsic: codecopy + load */ }
}

The compiler could automatically select Inline vs CodeData based on size thresholds (queried from TargetDataLayout), similar to how range bounds are detected from literals.

3.3 Considerations

This design implies compiler intrinsics for loading elements from code/data sections, and ties into backend capabilities that vary across targets. It also intersects with ongoing discussions about core/std "memory region" interfaces and contract desugaring plumbing; treat DataLoc/StaticSeq as a sketch for possible future surfaces, not a requirement for implementing data regions.

Part 4: Integration Summary

The seq-iteration branch establishes Seq/ForLoopSeq as the semantic contract for iteration. Performance features like unrolling and data regions can layer on top of this contract.

A few patterns emerge from the current design:

• Uniformity: Range flows through the same Seq machinery as arrays, keeping the compiler simple
• Type-level encoding: Compile-time knowledge (bounds, locations) lives in types with ZST representations
• Backend abstraction: TargetDataLayout and backend-neutral MIR structures support future multi-target work
• Centralized helpers: resolve_core_range_types() and similar functions reduce path-string duplication
• Non-interference: Data regions should land as backend-neutral IR + layout-driven policy, leaving any new core/std "region" traits as an explicit follow-on design step

Part 5: Key Files Reference