Section 3: Traits and Implementations

Goal: Trait-based polymorphism

SPEC: spec/09-properties-of-types.md, spec/10-declarations.md

Status: In-progress — Core evaluator complete (3.0-3.7, 3.14, 3.16, 3.18-3.21). LLVM AOT: 88 trait tests, 43 derive tests, 17 formattable tests, 26 iterator tests — all passing. 4181 spec tests pass, 0 fail, 42 skip. Evaluator verified complete for all subsections through 3.21. LLVM gaps remain for: Debug (3.9), Traceable (3.13), iterator advanced features (3.8), Index (3.12), derived sum/generic/recursive (3.15). Not started: 3.23 (impl colon syntax), 3.24 (Value trait). 3.22 eliminated per capability-unification decision. Last verified 2026-03-29.

Implementation Location

SYNC POINT: Adding a new derived trait (e.g., Debug, Comparable, Reflect) requires updating ALL 5 crates simultaneously. See CLAUDE.md “Adding a New Derived Trait” and memory “Derived Trait Sync — DO NOT” for the full protocol: ori_ir (DerivedTrait enum), ori_types (registration), ori_eval (eval dispatch), ori_llvm (codegen), library/std/prelude.ori (trait definition).

All items in this section (3.0-3.21) are implemented in ori_types (the unified type checker crate).

Key Files:

ori_types/src/check/registration/ — Trait/impl registration
ori_types/src/check/bounds/ — Constraint satisfaction and bound checking
ori_types/src/infer/ — Type inference including built-in method signatures

PRIORITY NOTE

Per the “Lean Core, Rich Libraries” principle, most built-in functions have been moved from the compiler core to trait methods. The compiler now only provides:

Remaining built-ins:

print(msg: str) - I/O
panic(msg: str) - Control flow

Moved to traits (must implement in this section):

len(collection) -> Len trait with .len() method
is_empty(collection) -> IsEmpty trait with .is_empty() method
is_some(option), is_none(option) -> Option methods
is_ok(result), is_err(result) -> Result methods
compare(left, right) -> Comparable trait with .compare() method
min(a, b), max(a, b) -> Comparable trait or standalone functions via traits
assert(condition) -> Assert trait or testing module
assert_eq(actual, expected), assert_ne(actual, unexpected) -> Testing traits

Without traits, tests cannot use assertions - this blocks the testing workflow.

3.0 Core Library Traits

STATUS: COMPLETE (verified 2026-03-29 — evaluator complete, map/set LLVM equals/hash pending AOT collection infrastructure)

Core library traits are implemented via:

Runtime: Evaluator’s MethodRegistry provides hardcoded Rust dispatch for methods like .len(), .is_empty(), .is_some(), etc.
Type checking: infer_builtin_method() provides type inference for these methods
Trait bounds: primitive_implements_trait() in bound_checking.rs recognizes when types implement these traits

This approach follows the “Lean Core, Rich Libraries” principle — the runtime implementation stays in Rust for efficiency, while the type system recognizes the trait bounds for generic programming.

3.0.1 Len Trait

Proposal: proposals/approved/len-trait-proposal.md (approved 2026-02-18)

3.0.2 IsEmpty Trait

Proposal: proposals/approved/is-empty-trait-proposal.md (approved 2026-02-21)

3.0.3 Option Methods

Implemented: .is_some(), .is_none(), .unwrap(), .unwrap_or(default:) methods [done] (2026-02-10)
- Rust Tests: ori_eval/src/methods.rs — option_methods module
- Ori Tests: tests/spec/traits/core/option.ori — 16 tests (all pass)
- LLVM Support: LLVM codegen for Option — tag-based dispatch in lower_calls.rs
- AOT Tests: ori_llvm/tests/aot/traits.rs — .is_some() (2), .is_none() (2), .unwrap() (1), .unwrap_or() (2) all pass [done] (2026-02-13)
Type checking: infer_builtin_method() handles Option methods [done] (2026-02-10)

3.0.4 Result Methods

Implemented: .is_ok(), .is_err(), .unwrap() methods [done] (2026-02-10)
- Rust Tests: ori_eval/src/methods.rs — result_methods module
- Ori Tests: tests/spec/traits/core/result.ori — 14 tests (all pass)
- LLVM Support: LLVM codegen for Result — tag-based dispatch in lower_calls.rs
- AOT Tests: ori_llvm/tests/aot/traits.rs — .is_ok() (2), .is_err() (2), .unwrap() (1) all pass [done] (2026-02-13)
Type checking: infer_builtin_method() handles Result methods [done] (2026-02-10)

3.0.5 Comparable Trait

Implemented: Trait bound Comparable recognized for int, float, bool, str, char, byte, Duration, Size, [T], Option<T>, Result<T, E>, Ordering [done] (2026-02-10)
- Rust Tests: ori_types/src/check/tests.rs — test_comparable_bound_satisfied_by_*
- Ori Tests: tests/spec/traits/core/comparable.ori — 58 tests (all pass)
Type checking: All comparable types have .compare(other:) returning Ordering [done] (2026-02-10)
- Type Checking: ori_types/src/infer/ — numeric.rs, string.rs, list.rs, option.rs, result.rs, units.rs, ordering.rs
- LLVM Support: LLVM codegen for .compare() — inline arithmetic/comparison in lower_calls.rs
- AOT Tests: ori_llvm/tests/aot/traits.rs — 7 tests passing: .compare() + Ordering methods (is_less, is_equal, is_greater, reverse, is_less_or_equal, is_greater_or_equal) [done] (2026-02-13)

3.0.6 Eq Trait

Implemented: Trait bound Eq recognized for all primitive types [done] (2026-02-10)
- Rust Tests: ori_types/src/check/tests.rs — test_eq_bound_satisfied_by_*
- Ori Tests: tests/spec/traits/core/eq.ori — 23 tests (all pass)
- LLVM Support: LLVM codegen for ==/!= on all primitives [done]
- AOT Tests: ori_llvm/tests/aot/traits.rs — ==/!= for int, bool, str (3 tests) [done] (2026-02-13)

Additional Traits

The following traits are also recognized in trait bounds:

Clone: All primitives, collections
Hashable: int, bool, str, char, byte
Default: int, float, bool, str, Unit, Option<T>
Printable: All primitives

3.1 Trait Declarations

STATUS: COMPLETE (verified 2026-03-29)

3.2 Trait Implementations

STATUS: COMPLETE (verified 2026-03-29 — evaluator complete; LLVM generic impls intentionally deferred, no monomorphization pipeline)

3.3 Trait Bounds

Complete Implementation: [done] (verified 2026-02-14, re-verified 2026-03-29)

What Works Now:

Parsing generic functions: @compare<T: Comparable> (a: T, b: T) -> Ordering
Parsing multiple bounds: @process<T: Eq + Clone> (x: T) -> T
Parsing where clauses: @transform<T> (x: T) -> T where T: Clone = x
Constraint satisfaction checking at call sites
Error messages when types don’t satisfy required bounds

Implementation Details:

Param.ty stores type annotations as ParsedType; generic parameter names resolved via FunctionSig.type_params
FunctionSig.type_param_bounds stores bounds per generic parameter as Vec<Vec<Name>>
infer_function_signature_with_arena() creates fresh type vars and builds generic_param_mapping
When a param’s type matches a generic, the type var is used instead of inferring
Bound checking in calls.rs resolves type vars after unification and verifies trait impls
type_satisfies_trait() uses trait registry to verify implementations
Implement: Single bound <T: Trait> — spec/10-declarations.md § Generic Declarations [done] (2026-02-10)
- Write test: Rust unit tests in typeck/checker.rs::tests (10 tests pass)
- Run test: All pass
Implement: Multiple bounds <T: A + B> — spec/10-declarations.md § Generic Declarations [done] (2026-02-10)
- Write test: test_multiple_bounds_parsing in Rust unit tests
- Run test: All pass
Implement: Constraint satisfaction checking — spec/09-properties-of-types.md § Trait Bounds [done] (2026-02-10)
- Rust Tests: ori_types/src/check/tests.rs — 10+ constraint satisfaction tests
- Ori Tests: tests/spec/traits/associated_types.ori — needs_eq_item + compile_fail for violated bound

3.4 Associated Types

STATUS: COMPLETE (verified 2026-03-29)

Infrastructure implemented:

3.5 Derive Traits

STATUS: COMPLETE (verified 2026-03-29 — all 7 DerivedTrait variants synced across ori_ir, ori_types, ori_eval, ori_llvm)

All 5 derive traits implemented in ori_types/src/check/ (derives).

BLOAT: compiler/ori_eval/src/interpreter/derived_methods.rs is 504 lines — at the 500-line limit. Monitor for growth. Tests at tests/spec/traits/derive/all_derives.ori (7 tests pass).

3.6 Section Completion Checklist

Exit Criteria: Core trait-based code compiles and runs in evaluator [done]. LLVM codegen for built-in and user methods works [done]. User-defined operator traits complete [done] (2026-02-15). Formal trait proposals (3.8-3.17) evaluator complete, LLVM partial.

/tpr-review passed — independent review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — hygiene review clean. MUST run AFTER /tpr-review is clean.
Subsection close-out (3.6) — MANDATORY before starting the next subsection. Run /improve-tooling retrospectively on THIS subsection’s debugging journey (per .claude/skills/improve-tooling/SKILL.md “Per-Subsection Workflow”): which diagnostics/ scripts you ran, where you added dbg!/tracing calls, where output was hard to interpret, where test failures gave unhelpful messages, where you ran the same command sequence repeatedly. Forward-look: what tool/log/diagnostic would shorten the next regression in this code path by 10 minutes? Implement improvements NOW (zero deferral) and commit each via SEPARATE /commit-push using a valid conventional-commit type (build(diagnostics): ... — surfaced by section-3.6 retrospective — build/test/chore/ci/docs are valid; tools(...) is rejected by the lefthook commit-msg hook). Mandatory even when nothing felt painful. If genuinely no gaps, document briefly: “Retrospective 3.6: no tooling gaps”. Update this subsection’s status in section frontmatter to complete.
/sync-claude section-close doc sync — verify Claude artifacts across all section commits. Map changed crates to rules files, check CLAUDE.md, canon.md. Fix drift NOW.
Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files.

3.7 Clone Trait Formal Definition

STATUS: COMPLETE (verified 2026-03-29)

Proposal: proposals/approved/clone-trait-proposal.md

Formalizes the Clone trait that enables explicit value duplication. The trait is already recognized in trait bounds and derivable, but this proposal adds the formal definition and comprehensive prelude implementations.

Implementation

3.8 Iterator Traits

STATUS: Evaluator COMPLETE, LLVM PARTIAL (verified 2026-03-29 — evaluator verified complete; LLVM Phase 1 done with 26 AOT tests; Phase 2+ LLVM items unchecked; collect_set.ori has 6 skips with stub bodies — WEAK TESTS)

Proposal: proposals/approved/iterator-traits-proposal.md

Formalizes iteration with four core traits: Iterator, DoubleEndedIterator, Iterable, and Collect. Enables generic programming over any iterable, user types participating in for loops, and transformation methods.

Implementation

3.8.1 Iterator Performance and Semantics

STATUS: Evaluator COMPLETE, LLVM/optimizations NOT STARTED (verified 2026-03-29 — evaluator items verified; all LLVM items unchecked; optimization items correctly marked as not started)

Proposal: proposals/approved/iterator-performance-semantics-proposal.md

Formalizes the performance characteristics and precise semantics of Ori’s functional iterator model. Specifies copy elision guarantees, lazy evaluation, compiler optimizations, and introduces infinite range syntax (start..).

Implementation

3.9 Debug Trait

STATUS: Evaluator COMPLETE, LLVM NOT STARTED (verified 2026-03-29 — all evaluator items verified; all LLVM items unchecked)

Proposal: proposals/approved/debug-trait-proposal.md

Adds a Debug trait separate from Printable for developer-facing structural representation of values. Debug is automatically derivable and shows complete internal structure, while Printable remains for intentional user-facing output. Mirrors Rust’s Display vs Debug distinction.

Dependencies

as conversion syntax (as-conversion-proposal.md) — for self as str conversions
str.escape() method — stdlib method for escaping special characters
Iterator.join() method — stdlib method for joining iterator elements

Implementation

3.10 Trait Resolution and Conflict Handling

STATUS: PARTIAL (verified 2026-03-29 — implemented items verified; blocked items correctly annotated with dependencies)

Proposal: proposals/approved/trait-resolution-conflicts-proposal.md

Specifies rules for resolving trait implementation conflicts: diamond problem, coherence/orphan rules, method resolution order, super trait calls, and extension method conflicts.

Implementation

3.11 Object Safety Rules

STATUS: COMPLETE (verified 2026-03-29)

Proposal: proposals/approved/object-safety-rules-proposal.md

Formalizes the rules that determine whether a trait can be used as a trait object for dynamic dispatch. Defines three object safety rules and associated error codes.

Implementation

3.12 Custom Subscripting (Index Trait)

STATUS: Evaluator COMPLETE, LLVM NOT STARTED (verified 2026-03-29 — evaluator verified; no LLVM codegen tests)

Proposals:

proposals/approved/custom-subscripting-proposal.md — Design and motivation
proposals/approved/index-trait-proposal.md — Formal specification and error messages

Introduces the Index trait for read-only custom subscripting, allowing user-defined types to use [] syntax. Supports multiple index types per type (e.g., JsonValue with both str and int keys) and flexible return types (T, Option<T>, or Result<T, E>).

Implementation

3.13 Additional Core Traits

STATUS: Evaluator COMPLETE, LLVM PARTIAL (verified 2026-03-29 — Printable and Default have LLVM support; Traceable LLVM pending)

Proposal: proposals/approved/additional-traits-proposal.md

Formalizes three core traits: Printable, Default, and Traceable. The Iterable, Iterator, DoubleEndedIterator, and Collect traits are already defined in the spec and implemented in Section 3.8.

Implementation

3.14 Comparable and Hashable Traits

STATUS: COMPLETE (verified 2026-03-29 — excellent coverage: 120+ test assertions, all relevant types covered, AOT coverage for list/tuple/option/result; map/set LLVM pending AOT collection infrastructure)

Proposal: proposals/approved/comparable-hashable-traits-proposal.md

Formalizes the Comparable and Hashable traits with complete definitions, mathematical invariants, standard implementations, and derivation rules. Adds Result<T, E> to both trait implementations and introduces hash_combine as a prelude function.

Phase boundary discipline: Each method must be implemented across ALL THREE phases (type checker → evaluator → LLVM codegen) before the type checker may accept it. Commit 01051607 added hash/equals to the type checker for compound types without evaluator/LLVM handlers — this was reverted in the hygiene review (see 3.7). When implementing items below, add to type checker LAST, after evaluator and LLVM codegen are working.

equals() on compound types is also tracked here. The Eq trait (3.0.6) covers primitives only. Collection/wrapper equals() methods (list, map, set, Option, Result, tuple) require the same all-phase implementation as hash().

Implementation

3.15 Derived Traits Formal Semantics

STATUS: Evaluator COMPLETE, LLVM PARTIAL (verified 2026-03-29 — 90+ evaluator tests across 12 files; LLVM gaps: sum type Eq, Debug, generic conditional, recursive derive)

Proposal: proposals/approved/derived-traits-proposal.md

Formalizes the #derive attribute semantics: derivable traits list, derivation rules, field constraints, generic type handling, and error messages.

Implementation

3.16 Formattable Trait

STATUS: COMPLETE (verified 2026-03-29 — 8 evaluator test files + 17 AOT tests; one documented GAP: user-defined Formattable::format() LLVM codegen blocked by general trait method call codegen)

Proposal: proposals/approved/formattable-trait-proposal.md

Formalizes the Formattable trait and format specification syntax for customized string formatting. Defines FormatSpec type structure, format spec syntax, and the relationship between Formattable and Printable via blanket implementation.

Implementation

3.17 Into Trait

STATUS: Evaluator COMPLETE, LLVM PARTIAL (verified 2026-03-29 — int->float LLVM done; str->Error blocked by Error type LLVM repr; orphan rules blocked by module system)

Proposal: proposals/approved/into-trait-proposal.md

Formalizes the Into trait for semantic, lossless type conversions. Defines trait signature, standard implementations, relationship to as/as?, and rules for custom implementations.

Implementation

Note: str.into() returns Idx::ERROR directly (pre-interned primitive) rather than pool.named("Error"). The WellKnownNames.error_type field was removed as unused. If a future feature needs to resolve “Error” by name at type-check time, re-add it to well_known.rs. Error.message field access is implemented in both type checker (infer_field in structs.rs) and evaluator (eval_field_access in expr.rs) — if more Error fields are added (e.g. .source), update both.

/tpr-review passed — independent review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — hygiene review clean. MUST run AFTER /tpr-review is clean.
Subsection close-out (3.17) — MANDATORY before starting the next subsection. Run /improve-tooling retrospectively on THIS subsection’s debugging journey (per .claude/skills/improve-tooling/SKILL.md “Per-Subsection Workflow”): which diagnostics/ scripts you ran, where you added dbg!/tracing calls, where output was hard to interpret, where test failures gave unhelpful messages, where you ran the same command sequence repeatedly. Forward-look: what tool/log/diagnostic would shorten the next regression in this code path by 10 minutes? Implement improvements NOW (zero deferral) and commit each via SEPARATE /commit-push using a valid conventional-commit type (build(diagnostics): ... — surfaced by section-3.17 retrospective — build/test/chore/ci/docs are valid; tools(...) is rejected by the lefthook commit-msg hook). Mandatory even when nothing felt painful. If genuinely no gaps, document briefly: “Retrospective 3.17: no tooling gaps”. Update this subsection’s status in section frontmatter to complete.
/sync-claude section-close doc sync — verify Claude artifacts across all section commits. Map changed crates to rules files, check CLAUDE.md, canon.md. Fix drift NOW.
Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files.

3.18 Ordering Type

STATUS: COMPLETE (verified 2026-03-29 — 41 spec tests, all methods complete; only Ordering.default() deferred, blocked by static method support)

Proposal: proposals/approved/ordering-type-proposal.md

Formalizes the Ordering type that represents comparison results. Defines the three variants (Less, Equal, Greater), methods (is_less, is_equal, is_greater, is_less_or_equal, is_greater_or_equal, reverse, then, then_with), and trait implementations.

Implementation

3.19 Default Type Parameters on Traits

STATUS: COMPLETE (verified 2026-03-29 — WEAK TESTS: only 2 spec tests for this feature)

Proposal: proposals/approved/default-type-parameters-proposal.md

Allow type parameters on traits to have default values, enabling trait Add<Rhs = Self> where Rhs defaults to Self if not specified. Essential prerequisite for operator traits.

Implementation

3.20 Default Associated Types

STATUS: COMPLETE (verified 2026-03-29 — bounds checking on defaults deferred)

Proposal: proposals/approved/default-associated-types-proposal.md

Allow associated types in traits to have default values, enabling type Output = Self where implementors can omit the associated type if the default is acceptable. Works alongside default type parameters to enable operator traits.

Implementation

3.21 Operator Traits

STATUS: COMPLETE (verified 2026-03-29 — type checker desugaring, evaluator dispatch, LLVM codegen, error messages all working; derive for newtypes optional/deferred; MatMul 3.21.1 not started)

Proposal: proposals/approved/operator-traits-proposal.md

Defines traits for arithmetic, bitwise, and unary operators that user-defined types can implement to support operator syntax. The compiler desugars operators to trait method calls. Enables Duration and Size types to move to stdlib.

Dependencies

Default Type Parameters on Traits (3.19) — for trait Add<Rhs = Self> [done] (2026-02-10)
Default Associated Types (3.20) — for type Output = Self [done] (2026-02-10)

Implementation

3.21.1 MatMul Operator (`@`)

Proposal: proposals/approved/matmul-operator-proposal.md

Add @ as a binary operator for matrix multiplication at multiplicative precedence (level 3), desugaring to the MatMul trait method matrix_multiply(). Follows Python PEP 465 convention for ML/scientific computing adoption. The @ token is disambiguated by parser context (item position = function sigil, expression position = matmul operator, pattern position = binding).

Dependencies

Operator Traits (3.21) — trait dispatch infrastructure [done]

Implementation

3.22 Bound Syntax — ELIMINATED (Capability Unification)

STATUS: ELIMINATED (verified 2026-03-29 — correctly eliminated per 2026-03-04 capability-unification decision)

Proposal: proposals/approved/capability-unification-generics-proposal.md — Phase 2 (eliminated)

Status: This section is no longer needed. The 2026-03-04 addendum to the capability-unification-generics-proposal decided to retain : for all bound positions (generic parameters, where clauses, supertrait declarations, impl block bounds). No parser changes, no test migration, no spec updates for bound syntax. Only the #derive → : trait clause on type declarations is a new syntax change (tracked in Section 5).

/tpr-review passed — independent review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — hygiene review clean. MUST run AFTER /tpr-review is clean.
Subsection close-out (3.22) — MANDATORY before starting the next subsection. Run /improve-tooling retrospectively on THIS subsection’s debugging journey (per .claude/skills/improve-tooling/SKILL.md “Per-Subsection Workflow”): which diagnostics/ scripts you ran, where you added dbg!/tracing calls, where output was hard to interpret, where test failures gave unhelpful messages, where you ran the same command sequence repeatedly. Forward-look: what tool/log/diagnostic would shorten the next regression in this code path by 10 minutes? Implement improvements NOW (zero deferral) and commit each via SEPARATE /commit-push using a valid conventional-commit type (build(diagnostics): ... — surfaced by section-3.22 retrospective — build/test/chore/ci/docs are valid; tools(...) is rejected by the lefthook commit-msg hook). Mandatory even when nothing felt painful. If genuinely no gaps, document briefly: “Retrospective 3.22: no tooling gaps”. Update this subsection’s status in section frontmatter to complete.
/sync-claude section-close doc sync — verify Claude artifacts across all section commits. Map changed crates to rules files, check CLAUDE.md, canon.md. Fix drift NOW.
Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files.

3.23 Impl Colon Syntax

STATUS: NOT STARTED (verified 2026-03-29 — all items unchecked)

Proposal: proposals/approved/impl-colon-syntax-proposal.md

Replace impl Trait for Type with impl Type: Trait — subject-first ordering, completes : = “conforms to” unification across all five conformance positions.

Implementation

3.24 Value Trait (ARC-Free Value Types)

STATUS: NOT STARTED (verified 2026-03-29 — all items unchecked across 5 phases)

Proposal: proposals/approved/value-trait-proposal.md

Marker trait guaranteeing inline storage, bitwise copy, no ARC, and no Drop. Supersedes the Copy trait slot and inline type keyword reservation.

Phase 1: Type Checker Validation

Phase 2: ARC Pipeline Fast Path

Implement: Fast path in ori_arc/src/classify/mod.rs — types with Value trait -> ArcClass::Scalar
- Skip field traversal for Value types
- Rust Tests: ori_arc/src/classify/tests.rs
Implement: Skip borrow inference for Value parameters — ori_arc/src/borrow/
- Always cheap to copy, no borrow optimization needed
- Rust Tests: Borrow inference tests
Implement: Skip RC insertion for Value-typed variables — ori_arc/src/rc_insert/
- Rust Tests: RC insertion skip tests

Phase 3: Evaluator Support

Implement: Value trait recognition in evaluator — ori_eval/
- Auto-satisfy Clone for Value types (bitwise copy)
- Rust Tests: Evaluator Value type tests
- Ori Tests: tests/spec/traits/value/ — runtime behavior

Phase 4: LLVM Codegen Optimization

Implement: memcpy for Value types — ori_llvm/
- Value types passed by value (no indirection through pointers) when <=2 registers
- No RC inc/dec emitted for Value types
- LLVM SROA and constant folding work on Value types
- LLVM Rust Tests: ori_llvm/tests/aot/value_types.rs
- Ori Tests: AOT tests for Value type operations

Phase 5: Const Generic Integration (Future)

Implement: Value + Hashable types eligible as const generic parameters
- Ori Tests: Const generic with Value types
/tpr-review passed — independent review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — hygiene review clean. MUST run AFTER /tpr-review is clean.
Subsection close-out (3.24) — MANDATORY before starting the next subsection. Run /improve-tooling retrospectively on THIS subsection’s debugging journey (per .claude/skills/improve-tooling/SKILL.md “Per-Subsection Workflow”): which diagnostics/ scripts you ran, where you added dbg!/tracing calls, where output was hard to interpret, where test failures gave unhelpful messages, where you ran the same command sequence repeatedly. Forward-look: what tool/log/diagnostic would shorten the next regression in this code path by 10 minutes? Implement improvements NOW (zero deferral) and commit each via SEPARATE /commit-push using a valid conventional-commit type (build(diagnostics): ... — surfaced by section-3.24 retrospective — build/test/chore/ci/docs are valid; tools(...) is rejected by the lefthook commit-msg hook). Mandatory even when nothing felt painful. If genuinely no gaps, document briefly: “Retrospective 3.24: no tooling gaps”. Update this subsection’s status in section frontmatter to complete.
/sync-claude section-close doc sync — verify Claude artifacts across all section commits. Map changed crates to rules files, check CLAUDE.md, canon.md. Fix drift NOW.
Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files.

3.25 Structural Trait Defaults

Status: Not Started Goal: Formalize and complete structural trait defaults — Eq/Clone/Debug/Printable work without declaration on all types; eq → equals method rename; LLVM codegen parity with evaluator for enum structural equality and structural Clone/Debug/Printable fallbacks.

Context: Ori is a pure value-type language. The evaluator has always performed structural equality for all types without requiring #derive(Eq). The type checker does not gate ==/!= on the Eq trait. The LLVM codegen has structural eq fallback for structs but not enums. This subsection formalizes this behavior per the approved structural-trait-defaults-proposal (2026-04-02) and closes the LLVM codegen gaps.

Proposal: docs/ori_lang/proposals/approved/structural-trait-defaults-proposal.md

Reference implementations:

Gleam compiler-core/src/type_/expression.rs: all types structurally comparable — no Eq trait requirement
Elm compiler/src/Type/Error.hs: structural equality built-in for all values
Roc crates/compiler/mono/src/ir.rs: structural equality as default for all types

Depends on: None (evaluator and type checker already implement this behavior).

Key design decisions:

Two-tier model: Structural ==/!= works on all types without declaration. Declaring type T: Eq = {...} generates a named equals method for trait dispatch in generic T: Eq contexts.
Comparable/Hashable/Default require explicit declaration — no structural default (field ordering is semantic, not structural).
eq → equals method rename — unifies a partial rename already in progress (evaluator and mangling use "equals", IR and codegen use "eq").

/tpr-review passed — independent review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — hygiene review clean. MUST run AFTER /tpr-review is clean.
Subsection close-out (3.25) — MANDATORY before starting the next subsection. Run /improve-tooling retrospectively on THIS subsection’s debugging journey (per .claude/skills/improve-tooling/SKILL.md “Per-Subsection Workflow”): which diagnostics/ scripts you ran, where you added dbg!/tracing calls, where output was hard to interpret, where test failures gave unhelpful messages, where you ran the same command sequence repeatedly. Forward-look: what tool/log/diagnostic would shorten the next regression in this code path by 10 minutes? Implement improvements NOW (zero deferral) and commit each via SEPARATE /commit-push using a valid conventional-commit type (build(diagnostics): ... — surfaced by section-3.25 retrospective — build/test/chore/ci/docs are valid; tools(...) is rejected by the lefthook commit-msg hook). Mandatory even when nothing felt painful. If genuinely no gaps, document briefly: “Retrospective 3.25: no tooling gaps”. Update this subsection’s status in section frontmatter to complete.
/sync-claude section-close doc sync — verify Claude artifacts across all section commits. Map changed crates to rules files, check CLAUDE.md, canon.md. Fix drift NOW.
Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files.

3.25.1 `eq` → `equals` Method Rename

File(s): ori_ir/src/derives/mod.rs, library/std/prelude.ori, ori_llvm/src/codegen/arc_emitter/builtins/compound_traits.rs, ori_llvm/src/codegen/arc_emitter/operators/mod.rs, ori_llvm/src/codegen/derive_codegen/field_ops/thunks.rs, ori_eval/src/derives/tests.rs, ori_ir/src/derives/tests.rs

The codebase has a partial inconsistency: the evaluator runtime (MethodNames.equals), mangling ($equals), type checker registration, and some test files already use "equals". The IR source of truth (DerivedTrait::Eq.method_name()) and LLVM codegen hardcode "eq". This subsection unifies to "equals" everywhere.

Rename targets (must change):

File	Current	Change To
`compiler/ori_ir/src/derives/mod.rs` line 145	`"eq"` in `define_derived_traits!` macro	`"equals"`
`library/std/prelude.ori` line 20	`@eq (self, other: Self) -> bool`	`@equals (self, other: Self) -> bool`
`compiler/ori_ir/src/derives/tests.rs` line 29	`assert_eq!(DerivedTrait::Eq.method_name(), "eq")`	`"equals"`
`compiler/ori_llvm/src/codegen/arc_emitter/operators/mod.rs` lines 203-204	`"eq"` in operator dispatch	`"equals"`
`compiler/ori_llvm/src/codegen/arc_emitter/builtins/compound_traits.rs` line 216	`self.interner.intern("eq")`	`self.interner.intern("equals")`
`compiler/ori_llvm/src/codegen/derive_codegen/field_ops/thunks.rs`	`fc.intern("eq")`	`fc.intern("equals")`
`compiler/ori_eval/src/derives/tests.rs` (3 occurrences)	`interner.intern("eq")`	`interner.intern("equals")`

Already correct (no change needed):

Test matrix:

Types: struct (single-field, multi-field), newtype, enum (unit variants, payload variants)
Patterns: direct ==, direct !=, method call .equals(other:), use in generic T: Eq context
Backends: eval + LLVM (debug + release)

3.25.2 LLVM Enum Structural Equality

File(s): compiler/ori_llvm/src/codegen/arc_emitter/builtins/compound_traits.rs

Currently, when emit_element_equals encounters an enum type at line 205, it only tries emit_derived_eq_call — there is no structural fallback. Structs have this fallback (line 200-203: try derived, .or_else(|| self.emit_structural_eq(...))). This means enums without #derive(Eq) cannot be compared in LLVM codegen, even though the evaluator compares them structurally.

Pattern to follow: compiler/ori_llvm/src/codegen/derive_codegen/enum_bodies/enum_comparable.rs (lines 21-73) — emit_enum_lexicographic() shows the exact tag-extraction + payload-switch pattern for enum comparison in LLVM IR.

Algorithm for emit_structural_enum_eq:

Extract discriminant (tag) from both lhs and rhs via extract_value(val, 0, ...)
Compare tags with icmp_eq
If tags differ → return false
If tags match → switch on tag value, for each variant:
- If unit variant (no payload) → contribute true
- If payload variant → extract payload fields, recursively call emit_element_equals on each, accumulate with AND
Return accumulated result via phi node

Write failing test first: Add AOT test compiler/ori_llvm/tests/aot/structural_eq.rs with enum type having no #derive(Eq), assert ==/!= work correctly
- Unit-variant enum: type Color = Red | Green | Blue
- Payload enum: type Shape = Circle(r: float) | Rect(w: float, h: float)
- Verify test fails (LLVM can’t emit structural enum eq)
Implement emit_structural_enum_eq in compound_traits.rs:
- Add function signature: fn emit_structural_enum_eq(&mut self, lhs: ValueId, rhs: ValueId, variants: &[...], ty: Idx) -> Option<ValueId>
- Implement tag extraction and comparison
- Implement variant-switch payload comparison (reuse emit_element_equals for recursion)
- Handle edge cases: all-unit enum (no payload switch needed), single-variant enum

Wire into dispatch: Change line 205 from:

TypeInfo::Enum { .. } => self.emit_derived_eq_call(lhs, rhs, elem_ty),

to:

TypeInfo::Enum { variants, .. } => {
    let variants = variants.clone();
    self.emit_derived_eq_call(lhs, rhs, elem_ty)
        .or_else(|| self.emit_structural_enum_eq(lhs, rhs, &variants, elem_ty))
}

Verify tests pass: All new AOT tests pass in debug and release
Dual-execution parity: Run diagnostics/dual-exec-verify.sh on test programs — evaluator and LLVM must produce identical results
Semantic pin: Test that verifies enum structural eq works WITHOUT #derive(Eq) — would fail if fallback is removed
Negative pin: Test that verifies a type with custom impl T: Eq uses the custom method, not structural default

Test matrix:

Types: unit enum, payload enum (single field, multi-field), nested enum (enum containing enum), enum with struct payload, Option-like enum, Result-like enum
Patterns: == same variant, == different variant, !=, nested comparison
Backends: LLVM debug + release (FastISel divergence check)

3.25.3 LLVM Structural Clone/Debug/Printable Fallbacks

File(s): compiler/ori_llvm/src/codegen/arc_emitter/builtins/compound_traits.rs, compiler/ori_llvm/src/codegen/arc_emitter/builtins/debug_helpers.rs

Currently:

Clone: No structural fallback. Types without #derive(Clone) cannot be cloned in LLVM codegen (evaluator clones all types structurally).
Debug: Falls back to "<?>" literal when no derived debug method exists (line 189-190 of debug_helpers.rs). Should produce TypeName { field: value, ... } structurally.
Printable: Same as Debug — falls back to "<?>". Should produce the same structural format as Debug default.

Implementation order: Clone first (simplest — no string building), then Debug (requires string concatenation), then Printable (identical to Debug structural default).

Phase A: Structural Clone

Write failing test: AOT test with struct/enum without #derive(Clone), call .clone() structurally
Implement emit_structural_clone in compound_traits.rs:
- For structs: extract each field, recursively clone, rebuild struct via insert_value
- For enums: extract tag + payload, switch on tag, clone payload fields per variant, rebuild
- Wire into clone dispatch with .or_else(|| self.emit_structural_clone(...))
Verify: Tests pass, dual-exec parity

Phase B: Structural Debug

Write failing test: AOT test with struct/enum without #derive(Debug), call .debug(), verify output format
Implement emit_structural_debug in debug_helpers.rs:
- Build string: TypeName { field1: <debug(f1)>, field2: <debug(f2)>, ... }
- Use emit_literal_ori_str for type/field names, emit_element_debug for field values
- Concatenate via emit_str_concat (runtime call ori_str_concat)
- Handle enums: VariantName (unit) or VariantName(field1: <debug>, ...)
- Handle Sret return convention (debug returns str = 24 bytes)
Wire into dispatch: Replace "<?>" fallback at line 189-190 with structural debug
Verify: Tests pass, dual-exec parity, output matches evaluator format

Phase C: Structural Printable (to_str)

Write failing test: AOT test with struct/enum without #derive(Printable), call .to_str() or use in string interpolation
Implement emit_structural_to_str: Identical to structural debug (same format per proposal)
Wire into dispatch in the to_str emission path
Verify: Tests pass, dual-exec parity

Test matrix (all three phases):

Types: empty struct, single-field struct, multi-field struct, newtype, unit enum, payload enum, nested types (struct containing enum), generic types
Patterns: direct method call (.clone(), .debug(), .to_str()), use in string interpolation (Printable), use in dbg() (Debug)
Backends: eval + LLVM (debug + release)
Format verification: structural output matches TypeName { field: value } format exactly

3.25.4 Spec and Documentation Updates

File(s): docs/ori_lang/v2026/spec/operator-rules.md, docs/ori_lang/v2026/spec/09-properties-of-types.md, .claude/rules/ori-syntax.md

3.25.R Third Party Review Findings

None.

3.25.N Completion Checklist

Exit Criteria: All types (structs, enums, newtypes) support ==/!=, .clone(), .debug(), and .to_str() structurally in both evaluator and LLVM codegen without requiring #derive(...). The equals method name is consistent across all compiler crates. Spec reflects structural defaults. Zero regressions in ./test-all.sh (debug and release). Dual-execution parity confirmed for all new test programs.

Section 3: Traits and Implementations

Implementation Location

PRIORITY NOTE

3.0 Core Library Traits

3.0.1 Len Trait

3.0.2 IsEmpty Trait

3.0.3 Option Methods

3.0.4 Result Methods

3.0.5 Comparable Trait

3.0.6 Eq Trait

Additional Traits

3.1 Trait Declarations

3.2 Trait Implementations

3.3 Trait Bounds

3.4 Associated Types

3.5 Derive Traits

3.6 Section Completion Checklist

3.7 Clone Trait Formal Definition

Implementation

3.8 Iterator Traits

Implementation

3.8.1 Iterator Performance and Semantics

Implementation

3.9 Debug Trait

Dependencies

Implementation

3.10 Trait Resolution and Conflict Handling

Implementation

3.11 Object Safety Rules

Implementation

3.12 Custom Subscripting (Index Trait)

Implementation

3.13 Additional Core Traits

Implementation

3.14 Comparable and Hashable Traits

Implementation

3.15 Derived Traits Formal Semantics

Implementation

3.16 Formattable Trait

Implementation

3.17 Into Trait

Implementation

3.18 Ordering Type

Implementation

3.19 Default Type Parameters on Traits

Implementation

3.20 Default Associated Types

Implementation

3.21 Operator Traits

Dependencies

Implementation

3.21.1 MatMul Operator (@)

Dependencies

Implementation

3.22 Bound Syntax — ELIMINATED (Capability Unification)

3.23 Impl Colon Syntax

Implementation

3.24 Value Trait (ARC-Free Value Types)

Phase 1: Type Checker Validation

Phase 2: ARC Pipeline Fast Path

Phase 3: Evaluator Support

Phase 4: LLVM Codegen Optimization

Phase 5: Const Generic Integration (Future)

3.25 Structural Trait Defaults

3.25.1 eq → equals Method Rename

3.25.2 LLVM Enum Structural Equality

3.25.3 LLVM Structural Clone/Debug/Printable Fallbacks

Phase A: Structural Clone

Phase B: Structural Debug

Phase C: Structural Printable (to_str)

3.25.4 Spec and Documentation Updates

3.25.R Third Party Review Findings

3.25.N Completion Checklist

3.21.1 MatMul Operator (`@`)

3.25.1 `eq` → `equals` Method Rename