Crate elly 

elly — run an Elly module as a program.

A program is a module: the same parser, the same const stage, the same instantiation, plus one reserved moditem saying the file may be run. A library is the same file without it. See docs/done/2026-08-14_elly-run.md.

The whole runner is five steps: load the graph, read the entry module’s body slot, evaluate it in the module’s own environment, apply the result to the root capability IO, and turn what comes back into an exit status.

Modules

io 🔒

Building IO, the root capability the runner hands a program.

resolve 🔒

The runner’s [ModuleResolver]: enough to run a project-less script, and no more (decision 4 of docs/done/2026-08-14_elly-run.md).

Enums

Args 🔒

What the command line asked for.

Constants

FAILED 🔒

The program started and failed: an uncaught raise.

NOT_STARTED 🔒

The program never started: bad usage, an unreadable file, a load or compile failure. The two failure statuses differ because they fail at different stages.

OK 🔒

The program ran and asked for nothing else.

USAGE 🔒

Functions

describe_load 🔒

Why a module graph would not load, in one line.

fail 🔒

Report message on stderr under the program’s own name, and hand back status for main to exit with.

finished 🔒

The program returned normally. Its value is ignored — printing a result is REPL behaviour, and [] as unit is not distinctive enough to key on — so the status is 0 unless IO.Proc.exit already said otherwise.

main 🔒

parse_args 🔒

Read the command line. Two invocations, because #!/usr/bin/env elly execs elly <script> <args…>: the bare form has to work, with elly run <script> as its explicit spelling.

raised 🔒

A raise reached the top. Either it is IO.Proc.return’s unwind — the program asking for an exit status — or it is a genuine failure, which goes to stderr with status 1.

read_script 🔒

Canonicalize and read the entry script, or say why not.

requested_exit 🔒

The status IO.Proc.return n asked for, if that is what this raise is: a two-element list led by the iota only IO.Proc can mint. An ordinary raise cannot be mistaken for one, whatever shape it has, because it cannot hold that value.

run 🔒

Load script, run its __main against a fresh IO, and report what happened.