Roadmap

Roadmap

Phase 0 — Architecture and scope freeze

Goal: define what belongs to IRx core/runtime versus Arx stdlib.

Deliverables:

• Write a short design doc with these rules:

  • IRx: reusable runtime primitives, C bindings, portable helpers
  • Arx: language-facing modules, wrappers, convenience APIs
  • ASTx: no stdlib ownership; only representation of functions/modules/helpers when needed

• Define the first module surface:

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

• Define the first implementation styles:

  • direct IRx lowering
  • C runtime bindings
  • ASTx-authored helper routines inside IRx

Exit criteria:

• one accepted design doc
• one function inventory tagged as irx-runtime, irx-ast-helper, or arx-stdlib

Phase 1 — IRx runtime substrate

Goal: create the smallest reusable runtime layer in IRx.

Implement in IRx:

• symbol declaration and linking support for runtime functions

• platform-neutral runtime API names such as:

  • 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

Implementation approach:

• back these with a tiny C runtime first
• keep signatures narrow and stable
• avoid Arx-specific naming at this layer

Deliverables:

• irx/runtime/ or equivalent package
• a tiny C runtime library
• IRx codegen/linker support for attaching that runtime

Exit criteria:

• IRx can compile and run a minimal ASTx program that prints text
• IRx can read stdin, read/write a file, and access argv via runtime calls

Phase 2 — IRx portable helper layer

Goal: add reusable helpers authored with ASTx inside IRx and compiled through IRx.

This is where your clarified idea fits.

Good candidates:

• wrappers over runtime functions
• simple conversions
• pure helpers
• small string/numeric helpers that do not depend on libc details

Examples:

• str_len if string layout/runtime allows it
• str_eq
• concat wrapper
• to_string_int
• small normalization helpers

Avoid here:

• direct filesystem and console internals
• process/env/platform APIs

Deliverables:

• a small internal IRx helper library represented as ASTx modules/functions
• tests proving those helpers compile and run through IRx

Exit criteria:

• at least 3–5 helper routines are built this way

• clear examples show both implementation modes working:

  • C-backed runtime primitive
  • ASTx-authored portable helper

Phase 3 — Arx stdlib MVP

Goal: expose a clean language-facing stdlib in Arx.

Create in Arx:

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

First public functions:

std.io

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

std.fs

• read_text
• write_text
• append_text
• exists

std.process

• exit
• argc
• argv_get

std.str

• len
• eq
• concat

Arx responsibilities:

• stdlib module names and import behavior
• default linking behavior
• optional --no-stdlib / --stdlib=... flag
• wrappers around IRx runtime/helper functions

Exit criteria:

• Arx users can import and use the MVP stdlib without knowing about IRx internals
• basic CLI/file examples work end-to-end through Arx ([GitHub]4)

Phase 4 — Tooling, packaging, and tests

Goal: make stdlib reproducible and easy to evolve.

Implement:

• stdlib build flow in Arx

• runtime artifact build in IRx

• integration tests across repos:

  • IRx unit tests for runtime lowering
  • IRx execution tests for helper routines
  • Arx end-to-end tests for imports and compiled programs

Suggested test matrix:

• print to stdout/stderr
• read a line from stdin
• read/write/append file
• exists check
• argv access
• string equality/length/concat

Exit criteria:

• CI validates runtime build + Arx e2e examples
• examples become part of docs

Phase 5 — Expand core stdlib

Goal: add the next practical layer without overreaching.

Add next:

• std.math

  • abs
  • min
  • max
  • maybe pow

• std.conv

  • parse_int
  • parse_float
  • to_string

• std.collections

  • only if array/list semantics are stable

• std.time

  • only after runtime policy is clear

Keep these mostly in:

• IRx runtime/helpers if broadly reusable
• Arx if shaped by Arx language semantics

Exit criteria:

• second stdlib milestone documented and versioned

Phase 6 — Arx-native stdlib growth

Goal: start writing more stdlib in Arx itself.

Once Arx is stable enough:

• implement higher-level helpers in Arx
• compile/distribute them as part of the stdlib
• keep low-level runtime pieces in IRx

Good candidates:

• string convenience helpers
• collection helpers
• formatting helpers
• Arrow-oriented helpers that are specific to Arx’s direction as a language with an Apache Arrow focus. ([GitHub]4)

Exit criteria:

• clear split between:

  • IRx runtime/core
  • Arx-native stdlib modules

Recommended ownership split

ASTx

Owns:

• node types needed to represent functions/modules/imports/helpers
• no stdlib implementation ownership ([GitHub]1)

IRx

Owns:

• runtime ABI
• C runtime bindings
• ASTx-authored portable helper routines
• lowering/linking/tests for reusable core behavior ([GitHub]2)

Arx

Owns:

• stdlib module names
• imports/prelude
• stdlib packaging
• wrappers and higher-level Arx-specific library code ([GitHub]4)

Suggested implementation order

I would do the work in this exact order:

1. design doc + function classification
2. IRx runtime ABI and C runtime
3. IRx lowering/linking support
4. one ASTx-authored helper inside IRx as proof of pattern
5. Arx std.io
6. Arx std.fs
7. Arx std.process
8. Arx std.str
9. tests and docs
10. phase-2 expansions like math/conversions

First milestone

A very good first milestone would be:

• println("hello")
• name = read_line()
• text = read_text("file.txt")
• write_text("out.txt", text)
• exists("out.txt")
• exit(0)
• argv_get(0)

If that works cleanly, the architecture is validated.

Practical rule for future decisions

Use this filter every time:

• Put it in IRx if another ASTx+IRx-based language could plausibly reuse it.
• Put it in Arx if it is shaped by Arx syntax, ergonomics, or Arrow-specific language goals.
• Use ASTx inside IRx when the routine is pure and portable.
• Use C runtime bindings when the routine touches OS/libc/process/file/device concerns.