Skip to content

Package Language

sarr-io edited this page Sep 14, 2026 · 13 revisions

Package language

Source files

The Image compiler recursively reads .lua and .md files below the source directory. It does not follow symlinks, rejects duplicate module names, and rejects the reserved module name pa.

The module name is the path without its extension; / and \ become .:

entry.md       -> entry
src/run.lua    -> src.run
prompts/en.md  -> prompts.en

Image modules and Import modules are available through trusted require. Other Lua and native modules use the normal trusted package searchers.

Entry contract

The configured entry must be a table with a function-valued __call metamethod. Every direct entry key must be a string and every direct value must be a function:

local entry = {
    read = function(input, config)
        return input
    end,
}

return setmetatable(entry, {
    __call = function(_, input, config)
        return input
    end,
    __metatable = false,
})

The root call and direct members receive (input, config) as strings and must return strings. Config is opaque to Portable Agents.

Markdown modules

Markdown is translated into a module-local document containing headings, prose, lists, tables, and non-Lua fenced blocks. A Lua fence shares the module's scope and controls the module's return value. A Markdown file without Lua fences returns its document.

A Lua fence gets its own immutable document through:

local document = require("pa").document()

The document and all nested tables are read-only. The binding belongs only to that Markdown module. Plain Lua modules cannot retrieve it.

Trusted loading

Trusted package code has normal Lua libraries and package searchers. Eval is a different runtime: it receives only its selected members, its input, and its caller Imports.

Clone this wiki locally