a/lua/stubs/README.md

Lua stubs for the Luna runtime environment

---@meta type definitions of the Rust-native parts of the Luna stdlib, for 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.