Section 4: Module System

Goal: Multi-file compilation

SPEC: spec/18-modules.md DESIGN: design/09-modules/index.md PROPOSAL: proposals/approved/no-circular-imports-proposal.md — Circular import rejection PROPOSAL: proposals/approved/module-system-details-proposal.md — Entry points, re-export chains, visibility

Status: In-progress — Core evaluator complete (4.1-4.6), LLVM multi-file infrastructure present (dependency graph, topological sort, symbol mangling), tooling pending (4.7), module details pending (4.8), constants parser done / evaluator pending (4.11), extension parser + basic evaluator done / type checker pending (4.12). Verified 2026-03-29.

4.1 Module Definition

4.2 Import Parsing

Relative imports:

Module imports:

Implement: use std.module { item } — spec/18-modules.md § Module Imports [done] (verified 2026-03-29)
- Rust Tests: oric/src/imports/tests.rs::resolve_module_path_not_found — stdlib path resolution
- Ori Tests: All 4181 test files use use std.testing { assert_eq }
Implement: Nested use std.net.http { get } — spec/18-modules.md § Module Imports
- Rust Tests: Parser supports multi-segment paths (verified via test_import_without_def_basic); no runtime test
- Ori Tests: N/A — no nested stdlib modules exist yet to test

Private imports:

Implement: use './path' { ::private_item } — spec/18-modules.md § Private Imports [done] (verified 2026-03-29)
- Rust Tests: oric/tests/phases/parse/imports.rs::test_import_private_basic, test_import_private_with_alias
- Ori Tests: tests/spec/modules/_test/use_private.test.ori (2 tests: private fn access, private + public combo)
Implement: :: prefix — spec/18-modules.md § Private Imports [done] (verified 2026-03-29)
- Rust Tests: Parser tests verify items[0].is_private flag set for :: prefix
- Ori Tests: tests/spec/modules/_test/use_private.test.ori

Aliases:

4.3 Visibility

4.4 Module Resolution

4.5 Test Modules

Implement: _test/ convention — spec/18-modules.md § Test Modules [done] (verified 2026-03-29)
- Rust Tests: oric/src/imports/tests.rs — 4 is_test_module tests: valid, not_in_test_dir, wrong_extension, nested
- Ori Tests: tests/spec/modules/_test/test_module_access.test.ori (2 tests)
Implement: Test files access private items — spec/18-modules.md § Test Modules [done] (verified 2026-03-29)
- Rust Tests: oric/src/imports/tests.rs — 3 is_parent_module_import tests
- Ori Tests: tests/spec/modules/_test/test_module_access.test.ori (accesses private internal_helper without :: prefix)

4.6 Prelude

4.7 Import Graph Tooling

PROPOSAL: proposals/approved/no-circular-imports-proposal.md § Tooling Support

4.8 Module System Details

PROPOSAL: proposals/approved/module-system-details-proposal.md

Entry Point Files

Implement: lib.ori as library entry point — spec/18-modules.md § Entry Point Files
- Rust Tests: ori_eval/src/interpreter/module/ — library entry detection
- Ori Tests: tests/spec/modules/library_entry.ori
Implement: Distinguish lib.ori vs mod.ori — spec/18-modules.md § Entry Point Files
- Package root requires lib.ori, not mod.ori
- Rust Tests: ori_eval/src/interpreter/module/ — entry point validation
- Ori Tests: tests/spec/modules/entry_point_validation.ori

Binary-Library Separation

Implement: Binary accesses library via public API only — spec/18-modules.md § Library + Binary
- use "my_pkg" { item } accesses lib.ori exports
- use "my_pkg" { ::private } is an error (no private access)
- Rust Tests: ori_eval/src/interpreter/module/ — binary-library access tests
- Ori Tests: tests/spec/modules/binary_library_access.ori

Re-export Chains

Implement: Multi-level re-export resolution — spec/18-modules.md § Re-export Chains
- Track visibility through chain (all levels must be pub)
- Aliases propagate through chains
- Rust Tests: ori_eval/src/interpreter/module/ — re-export chain tests
- Ori Tests: tests/spec/modules/reexport_chain.ori
Implement: Diamond re-exports — spec/18-modules.md § Re-export Chains
- Same item via multiple paths is not an error
- Rust Tests: ori_eval/src/interpreter/module/ — diamond import tests
- Ori Tests: tests/spec/modules/diamond_reexport.ori

Error Messages

4.9 Remaining Work (Pre-existing)

Parsing/Runtime complete, type checker pending:

4.11 Module-Level Constants

Source: grammar.ebnf § constant_decl, spec/12-constants.md

Module-level constants declared with let $NAME = value.

let $PI = 3.14159
let $MAX_SIZE: int = 1000
pub let $VERSION = "1.0.0"

Status: Parser complete (verified 2026-03-29), evaluator incomplete.

Parser

Implement: Parse let $NAME = value — constant_decl production [done] (verified 2026-03-29)
- Rust Tests: compiler/ori_parse/src/grammar/item/config/mod.rs — parse_const() implementation; oric/tests/phases/parse/imports.rs — test_import_constant_basic, _multiple, _mixed_with_regular, _mixed_with_private (6 tests)
- Ori Tests: tests/spec/modules/use_imports.ori — declares pub $default_timeout = 30 and $internal_limit = 100
Implement: Parse typed constants let $NAME: Type = value [done] (verified 2026-03-29)
- Rust Tests: oric/tests/phases/parse/imports.rs — constant parsing tests cover typed forms
Implement: Parse public constants pub let $NAME = value [done] (verified 2026-03-29)
- Rust Tests: oric/tests/phases/parse/imports.rs — visibility parsing for constants

Evaluator

Implement: Evaluate module-level constants at load time
- Rust Tests: ori_eval/src/interpreter/mod.rs — constant evaluation
- Ori Tests: tests/spec/declarations/constants_eval.ori
- LLVM Support: LLVM codegen for module constants
- LLVM Rust Tests: ori_llvm/tests/constant_tests.rs
- AOT Tests: No AOT coverage yet
Implement: Register constants in module namespace
- Rust Tests: ori_eval/src/interpreter/module_loading.rs — constant registration
- Ori Tests: tests/spec/modules/import_constants.ori

Type Checker

Implement: Type check constant initializers
- Rust Tests: ori_types/src/check/ — constant type checking
- Ori Tests: tests/spec/types/constant_types.ori
Implement: Enforce constant expression restrictions (no function calls with side effects)
- Rust Tests: ori_types/src/check/ — constant expression validation
- Ori Compile-Fail Tests: tests/compile-fail/constant_non_const_expr.ori

Import/Export

Implement: Export constants via pub let
- Ori Tests: tests/spec/modules/export_constants.ori
Implement: Import constants via use "path" { $CONST }
- Ori Tests: tests/spec/modules/import_constants.ori
/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 (4.11) — 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-4.11 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 4.11: 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.

4.12 Extension Methods

PROPOSAL: proposals/approved/extension-methods-proposal.md

Extension methods add methods to existing types without modifying their definition.

Status: Parser and basic evaluator complete (verified 2026-03-29). Type checker integration, conflict detection, orphan rules, error codes (E0850-E0852), LLVM codegen pending.

Extension Definition

Extension Import

Method Resolution

Implement: Resolution order — proposals/approved/extension-methods-proposal.md § Resolution Order
- Inherent > Trait > Extension
- Rust Tests: ori_types/src/check/ — resolution order tests
- Ori Tests: tests/spec/extensions/resolution_order.ori
Implement: Conflict detection — proposals/approved/extension-methods-proposal.md § Conflict Resolution
- Error on ambiguous extension methods
- Qualified syntax for disambiguation: module.Type.method(v)
- Rust Tests: ori_types/src/check/ — conflict detection tests
- Ori Tests: tests/spec/extensions/conflict.ori

Orphan Rules

Implement: Same-package rule — proposals/approved/extension-methods-proposal.md § Orphan Rules
- Extension must be in same package as type OR trait bound
- Error for foreign type without local trait bound
- Rust Tests: ori_types/src/check/ — orphan rule tests
- Ori Tests: tests/spec/extensions/orphan.ori

Error Messages

LLVM Support

Implement: Extension method codegen — Extension methods in LLVM backend
- Same codegen as regular methods
- LLVM Rust Tests: ori_llvm/tests/extension_tests.rs
- AOT Tests: No AOT coverage yet

Note on Type Definitions:

Full prelude with user-defined Option, Result, etc. requires Section 5 (Type Declarations)
Currently using built-in types in evaluator
See section-05-type-declarations.md § 5.1-5.4 for type definition work
/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 (4.12) — 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-4.12 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 4.12: 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.

4.10 Section Completion Checklist

Exit Criteria: Multi-file projects compile (core support complete) Status: Section 4 evaluator and parser complete. 27 of 35 [x] items fully verified, 4 have weak tests, 1 incomplete (config var imports reopened), 1 needs negative pin. LLVM multi-file infrastructure present (15 unit tests, zero integration tests). Extension parser and basic evaluator ahead of roadmap. Constant parser ahead of roadmap. Verified 2026-03-29.

/tpr-review passed — independent review found no critical or major issues (or all findings triaged)
Subsection close-out (4.10) — 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-4.10 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 4.10: 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.