Skip to content

Milestones

Jump to bottom
Ivan Ogasawara edited this page Mar 11, 2026 · 1 revision

Proposed milestones

Milestone 1 — Stdlib architecture freeze

Target repo:

  • arx-proposals or arx

Goal:

  • approve the split between IRx runtime/core and Arx stdlib surface.

Issues:

1. ArxEP: define stdlib layering across ASTx, IRx, and Arx

Description: Define the architectural split:

  • ASTx as representation only
  • IRx as reusable runtime/core substrate
  • Arx as user-facing stdlib and higher-level modules

2. Define MVP stdlib modules and function inventory

Description: Freeze the first public module surface:

  • std.io
  • std.fs
  • std.process
  • std.str

And classify each function as:

  • irx-runtime
  • irx-ast-helper
  • arx-stdlib

3. Define runtime ABI naming convention

Description: Choose stable backend/runtime symbol names such as rt_println, rt_read_line, rt_file_read_text, and rt_exit, keeping them generic enough for reuse beyond Arx.

Milestone 2 — IRx runtime substrate MVP

Target repo:

  • irx

Goal:

  • add a tiny reusable runtime layer in IRx for I/O, files, process, and argv support. IRx already lowers ASTx nodes to LLVM IR, produces executables via clang, and today includes small built-ins like putchar plus puts declarations, so this is the natural next layer. ([GitHub]2)

Issues:

4. Add runtime module skeleton to IRx

Description: Create the internal package structure for runtime/core support, such as:

  • irx.runtime
  • irx.runtime.bindings
  • irx.runtime.linking

5. Add runtime symbol declaration helpers

Description: Provide helpers to declare and reuse external runtime symbols in generated LLVM IR.

6. Add runtime link integration in IRx build flow

Description: Teach IRx how to compile/link with a tiny runtime object or library during executable generation.

7. Add C runtime MVP for console I/O

Description: Implement C-backed runtime functions for:

  • rt_print
  • rt_println
  • rt_eprint
  • rt_eprintln
  • rt_read_line
  • rt_read_char

8. Add C runtime MVP for file operations

Description: Implement:

  • rt_file_read_text
  • rt_file_write_text
  • rt_file_append_text
  • rt_file_exists

9. Add C runtime MVP for process and argv

Description: Implement:

  • rt_exit
  • rt_argc
  • rt_argv_get

10. Add IRx lowering support for runtime calls

Description: Allow IRx-generated programs to emit calls to the runtime ABI.

11. Add execution tests for runtime-backed programs

Description: Add end-to-end tests that compile and run tiny ASTx programs using the new runtime surface.

Milestone 3 — IRx AST-authored helper layer

Target repo:

  • irx

Goal:

  • validate the pattern of writing reusable helpers with ASTx nodes inside IRx, then compiling them with IRx. This fits your clarified design and preserves ASTx as representation while letting IRx host portable helper routines. ASTx explicitly positions itself as a language-agnostic AST library and notes integration with IRx for code generation. ([GitHub]1)

Issues:

12. Add internal helper module builder using ASTx

Description: Create a small internal facility in IRx for defining helper functions/modules with ASTx nodes.

13. Implement first AST-authored helper in IRx

Description: Add one trivial but useful helper as proof of pattern, for example a wrapper routine over a runtime primitive or a tiny pure helper.

14. Add test suite for AST-authored IRx helpers

Description: Verify those helpers can be generated, compiled, linked, and executed.

15. Document decision rules for C-backed vs AST-authored helpers

Description: Write guidelines for when a helper belongs in:

  • C runtime
  • direct IR generation
  • ASTx-authored helper layer

Milestone 4 — Arx stdlib MVP surface

Target repo:

  • arx

Goal:

  • expose the first user-facing stdlib modules in Arx. Arx is the language/compiler layer and is already the right place to own user-facing imports, module names, and defaults. ([GitHub]3)

Issues:

16. Add stdlib module layout in Arx

Description: Create the public module structure:

  • std.io
  • std.fs
  • std.process
  • std.str

17. Add Arx wrappers for IRx console runtime

Description: Expose:

  • print
  • println
  • eprint
  • eprintln
  • read_line
  • read_char

18. Add Arx wrappers for IRx file runtime

Description: Expose:

  • read_text
  • write_text
  • append_text
  • exists

19. Add Arx wrappers for IRx process runtime

Description: Expose:

  • exit
  • argc
  • argv_get

20. Add Arx wrappers/helpers for basic string operations

Description: Expose:

  • len
  • eq
  • concat

Whether these call runtime functions or IRx helper routines can be decided function by function.

21. Add stdlib import resolution in Arx

Description: Make stdlib modules resolvable from normal Arx programs.

22. Add --no-stdlib flag

Description: Allow building without the standard library layer for testing, minimal programs, or alternative runtimes.

23. Add --stdlib mode flag

Description: Prepare for future selection modes such as auto, bundled, or none.

Milestone 5 — End-to-end examples and CI

Target repos:

  • irx
  • arx

Goal:

  • validate the full path from ASTx/IRx runtime to Arx user-facing stdlib.

Issues:

24. Add IRx integration example: hello world with runtime

Description: Minimal ASTx→IRx→executable example using rt_println.

25. Add Arx example: stdin to stdout

Description: Example using read_line and println.

26. Add Arx example: file copy

Description: Example using read_text and write_text.

27. Add Arx example: argv inspection

Description: Example using argc and argv_get.

28. Add CI jobs for runtime-backed e2e tests

Description: Run compiled/runtime-backed examples in CI for both IRx and Arx.

29. Add docs page for stdlib architecture

Description: Document the split:

  • ASTx representation
  • IRx runtime/core
  • Arx stdlib surface

Milestone 6 — First expansion after MVP

Target repos:

  • mostly arx, some irx

Goal:

  • add the next practical layer once the architecture is stable.

Issues:

30. Add std.conv MVP

Description: Expose:

  • parse_int
  • parse_float
  • to_string

31. Add std.math MVP

Description: Expose:

  • abs
  • min
  • max

32. Evaluate std.collections prerequisites

Description: Decide whether array/list semantics are mature enough for collection helpers.

33. Move suitable pure helpers from Arx to IRx helper layer

Description: Review helpers added in Arx and migrate any backend-generic logic that could be reused by non-Arx consumers.

Suggested ordering

I would execute the roadmap in this order:

  1. ArxEP / architecture freeze
  2. IRx runtime substrate
  3. IRx AST-authored helper proof
  4. Arx stdlib MVP modules
  5. e2e examples and CI
  6. post-MVP expansion

That sequence keeps the reuse boundary clean and avoids baking Arx-specific assumptions too early.

MVP function classification

Here is the split I would start with.

irx-runtime

  • rt_print
  • rt_println
  • rt_eprint
  • rt_eprintln
  • rt_read_line
  • rt_read_char
  • rt_file_read_text
  • rt_file_write_text
  • rt_file_append_text
  • rt_file_exists
  • rt_exit
  • rt_argc
  • rt_argv_get

irx-ast-helper

Candidates only after runtime works:

  • simple wrappers
  • normalization helpers
  • small pure string helpers
  • small conversions that do not depend on OS/libc details

arx-stdlib

  • std.io.print
  • std.io.println
  • std.io.eprint
  • std.io.eprintln
  • std.io.read_line
  • std.io.read_char
  • std.fs.read_text
  • std.fs.write_text
  • std.fs.append_text
  • std.fs.exists
  • std.process.exit
  • std.process.argc
  • std.process.argv_get
  • std.str.len
  • std.str.eq
  • std.str.concat

Good first 10 issues to open now

If you want the most practical starting batch, I would open these first:

  1. ArxEP: define stdlib layering across ASTx, IRx, and Arx
  2. Define MVP stdlib modules and function inventory
  3. Define runtime ABI naming convention
  4. Add runtime module skeleton to IRx
  5. Add runtime symbol declaration helpers
  6. Add runtime link integration in IRx build flow
  7. Add C runtime MVP for console I/O
  8. Add C runtime MVP for file operations
  9. Add C runtime MVP for process and argv
  10. Add Arx stdlib module layout

Recommendation on repo placement

I would put:

  • the architecture/design issue in arx-proposals if you want it formalized as an ArxEP, since that repo exists exactly for enhancement proposals and process/design discussions. ([GitHub]4)
  • implementation issues in irx and arx
  • no ASTx issues unless you later discover a missing AST node needed to represent helper routines

One small naming refinement

I would avoid calling the IRx layer “IRx stdlib.” I would call it:

  • IRx runtime/core
  • Arx standard library

That wording keeps the boundary crisp and protects IRx’s reuse story.

Clone this wiki locally