# Lua stubs for the `a` runtime environment

`---@meta` type definitions of the **Rust-native** parts of the `a` stdlib, for
[lua-language-server](https://github.com/LuaLS/lua-language-server) (completion,
hover docs, static checking). Definitions only — these files are never executed
and are not part of the runtime.

The **Lua-implemented** parts of the stdlib need no stubs: `lua/stdlib/*.lua`
are the actual sources and the language server reads them directly. The split:

| Stub here      | Covers                                                        |
|----------------|---------------------------------------------------------------|
| `tui.lua`      | the whole `tui` module (fully native)                         |
| `http.lua`     | `http` requests, response shape, sessions                     |
| `sqlite.lua`   | `sqlite.connect` and the connection methods                   |
| `log.lua`      | `log.trace` … `log.error`                                     |
| `task.lua`     | `task.join`                                                   |
| `utils.lua`    | native half: `NULL`, `isNull`, `dump`, `toJSON`, `fromJSON` (`try`/`tryn` live in `lua/stdlib/utils.lua`) |
| `os.lua`       | sandbox additions `os.microtime`, `os.sleep`                  |
| `require.lua`  | the sandboxed `require` (the stock `package` library is disabled in `.luarc.json`) |

The sandbox itself is mirrored in the repo-root `.luarc.json`: `runtime.builtin`
disables `io`, `debug` and `package`, which do not exist in scripts.
lua-language-server cannot hide *individual* fields, so removed functions that
live inside kept libraries (`os.execute`, `os.remove`, `os.exit`, `load`,
`loadfile`, `dofile`, `string.dump`) still autocomplete — they raise at runtime,
do not use them.

Keep these files in sync with the real API; the prose reference is `docs/*.md`.