lua: Lua 5.5 as a crate, with io, os and kore.fs

[SnowCheetos]

Overview

crates/lua (kore-lua): the Lua 5.5 engine, its freestanding host and the kore.* standard library, moved out of Kore's user/apps/utils/lua so any libkore consumer can embed it. Beside kore-wasi, on the same seam.

A script sees two surfaces over one implementation. io.open and kore.fs.open return the same file object; one failure is rendered two ways, both derived from FsError. io/os answer what POSIX can ask, with the capabilities defaulted from the mode string; kore.fs answers what the store can. docs/lua.md is the reference.

io and os are written here, not vendored: Lua's liolib.c and loslib.c are libc over POSIX and this target has neither.

Capabilities

A DagFS route is reached through a View, which is affine. Only one of the four surfaces can hold one, because only one has a language that enforces it.

Surface	What you hold	What stops a second use	Rights you can name
io / os	a file object	__close/__gc, plus a generation check	none; inferred from the mode string
kore.fs	the same file object	the same	r, w today; n, s as their verbs land
C (kore-ffi)	a KoreFsHandle	the adapter, at run time	uint32_t; KORE_FS_READ, KORE_FS_WRITE
Rust (kore::fs)	the View itself	the borrow checker, at compile time	the whole Rights type, and fs::dag

Lua and C are in the same position for the same reason: a Lua value can be copied into a table or captured by a closure, and a C struct can be memcpy'd, so neither can be handed something affine. Both get a handle — an index and a generation into a table thread 0 owns — and a stale one is invalid-handle. Rust holds the capability itself; src/fs.rs keeps a compile_fail doctest to prove it.

No surface forges authority: the store resolves every route through a generational slot. What differs is how much of the vocabulary each can say, what it costs to say it, and how early a mistake is caught.

io is not a smaller filesystem. It is the same one with the capability questions answered by convention, so it cannot ask for less, ask for more, or find out what it got:

local f = assert(io.open("/var/log/app", "a"))        -- rights: READ WRITE, create, append

local g = assert(kore.fs.open("/etc/hosts", "r"))     -- least authority, on purpose
local held = assert(kore.fs.rights("/var/log"))       -- and what did this task actually get?
if not held.write then return nil, "not endowed with write authority there" end

kore.fs expresses every route io can, plus three things it has no spelling for: rights asked for by name, rights reported back, and behaviour chosen apart from authority.

-- io's "w" is three decisions fused into one letter. Taken apart, you can take two:
local f = assert(kore.fs.open(path, "rw", {create = true}))   -- keep what is there

Lifetime is deterministic on both surfaces, __gc only a backstop. revision and id are visible on neither io nor POSIX: one moves on every commit, so a script can tell a write landed underneath it; the other is volume-stable, so it answers "same object" where a path answers "same name".

do
  local f <close> = assert(kore.fs.open("/tmp/scratch", "rw", {create = true}))
  f:write(payload)
end   -- retired here, whether the block ended or threw

docs/lua.md has the worked version.

kore.fs

Each answers nil, err on failure, where err is {code, kind} with a __tostring of the code.

Verb	Answers
open(path [, rights [, options]])	a file object
read_file(path)	the whole file; "" for an empty one
write_file(path, bytes)	the byte count written
resize(file, bytes)	true; takes an open file, not a path
stat(path)	the object's record
entries(path)	the directory's edges
rights(path)	the rights held there
list(path)	the directory's names
exists(path)	a boolean; no failure spelling
mkdir(path)	true
remove(path)	true
rename(from, to)	true; the store's own move, across directories, keeping identity and grants

open takes authority and behaviour separately:

local f = assert(kore.fs.open("/etc/hosts"))                         -- rights default to "r"
local g = assert(kore.fs.open("/var/log", "rw", {create = true}))

rights is a subset of the store's rwns spelling, each letter once, parsed by kore_dagfs::rights_parse rather than in C. READ is implied, so "w" is a readable write route. n and s are refused by name until the verbs that use them exist. options are create, truncate, append, exclusive.

Mistakes raise: a malformed spelling, an unreachable right, an unknown option key, truncate or append without w, exclusive without create. A refusal from the store arrives as nil, err.

stat answers the object's whole record. None of it is authority.

Field
size_bytes	integer
kind, directory	"file" or "directory", and the same fact as a predicate
revision	monotonic; moves on every commit
id	volume-stable; survives a service restart
links, grants	names pointing at the object, grants outstanding on it
subtype	"plain", "executable-image", "package-manifest", or absent when this build cannot name the byte
subtype_bits	the raw byte, always present

entries answers {name, kind, directory, subtype?, subtype_bits} per edge, where list answers names. rights answers {spelling, read, write, mutate_namespace, share}; spelling is what a later share would accept, and the booleans are derived from it.

The file object

One userdata, whichever surface opened it.

Method	Answers
f:read(...)	"a", "l", "L", "n", or a byte count
f:write(...)	the file, so writes chain
f:lines(...)	an iterator over the read formats
f:seek([whence [, offset]])	the new position
f:flush()	true; a durability barrier, not a buffer drain
f:setvbuf(mode)	true; accepted and inert
f:close()	true; idempotent
f:closed()	a boolean, without raising

The stream position and its read-ahead live in the file object, not beside the view, so there is one authority for it; the host side is purely positional. A handle is an index and a generation, so a use after close is invalid-handle rather than a read of whatever took the slot. __close and __gc both retire the handle, deterministic close first.

io and os

Twenty of the twenty-two members the manual lists, and all seven file: methods. Where the manual leaves a detail to the system, this build chooses and records it in KORE-VENDOR.md:

Member
os.getenv	nil for every name; a task's authority arrives as capabilities, not strings
os.date, os.time	one clock, UTC; isdst false; civil time computed, there being no gmtime or timezone database below
os.clock	monotonic since the VM started
os.exit	records the code and unwinds by raising, so <close> handlers run
os.setlocale	"C", nil for anything else
os.tmpname, io.tmpfile	the name is created exclusively; io.tmpfile removes its own on retire
io.lines(name)	four values, the last to-be-closed

Absent: os.execute and io.popen, both of which launch a process — a service face the embedding program holds and this crate does not, so they arrive through Extension. Also string.format (no hosted printf) and load/loadfile/dofile/string.dump (no bytecode verifier upstream).

The rest of kore.*

Module
kore.time	now(), mono_ns(), wall(), wall_ns(), sleep(seconds)
kore.random	bytes(n) for n <= 4096, integer(lo, hi), available()
kore.proc	args, a lazy 1-based array fetched once
kore	has(name), caps(); an unheld module is nil, so if kore.fs then is the idiom
require	the task's tree then libs/; <name>.lua over <name>.so; source bounded at 64 KiB

Errors

local f, err        = kore.fs.open("/nowhere", "r")   -- err.code == "not-found", err.kind == "refused"
local g, why, errno = io.open("/nowhere", "r")        -- why == "not-found", errno == 2

kind is "refused" when the service named a reason, "unavailable" when the call could not be made at all. Expected failures answer nil, err; programming errors raise.

The embedding API

Item
Host::start::<E>(transport)	spawn the VM worker
Host::eval::<E>(services, extension, script, chunk_name, repl)	run a chunk, serving every require; answers (Outcome, stdout, stderr) or Fatal
Host::quit(self)	retire the worker
Services::new(rt, transport, args)	the thread-0 half: filesystem session, open files, launch arguments
Services::{exit_request, close_open_files, fs}	the code os.exit recorded, teardown, the attached face
Outcome	Ok, Failed, Exited, Incomplete, ResourceRefused, Startup

pub trait Extension {
    const LIBRARIES: &'static [Library] = &[];
    fn serve(&mut self, op: u32, args: [u64; 3]) -> impl Future<Output = Answer>;
}

Library::new(name, opener) registers one module beneath kore. Answer is Value(u64, u64), Bytes(u64, Vec<u8>), Refused(String) or Unavailable(String). Ops at or above OP_EMBEDDER_BASE (64) reach serve; below it the vocabulary is this crate's. kore_lua::api is the Lua C API subset an opener calls, and files::code is public so an embedder's own filesystem failures render in the same words.

Extension carries no 'static bound. It forbade the one shape an embedder has — a face borrowed from the Rt and transport its main owns — and bought nothing; the worker reads only LIBRARIES.

The transport grows one borrowed byte window so a path or a write's bytes cross without a copy. No new word state, and a verb is still a constant and an arm.

native/

Re-exported at Kore 9e4172bc2. The export grows kore-ld and kore-late, which require "<name>.so" needs to check a store object stamped EXECUTABLE_IMAGE, place it in the task's JIT arena and bind it against the exported Lua C API (Kore res/IMAGE.md §8).

Not implemented

Deriving a view, delegating one, and the grant vocabulary. Everything here reports rather than confers: a StableObjectId conveys no authority, a subtype gates nothing, rights reports what a walk already found. Conferring or moving authority waits on MicroPerceptron/kore#986 (grant boundary, route shape, rights vocabulary) and #991 (whether a userland authority domain gets a generic capability type).

Index publication on save waits on kore-dagfs's index feature, which pulls kore-svc-extract-worker-rust; enabling it is an image-size decision for this target.

search, grant listing, create with a subtype and scoped commit batching are planned. docs/kore-fs-vocabulary.md has the order, docs/pack-backed-reads.md the storage-transport half.

Gates

make fmt test check docs owners cross miri bindings-check and tools/check-local.py clean. make cross covers x86_64, aarch64 and riscv64gc and now includes this crate, so a target-only regression in the amalgamation meets a compiler instead of a keytest.

The host smoke runs the whole surface on every build against the in-memory store in tests/host_fs.c, which models the refusal vocabulary, the graph facts, short reads and short writes. Each behavioural claim has a negative control: stubbing out the large-read bypass, the short-write retry, the unknown-subtype carry or the unreachable-rights refusal fails that claim's assertion and no other.

The smoke also gets the right prototype for kore_lua_new: it declared three parameters against a definition taking five, so every run passed two garbage registers that luaopen_kore then walked as a library array.

Not proven on metal

Kore's user/apps/utils/lua still carries its own copy of the engine and pins libkore at 861cef90, from before this crate existed, so a Kore image builds a different program. Making that app a thin embedder over kore-lua is the follow-up. Until it lands, every measurement here is a host build.

Wasmtime

Two bumps unrelated to the Lua work, 47 → 48.0.3 and 48.0.3 → 48.0.5, for RUSTSEC-2026-0315, -0316, -0325, -0326 and -0327. The Advisories workflow fails on all five. Neither bump needed a source change.

Authored by @julian-avar

[Copilot]

The job was not started because a GitHub Actions budget is preventing further Actions use.

[SnowCheetos]

@julian-avar Can you confirm that the fs API you're using is compatible with https://github.com/MicroPerceptron/kore/pull/1064's upgraded dagfs? I foresee we transition fs fully to be pack backed, the performance upside is too high not to.

[julian-avar]

@SnowCheetos Take a look if its good now