Host Contract
The __sys_* interface between ilusm programs and the host environment.
Overview
ilusm programs are isolated from the host OS. All I/O, process, network, and crypto operations go through the host contract - a set of named syscalls prefixed with __sys_. The runtime dispatches these calls to the platform implementation.
A conforming host implements all required syscalls. Optional syscalls may be absent; the stdlib module that uses them should check availability and fail gracefully.
Core I/O
| Syscall | Args | Returns | Description |
|---|---|---|---|
__sys_read | path: str | str | nil | Read file contents |
__sys_write | path: str, data: str | tru | nil | Write file |
__sys_append | path: str, data: str | tru | nil | Append to file |
__sys_exists | path: str | tru | fls | File/dir exists |
__sys_ls | path: str | list[str] | List directory |
__sys_rm | path: str | tru | nil | Delete file |
__sys_mkdir | path: str | tru | nil | Create directory |
__sys_stat | path: str | obj | nil | File metadata |
Output
| Syscall | Args | Returns | Description |
|---|---|---|---|
__sys_prn | val: any | nil | Print to stdout + newline |
__sys_prnr | val: any | nil | Print to stdout (no newline) |
__sys_prne | val: any | nil | Print to stderr + newline |
__sys_stdin | (none) | str | Read line from stdin |
Process
| Syscall | Args | Returns | Description |
|---|---|---|---|
__sys_argv | (none) | list[str] | Command-line arguments |
__sys_env | name: str | str | nil | Environment variable |
__sys_exit | code: num | (no return) | Exit process |
__sys_spawn | cmd: str, args: list | obj | Spawn subprocess |
__sys_exec | cmd: str, args: list | obj | Execute and wait |
__sys_pid | (none) | num | Current process ID |
Time
| Syscall | Args | Returns | Description |
|---|---|---|---|
__sys_now | (none) | num | Unix timestamp (ms) |
__sys_sleep | ms: num | nil | Sleep for ms milliseconds |
__sys_date | ts: num | obj | Parse timestamp to date obj |
Networking
| Syscall | Args | Returns | Description |
|---|---|---|---|
__sys_http_get | url: str, headers: obj | obj | HTTP GET |
__sys_http_post | url: str, body: str, headers: obj | obj | HTTP POST |
__sys_tcp_conn | host: str, port: num | obj | Open TCP connection |
__sys_tcp_send | conn: obj, data: str | num | Send bytes |
__sys_tcp_recv | conn: obj, n: num | str | Receive bytes |
__sys_dns | host: str | list[str] | DNS lookup |
Cryptography
| Syscall | Args | Returns | Description |
|---|---|---|---|
__sys_sha256 | data: str | str | SHA-256 hex digest |
__sys_sha512 | data: str | str | SHA-512 hex digest |
__sys_hmac | key: str, data: str, algo: str | str | HMAC digest |
__sys_rand | n: num | str | n random bytes (hex) |
__sys_aes_enc | key: str, data: str | str | AES-256-GCM encrypt |
__sys_aes_dec | key: str, ct: str | str | AES-256-GCM decrypt |
Conforming host rules
- All required syscalls must be implemented and return the documented types.
- On error, syscalls return
nil(not an exception) unless the contract specifies otherwise. - Syscalls must not block the event loop for more than 100ms without yielding.
- New syscalls must be added to
lib/runtime/syscall_contract.ilubefore use.