fix: address F2/F4 review findings (leaks, qsort guard, err contract, compiler-default layering)

Wire the full pipeline into the binary: parse + validate the KDL buildfile,
discover extensions, bridge Lua, detect the C toolchain, and emit ./configure.
Adds the project's own stupid.kdl build file and a temp-dir-isolated self-host
integration test proving the generated configure + make rebuild the tool with
-std=c23. tests/run.sh tests 6+8 re-pin the interim 'accepted, no read' CLI
assertions to the wired 'missing buildfile -> exit 1' behavior.

.gitignore

@@ -52,3 +52,30 @@ Module.symvers
 Mkfile.old
 dkms.conf
 
+# ---> Autotools (all generated by autoreconf/configure; only the .am/.ac
+#      inputs are tracked in git)
+configure
+config.log
+config.status
+aclocal.m4
+autom4te.cache/
+Makefile
+Makefile.in
+compile
+depcomp
+install-sh
+missing
+test-driver
+.deps/
+.dirstamp
+test-suite.log
+*.trs
+*.log
+
+# ---> unit test binaries (built by tests/run.sh, never committed)
+/tests/.unit-build/
+
+# ---> stupidtools binaries (built, never committed)
+/stupidtools
+/src/stupidtools
+

AGENTS.md

@@ -0,0 +1,52 @@
+# AGENTS.md
+
+Operating rules for anyone working in this repo, human or agent. The project:
+a GNU AutoTools replacement in C that reads a KDL build file and emits a
+POSIX-sh `./configure`. Yes, the name is the joke. The rules below are not.
+
+## 1. C23 only
+
+Write C23 (ISO/IEC 9899:2024). Compile with `-std=c23` and `-Wall -Wextra
+-Wpedantic`. Never target C20 (it does not exist as a ratified standard), never
+use C2y (the next draft). The build breaks on anything else.
+
+## 2. Vendoring: thirdparty/ only, license + pinned SHA
+
+Every third-party library is vendored in-tree under `thirdparty/<name>/`, with
+all three of:
+
+- the upstream `LICENSE` file (never omitted, never stubbed),
+- an `UPSTREAM` file recording the source URL and the pinned upstream commit
+  SHA,
+- a row in the `thirdparty/README.md` provenance table (name, version, license,
+  SHA).
+
+No git submodules. If it is not vendored this way, it does not exist.
+
+## 3. Tests: TDD, `make check` + `tests/run.sh`
+
+- Unit tests use the vendored single-header C test framework and run via
+  `make check`.
+- Shell integration tests live in `tests/*.sh` and are invoked by
+  `tests/run.sh`, asserting exact exit codes and grep-able output markers.
+- TDD workflow: write the test alongside the code. Implementation + test is one
+  unit of work, never separated.
+
+## 4. Generated configure scripts: POSIX-sh only
+
+The emitted `./configure` must run unmodified under `dash`, `bash`, and `zsh`.
+Banned constructs, no exceptions:
+
+- `[[ ]]`
+- arrays
+- `local`
+- `==` (use `=` with `[`, or `case`)
+- `<<<`
+- `&>`
+
+`set -e` IS POSIX, but it is avoided by policy in generated scripts because its
+failure semantics vary across shells. Do not rely on it; make the script fail
+explicitly. `dash` is the strict oracle: `dash -n` must pass on everything we
+generate.
+
+For build, test, and commit workflows, see CONTRIBUTING.md.

CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing to stupidtools
+
+The project is a GNU AutoTools replacement: read a KDL build file, emit a
+POSIX-sh `./configure`. Contributions should follow the rules in AGENTS.md.
+This file covers the mechanics.
+
+## Build
+
+stupidtools bootstraps itself with autotools:
+
+```
+autoreconf -ivf
+./configure
+make
+```
+
+You need a C23-capable compiler (GCC >= 14 or Clang >= 18) and autotools.
+The build compiles with `-std=c23 -Wall -Wextra -Wpedantic`.
+
+## Test
+
+```
+make check      # unit tests via the vendored single-header C test framework
+tests/run.sh    # shell integration tests (exact exit codes + grep-able markers)
+```
+
+TDD workflow: write the test alongside the code. Implementation + test is one
+unit of work, never separated.
+
+## Commit
+
+Conventional commits, one per logical change:
+
+- `build:` build system, toolchain flags
+- `feat(kdl):` lexer, parser, values, schema
+- `feat(detect):` check registry, probes, feature resolution
+- `feat(gen):` configure generator, config.status/log/h, argument parsing
+- `feat(ext):` extension ABI, Lua embed, discovery
+- `test:` tests
+- `docs:` documentation
+- `chore:` vendoring, misc
+
+Never bundle two logical changes in one commit. Never commit generated
+artifacts (`configure`, `Makefile`, `config.h`, `config.status`, `config.log`).
+
+## Vendoring policy
+
+Every third-party library is vendored in-tree under `thirdparty/<name>/`:
+
+- the upstream `LICENSE` file (never omitted, never stubbed),
+- an `UPSTREAM` file recording the source URL and the pinned upstream commit
+  SHA,
+- a row in the `thirdparty/README.md` provenance table (name, version, license,
+  SHA).
+
+No git submodules. If it is not vendored this way, it does not exist.

Makefile.am

@@ -0,0 +1,37 @@
+# Top-level Makefile.am: recursion into src/ plus the test harness.
+# `make check` runs tests/run.sh through automake's parallel test harness
+# (genuinely executed - the harness propagates the script's exit code).
+
+SUBDIRS = src
+
+TESTS = tests/run.sh
+EXTRA_DIST = tests/run.sh scripts/build-static.sh
+
+# Fully-static musl build (explicit opt-in; the default build stays dynamic).
+# Requires a musl toolchain on the host - see scripts/build-static.sh for
+# the probe order (musl-gcc -> musl-clang -> clang+sysroot -> apt -> musl.cc).
+.PHONY: static
+static:
+	$(SHELL) "$(srcdir)/scripts/build-static.sh"
+
+# Release/debug build profiles (explicit opt-in; `make` alone is unchanged).
+#
+# Mechanism: CFLAGS is passed on the recursive make COMMAND LINE. Automake's
+# compile rule ends with `$(AM_CFLAGS) $(CFLAGS)`, so a command-line CFLAGS
+# overrides configure's `-g -O2` default while AM_CFLAGS (-std=c23 -Wall
+# -Wextra -Wpedantic) is always kept. No configure.ac churn, no default
+# build impact. Both targets clean first so a previous profile's objects
+# can never be reused as a fresh build.
+#
+# release: -O2 -DNDEBUG, no -g, then the binary is stripped (needs binutils
+#          `strip` on PATH).
+# debug:   -g2 only, no -O/-O2, no NDEBUG (default CFLAGS are overridden).
+.PHONY: release debug
+release:
+	$(MAKE) clean
+	$(MAKE) CFLAGS="-O2 -DNDEBUG"
+	strip src/stupidtools
+
+debug:
+	$(MAKE) clean
+	$(MAKE) CFLAGS="-g2"

builtin-ext/README.md

@@ -0,0 +1,45 @@
+# builtin-ext/ — builtin extension directory
+
+The directory of extension modules that ship with stupidtools (plan
+todo 20). It is currently empty on purpose; it exists to lock the
+convention.
+
+## What goes here
+
+Lua extension modules (`*.lua`) that load by default on every run. A
+module registers checks and languages through the sandboxed runtime's
+`st` API:
+
+```lua
+st.register_check("magic")
+st.register_language("fortran")
+```
+
+Only regular files with a `.lua` suffix are loaded (dotfiles are
+skipped); anything else here — this README included — is ignored by
+discovery. Files load in bytewise-lexicographic order.
+
+## How discovery finds this directory
+
+`st_ext_discover()` (src/ext/discovery.c) scans this directory LAST in
+the search order:
+
+1. each `--ext-dir` directory (repeatable flag),
+2. each `STUPIDTOOLS_EXT` entry (colon-separated environment list),
+3. the user directory: `$XDG_DATA_HOME/stupidtools/ext`, falling back
+   to `$HOME/.local/share/stupidtools/ext`,
+4. this directory.
+
+The location is the `STUPIDTOOLS_BUILTIN_EXT_DIR` macro — currently the
+literal `builtin-ext`, resolved relative to the working directory of
+the running binary (fine for the in-repo layout). When an installed
+layout arrives, the build will override it at compile time, e.g.
+`-DSTUPIDTOOLS_BUILTIN_EXT_DIR='"<prefix>/share/stupidtools/ext"'`, and
+ship modules here.
+
+## Why it is empty today
+
+The builtin C and C++ language modules are compiled C code
+(`src/ext/lang_c.c`, `src/ext/lang_cpp.c`), not Lua, so nothing needs
+to live here yet. The first shipped Lua module arrives with the example
+extension todo and could serve as a fixture for this location.

configure.ac

@@ -0,0 +1,27 @@
+# configure.ac - stupidtools bootstrap (autotools, C23).
+#
+# This is the *bootstrap* build only: stupidtools will later generate its
+# own ./configure (self-hosting, todo 23). Only Makefile.am inputs are
+# tracked in git; configure/Makefile* are generated and gitignored.
+
+AC_PREREQ([2.71])
+AC_INIT([stupidtools], [1.0.0], [[email protected]])
+AM_INIT_AUTOMAKE([foreign subdir-objects])
+AC_CONFIG_SRCDIR([src/main.c])
+AC_PROG_CC
+
+# Require a compiler that actually accepts C23 (ISO/IEC 9899:2024).
+# -std=c23: GCC >= 14, Clang >= 18. Never -std=c2y (next draft, not ratified).
+save_CFLAGS="$CFLAGS"
+CFLAGS="$CFLAGS -std=c23 -Werror"
+AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
+  [[#if !defined(__STDC_VERSION__) || __STDC_VERSION__ < 202311L
+#error "C23 (__STDC_VERSION__ >= 202311L) required"
+#endif]],
+  [[_Static_assert(1, "ok");]])],
+  [],
+  [AC_MSG_ERROR([a C compiler with C23 support (GCC >= 14 or Clang >= 18) is required])])
+CFLAGS="$save_CFLAGS"
+
+AC_CONFIG_FILES([Makefile src/Makefile])
+AC_OUTPUT

docs/extensions.md

@@ -0,0 +1,159 @@
+# Extensions: adding a language without touching core
+
+stupidtools is deliberately not a one-trick C compiler. The core binary
+knows only about a generic extension ABI (`src/ext/abi.h`); the C/C++
+languages are themselves just the first modules over it (`src/ext/lang_c.c`,
+`src/ext/lang_cpp.c`). Any other language — Fortran, Rust, D, a toy DSL —
+is added by dropping a Lua module into an extension directory. No core
+changes, no recompiling.
+
+The worked example this document walks through is
+[`examples/ext_fortran.lua`](../examples/ext_fortran.lua), a complete
+third-party Fortran stub. Read that file first; it is heavily commented.
+
+---
+
+## 1. Where extensions live (discovery)
+
+Extension discovery (`src/ext/discovery.h`) looks in this order:
+
+1. **`--ext-dir DIR`** — repeatable command-line flag (`stupidtools
+   --ext-dir DIR [--ext-dir DIR2 ...] <buildfile>`).
+2. **`STUPIDTOOLS_EXT`** — colon-separated directory list
+   (`STUPIDTOOLS_EXT=/a:/b stupidtools <buildfile>`); empty entries are
+   skipped.
+3. **User directory** — `$XDG_DATA_HOME/stupidtools/ext`, falling back to
+   `$HOME/.local/share/stupidtools/ext` when `XDG_DATA_HOME` is unset or
+   empty. Skipped entirely when neither variable yields a path.
+4. **Builtin directory** — `builtin-ext/` relative to the working
+   directory (compile-time configurable via
+   `-DSTUPIDTOOLS_BUILTIN_EXT_DIR` for installed layouts).
+
+Scanning rules: only **regular files ending in `.lua`** are loaded
+(dotfiles excluded); load order within a directory is bytewise-
+lexicographic; a missing or empty directory is a silent no-op; an empty
+`.lua` file is a clean no-op. Discovery **fail-fasts**: the first module
+that fails to load (syntax error, runtime error, sandbox violation,
+unreadable file) aborts with `extension load failed: <path>: <message>`,
+and later modules are not attempted.
+
+Each loaded module logs one line built from its **actual** registrations:
+
+```
+loaded extension: /tmp/extdemo/ext_fortran.lua — checks: 1 (fortran_compiler_flag) languages: 1 (fortran)
+```
+
+## 2. The sandbox contract
+
+Extension code runs in a stripped Lua 5.4 runtime (`src/ext/lua.h`). The
+module is **declarative** — it registers capabilities; it cannot execute
+or touch the outside world:
+
+| Capability | Status |
+| --- | --- |
+| `st.register_language`, `st.register_check` | the **only** interface |
+| base / table / string / curated `math` / hand-built `os` | available |
+| `os.execute`, `os.exit`, `os.remove`, `os.rename` | **present but blocked** — calling them raises `sandbox blocked: ...` and fails discovery |
+| `dofile`, `loadfile`, `require`, `package`, `io`, `debug`, `coroutine` | **nil** — their C libraries are not even linked |
+
+A module that violates the sandbox is rejected with a clear load error;
+the binary never runs untrusted program execution.
+
+## 3. The registration API
+
+Two functions on the `st` table. Call shapes (exact — see
+`src/ext/api.h` and `src/ext/lua.c`):
+
+```lua
+st.register_language(name, [spec_table])
+st.register_check(name, { kind = "compile"|"link"|"run", source = "<C snippet>", link = { "-lfoo", ... } })
+```
+
+- **`register_language(name [, table])`** — registers a language *name*.
+  The optional second argument, if present, must be a table; v1 records
+  the name only (the table's contents are reserved for future language
+  detection).
+- **`register_check(name, spec)`** — registers a custom check. `kind` is
+  the probe **mode** (compile / link / run), `source` is the C snippet
+  the probe compiles, and `link` is an optional list of extra argv
+  elements for the link step. The check's *name* becomes a new check kind
+  a build file can reference, exactly like the builtin `header` kind.
+- Names must be non-empty strings with no NUL bytes and must not collide
+  with an already-registered name (builtin or earlier module).
+
+The Lua tables are materialized into a `struct st_lua_probe_spec`
+(`src/ext/api.h`): all fields strdup'd, owned by the runtime's registry,
+freed with the runtime.
+
+## 4. v1 limitations (documented, deliberate)
+
+- **Custom checks compile C snippets against the C toolchain.** The
+  `source` in a probe spec is a *C* snippet driven by the detected C
+  compiler (`st_lua_probe_run` in `src/ext/api.h`). There is no generic
+  per-language probe runner yet; the Fortran example's check is a C
+  probe whose name says "fortran". (This is why the example keeps its
+  source libm-free and trivially true.)
+- **Lua language detection is a stub.** `register_language` records the
+  name only; nothing yet detects a `fortran` compiler on the host, and
+  the DSL has no language-scoped feature resolution wired to it. The
+  table argument exists so a later release can add
+  `register_language("fortran", { detect = ... })` without breaking
+  existing modules.
+- **The bridge maps every Lua check to the `"c"` language** internally
+  (`ST_LUA_CHECK_LANGUAGE` in `src/ext/api.c`) — again, v1 custom checks
+  are C snippets, by design.
+
+## 5. Step-by-step: adding a new language
+
+Copy this recipe for any language, not just Fortran.
+
+1. **Write a `.lua` module.** Model it on `examples/ext_fortran.lua`:
+
+   ```lua
+   -- mylang.lua
+   st.register_language("mylang", { kind = "compile" })
+   st.register_check("mylang_compiler_flag", {
+       kind   = "compile",
+       source = "int main(void) { return 0; }",
+       link   = { "-lmylang" },
+   })
+   ```
+
+   Only `st.*` calls are allowed; no `os.execute`, no `io`, no
+   `require` — the sandbox enforces it.
+
+2. **Drop it in a discovery directory.** Either:
+
+   ```sh
+   mkdir -p /tmp/extdemo
+   cp mylang.lua /tmp/extdemo/
+   ./src/stupidtools --ext-dir /tmp/extdemo
+   ```
+
+   or:
+
+   ```sh
+   STUPIDTOOLS_EXT=/tmp/extdemo ./src/stupidtools
+   ```
+
+   or install it to `$XDG_DATA_HOME/stupidtools/ext/` (default user dir).
+
+3. **Check the load line.** You should see your module named with its
+   actual registrations:
+
+   ```
+   loaded extension: /tmp/extdemo/mylang.lua — checks: 1 (mylang_compiler_flag) languages: 1 (mylang)
+   ```
+
+   A malformed module aborts discovery with `extension load failed:
+   <path>: <file>:<line>: <message>` — fix and rerun.
+
+4. **Reference the new check kind from a build file.** Once a module has
+   registered `mylang_compiler_flag`, a `feature` block in the KDL build
+   file can name that kind like any builtin check kind. (Full fixture-
+   driven resolution lands with the buildfile pipeline; discovery +
+   registration is what this version proves.)
+
+That is the whole contract: **discover → sandbox → register → reference.**
+Languages are data to core, and the builtin C/C++ modules are just the
+first extensions.

examples/ext_fortran.lua

@@ -0,0 +1,103 @@
+-- ext_fortran.lua -- an example third-party language extension.
+--
+-- WHAT THIS MODULE DOES
+--
+-- Fortran is NOT built into stupidtools: the builtin modules are only the
+-- C/C++ language pair (src/ext/lang_c.c / src/ext/lang_cpp.c). This file
+-- shows how a third party adds another language -- and a language-specific
+-- compiler-flag check -- without touching core or recompiling the binary.
+--
+-- HOW DISCOVERY LOADS IT
+--
+-- Any regular file whose name ends in ".lua" is discovered (src/ext/
+-- discovery.h), from any of these sources, in this order:
+--
+--   1. each --ext-dir DIR command-line flag (repeatable);
+--   2. each directory in the colon-separated STUPIDTOOLS_EXT env var;
+--   3. the per-user directory: $XDG_DATA_HOME/stupidtools/ext, falling
+--      back to $HOME/.local/share/stupidtools/ext;
+--   4. the builtin directory ("builtin-ext", compile-time configured).
+--
+-- Each module is read into memory and run as ONE sandboxed Lua chunk with
+-- the full file path as its chunkname (so diagnostics name file AND line).
+-- Load order within a directory is bytewise-lexicographic, and a module
+-- that fails to load aborts discovery (fail-fast). Try it:
+--
+--     cp examples/ext_fortran.lua /tmp/extdemo/
+--     ./src/stupidtools --ext-dir /tmp/extdemo
+--
+--   or, equivalently:
+--
+--     STUPIDTOOLS_EXT=/tmp/extdemo ./src/stupidtools
+--
+-- Discovery prints one line per loaded module, built from the ACTUAL
+-- registrations the module performed:
+--
+--     loaded extension: /tmp/extdemo/ext_fortran.lua - checks: 1
+--     (fortran_compiler_flag) languages: 1 (fortran)
+--
+-- THE SANDBOX CONTRACT (what a module CANNOT do)
+--
+-- The runtime is deliberately stripped (src/ext/lua.h). Extension code
+-- runs with:
+--   * os.execute / os.exit / os.remove / os.rename PRESENT but raising
+--     a "sandbox blocked:" error when called;
+--   * dofile / loadfile / require / package / io / debug / coroutine
+--     REMOVED (the globals are nil; their C libraries are not even
+--     linked);
+--   * only the base, table, string, a curated libm-free `math`, and the
+--     hand-built `os` tables available, plus the `st` registration table.
+--
+-- So a module can declare capabilities but cannot execute programs, touch
+-- the filesystem, or load other code. Violating the sandbox fails
+-- discovery with a clear error. Note the probe SOURCE strings below are
+-- inert text compiled by the host C toolchain, not executed here.
+--
+-- THE EXTENSION POINTS (the only API)
+--
+--   st.register_language(name [, spec-table])
+--       Registers a language. v1 registers the NAME only; the optional
+--       table is accepted (and must BE a table) for forward compatibility
+--       -- no language detection or toolchain is wired to it yet (see
+--       "v1 limitations" below).
+--
+--   st.register_check(name, { kind=..., source=..., link={...} })
+--       Registers a custom check. `kind` is the probe MODE
+--       ("compile" | "link" | "run"), `source` is the C snippet the probe
+--       compiles, and `link` (optional) is a list of extra argv elements
+--       for the link step. v1 custom checks are C snippets compiled with
+--       the detected C toolchain (see "v1 limitations" below).
+--
+-- Both names must be non-empty strings free of NUL bytes and must not
+-- collide with an already-registered name (builtin or earlier module).
+
+-- ---------------------------------------------------------------------------
+-- 1. Register the language itself. "fortran" is arbitrary from core's
+--    point of view -- any name works. The table argument is validated
+--    (must be a table) but its contents are NOT consumed in v1.
+-- ---------------------------------------------------------------------------
+st.register_language("fortran", { kind = "compile" })
+
+-- ---------------------------------------------------------------------------
+-- 2. Register a language-specific check. The name becomes a new check kind
+--    a build file can reference (like the builtin "header" kind is). The
+--    probe spec says: compile `source` with the C toolchain and require
+--    the compile (and, with `link`, the link) to succeed.
+--
+--    The source below is deliberately trivially-true C and libm-free: it
+--    links nothing, calls nothing, includes nothing -- a probe that must
+--    pass even on the smallest toolchain. A realistic flag probe would
+--    compile a C snippet with the flag in question and FAIL when the
+--    compiler rejects the flag. The `-lfortran` link argument is inert
+--    while the probe compiles (not links) but shows how extra link argv
+--    is carried through for "link"/"run" mode probes.
+-- ---------------------------------------------------------------------------
+st.register_check("fortran_compiler_flag", {
+    kind   = "compile",
+    source = "int main(void) { return 0; }",
+    link   = { "-lfortran" },
+})
+
+-- That is the whole module. Everything else -- detection, probing, the
+-- generated ./configure -- is core's job; an extension only declares
+-- what languages and checks exist.

scripts/build-static.sh

@@ -0,0 +1,301 @@
+#!/bin/sh
+#
+# scripts/build-static.sh - build the stupidtools binary as a FULLY STATIC
+# musl-linked executable and verify it with file(1) + ldd(1).
+#
+# Toolchain probe order (first probe that can actually PRODUCE a static
+# binary wins - `command -v` alone is not enough, the wrapper must work):
+#
+#   1. musl-gcc    -> CC=musl-gcc, LDFLAGS=-static   (musl-tools package)
+#   2. musl-clang  -> CC=musl-clang, LDFLAGS=-static
+#   3. clang --target=x86_64-linux-musl --sysroot="$MUSL_SYSROOT" -static
+#      -fuse-ld=lld  -> needs a musl sysroot; point the MUSL_SYSROOT env var
+#                       at it (e.g. /opt/x86_64-linux-musl from a musl.cc
+#                       cross toolchain, or /usr/lib/musl from musl-tools)
+#   4. apt-get install -y musl-tools (only if root or passwordless sudo)
+#   5. Download the musl.cc cross toolchain
+#        https://musl.cc/x86_64-linux-musl-cross.tgz
+#        (fallback mirror: https://more.musl.cc/x86_64-linux-musl-cross.tgz)
+#      into /tmp - NEVER into the repo - and use its
+#      bin/x86_64-linux-musl-gcc with -static.
+#
+# glibc -static is deliberately NOT a target: NSS and dlopen are broken in
+# fully-static glibc builds. musl is the only accepted static libc.
+# The DEFAULT build stays dynamic; static is an explicit opt-in via
+# `make static` (or running this script directly).
+#
+# CROSS-COMPILE VARIANT (aarch64) - documented, not wired as a flag:
+#
+#   Download https://musl.cc/aarch64-linux-musl-cross.tgz into /tmp, then:
+#     tar -C /tmp -xzf aarch64-linux-musl-cross.tgz
+#     cd <project-root> && make clean
+#     make CC=/tmp/aarch64-linux-musl-cross/bin/aarch64-linux-musl-gcc \
+#          CFLAGS=-O2 LDFLAGS=-static
+#   verify the result with:
+#     file src/stupidtools    # expect: "... statically linked ... ARM aarch64"
+#   (for a cross build, ldd must run under an emulator: use
+#    `qemu-aarch64 /path/to/ldd src/stupidtools` or file(1) alone as proof.)
+#
+# Env knobs (optional):
+#   MUSL_SYSROOT       - musl sysroot for the clang --sysroot route (route 3)
+#   STUPIDTOOLS_TOPDIR - project root override (default: this script's ../)
+#
+# Exit codes: 0 = static binary built AND verified; 1 = failure.
+
+msg() { printf '%s\n' "$*" >&2; }
+
+thisdir=$(CDPATH= cd "$(dirname "$0")" && pwd) || exit 1
+topdir=${STUPIDTOOLS_TOPDIR:-"$thisdir/.."}
+topdir=$(CDPATH= cd "$topdir" && pwd) || exit 1
+
+out=src/stupidtools   # relative to topdir (plan acceptance target)
+tmpdir=$(mktemp -d "${TMPDIR:-/tmp}/stupidtools-static.XXXXXX") || exit 1
+trap 'rm -rf "$tmpdir"' EXIT HUP INT TERM
+
+# ---------------------------------------------------------------------------
+# Verification gate - the ONLY definition of success. file(1) must report
+# "statically linked" and ldd(1) must report "not a dynamic executable".
+# Protects against stale dynamic binaries being mistaken for static ones.
+# ---------------------------------------------------------------------------
+verify_static() {
+    bin=$1
+    command -v file >/dev/null 2>&1 || { msg "ERROR: file(1) not available"; return 1; }
+    command -v ldd >/dev/null 2>&1 || { msg "ERROR: ldd(1) not available"; return 1; }
+    f=$(file "$bin") || { msg "ERROR: file(1) failed on $bin"; return 1; }
+    case "$f" in
+        *"statically linked"*) ;;
+        *)
+            msg "FAIL: $bin is NOT statically linked:"
+            msg "      $f"
+            return 1
+            ;;
+    esac
+    if l=$(ldd "$bin" 2>&1); then
+        # ldd exiting 0 means it resolved dynamic dependencies
+        msg "FAIL: $bin is dynamically linked (ldd resolved dependencies):"
+        msg "$l"
+        return 1
+    fi
+    case "$l" in
+        *"not a dynamic executable"*) ;;
+        *)
+            msg "FAIL: ldd(1) output for $bin was unexpected:"
+            msg "$l"
+            return 1
+            ;;
+    esac
+    return 0
+}
+
+# ---------------------------------------------------------------------------
+# probe_cc <cc> [flags...] - can this compiler produce a static binary?
+# ---------------------------------------------------------------------------
+probe_cc() {
+    cc=$1
+    shift
+    command -v file >/dev/null 2>&1 || return 1
+    printf 'int main(void){return 0;}\n' > "$tmpdir/probe.c" || return 1
+    if "$cc" "$@" "$tmpdir/probe.c" -o "$tmpdir/probe" 2>"$tmpdir/probe.log"; then
+        if file "$tmpdir/probe" 2>/dev/null | grep -q 'statically linked'; then
+            return 0
+        fi
+        msg "note: $cc linked a probe, but the result is not static; skipping"
+        return 1
+    fi
+    msg "note: $cc probe failed:"
+    sed 's/^/      /' "$tmpdir/probe.log" >&2
+    return 1
+}
+
+# ---------------------------------------------------------------------------
+# build_via_make <cc> - preferred path: reuse the automake tree (no source
+# list duplication). Requires ./configure to have been run (Makefile exists).
+# ---------------------------------------------------------------------------
+build_via_make() {
+    cc=$1
+    [ -f "$topdir/Makefile" ] || return 1
+    (
+        cd "$topdir" || exit 1
+        unset MAKEFLAGS MFLAGS
+        make clean >"$tmpdir/make-clean.log" 2>&1 || {
+            msg "ERROR: make clean failed:"
+            sed 's/^/      /' "$tmpdir/make-clean.log" >&2
+            exit 1
+        }
+        make CC="$cc" CFLAGS="-O2 $CC_CFLAGS" LDFLAGS="$CC_LDFLAGS" \
+            >"$tmpdir/make.log" 2>&1 || {
+            msg "ERROR: make CC=$cc failed:"
+            sed 's/^/      /' "$tmpdir/make.log" >&2
+            exit 1
+        }
+    ) || return 1
+    return 0
+}
+
+# ---------------------------------------------------------------------------
+# build_direct <cc> - fallback when the tree is not configured: compile the
+# source list straight out of src/Makefile.am (single source of truth).
+# ---------------------------------------------------------------------------
+build_direct() {
+    cc=$1
+    srcs=$(sed -n 's/^stupidtools_SOURCES *= *//p' "$topdir/src/Makefile.am") || {
+        msg "ERROR: cannot read the source list from src/Makefile.am"
+        return 1
+    }
+    [ -n "$srcs" ] || {
+        msg "ERROR: empty stupidtools_SOURCES in src/Makefile.am"
+        return 1
+    }
+    set --
+    for s in $srcs; do
+        set -- "$@" "$topdir/src/$s"
+    done
+    (
+        cd "$topdir" || exit 1
+        # shellcheck disable=SC2086  # CC_CFLAGS/CC_LDFLAGS are flag words
+        "$cc" $CC_CFLAGS -O2 -std=c23 -Wall -Wextra -Wpedantic \
+            -I"$topdir/src" -I"$topdir/include" \
+            $CC_LDFLAGS "$@" -o "$out" 2>"$tmpdir/direct.log" || {
+            msg "ERROR: direct compile with $cc failed:"
+            sed 's/^/      /' "$tmpdir/direct.log" >&2
+            exit 1
+        }
+    ) || return 1
+    return 0
+}
+
+# ---------------------------------------------------------------------------
+# try_apt_install - install musl-tools (route 4), non-interactively only.
+# ---------------------------------------------------------------------------
+try_apt_install() {
+    if ! command -v apt-get >/dev/null 2>&1; then
+        msg "note: apt-get not present (non-Debian host); skipping apt route"
+        return 1
+    fi
+    if [ "$(id -u)" -eq 0 ]; then
+        apt-get install -y musl-tools
+        return $?
+    fi
+    if command -v sudo >/dev/null 2>&1 && sudo -n true 2>/dev/null; then
+        sudo apt-get install -y musl-tools
+        return $?
+    fi
+    msg "note: no root and no passwordless sudo; cannot apt-get musl-tools"
+    return 1
+}
+
+# ---------------------------------------------------------------------------
+# try_muslcc_download - musl.cc cross toolchain into $tmpdir (route 5).
+# ---------------------------------------------------------------------------
+try_muslcc_download() {
+    tarball=x86_64-linux-musl-cross.tgz
+    if command -v curl >/dev/null 2>&1; then
+        msg "downloading $tarball from musl.cc (curl; ~100 MB, allow time)..."
+        if ! curl -fL --connect-timeout 15 --max-time 900 \
+                -o "$tmpdir/$tarball" "https://musl.cc/$tarball" 2>"$tmpdir/dl.log"; then
+            msg "note: primary mirror failed, trying more.musl.cc..."
+            curl -fL --connect-timeout 15 --max-time 900 \
+                -o "$tmpdir/$tarball" "https://more.musl.cc/$tarball" 2>"$tmpdir/dl.log" || {
+                msg "ERROR: musl.cc download failed:"
+                sed 's/^/      /' "$tmpdir/dl.log" >&2
+                return 1
+            }
+        fi
+    elif command -v wget >/dev/null 2>&1; then
+        msg "downloading $tarball from musl.cc (wget; ~100 MB, allow time)..."
+        if ! wget -q --timeout=15 -O "$tmpdir/$tarball" \
+                "https://musl.cc/$tarball" 2>"$tmpdir/dl.log"; then
+            msg "note: primary mirror failed, trying more.musl.cc..."
+            wget -q --timeout=15 -O "$tmpdir/$tarball" \
+                "https://more.musl.cc/$tarball" 2>"$tmpdir/dl.log" || {
+                msg "ERROR: musl.cc download failed:"
+                sed 's/^/      /' "$tmpdir/dl.log" >&2
+                return 1
+            }
+        fi
+    else
+        msg "ERROR: neither curl nor wget available for the musl.cc route"
+        return 1
+    fi
+    size=$(wc -c < "$tmpdir/$tarball")
+    msg "downloaded $size bytes; extracting..."
+    tar -C "$tmpdir" -xzf "$tmpdir/$tarball" || {
+        msg "ERROR: tar extraction of $tarball failed"
+        return 1
+    }
+    dlcc=$tmpdir/x86_64-linux-musl-cross/bin/x86_64-linux-musl-gcc
+    [ -x "$dlcc" ] || { msg "ERROR: $dlcc missing after extraction"; return 1; }
+    if probe_cc "$dlcc" -static -O2; then
+        CC_STATIC=$dlcc
+        return 0
+    fi
+    msg "ERROR: downloaded gcc could not produce a static binary"
+    return 1
+}
+
+# ---------------------------------------------------------------------------
+# Route selection
+# ---------------------------------------------------------------------------
+CC_STATIC=
+CC_CFLAGS=
+CC_LDFLAGS=-static
+
+if command -v musl-gcc >/dev/null 2>&1 && probe_cc musl-gcc -static -O2; then
+    CC_STATIC=musl-gcc
+elif command -v musl-clang >/dev/null 2>&1 && probe_cc musl-clang -static -O2; then
+    CC_STATIC=musl-clang
+elif [ -n "${MUSL_SYSROOT:-}" ] && command -v clang >/dev/null 2>&1 \
+        && probe_cc clang --target=x86_64-linux-musl \
+            --sysroot="$MUSL_SYSROOT" -static -fuse-ld=lld; then
+    CC_STATIC=clang
+    CC_CFLAGS="--target=x86_64-linux-musl --sysroot=$MUSL_SYSROOT"
+    CC_LDFLAGS="$CC_CFLAGS -fuse-ld=lld -static"
+fi
+
+if [ -z "$CC_STATIC" ]; then
+    msg "no local musl toolchain found; trying apt-get (route 4)..."
+    if try_apt_install; then
+        if command -v musl-gcc >/dev/null 2>&1 && probe_cc musl-gcc -static -O2; then
+            CC_STATIC=musl-gcc
+        fi
+    fi
+fi
+
+if [ -z "$CC_STATIC" ]; then
+    msg "trying musl.cc cross toolchain (route 5)..."
+    try_muslcc_download
+fi
+
+if [ -z "$CC_STATIC" ]; then
+    msg "ERROR: no usable musl toolchain could be obtained."
+    msg "       Options: install musl-tools (Debian/Ubuntu: apt-get install"
+    msg "       musl-tools; Arch: pacman -S musl), download a musl.cc cross"
+    msg "       toolchain, or set MUSL_SYSROOT and use clang (route 3)."
+    exit 1
+fi
+
+msg "building static binary with $CC_STATIC ..."
+if ! build_via_make "$CC_STATIC"; then
+    msg "note: automake route unavailable or failed; trying direct compile"
+    build_direct "$CC_STATIC" || {
+        msg "restoring default dynamic build (best effort)..."
+        if [ -f "$topdir/Makefile" ]; then
+            (cd "$topdir" && unset MAKEFLAGS MFLAGS && make >/dev/null 2>&1) || true
+        fi
+        msg "ERROR: static build failed"
+        exit 1
+    }
+fi
+
+if ! verify_static "$topdir/$out"; then
+    msg "restoring default dynamic build (best effort)..."
+    if [ -f "$topdir/Makefile" ]; then
+        (cd "$topdir" && unset MAKEFLAGS MFLAGS && make >/dev/null 2>&1) || true
+    fi
+    exit 1
+fi
+
+msg "OK: $out is a fully static musl-linked binary."
+file "$topdir/$out" 2>/dev/null || true
+ldd "$topdir/$out" 2>&1 || true
+exit 0

src/Makefile.am

@@ -0,0 +1,36 @@
+# src/Makefile.am - build the stupidtools binary (C23, strict warnings).
+
+AM_CFLAGS = -std=c23 -Wall -Wextra -Wpedantic
+
+bin_PROGRAMS = stupidtools
+stupidtools_SOURCES = \
+	main.c cli.c \
+	error.c span.c \
+	ext/discovery.c ext/lua.c ext/abi.c ext/lang_c.c ext/lang_cpp.c ext/api.c \
+	kdl/lexer.c kdl/parser.c kdl/value.c kdl/schema.c \
+	detect/check_registry.c detect/checks.c detect/probe.c detect/resolve.c \
+	gen/sh_emit.c gen/configure.c gen/config.c gen/args.c \
+	../thirdparty/lua/lapi.c ../thirdparty/lua/lauxlib.c \
+	../thirdparty/lua/lbaselib.c ../thirdparty/lua/lcode.c \
+	../thirdparty/lua/lctype.c ../thirdparty/lua/ldebug.c \
+	../thirdparty/lua/ldo.c ../thirdparty/lua/ldump.c \
+	../thirdparty/lua/lfunc.c ../thirdparty/lua/lgc.c \
+	../thirdparty/lua/llex.c ../thirdparty/lua/lmem.c \
+	../thirdparty/lua/lobject.c ../thirdparty/lua/lopcodes.c \
+	../thirdparty/lua/lparser.c ../thirdparty/lua/lstate.c \
+	../thirdparty/lua/lstring.c ../thirdparty/lua/ltable.c \
+	../thirdparty/lua/ltm.c ../thirdparty/lua/lundump.c \
+	../thirdparty/lua/lvm.c ../thirdparty/lua/lzio.c \
+	../thirdparty/lua/lstrlib.c ../thirdparty/lua/ltablib.c
+
+# The vendored Lua subset above deliberately EXCLUDES linit.c,
+# lmathlib.c, loadlib.c, liolib.c, loslib.c, ldblib.c, lcorolib.c,
+# lutf8lib.c and the lua.c/luac.c mains -- see src/ext/lua.c's -lm note
+# (the runtime's curated math/os tables replace lmathlib/loslib, and
+# the six libm shims in lua.c keep the link free of -lm).
+noinst_HEADERS = cli.h error.h span.h \
+	ext/discovery.h ext/lua.h ext/abi.h ext/lang_c.h ext/lang_cpp.h \
+	ext/lang_common.h ext/api.h \
+	kdl/lexer.h kdl/ast.h kdl/value.h kdl/schema.h \
+	detect/check_registry.h detect/checks.h detect/probe.h detect/resolve.h \
+	gen/sh_emit.h gen/configure.h gen/config.h gen/args.h

src/cli.c

@@ -0,0 +1,146 @@
+/*
+ * cli.c - argument parsing for the stupidtools entrypoint.
+ *
+ * Manual parsing on purpose: the flag surface is tiny and fully under
+ * our control, so there is no need for getopt's permutation rules or
+ * its platform quirks. Unknown options are usage errors (exit 2) with
+ * the usage text on stderr; a missing buildfile is a runtime error
+ * (exit 1). -- terminates option parsing so a buildfile whose name
+ * starts with '-' stays addressable.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "cli.h"
+
+#include <string.h>
+
+static const char *
+program_name(const char *argv0)
+{
+	if (argv0 == NULL || argv0[0] == '\0') {
+		return "stupidtools";
+	}
+	return argv0;
+}
+
+static int
+is_option(const char *arg)
+{
+	return arg[0] == '-' && arg[1] != '\0' && strcmp(arg, "-") != 0;
+}
+
+void
+cli_print_usage(FILE *stream, const char *program)
+{
+	fprintf(stream,
+	    "Usage: %s [OPTIONS] <buildfile.kdl>\n"
+	    "\n"
+	    "Reads a KDL build file and emits a POSIX-sh ./configure script.\n"
+	    "\n"
+	    "Options:\n"
+	    "  -h, --help     show this help and exit\n"
+	    "  -V, --version  print version and exit\n"
+	    "  --ext-dir DIR  load extensions from DIR (repeatable; the\n"
+	    "                 STUPIDTOOLS_EXT environment variable, a\n"
+	    "                 colon-separated directory list, is honored too)\n"
+	    "\n"
+	    "Note: buildfile processing is not yet implemented.\n",
+	    program);
+}
+
+/* Take the next positional argument, reporting usage errors to stderr.
+ * Returns CLI_ACTION_ERROR (with usage printed) or CLI_ACTION_RUN. */
+static enum cli_action
+take_positional(const char *arg, struct cli_opts *opts)
+{
+	if (opts->buildfile != NULL) {
+		fprintf(stderr, "%s: unexpected extra argument '%s'\n",
+		    opts->program, arg);
+		cli_print_usage(stderr, opts->program);
+		return CLI_ACTION_ERROR;
+	}
+	opts->buildfile = arg;
+	return CLI_ACTION_RUN;
+}
+
+enum cli_action
+cli_parse(int argc, char **argv, struct cli_opts *opts)
+{
+	enum cli_action action;
+	int i;
+
+	opts->program = program_name(argc > 0 ? argv[0] : NULL);
+	opts->buildfile = NULL;
+	opts->ext_dir_count = 0;
+
+	for (i = 1; i < argc; i++) {
+		const char *arg = argv[i];
+
+		if (!is_option(arg)) {
+			action = take_positional(arg, opts);
+			if (action != CLI_ACTION_RUN) {
+				return action;
+			}
+			continue;
+		}
+
+		if (strcmp(arg, "--") == 0) {
+			for (i++; i < argc; i++) {
+				action = take_positional(argv[i], opts);
+				if (action != CLI_ACTION_RUN) {
+					return action;
+				}
+			}
+			break;
+		}
+
+		if (strcmp(arg, "-h") == 0 || strcmp(arg, "--help") == 0) {
+			cli_print_usage(stdout, opts->program);
+			return CLI_ACTION_HELP;
+		}
+
+		if (strcmp(arg, "-V") == 0 || strcmp(arg, "--version") == 0) {
+			return CLI_ACTION_VERSION;
+		}
+
+		/* --ext-dir consumes the NEXT argument unconditionally
+		 * (getopt-style; even if it starts with '-'), is repeatable,
+		 * and rejects a missing/empty value and more than
+		 * CLI_MAX_EXT_DIRS repetitions as usage errors. The value is
+		 * borrowed from argv; a dir that does not exist is not an
+		 * error -- discovery skips missing dirs silently. */
+		if (strcmp(arg, "--ext-dir") == 0) {
+			if (i + 1 >= argc) {
+				fprintf(stderr, "%s: option '--ext-dir' "
+				    "requires an argument\n", opts->program);
+				cli_print_usage(stderr, opts->program);
+				return CLI_ACTION_ERROR;
+			}
+			i++;
+			if (argv[i][0] == '\0') {
+				fprintf(stderr, "%s: option '--ext-dir' "
+				    "requires a non-empty directory\n",
+				    opts->program);
+				cli_print_usage(stderr, opts->program);
+				return CLI_ACTION_ERROR;
+			}
+			if (opts->ext_dir_count >= CLI_MAX_EXT_DIRS) {
+				fprintf(stderr, "%s: too many --ext-dir options "
+				    "(max %d)\n", opts->program, CLI_MAX_EXT_DIRS);
+				cli_print_usage(stderr, opts->program);
+				return CLI_ACTION_ERROR;
+			}
+			opts->ext_dirs[opts->ext_dir_count++] = argv[i];
+			continue;
+		}
+
+		fprintf(stderr, "%s: unrecognized option '%s'\n",
+		    opts->program, arg);
+		cli_print_usage(stderr, opts->program);
+		return CLI_ACTION_ERROR;
+	}
+
+	return CLI_ACTION_RUN;
+}

src/cli.h

@@ -0,0 +1,44 @@
+/*
+ * cli.h - argument parsing for the stupidtools entrypoint.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef STUPIDTOOLS_CLI_H
+#define STUPIDTOOLS_CLI_H
+
+#include <stdio.h>
+
+/* Must match AC_INIT version in configure.ac (todo 1: 1.0.0). */
+#define STUPIDTOOLS_VERSION "1.0.0"
+
+#define CLI_EXIT_OK 0
+#define CLI_EXIT_RUNTIME 1
+#define CLI_EXIT_USAGE 2
+
+/* Sane cap on repeated --ext-dir flags (todo 20). */
+#define CLI_MAX_EXT_DIRS 32
+
+/* What the caller should do after parsing argv. */
+enum cli_action {
+	CLI_ACTION_RUN,     /* proceed with the parsed buildfile (todo 16+) */
+	CLI_ACTION_HELP,    /* usage already printed to stdout, exit 0 */
+	CLI_ACTION_VERSION, /* caller prints the version line, exit 0 */
+	CLI_ACTION_ERROR    /* error + usage already printed to stderr, exit 2 */
+};
+
+struct cli_opts {
+	const char *program;   /* argv[0] as given (or a default) */
+	const char *buildfile; /* single positional buildfile, NULL if none */
+	/* --ext-dir values, in the order given; the pointers are borrowed
+	 * from argv. STUPIDTOOLS_EXT is NOT merged here -- discovery reads
+	 * the environment itself and appends those dirs after these. */
+	const char *ext_dirs[CLI_MAX_EXT_DIRS];
+	size_t ext_dir_count;
+};
+
+enum cli_action cli_parse(int argc, char **argv, struct cli_opts *opts);
+void cli_print_usage(FILE *stream, const char *program);
+
+#endif /* STUPIDTOOLS_CLI_H */

src/detect/check_registry.c

@@ -0,0 +1,251 @@
+/*
+ * check_registry.c - declarative feature-check kinds for stupidtools
+ * (todo 10).
+ *
+ * The 8 check kinds a `feature` node's children can carry, their DSL
+ * keyword spellings, and their argument/property shapes - as DATA (the
+ * st_check_shapes table), plus the node->kind mapping. See
+ * detect/check_registry.h for the semantics; this module deliberately
+ * does NOT generate probes (todo 11) and does NOT execute anything.
+ *
+ * Check node names may be any KDL string form (identifier, quoted,
+ * raw, multi-line): non-identifier names are interpreted through the
+ * value model (kdl/value.h) before comparison. A value-model failure on
+ * the name (bad escape etc.) is re-owned as a schema error, exactly
+ * like src/kdl/schema.c does.
+ *
+ * ERRORS AND SPANS
+ * ----------------
+ * st_check_kind_from_node() reports failures as owned ST_ERR_KDL_SCHEMA
+ * errors whose span is heap-allocated IN THE SAME BLOCK as the error
+ * struct (the parser.c pattern), so err->span stays valid until
+ * st_error_free() and is never dangling. The span points at the node's
+ * NAME token (its `file` pointer borrows the caller's source buffer -
+ * the same lifetime contract as the parser). The single span-less error
+ * is the defensive NULL-node case: no source position exists to point
+ * at.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "detect/check_registry.h"
+
+#include "error.h"
+#include "kdl/ast.h"
+#include "kdl/value.h"
+
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* ---- the shape table (the data contract for todos 11/16) ------------- */
+
+/* `library` and `pkg_config` carry an optional version constraint as two
+ * further positional args: the literal `version` keyword followed by the
+ * constraint string (see the header comment). */
+const struct st_check_shape st_check_shapes[ST_CHECK_KIND_COUNT] = {
+    { ST_CHECK_HEADER, "header", "header name", 1, 0 },
+    { ST_CHECK_FUNCTION, "function", "function name", 1, 0 },
+    { ST_CHECK_LIBRARY, "library", "library name (linked as -l<name>)",
+      1, 2 },
+    { ST_CHECK_TYPE, "type", "type name", 1, 0 },
+    { ST_CHECK_SIZEOF, "sizeof", "type name", 1, 0 },
+    { ST_CHECK_PROGRAM, "program", "program name (checked via "
+      "command -v)", 1, 0 },
+    { ST_CHECK_COMPILER_FLAG, "compiler_flag", "compiler flag", 1, 0 },
+    { ST_CHECK_PKG_CONFIG, "pkg_config", "pkg-config package name", 1,
+      2 },
+};
+
+/* ---- owned errors ----------------------------------------------------- */
+
+/* Build an owned ST_ERR_KDL_SCHEMA error whose span lives in the same
+ * allocation as the error struct (aligned right after it). Returns NULL
+ * only on allocation failure. */
+static struct st_error *
+err_at_owned(struct st_span sp, const char *msg)
+{
+    const size_t align = _Alignof(struct st_span);
+    const size_t esize =
+        (sizeof(struct st_error) + align - 1) & ~(align - 1);
+    struct st_error *e;
+    struct st_span *spc;
+    size_t mlen;
+
+    if (msg == NULL) {
+        msg = "";
+    }
+    e = malloc(esize + sizeof(struct st_span));
+    if (e == NULL) {
+        return NULL;
+    }
+    mlen = strlen(msg);
+    e->message = malloc(mlen + 1);
+    if (e->message == NULL) {
+        free(e);
+        return NULL;
+    }
+    memcpy(e->message, msg, mlen + 1);
+    e->category = ST_ERR_KDL_SCHEMA;
+    spc = (struct st_span *)((unsigned char *)e + esize);
+    *spc = sp;
+    e->span = spc;
+    return e;
+}
+
+/* Re-own a value-model (ST_ERR_KDL_PARSE) error as a schema error: copy
+ * the message and the span VALUE into a fresh block. The caller frees
+ * the original error. */
+static struct st_error *
+schema_err_from(const struct st_error *e)
+{
+    struct st_span sp;
+
+    if (e->span != NULL) {
+        sp = *e->span;
+    } else {
+        sp = (struct st_span){ NULL, 0, 0 };
+    }
+    return err_at_owned(sp, e->message != NULL ? e->message : "");
+}
+
+/* ---- name matching ---------------------------------------------------- */
+
+/* Compare a node name token against a literal, accepting every string
+ * form (identifiers compared directly; other forms via the value
+ * model). Returns NULL and sets *out on success, or an owned schema
+ * error when the name is a string the value model cannot interpret. */
+static struct st_error *
+ref_equals(const struct st_kdl_token_ref *name, const char *s, bool *out)
+{
+    if (name->kind == ST_TOK_IDENT) {
+        *out = name->len == strlen(s) &&
+               memcmp(name->text, s, name->len) == 0;
+        return NULL;
+    }
+    {
+        struct st_kdl_value v;
+        struct st_error *e = st_kdl_value_from_token(name, &v);
+
+        if (e != NULL) {
+            struct st_error *r = schema_err_from(e);
+
+            st_error_free(e);
+            *out = false;
+            return r;
+        }
+        *out = v.kind == ST_KDL_VAL_STRING && strcmp(v.as.str, s) == 0;
+        st_kdl_value_free(&v);
+        return NULL;
+    }
+}
+
+/* Copy a node name token into a fixed buffer for MESSAGE text,
+ * truncating to fit (message-only; never fatal). */
+static void
+name_into(const struct st_kdl_token_ref *name, char *buf, size_t cap)
+{
+    if (cap == 0) {
+        return;
+    }
+    if (name->kind == ST_TOK_IDENT) {
+        size_t n = name->len < cap - 1 ? name->len : cap - 1;
+
+        memcpy(buf, name->text, n);
+        buf[n] = '\0';
+        return;
+    }
+    {
+        struct st_kdl_value v;
+        struct st_error *e = st_kdl_value_from_token(name, &v);
+
+        if (e == NULL && v.kind == ST_KDL_VAL_STRING) {
+            snprintf(buf, cap, "%s", v.as.str);
+        } else {
+            snprintf(buf, cap, "?");
+        }
+        st_error_free(e);
+        st_kdl_value_free(&v);
+    }
+}
+
+/* ---- public API ------------------------------------------------------- */
+
+enum st_check_kind
+st_check_kind_from_node(const struct st_kdl_node *node,
+                        struct st_error **err)
+{
+    char msg[192];
+    size_t i;
+
+    if (err != NULL) {
+        *err = NULL;
+    }
+    if (node == NULL) {
+        if (err != NULL) {
+            *err = st_error_kdl_schema("check node is NULL");
+        }
+        return ST_CHECK_KIND_COUNT;
+    }
+    if (node->name.len == 0) {
+        if (err != NULL) {
+            *err = err_at_owned(node->name.span,
+                                "check node has an empty name");
+        }
+        return ST_CHECK_KIND_COUNT;
+    }
+    for (i = 0; i < ST_CHECK_KIND_COUNT; i++) {
+        bool eq = false;
+        struct st_error *e = ref_equals(&node->name,
+                                        st_check_shapes[i].name, &eq);
+
+        if (e != NULL) {
+            if (err != NULL) {
+                *err = e;
+            } else {
+                st_error_free(e);
+            }
+            return ST_CHECK_KIND_COUNT;
+        }
+        if (eq) {
+            return st_check_shapes[i].kind;
+        }
+    }
+    if (err != NULL) {
+        char nm[65];
+
+        name_into(&node->name, nm, sizeof nm);
+        snprintf(msg, sizeof msg,
+            "unknown check kind '%s' (expected 'header', 'function', "
+            "'library', 'type', 'sizeof', 'program', 'compiler_flag', "
+            "or 'pkg_config')", nm);
+        *err = err_at_owned(node->name.span, msg);
+    }
+    return ST_CHECK_KIND_COUNT;
+}
+
+const char *
+st_check_kind_name(enum st_check_kind kind)
+{
+    if ((size_t)kind >= ST_CHECK_KIND_COUNT) {
+        return "?";
+    }
+    return st_check_shapes[kind].name;
+}
+
+const struct st_check_shape *
+st_check_kind_shape(enum st_check_kind kind)
+{
+    if ((size_t)kind >= ST_CHECK_KIND_COUNT) {
+        return NULL;
+    }
+    return &st_check_shapes[kind];
+}
+
+size_t
+st_check_kind_count(void)
+{
+    return ST_CHECK_KIND_COUNT;
+}

src/detect/check_registry.h

@@ -0,0 +1,140 @@
+/*
+ * check_registry.h - declarative feature-check kinds for stupidtools
+ * (todo 10).
+ *
+ * A `feature "name" { check* }` block's children are CHECK nodes. Each
+ * check node's NAME is one of eight fixed keywords - the check KINDS -
+ * and its FIRST (and only) positional argument is the TARGET the check
+ * is about:
+ *
+ *   check := <name> <arg> props*
+ *
+ * The eight kinds mirror GNU Autoconf's "Existing Tests" (manual §5) and
+ * pkg-config's PKG_CHECK_MODULES:
+ *
+ *   header         arg = header name    -> #include <arg> probe
+ *                                      e.g. header "pthread.h"
+ *   function       arg = function name  -> link probe for the symbol
+ *                                      e.g. function "strdup"
+ *   library        arg = library name   -> -l<arg> link probe
+ *                                      e.g. library "pthread"
+ *   type           arg = type name      -> compile probe for the type
+ *                                      e.g. type "size_t"
+ *   sizeof         arg = type name      -> sizeof(<arg>) probe
+ *                                      e.g. sizeof "long"
+ *   program        arg = program name   -> command -v <arg> probe
+ *                                      e.g. program "pkg-config"
+ *   compiler_flag  arg = flag           -> compile probe with <arg> added
+ *                                      e.g. compiler_flag "-fsanitize=address"
+ *   pkg_config     arg = package name   -> pkg-config --cflags --libs <arg>
+ *                                      e.g. pkg_config "openssl"
+ *
+ * WHAT THIS TODO OWNS
+ * -------------------
+ * Only the DECLARATIVE SHAPE: the kind enumeration, the kind<->keyword
+ * mapping, and per-kind argument/property shape as DATA (the table
+ * below). It deliberately does NOT implement probe generation (todo 11)
+ * or probe execution/caching (todo 12). src/kdl/schema.c consumes the
+ * mapping + table to enforce the DSL (see its todo-10 HOOK); todos 11
+ * and 16 consume the same table to generate probes and substitute
+ * results - THIS HEADER IS THE CONTRACT for them.
+ *
+ * OPTIONAL `version` CONSTRAINT (library and pkg_config)
+ * ------------------------------------------------------
+ * `library` and `pkg_config` may carry an optional version constraint,
+ * spelled EXACTLY like the project node's version (pinned by todo 9):
+ * the literal keyword `version` followed by a constraint string, as two
+ * further positional arguments:
+ *
+ *     library "curl" version ">=7.0"
+ *     pkg_config "openssl" version ">=1.1"
+ *
+ * The constraint is "<op><version>": <op> one of >= <= = > <, <version>
+ * a dotted numeric version. Todo 10 pins only the SHAPE (the keyword +
+ * a non-empty unannotated string); the OPERATOR SEMANTICS are
+ * interpreted by todo 11 (probe generation) and todo 16 (result
+ * substitution). The spelling is an argument pair, not a KDL property,
+ * because this parser classifies `version "..."` as two positional
+ * arguments - the same reason the project node spells it that way. The
+ * property form `version="..."` is NOT part of the DSL and is rejected
+ * (see PROPERTIES below).
+ *
+ * PROPERTIES
+ * ----------
+ * No check kind accepts properties in this todo (the grammar's `props*`
+ * is always empty for now); the schema validator rejects them with a
+ * spanned error. The shape table carries no props column for the same
+ * reason - todos 11/16 derive everything from the argument counts.
+ *
+ * ERRORS
+ * ------
+ * st_check_kind_from_node() reports unknown/empty check names as owned
+ * ST_ERR_KDL_SCHEMA errors whose span is heap-allocated IN THE SAME
+ * BLOCK as the error (the parser.c pattern), so err->span stays valid
+ * until st_error_free(err). The span points at the node's name token.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef ST_DETECT_CHECK_REGISTRY_H
+#define ST_DETECT_CHECK_REGISTRY_H
+
+#include <stddef.h>
+
+struct st_error;
+struct st_kdl_node;
+
+/* The eight declarative check kinds, in canonical order. */
+enum st_check_kind {
+    ST_CHECK_HEADER = 0,        /* header "pthread.h" */
+    ST_CHECK_FUNCTION,          /* function "strdup" */
+    ST_CHECK_LIBRARY,           /* library "pthread" -> -lpthread */
+    ST_CHECK_TYPE,              /* type "size_t" */
+    ST_CHECK_SIZEOF,            /* sizeof "long" */
+    ST_CHECK_PROGRAM,           /* program "pkg-config" -> command -v */
+    ST_CHECK_COMPILER_FLAG,     /* compiler_flag "-fsanitize=address" */
+    ST_CHECK_PKG_CONFIG,        /* pkg_config "openssl" */
+    ST_CHECK_KIND_COUNT,        /* sentinel: number of real kinds above */
+};
+
+/* The DSL shape of one check kind, as DATA (consumed by the schema
+ * validator and by todos 11/16). */
+struct st_check_shape {
+    enum st_check_kind kind;    /* the kind this row describes */
+    const char *name;           /* DSL keyword spelling, e.g. "header" */
+    const char *arg_meaning;    /* what the required argument names, e.g.
+                                   "header name" */
+    size_t required_args;       /* positional args the node MUST carry */
+    size_t optional_args;       /* further positional args tolerated; 2
+                                   for library/pkg_config = the literal
+                                   `version` keyword followed by the
+                                   version constraint string (see the
+                                   header comment); 0 elsewhere */
+};
+
+/* The registry table: one row per kind, indexed by the ST_CHECK_*
+ * values (st_check_shapes[k].kind == k). */
+extern const struct st_check_shape st_check_shapes[ST_CHECK_KIND_COUNT];
+
+/* Map a feature's check child node to its kind by the node NAME. The
+ * name may be any KDL string form (bare identifier or quoted). Returns
+ * the kind and leaves *err untouched on success. On failure returns
+ * ST_CHECK_KIND_COUNT and sets *err to an owned ST_ERR_KDL_SCHEMA error
+ * whose span points at the node's name: an unknown keyword, an empty
+ * name, or (defensively) a NULL node. */
+enum st_check_kind st_check_kind_from_node(const struct st_kdl_node *node,
+                                           struct st_error **err);
+
+/* Stable DSL keyword for a kind (e.g. "header"). Kinds outside the
+ * table yield "?" rather than indexing out of range. */
+const char *st_check_kind_name(enum st_check_kind kind);
+
+/* The shape-table row for a kind, or NULL when `kind` is not a real
+ * kind. */
+const struct st_check_shape *st_check_kind_shape(enum st_check_kind kind);
+
+/* Number of real kinds (ST_CHECK_KIND_COUNT). */
+size_t st_check_kind_count(void);
+
+#endif /* ST_DETECT_CHECK_REGISTRY_H */

src/detect/checks.c

@@ -0,0 +1,769 @@
+/*
+ * checks.c - probe-source specs for the 8 check kinds (todo 11).
+ *
+ * Builds a `struct st_check_probe` for a schema-validated CHECK node, per
+ * the per-kind table documented in detect/checks.h. This module builds
+ * SPECS ONLY: it does not execute probes (todo 12) and does not emit shell
+ * text (todo 16). See the header for the struct contract and ownership.
+ *
+ * DESIGN NOTES (the decisions that are NOT obvious from the header):
+ *
+ *   - FUNCTION probes carry `-fno-builtin` in extra_args. GCC treats
+ *     ~1000 names (strdup, printf, malloc, ...) as builtins and, with
+ *     `-Wbuiltin-declaration-mismatch` (on by default), warns on ANY
+ *     declaration whose signature differs from the builtin's — and there
+ *     is no single generic signature compatible with every builtin. A
+ *     generic `extern void NAME(void); ... NAME();` is therefore wrapped
+ *     in `-fno-builtin` so the link probe resolves the REAL library
+ *     symbol (also preventing builtin inlining from giving a false
+ *     positive). The function is declared `void (void)` and CALLED; the C
+ *     ABI does not name-mangle, so linking resolves the symbol NAME
+ *     regardless of its true signature — the probe only checks symbol
+ *     presence and never runs the function.
+ *
+ *   - LIBRARY probes link a trivial `int main(void){return 0;}` against
+ *     `-l<name>`. The DSL carries only the library name (no function, as
+ *     AC_CHECK_LIB requires), so "present and linkable" is the honest
+ *     v1 meaning: the link fails if `-l<name>` cannot be found or linked.
+ *
+ *   - VERSION constraints (`library`/`pkg_config` carry an optional
+ *     `version "<op><version>"` pair) are PARSED here (`<op>` ∈
+ *     >= <= = > <; `<version>` dotted-numeric) and the raw string is
+ *     recorded in probe->version_constraint. v1 enforcement:
+ *       * library: the probe is the plain `-l` link probe UNCHANGED; the
+ *         constraint is recorded for todo 16 to enforce via pkg-config
+ *         (or a library symbol check) when available.
+ *       * pkg_config: the op maps to a pkg-config version flag —
+ *         `>=` → `--atleast-version=`, `<=` → `--max-version=`,
+ *         `=` → `--exact-version=` — added before `--cflags --libs`.
+ *         Strict `>` and `<` have no pkg-config flag: they are recorded
+ *         in version_constraint only (todo 16 may reject or handle them).
+ *
+ *   - HEADER names are embedded as `#include <NAME>` when the name is
+ *     "plain" (only [A-Za-z0-9_./+-]); otherwise as `#include "..."` with
+ *     `"` and `\` C-escaped, so a hostile name (`"; rm -rf /`) stays a
+ *     literal string and cannot break out of the directive. Any control
+ *     byte (newline/NUL/...) in a header/function/type name is rejected.
+ *
+ *   - TYPE and SIZEOF names are embedded verbatim in `sizeof(...)`; only
+ *     control bytes are rejected (a `unsigned long`-style multi-token
+ *     type is legitimate, and a bogus type fails the compile probe
+ *     naturally). v1 does NOT add an AC_INCLUDES_DEFAULT-style header
+ *     list, so `type "size_t"` tests only types visible without includes.
+ *
+ * ERRORS AND SPANS
+ * ----------------
+ * Failures are owned ST_ERR_KDL_SCHEMA errors with the span heap-allocated
+ * IN THE SAME BLOCK as the error (the parser.c pattern), at the offending
+ * token. See checks.h.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "detect/checks.h"
+
+#include "detect/check_registry.h"
+#include "error.h"
+#include "kdl/ast.h"
+#include "kdl/value.h"
+
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* ---- owned errors ----------------------------------------------------- */
+
+/* Build an owned ST_ERR_KDL_SCHEMA error whose span lives in the same
+ * allocation as the error struct (aligned right after it). Returns NULL
+ * only on allocation failure. */
+static struct st_error *
+err_at_owned(struct st_span sp, const char *msg)
+{
+    const size_t align = _Alignof(struct st_span);
+    const size_t esize =
+        (sizeof(struct st_error) + align - 1) & ~(align - 1);
+    struct st_error *e;
+    struct st_span *spc;
+    size_t mlen;
+
+    if (msg == NULL) {
+        msg = "";
+    }
+    e = malloc(esize + sizeof(struct st_span));
+    if (e == NULL) {
+        return NULL;
+    }
+    mlen = strlen(msg);
+    e->message = malloc(mlen + 1);
+    if (e->message == NULL) {
+        free(e);
+        return NULL;
+    }
+    memcpy(e->message, msg, mlen + 1);
+    e->category = ST_ERR_KDL_SCHEMA;
+    spc = (struct st_span *)((unsigned char *)e + esize);
+    *spc = sp;
+    e->span = spc;
+    return e;
+}
+
+/* Re-own a value-model (ST_ERR_KDL_PARSE) error as a schema error: copy
+ * the message and the span VALUE into a fresh block. The caller frees the
+ * original error. */
+static struct st_error *
+schema_err_from(const struct st_error *e)
+{
+    struct st_span sp;
+
+    if (e->span != NULL) {
+        sp = *e->span;
+    } else {
+        sp = (struct st_span){ NULL, 0, 0 };
+    }
+    return err_at_owned(sp, e->message != NULL ? e->message : "");
+}
+
+/* ---- small allocators -------------------------------------------------- */
+
+/* Duplicate a string without relying on POSIX strdup (which strict C23
+ * hides behind _POSIX_C_SOURCE). Returns NULL on OOM. */
+static char *
+xstrdup(const char *s)
+{
+    size_t n = strlen(s);
+    char *p = malloc(n + 1);
+
+    if (p != NULL) {
+        memcpy(p, s, n + 1);
+    }
+    return p;
+}
+
+/* vsnprintf-based string builder. Returns a malloc'd NUL-terminated string
+ * or NULL on OOM / formatting failure. */
+static char *
+strbuild(const char *fmt, ...)
+{
+    va_list ap;
+    va_list ap2;
+    int n;
+    char *out;
+
+    va_start(ap, fmt);
+    va_copy(ap2, ap);
+    n = vsnprintf(NULL, 0, fmt, ap);
+    va_end(ap);
+    if (n < 0) {
+        va_end(ap2);
+        return NULL;
+    }
+    out = malloc((size_t)n + 1);
+    if (out == NULL) {
+        va_end(ap2);
+        return NULL;
+    }
+    (void)vsnprintf(out, (size_t)n + 1, fmt, ap2);
+    va_end(ap2);
+    return out;
+}
+
+/* Free a NULL-terminated argv of heap strings (each element freed, then
+ * the array). NULL is a safe no-op. */
+static void
+argv_free(char **av)
+{
+    size_t i;
+
+    if (av == NULL) {
+        return;
+    }
+    for (i = 0; av[i] != NULL; i++) {
+        free(av[i]);
+    }
+    free(av);
+}
+
+/* ---- argument extraction ---------------------------------------------- */
+
+/* Interpret `tok` (with optional annotation) as the non-empty unannotated
+ * string a check slot requires; on success *out owns the string. `ctx`
+ * names the slot in messages, e.g. "check 'header' argument". */
+static struct st_error *
+require_string_arg(const struct st_kdl_token_ref *tok,
+                   const struct st_kdl_token_ref *ann,
+                   const char *ctx, char **out)
+{
+    struct st_kdl_value v;
+    struct st_error *e;
+    char msg[192];
+
+    *out = NULL;
+    e = st_kdl_value_from_token_annotated(tok, ann, &v);
+    if (e != NULL) {
+        struct st_error *r = schema_err_from(e);
+
+        st_error_free(e);
+        return r;
+    }
+    if (v.annotation != NULL) {
+        snprintf(msg, sizeof msg, "%s must not carry a type annotation", ctx);
+        e = err_at_owned(tok->span, msg);
+        st_kdl_value_free(&v);
+        return e;
+    }
+    if (v.kind != ST_KDL_VAL_STRING) {
+        snprintf(msg, sizeof msg, "%s must be a non-empty string (got %s)",
+                 ctx, st_kdl_value_kind_name(v.kind));
+        e = err_at_owned(tok->span, msg);
+        st_kdl_value_free(&v);
+        return e;
+    }
+    if (v.as.str[0] == '\0') {
+        snprintf(msg, sizeof msg, "%s must be a non-empty string", ctx);
+        e = err_at_owned(tok->span, msg);
+        st_kdl_value_free(&v);
+        return e;
+    }
+    *out = v.as.str;
+    v.as.str = NULL;
+    st_kdl_value_free(&v); /* frees the annotation only */
+    return NULL;
+}
+
+/* ---- token safety checks (C-embedding boundaries) --------------------- */
+
+/* True when `s` contains a control byte (including NUL); these cannot
+ * appear in any C source token we embed verbatim. */
+static bool
+has_control_byte(const char *s)
+{
+    const unsigned char *p = (const unsigned char *)s;
+
+    for (; *p != '\0'; p++) {
+        if (*p < 0x20u || *p == 0x7fu) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/* True when `s` is a plain header name (only [A-Za-z0-9_./+-]). */
+static bool
+is_plain_header_name(const char *s)
+{
+    const unsigned char *p = (const unsigned char *)s;
+
+    if (*p == '\0') {
+        return false;
+    }
+    for (; *p != '\0'; p++) {
+        if (!((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') ||
+              (*p >= '0' && *p <= '9') || *p == '_' || *p == '.' ||
+              *p == '/' || *p == '+' || *p == '-')) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/* True when `s` is a valid C identifier (letter/underscore, then letters,
+ * digits, underscores). */
+static bool
+is_c_identifier(const char *s)
+{
+    const unsigned char *p = (const unsigned char *)s;
+
+    if (!((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') ||
+          *p == '_')) {
+        return false;
+    }
+    for (p++; *p != '\0'; p++) {
+        if (!((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') ||
+              (*p >= '0' && *p <= '9') || *p == '_')) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/* Build the include target for a header name: `<name>` for plain names,
+ * `"..."` (with `"` and `\` C-escaped) otherwise. Returns a malloc'd
+ * string, or NULL with *err set when the name carries a control byte. */
+static char *
+header_ref(const char *name, struct st_error **err)
+{
+    if (err != NULL) {
+        *err = NULL;
+    }
+    if (has_control_byte(name)) {
+        char msg[192];
+
+        snprintf(msg, sizeof msg,
+            "check 'header': header name contains a control character");
+        if (err != NULL) {
+            *err = st_error_kdl_schema(msg);
+        }
+        return NULL;
+    }
+    if (is_plain_header_name(name)) {
+        return strbuild("<%s>", name);
+    }
+    {
+        /* escape `\` and `"` for the quoted include form */
+        size_t i;
+        size_t cap = strlen(name) * 2 + 3; /* 2x for worst-case escapes + "" NUL */
+        char *out = malloc(cap);
+        size_t n = 0;
+
+        if (out == NULL) {
+            return NULL;
+        }
+        out[n++] = '"';
+        for (i = 0; name[i] != '\0'; i++) {
+            if (name[i] == '\\' || name[i] == '"') {
+                out[n++] = '\\';
+            }
+            out[n++] = name[i];
+        }
+        out[n++] = '"';
+        out[n] = '\0';
+        return out;
+    }
+}
+
+/* ---- version constraint parsing --------------------------------------- */
+
+/* Parse "<op><version>". On success returns 0 and sets *ver (a pointer
+ * into `s`, NUL-terminated because `s` is). The version part must be
+ * non-empty dotted-numeric (digits and '.', at least one digit). Returns
+ * -1 otherwise. */
+static int
+parse_constraint(const char *s, const char **ver)
+{
+    size_t ol = 0;
+    const char *v;
+    size_t i;
+    size_t ndigits = 0;
+
+    if (s[0] == '>' && s[1] == '=') {
+        ol = 2;
+    } else if (s[0] == '<' && s[1] == '=') {
+        ol = 2;
+    } else if (s[0] == '>' || s[0] == '<' || s[0] == '=') {
+        ol = 1;
+    } else {
+        return -1;
+    }
+    v = s + ol;
+    if (v[0] == '\0') {
+        return -1;
+    }
+    for (i = 0; v[i] != '\0'; i++) {
+        if (v[i] >= '0' && v[i] <= '9') {
+            ndigits++;
+        } else if (v[i] != '.') {
+            return -1;
+        }
+    }
+    if (ndigits == 0) {
+        return -1;
+    }
+    *ver = v;
+    return 0;
+}
+
+/* ---- per-kind source builders ----------------------------------------- */
+
+/* The trivial main shared by library and compiler_flag probes. */
+static char *
+trivial_main_source(void)
+{
+    return xstrdup(
+        "int main(void)\n"
+        "{\n"
+        "    return 0;\n"
+        "}\n");
+}
+
+/* ---- public API ------------------------------------------------------- */
+
+struct st_error *
+st_check_probe_build(enum st_check_kind kind, const struct st_kdl_node *node,
+                     struct st_check_probe *out)
+{
+    struct st_check_probe tmp = { ST_PROBE_PREPROCESS, NULL, NULL, NULL,
+                                  NULL };
+    const struct st_check_shape *shape;
+    struct st_error *err = NULL;
+    char *arg = NULL;
+    char *constraint = NULL; /* raw "<op><version>" for library/pkg_config */
+    const char *con_ver = NULL; /* parsed version pointer into `constraint` */
+    char ctx[96];
+
+    if (out != NULL) {
+        *out = (struct st_check_probe){ ST_PROBE_PREPROCESS, NULL, NULL, NULL,
+                                        NULL };
+    }
+    if ((size_t)kind >= ST_CHECK_KIND_COUNT) {
+        return st_error_kdl_schema(
+            "st_check_probe_build: unknown check kind");
+    }
+    if (node == NULL) {
+        return st_error_kdl_schema("check node is NULL");
+    }
+
+    shape = &st_check_shapes[kind];
+
+    /* the target argument */
+    if (node->args == NULL) {
+        char msg[192];
+
+        snprintf(msg, sizeof msg,
+            "check '%s' requires an argument (the %s)", shape->name,
+            shape->arg_meaning);
+        err = err_at_owned(node->name.span, msg);
+        goto done;
+    }
+    snprintf(ctx, sizeof ctx, "check '%s' argument", shape->name);
+    err = require_string_arg(&node->args->value, node->args->annotation, ctx,
+                             &arg);
+    if (err != NULL) {
+        goto done;
+    }
+
+    /* the optional `version` keyword + constraint pair (library/pkg_config) */
+    if (shape->optional_args == 2 && node->args->next != NULL) {
+        const struct st_kdl_arg *vk = node->args->next;
+        char msg[192];
+
+        if (vk->annotation != NULL ||
+            !(vk->value.kind == ST_TOK_IDENT && vk->value.len == 7 &&
+              memcmp(vk->value.text, "version", 7) == 0)) {
+            snprintf(msg, sizeof msg,
+                "check '%s': expected the keyword 'version' as the second "
+                "argument", shape->name);
+            err = err_at_owned(vk->value.span, msg);
+            goto done;
+        }
+        if (vk->next == NULL) {
+            snprintf(msg, sizeof msg,
+                "check '%s': 'version' requires the version constraint "
+                "argument", shape->name);
+            err = err_at_owned(vk->value.span, msg);
+            goto done;
+        }
+        snprintf(ctx, sizeof ctx, "check '%s' version", shape->name);
+        err = require_string_arg(&vk->next->value, vk->next->annotation, ctx,
+                                 &constraint);
+        if (err != NULL) {
+            goto done;
+        }
+    }
+
+    /* Validate "<op><version>" for BOTH kinds; `library` only records it
+     * (enforcement is todo 16), so this runs even where it is not applied. */
+    if (constraint != NULL) {
+        char msg[192];
+
+        if (parse_constraint(constraint, &con_ver) != 0) {
+            snprintf(msg, sizeof msg,
+                "check '%s': malformed version constraint '%s' "
+                "(expected '<op><version>', e.g. '>=1.0')", shape->name,
+                constraint);
+            err = err_at_owned(node->args->next->next->value.span, msg);
+            goto done;
+        }
+    }
+
+    switch (kind) {
+    case ST_CHECK_HEADER: {
+        char *ref = header_ref(arg, &err);
+
+        if (err != NULL) {
+            goto done;
+        }
+        if (ref == NULL) {
+            err = st_error_internal("out of memory building header probe");
+            goto done;
+        }
+        tmp.mode = ST_PROBE_COMPILE;
+        tmp.c_source = strbuild("#include %s\n", ref);
+        free(ref);
+        if (tmp.c_source == NULL) {
+            err = st_error_internal("out of memory building header probe");
+            goto done;
+        }
+        break;
+    }
+    case ST_CHECK_FUNCTION: {
+        char msg[192];
+
+        if (!is_c_identifier(arg)) {
+            snprintf(msg, sizeof msg,
+                "check 'function': function name '%s' is not a valid C "
+                "identifier", arg);
+            err = err_at_owned(node->args->value.span, msg);
+            goto done;
+        }
+        tmp.mode = ST_PROBE_LINK;
+        tmp.c_source = strbuild(
+            "extern void %s(void);\n"
+            "int main(void)\n"
+            "{\n"
+            "    %s();\n"
+            "    return 0;\n"
+            "}\n",
+            arg, arg);
+        if (tmp.c_source == NULL) {
+            err = st_error_internal("out of memory building function probe");
+            goto done;
+        }
+        tmp.extra_args = calloc(2, sizeof(char *));
+        if (tmp.extra_args == NULL) {
+            err = st_error_internal("out of memory building function probe");
+            goto done;
+        }
+        tmp.extra_args[0] = xstrdup("-fno-builtin");
+        if (tmp.extra_args[0] == NULL) {
+            err = st_error_internal("out of memory building function probe");
+            goto done;
+        }
+        break;
+    }
+    case ST_CHECK_LIBRARY: {
+        tmp.mode = ST_PROBE_LINK;
+        tmp.c_source = trivial_main_source();
+        if (tmp.c_source == NULL) {
+            err = st_error_internal("out of memory building library probe");
+            goto done;
+        }
+        tmp.extra_args = calloc(2, sizeof(char *));
+        if (tmp.extra_args == NULL) {
+            err = st_error_internal("out of memory building library probe");
+            goto done;
+        }
+        tmp.extra_args[0] = strbuild("-l%s", arg);
+        if (tmp.extra_args[0] == NULL) {
+            err = st_error_internal("out of memory building library probe");
+            goto done;
+        }
+        if (constraint != NULL) {
+            tmp.version_constraint = xstrdup(constraint);
+            if (tmp.version_constraint == NULL) {
+                err = st_error_internal("out of memory building library "
+                                        "probe");
+                goto done;
+            }
+        }
+        break;
+    }
+    case ST_CHECK_TYPE: {
+        char msg[192];
+
+        if (has_control_byte(arg)) {
+            snprintf(msg, sizeof msg,
+                "check 'type': type name contains a control character");
+            err = err_at_owned(node->args->value.span, msg);
+            goto done;
+        }
+        tmp.mode = ST_PROBE_COMPILE;
+        tmp.c_source = strbuild(
+            "_Static_assert(sizeof(%s) != 0, \"type must be a complete "
+            "object type\");\n",
+            arg);
+        if (tmp.c_source == NULL) {
+            err = st_error_internal("out of memory building type probe");
+            goto done;
+        }
+        break;
+    }
+    case ST_CHECK_SIZEOF: {
+        char msg[192];
+
+        if (has_control_byte(arg)) {
+            snprintf(msg, sizeof msg,
+                "check 'sizeof': type name contains a control character");
+            err = err_at_owned(node->args->value.span, msg);
+            goto done;
+        }
+        tmp.mode = ST_PROBE_RUN;
+        tmp.c_source = strbuild(
+            "#include <stdio.h>\n"
+            "_Static_assert(sizeof(%s) != 0, \"type must be a complete "
+            "object type\");\n"
+            "int main(void)\n"
+            "{\n"
+            "    printf(\"%%zu\\n\", sizeof(%s));\n"
+            "    return 0;\n"
+            "}\n",
+            arg, arg);
+        if (tmp.c_source == NULL) {
+            err = st_error_internal("out of memory building sizeof probe");
+            goto done;
+        }
+        break;
+    }
+    case ST_CHECK_PROGRAM: {
+        tmp.mode = ST_PROBE_COMMAND;
+        tmp.command = calloc(4, sizeof(char *));
+        if (tmp.command == NULL) {
+            err = st_error_internal("out of memory building program probe");
+            goto done;
+        }
+        tmp.command[0] = xstrdup("command");
+        tmp.command[1] = xstrdup("-v");
+        tmp.command[2] = xstrdup(arg);
+        if (tmp.command[0] == NULL || tmp.command[1] == NULL ||
+            tmp.command[2] == NULL) {
+            err = st_error_internal("out of memory building program probe");
+            goto done;
+        }
+        break;
+    }
+    case ST_CHECK_COMPILER_FLAG: {
+        tmp.mode = ST_PROBE_COMPILE;
+        tmp.c_source = trivial_main_source();
+        if (tmp.c_source == NULL) {
+            err = st_error_internal("out of memory building compiler_flag "
+                                    "probe");
+            goto done;
+        }
+        tmp.extra_args = calloc(2, sizeof(char *));
+        if (tmp.extra_args == NULL) {
+            err = st_error_internal("out of memory building compiler_flag "
+                                    "probe");
+            goto done;
+        }
+        tmp.extra_args[0] = xstrdup(arg);
+        if (tmp.extra_args[0] == NULL) {
+            err = st_error_internal("out of memory building compiler_flag "
+                                    "probe");
+            goto done;
+        }
+        break;
+    }
+    case ST_CHECK_PKG_CONFIG: {
+        const char *ver_flag = NULL;
+
+        if (constraint != NULL) {
+            if (constraint[0] == '>' && constraint[1] == '=') {
+                ver_flag = "--atleast-version=";
+            } else if (constraint[0] == '<' && constraint[1] == '=') {
+                ver_flag = "--max-version=";
+            } else if (constraint[0] == '=') {
+                ver_flag = "--exact-version=";
+            }
+            /* strict '>' and '<' have no pkg-config flag: recorded only */
+            tmp.version_constraint = xstrdup(constraint);
+            if (tmp.version_constraint == NULL) {
+                err = st_error_internal("out of memory building pkg_config "
+                                        "probe");
+                goto done;
+            }
+        }
+        tmp.mode = ST_PROBE_COMMAND;
+        if (ver_flag != NULL) {
+            char *flag = strbuild("%s%s", ver_flag, con_ver);
+
+            if (flag == NULL) {
+                err = st_error_internal("out of memory building pkg_config "
+                                        "probe");
+                goto done;
+            }
+            tmp.command = calloc(6, sizeof(char *));
+            if (tmp.command == NULL) {
+                free(flag);
+                err = st_error_internal("out of memory building pkg_config "
+                                        "probe");
+                goto done;
+            }
+            tmp.command[0] = xstrdup("pkg-config");
+            tmp.command[1] = flag;
+            tmp.command[2] = xstrdup("--cflags");
+            tmp.command[3] = xstrdup("--libs");
+            tmp.command[4] = xstrdup(arg);
+            if (tmp.command[0] == NULL || tmp.command[2] == NULL ||
+                tmp.command[3] == NULL || tmp.command[4] == NULL) {
+                err = st_error_internal("out of memory building pkg_config "
+                                        "probe");
+                goto done;
+            }
+        } else {
+            tmp.command = calloc(5, sizeof(char *));
+            if (tmp.command == NULL) {
+                err = st_error_internal("out of memory building pkg_config "
+                                        "probe");
+                goto done;
+            }
+            tmp.command[0] = xstrdup("pkg-config");
+            tmp.command[1] = xstrdup("--cflags");
+            tmp.command[2] = xstrdup("--libs");
+            tmp.command[3] = xstrdup(arg);
+            if (tmp.command[0] == NULL || tmp.command[1] == NULL ||
+                tmp.command[2] == NULL || tmp.command[3] == NULL) {
+                err = st_error_internal("out of memory building pkg_config "
+                                        "probe");
+                goto done;
+            }
+        }
+        break;
+    }
+    default:
+        err = st_error_kdl_schema("st_check_probe_build: unknown check kind");
+        goto done;
+    }
+
+done:
+    free(arg);
+    free(constraint);
+    if (err != NULL) {
+        st_check_probe_free(&tmp);
+        return err;
+    }
+    if (out != NULL) {
+        *out = tmp;
+    } else {
+        st_check_probe_free(&tmp);
+    }
+    return NULL;
+}
+
+void
+st_check_probe_free(struct st_check_probe *p)
+{
+    if (p == NULL) {
+        return;
+    }
+    free(p->c_source);
+    free(p->version_constraint);
+    argv_free(p->command);
+    argv_free(p->extra_args);
+    p->mode = ST_PROBE_PREPROCESS;
+    p->c_source = NULL;
+    p->version_constraint = NULL;
+    p->command = NULL;
+    p->extra_args = NULL;
+}
+
+const char *
+st_check_probe_mode_name(enum st_check_probe_mode mode)
+{
+    switch (mode) {
+    case ST_PROBE_PREPROCESS:
+        return "preprocess";
+    case ST_PROBE_COMPILE:
+        return "compile";
+    case ST_PROBE_LINK:
+        return "link";
+    case ST_PROBE_RUN:
+        return "run";
+    case ST_PROBE_COMMAND:
+        return "command";
+    default:
+        return "?";
+    }
+}

src/detect/checks.h

@@ -0,0 +1,131 @@
+/*
+ * checks.h - probe-source specs for the 8 check kinds (todo 11).
+ *
+ * Given a feature's CHECK node (already schema-validated by src/kdl/schema.c),
+ * this module builds the exact PROBE SPEC that todo 12 (probe code generator)
+ * turns into configure-time compile/link/run/command invocations and todo 16
+ * (configure assembly) substitutes the results of. It builds SPECS ONLY: it
+ * never executes a probe, never touches the filesystem beyond heap
+ * allocation, and never emits shell text.
+ *
+ * THE PROBE SPEC (the contract todo 12/16 consume)
+ * ------------------------------------------------
+ *
+ *     enum st_check_probe_mode {
+ *         ST_PROBE_PREPROCESS, // -E: header existence via the preprocessor
+ *         ST_PROBE_COMPILE,    // compile a C translation unit (-c)
+ *         ST_PROBE_LINK,       // compile + link a C program
+ *         ST_PROBE_RUN,        // compile + link + RUN, capture stdout
+ *         ST_PROBE_COMMAND,    // run an external command via execvp (argv)
+ *     };
+ *
+ *     struct st_check_probe {
+ *         enum st_check_probe_mode mode;
+ *         char *c_source;            // C snippet; NULL for COMMAND probes
+ *         char **command;            // argv (NULL-terminated); NULL unless
+ *                                    //   mode == ST_PROBE_COMMAND
+ *         char **extra_args;         // argv (NULL-terminated) of extra
+ *                                    //   compile/link flags (e.g. "-lpthread",
+ *                                    //   "-fsanitize=address",
+ *                                    //   "-fno-builtin"); NULL when empty
+ *         char *version_constraint;  // raw "<op><version>" string for
+ *                                    //   library/pkg_config; NULL when absent
+ *     };
+ *
+ *   - `command` and `extra_args` are exec-style argv arrays (char **, first
+ *     element is argv[0] for `command`, a flag for `extra_args`; both
+ *     NULL-terminated). The program/package name a COMMAND probe targets is
+ *     carried as a SINGLE argv element, never concatenated into a shell
+ *     string — todo 12/16 shell-quote it at emission (st_sh_quote) so
+ *     injection is structurally impossible here.
+ *   - `c_source` is a complete, self-contained C23 translation unit (or a
+ *     standalone declaration for compile-only probes) that compiles clean
+ *     under `-std=c23 -Wall -Wextra -Wpedantic`.
+ *
+ * PER-KIND SPEC TABLE
+ * -------------------
+ *   header "pthread.h"        COMPILE  `#include <pthread.h>` (angle form for
+ *                                       plain names; `"..."` escaped form for
+ *                                       names with spaces/quotes/metachars)
+ *   function "strdup"         LINK     `extern void strdup(void); ...`
+ *                                       + a call; extra_args = {"-fno-builtin"}
+ *   library "pthread"         LINK     trivial `int main(void){return 0;}`
+ *                                       + extra_args = {"-lpthread"}
+ *   type "size_t"             COMPILE  `_Static_assert(sizeof(size_t) != 0,...)`
+ *   sizeof "long"             RUN      `_Static_assert(...)` sentinel + a
+ *                                       printf of `sizeof(long)` (run path)
+ *   program "pkg-config"      COMMAND  argv {command, -v, pkg-config}
+ *   compiler_flag "-fsani..." COMPILE  trivial main + extra_args = {flag}
+ *   pkg_config "openssl"      COMMAND  argv {pkg-config, --cflags, --libs, pkg}
+ *
+ * OWNERSHIP
+ * ---------
+ * st_check_probe_build() writes a FULLY HEAP-OWNED probe into a caller
+ * provided struct; st_check_probe_free() releases it (NULL is a safe no-op).
+ * On error `out` is left zeroed and an owned st_error is returned.
+ *
+ * ERRORS
+ * ------
+ * Failures return an owned st_error of category ST_ERR_KDL_SCHEMA whose span
+ * is heap-allocated IN THE SAME BLOCK as the error (the parser.c pattern), at
+ * the offending token: a NULL node, a missing/non-string target argument, a
+ * malformed version constraint, a non-identifier function name, or a control
+ * character in an embedded C token. An out-of-range kind is the one span-less
+ * case (defensive; no source position exists). On allocation failure the
+ * error is a plain ST_ERR_INTERNAL with no span (and, as throughout this
+ * codebase, may itself be NULL under catastrophic OOM).
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef ST_DETECT_CHECKS_H
+#define ST_DETECT_CHECKS_H
+
+#include <stddef.h>
+
+#include "detect/check_registry.h" /* enum st_check_kind */
+
+struct st_error;
+struct st_kdl_node;
+
+/* The probe MODE: what todo 12 must do with the snippet to test the check.
+ * PREPROCESS is reserved for a future header fast-path; none of the 8 v1
+ * kinds emit it (header uses COMPILE). */
+enum st_check_probe_mode {
+    ST_PROBE_PREPROCESS = 0, /* -E the snippet (unused by v1 kinds) */
+    ST_PROBE_COMPILE,        /* compile the snippet (-c)              */
+    ST_PROBE_LINK,           /* compile + link the snippet            */
+    ST_PROBE_RUN,            /* compile + link + run, capture stdout  */
+    ST_PROBE_COMMAND,        /* exec the `command` argv               */
+};
+
+/* A built probe spec (see the header comment for the per-kind table). */
+struct st_check_probe {
+    enum st_check_probe_mode mode;
+    char *c_source;            /* heap C snippet; NULL for COMMAND probes */
+    char **command;            /* heap argv (NULL-terminated); NULL unless
+                                  mode == ST_PROBE_COMMAND */
+    char **extra_args;         /* heap argv (NULL-terminated) of extra
+                                  compile/link flags; NULL when empty */
+    char *version_constraint;  /* heap raw "<op><version>"; NULL when absent */
+};
+
+/* Build the probe spec for `kind` from a schema-validated CHECK node. The
+ * node's FIRST positional argument is the target; for library/pkg_config the
+ * optional `version` keyword + constraint pair is read too. On success
+ * returns NULL and fills `*out` (a fully heap-owned probe). On failure
+ * returns an owned error (see ERRORS) and leaves `*out` zeroed. */
+struct st_error *st_check_probe_build(enum st_check_kind kind,
+                                      const struct st_kdl_node *node,
+                                      struct st_check_probe *out);
+
+/* Release a probe spec produced by st_check_probe_build. NULL is a safe
+ * no-op; the probe is zeroed after freeing. */
+void st_check_probe_free(struct st_check_probe *p);
+
+/* Stable display name for a probe mode, e.g. "compile". Out-of-range modes
+ * yield "?" rather than indexing out of range. */
+const char *st_check_probe_mode_name(enum st_check_probe_mode mode);
+
+#endif /* ST_DETECT_CHECKS_H */

src/detect/probe.c

@@ -0,0 +1,382 @@
+/*
+ * probe.c - configure-time probe snippet generator (todo 12).
+ *
+ * Emits POSIX-sh that probes a check AT CONFIGURE TIME, inside the
+ * generated ./configure. This module is a pure code generator: it never
+ * runs a compiler, never writes probe sources, never executes anything. All
+ * context (CC, cross_compiling, compiler id, cache/log/tmp paths) is shell
+ * variables established by the configure preamble (todo 16); see probe.h
+ * for the full contract, the cache-key scheme, and the emitted shape.
+ *
+ * The two load-bearing safety decisions:
+ *   - The C source is embedded with `printf '%s' <st_sh_quote(c_source)> >
+ *     "$st_probe_src"` — a single-quoted literal (not a here-document), so
+ *     arbitrary bytes incl. newlines and quotes in the C source are inert.
+ *     st_sh_quote (todo 15) is the ONLY safe embedder; everything else here
+ *     is hand-written fixed shell text or identifier-validated names.
+ *   - checkname is validated as a POSIX identifier before interpolation,
+ *     because it lands in variable-NAME positions (have_<name>,
+ *     ac_cv_<name>_$st_cc_id, a temp filename) that cannot be quoted.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "detect/probe.h"
+
+#include "error.h"
+#include "gen/sh_emit.h"
+
+#include <stdbool.h>
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+/* ---- small helpers ----------------------------------------------------- */
+
+/* True when `s` is a valid POSIX shell identifier: letter/underscore, then
+ * letters/digits/underscores, non-empty. */
+static bool
+valid_ident(const char *s)
+{
+    const unsigned char *p;
+
+    if (s == NULL || *s == '\0') {
+        return false;
+    }
+    p = (const unsigned char *)s;
+    if (!((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') ||
+          *p == '_')) {
+        return false;
+    }
+    for (p++; *p != '\0'; p++) {
+        if (!((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') ||
+              (*p >= '0' && *p <= '9') || *p == '_')) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/* Write each argv element as a single-quoted literal, space-separated.
+ * Returns 0 on success. Returns -1 with *err set (ST_ERR_INTERNAL) when
+ * quoting fails (NUL byte / OOM); I/O errors are detected later via
+ * ferror(out) and are NOT reported here. */
+static int
+emit_argv_quoted(FILE *out, char *const *argv, struct st_error **err)
+{
+    size_t i;
+
+    for (i = 0; argv[i] != NULL; i++) {
+        char *q = st_sh_quote_ex(argv[i], err);
+
+        if (q == NULL) {
+            if (err != NULL && *err == NULL) {
+                *err = st_error_internal("out of memory quoting probe argv");
+            }
+            return -1;
+        }
+        if (i > 0) {
+            (void)fputc(' ', out);
+        }
+        (void)fputs(q, out);
+        free(q);
+    }
+    return 0;
+}
+
+/* Emit a COMMAND probe's argv as a shell command. All elements except the
+ * LAST are hardcoded literals owned by checks.c (the program name "command"
+ * / "pkg-config" plus fixed flags like "-v"/"--cflags"/"--libs"), so they
+ * are written verbatim; the LAST element is the user-supplied target
+ * (program/package name) and is single-quoted. Returns 0, or -1 with *err
+ * set when quoting fails; I/O errors are caught via ferror. */
+static int
+emit_command_argv(FILE *out, char *const *argv, struct st_error **err)
+{
+    size_t n = 0;
+    size_t i;
+
+    while (argv[n] != NULL) {
+        n++;
+    }
+    for (i = 0; i < n; i++) {
+        if (i > 0) {
+            (void)fputc(' ', out);
+        }
+        if (i + 1 == n) {
+            char *q = st_sh_quote_ex(argv[i], err);
+
+            if (q == NULL) {
+                if (err != NULL && *err == NULL) {
+                    *err = st_error_internal("out of memory quoting probe "
+                                             "argv");
+                }
+                return -1;
+            }
+            (void)fputs(q, out);
+            free(q);
+        } else {
+            (void)fputs(argv[i], out);
+        }
+    }
+    return 0;
+}
+
+/* ---- the cache boilerplate -------------------------------------------- */
+
+/* Emitted verbatim (POSIX-sh only). Uses st_sh_emit_str, so no format
+ * processing — the `%` in `printf '%s'` and `${var#*=}` stays literal. */
+static const char CACHE_FUNCS[] =
+    "# --- configure-time probe cache (config.cache) ----------------------\n"
+    "# Emitted by st_probe_emit_cache_functions (todo 12). The probe\n"
+    "# snippets read results via st_cache_get and record them via\n"
+    "# st_cache_set. Cache key: ac_cv_<checkname>_<compiler-id>.\n"
+    "\n"
+    ": \"${CFLAGS:=}\"\n"
+    ": \"${st_cc_id:=unknown}\"\n"
+    ": \"${cross_compiling:=}\"\n"
+    ": \"${config_cache:=./config.cache}\"\n"
+    ": \"${config_log:=./config.log}\"\n"
+    ": \"${st_tmpdir:=${TMPDIR:-/tmp}}\"\n"
+    "\n"
+    "# st_cache_get KEY: print the cached value (yes/no) and return 0, or\n"
+    "# return 1 when config.cache is absent or KEY is not recorded. The\n"
+    "# key is matched with grep -F (literal, no regex) anchored by its\n"
+    "# trailing '='; keys and values never contain '='.\n"
+    "st_cache_get() {\n"
+    "    st_cv_line=\n"
+    "    [ -f \"$config_cache\" ] || return 1\n"
+    "    st_cv_line=$(grep -F -- \"$1=\" \"$config_cache\" 2>/dev/null | tail -n 1)\n"
+    "    [ -n \"$st_cv_line\" ] || return 1\n"
+    "    printf '%s\\n' \"${st_cv_line#*=}\"\n"
+    "    return 0\n"
+    "}\n"
+    "\n"
+    "# st_cache_set KEY VALUE: record VALUE (yes/no) under KEY, replacing\n"
+    "# any earlier line for the same key. Creates config.cache when absent.\n"
+    "st_cache_set() {\n"
+    "    st_cv_tmp=\"$config_cache.tmp.$$\"\n"
+    "    if [ -f \"$config_cache\" ]; then\n"
+    "        grep -v -F -- \"$1=\" \"$config_cache\" > \"$st_cv_tmp\" 2>/dev/null\n"
+    "        mv -f \"$st_cv_tmp\" \"$config_cache\"\n"
+    "    fi\n"
+    "    printf '%s=%s\\n' \"$1\" \"$2\" >> \"$config_cache\"\n"
+    "    rm -f \"$st_cv_tmp\"\n"
+    "}\n"
+    "\n";
+
+struct st_error *
+st_probe_emit_cache_functions(FILE *out)
+{
+    if (out == NULL) {
+        return st_error_usage("st_probe_emit_cache_functions: NULL stream");
+    }
+    if (st_sh_emit_str(out, CACHE_FUNCS) < 0) {
+        return st_error_io("I/O error emitting cache boilerplate");
+    }
+    return NULL;
+}
+
+/* ---- the per-check snippet -------------------------------------------- */
+
+struct st_error *
+st_probe_emit_snippet(const char *checkname, const struct st_check_probe *probe,
+                      FILE *out)
+{
+    struct st_error *err = NULL;
+    const char *mode_name;
+    char *qsrc = NULL;
+    bool is_command;
+    bool is_run;
+
+    if (out == NULL || checkname == NULL || probe == NULL) {
+        return st_error_usage("st_probe_emit_snippet: NULL argument");
+    }
+    if (!valid_ident(checkname)) {
+        return st_error_usage("st_probe_emit_snippet: checkname must be a "
+                              "POSIX shell identifier");
+    }
+    if (probe->mode < ST_PROBE_PREPROCESS || probe->mode > ST_PROBE_COMMAND) {
+        return st_error_usage("st_probe_emit_snippet: unknown probe mode");
+    }
+    mode_name = st_check_probe_mode_name(probe->mode);
+    is_command = (probe->mode == ST_PROBE_COMMAND);
+    is_run = (probe->mode == ST_PROBE_RUN);
+
+    if (is_command) {
+        if (probe->command == NULL || probe->command[0] == NULL) {
+            return st_error_usage("st_probe_emit_snippet: COMMAND probe has "
+                                  "no command argv");
+        }
+    } else {
+        if (probe->c_source == NULL) {
+            return st_error_usage("st_probe_emit_snippet: probe has no C "
+                                  "source");
+        }
+        qsrc = st_sh_quote_ex(probe->c_source, &err);
+        if (err != NULL) {
+            return err;
+        }
+        if (qsrc == NULL) {
+            return st_error_internal("st_probe_emit_snippet: out of memory "
+                                     "quoting C source");
+        }
+    }
+
+    (void)fprintf(out, "# probe: %s check '%s'\n", mode_name, checkname);
+    (void)fprintf(out, "st_cv_key=ac_cv_%s_$st_cc_id\n", checkname);
+
+    if (is_run) {
+        /* cross-compile guard FIRST: skip, warn, mark, default "no", and do
+         * NOT read or write the cache (a cross default must never poison a
+         * native build's cache entry). */
+        (void)fprintf(out,
+            "if [ \"$cross_compiling\" = \"yes\" ]; then\n"
+            "    st_cross_%s=yes\n"
+            "    have_%s=no\n"
+            "    echo \"warning: skipping runtime check '%s' while "
+            "cross-compiling\" >&2\n"
+            "elif st_cv_val=$(st_cache_get \"$st_cv_key\"); then\n"
+            "    have_%s=$st_cv_val\n"
+            "else\n"
+            "    have_%s=no\n",
+            checkname, checkname, checkname, checkname, checkname);
+    } else {
+        (void)fprintf(out,
+            "if st_cv_val=$(st_cache_get \"$st_cv_key\"); then\n"
+            "    have_%s=$st_cv_val\n"
+            "else\n"
+            "    have_%s=no\n",
+            checkname, checkname);
+    }
+
+    /* ---- probe body -------------------------------------------------- */
+    if (is_command) {
+        (void)fputs("    if ", out);
+        if (emit_command_argv(out, probe->command, &err) < 0) {
+            free(qsrc);
+            return err;
+        }
+        (void)fprintf(out,
+            " >>\"$config_log\" 2>&1; then\n"
+            "        have_%s=yes\n"
+            "    fi\n",
+            checkname);
+    } else {
+        (void)fprintf(out,
+            "    st_probe_src=\"$st_tmpdir/st_probe_%s.$$.c\"\n"
+            "    printf '%%s' %s > \"$st_probe_src\"\n",
+            checkname, qsrc);
+        switch (probe->mode) {
+        case ST_PROBE_PREPROCESS:
+            (void)fputs("    if $CC $CFLAGS", out);
+            if (probe->extra_args != NULL) {
+                (void)fputc(' ', out);
+                if (emit_argv_quoted(out, probe->extra_args, &err) < 0) {
+                    free(qsrc);
+                    return err;
+                }
+            }
+            (void)fprintf(out,
+                " -E \"$st_probe_src\" >>\"$config_log\" 2>&1; then\n"
+                "        have_%s=yes\n"
+                "    fi\n"
+                "    rm -f \"$st_probe_src\"\n",
+                checkname);
+            break;
+        case ST_PROBE_COMPILE:
+            (void)fputs("    if $CC $CFLAGS", out);
+            if (probe->extra_args != NULL) {
+                (void)fputc(' ', out);
+                if (emit_argv_quoted(out, probe->extra_args, &err) < 0) {
+                    free(qsrc);
+                    return err;
+                }
+            }
+            (void)fprintf(out,
+                " -c \"$st_probe_src\" -o \"$st_probe_src.o\" "
+                ">>\"$config_log\" 2>&1; then\n"
+                "        have_%s=yes\n"
+                "    fi\n"
+                "    rm -f \"$st_probe_src\" \"$st_probe_src.o\"\n",
+                checkname);
+            break;
+        case ST_PROBE_LINK:
+            (void)fputs("    if $CC $CFLAGS", out);
+            if (probe->extra_args != NULL) {
+                (void)fputc(' ', out);
+                if (emit_argv_quoted(out, probe->extra_args, &err) < 0) {
+                    free(qsrc);
+                    return err;
+                }
+            }
+            (void)fprintf(out,
+                " \"$st_probe_src\" -o \"$st_probe_src.bin\" "
+                ">>\"$config_log\" 2>&1; then\n"
+                "        have_%s=yes\n"
+                "    fi\n"
+                "    rm -f \"$st_probe_src\" \"$st_probe_src.bin\"\n",
+                checkname);
+            break;
+        case ST_PROBE_RUN:
+            (void)fputs("    if $CC $CFLAGS", out);
+            if (probe->extra_args != NULL) {
+                (void)fputc(' ', out);
+                if (emit_argv_quoted(out, probe->extra_args, &err) < 0) {
+                    free(qsrc);
+                    return err;
+                }
+            }
+            (void)fprintf(out,
+                " \"$st_probe_src\" -o \"$st_probe_src.bin\" "
+                ">>\"$config_log\" 2>&1; then\n"
+                "        if \"$st_probe_src.bin\" >>\"$config_log\" 2>&1; "
+                "then\n"
+                "            have_%s=yes\n"
+                "        fi\n"
+                "    fi\n"
+                "    rm -f \"$st_probe_src\" \"$st_probe_src.bin\"\n",
+                checkname);
+            break;
+        default:
+            free(qsrc);
+            return st_error_usage("st_probe_emit_snippet: unknown probe mode");
+        }
+    }
+
+    /* ---- cache write + close ---------------------------------------- */
+    (void)fprintf(out, "    st_cache_set \"$st_cv_key\" \"$have_%s\"\n"
+                       "fi\n", checkname);
+
+    free(qsrc);
+    if (ferror(out)) {
+        return st_error_io("I/O error emitting probe snippet");
+    }
+    return NULL;
+}
+
+/* ---- a feature's list of checks --------------------------------------- */
+
+struct st_error *
+st_probe_emit_all(const struct st_probe_entry *entries, size_t count,
+                  FILE *out)
+{
+    size_t i;
+
+    if (count > 0 && entries == NULL) {
+        return st_error_usage("st_probe_emit_all: NULL entries");
+    }
+    for (i = 0; i < count; i++) {
+        struct st_error *err;
+
+        if (i > 0 && fputc('\n', out) == EOF) {
+            return st_error_io("I/O error emitting probe snippet");
+        }
+        err = st_probe_emit_snippet(entries[i].name, entries[i].probe, out);
+        if (err != NULL) {
+            return err;
+        }
+    }
+    return NULL;
+}

src/detect/probe.h

@@ -0,0 +1,163 @@
+/*
+ * probe.h - configure-time probe snippet generator (todo 12).
+ *
+ * MODEL (the thing to internalize before reading anything else): this
+ * module NEVER executes a probe. It is a pure CODE GENERATOR: given a
+ * check's probe spec (struct st_check_probe, todo 11), it EMITS a POSIX-sh
+ * snippet that, when it runs inside the generated ./configure at configure
+ * time, writes the probe's C source to a temp file, drives the detected
+ * toolchain ($CC -c / -o / run), captures the exit status, and records
+ * have_<checkname>=yes|no. The generator is therefore STATELESS — it takes
+ * no context object, because all probe context (compiler, flags,
+ * cross-compile flag, compiler id, cache/log/tmp paths) lives in the
+ * configure-time shell environment, not in the generator process.
+ *
+ * CONFIG.SHELL VARIABLE CONTRACT (todo 16's preamble MUST establish these;
+ * the boilerplate below emits conservative defaults):
+ *
+ *   CC               the C compiler command (word-split; default "cc")
+ *   CFLAGS           extra compiler flags (default empty)
+ *   cross_compiling  "yes" when cross-compiling (--host != --build), else
+ *                    unset/empty. RUN probes test `[ "$cross_compiling" =
+ *                    "yes" ]` and skip execution when set.
+ *   st_cc_id         compiler identity string used in cache keys (default
+ *                    "unknown"). Must be a shell-safe token free of `=` and
+ *                    regex metacharacters (compiler ids are, e.g.
+ *                    "gcc"/"clang"); it is interpolated into a cache key
+ *                    that st_cache_get matches with grep -F.
+ *   config_cache     path to the runtime result cache (default ./config.cache)
+ *   config_log       path probe stdout/stderr is appended to (default ./config.log)
+ *   st_tmpdir        directory for temp probe files (default ${TMPDIR:-/tmp})
+ *
+ * CACHE KEY SCHEME
+ * ----------------
+ * One config.cache line per check per compiler, value `yes` or `no`:
+ *
+ *     ac_cv_<checkname>_<compiler-id>=yes|no
+ *
+ * `<checkname>` is the unique name passed to st_probe_emit_snippet (see
+ * below); `<compiler-id>` is the configure-time $st_cc_id. This is the
+ * ac_cv_func_strdup pattern generalized: the key is derived from the check
+ * AND the compiler so that re-running configure under a different compiler
+ * re-probes instead of trusting a foreign cache entry.
+ *
+ * EMITTED SNIPPET SHAPE (per check)
+ * ---------------------------------
+ *     # probe: <mode> check '<checkname>'
+ *     st_cv_key=ac_cv_<checkname>_$st_cc_id
+ *     if st_cv_val=$(st_cache_get "$st_cv_key"); then
+ *         have_<checkname>=$st_cv_val
+ *     else
+ *         have_<checkname>=no
+ *         <mode-specific probe body, sets have_<checkname>=yes on success>
+ *         st_cache_set "$st_cv_key" "$have_<checkname>"
+ *     fi
+ *
+ * RUN probes wrap that in a cross-compile guard FIRST:
+ *     if [ "$cross_compiling" = "yes" ]; then
+ *         st_cross_<checkname>=yes
+ *         have_<checkname>=no
+ *         echo "warning: skipping runtime check '<checkname>' while
+ *               cross-compiling" >&2
+ *     elif st_cv_val=$(st_cache_get "$st_cv_key"); then
+ *         have_<checkname>=$st_cv_val
+ *     else
+ *         ...compile + run...
+ *     fi
+ * The cross-skipped result is NOT written to config.cache (a cross default
+ * must never poison a native build's cache entry).
+ *
+ * Mode bodies (all probe stdout+stderr appended to "$config_log" via
+ * >>"$config_log" 2>&1; temp files removed with rm -f; the .c source is
+ * written with `printf '%s' <st_sh_quote(c_source)> > "$st_probe_src"` —
+ * single-quote wrapping, NOT a here-document, so a C source containing
+ * arbitrary bytes incl. newlines and the delimiter-like text stays inert):
+ *   COMPILE   $CC $CFLAGS <extra> -c "$src" -o "$src.o"
+ *   LINK      $CC $CFLAGS <extra> "$src" -o "$src.bin"
+ *   RUN       compile+link, then "$src.bin"
+ *   COMMAND   <command argv>: every element except the LAST is a hardcoded
+ *             literal (program name "command"/"pkg-config" + fixed flags)
+ *             and is emitted verbatim; the LAST element (the user-supplied
+ *             target) is single-quoted. e.g. `command -v 'pkg-config'`,
+ *             `pkg-config --cflags --libs 'openssl'`. (A future kind
+ *             supplying a user-controlled non-final element must quote it.)
+ *   PREPROCESS  $CC $CFLAGS <extra> -E "$src"  (reserved; unused by v1)
+ *
+ * CHECKNAME CONTRACT
+ * ------------------
+ * `checkname` MUST be a valid POSIX shell identifier ([A-Za-z_][A-Za-z0-9_]*).
+ * It is interpolated into the variable names have_<checkname> /
+ * st_cross_<checkname> / ac_cv_<checkname>_$st_cc_id and a temp filename,
+ * none of which can be shell-quoted. st_probe_emit_snippet validates this
+ * and returns ST_ERR_USAGE on violation (mirroring sh_emit.h's documented
+ * trust boundary for `var`, but enforced rather than trusted because the
+ * value reaches a variable-NAME position). The caller chooses a unique
+ * checkname per check: for a single-check feature that is the feature name
+ * (so have_<feature> is set directly); for a multi-check feature the caller
+ * derives distinct names and todo 14/16 ANDs them into have_<feature>.
+ *
+ * VERSION CONSTRAINT
+ * ------------------
+ * probe->version_constraint is NOT consumed by the emitted snippet. For
+ * pkg_config the constraint operator was already folded into the command
+ * argv by checks.c (e.g. --atleast-version=1.1); for library the constraint
+ * is recorded only and todo 16 enforces it (via pkg-config when available).
+ * This field is simply ignored here.
+ *
+ * ERRORS
+ * ------
+ * All functions return NULL on success. Failures return an owned st_error:
+ * ST_ERR_USAGE for NULL arguments, an invalid checkname, an out-of-range
+ * probe mode, a COMMAND probe with no command argv, or a non-COMMAND probe
+ * with no C source; ST_ERR_INTERNAL when st_sh_quote fails (NUL byte / OOM,
+ * propagated) or quoting allocation fails; ST_ERR_IO when writing to the
+ * stream fails (detected via ferror after emission).
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef ST_DETECT_PROBE_H
+#define ST_DETECT_PROBE_H
+
+#include <stddef.h>
+#include <stdio.h>
+
+#include "detect/checks.h" /* struct st_check_probe, enum st_check_probe_mode */
+
+struct st_error;
+
+/* Emit the config.cache boilerplate: the st_cache_get / st_cache_set shell
+ * functions plus the conservative defaults for the contract variables
+ * (CC/CFLAGS/cross_compiling/st_cc_id/config_cache/config_log/st_tmpdir).
+ * This is emitted ONCE per configure script, before any probe snippet. The
+ * two functions are:
+ *   st_cache_get KEY      -> echoes the cached value (yes/no) and returns 0,
+ *                           or returns 1 when config.cache is absent or KEY
+ *                           is not recorded.
+ *   st_cache_set KEY VALUE -> records VALUE (yes/no) under KEY, replacing
+ *                           any prior line for the same key; creates
+ *                           config.cache when absent.
+ * POSIX-only (no `local`, no arrays, no `==`). */
+struct st_error *st_probe_emit_cache_functions(FILE *out);
+
+/* Emit the POSIX-sh snippet that probes ONE check at configure time.
+ * Appends to `out`; sets have_<checkname>=yes|no (always, on every path).
+ * Returns NULL on success. */
+struct st_error *st_probe_emit_snippet(const char *checkname,
+                                       const struct st_check_probe *probe,
+                                       FILE *out);
+
+/* One entry of a feature's check list: a unique check name paired with its
+ * probe spec. `name` is the have_<name> variable + cache-key base. */
+struct st_probe_entry {
+    const char *name;                 /* unique POSIX identifier */
+    const struct st_check_probe *probe; /* borrowed; not freed here */
+};
+
+/* Emit a feature's list of checks (each via st_probe_emit_snippet). A blank
+ * line separates checks. Returns NULL on success, or the first error. */
+struct st_error *st_probe_emit_all(const struct st_probe_entry *entries,
+                                   size_t count, FILE *out);
+
+#endif /* ST_DETECT_PROBE_H */

src/detect/resolve.c

@@ -0,0 +1,869 @@
+/*
+ * resolve.c - feature resolution + `when` guards (todo 14).
+ *
+ * Pure code generator: it PARSES the `when` guard grammar into an AST and
+ * EMITS POSIX-sh that evaluates guards and aggregates feature results at
+ * CONFIGURE time. It never runs a probe and never evaluates a guard
+ * itself. See resolve.h for the guard grammar, the os-mapping table, the
+ * $st_os contract, the emitted guard shape, and the feature-aggregation
+ * contract that todo 16 consumes.
+ *
+ * Safety decisions:
+ *   - Guard leaves emit `[ "$have_<ident>" = "yes" ]` and
+ *     `[ "$st_os" = '<name>' ]`; the ident is validated as a POSIX shell
+ *     identifier (it lands in a variable-NAME position and cannot be
+ *     quoted), the os name is validated against the same charset AND
+ *     single-quoted on emission (belt and braces).
+ *   - Binary nodes re-parenthesize with `( ... )` because POSIX sh gives
+ *     `&&`/`||` equal left-associative precedence, unlike the guard
+ *     grammar's or-over-and hierarchy.
+ *   - The os table is a single source of truth: st_os_normalize (C) and
+ *     st_resolve_emit_os_norm (shell) both derive from os_map[].
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "detect/resolve.h"
+
+#include "error.h"
+#include "gen/sh_emit.h"
+
+#include <stdbool.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* ---- the os mapping table (single source of truth) -------------------- */
+
+struct st_os_entry {
+    const char *uname_s; /* raw `uname -s` output */
+    const char *norm;    /* canonical name for os= guards */
+};
+
+static const struct st_os_entry os_map[] = {
+    { "Linux", "linux" },
+    { "Darwin", "macos" },
+    { "FreeBSD", "bsd" },
+    { "OpenBSD", "bsd" },
+    { "NetBSD", "bsd" },
+};
+
+#define OS_MAP_COUNT (sizeof(os_map) / sizeof(os_map[0]))
+
+const char *
+st_os_normalize(const char *uname_s)
+{
+    size_t i;
+
+    if (uname_s == NULL) {
+        return "other";
+    }
+    for (i = 0; i < OS_MAP_COUNT; i++) {
+        if (strcmp(uname_s, os_map[i].uname_s) == 0) {
+            return os_map[i].norm;
+        }
+    }
+    return "other";
+}
+
+/* ---- identifiers ------------------------------------------------------ */
+
+static bool
+valid_ident(const char *s)
+{
+    const unsigned char *p;
+
+    if (s == NULL || *s == '\0') {
+        return false;
+    }
+    p = (const unsigned char *)s;
+    if (!((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') ||
+          *p == '_')) {
+        return false;
+    }
+    for (p++; *p != '\0'; p++) {
+        if (!((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') ||
+              (*p >= '0' && *p <= '9') || *p == '_')) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/* Length-bounded identifier check (word slices are not NUL-terminated). */
+static bool
+valid_ident_n(const char *s, size_t n)
+{
+    size_t i;
+
+    if (s == NULL || n == 0) {
+        return false;
+    }
+    if (!((s[0] >= 'a' && s[0] <= 'z') || (s[0] >= 'A' && s[0] <= 'Z') ||
+          s[0] == '_')) {
+        return false;
+    }
+    for (i = 1; i < n; i++) {
+        if (!((s[i] >= 'a' && s[i] <= 'z') || (s[i] >= 'A' && s[i] <= 'Z') ||
+              (s[i] >= '0' && s[i] <= '9') || s[i] == '_')) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/* ---- owned errors (same-block span, the parser.c pattern) ------------- */
+
+static struct st_error *
+err_at_owned(struct st_span sp, const char *msg)
+{
+    const size_t align = _Alignof(struct st_span);
+    const size_t esize =
+        (sizeof(struct st_error) + align - 1) & ~(align - 1);
+    struct st_error *e;
+    struct st_span *spc;
+    size_t mlen;
+
+    if (msg == NULL) {
+        msg = "";
+    }
+    e = malloc(esize + sizeof(struct st_span));
+    if (e == NULL) {
+        return NULL;
+    }
+    mlen = strlen(msg);
+    e->message = malloc(mlen + 1);
+    if (e->message == NULL) {
+        free(e);
+        return NULL;
+    }
+    memcpy(e->message, msg, mlen + 1);
+    e->category = ST_ERR_KDL_SCHEMA;
+    spc = (struct st_span *)((unsigned char *)e + esize);
+    *spc = sp;
+    e->span = spc;
+    return e;
+}
+
+/* ---- the guard AST ---------------------------------------------------- */
+
+enum st_when_kind {
+    ST_WHEN_HAVE = 0, /* have_<ident>: $have_<ident> = "yes" */
+    ST_WHEN_OS,       /* os=<name>: $st_os = '<name>'          */
+    ST_WHEN_NOT,      /* ! <left>                              */
+    ST_WHEN_AND,      /* <left> && <right>                     */
+    ST_WHEN_OR,       /* <left> || <right>                     */
+};
+
+struct st_when_ast {
+    enum st_when_kind kind;
+    char *text;                /* HAVE: ident; OS: name; else NULL */
+    struct st_when_ast *left;  /* NOT operand; AND/OR left */
+    struct st_when_ast *right; /* AND/OR right */
+};
+
+static char *
+dup_n(const char *s, size_t n)
+{
+    char *p = malloc(n + 1);
+
+    if (p == NULL) {
+        return NULL;
+    }
+    memcpy(p, s, n);
+    p[n] = '\0';
+    return p;
+}
+
+static struct st_when_ast *
+leaf(enum st_when_kind kind, const char *text, size_t len)
+{
+    struct st_when_ast *a = calloc(1, sizeof(*a));
+
+    if (a == NULL) {
+        return NULL;
+    }
+    a->kind = kind;
+    if (text != NULL) {
+        a->text = dup_n(text, len);
+        if (a->text == NULL) {
+            free(a);
+            return NULL;
+        }
+    }
+    return a;
+}
+
+void
+st_when_free(struct st_when_ast *a)
+{
+    if (a == NULL) {
+        return;
+    }
+    st_when_free(a->left);
+    st_when_free(a->right);
+    free(a->text);
+    free(a);
+}
+
+/* ---- the guard lexer -------------------------------------------------- */
+
+enum gtok_kind {
+    GTOK_EOF = 0,
+    GTOK_HAVE,       /* text = ident (slice) */
+    GTOK_OS,         /* text = name (slice)  */
+    GTOK_AND,
+    GTOK_OR,
+    GTOK_NOT,
+    GTOK_LPAREN,
+    GTOK_RPAREN,
+    GTOK_UNKNOWN,    /* word that is none of the above */
+    GTOK_HAVE_EMPTY, /* word == "have_" */
+    GTOK_HAVE_BAD,   /* have_ + invalid ident */
+    GTOK_OS_EMPTY,   /* word == "os=" */
+    GTOK_OS_BAD,     /* os= + invalid name */
+};
+
+struct gtok {
+    enum gtok_kind kind;
+    size_t off;       /* byte offset of the token start in the guard */
+    const char *text; /* slice into the guard (word, or ident/name) */
+    size_t len;
+};
+
+struct glex {
+    const char *s;
+    size_t len;
+    size_t pos;
+    struct gtok cur;
+};
+
+static bool
+is_space(unsigned char c)
+{
+    return c == ' ' || c == '\t' || c == '\n' || c == '\r' || c == '\v' ||
+           c == '\f';
+}
+
+/* Classify a word slice (not NUL-terminated). For HAVE/OS success the
+ * text/len are narrowed to the ident/name; for error kinds they stay the
+ * whole word so the parser can echo it. */
+static void
+classify_word(struct gtok *t, const char *w, size_t wlen, size_t off)
+{
+    t->off = off;
+    t->text = w;
+    t->len = wlen;
+
+    if (wlen == 3 && memcmp(w, "and", 3) == 0) {
+        t->kind = GTOK_AND;
+    } else if (wlen == 2 && memcmp(w, "or", 2) == 0) {
+        t->kind = GTOK_OR;
+    } else if (wlen == 3 && memcmp(w, "not", 3) == 0) {
+        t->kind = GTOK_NOT;
+    } else if (wlen >= 5 && memcmp(w, "have_", 5) == 0) {
+        if (wlen == 5) {
+            t->kind = GTOK_HAVE_EMPTY;
+        } else if (!valid_ident_n(w + 5, wlen - 5)) {
+            t->kind = GTOK_HAVE_BAD;
+        } else {
+            t->kind = GTOK_HAVE;
+            t->text = w + 5;
+            t->len = wlen - 5;
+        }
+    } else if (wlen >= 3 && memcmp(w, "os=", 3) == 0) {
+        if (wlen == 3) {
+            t->kind = GTOK_OS_EMPTY;
+        } else if (!valid_ident_n(w + 3, wlen - 3)) {
+            t->kind = GTOK_OS_BAD;
+        } else {
+            t->kind = GTOK_OS;
+            t->text = w + 3;
+            t->len = wlen - 3;
+        }
+    } else {
+        t->kind = GTOK_UNKNOWN;
+    }
+}
+
+static void
+next_tok(struct glex *lx)
+{
+    const char *s = lx->s;
+    size_t n = lx->len;
+    size_t i = lx->pos;
+    size_t start;
+
+    while (i < n && is_space((unsigned char)s[i])) {
+        i++;
+    }
+    lx->pos = i;
+    lx->cur.text = NULL;
+    lx->cur.len = 0;
+    lx->cur.kind = GTOK_EOF;
+
+    if (i >= n) {
+        lx->cur.off = n;
+        return;
+    }
+    if (s[i] == '(') {
+        lx->cur.kind = GTOK_LPAREN;
+        lx->cur.off = i;
+        lx->cur.text = s + i;
+        lx->cur.len = 1;
+        lx->pos = i + 1;
+        return;
+    }
+    if (s[i] == ')') {
+        lx->cur.kind = GTOK_RPAREN;
+        lx->cur.off = i;
+        lx->cur.text = s + i;
+        lx->cur.len = 1;
+        lx->pos = i + 1;
+        return;
+    }
+
+    start = i;
+    while (i < n && !is_space((unsigned char)s[i]) && s[i] != '(' &&
+           s[i] != ')') {
+        i++;
+    }
+    lx->pos = i;
+    classify_word(&lx->cur, s + start, i - start, start);
+}
+
+/* ---- the guard parser ------------------------------------------------- */
+
+struct parse_ctx {
+    struct glex lx;
+    const struct st_span *base; /* NULL -> offset span into the guard */
+};
+
+/* 1-based line/col of byte offset `off` within `s`. */
+static struct st_span
+off_span(const char *s, size_t off)
+{
+    struct st_span sp = { NULL, 1, 1 };
+    size_t i;
+
+    for (i = 0; i < off && s[i] != '\0'; i++) {
+        if (s[i] == '\n') {
+            sp.line++;
+            sp.col = 1;
+        } else {
+            sp.col++;
+        }
+    }
+    return sp;
+}
+
+static struct st_error *
+parse_error(const struct parse_ctx *pc, size_t off, const char *msg)
+{
+    struct st_span sp;
+
+    if (pc->base != NULL) {
+        sp = *pc->base;
+    } else {
+        sp = off_span(pc->lx.s, off);
+    }
+    return err_at_owned(sp, msg);
+}
+
+/* Copy the current token's word into `buf` for message text. */
+static const char *
+word_into(const struct gtok *t, char *buf, size_t cap)
+{
+    size_t n = t->len < cap - 1 ? t->len : cap - 1;
+
+    if (t->text == NULL) {
+        n = 0;
+    }
+    if (n > 0) {
+        memcpy(buf, t->text, n);
+    }
+    buf[n] = '\0';
+    return buf;
+}
+
+static struct st_error *
+unexpected(struct parse_ctx *pc)
+{
+    const struct gtok *t = &pc->lx.cur;
+    char w[65];
+    char msg[160];
+
+    switch (t->kind) {
+    case GTOK_UNKNOWN:
+        snprintf(msg, sizeof msg, "unknown token '%s' in when guard",
+                 word_into(t, w, sizeof w));
+        break;
+    case GTOK_HAVE_EMPTY:
+        snprintf(msg, sizeof msg,
+                 "missing feature name after 'have_' in when guard");
+        break;
+    case GTOK_HAVE_BAD:
+        snprintf(msg, sizeof msg,
+                 "invalid feature name '%s' after 'have_' in when guard",
+                 word_into(t, w, sizeof w));
+        break;
+    case GTOK_OS_EMPTY:
+        snprintf(msg, sizeof msg, "missing os name after 'os=' in when "
+                 "guard");
+        break;
+    case GTOK_OS_BAD:
+        snprintf(msg, sizeof msg,
+                 "invalid os name '%s' after 'os=' in when guard",
+                 word_into(t, w, sizeof w));
+        break;
+    case GTOK_EOF:
+        snprintf(msg, sizeof msg, "unexpected end of when guard expression");
+        break;
+    default:
+        snprintf(msg, sizeof msg, "unexpected token '%s' in when guard",
+                 word_into(t, w, sizeof w));
+        break;
+    }
+    return parse_error(pc, t->off, msg);
+}
+
+static struct st_error *
+parse_or(struct parse_ctx *pc, struct st_when_ast **out);
+
+static struct st_error *
+parse_primary(struct parse_ctx *pc, struct st_when_ast **out)
+{
+    const struct gtok *t = &pc->lx.cur;
+
+    *out = NULL;
+    switch (t->kind) {
+    case GTOK_LPAREN: {
+        struct st_when_ast *inner = NULL;
+        struct st_error *e;
+
+        next_tok(&pc->lx);
+        e = parse_or(pc, &inner);
+        if (e != NULL) {
+            return e;
+        }
+        if (pc->lx.cur.kind != GTOK_RPAREN) {
+            struct st_error *e2 = parse_error(pc, pc->lx.cur.off,
+                                              "expected ')' in when guard");
+
+            st_when_free(inner);
+            return e2;
+        }
+        next_tok(&pc->lx);
+        *out = inner;
+        return NULL;
+    }
+    case GTOK_HAVE: {
+        struct st_when_ast *a = leaf(ST_WHEN_HAVE, t->text, t->len);
+
+        if (a == NULL) {
+            return st_error_internal("out of memory parsing when guard");
+        }
+        next_tok(&pc->lx);
+        *out = a;
+        return NULL;
+    }
+    case GTOK_OS: {
+        struct st_when_ast *a = leaf(ST_WHEN_OS, t->text, t->len);
+
+        if (a == NULL) {
+            return st_error_internal("out of memory parsing when guard");
+        }
+        next_tok(&pc->lx);
+        *out = a;
+        return NULL;
+    }
+    default:
+        return unexpected(pc);
+    }
+}
+
+static struct st_error *
+parse_not(struct parse_ctx *pc, struct st_when_ast **out)
+{
+    if (pc->lx.cur.kind == GTOK_NOT) {
+        struct st_when_ast *inner = NULL;
+        struct st_when_ast *a;
+        struct st_error *e;
+
+        next_tok(&pc->lx);
+        e = parse_not(pc, &inner);
+        if (e != NULL) {
+            return e;
+        }
+        a = calloc(1, sizeof(*a));
+        if (a == NULL) {
+            st_when_free(inner);
+            return st_error_internal("out of memory parsing when guard");
+        }
+        a->kind = ST_WHEN_NOT;
+        a->left = inner;
+        *out = a;
+        return NULL;
+    }
+    return parse_primary(pc, out);
+}
+
+static struct st_error *
+parse_and(struct parse_ctx *pc, struct st_when_ast **out)
+{
+    struct st_when_ast *lhs = NULL;
+    struct st_error *e;
+
+    e = parse_not(pc, &lhs);
+    if (e != NULL) {
+        return e;
+    }
+    while (pc->lx.cur.kind == GTOK_AND) {
+        struct st_when_ast *rhs = NULL;
+        struct st_when_ast *join;
+
+        next_tok(&pc->lx);
+        e = parse_not(pc, &rhs);
+        if (e != NULL) {
+            st_when_free(lhs);
+            return e;
+        }
+        join = calloc(1, sizeof(*join));
+        if (join == NULL) {
+            st_when_free(lhs);
+            st_when_free(rhs);
+            return st_error_internal("out of memory parsing when guard");
+        }
+        join->kind = ST_WHEN_AND;
+        join->left = lhs;
+        join->right = rhs;
+        lhs = join;
+    }
+    *out = lhs;
+    return NULL;
+}
+
+static struct st_error *
+parse_or(struct parse_ctx *pc, struct st_when_ast **out)
+{
+    struct st_when_ast *lhs = NULL;
+    struct st_error *e;
+
+    e = parse_and(pc, &lhs);
+    if (e != NULL) {
+        return e;
+    }
+    while (pc->lx.cur.kind == GTOK_OR) {
+        struct st_when_ast *rhs = NULL;
+        struct st_when_ast *join;
+
+        next_tok(&pc->lx);
+        e = parse_and(pc, &rhs);
+        if (e != NULL) {
+            st_when_free(lhs);
+            return e;
+        }
+        join = calloc(1, sizeof(*join));
+        if (join == NULL) {
+            st_when_free(lhs);
+            st_when_free(rhs);
+            return st_error_internal("out of memory parsing when guard");
+        }
+        join->kind = ST_WHEN_OR;
+        join->left = lhs;
+        join->right = rhs;
+        lhs = join;
+    }
+    *out = lhs;
+    return NULL;
+}
+
+struct st_error *
+st_when_parse_at(const char *guard, const struct st_span *at,
+                 struct st_when_ast **out)
+{
+    struct parse_ctx pc;
+    struct st_when_ast *ast = NULL;
+    struct st_error *e;
+
+    if (out == NULL) {
+        return st_error_usage("st_when_parse: NULL out");
+    }
+    *out = NULL;
+    if (guard == NULL || guard[0] == '\0') {
+        return NULL; /* absent guard = always true */
+    }
+
+    pc.lx.s = guard;
+    pc.lx.len = strlen(guard);
+    pc.lx.pos = 0;
+    pc.base = at;
+    next_tok(&pc.lx);
+
+    e = parse_or(&pc, &ast);
+    if (e != NULL) {
+        st_when_free(ast);
+        return e;
+    }
+    if (pc.lx.cur.kind != GTOK_EOF) {
+        e = unexpected(&pc);
+        st_when_free(ast);
+        return e;
+    }
+    *out = ast;
+    return NULL;
+}
+
+struct st_error *
+st_when_parse(const char *guard, struct st_when_ast **out)
+{
+    return st_when_parse_at(guard, NULL, out);
+}
+
+/* ---- guard emission --------------------------------------------------- */
+
+static struct st_error *
+emit_node(FILE *out, const struct st_when_ast *n)
+{
+    switch (n->kind) {
+    case ST_WHEN_HAVE:
+        if (fprintf(out, "[ \"$have_%s\" = \"yes\" ]", n->text) < 0) {
+            return st_error_io("I/O error emitting when guard");
+        }
+        break;
+    case ST_WHEN_OS: {
+        char *q = st_sh_quote(n->text);
+        int rc;
+
+        if (q == NULL) {
+            return st_error_internal("out of memory quoting os name");
+        }
+        rc = fprintf(out, "[ \"$st_os\" = %s ]", q);
+        free(q);
+        if (rc < 0) {
+            return st_error_io("I/O error emitting when guard");
+        }
+        break;
+    }
+    case ST_WHEN_NOT: {
+        struct st_error *e;
+
+        if (fputs("! ( ", out) == EOF) {
+            return st_error_io("I/O error emitting when guard");
+        }
+        e = emit_node(out, n->left);
+        if (e != NULL) {
+            return e;
+        }
+        if (fputs(" )", out) == EOF) {
+            return st_error_io("I/O error emitting when guard");
+        }
+        break;
+    }
+    case ST_WHEN_AND:
+    case ST_WHEN_OR: {
+        const char *op = (n->kind == ST_WHEN_AND) ? "&&" : "||";
+        struct st_error *e;
+
+        if (fputs("( ", out) == EOF) {
+            return st_error_io("I/O error emitting when guard");
+        }
+        e = emit_node(out, n->left);
+        if (e != NULL) {
+            return e;
+        }
+        if (fprintf(out, " ) %s ( ", op) < 0) {
+            return st_error_io("I/O error emitting when guard");
+        }
+        e = emit_node(out, n->right);
+        if (e != NULL) {
+            return e;
+        }
+        if (fputs(" )", out) == EOF) {
+            return st_error_io("I/O error emitting when guard");
+        }
+        break;
+    }
+    default:
+        return st_error_internal("st_when_emit: corrupted guard AST");
+    }
+    return NULL;
+}
+
+struct st_error *
+st_when_emit(FILE *out, const struct st_when_ast *ast)
+{
+    if (out == NULL) {
+        return st_error_usage("st_when_emit: NULL stream");
+    }
+    if (ast == NULL) {
+        /* absent guard = always true; `:` is the no-op command */
+        if (fputs(":", out) == EOF) {
+            return st_error_io("I/O error emitting when guard");
+        }
+        return NULL;
+    }
+    return emit_node(out, ast);
+}
+
+/* ---- os normalization boilerplate ------------------------------------- */
+
+struct st_error *
+st_resolve_emit_os_norm(FILE *out)
+{
+    size_t i;
+
+    if (out == NULL) {
+        return st_error_usage("st_resolve_emit_os_norm: NULL stream");
+    }
+    if (fputs(
+            "# st_os holds the raw `uname -s` output (set by the configure\n"
+            "# preamble). st_os_norm rewrites it IN PLACE to the canonical\n"
+            "# name that `os=<name>` guards compare against.\n"
+            "st_os_norm() {\n"
+            "    case \"$st_os\" in\n",
+            out) == EOF) {
+        return st_error_io("I/O error emitting st_os_norm");
+    }
+    for (i = 0; i < OS_MAP_COUNT; i++) {
+        char *pat = st_sh_quote(os_map[i].uname_s);
+        char *val = st_sh_quote(os_map[i].norm);
+        int rc;
+
+        if (pat == NULL || val == NULL) {
+            free(pat);
+            free(val);
+            return st_error_internal("out of memory emitting st_os_norm");
+        }
+        rc = fprintf(out, "        %s) st_os=%s ;;\n", pat, val);
+        free(pat);
+        free(val);
+        if (rc < 0) {
+            return st_error_io("I/O error emitting st_os_norm");
+        }
+    }
+    if (fputs("        *) st_os='other' ;;\n"
+              "    esac\n"
+              "}\n",
+              out) == EOF) {
+        return st_error_io("I/O error emitting st_os_norm");
+    }
+    if (ferror(out)) {
+        return st_error_io("I/O error emitting st_os_norm");
+    }
+    return NULL;
+}
+
+/* ---- feature aggregation ---------------------------------------------- */
+
+int
+st_resolve_check_name(const char *name, size_t index, size_t count,
+                      char *out, size_t out_cap)
+{
+    int rc;
+
+    if (name == NULL || out == NULL || out_cap == 0) {
+        return -1;
+    }
+    if (!valid_ident(name)) {
+        return -1;
+    }
+    if (count == 0 || index >= count) {
+        return -1;
+    }
+    if (count == 1) {
+        rc = snprintf(out, out_cap, "%s", name);
+    } else {
+        rc = snprintf(out, out_cap, "%s_%zu", name, index);
+    }
+    if (rc < 0 || (size_t)rc >= out_cap) {
+        return -1;
+    }
+    return 0;
+}
+
+struct st_error *
+st_resolve_emit_feature(FILE *out, const struct st_resolve_feature *f)
+{
+    bool direct;
+    size_t i;
+    struct st_error *e;
+
+    if (out == NULL || f == NULL) {
+        return st_error_usage("st_resolve_emit_feature: NULL argument");
+    }
+    if (!valid_ident(f->name)) {
+        return st_error_usage("st_resolve_emit_feature: feature name must "
+                              "be a POSIX shell identifier");
+    }
+    if (f->check_count == 0) {
+        return st_error_usage("st_resolve_emit_feature: feature has no "
+                              "checks");
+    }
+    if (f->check_names == NULL) {
+        return st_error_usage("st_resolve_emit_feature: NULL check_names");
+    }
+    for (i = 0; i < f->check_count; i++) {
+        if (!valid_ident(f->check_names[i])) {
+            return st_error_usage("st_resolve_emit_feature: check name "
+                                  "must be a POSIX shell identifier");
+        }
+    }
+
+    if (fprintf(out, "# feature '%s'\n", f->name) < 0) {
+        return st_error_io("I/O error emitting feature resolution");
+    }
+
+    /* The single check whose name IS the feature name was already set to
+     * have_<name> by todo 12's snippet — nothing to aggregate. */
+    direct = (f->check_count == 1 &&
+              strcmp(f->check_names[0], f->name) == 0);
+
+    if (!direct) {
+        if (f->check_count == 1) {
+            if (fprintf(out, "have_%s=$have_%s\n", f->name,
+                        f->check_names[0]) < 0) {
+                return st_error_io("I/O error emitting feature resolution");
+            }
+        } else {
+            if (fputs("if ", out) == EOF) {
+                return st_error_io("I/O error emitting feature resolution");
+            }
+            for (i = 0; i < f->check_count; i++) {
+                if (i > 0 && fputs(" && ", out) == EOF) {
+                    return st_error_io("I/O error emitting feature "
+                                       "resolution");
+                }
+                if (fprintf(out, "[ \"$have_%s\" = \"yes\" ]",
+                            f->check_names[i]) < 0) {
+                    return st_error_io("I/O error emitting feature "
+                                       "resolution");
+                }
+            }
+            if (fprintf(out, "; then\n    have_%s=yes\nelse\n    "
+                        "have_%s=no\nfi\n", f->name, f->name) < 0) {
+                return st_error_io("I/O error emitting feature resolution");
+            }
+        }
+    }
+
+    if (f->guard != NULL) {
+        if (fputs("if ", out) == EOF) {
+            return st_error_io("I/O error emitting feature resolution");
+        }
+        e = st_when_emit(out, f->guard);
+        if (e != NULL) {
+            return e;
+        }
+        if (fprintf(out, "; then\n    :\nelse\n    have_%s=no\nfi\n",
+                    f->name) < 0) {
+            return st_error_io("I/O error emitting feature resolution");
+        }
+    }
+
+    if (ferror(out)) {
+        return st_error_io("I/O error emitting feature resolution");
+    }
+    return NULL;
+}

src/detect/resolve.h

@@ -0,0 +1,192 @@
+/*
+ * resolve.h - feature resolution + `when` guards (todo 14).
+ *
+ * Two jobs live here, both PURE CODE GENERATION — this module never runs
+ * a probe and never evaluates a guard itself; the emitted shell does that
+ * at CONFIGURE time inside the generated ./configure:
+ *
+ *   (1) FEATURE RESOLUTION: combine each feature's per-check results (the
+ *       have_<checkname>=yes|no variables set by todo 12's snippets) into
+ *       the single availability boolean have_<feature>. A single-check
+ *       feature names its check after the feature (have_<feature> is set
+ *       directly by the probe); a multi-check feature derives distinct
+ *       names (<feature>_0, <feature>_1, ...) and this module ANDs them.
+ *
+ *   (2) THE `when` GUARD LANGUAGE: parse a guard STRING (the DSL's `when`
+ *       property) into an opaque AST and emit a POSIX-sh boolean test that
+ *       evaluates it against the configure-time variables $have_<feature>
+ *       and the normalized $st_os.
+ *
+ * THE `when` DSL PLACEMENT (pinned here; extends the todo-9 grammar)
+ * ----------------------------------------------------------------------
+ * `when` is an OPTIONAL property on a `feature` node, spelling (a KDL
+ * `key=value` property, exactly like an option's `default=#bool`):
+ *
+ *     feature "pthread" when="os=linux" { header "pthread.h" }
+ *
+ * Its value is a non-empty KDL string (enforced by src/kdl/schema.c). The
+ * guard STRING is NOT parsed by the schema — only resolve parses it (todo
+ * 16 extracts the string, calls st_when_parse_at with the feature node's
+ * span, then st_resolve_emit_feature). `target`/`option` take no `when`.
+ *
+ * GUARD GRAMMAR
+ * -------------
+ *     expr      := or_expr
+ *     or_expr   := and_expr ('or' and_expr)*
+ *     and_expr  := not_expr ('and' not_expr)*
+ *     not_expr  := 'not' not_expr | primary
+ *     primary   := '(' expr ')' | 'have_' <ident> | 'os=' <name>
+ *
+ * Tokens are whitespace-insensitive: `and`, `or`, `not`, `(`, `)`,
+ * `have_<ident>` (ident = [A-Za-z_][A-Za-z0-9_]*), and `os=<name>` (name
+ * uses the same identifier charset). `have_<ident>` reads the
+ * configure-time $have_<ident> (= "yes"|"no"); `os=<name>` compares the
+ * normalized $st_os for equality. Guards may reference OTHER features'
+ * availability (have_<bar>) — todo 16 orders features so referenced
+ * results are already computed; a self-referencing feature is a todo-16
+ * cycle to reject, not something resolve checks.
+ *
+ * THE $st_os CONTRACT (todo 16 preamble)
+ * --------------------------------------
+ * The configure preamble captures `uname -s` into $st_os, then calls the
+ * emitted st_os_norm() (see st_resolve_emit_os_norm), which rewrites it
+ * IN PLACE to the canonical name guards compare against:
+ *
+ *     Linux -> linux; Darwin -> macos; FreeBSD -> bsd;
+ *     OpenBSD/NetBSD -> bsd; anything else -> other
+ *
+ * The canonical table is the single source of truth: st_os_normalize()
+ * (C side) and the emitted st_os_norm() (shell side) both derive from it.
+ * os= guards therefore compare the ALREADY-normalized $st_os, so the
+ * emitted test is `[ "$st_os" = '<name>' ]` — no uname string is ever
+ * baked into a guard.
+ *
+ * EMITTED GUARD SHAPE (what todo 16 wraps)
+ * ----------------------------------------
+ * st_when_emit writes a SELF-CONTAINED boolean condition, designed to sit
+ * between `if` and `; then`:
+ *
+ *     if <emitted>; then ... fi
+ *
+ * Leaves:   [ "$have_<ident>" = "yes" ]      [ "$st_os" = '<name>' ]
+ * NOT:      ! ( <child> )
+ * AND/OR:   ( <left> ) && ( <right> )        ( <left> ) || ( <right> )
+ *
+ * The subshell grouping `( ... )` is deliberate: POSIX sh gives `&&` and
+ * `||` EQUAL (left-associative) precedence, unlike C, so the AST's
+ * structure must be re-parenthesized on emission. Only `[`, `!`, `&&`,
+ * `||`, `(`, `)` are used — no `[[`, no `==`, no `local`; the output
+ * passes sh -n / bash -n / zsh -n. A NULL AST (empty/absent guard) is
+ * "always true": st_when_emit writes the no-op command `:`.
+ *
+ * FEATURE AGGREGATION (the todo-16 contract)
+ * ------------------------------------------
+ * st_resolve_emit_feature() emits, in order:
+ *   1. a `# feature 'NAME'` comment;
+ *   2. the have_<name> AND-aggregation — nothing for a single check whose
+ *      name IS the feature name (the probe set it directly); a plain copy
+ *      `have_<name>=$have_<c0>` for a single differently-named check; and
+ *      an `if [ ... ] && [ ... ]; then have_<name>=yes; else
+ *      have_<name>=no; fi` for multiple checks;
+ *   3. the `when` gate (when f->guard != NULL):
+ *      `if <guard>; then :; else have_<name>=no; fi`.
+ * todo 16 emits the per-check probe snippets (todo 12) BEFORE calling
+ * this, so the aggregation always reads already-set have_<checkname>.
+ * Semantics pinned: have_<feature> = (AND of its checks) AND (guard).
+ *
+ * CHECK-NAME SCHEME
+ * -----------------
+ * st_resolve_check_name(name, index, count, ...) derives the per-check
+ * name todo 16 passes to st_probe_emit_snippet: count == 1 -> the feature
+ * name itself (have_<name> set directly); count > 1 -> "<name>_<index>".
+ *
+ * ERRORS
+ * ------
+ * st_when_parse/st_when_parse_at return an owned ST_ERR_KDL_SCHEMA error
+ * on a malformed guard, with a span heap-allocated IN THE SAME BLOCK as
+ * the error (the parser.c pattern). Without a base span (st_when_parse)
+ * the span points INTO the guard string (file = NULL, line/col = the
+ * offending token). With a base span (st_when_parse_at) the error carries
+ * that span — the `when` node's span, so todo 16 can attribute the error
+ * to the build file. Emitters follow the probe.c convention: NULL args /
+ * invalid identifiers -> ST_ERR_USAGE, quoting failure -> ST_ERR_INTERNAL,
+ * write failure -> ST_ERR_IO.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef ST_DETECT_RESOLVE_H
+#define ST_DETECT_RESOLVE_H
+
+#include <stddef.h>
+#include <stdio.h>
+
+struct st_error;
+struct st_span;
+
+/* ---- the `when` guard AST (opaque) ------------------------------------ */
+
+struct st_when_ast;
+
+/* Parse a `when` guard string into an AST. NULL or empty guard -> *out is
+ * left NULL ("always true") and NULL is returned. On a malformed guard
+ * returns an owned ST_ERR_KDL_SCHEMA error (span points into the guard
+ * string, file = NULL). On catastrophic OOM the returned error may itself
+ * be NULL (codebase-wide convention). *out is untouched on error. */
+struct st_error *st_when_parse(const char *guard, struct st_when_ast **out);
+
+/* As st_when_parse, but on error the error carries `at` (borrowed) as its
+ * span instead of a guard-offset span. Use it when the guard came from a
+ * KDL node so the error points at the `when` property's span. `at` may be
+ * NULL (then behaves like st_when_parse). */
+struct st_error *st_when_parse_at(const char *guard, const struct st_span *at,
+                                  struct st_when_ast **out);
+
+/* Release an AST. NULL is a safe no-op. */
+void st_when_free(struct st_when_ast *ast);
+
+/* Emit the guard as a self-contained POSIX-sh boolean condition (see the
+ * header's EMITTED GUARD SHAPE). NULL AST -> emits `:` ("always true").
+ * Returns NULL on success, an owned error otherwise. */
+struct st_error *st_when_emit(FILE *out, const struct st_when_ast *ast);
+
+/* ---- the os mapping --------------------------------------------------- */
+
+/* Map a raw `uname -s` string to its canonical name: Linux->linux,
+ * Darwin->macos, FreeBSD/OpenBSD/NetBSD->bsd, anything else (incl. NULL)
+ * -> other. The returned pointer is static. */
+const char *st_os_normalize(const char *uname_s);
+
+/* Emit the st_os_norm() shell function that rewrites $st_os in place to
+ * its canonical name (the same table as st_os_normalize). POSIX-sh only.
+ * Returns NULL on success. */
+struct st_error *st_resolve_emit_os_norm(FILE *out);
+
+/* ---- feature aggregation (the todo-16 contract) ----------------------- */
+
+/* One feature's resolution model. Everything is borrowed: the strings and
+ * the guard AST are owned by the caller and must outlive the emit call
+ * (the emit does not free the AST). */
+struct st_resolve_feature {
+    const char *name;              /* feature name -> have_<name> */
+    const char *const *check_names;/* [check_count] have_<cn> variables */
+    size_t check_count;            /* >= 1 */
+    struct st_when_ast *guard;     /* parsed guard; NULL = no guard */
+};
+
+/* Emit one feature's resolution (aggregation + when-gate) as described in
+ * the header. Returns NULL on success, an owned error otherwise. */
+struct st_error *st_resolve_emit_feature(FILE *out,
+                                         const struct st_resolve_feature *f);
+
+/* Derive the checkname todo 16 passes to st_probe_emit_snippet for
+ * `name`'s check at 0-based `index` when the feature has `count` checks.
+ * count == 1 -> the feature name itself; count > 1 -> "<name>_<index>".
+ * Writes into `out` (capacity `out_cap`). Returns 0 on success, -1 on
+ * NULL args, an invalid feature name, a zero count, an out-of-range
+ * index, or truncation. */
+int st_resolve_check_name(const char *name, size_t index, size_t count,
+                          char *out, size_t out_cap);
+
+#endif /* ST_DETECT_RESOLVE_H */

src/error.c

@@ -0,0 +1,138 @@
+#include "error.h"
+
+#include <stdlib.h>
+#include <string.h>
+
+/* C23 only: ISO/IEC 9899:2024. */
+
+static const char *const category_names[] = {
+    [ST_ERR_KDL_PARSE] = "kdl-parse",
+    [ST_ERR_KDL_SCHEMA] = "kdl-schema",
+    [ST_ERR_IO] = "io",
+    [ST_ERR_USAGE] = "usage",
+    [ST_ERR_INTERNAL] = "internal",
+};
+
+struct st_error *
+st_error_new(enum st_error_category category, const char *message)
+{
+    struct st_error *e;
+    size_t len;
+
+    if (message == NULL) {
+        message = "";
+    }
+    e = calloc(1, sizeof(*e));
+    if (e == NULL) {
+        return NULL;
+    }
+    len = strlen(message);
+    e->message = malloc(len + 1);
+    if (e->message == NULL) {
+        free(e);
+        return NULL;
+    }
+    memcpy(e->message, message, len + 1);
+    e->category = category;
+    return e;
+}
+
+struct st_error *
+st_error_kdl_parse(const char *message)
+{
+    return st_error_new(ST_ERR_KDL_PARSE, message);
+}
+
+struct st_error *
+st_error_kdl_schema(const char *message)
+{
+    return st_error_new(ST_ERR_KDL_SCHEMA, message);
+}
+
+struct st_error *
+st_error_io(const char *message)
+{
+    return st_error_new(ST_ERR_IO, message);
+}
+
+struct st_error *
+st_error_usage(const char *message)
+{
+    return st_error_new(ST_ERR_USAGE, message);
+}
+
+struct st_error *
+st_error_internal(const char *message)
+{
+    return st_error_new(ST_ERR_INTERNAL, message);
+}
+
+struct st_error *
+st_error_at(struct st_error *e, const struct st_span *span)
+{
+    if (e != NULL) {
+        e->span = span;
+    }
+    return e;
+}
+
+void
+st_error_free(struct st_error *e)
+{
+    if (e == NULL) {
+        return;
+    }
+    free(e->message);
+    free(e);
+}
+
+enum st_error_category
+st_error_category_of(const struct st_error *e)
+{
+    return e != NULL ? e->category : ST_ERR_INTERNAL;
+}
+
+const char *
+st_error_message(const struct st_error *e)
+{
+    return e != NULL ? e->message : "";
+}
+
+const char *
+st_error_category_name(enum st_error_category category)
+{
+    if ((size_t)category >= sizeof(category_names) / sizeof(category_names[0])) {
+        return "unknown";
+    }
+    return category_names[category];
+}
+
+void
+st_error_print(FILE *out, const struct st_error *e)
+{
+    const char *cat;
+    char *prefixed;
+    size_t len;
+    int rc;
+
+    if (out == NULL || e == NULL) {
+        return;
+    }
+    cat = st_error_category_name(e->category);
+    len = strlen(cat) + strlen(e->message) + 4; /* "[", "]", " ", NUL */
+    prefixed = malloc(len);
+    if (prefixed == NULL) {
+        fprintf(out, "%s\n", e->message);
+        return;
+    }
+    rc = snprintf(prefixed, len, "[%s] %s", cat, e->message);
+    if (rc < 0) {
+        prefixed[0] = '\0';
+    }
+    if (e->span != NULL) {
+        st_span_print(out, e->span, prefixed);
+    } else {
+        fprintf(out, "%s\n", prefixed);
+    }
+    free(prefixed);
+}

src/error.h

@@ -0,0 +1,55 @@
+#ifndef ST_ERROR_H
+#define ST_ERROR_H
+
+#include <stdio.h>
+
+#include "span.h"
+
+/*
+ * Typed error for all library code paths. Library code RETURNS these;
+ * it never calls exit()/abort() on user input (only main.c exits).
+ */
+enum st_error_category {
+    ST_ERR_KDL_PARSE = 0,
+    ST_ERR_KDL_SCHEMA,
+    ST_ERR_IO,
+    ST_ERR_USAGE,
+    ST_ERR_INTERNAL,
+};
+
+struct st_error {
+    enum st_error_category category;
+    char *message;              /* owned copy; never NULL after construction */
+    const struct st_span *span; /* borrowed, may be NULL */
+};
+
+/* Constructors. All duplicate `message`; NULL is treated as "". They
+ * return NULL only on allocation failure. */
+struct st_error *st_error_new(enum st_error_category category,
+                              const char *message);
+struct st_error *st_error_kdl_parse(const char *message);
+struct st_error *st_error_kdl_schema(const char *message);
+struct st_error *st_error_io(const char *message);
+struct st_error *st_error_usage(const char *message);
+struct st_error *st_error_internal(const char *message);
+
+/* Attaches a borrowed span and returns `e` for chaining:
+ *   err = st_error_at(st_error_kdl_parse("bad token"), &span); */
+struct st_error *st_error_at(struct st_error *e, const struct st_span *span);
+
+/* Frees the error (message + struct). NULL is a safe no-op. */
+void st_error_free(struct st_error *e);
+
+enum st_error_category st_error_category_of(const struct st_error *e);
+const char *st_error_message(const struct st_error *e);
+
+/* Stable display name, e.g. "kdl-parse". Unknown categories yield
+ * "unknown" rather than indexing out of range. */
+const char *st_error_category_name(enum st_error_category category);
+
+/* Prints the diagnostic. With a span: the canonical two-line form with
+ * the category-prefixed message ("file:line:col: [cat] <msg>\n" +
+ * caret line). Without a span: "[cat] <msg>\n". NULL is tolerated. */
+void st_error_print(FILE *out, const struct st_error *e);
+
+#endif

src/ext/abi.c

@@ -0,0 +1,694 @@
+#ifndef _POSIX_C_SOURCE
+#define _POSIX_C_SOURCE 200809L /* strdup, fork/exec/wait (POSIX.1-2008) */
+#endif
+
+#include "abi.h"
+
+#include "lang_c.h"
+#include "lang_cpp.h"
+
+#include <errno.h>
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/wait.h>
+#include <unistd.h>
+
+/*
+ * Generic extension ABI (plan todo 13). Owns three registries:
+ * variables (name/value, insertion order), languages, checks.
+ *
+ * No language-specific knowledge lives here: the builtin module table
+ * below names module ENTRY POINTS only; every compiler string lives in
+ * lang_c.c / lang_cpp.c. All state is reached through an explicitly
+ * passed `struct st_ext_ctx *` so a future Lua binding (todo 19) only
+ * wraps these functions.
+ */
+
+/* ---------------- formatting helper ---------------- */
+
+/* snprintf-based formatter for our diagnostic messages. Returns a heap
+ * st_error of the given category. */
+static struct st_error *
+errf(enum st_error_category cat, const char *fmt, ...)
+{
+    va_list ap;
+    int n;
+    char *msg;
+    struct st_error *e;
+
+    va_start(ap, fmt);
+    n = vsnprintf(NULL, 0, fmt, ap);
+    va_end(ap);
+    if (n < 0) {
+        return st_error_internal("failed to format error message");
+    }
+    msg = malloc((size_t)n + 1);
+    if (msg == NULL) {
+        return st_error_internal("out of memory");
+    }
+    va_start(ap, fmt);
+    vsnprintf(msg, (size_t)n + 1, fmt, ap);
+    va_end(ap);
+    e = st_error_new(cat, msg);
+    free(msg);
+    return e;
+}
+
+/* ---------------- variable registry ---------------- */
+
+struct st_reg_var {
+    char *name;   /* owned */
+    char *value;  /* owned; never NULL after insertion */
+    struct st_reg_var *next;
+};
+
+struct st_registry {
+    struct st_reg_var *head;
+    struct st_reg_var *tail;
+    size_t count;
+};
+
+struct st_registry *
+st_registry_new(void)
+{
+    return calloc(1, sizeof(struct st_registry));
+}
+
+void
+st_registry_free(struct st_registry *r)
+{
+    struct st_reg_var *node, *next;
+
+    if (r == NULL) {
+        return;
+    }
+    for (node = r->head; node != NULL; node = next) {
+        next = node->next;
+        free(node->name);
+        free(node->value);
+        free(node);
+    }
+    free(r);
+}
+
+struct st_error *
+st_registry_set_var(struct st_registry *r, const char *name,
+                    const char *value)
+{
+    struct st_reg_var *node, *prev;
+    char *dup_name, *dup_value;
+
+    if (r == NULL || name == NULL || name[0] == '\0') {
+        return st_error_usage("st_registry_set_var: NULL/empty name");
+    }
+    if (value != NULL) {
+        dup_value = strdup(value);
+        if (dup_value == NULL) {
+            return st_error_internal("out of memory");
+        }
+    } else {
+        dup_value = NULL;
+    }
+
+    prev = NULL;
+    for (node = r->head; node != NULL; prev = node, node = node->next) {
+        if (strcmp(node->name, name) != 0) {
+            continue;
+        }
+        if (dup_value == NULL) {
+            /* unset: unlink + free */
+            if (prev != NULL) {
+                prev->next = node->next;
+            } else {
+                r->head = node->next;
+            }
+            if (r->tail == node) {
+                r->tail = prev;
+            }
+            free(node->name);
+            free(node->value);
+            free(node);
+            r->count--;
+        } else {
+            free(node->value);
+            node->value = dup_value;
+        }
+        return NULL;
+    }
+
+    if (dup_value == NULL) {
+        return NULL; /* unsetting a var that does not exist: no-op */
+    }
+    dup_name = strdup(name);
+    if (dup_name == NULL) {
+        free(dup_value);
+        return st_error_internal("out of memory");
+    }
+    node = calloc(1, sizeof *node);
+    if (node == NULL) {
+        free(dup_name);
+        free(dup_value);
+        return st_error_internal("out of memory");
+    }
+    node->name = dup_name;
+    node->value = dup_value;
+    if (r->tail != NULL) {
+        r->tail->next = node;
+    } else {
+        r->head = node;
+    }
+    r->tail = node;
+    r->count++;
+    return NULL;
+}
+
+const char *
+st_registry_get_var(const struct st_registry *r, const char *name)
+{
+    const struct st_reg_var *node;
+
+    if (r == NULL || name == NULL) {
+        return NULL;
+    }
+    for (node = r->head; node != NULL; node = node->next) {
+        if (strcmp(node->name, name) == 0) {
+            return node->value;
+        }
+    }
+    return NULL;
+}
+
+size_t
+st_registry_var_count(const struct st_registry *r)
+{
+    return r == NULL ? 0 : r->count;
+}
+
+const char *
+st_registry_var_name(const struct st_registry *r, size_t i)
+{
+    const struct st_reg_var *node;
+
+    if (r == NULL) {
+        return NULL;
+    }
+    for (node = r->head; node != NULL && i > 0; node = node->next, i--) {
+    }
+    return node != NULL ? node->name : NULL;
+}
+
+const char *
+st_registry_var_value(const struct st_registry *r, size_t i)
+{
+    const struct st_reg_var *node;
+
+    if (r == NULL) {
+        return NULL;
+    }
+    for (node = r->head; node != NULL && i > 0; node = node->next, i--) {
+    }
+    return node != NULL ? node->value : NULL;
+}
+
+/* ---------------- toolchain ---------------- */
+
+static void
+toolchain_reset(struct st_toolchain *tc)
+{
+    if (tc == NULL) {
+        return;
+    }
+    free(tc->path);
+    free(tc->id);
+    free(tc->version);
+    tc->path = NULL;
+    tc->id = NULL;
+    tc->version = NULL;
+}
+
+/* ---------------- language registry ---------------- */
+
+struct st_language_node {
+    struct st_language pub;
+    char *name_owned;          /* pub.name points here */
+    char **var_names_owned;    /* pub.var_names points here (NULL-term) */
+    struct st_toolchain tc;    /* pub.toolchain points here when detected */
+    struct st_language_node *next;
+};
+
+struct st_check_node {
+    struct st_check pub;
+    char *language_owned;      /* pub.language points here */
+    char *kind_owned;          /* pub.kind points here */
+    struct st_check_node *next;
+};
+
+struct st_ext_ctx {
+    struct st_registry *vars;
+    struct st_language_node *langs_head, *langs_tail;
+    size_t lang_count;
+    struct st_check_node *checks_head, *checks_tail;
+    size_t check_count;
+};
+
+struct st_ext_ctx *
+st_ext_ctx_new(void)
+{
+    struct st_ext_ctx *ctx = calloc(1, sizeof *ctx);
+
+    if (ctx == NULL) {
+        return NULL;
+    }
+    ctx->vars = st_registry_new();
+    if (ctx->vars == NULL) {
+        free(ctx);
+        return NULL;
+    }
+    return ctx;
+}
+
+static void
+language_node_free(struct st_language_node *node)
+{
+    size_t i;
+
+    if (node == NULL) {
+        return;
+    }
+    free(node->name_owned);
+    if (node->var_names_owned != NULL) {
+        for (i = 0; node->var_names_owned[i] != NULL; i++) {
+            free(node->var_names_owned[i]);
+        }
+    }
+    free(node->var_names_owned);
+    toolchain_reset(&node->tc);
+    free(node);
+}
+
+void
+st_ext_ctx_free(struct st_ext_ctx *ctx)
+{
+    struct st_language_node *lnode, *lnext;
+    struct st_check_node *cnode, *cnext;
+
+    if (ctx == NULL) {
+        return;
+    }
+    for (lnode = ctx->langs_head; lnode != NULL; lnode = lnext) {
+        lnext = lnode->next;
+        language_node_free(lnode);
+    }
+    for (cnode = ctx->checks_head; cnode != NULL; cnode = cnext) {
+        cnext = cnode->next;
+        free(cnode->language_owned);
+        free(cnode->kind_owned);
+        free(cnode);
+    }
+    st_registry_free(ctx->vars);
+    free(ctx);
+}
+
+struct st_registry *
+st_ext_var_registry(struct st_ext_ctx *ctx)
+{
+    return ctx != NULL ? ctx->vars : NULL;
+}
+
+static struct st_language_node *
+find_language(const struct st_ext_ctx *ctx, const char *name)
+{
+    struct st_language_node *node;
+
+    if (ctx == NULL || name == NULL) {
+        return NULL;
+    }
+    for (node = ctx->langs_head; node != NULL; node = node->next) {
+        if (strcmp(node->pub.name, name) == 0) {
+            return node;
+        }
+    }
+    return NULL;
+}
+
+static const struct st_language_node *
+find_language_const(const struct st_ext_ctx *ctx, const char *name)
+{
+    return find_language(ctx, name);
+}
+
+struct st_error *
+st_ext_register_language(struct st_ext_ctx *ctx, const char *name,
+                         st_lang_detect_fn detect, void *module_ctx,
+                         const char *const *var_names)
+{
+    struct st_language_node *node;
+    size_t n_vars = 0, i;
+
+    if (ctx == NULL || name == NULL || name[0] == '\0' || detect == NULL) {
+        return st_error_usage("st_ext_register_language: bad argument");
+    }
+    if (find_language(ctx, name) != NULL) {
+        return errf(ST_ERR_USAGE, "language already registered: %s", name);
+    }
+
+    node = calloc(1, sizeof *node);
+    if (node == NULL) {
+        return st_error_internal("out of memory");
+    }
+    node->name_owned = strdup(name);
+    if (node->name_owned == NULL) {
+        language_node_free(node);
+        return st_error_internal("out of memory");
+    }
+    while (var_names != NULL && var_names[n_vars] != NULL) {
+        n_vars++;
+    }
+    node->var_names_owned = calloc(n_vars + 1, sizeof *node->var_names_owned);
+    if (node->var_names_owned == NULL) {
+        language_node_free(node);
+        return st_error_internal("out of memory");
+    }
+    for (i = 0; i < n_vars; i++) {
+        node->var_names_owned[i] = strdup(var_names[i]);
+        if (node->var_names_owned[i] == NULL) {
+            language_node_free(node);
+            return st_error_internal("out of memory");
+        }
+    }
+
+    node->pub.name = node->name_owned;
+    node->pub.detect = detect;
+    node->pub.module_ctx = module_ctx;
+    node->pub.var_names = (const char *const *)node->var_names_owned;
+    node->pub.toolchain = NULL;
+
+    if (ctx->langs_tail != NULL) {
+        ctx->langs_tail->next = node;
+    } else {
+        ctx->langs_head = node;
+    }
+    ctx->langs_tail = node;
+    ctx->lang_count++;
+    return NULL;
+}
+
+size_t
+st_ext_language_count(const struct st_ext_ctx *ctx)
+{
+    return ctx != NULL ? ctx->lang_count : 0;
+}
+
+const struct st_language *
+st_ext_language(const struct st_ext_ctx *ctx, size_t i)
+{
+    const struct st_language_node *node;
+
+    if (ctx == NULL) {
+        return NULL;
+    }
+    for (node = ctx->langs_head; node != NULL && i > 0;
+         node = node->next, i--) {
+    }
+    return node != NULL ? &node->pub : NULL;
+}
+
+const char *
+st_ext_language_name(const struct st_ext_ctx *ctx, size_t i)
+{
+    const struct st_language *lang = st_ext_language(ctx, i);
+
+    return lang != NULL ? lang->name : NULL;
+}
+
+const struct st_toolchain *
+st_ext_language_toolchain(const struct st_ext_ctx *ctx, size_t i)
+{
+    const struct st_language *lang = st_ext_language(ctx, i);
+
+    return lang != NULL ? lang->toolchain : NULL;
+}
+
+const struct st_toolchain *
+st_ext_language_toolchain_named(const struct st_ext_ctx *ctx,
+                                const char *name)
+{
+    const struct st_language_node *node = find_language_const(ctx, name);
+
+    return node != NULL ? node->pub.toolchain : NULL;
+}
+
+struct st_error *
+st_ext_detect_language(struct st_ext_ctx *ctx, const char *name)
+{
+    struct st_language_node *node = find_language(ctx, name);
+    struct st_error *err;
+
+    if (node == NULL) {
+        return errf(ST_ERR_USAGE, "unknown language: %s", name);
+    }
+    toolchain_reset(&node->tc);
+    node->pub.toolchain = NULL;
+
+    err = node->pub.detect(ctx, node->pub.module_ctx, &node->tc);
+    if (err != NULL) {
+        toolchain_reset(&node->tc); /* free partial fills */
+        return err;
+    }
+    node->pub.toolchain = &node->tc;
+    return NULL;
+}
+
+/* ---------------- check registry ---------------- */
+
+static const struct st_check_node *
+find_check(const struct st_ext_ctx *ctx, const char *language,
+           const char *kind)
+{
+    const struct st_check_node *node;
+
+    if (ctx == NULL || language == NULL || kind == NULL) {
+        return NULL;
+    }
+    for (node = ctx->checks_head; node != NULL; node = node->next) {
+        if (strcmp(node->pub.language, language) == 0 &&
+            strcmp(node->pub.kind, kind) == 0) {
+            return node;
+        }
+    }
+    return NULL;
+}
+
+struct st_error *
+st_ext_register_check(struct st_ext_ctx *ctx, const char *language,
+                      const char *kind, void *probe_spec)
+{
+    struct st_check_node *node;
+
+    if (ctx == NULL || language == NULL || language[0] == '\0' ||
+        kind == NULL || kind[0] == '\0') {
+        return st_error_usage("st_ext_register_check: bad argument");
+    }
+    if (find_check(ctx, language, kind) != NULL) {
+        return errf(ST_ERR_USAGE, "check already registered: %s/%s",
+                    language, kind);
+    }
+    node = calloc(1, sizeof *node);
+    if (node == NULL) {
+        return st_error_internal("out of memory");
+    }
+    node->language_owned = strdup(language);
+    node->kind_owned = strdup(kind);
+    if (node->language_owned == NULL || node->kind_owned == NULL) {
+        free(node->language_owned);
+        free(node->kind_owned);
+        free(node);
+        return st_error_internal("out of memory");
+    }
+    node->pub.language = node->language_owned;
+    node->pub.kind = node->kind_owned;
+    node->pub.probe_spec = probe_spec;
+
+    if (ctx->checks_tail != NULL) {
+        ctx->checks_tail->next = node;
+    } else {
+        ctx->checks_head = node;
+    }
+    ctx->checks_tail = node;
+    ctx->check_count++;
+    return NULL;
+}
+
+size_t
+st_ext_check_count(const struct st_ext_ctx *ctx)
+{
+    return ctx != NULL ? ctx->check_count : 0;
+}
+
+const struct st_check *
+st_ext_check(const struct st_ext_ctx *ctx, size_t i)
+{
+    const struct st_check_node *node;
+
+    if (ctx == NULL) {
+        return NULL;
+    }
+    for (node = ctx->checks_head; node != NULL && i > 0;
+         node = node->next, i--) {
+    }
+    return node != NULL ? &node->pub : NULL;
+}
+
+const char *
+st_ext_check_language(const struct st_ext_ctx *ctx, size_t i)
+{
+    const struct st_check *check = st_ext_check(ctx, i);
+
+    return check != NULL ? check->language : NULL;
+}
+
+const char *
+st_ext_check_kind(const struct st_ext_ctx *ctx, size_t i)
+{
+    const struct st_check *check = st_ext_check(ctx, i);
+
+    return check != NULL ? check->kind : NULL;
+}
+
+void *
+st_ext_check_probe_spec(const struct st_ext_ctx *ctx, size_t i)
+{
+    const struct st_check *check = st_ext_check(ctx, i);
+
+    return check != NULL ? check->probe_spec : NULL;
+}
+
+/* ---------------- builtin module registry ---------------- */
+
+typedef struct st_error *(*st_builtin_init_fn)(struct st_ext_ctx *);
+
+/* Entry points only -- no compiler strings here. Each module registers
+ * itself over the generic ABI. */
+static const st_builtin_init_fn builtin_modules[] = {
+    st_ext_lang_c_init,
+    st_ext_lang_cpp_init,
+};
+
+struct st_error *
+st_ext_init_builtins(struct st_ext_ctx *ctx)
+{
+    size_t i;
+
+    if (ctx == NULL) {
+        return st_error_usage("st_ext_init_builtins: NULL ctx");
+    }
+    for (i = 0; i < sizeof builtin_modules / sizeof builtin_modules[0]; i++) {
+        struct st_error *err = builtin_modules[i](ctx);
+
+        if (err != NULL) {
+            return err;
+        }
+    }
+    return NULL;
+}
+
+/* ---------------- process helper ---------------- */
+
+int
+st_ext_run_capture(char *const argv[], char **out, size_t *out_len)
+{
+    int pfd[2];
+    pid_t pid;
+    int status;
+    char *buf = NULL;
+    size_t len = 0, cap = 0;
+    int rc = -1;
+
+    if (argv == NULL || argv[0] == NULL) {
+        return -1;
+    }
+    if (pipe(pfd) != 0) {
+        return -1;
+    }
+    pid = fork();
+    if (pid < 0) {
+        close(pfd[0]);
+        close(pfd[1]);
+        return -1;
+    }
+    if (pid == 0) {
+        /* child: stdout + stderr into the pipe */
+        close(pfd[0]);
+        if (dup2(pfd[1], STDOUT_FILENO) < 0 ||
+            dup2(pfd[1], STDERR_FILENO) < 0) {
+            _exit(126);
+        }
+        close(pfd[1]);
+        execvp(argv[0], argv);
+        _exit(127); /* shell convention: command not found */
+    }
+
+    close(pfd[1]);
+    /* parent: drain until EOF; keep at most 64 KiB (--version is tiny) */
+    for (;;) {
+        char scratch[4096];
+        ssize_t n = read(pfd[0], scratch, sizeof scratch);
+
+        if (n < 0) {
+            if (errno == EINTR) {
+                continue;
+            }
+            break;
+        }
+        if (n == 0) {
+            break;
+        }
+        if (out != NULL && len < 65536) {
+            size_t take = (size_t)n;
+            char *nbuf;
+
+            if (take > 65536 - len) {
+                take = 65536 - len;
+            }
+            if (cap < len + take) {
+                size_t ncap = cap == 0 ? 256 : cap;
+
+                while (ncap < len + take) {
+                    ncap *= 2;
+                }
+                nbuf = realloc(buf, ncap);
+                if (nbuf == NULL) {
+                    break; /* OOM: stop storing, keep draining below */
+                }
+                buf = nbuf;
+                cap = ncap;
+            }
+            if (cap >= len + take) {
+                memcpy(buf + len, scratch, take);
+                len += take;
+            }
+        }
+    }
+    close(pfd[0]);
+
+    while (waitpid(pid, &status, 0) < 0) {
+        if (errno != EINTR) {
+            rc = -1;
+            goto out;
+        }
+    }
+    rc = WIFEXITED(status) ? WEXITSTATUS(status) : -1;
+
+out:
+    if (out != NULL) {
+        *out = buf;
+    } else {
+        free(buf);
+    }
+    if (out_len != NULL) {
+        *out_len = len;
+    }
+    return rc;
+}

src/ext/abi.h

@@ -0,0 +1,161 @@
+#ifndef ST_EXT_ABI_H
+#define ST_EXT_ABI_H
+
+/*
+ * The extension ABI (plan todo 13).
+ *
+ * Everything a language module can do goes through this header. Core
+ * knows NOTHING language-specific: no compiler names, no CC/CFLAGS
+ * variables, nothing C/C++-specific anywhere outside the module files
+ * (lang_c.c / lang_cpp.c and their private shared header).
+ *
+ * Three generic facilities:
+ *   1. a variable registry  (st_registry_set_var / st_registry_get_var)
+ *      -- the configure generator (todo 16) substitutes from this BY
+ *      NAME; CC/CFLAGS/CXX/CXXFLAGS are registered here by the C/C++
+ *      modules, never hardcoded in core;
+ *   2. a language registry  (st_ext_register_language + detect);
+ *   3. a check registry     (st_ext_register_check).
+ *
+ * Lua-friendliness (todo 19/21): everything is a plain C function
+ * pointer taking an explicitly passed `struct st_ext_ctx *`. There is
+ * NO static state hidden inside the .c files -- a Lua binding only
+ * needs to wrap these functions; the ctx is a userdata it passes back.
+ * Borrowed results stay valid until the next mutation of the ctx (the
+ * registries are linked lists, so node addresses are stable across
+ * registrations).
+ */
+
+#include <stddef.h>
+
+#include "error.h"
+
+/* ---------------- generic variable registry ---------------- */
+
+struct st_registry; /* opaque; owns name/value pairs in insertion order */
+
+struct st_registry *st_registry_new(void);
+void st_registry_free(struct st_registry *r); /* NULL is a no-op */
+
+/* Set or update a variable. `value == NULL` UNSETS (removes) it.
+ * Returns NULL on success, or a heap st_error on allocation failure.
+ * Values are duplicated. */
+struct st_error *st_registry_set_var(struct st_registry *r, const char *name,
+                                     const char *value);
+
+/* Borrowed value, or NULL when unset. */
+const char *st_registry_get_var(const struct st_registry *r,
+                                const char *name);
+
+/* Ordered iteration (insertion order) for the substitution engine. */
+size_t st_registry_var_count(const struct st_registry *r);
+const char *st_registry_var_name(const struct st_registry *r, size_t i);
+const char *st_registry_var_value(const struct st_registry *r, size_t i);
+
+/* ---------------- toolchain result ---------------- */
+
+/* What a successful detection produced. `path` is the command as
+ * invoked (env override value or the candidate that worked); `id` is
+ * derived from the compiler's own `--version` output (vendor name, or
+ * "unknown" when unrecognizable); `version` is likewise ("16.2.1") or
+ * "" when unparsable. All three fields are heap-allocated and owned by
+ * the ctx. */
+struct st_toolchain {
+    char *path;
+    char *id;
+    char *version;
+};
+
+/* ---------------- extension context ---------------- */
+
+struct st_ext_ctx; /* opaque; owns languages, checks, variables */
+
+/* Detects a language's toolchain. MUST fill `out` completely on
+ * success (all three fields freshly strdup'd); on failure it returns a
+ * heap st_error and may leave `out` partially filled -- the ctx frees
+ * partial fields automatically. */
+typedef struct st_error *(*st_lang_detect_fn)(struct st_ext_ctx *ctx,
+                                              void *module_ctx,
+                                              struct st_toolchain *out);
+
+/* A registered language. Borrowed view into the ctx; stable until the
+ * ctx is freed. */
+struct st_language {
+    const char *name;              /* "c", "cxx", ... (owned by the ctx) */
+    st_lang_detect_fn detect;      /* how to find the toolchain */
+    void *module_ctx;              /* opaque module state, passed back */
+    const char *const *var_names;  /* NULL-terminated vars this language
+                                      registers on detection (CC, CFLAGS…) */
+    const struct st_toolchain *toolchain; /* filled on detect; NULL before */
+};
+
+/* A registered check kind ("header" is universal; per-language kinds
+ * arrive with todo 11/12). Borrowed view; stable until ctx free. */
+struct st_check {
+    const char *language;  /* which language this check applies to */
+    const char *kind;      /* "header", "function", ... */
+    void *probe_spec;      /* opaque module data; may be NULL for now */
+};
+
+struct st_ext_ctx *st_ext_ctx_new(void); /* NULL on allocation failure */
+void st_ext_ctx_free(struct st_ext_ctx *ctx); /* NULL is a no-op */
+
+/* The ctx's variable registry (same instance the language modules
+ * write into; what todo 16 substitutes from). */
+struct st_registry *st_ext_var_registry(struct st_ext_ctx *ctx);
+
+/* Registers a language. `var_names` is copied (NULL-terminated array).
+ * Returns NULL on success, or an error for bad arguments / duplicates. */
+struct st_error *st_ext_register_language(struct st_ext_ctx *ctx,
+                                          const char *name,
+                                          st_lang_detect_fn detect,
+                                          void *module_ctx,
+                                          const char *const *var_names);
+
+size_t st_ext_language_count(const struct st_ext_ctx *ctx);
+const struct st_language *st_ext_language(const struct st_ext_ctx *ctx,
+                                          size_t i); /* NULL past end */
+const char *st_ext_language_name(const struct st_ext_ctx *ctx, size_t i);
+const struct st_toolchain *st_ext_language_toolchain(
+    const struct st_ext_ctx *ctx, size_t i);
+const struct st_toolchain *st_ext_language_toolchain_named(
+    const struct st_ext_ctx *ctx, const char *name);
+
+/* Runs the registered detect fn for the named language and stores the
+ * result. Returns NULL on success, or an error (unknown language /
+ * detection failure -- e.g. no compiler found). */
+struct st_error *st_ext_detect_language(struct st_ext_ctx *ctx,
+                                        const char *name);
+
+/* Registers a check kind for a language. Duplicate (language, kind)
+ * pairs are errors. Returns NULL on success. */
+struct st_error *st_ext_register_check(struct st_ext_ctx *ctx,
+                                       const char *language,
+                                       const char *kind, void *probe_spec);
+
+size_t st_ext_check_count(const struct st_ext_ctx *ctx);
+const struct st_check *st_ext_check(const struct st_ext_ctx *ctx,
+                                    size_t i); /* NULL past end */
+const char *st_ext_check_language(const struct st_ext_ctx *ctx, size_t i);
+const char *st_ext_check_kind(const struct st_ext_ctx *ctx, size_t i);
+void *st_ext_check_probe_spec(const struct st_ext_ctx *ctx, size_t i);
+
+/* ---------------- builtin module registry ---------------- */
+
+/* Runs the builtin module entry points (lang_c, lang_cpp). The modules
+ * register themselves through the generic ABI above -- the table here
+ * names entry points only; every compiler string lives in the modules.
+ * Returns NULL on success. */
+struct st_error *st_ext_init_builtins(struct st_ext_ctx *ctx);
+
+/* ---------------- process helper for module authors ---------------- */
+
+/* Runs argv (NULL-terminated; argv[0] looked up via execvp on PATH)
+ * and captures stdout+stderr into *out (malloc'd; caller frees; may be
+ * NULL to discard) with *out_len. Returns the child's exit status
+ * (0-255), or -1 when it could not be spawned (e.g. ENOENT) or was
+ * killed by a signal. No timeout: intended for short commands like
+ * `cc --version`. */
+int st_ext_run_capture(char *const argv[], char **out, size_t *out_len);
+
+#endif /* ST_EXT_ABI_H */

src/ext/api.c

@@ -0,0 +1,266 @@
+/*
+ * src/ext/api.c - the Lua API over the extension ABI (plan todo 21).
+ *
+ * See src/ext/api.h for the full contract: st_ext_bridge_lua() flushes a
+ * Lua runtime's registrations into a struct st_ext_ctx (thin shim over
+ * the todo-13 ABI -- no registry reimplementation, no DSL mutation), and
+ * st_lua_probe_run() resolves a probe spec by driving the detected C
+ * toolchain through st_ext_run_capture (argv only, never a shell).
+ *
+ * The probe run here is a DIRECT compile/link/run for the acceptance
+ * test only. Feature resolution (todo 14) and configure-script probe
+ * generation (todo 12) consume the registered checks later; this file
+ * stops at "run a spec against a toolchain and report pass/fail".
+ */
+
+#ifndef _POSIX_C_SOURCE
+#define _POSIX_C_SOURCE 200809L /* mkstemp, write, unlink, strdup */
+#endif
+
+#include "api.h"
+
+#include <errno.h>
+#include <string.h>
+#include <unistd.h>
+
+/* The language v1 custom checks compile against: custom checks are C
+ * snippets, so they belong to the builtin "c" module's toolchain. This
+ * is the one language string this bridge knows; it is NOT a core string
+ * (core never sees it -- api.c is extension territory, like lang_c.c). */
+#define ST_LUA_CHECK_LANGUAGE "c"
+
+/* ------------------------------------------------------------------ */
+/* language detect stub                                                */
+/* ------------------------------------------------------------------ */
+
+/* A Lua-registered language has no generic detection in v1: there is no
+ * way for an arbitrary extension to express "here is my compiler" that
+ * survives the sandbox (which has no process/io surface). Real detection
+ * for third-party languages lands in todo 22 (example fortran module).
+ * Until then detecting a Lua language is a clean usage error -- a Lua
+ * language still REGISTERS (lands in the ctx, enumerable, name visible)
+ * but its toolchain cannot be detected. */
+static struct st_error *
+lua_lang_detect(struct st_ext_ctx *ctx, void *module_ctx,
+                struct st_toolchain *out)
+{
+    (void)ctx;
+    (void)module_ctx;
+    (void)out;
+    return st_error_usage("Lua-registered language has no detection yet "
+                          "(todo 22)");
+}
+
+/* ------------------------------------------------------------------ */
+/* bridge                                                              */
+/* ------------------------------------------------------------------ */
+
+struct st_error *
+st_ext_bridge_lua(struct st_ext_ctx *ctx, struct st_lua_rt *rt)
+{
+    struct st_error *err;
+    size_t i, n;
+
+    if (ctx == NULL || rt == NULL) {
+        return st_error_usage("st_ext_bridge_lua: NULL argument");
+    }
+
+    /* Languages first, then checks (checks reference a language; the
+     * builtin "c" module is already registered by discovery/init). */
+    n = st_lua_language_count(rt);
+    for (i = 0; i < n; i++) {
+        const char *name = st_lua_language_name(rt, i);
+
+        err = st_ext_register_language(ctx, name, lua_lang_detect, NULL,
+                                       NULL);
+        if (err != NULL) {
+            return err;
+        }
+    }
+
+    n = st_lua_check_count(rt);
+    for (i = 0; i < n; i++) {
+        const char *name = st_lua_check_name(rt, i);
+        void *spec = st_lua_check_probe_spec(rt, i);
+
+        /* The Lua check NAME becomes the ABI check KIND; the spec's own
+         * `kind` field (compile/link/run) is the PROBE MODE and stays
+         * inside the spec. probe_spec is BORROWED (owned by the rt --
+         * see api.h ownership note). */
+        err = st_ext_register_check(ctx, ST_LUA_CHECK_LANGUAGE, name, spec);
+        if (err != NULL) {
+            return err;
+        }
+    }
+    return NULL;
+}
+
+/* ------------------------------------------------------------------ */
+/* probe run                                                           */
+/* ------------------------------------------------------------------ */
+
+/* Grow a heap argv by one element (kept NULL-terminated). Returns 0 or
+ * -1 on OOM. */
+static int
+argv_push(char ***argv, size_t *argc, const char *s)
+{
+    char **na = realloc(*argv, (*argc + 2) * sizeof *na);
+
+    if (na == NULL) {
+        return -1;
+    }
+    *argv = na;
+    (*argv)[(*argc)++] = (char *)s;
+    (*argv)[*argc] = NULL;
+    return 0;
+}
+
+/* Copy the captured compiler output into *errbuf (or free it). Sets
+ * *errbuf = NULL when the probe passed or there was nothing captured. */
+static void
+set_errbuf(char **errbuf, char *captured, int passed)
+{
+    if (errbuf == NULL) {
+        free(captured);
+        return;
+    }
+    if (passed) {
+        free(captured);
+        *errbuf = NULL;
+    } else if (captured != NULL) {
+        *errbuf = captured; /* hand ownership to the caller */
+    } else {
+        *errbuf = strdup("probe failed (no compiler output)");
+    }
+}
+
+int
+st_lua_probe_run(const struct st_toolchain *tc,
+                 const struct st_lua_probe_spec *spec, char **errbuf)
+{
+    char src_tmpl[] = "/tmp/stprobe_src_XXXXXX";
+    char out_tmpl[] = "/tmp/stprobe_out_XXXXXX";
+    int sfd;
+    int ofd;
+    size_t off;
+    size_t slen;
+    size_t nlink = 0;
+    size_t i;
+    size_t argc = 0;
+    char **argv = NULL;
+    char *captured = NULL;
+    size_t captured_len = 0;
+    int compile_only;
+    int run_it;
+    int rc;
+
+    if (errbuf != NULL) {
+        *errbuf = NULL;
+    }
+    if (tc == NULL || tc->path == NULL || tc->path[0] == '\0' ||
+        spec == NULL || spec->kind == NULL || spec->source == NULL) {
+        if (errbuf != NULL) {
+            *errbuf = strdup("probe: missing toolchain or spec");
+        }
+        return -1;
+    }
+
+    compile_only = strcmp(spec->kind, "compile") == 0;
+    run_it = strcmp(spec->kind, "run") == 0;
+
+    slen = strlen(spec->source);
+    if (spec->link != NULL) {
+        while (spec->link[nlink] != NULL) {
+            nlink++;
+        }
+    }
+
+    /* Write the source to a unique temp file. The "-x c" flag below (not
+     * a ".c" suffix -- mkstemp needs the template to END in XXXXXX, so no
+     * suffix is possible) forces the compiler to classify it as C: an
+     * extensionless file is otherwise treated as a linker input and would
+     * "pass" every probe. mkstemp -> no shell, no path collision; the
+     * source's shell metacharacters are just bytes in a file. */
+    sfd = mkstemp(src_tmpl);
+    if (sfd < 0) {
+        if (errbuf != NULL) {
+            *errbuf = strdup("probe: cannot create temp source file");
+        }
+        return -1;
+    }
+    /* A unique output path (the file is created empty; cc overwrites it).
+     * Non-fatal if it fails: the literal template still names a usable
+     * path and every probe unlinks it afterwards. */
+    ofd = mkstemp(out_tmpl);
+    if (ofd >= 0) {
+        (void)close(ofd);
+    }
+    off = 0;
+    while (off < slen) {
+        ssize_t w = write(sfd, spec->source + off, slen - off);
+
+        if (w < 0) {
+            if (errno == EINTR) {
+                continue;
+            }
+            break;
+        }
+        off += (size_t)w;
+    }
+    (void)close(sfd);
+    if (off != slen) {
+        (void)unlink(src_tmpl);
+        if (errbuf != NULL) {
+            *errbuf = strdup("probe: cannot write temp source file");
+        }
+        return -1;
+    }
+
+    /* <cc> -x c [-c] <src> -o <out> [link...] */
+    if (argv_push(&argv, &argc, tc->path) != 0 ||
+        argv_push(&argv, &argc, "-x") != 0 ||
+        argv_push(&argv, &argc, "c") != 0 ||
+        (compile_only && argv_push(&argv, &argc, "-c") != 0) ||
+        argv_push(&argv, &argc, src_tmpl) != 0 ||
+        argv_push(&argv, &argc, "-o") != 0 ||
+        argv_push(&argv, &argc, out_tmpl) != 0) {
+        goto oom;
+    }
+    for (i = 0; i < nlink; i++) {
+        if (argv_push(&argv, &argc, spec->link[i]) != 0) {
+            goto oom;
+        }
+    }
+
+    /* compile (and link) -- `out_tmpl` already exists from the mkstemp
+     * placeholder above; cc overwrites it. */
+    rc = st_ext_run_capture(argv, &captured, &captured_len);
+
+    if (rc == 0 && run_it) {
+        char *runargv[2] = { out_tmpl, NULL };
+        char *rcap = NULL;
+        size_t rclen = 0;
+
+        free(captured);
+        captured = NULL;
+        captured_len = 0;
+        rc = st_ext_run_capture(runargv, &rcap, &rclen);
+        free(rcap);
+    }
+
+    free(argv);
+    (void)unlink(out_tmpl);
+    (void)unlink(src_tmpl);
+    set_errbuf(errbuf, captured, rc == 0);
+    return rc == 0 ? 1 : 0;
+
+oom:
+    free(argv);
+    (void)unlink(out_tmpl);
+    (void)unlink(src_tmpl);
+    free(captured);
+    if (errbuf != NULL) {
+        *errbuf = strdup("probe: out of memory");
+    }
+    return -1;
+}

src/ext/api.h

@@ -0,0 +1,140 @@
+#ifndef ST_EXT_API_H
+#define ST_EXT_API_H
+
+/*
+ * The Lua API over the extension ABI (plan todo 21).
+ *
+ * Todo 19 shipped the sandboxed Lua runtime and let extensions RECORD
+ * registrations into the runtime's own lists (st_lua_check_* /
+ * st_lua_language_*). Todo 13 shipped the extension ABI (abi.h) with the
+ * real check/language registries a builtin module (lang_c.c / lang_cpp.c)
+ * registers into. THIS header bridges the two: it flushes a Lua runtime's
+ * registrations into a struct st_ext_ctx so a Lua-registered check or
+ * language behaves exactly like a builtin.
+ *
+ * The bridge (st_ext_bridge_lua) is a thin shim -- it does NOT reimplement
+ * the registry in Lua and does NOT let extensions mutate the DSL grammar:
+ *
+ *   - each Lua check       -> st_ext_register_check(ctx, "c", name, spec)
+ *   - each Lua language    -> st_ext_register_language(ctx, name, detect, ...)
+ *
+ * PROBE SPEC (the one piece of module data this todo adds):
+ *
+ *   A Lua extension describes a custom check with a Lua table:
+ *
+ *     st.register_check("magic", {
+ *       kind   = "compile",                -- "compile" | "link" | "run"
+ *       source = "int main(void){return 0;}",
+ *       link   = { "-lfoo", "-lbar" },     -- optional
+ *     })
+ *
+ *   which the runtime materializes into the C struct below and stores in
+ *   the runtime registry's opaque `probe_spec` slot. `kind` is the PROBE
+ *   MODE (compile / link / run), not the ABI's check "kind" (that slot
+ *   gets the check's NAME -- see the bridge note). `source` is a C
+ *   snippet; `link` are extra argv elements for the link step. v1 keeps
+ *   everything STRINGS: no Lua functions as probe callbacks (documented
+ *   limitation; a later todo may allow functions).
+ *
+ *   RESOLVING a spec = compiling `source` with the detected C toolchain
+ *   and asserting the compile/link/run succeeded. st_lua_probe_run() does
+ *   exactly that (driving the compiler through st_ext_run_capture, argv
+ *   only -- never a shell string) and is what the acceptance test uses
+ *   directly. The registry-driven resolution that todo 14/16 perform is
+ *   OUT of scope here; those todos consume the registered checks and call
+ *   the probe runner (or its generated-configure equivalent, todo 12).
+ *
+ * OWNERSHIP (the one subtle contract):
+ *
+ *   A probe spec is heap-allocated by the Lua runtime when it parses the
+ *   table, OWNED BY THE RUNTIME's registry entry, and freed when the
+ *   runtime is freed. The ABI ctx stores only a BORROWED pointer to it
+ *   (abi.h's probe_spec slot is opaque module data the ctx never frees).
+ *   Consequence: the ctx must not be used to read probe specs after the
+ *   runtime that produced them is freed. A bridge call is therefore
+ *   expected to be followed by (ctx, rt) being used together and freed in
+ *   that order (rt last). This mirrors how lang_c.c's probe_spec would be
+ *   owned by the module that registered it.
+ *
+ * Why st_lua_probe_spec_free is a STATIC INLINE here rather than a
+ * function in api.c: the Lua runtime (lua.c, todo 19) must free specs it
+ * owns, but tests/unit/test_lua.c and test_discovery.c link lua.c WITHOUT
+ * api.c. A static inline in this header keeps lua.c free of any api.c
+ * symbol reference while still sharing one spec layout. Do NOT move the
+ * free into api.c without also fixing those two frozen test link lines.
+ */
+
+#include <stdlib.h>
+
+#include "abi.h"
+#include "lua.h"
+
+/* A custom check's probe spec, materialized from the Lua table
+ * { kind = "compile"|"link"|"run", source = "<C snippet>",
+ *   link = { "-lfoo", ... } } (link optional). All fields are owned
+ * (strdup'd) and freed together by st_lua_probe_spec_free(). */
+struct st_lua_probe_spec {
+    char *kind;    /* "compile" | "link" | "run" */
+    char *source;  /* the C snippet (NUL-terminated, owned) */
+    char **link;   /* NULL-terminated extra link args, or NULL when absent */
+};
+
+/* Frees a spec (all fields). NULL is a safe no-op. Static inline so the
+ * runtime (lua.c) can call it without linking api.c. */
+static inline void
+st_lua_probe_spec_free(struct st_lua_probe_spec *spec)
+{
+    size_t i;
+
+    if (spec == NULL) {
+        return;
+    }
+    free(spec->kind);
+    free(spec->source);
+    if (spec->link != NULL) {
+        for (i = 0; spec->link[i] != NULL; i++) {
+            free(spec->link[i]);
+        }
+        free(spec->link);
+    }
+    free(spec);
+}
+
+/* Flushes the Lua runtime's registrations into the ABI ctx:
+ *
+ *   languages: st_ext_register_language(ctx, name, lua_lang_detect, ...)
+ *   checks:    st_ext_register_check(ctx, "c", name, probe_spec)
+ *
+ * where "c" is the language a v1 custom check compiles against (v1 custom
+ * checks are C snippets; the C toolchain -- builtin "c" module -- is what
+ * st_lua_probe_run drives). The language detect fn is a documented v1
+ * stub (Lua languages have no generic detection yet; todo 22 wires it).
+ *
+ * Returns NULL on success. Any registration error (duplicate name that
+ * collides with a builtin, e.g. a Lua check named "header", or a Lua
+ * language named "c") is returned unchanged. Idempotency is NOT promised:
+ * a second bridge re-registers the same names and fails on duplicates. */
+struct st_error *st_ext_bridge_lua(struct st_ext_ctx *ctx,
+                                   struct st_lua_rt *rt);
+
+/* Runs a probe spec against a detected C toolchain (`tc->path` is the
+ * compiler command, e.g. the CC the builtin "c" module detected):
+ *
+ *   compile  ->  <cc> -c <tmp.c> -o <tmp.o>
+ *   link     ->  <cc> <tmp.c> -o <tmp> [link...]
+ *   run      ->  link, then execute <tmp>
+ *
+ * The source is written to a mkstemp'd file and every argument is passed
+ * as an argv element through st_ext_run_capture (execvp) -- NEVER through
+ * a shell, so shell metacharacters in `source` or `link` are inert.
+ *
+ * Returns 1 when the required step(s) all exit 0 (probe passed), 0 when
+ * any step fails (compiler non-zero exit or spawn failure), or -1 on a
+ * setup error (NULL toolchain/spec, temp-file creation/write failure, or
+ * OOM). When `errbuf` is non-NULL and the probe does NOT pass, *errbuf is
+ * set to a malloc'd copy of the captured compiler stderr/stdout (caller
+ * frees); on success *errbuf is set to NULL. */
+int st_lua_probe_run(const struct st_toolchain *tc,
+                     const struct st_lua_probe_spec *spec, char **errbuf);
+
+#endif /* ST_EXT_API_H */

src/ext/discovery.c

@@ -0,0 +1,465 @@
+/*
+ * src/ext/discovery.c - extension discovery and loading (plan todo 20).
+ *
+ * See src/ext/discovery.h for the full contract: the discovery order
+ * (builtin C modules -> --ext-dir -> STUPIDTOOLS_EXT -> user dir ->
+ * builtin dir), the per-directory scan rules (regular *.lua files,
+ * bytewise order, missing dirs are no-ops), and the FAIL-FAST error
+ * contract ("extension load failed: <path>: ...").
+ *
+ * Everything loads through the sandboxed Lua runtime (st_lua_run); the
+ * builtin C/C++ language modules go through st_ext_init_builtins() into
+ * the ABI ctx. No language is hardcoded here.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef _POSIX_C_SOURCE
+#define _POSIX_C_SOURCE 200809L /* strdup, strtok_r, stat, readdir */
+#endif
+
+#include <dirent.h>
+#include <errno.h>
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+
+#include "abi.h"
+#include "discovery.h"
+#include "lua.h"
+
+/* Compile-time override for the shipped builtin extension directory;
+ * the default is resolved relative to the current working directory
+ * (repo-layout friendly -- see builtin-ext/README.md). An installed
+ * layout overrides it, e.g.
+ *   -DSTUPIDTOOLS_BUILTIN_EXT_DIR='"<prefix>/share/stupidtools/ext"'
+ */
+#ifndef STUPIDTOOLS_BUILTIN_EXT_DIR
+#define STUPIDTOOLS_BUILTIN_EXT_DIR "builtin-ext"
+#endif
+
+/* ---------------- logging ---------------- */
+
+/* NULL -> default stderr logger. The one piece of module state; the
+ * task explicitly asks for a minimal hook, and threading a logger
+ * parameter through the whole chain would churn the public signature. */
+static st_ext_log_fn g_log_fn;
+
+void
+st_ext_discover_set_log(st_ext_log_fn fn)
+{
+	g_log_fn = fn;
+}
+
+void
+st_ext_discover_log(const char *fmt, ...)
+{
+	va_list ap;
+
+	va_start(ap, fmt);
+	if (g_log_fn != NULL) {
+		g_log_fn(fmt, ap);
+	} else {
+		vfprintf(stderr, fmt, ap);
+	}
+	va_end(ap);
+}
+
+/* ---------------- small helpers ---------------- */
+
+/* Comma-joined names of registrations [from, count) via the accessor;
+ * malloc'd, NULL when the range is empty or on allocation failure. */
+static char *
+names_join(const struct st_lua_rt *rt, size_t from, size_t count,
+           const char *(*name_at)(const struct st_lua_rt *, size_t))
+{
+	size_t i, total = 0;
+	char *buf, *p;
+
+	if (count <= from) return NULL;
+	for (i = from; i < count; i++) {
+		const char *n = name_at(rt, i);
+		if (n != NULL) total += strlen(n) + 2; /* ", " separator */
+	}
+	if (total == 0) return NULL;
+	buf = malloc(total + 1);
+	if (buf == NULL) return NULL;
+	p = buf;
+	for (i = from; i < count; i++) {
+		const char *n = name_at(rt, i);
+		size_t len;
+
+		if (n == NULL) continue;
+		len = strlen(n);
+		if (p != buf) {
+			*p++ = ',';
+			*p++ = ' ';
+		}
+		memcpy(p, n, len);
+		p += len;
+	}
+	*p = '\0';
+	return buf;
+}
+
+/* "c, cxx" style list of the ABI ctx's language names (malloc'd). */
+static char *
+abi_language_names(const struct st_ext_ctx *ctx)
+{
+	size_t i, n = st_ext_language_count(ctx), total = 0;
+	char *buf, *p;
+
+	for (i = 0; i < n; i++) {
+		const char *nm = st_ext_language_name(ctx, i);
+		if (nm != NULL) total += strlen(nm) + 2;
+	}
+	if (total == 0) return NULL;
+	buf = malloc(total + 1);
+	if (buf == NULL) return NULL;
+	p = buf;
+	for (i = 0; i < n; i++) {
+		const char *nm = st_ext_language_name(ctx, i);
+		size_t len;
+
+		if (nm == NULL) continue;
+		len = strlen(nm);
+		if (p != buf) {
+			*p++ = ',';
+			*p++ = ' ';
+		}
+		memcpy(p, nm, len);
+		p += len;
+	}
+	*p = '\0';
+	return buf;
+}
+
+/* Reads a whole file into a freshly malloc'd NUL-terminated buffer.
+ * NULL on success (buffer in *out, length in *out_len); an st_error on
+ * failure (I/O -> ST_ERR_IO naming the file, OOM -> ST_ERR_INTERNAL). */
+static struct st_error *
+read_module_source(const char *path, char **out, size_t *out_len)
+{
+	FILE *f;
+	long size;
+	char *buf;
+	size_t got;
+	size_t need;
+	struct st_error *err;
+
+	f = fopen(path, "rb");
+	if (f == NULL) goto io_fail;
+	if (fseek(f, 0, SEEK_END) != 0) {
+		(void)fclose(f);
+		goto io_fail;
+	}
+	size = ftell(f);
+	if (size < 0 || fseek(f, 0, SEEK_SET) != 0) {
+		(void)fclose(f);
+		goto io_fail;
+	}
+	buf = malloc((size_t)size + 1);
+	if (buf == NULL) {
+		(void)fclose(f);
+		return st_error_internal("extension load failed: out of memory");
+	}
+	got = fread(buf, 1, (size_t)size, f);
+	if (got != (size_t)size) {
+		/* short read: close BEFORE the error return (no leak) */
+		(void)fclose(f);
+		free(buf);
+		goto io_fail;
+	}
+	if (fclose(f) != 0) {
+		free(buf);
+		goto io_fail;
+	}
+	buf[size] = '\0';
+	*out = buf;
+	*out_len = (size_t)size;
+	return NULL;
+
+io_fail:
+	need = strlen(path) + 64;
+	buf = malloc(need);
+	if (buf == NULL)
+		return st_error_internal("extension load failed: out of memory");
+	(void)snprintf(buf, need, "extension load failed: %s: %s", path,
+	    strerror(errno));
+	err = st_error_io(buf);
+	free(buf);
+	return err;
+}
+
+/* Wraps the runtime's error so the message names the module file. The
+ * category is preserved (sandbox violations stay ST_ERR_KDL_SCHEMA so
+ * st_error_print keeps its [kdl-schema] marker); the runtime's own
+ * message already carries "<file>:<line>: " via chunkname propagation. */
+static struct st_error *
+module_load_error(struct st_error *inner, const char *path)
+{
+	enum st_error_category cat = st_error_category_of(inner);
+	const char *msg = st_error_message(inner);
+	size_t need = strlen(path) + (msg != NULL ? strlen(msg) : 12) + 32;
+	char *buf = malloc(need);
+	struct st_error *err;
+
+	if (buf == NULL) {
+		st_error_free(inner);
+		return st_error_internal("extension load failed: out of memory");
+	}
+	(void)snprintf(buf, need, "extension load failed: %s: %s", path,
+	    msg != NULL ? msg : "(no message)");
+	err = st_error_new(cat, buf);
+	free(buf);
+	st_error_free(inner);
+	return err;
+}
+
+/* Logs one loaded module with the registrations it added, computed from
+ * the runtime's counts before/after the load (registrations only ever
+ * append, so the additions are exactly [before, after)). */
+static void
+log_module(struct st_lua_rt *rt, const char *path, size_t checks_before,
+           size_t langs_before)
+{
+	size_t checks_after = st_lua_check_count(rt);
+	size_t langs_after = st_lua_language_count(rt);
+	char *ck = names_join(rt, checks_before, checks_after, st_lua_check_name);
+	char *lg = names_join(rt, langs_before, langs_after,
+	                      st_lua_language_name);
+
+	if (ck != NULL && lg != NULL) {
+		st_ext_discover_log("loaded extension: %s — checks: %zu (%s) "
+		    "languages: %zu (%s)\n", path,
+		    checks_after - checks_before, ck,
+		    langs_after - langs_before, lg);
+	} else if (ck != NULL) {
+		st_ext_discover_log("loaded extension: %s — checks: %zu (%s) "
+		    "languages: %zu\n", path, checks_after - checks_before, ck,
+		    langs_after - langs_before);
+	} else if (lg != NULL) {
+		st_ext_discover_log("loaded extension: %s — checks: %zu "
+		    "languages: %zu (%s)\n", path, checks_after - checks_before,
+		    langs_after - langs_before, lg);
+	} else {
+		st_ext_discover_log("loaded extension: %s — checks: %zu "
+		    "languages: %zu\n", path, checks_after - checks_before,
+		    langs_after - langs_before);
+	}
+	free(ck);
+	free(lg);
+}
+
+/* Logs the builtin C modules from the ACTUAL ABI registrations. */
+static void
+log_builtins(const struct st_ext_ctx *ctx)
+{
+	char *names = abi_language_names(ctx);
+
+	if (names != NULL) {
+		st_ext_discover_log("loaded builtin modules: languages: %s\n",
+		    names);
+		free(names);
+	} else {
+		st_ext_discover_log("loaded builtin modules\n");
+	}
+}
+
+/* Loads one module file into the sandbox. NULL on success; on failure a
+ * wrapped error naming the file (the fail-fast contract). */
+static struct st_error *
+load_module(struct st_lua_rt *rt, const char *path)
+{
+	char *src = NULL;
+	size_t len = 0;
+	size_t c_before = st_lua_check_count(rt);
+	size_t l_before = st_lua_language_count(rt);
+	struct st_error *err = read_module_source(path, &src, &len);
+
+	if (err != NULL) return err;
+	err = st_lua_run(rt, src, path); /* chunkname = full path */
+	free(src);
+	if (err != NULL) return module_load_error(err, path);
+	log_module(rt, path, c_before, l_before);
+	return NULL;
+}
+
+static int
+cmp_str(const void *a, const void *b)
+{
+	const char *const *sa = a;
+	const char *const *sb = b;
+
+	return strcmp(*sa, *sb);
+}
+
+/* Scans one directory for *.lua modules and loads them in bytewise
+ * order. NULL on success; a missing directory is a documented no-op. */
+static struct st_error *
+discover_dir(struct st_lua_rt *rt, const char *dir)
+{
+	DIR *d = opendir(dir);
+	struct dirent *e;
+	char **names = NULL;
+	size_t n = 0, cap = 0, i;
+	struct st_error *err = NULL;
+
+	if (d == NULL) return NULL; /* missing dir: silent no-op */
+	while ((e = readdir(d)) != NULL) {
+		size_t nlen;
+
+		if (e->d_name[0] == '.') continue; /* ., .. and dotfiles */
+		nlen = strlen(e->d_name);
+		if (nlen < 4 || strcmp(e->d_name + nlen - 4, ".lua") != 0)
+			continue;
+		if (n == cap) {
+			size_t ncap = cap == 0 ? 16 : cap * 2;
+			char **nn = realloc(names, ncap * sizeof *nn);
+
+			if (nn == NULL) {
+				err = st_error_internal("extension load failed: "
+				    "out of memory");
+				break;
+			}
+			names = nn;
+			cap = ncap;
+		}
+		names[n] = strdup(e->d_name);
+		if (names[n] == NULL) {
+			err = st_error_internal("extension load failed: "
+			    "out of memory");
+			break;
+		}
+		n++;
+	}
+	(void)closedir(d);
+	if (err != NULL) {
+		for (i = 0; i < n; i++) free(names[i]);
+		free(names);
+		return err;
+	}
+	if (n > 1)
+		qsort(names, n, sizeof *names, cmp_str);
+	for (i = 0; i < n && err == NULL; i++) {
+		char *path;
+		struct stat st;
+		size_t dlen = strlen(dir);
+		size_t nlen = strlen(names[i]);
+
+		while (dlen > 0 && dir[dlen - 1] == '/') dlen--;
+		path = malloc(dlen + 1 + nlen + 1);
+		if (path == NULL) {
+			err = st_error_internal("extension load failed: "
+			    "out of memory");
+			break;
+		}
+		memcpy(path, dir, dlen);
+		path[dlen] = '/';
+		memcpy(path + dlen + 1, names[i], nlen + 1);
+		if (stat(path, &st) != 0 || !S_ISREG(st.st_mode)) {
+			/* vanished between readdir and stat, or non-regular
+			 * (a directory named *.lua etc.): skip */
+			free(path);
+			continue;
+		}
+		err = load_module(rt, path);
+		free(path);
+	}
+	for (i = 0; i < n; i++) free(names[i]);
+	free(names);
+	return err;
+}
+
+/* STUPIDTOOLS_EXT: colon-separated directory list (no escaping); empty
+ * entries are skipped so a trailing colon is harmless. */
+static struct st_error *
+discover_env_dirs(struct st_lua_rt *rt)
+{
+	const char *env = getenv("STUPIDTOOLS_EXT");
+	char *copy;
+	char *save = NULL;
+	char *tok;
+	struct st_error *err = NULL;
+
+	if (env == NULL || env[0] == '\0') return NULL;
+	copy = strdup(env);
+	if (copy == NULL)
+		return st_error_internal("extension load failed: out of memory");
+	for (tok = strtok_r(copy, ":", &save); tok != NULL && err == NULL;
+	     tok = strtok_r(NULL, ":", &save)) {
+		if (tok[0] != '\0') err = discover_dir(rt, tok);
+	}
+	free(copy);
+	return err;
+}
+
+/* User extension dir: $XDG_DATA_HOME/stupidtools/ext (canonical), else
+ * $HOME/.local/share/stupidtools/ext; skipped when neither is usable. */
+static struct st_error *
+discover_user_dir(struct st_lua_rt *rt)
+{
+	const char *xdg = getenv("XDG_DATA_HOME");
+	const char *home;
+	char *dir;
+	size_t need;
+	struct st_error *err;
+
+	if (xdg == NULL || xdg[0] == '\0') {
+		home = getenv("HOME");
+		if (home == NULL || home[0] == '\0') return NULL;
+		need = strlen(home) + sizeof "/.local/share/stupidtools/ext";
+		dir = malloc(need);
+		if (dir == NULL)
+			return st_error_internal("extension load failed: "
+			    "out of memory");
+		(void)snprintf(dir, need, "%s/.local/share/stupidtools/ext",
+		    home);
+	} else {
+		need = strlen(xdg) + sizeof "/stupidtools/ext";
+		dir = malloc(need);
+		if (dir == NULL)
+			return st_error_internal("extension load failed: "
+			    "out of memory");
+		(void)snprintf(dir, need, "%s/stupidtools/ext", xdg);
+	}
+	err = discover_dir(rt, dir);
+	free(dir);
+	return err;
+}
+
+/* ---------------- public entry point ---------------- */
+
+struct st_error *
+st_ext_discover(struct st_ext_ctx *ctx, struct st_lua_rt *rt,
+                const char *const *extra_dirs, size_t n_dirs)
+{
+	struct st_error *err;
+	size_t i;
+
+	if (rt == NULL) return st_error_internal("st_ext_discover: NULL runtime");
+	if (ctx == NULL) return st_error_usage("st_ext_discover: NULL extension context");
+
+	/* Builtin C/C++ language modules first -- the foundation; the
+	 * builtin-ext DIRECTORY is scanned below with the other dirs. */
+	err = st_ext_init_builtins(ctx);
+	if (err != NULL) return err;
+	log_builtins(ctx);
+
+	for (i = 0; i < n_dirs && err == NULL; i++) {
+		if (extra_dirs[i] != NULL && extra_dirs[i][0] != '\0')
+			err = discover_dir(rt, extra_dirs[i]);
+	}
+	if (err != NULL) return err;
+
+	err = discover_env_dirs(rt);
+	if (err != NULL) return err;
+
+	err = discover_user_dir(rt);
+	if (err != NULL) return err;
+
+	return discover_dir(rt, STUPIDTOOLS_BUILTIN_EXT_DIR);
+}

src/ext/discovery.h

@@ -0,0 +1,95 @@
+#ifndef ST_EXT_DISCOVERY_H
+#define ST_EXT_DISCOVERY_H
+
+/*
+ * Extension discovery and loading (plan todo 20).
+ *
+ * st_ext_discover() loads every extension known to a stupidtools run
+ * into a freshly created ABI context + sandboxed Lua runtime. Search
+ * order:
+ *
+ *   1. the BUILTIN C language modules -- st_ext_init_builtins() puts
+ *      the "c"/"cxx" languages (and their checks) into the ABI ctx;
+ *   2. each --ext-dir directory (extra_dirs, in the given order);
+ *   3. each STUPIDTOOLS_EXT directory (colon-separated, empty entries
+ *      skipped);
+ *   4. the USER directory: $XDG_DATA_HOME/stupidtools/ext, falling
+ *      back to $HOME/.local/share/stupidtools/ext when XDG_DATA_HOME is
+ *      unset or empty; skipped entirely when neither variable yields a
+ *      path. XDG_DATA_HOME is the canonical convention.
+ *   5. the BUILTIN directory: the STUPIDTOOLS_BUILTIN_EXT_DIR macro
+ *      (default "builtin-ext", resolved relative to the current working
+ *      directory of the running binary; an installed layout overrides
+ *      it at compile time, e.g.
+ *      -DSTUPIDTOOLS_BUILTIN_EXT_DIR='"<prefix>/share/stupidtools/ext"').
+ *
+ * Directory scanning contract:
+ *   - only REGULAR files whose name ends in ".lua" are loaded (dotfiles
+ *     excluded). Entries arrive from readdir() as bare basenames -- no
+ *     directory entry can contain a path separator, so a malicious
+ *     name like "../evil.lua" cannot occur, let alone escape the dir.
+ *     Symlinks are followed (stat); pointing one at a file outside the
+ *     directory is the caller's own responsibility in an explicitly
+ *     configured dir.
+ *   - within a directory, modules load in bytewise-lexicographic order
+ *     (deterministic, independent of readdir order);
+ *   - a directory that does not exist is silently skipped (a no-op --
+ *     env lists routinely contain stale paths); an empty directory is
+ *     likewise a no-op; an EMPTY .lua file loads as an empty chunk and
+ *     is a clean no-op;
+ *   - each module is read into memory and run via st_lua_run() with the
+ *     full path as chunkname, so Lua diagnostics name file AND line.
+ *     Note: st_lua_run() compiles strlen(chunk) bytes, so a file with
+ *     embedded NULs is truncated at the first NUL before compilation;
+ *     binary garbage then fails with a syntax error naming the file.
+ *
+ * Failure contract: FAIL-FAST. The first module that fails to load
+ * (syntax error, runtime error, sandbox violation, unreadable file)
+ * aborts discovery; the returned st_error's message starts with
+ * "extension load failed: <path>: ..." and preserves the underlying
+ * category (sandbox violations stay ST_ERR_KDL_SCHEMA, other Lua
+ * failures ST_ERR_INTERNAL, read failures ST_ERR_IO). Later modules
+ * are NOT attempted. Deliberate choice: a broken extension should be
+ * loud, and a half-loaded extension set is a confusing state.
+ *
+ * Lifecycle notes:
+ *   - st_ext_discover() calls st_ext_init_builtins() itself; call it
+ *     ONCE per ctx (a second call re-registers the builtins and fails
+ *     on duplicate registrations);
+ *   - the ABI ctx receives the builtin modules only; Lua registrations
+ *     stay in the runtime's own registries (st_lua_check_* /
+ *     st_lua_language_*) -- todo 21 bridges them into the ctx.
+ *
+ * Logging: st_ext_discover_log() prints to stderr by default;
+ * st_ext_discover_set_log() installs a vfprintf-style callback (NULL
+ * restores the default). Discovery logs one line per loaded module:
+ *
+ *   loaded extension: <path> — checks: <n> (<names>) languages: <m> (<names>)
+ *
+ * where the counts and names come from the ACTUAL registrations the
+ * module performed (enumerated from the runtime), never from the file
+ * name alone. The builtin modules log one line of the same shape.
+ */
+
+#include <stdarg.h>
+#include <stddef.h>
+
+#include "error.h"
+
+struct st_ext_ctx;
+struct st_lua_rt;
+
+/* vfprintf-style log sink (NULL restores the default stderr logger). */
+typedef void (*st_ext_log_fn)(const char *fmt, va_list ap);
+
+void st_ext_discover_set_log(st_ext_log_fn fn);
+void st_ext_discover_log(const char *fmt, ...);
+
+/* Returns NULL on success. `extra_dirs` are the --ext-dir values (may
+ * be NULL/0); see the header contract for the full discovery order and
+ * the fail-fast failure semantics. */
+struct st_error *st_ext_discover(struct st_ext_ctx *ctx, struct st_lua_rt *rt,
+                                 const char *const *extra_dirs,
+                                 size_t n_dirs);
+
+#endif /* ST_EXT_DISCOVERY_H */

src/ext/lang_c.c

@@ -0,0 +1,44 @@
+#ifndef _POSIX_C_SOURCE
+#define _POSIX_C_SOURCE 200809L /* getenv/setenv surface (POSIX.1-2008) */
+#endif
+
+#include "lang_c.h"
+
+#include "lang_common.h"
+
+#include <stddef.h>
+
+/*
+ * The C language, entirely as a module over the extension ABI.
+ * ALL C-specific strings live here -- core never sees them.
+ *
+ * Detection order (see lang_common.h): env CC -> cc -> gcc -> clang.
+ */
+
+/* fallback candidates, in probe order (env override is checked first) */
+static const char *const candidates[] = { "cc", "gcc", "clang" };
+
+/* variables this language owns and registers on successful detection */
+static const char *const var_names[] = { "CC", "CFLAGS", NULL };
+
+static struct st_error *
+detect_c(struct st_ext_ctx *ctx, void *module_ctx, struct st_toolchain *out)
+{
+    (void)module_ctx;
+    return st_lang_detect_common(ctx, "CC", "C", candidates,
+                                 sizeof candidates / sizeof candidates[0],
+                                 var_names, out);
+}
+
+struct st_error *
+st_ext_lang_c_init(struct st_ext_ctx *ctx)
+{
+    struct st_error *err;
+
+    err = st_ext_register_language(ctx, "c", detect_c, NULL, var_names);
+    if (err != NULL) {
+        return err;
+    }
+    /* the `header` check is universal: register it for this language */
+    return st_ext_register_check(ctx, "c", "header", NULL);
+}

src/ext/lang_c.h

@@ -0,0 +1,20 @@
+#ifndef ST_EXT_LANG_C_H
+#define ST_EXT_LANG_C_H
+
+#include "abi.h"
+
+/*
+ * Builtin C language module entry point (called by the builtin module
+ * registry in abi.c; a future extension-discovery todo keeps this
+ * shape for user modules too).
+ *
+ * Registers over the generic ABI:
+ *   - language "c"        (detect fn + the CC/CFLAGS variables it owns)
+ *   - check kind "header" for language "c"
+ *
+ * Returns NULL on success. Every compiler-specific string lives in
+ * lang_c.c -- nothing here is known to core.
+ */
+struct st_error *st_ext_lang_c_init(struct st_ext_ctx *ctx);
+
+#endif /* ST_EXT_LANG_C_H */

src/ext/lang_common.h

@@ -0,0 +1,225 @@
+#ifndef ST_EXT_LANG_COMMON_H
+#define ST_EXT_LANG_COMMON_H
+
+/*
+ * Shared internals for the builtin C and C++ language modules
+ * (lang_c.c / lang_cpp.c). NOT part of the public ABI -- abi.h is the
+ * only interface core (and a future Lua binding) sees.
+ *
+ * Everything here is `static inline` so the two modules stay
+ * independently compilable while sharing ONE tested implementation of
+ * the detection order and the `--version` parsing.
+ */
+
+#include "abi.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* Copy the version token after `needle`: a run of [0-9.] up to
+ * whitespace. Returns malloc'd string or NULL. */
+static inline char *
+st_lang_version_token(const char *text, const char *needle)
+{
+    const char *p = strstr(text, needle);
+    size_t n;
+    char *tok;
+
+    if (p == NULL) {
+        return NULL;
+    }
+    p += strlen(needle);
+    while (*p == ' ' || *p == '\t') {
+        p++;
+    }
+    n = 0;
+    while ((p[n] >= '0' && p[n] <= '9') || p[n] == '.') {
+        n++;
+    }
+    if (n == 0) {
+        return NULL;
+    }
+    tok = malloc(n + 1);
+    if (tok == NULL) {
+        return NULL;
+    }
+    memcpy(tok, p, n);
+    tok[n] = '\0';
+    return tok;
+}
+
+/* Fallback: the last first-line token beginning with a digit, trimmed
+ * to its [0-9.] run. Handles "cc (Ubuntu 13.2.0-1) 13.2.0" style
+ * output where the "(GCC) " needle is absent. Returns malloc'd string
+ * or NULL. */
+static inline char *
+st_lang_last_version(const char *text)
+{
+    const char *p = text;
+    char *tok = NULL;
+
+    while (*p != '\0' && *p != '\n') {
+        const char *start;
+        size_t n;
+
+        while (*p == ' ' || *p == '\t') {
+            p++;
+        }
+        if (*p == '\0' || *p == '\n') {
+            break;
+        }
+        start = p;
+        while (*p != '\0' && *p != ' ' && *p != '\t' && *p != '\n') {
+            p++;
+        }
+        if (*start < '0' || *start > '9') {
+            continue; /* token must begin with a digit */
+        }
+        n = 0;
+        while (start + n < p &&
+               ((start[n] >= '0' && start[n] <= '9') || start[n] == '.')) {
+            n++;
+        }
+        free(tok);
+        tok = malloc(n + 1);
+        if (tok == NULL) {
+            return NULL;
+        }
+        memcpy(tok, start, n);
+        tok[n] = '\0';
+    }
+    return tok;
+}
+
+/* Identify a compiler from its `--version` output: id ("clang",
+ * "gcc", "unknown") + version, both freshly allocated (version is ""
+ * when unparsable). Never hard-fails: worst case is "unknown"/"". */
+static inline void
+st_lang_identify(const char *text, char **id, char **version)
+{
+    *id = NULL;
+    *version = NULL;
+
+    if (strstr(text, "clang") != NULL) {
+        *id = strdup("clang");
+        *version = st_lang_version_token(text, "clang version ");
+    } else if (strstr(text, "GCC") != NULL || strstr(text, "gcc") != NULL) {
+        *id = strdup("gcc");
+        *version = st_lang_version_token(text, "(GCC) ");
+    } else {
+        *id = strdup("unknown");
+    }
+    if (*version == NULL) {
+        *version = st_lang_last_version(text);
+    }
+    if (*version == NULL) {
+        *version = strdup("");
+    }
+    if (*id == NULL) {
+        *id = strdup("unknown");
+    }
+}
+
+/* snprintf-based one-argument IO error (our detection messages carry at
+ * most one dynamic argument). */
+static inline struct st_error *
+st_lang_errio(const char *fmt, const char *arg)
+{
+    int n = snprintf(NULL, 0, fmt, arg);
+    char *msg;
+    struct st_error *e;
+
+    if (n < 0) {
+        return st_error_internal("failed to format error message");
+    }
+    msg = malloc((size_t)n + 1);
+    if (msg == NULL) {
+        return st_error_internal("out of memory");
+    }
+    snprintf(msg, (size_t)n + 1, fmt, arg);
+    e = st_error_io(msg);
+    free(msg);
+    return e;
+}
+
+/*
+ * The shared detection engine, parameterized by the module:
+ *
+ *   env_name    environment override variable ("CC" / "CXX")
+ *   display     human name for diagnostics ("C" / "C++")
+ *   candidates  fallback order: {"cc","gcc","clang"} / {"c++","g++","clang++"}
+ *   var_names   {"CC","CFLAGS",NULL} / {"CXX","CXXFLAGS",NULL}
+ *
+ * Detection ORDER (locked, mirrors the plan todo 13):
+ *   1. env override -- authoritative: if set and not runnable, fail
+ *      with a clean "compiler not found" error, NEVER silently fall
+ *      back to a default;
+ *   2. `cc` / `c++` (the ubiquitous fallback);
+ *   3. probe `gcc`/`clang` / `g++`/`clang++`.
+ *
+ * Detection EXECUTES the compiler (`--version`), never guesses from
+ * PATH strings. On success fills `out` (the ctx owns it) and registers
+ * the module's variables: var_names[0] = the command, var_names[1] =
+ * flags from the environment (empty default).
+ */
+static inline struct st_error *
+st_lang_detect_common(struct st_ext_ctx *ctx, const char *env_name,
+                      const char *display, const char *const *candidates,
+                      size_t n_candidates, const char *const *var_names,
+                      struct st_toolchain *out)
+{
+    struct st_registry *reg = st_ext_var_registry(ctx);
+    const char *env = getenv(env_name);
+    const char *cmd = NULL;
+    const char *flags;
+    char *buf = NULL;
+    size_t buflen = 0;
+    size_t i;
+    struct st_error *err;
+
+    if (env != NULL && env[0] != '\0') {
+        char *argv[3] = { (char *)env, "--version", NULL };
+
+        if (st_ext_run_capture(argv, &buf, &buflen) == 0) {
+            cmd = env;
+        } else {
+            free(buf);
+            return st_lang_errio("compiler not found: %s", env);
+        }
+    } else {
+        for (i = 0; i < n_candidates; i++) {
+            char *argv[3] = { (char *)candidates[i], "--version", NULL };
+
+            if (st_ext_run_capture(argv, &buf, &buflen) == 0) {
+                cmd = candidates[i];
+                break;
+            }
+            free(buf);
+            buf = NULL;
+            buflen = 0;
+        }
+        if (cmd == NULL) {
+            return st_lang_errio("no %s compiler found", display);
+        }
+    }
+
+    out->path = strdup(cmd);
+    if (out->path == NULL) {
+        free(buf);
+        return st_error_internal("out of memory");
+    }
+    st_lang_identify(buf != NULL ? buf : "", &out->id, &out->version);
+    free(buf);
+
+    /* register this module's variables with the GENERIC registry */
+    err = st_registry_set_var(reg, var_names[0], cmd);
+    if (err != NULL) {
+        return err;
+    }
+    flags = getenv(var_names[1]);
+    return st_registry_set_var(reg, var_names[1],
+                               flags != NULL ? flags : "");
+}
+
+#endif /* ST_EXT_LANG_COMMON_H */

src/ext/lang_cpp.c

@@ -0,0 +1,45 @@
+#ifndef _POSIX_C_SOURCE
+#define _POSIX_C_SOURCE 200809L /* getenv/setenv surface (POSIX.1-2008) */
+#endif
+
+#include "lang_cpp.h"
+
+#include "lang_common.h"
+
+#include <stddef.h>
+
+/*
+ * The C++ language, entirely as a module over the extension ABI.
+ * ALL C++-specific strings live here -- core never sees them.
+ *
+ * Detection order (see lang_common.h): env CXX -> c++ -> g++ -> clang++.
+ */
+
+/* fallback candidates, in probe order (env override is checked first) */
+static const char *const candidates[] = { "c++", "g++", "clang++" };
+
+/* variables this language owns and registers on successful detection */
+static const char *const var_names[] = { "CXX", "CXXFLAGS", NULL };
+
+static struct st_error *
+detect_cxx(struct st_ext_ctx *ctx, void *module_ctx,
+           struct st_toolchain *out)
+{
+    (void)module_ctx;
+    return st_lang_detect_common(ctx, "CXX", "C++", candidates,
+                                 sizeof candidates / sizeof candidates[0],
+                                 var_names, out);
+}
+
+struct st_error *
+st_ext_lang_cpp_init(struct st_ext_ctx *ctx)
+{
+    struct st_error *err;
+
+    err = st_ext_register_language(ctx, "cxx", detect_cxx, NULL, var_names);
+    if (err != NULL) {
+        return err;
+    }
+    /* the `header` check is universal: register it for this language */
+    return st_ext_register_check(ctx, "cxx", "header", NULL);
+}

src/ext/lang_cpp.h

@@ -0,0 +1,19 @@
+#ifndef ST_EXT_LANG_CPP_H
+#define ST_EXT_LANG_CPP_H
+
+#include "abi.h"
+
+/*
+ * Builtin C++ language module entry point (called by the builtin module
+ * registry in abi.c).
+ *
+ * Registers over the generic ABI:
+ *   - language "cxx"      (detect fn + the CXX/CXXFLAGS variables it owns)
+ *   - check kind "header" for language "cxx"
+ *
+ * Returns NULL on success. Every compiler-specific string lives in
+ * lang_cpp.c -- nothing here is known to core.
+ */
+struct st_error *st_ext_lang_cpp_init(struct st_ext_ctx *ctx);
+
+#endif /* ST_EXT_LANG_CPP_H */

src/ext/lua.c

@@ -0,0 +1,876 @@
+/*
+ * src/ext/lua.c - embedded sandboxed Lua runtime (plan todo 19).
+ *
+ * Initializes the vendored Lua 5.4 as the stupidtools extension runtime
+ * with a SANDBOXED environment. See src/ext/lua.h for the exact
+ * sandbox contract (what is opened, blocked, removed) and the error
+ * contract of st_lua_run().
+ *
+ * LINKING / THE -lm TRAP (important for the build wiring):
+ *   The unit-test harness compiles every test file under tests/unit/
+ *   with NO extra libraries -- in particular no -lm. Stock Lua needs
+ *   libm in TWO
+ *   places: (1) lmathlib.c (sin/cos/pow/log/...), and (2) the CORE
+ *   itself: lvm.c calls floor(), ltable.c frexp()+fabs(), lstrlib.c
+ *   floor()+frexp(), lobject.c and lcode.c ldexp()+fabs(), and the
+ *   arithmetic dispatcher luaO_arith() calls pow() and fmod(). On this
+ *   host `floor` does NOT resolve without -lm (verified: gcc 16.2.1 /
+ *   glibc 2.44 -- libm is a separate library).
+ *
+ *   Two consequences:
+ *     a) lmathlib.c and linit.c (which references luaopen_math) are NOT
+ *        part of the link list; the curated `math` table below is
+ *        written by hand with libm-free code, so extensions still get
+ *        math.abs etc. (the plan's test requires math.abs(-3) to work).
+ *     b) The core's remaining libm references are satisfied by the
+ *        portable IEEE-754 binary64 shims at the top of this file
+ *        (fabs/floor/frexp/ldexp/fmod/pow). They are correct for the
+ *        common paths (the C23-annex-F binary64 assumption holds on
+ *        gcc/clang x86-64/aarch64); pow's exotic sign edge cases are
+ *        approximate. The main binary (todo 21+) may link the real
+ *        libm later; these shims stay harmless because Lua's undefined
+ *        references then simply resolve against libm instead... in
+ *        fact they will NOT: our definitions take precedence. When the
+ *        real libm becomes available, delete this block and add -lm.
+ *
+ * Include paths: the vendored headers are pulled in via path relative
+ * to THIS file (../../thirdparty/lua/...), because the unit-test
+ * harness only adds -I thirdparty/munit and -I src -- it never adds a
+ * Lua include dir. The file-relative form works under any invocation
+ * that compiles this file at its real location.
+ */
+
+#ifndef _POSIX_C_SOURCE
+#define _POSIX_C_SOURCE 200809L /* strdup (POSIX.1-2008) */
+#endif
+
+#include <stddef.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "../../thirdparty/lua/lauxlib.h"
+#include "../../thirdparty/lua/lua.h"
+#include "../../thirdparty/lua/lualib.h"
+
+#include "lua.h"
+
+/* The probe-spec struct (struct st_lua_probe_spec) and its static-inline
+ * free live in api.h (todo 21). Including it here is deliberate and safe
+ * under the frozen unit-test link lines: api.h contributes only a struct
+ * definition + a static inline, so lua.c gains NO reference to any
+ * api.c/abi.c symbol -- tests/unit/test_lua.c and test_discovery.c, which
+ * link lua.c WITHOUT api.c/abi.c, keep linking. */
+#include "api.h"
+
+/* ------------------------------------------------------------------ */
+/* libm-free math shims                                                */
+/* ------------------------------------------------------------------ */
+/*
+ * All six are exactly the symbols the vendored Lua core references from
+ * libm (see the -lm note above). fabs uses the compiler builtin (a
+ * single ANDPS, no call); floor/frexp/ldexp/fmod/pow are hand-written.
+ * Bit-level code assumes IEEE 754 binary64 doubles (8-byte), which C23
+ * annex F plus gcc/clang guarantee on the supported targets.
+ */
+
+double fabs(double x);
+double floor(double x);
+double frexp(double x, int *e);
+double ldexp(double x, int n);
+double fmod(double x, double y);
+double pow(double x, double y);
+
+double
+fabs(double x)
+{
+    return __builtin_fabs(x);
+}
+
+/* Truncation toward zero, safe for the full double range (casting an
+ * out-of-range double to long long is UB, hence the guard). */
+static double
+l_shim_trunc(double x)
+{
+    static const double maxint = 9223372036854775808.0; /* 2^63 */
+
+    if (x > -maxint && x < maxint) {
+        return (double)(long long)x;
+    }
+    return x; /* NaN, +/-inf, or a magnitude already integral */
+}
+
+double
+floor(double x)
+{
+    static const double minint = -9223372036854775808.0;
+    static const double maxint = 9223372036854775808.0;
+
+    if (x == 0.0) return x; /* preserves the sign of zero */
+    if (x > minint && x < maxint) {
+        double t = (double)(long long)x;
+        return x < t ? t - 1.0 : t;
+    }
+    return x; /* NaN, +/-inf, or out of range (already integral) */
+}
+
+double
+frexp(double x, int *e)
+{
+    union {
+        double d;
+        unsigned long long u;
+    } v;
+    unsigned long long expfield;
+
+    v.d = x;
+    expfield = (v.u >> 52) & 0x7FFULL;
+    if (expfield == 0x7FFULL) { /* inf or NaN: value returned unchanged */
+        *e = 0;
+        return x;
+    }
+    if (expfield == 0) { /* zero or subnormal */
+        if ((v.u & 0x000FFFFFFFFFFFFFULL) == 0ULL) { /* zero */
+            *e = 0;
+            return x;
+        }
+        /* Normalize a subnormal by scaling it up 2^64 (the largest
+         * subnormal is ~2^-1022, so the result is normal), then fix
+         * the exponent. */
+        x = frexp(x * 0x1p64, e);
+        *e -= 64;
+        return x;
+    }
+    /* Normal case: keep the fraction, force the exponent field to 1022
+     * so the result lands in [0.5, 1), and report the difference. */
+    *e = (int)expfield - 1022;
+    v.u = (v.u & 0x800FFFFFFFFFFFFFULL) | 0x3FE0000000000000ULL;
+    return v.d;
+}
+
+double
+ldexp(double x, int n)
+{
+    union {
+        double d;
+        unsigned long long u;
+    } v;
+
+    if (n > 1023) {
+        x *= 0x1p1023;
+        n -= 1023;
+        if (n > 1023) {
+            x *= 0x1p1023;
+            n -= 1023;
+            if (n > 1023) n = 1023;
+        }
+    } else if (n < -1022) {
+        /* pre-scale so the final multiply stays clear of the subnormal
+         * range and rounds once (avoids double rounding) */
+        x *= 0x1p-1022 * 0x1p53;
+        n += 1022 - 53;
+        if (n < -1022) {
+            x *= 0x1p-1022 * 0x1p53;
+            n += 1022 - 53;
+            if (n < -1022) n = -1022;
+        }
+    }
+    v.u = (unsigned long long)(0x3FF + n) << 52;
+    return x * v.d;
+}
+
+double
+fmod(double x, double y)
+{
+    double r;
+    double ax, ay;
+    int ex, ey;
+    int neg;
+
+    if (y == 0.0 || x != x || y != y) return __builtin_nan("");
+    if (x == 0.0) return x;                            /* keeps the sign */
+    if (fabs(x) == __builtin_inf()) return __builtin_nan("");
+    if (fabs(y) == __builtin_inf()) return x;          /* fmod(x, inf) = x */
+
+    neg = x < 0.0;
+    ax = fabs(x);
+    ay = fabs(y);
+    frexp(ax, &ex);
+    frexp(ay, &ey);
+    /* Binary long division: subtract the largest multiple of ay that
+     * fits, then halve. Bounded by the exponent range (~2100 steps). */
+    r = ax;
+    while (ex >= ey && r != 0.0) {
+        double s = ldexp(ay, ex - ey);
+        if (r >= s) r -= s;
+        ex--;
+    }
+    return neg ? -r : r;
+}
+
+/* e^x via the reduction x = k*ln(2) + r, |r| <= ln(2)/2, then a Taylor
+ * series (20 terms: the truncation error is ~4e-30, far below double
+ * precision). */
+static double
+l_shim_exp(double x)
+{
+    static const double ln2 = 0.69314718055994530942;
+    static const double invln2 = 1.44269504088896340736;
+    long long k;
+    double r, t, y;
+    int i;
+
+    if (x > 709.7827128933839731) return __builtin_inf(); /* overflow */
+    if (x < -745.1332191019411085) return 0.0;            /* underflow */
+    if (x != x) return x;                                 /* NaN */
+
+    k = (long long)(x * invln2 + (x >= 0.0 ? 0.5 : -0.5));
+    r = x - (double)k * ln2;
+    y = 1.0;
+    t = 1.0;
+    for (i = 1; i <= 20; i++) {
+        t = t * (r / (double)i);
+        y += t;
+    }
+    return ldexp(y, (int)k);
+}
+
+/* ln(x) via x = m * 2^e (m in [0.5, 1)), then the atanh series around
+ * m = 2/3:  log(m) = log(2/3) + 2*atanh(t), t = (m - 2/3)/(m + 2/3),
+ * |t| <= 0.2. 12 terms leave ~1e-18, i.e. a few ulps. */
+static double
+l_shim_log(double x)
+{
+    static const double ln2 = 0.69314718055994530942;
+    static const double log32 = -0.40546510810816438098; /* ln(2/3) */
+    double m, t, p, term, sum;
+    int e;
+    int i;
+
+    if (x < 0.0 || x != x) return __builtin_nan("");
+    if (x == 0.0) return -__builtin_inf();
+    if (x == __builtin_inf()) return x;
+
+    m = frexp(x, &e);
+    t = (m - 0.66666666666666663) / (m + 0.66666666666666663);
+    p = t * t;
+    term = t;
+    sum = t;
+    for (i = 1; i <= 12; i++) {
+        term *= p;
+        sum += term / (double)(2 * i + 1);
+    }
+    return (double)e * ln2 + log32 + 2.0 * sum;
+}
+
+double
+pow(double x, double y)
+{
+    if (y == 0.0) return 1.0;        /* even pow(NaN, 0) == 1 */
+    if (x == 1.0) return 1.0;
+    if ((x == -1.0) &&
+        (y == __builtin_inf() || y == -__builtin_inf())) return 1.0;
+    if (x != x || y != y) return __builtin_nan("");
+
+    /* Integral exponent within the exactly-representable range: exact
+     * repeated squaring (this also covers negative bases). */
+    if (y == l_shim_trunc(y) && y > -9007199254740992.0 &&
+        y < 9007199254740992.0) {
+        long long n = (long long)y;
+        unsigned long long m = n < 0 ? (unsigned long long)(-n)
+                                     : (unsigned long long)n;
+        double r = 1.0;
+        double b = x;
+        while (m != 0ULL) {
+            if ((m & 1ULL) != 0ULL) r *= b;
+            b *= b;
+            m >>= 1;
+        }
+        return n < 0 ? 1.0 / r : r;
+    }
+
+    if (x == __builtin_inf()) return y > 0.0 ? x : 0.0;
+    if (x == -__builtin_inf()) return y > 0.0 ? __builtin_inf() : 0.0;
+    if (x == 0.0) return y > 0.0 ? 0.0 : __builtin_inf();
+    if (y == __builtin_inf()) return x > 1.0 ? __builtin_inf() : 0.0;
+    if (y == -__builtin_inf()) return x < 1.0 ? __builtin_inf() : 0.0;
+    if (x < 0.0) return __builtin_nan(""); /* negative base, non-int y */
+    return l_shim_exp(y * l_shim_log(x));
+}
+
+/* ------------------------------------------------------------------ */
+/* runtime state                                                       */
+/* ------------------------------------------------------------------ */
+
+struct st_lua_reg {
+    struct st_lua_reg *next;
+    char *name;         /* owned copy */
+    void *probe_spec;   /* checks: a struct st_lua_probe_spec * (owned);
+                           languages: always NULL (name only in v1) */
+};
+
+struct st_lua_rt {
+    lua_State *L;
+    struct st_lua_reg *checks;     /* insertion-ordered linked lists */
+    struct st_lua_reg *languages;
+    size_t check_count;
+    size_t language_count;
+};
+
+/* Appends (name, spec) at the TAIL of *head (insertion order, matching
+ * the ABI registries' contract) unless it is a duplicate. Returns 0 on
+ * success, -1 on duplicate or allocation failure. */
+static int
+reg_append(struct st_lua_reg **head, size_t *count, const char *name,
+           void *spec)
+{
+    struct st_lua_reg *n, *p;
+
+    for (p = *head; p != NULL; p = p->next) {
+        if (strcmp(p->name, name) == 0) return -1; /* duplicate */
+    }
+    n = malloc(sizeof *n);
+    if (n == NULL) return -1;
+    n->name = strdup(name);
+    if (n->name == NULL) {
+        free(n);
+        return -1;
+    }
+    n->probe_spec = spec;
+    n->next = NULL;
+    if (*head == NULL) {
+        *head = n;
+    } else {
+        for (p = *head; p->next != NULL; p = p->next) {
+        }
+        p->next = n;
+    }
+    *count += 1;
+    return 0;
+}
+
+static void
+regs_free(struct st_lua_reg *head)
+{
+    struct st_lua_reg *p = head;
+    while (p != NULL) {
+        struct st_lua_reg *next = p->next;
+        free(p->name);
+        st_lua_probe_spec_free((struct st_lua_probe_spec *)p->probe_spec);
+        free(p);
+        p = next;
+    }
+}
+
+static const struct st_lua_reg *
+reg_at(const struct st_lua_reg *head, size_t i)
+{
+    const struct st_lua_reg *p = head;
+    while (p != NULL && i > 0) {
+        p = p->next;
+        i--;
+    }
+    return p;
+}
+
+/* ------------------------------------------------------------------ */
+/* sandboxed globals                                                   */
+/* ------------------------------------------------------------------ */
+
+/* The one string sandbox violations contain; st_lua_run() classifies
+ * errors by finding it in the message. Keep in sync with l_os_blocked(). */
+#define SANDBOX_PREFIX "sandbox blocked: "
+
+/* os.execute / os.exit / os.remove / os.rename all land here: a stub
+ * that raises a clear sandbox error no matter how it is called (direct,
+ * pcall'd, aliased, ...). */
+static int
+l_os_blocked(lua_State *L)
+{
+    const char *name = lua_tostring(L, lua_upvalueindex(1));
+    return luaL_error(L, SANDBOX_PREFIX "os.%s is not available to "
+                          "extension code",
+                      name != NULL ? name : "?");
+}
+
+/* The ONLY os table extensions see: the four stubs above, nothing else
+ * (no clock/date/getenv -- extension code needs none of them in v1 and
+ * a smaller surface is a better sandbox). The stock loslib is not even
+ * linked. */
+static void
+l_os_open_sandboxed(lua_State *L)
+{
+    static const char *const blocked[] = { "execute", "exit", "remove",
+                                           "rename", NULL };
+    int i;
+
+    lua_newtable(L);
+    for (i = 0; blocked[i] != NULL; i++) {
+        lua_pushstring(L, blocked[i]); /* upvalue: the function's name */
+        lua_pushcclosure(L, l_os_blocked, 1);
+        lua_setfield(L, -2, blocked[i]);
+    }
+    lua_setglobal(L, "os");
+}
+
+/* Curated, libm-FREE math library (stock lmathlib would pull sin/cos/
+ * pow/log/... from libm; see the header note). abs/max/min/tointeger/
+ * type/maxinteger/mininteger/pi/huge cover what extension code needs
+ * in v1; floor/ceil/sqrt etc. arrive when the main binary links real
+ * libm (todo 21+). */
+static int
+l_math_abs(lua_State *L)
+{
+    if (lua_isinteger(L, 1)) {
+        lua_Integer n = lua_tointeger(L, 1);
+        lua_pushinteger(L, n < 0 ? (lua_Integer)(0u - (lua_Unsigned)n) : n);
+    } else {
+        lua_pushnumber(L, fabs(luaL_checknumber(L, 1)));
+    }
+    return 1;
+}
+
+static int
+l_math_max(lua_State *L)
+{
+    int n = lua_gettop(L);
+    int i;
+    lua_Number m;
+
+    if (n == 0) return luaL_error(L, "math.max: expected at least one argument");
+    m = luaL_checknumber(L, 1);
+    for (i = 2; i <= n; i++) {
+        lua_Number v = luaL_checknumber(L, i);
+        if (v > m) m = v;
+    }
+    lua_pushnumber(L, m);
+    return 1;
+}
+
+static int
+l_math_min(lua_State *L)
+{
+    int n = lua_gettop(L);
+    int i;
+    lua_Number m;
+
+    if (n == 0) return luaL_error(L, "math.min: expected at least one argument");
+    m = luaL_checknumber(L, 1);
+    for (i = 2; i <= n; i++) {
+        lua_Number v = luaL_checknumber(L, i);
+        if (v < m) m = v;
+    }
+    lua_pushnumber(L, m);
+    return 1;
+}
+
+/* Mirrors stock math.tointeger: converts a value that has an exact
+ * integer representation (this exercises the floor() shim through
+ * luaV_flttointeger). */
+static int
+l_math_tointeger(lua_State *L)
+{
+    int valid;
+    lua_Integer n = lua_tointegerx(L, 1, &valid);
+
+    if (valid) {
+        lua_pushinteger(L, n);
+    } else {
+        luaL_checkany(L, 1);
+        lua_pushnil(L); /* not convertible */
+    }
+    return 1;
+}
+
+static int
+l_math_type(lua_State *L)
+{
+    if (lua_type(L, 1) == LUA_TNUMBER) {
+        if (lua_isinteger(L, 1)) {
+            lua_pushliteral(L, "integer");
+        } else {
+            lua_pushliteral(L, "float");
+        }
+    } else {
+        luaL_checkany(L, 1);
+        lua_pushnil(L);
+    }
+    return 1;
+}
+
+static void
+l_math_open(lua_State *L)
+{
+    static const luaL_Reg funcs[] = {
+        { "abs", l_math_abs },
+        { "max", l_math_max },
+        { "min", l_math_min },
+        { "tointeger", l_math_tointeger },
+        { "type", l_math_type },
+        { NULL, NULL },
+    };
+
+    luaL_newlib(L, funcs);
+    lua_pushinteger(L, LUA_MAXINTEGER);
+    lua_setfield(L, -2, "maxinteger");
+    lua_pushinteger(L, LUA_MININTEGER);
+    lua_setfield(L, -2, "mininteger");
+    lua_pushnumber(L, 3.14159265358979323846);
+    lua_setfield(L, -2, "pi");
+    lua_pushnumber(L, __builtin_inf());
+    lua_setfield(L, -2, "huge");
+    lua_setglobal(L, "math");
+}
+
+/* ------------------------------------------------------------------ */
+/* registration API (Lua side)                                         */
+/* ------------------------------------------------------------------ */
+
+/* The `st` table: st.register_check(name[, spec]) and
+ * st.register_language(name[, spec]). Both write into the runtime's own
+ * registries through the same C API todo 21 enumerates when bridging into
+ * a struct st_ext_ctx. The rt travels as a light-userdata upvalue -- there
+ * is no global state. A present second argument (a probe-spec TABLE) is
+ * parsed into a heap struct st_lua_probe_spec (api.h) and passed through
+ * as the registry entry's opaque spec pointer. */
+
+static void
+l_links_free(char **link)
+{
+    size_t i;
+
+    if (link == NULL) {
+        return;
+    }
+    for (i = 0; link[i] != NULL; i++) {
+        free(link[i]);
+    }
+    free(link);
+}
+
+/* Parses the optional probe-spec table (argument 2) into a heap
+ * struct st_lua_probe_spec. Returns NULL when argument 2 is absent or
+ * nil (bare registration); raises a Lua error on a malformed table.
+ * All fields are strdup'd (so the borrowed lua_tostring pointers never
+ * outlive their stack slot); the caller owns the result. */
+static struct st_lua_probe_spec *
+l_parse_probe_spec(lua_State *L)
+{
+    struct st_lua_probe_spec *spec;
+    char *kind_dup = NULL;
+    char *source_dup = NULL;
+    char **link = NULL;
+    size_t nlink = 0;
+    size_t i;
+    const char *s;
+
+    if (lua_gettop(L) < 2 || lua_isnoneornil(L, 2)) {
+        return NULL;
+    }
+    luaL_checktype(L, 2, LUA_TTABLE);
+
+    lua_getfield(L, 2, "kind");
+    if (lua_type(L, -1) != LUA_TSTRING) {
+        luaL_error(L, "probe spec 'kind' must be a string");
+        return NULL;
+    }
+    s = lua_tostring(L, -1);
+    if (strcmp(s, "compile") != 0 && strcmp(s, "link") != 0 &&
+        strcmp(s, "run") != 0) {
+        luaL_error(L, "probe spec 'kind' must be \"compile\", \"link\" or "
+                      "\"run\"");
+        return NULL;
+    }
+    kind_dup = strdup(s);
+    lua_pop(L, 1);
+    if (kind_dup == NULL) {
+        luaL_error(L, "out of memory");
+        return NULL;
+    }
+
+    lua_getfield(L, 2, "source");
+    if (lua_type(L, -1) != LUA_TSTRING) {
+        free(kind_dup);
+        luaL_error(L, "probe spec 'source' must be a string");
+        return NULL;
+    }
+    s = lua_tostring(L, -1);
+    source_dup = strdup(s);
+    lua_pop(L, 1);
+    if (source_dup == NULL) {
+        free(kind_dup);
+        luaL_error(L, "out of memory");
+        return NULL;
+    }
+
+    lua_getfield(L, 2, "link");
+    if (!lua_isnoneornil(L, -1)) {
+        luaL_checktype(L, -1, LUA_TTABLE);
+        nlink = lua_rawlen(L, -1);
+        link = calloc(nlink + 1, sizeof *link);
+        if (link == NULL) {
+            free(kind_dup);
+            free(source_dup);
+            luaL_error(L, "out of memory");
+            return NULL;
+        }
+        for (i = 0; i < nlink; i++) {
+            size_t slen;
+
+            lua_geti(L, -1, (lua_Integer)i + 1);
+            s = lua_tostring(L, -1);
+            slen = lua_rawlen(L, -1);
+            if (lua_type(L, -1) != LUA_TSTRING || s == NULL ||
+                strlen(s) != slen) {
+                lua_pop(L, 1);
+                l_links_free(link);
+                free(kind_dup);
+                free(source_dup);
+                luaL_error(L, "probe spec 'link' entries must be strings "
+                              "without NUL bytes");
+                return NULL;
+            }
+            link[i] = strdup(s);
+            lua_pop(L, 1);
+            if (link[i] == NULL) {
+                l_links_free(link);
+                free(kind_dup);
+                free(source_dup);
+                luaL_error(L, "out of memory");
+                return NULL;
+            }
+        }
+        link[nlink] = NULL;
+    }
+    lua_pop(L, 1);
+
+    spec = malloc(sizeof *spec);
+    if (spec == NULL) {
+        l_links_free(link);
+        free(kind_dup);
+        free(source_dup);
+        luaL_error(L, "out of memory");
+        return NULL;
+    }
+    spec->kind = kind_dup;
+    spec->source = source_dup;
+    spec->link = link;
+    return spec;
+}
+
+static int
+l_st_register_check(lua_State *L)
+{
+    struct st_lua_rt *rt = lua_touserdata(L, lua_upvalueindex(1));
+    struct st_lua_probe_spec *spec;
+    size_t len;
+    const char *name;
+
+    if (lua_type(L, 1) != LUA_TSTRING) {
+        return luaL_typeerror(L, 1, "string");
+    }
+    name = lua_tostring(L, 1);
+    len = lua_rawlen(L, 1);
+    if (name == NULL || strlen(name) != len) {
+        return luaL_error(L, "check name must not contain a NUL byte");
+    }
+    spec = l_parse_probe_spec(L);
+    if (st_lua_register_check(rt, name, spec) != 0) {
+        st_lua_probe_spec_free(spec); /* not stored: free it */
+        return luaL_error(L, "check '%s' is already registered", name);
+    }
+    return 0;
+}
+
+static int
+l_st_register_language(lua_State *L)
+{
+    struct st_lua_rt *rt = lua_touserdata(L, lua_upvalueindex(1));
+    size_t len;
+    const char *name;
+
+    if (lua_type(L, 1) != LUA_TSTRING) {
+        return luaL_typeerror(L, 1, "string");
+    }
+    name = lua_tostring(L, 1);
+    len = lua_rawlen(L, 1);
+    if (name == NULL || strlen(name) != len) {
+        return luaL_error(L, "language name must not contain a NUL byte");
+    }
+    /* Optional second arg: accept a probe-spec TABLE for forward
+     * compatibility, but for v1 register the name only -- the table's
+     * contents (detection info) are consumed by todo 22. A non-table
+     * second arg is a clean error. */
+    if (lua_gettop(L) >= 2 && !lua_isnoneornil(L, 2)) {
+        luaL_checktype(L, 2, LUA_TTABLE);
+    }
+    if (st_lua_register_language(rt, name) != 0) {
+        return luaL_error(L, "language '%s' is already registered", name);
+    }
+    return 0;
+}
+
+static void
+l_st_open(lua_State *L, struct st_lua_rt *rt)
+{
+    lua_newtable(L);
+    lua_pushlightuserdata(L, rt);
+    lua_pushcclosure(L, l_st_register_check, 1);
+    lua_setfield(L, -2, "register_check");
+    lua_pushlightuserdata(L, rt);
+    lua_pushcclosure(L, l_st_register_language, 1);
+    lua_setfield(L, -2, "register_language");
+    lua_setglobal(L, "st");
+}
+
+/* ------------------------------------------------------------------ */
+/* runtime lifecycle + sandbox assembly                                */
+/* ------------------------------------------------------------------ */
+
+struct st_lua_rt *
+st_lua_rt_new(void)
+{
+    struct st_lua_rt *rt = calloc(1, sizeof *rt);
+    lua_State *L;
+
+    if (rt == NULL) return NULL;
+    L = luaL_newstate();
+    if (L == NULL) {
+        free(rt);
+        return NULL;
+    }
+    rt->L = L;
+
+    /* Selective library set -- deliberately NOT luaL_openlibs():
+     *   base / table / string are the only stock libraries loaded;
+     *   math and os are the hand-built sandboxed ones below;
+     *   package/io/debug/coroutine are never loaded (and their .c
+     *   files are not even linked -- see the -lm note at the top);
+     *   lmathlib/linit are excluded from the link for the same reason. */
+    luaL_requiref(L, "base", luaopen_base, 1);
+    lua_pop(L, 1);
+    luaL_requiref(L, "table", luaopen_table, 1);
+    lua_pop(L, 1);
+    luaL_requiref(L, "string", luaopen_string, 1);
+    lua_pop(L, 1);
+
+    /* Remove the base-library globals that reach files/modules. (`load`
+     * is kept: with io/os/package gone it can only compile strings, and
+     * that is how extension loading works in todo 20/21.) */
+    lua_pushnil(L);
+    lua_setglobal(L, "dofile");
+    lua_pushnil(L);
+    lua_setglobal(L, "loadfile");
+    lua_pushnil(L);
+    lua_setglobal(L, "require"); /* defensive: 5.4 defines it in loadlib */
+
+    l_os_open_sandboxed(L);
+    l_math_open(L);
+    l_st_open(L, rt);
+    return rt;
+}
+
+void
+st_lua_rt_free(struct st_lua_rt *rt)
+{
+    if (rt == NULL) return;
+    if (rt->L != NULL) lua_close(rt->L);
+    regs_free(rt->checks);
+    regs_free(rt->languages);
+    free(rt);
+}
+
+/* ------------------------------------------------------------------ */
+/* registration API (C side) + todo-21 enumeration bridge              */
+/* ------------------------------------------------------------------ */
+
+int
+st_lua_register_check(struct st_lua_rt *rt, const char *name,
+                      void *probe_spec_or_null)
+{
+    if (rt == NULL || name == NULL || name[0] == '\0') return -1;
+    return reg_append(&rt->checks, &rt->check_count, name, probe_spec_or_null);
+}
+
+int
+st_lua_register_language(struct st_lua_rt *rt, const char *name)
+{
+    if (rt == NULL || name == NULL || name[0] == '\0') return -1;
+    return reg_append(&rt->languages, &rt->language_count, name, NULL);
+}
+
+size_t
+st_lua_check_count(const struct st_lua_rt *rt)
+{
+    return rt != NULL ? rt->check_count : 0;
+}
+
+const char *
+st_lua_check_name(const struct st_lua_rt *rt, size_t i)
+{
+    const struct st_lua_reg *r = rt != NULL ? reg_at(rt->checks, i) : NULL;
+    return r != NULL ? r->name : NULL;
+}
+
+void *
+st_lua_check_probe_spec(const struct st_lua_rt *rt, size_t i)
+{
+    const struct st_lua_reg *r = rt != NULL ? reg_at(rt->checks, i) : NULL;
+    return r != NULL ? r->probe_spec : NULL;
+}
+
+size_t
+st_lua_language_count(const struct st_lua_rt *rt)
+{
+    return rt != NULL ? rt->language_count : 0;
+}
+
+const char *
+st_lua_language_name(const struct st_lua_rt *rt, size_t i)
+{
+    const struct st_lua_reg *r = rt != NULL ? reg_at(rt->languages, i) : NULL;
+    return r != NULL ? r->name : NULL;
+}
+
+/* ------------------------------------------------------------------ */
+/* execution                                                           */
+/* ------------------------------------------------------------------ */
+
+/* Takes the error object Lua left on the top of the stack, classifies
+ * it (sandbox violation vs. everything else), builds the st_error and
+ * pops the object. */
+static struct st_error *
+lua_error_to_st_error(lua_State *L)
+{
+    const char *msg = lua_tostring(L, -1);
+    struct st_error *err;
+
+    if (msg == NULL) msg = "(non-string Lua error)";
+    /* luaL_error prepends "chunkname:line: " to the message, so the
+     * sandbox marker is matched as a substring, not a prefix. */
+    if (strstr(msg, SANDBOX_PREFIX) != NULL) {
+        err = st_error_kdl_schema(msg);
+    } else {
+        err = st_error_internal(msg);
+    }
+    lua_pop(L, 1);
+    return err;
+}
+
+struct st_error *
+st_lua_run(struct st_lua_rt *rt, const char *chunk, const char *chunkname)
+{
+    lua_State *L;
+    int status;
+
+    if (rt == NULL) return st_error_internal("st_lua_run: NULL runtime");
+    if (chunk == NULL) return st_error_internal("st_lua_run: NULL chunk");
+    L = rt->L;
+
+    status = luaL_loadbuffer(L, chunk, strlen(chunk),
+                             chunkname != NULL ? chunkname : "=(extension)");
+    if (status == LUA_OK) {
+        status = lua_pcall(L, 0, 0, 0);
+    }
+    if (status == LUA_OK) return NULL;
+    return lua_error_to_st_error(L);
+}

src/ext/lua.h

@@ -0,0 +1,100 @@
+#ifndef ST_EXT_LUA_H
+#define ST_EXT_LUA_H
+
+/*
+ * Embedded sandboxed Lua runtime for stupidtools extensions (plan todo
+ * 19). Binds the vendored Lua 5.4 (thirdparty/lua/) as the extension
+ * language; the extension ABI (src/ext/abi.h, todo 13) is bridged in
+ * todo 21 -- THIS todo only ships the runtime, the sandbox, and the
+ * registration hooks.
+ *
+ * Sandbox contract (what extension code may and may not do):
+ *
+ *   OPENED libraries (the ONLY ones linked and loaded):
+ *     base     -- minus the globals below
+ *     table, string
+ *     math     -- a curated, libm-FREE subset written here: abs, max,
+ *                 min, tointeger, type, maxinteger, mininteger, pi,
+ *                 huge. The stock lmathlib.c is NOT linked: it pulls
+ *                 sin/cos/pow/... from libm and the unit-test harness
+ *                 links NO extra libraries (-lm is unavailable).
+ *     os       -- a hand-built table containing ONLY the stubs below.
+ *
+ *   BLOCKED (exist but raise "sandbox blocked: ..." errors):
+ *     os.execute, os.exit, os.remove, os.rename
+ *
+ *   REMOVED (globals are nil; their C libraries are not even linked):
+ *     dofile, loadfile, require, package, io, debug, coroutine
+ *
+ *   KEPT with the rationale that they cannot reach the filesystem or a
+ *   process without io/os/package (all gone): `load` (string chunks
+ *   only), collectgarbage, print, warn, the string/table libraries.
+ *
+ *   REGISTRATION API (the only way extensions talk to stupidtools):
+ *     st.register_check("name")
+ *     st.register_language("name")
+ *   These record into the RUNTIME'S OWN registries (see below); the
+ *   flush into a struct st_ext_ctx is todo 21's bridge.
+ *
+ * Error contract of st_lua_run():
+ *   - success            -> NULL;
+ *   - sandbox violation  -> st_error, category ST_ERR_KDL_SCHEMA, whose
+ *     message contains "sandbox blocked: " (the extension violated
+ *     its contract -- the closest existing category; error.h is frozen
+ *     to this todo);
+ *   - any other Lua failure (syntax error, runtime error, OOM) ->
+ *     st_error, category ST_ERR_INTERNAL, carrying Lua's message
+ *     (chunkname is propagated into syntax-error messages).
+ */
+
+#include <stddef.h>
+
+#include "error.h"
+
+struct st_lua_rt; /* opaque */
+
+/* Fresh runtime with the sandboxed environment installed. NULL only on
+ * allocation failure. */
+struct st_lua_rt *st_lua_rt_new(void);
+
+/* NULL is a no-op. */
+void st_lua_rt_free(struct st_lua_rt *rt);
+
+/* ---------------- registration API (C side) ---------------- */
+
+/* Record a check registration in the runtime's own registry. `name`
+ * must be a non-empty NUL-terminated string; `probe_spec_or_null` is an
+ * opaque pointer kept verbatim (todo 21 passes it through to the ABI's
+ * st_ext_register_check). Returns 0 on success, -1 on bad arguments,
+ * duplicate name, or allocation failure. Mirrored from Lua by
+ * st.register_check(name). */
+int st_lua_register_check(struct st_lua_rt *rt, const char *name,
+                          void *probe_spec_or_null);
+
+/* Same, for languages (mirrored by st.register_language(name)). */
+int st_lua_register_language(struct st_lua_rt *rt, const char *name);
+
+/* ---------------- enumeration (the todo 21 bridge) ----------------
+ *
+ * Everything the runtime has recorded, in registration order. Todo 21
+ * walks these and calls st_ext_register_check / st_ext_register_language
+ * on a struct st_ext_ctx -- no state lives anywhere else. */
+
+size_t st_lua_check_count(const struct st_lua_rt *rt);
+const char *st_lua_check_name(const struct st_lua_rt *rt, size_t i);
+void *st_lua_check_probe_spec(const struct st_lua_rt *rt, size_t i);
+
+size_t st_lua_language_count(const struct st_lua_rt *rt);
+const char *st_lua_language_name(const struct st_lua_rt *rt, size_t i);
+
+/* ---------------- execution ---------------- */
+
+/* Compiles `chunk` (NUL-terminated; must not be NULL) and runs it in
+ * the sandbox. `chunkname` may be NULL and only feeds diagnostics.
+ * Returns NULL on success; otherwise see the error contract above (the
+ * caller owns the returned st_error). The runtime stays usable after an
+ * error. */
+struct st_error *st_lua_run(struct st_lua_rt *rt, const char *chunk,
+                            const char *chunkname);
+
+#endif /* ST_EXT_LUA_H */

src/gen/args.c

@@ -0,0 +1,655 @@
+/*
+ * args.c - the generated ./configure preamble emitter (todo 18).
+ *
+ * Generates the full --help / argument-parsing section that replaces the
+ * v1 minimal preamble todo 16 emitted inline in configure.c. See
+ * gen/args.h for the emitted-section layout, the option -> --enable
+ * mapping, the VAR=VALUE eval-assignment security argument, the
+ * cross_compiling contract and the error categories.
+ *
+ * Safety invariants, carried through from the detect chain:
+ *   - every user-supplied byte (option names, project name/version)
+ *     reaches the emitted script either through st_sh_quote (single-
+ *     quoted literal) or through a validated-identifier position
+ *     (enable_<name>, --enable-<name>);
+ *   - the positional VAR=VALUE assignment is handled by the EMITTED
+ *     script with the sed-quote + eval pattern (see args.h), never by
+ *     this generator - the value is only ever quoted at configure time.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "gen/args.h"
+
+#include "cli.h" /* STUPIDTOOLS_VERSION (the generated-by line) */
+
+#include "error.h"
+#include "gen/sh_emit.h"
+#include "kdl/ast.h"
+#include "kdl/value.h"
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* ---- small helpers (mirror configure.c) -------------------------------- */
+
+/* True when `s` is a valid POSIX shell identifier: letter/underscore,
+ * then letters/digits/underscores, non-empty. Option names must pass
+ * this (they land in enable_<name> / --enable-<name> positions). */
+static bool
+valid_ident(const char *s)
+{
+    const unsigned char *p;
+
+    if (s == NULL || *s == '\0') {
+        return false;
+    }
+    p = (const unsigned char *)s;
+    if (!((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') ||
+          *p == '_')) {
+        return false;
+    }
+    for (p++; *p != '\0'; p++) {
+        if (!((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') ||
+              (*p >= '0' && *p <= '9') || *p == '_')) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/* Build an owned ST_ERR_KDL_SCHEMA error whose span lives in the same
+ * allocation as the error struct (the parser.c pattern). Returns NULL
+ * only on allocation failure. */
+static struct st_error *
+err_at_owned(struct st_span sp, const char *msg)
+{
+    const size_t align = _Alignof(struct st_span);
+    const size_t esize =
+        (sizeof(struct st_error) + align - 1) & ~(align - 1);
+    struct st_error *e;
+    struct st_span *spc;
+    size_t mlen;
+
+    if (msg == NULL) {
+        msg = "";
+    }
+    e = malloc(esize + sizeof(struct st_span));
+    if (e == NULL) {
+        return NULL;
+    }
+    mlen = strlen(msg);
+    e->message = malloc(mlen + 1);
+    if (e->message == NULL) {
+        free(e);
+        return NULL;
+    }
+    memcpy(e->message, msg, mlen + 1);
+    e->category = ST_ERR_KDL_SCHEMA;
+    spc = (struct st_span *)((unsigned char *)e + esize);
+    *spc = sp;
+    e->span = spc;
+    return e;
+}
+
+/* Interpret `tok` as the non-empty unannotated string a slot requires;
+ * on success *out owns the string. Value-model failures are re-owned as
+ * schema errors (the checks.c pattern). */
+static struct st_error *
+extract_string(const struct st_kdl_token_ref *tok, const char *ctx,
+               char **out)
+{
+    struct st_kdl_value v;
+    struct st_error *e;
+    char msg[192];
+
+    *out = NULL;
+    e = st_kdl_value_from_token(tok, &v);
+    if (e != NULL) {
+        struct st_span sp = e->span != NULL ? *e->span
+                                            : (struct st_span){ NULL, 0, 0 };
+        struct st_error *r = err_at_owned(sp, e->message != NULL
+                                                    ? e->message : "");
+
+        st_error_free(e);
+        return r;
+    }
+    if (v.kind != ST_KDL_VAL_STRING) {
+        snprintf(msg, sizeof msg, "%s must be a non-empty string", ctx);
+        e = err_at_owned(tok->span, msg);
+        st_kdl_value_free(&v);
+        return e;
+    }
+    if (v.as.str[0] == '\0') {
+        snprintf(msg, sizeof msg, "%s must be a non-empty string", ctx);
+        e = err_at_owned(tok->span, msg);
+        st_kdl_value_free(&v);
+        return e;
+    }
+    *out = v.as.str;
+    v.as.str = NULL;
+    st_kdl_value_free(&v);
+    return NULL;
+}
+
+/* Compare a property key against a literal identifier. */
+static struct st_error *
+key_equals(const struct st_kdl_token_ref *key, const char *s, bool *out)
+{
+    struct st_kdl_value v;
+    struct st_error *e;
+
+    if (key->kind == ST_TOK_IDENT) {
+        *out = key->len == strlen(s) && memcmp(key->text, s, key->len) == 0;
+        return NULL;
+    }
+    e = st_kdl_value_from_token(key, &v);
+    if (e != NULL) {
+        struct st_error *r;
+        struct st_span sp = e->span != NULL
+                                ? *e->span
+                                : (struct st_span){ NULL, 0, 0 };
+
+        r = err_at_owned(sp, e->message != NULL ? e->message : "");
+        st_error_free(e);
+        *out = false;
+        return r;
+    }
+    *out = v.kind == ST_KDL_VAL_STRING && strcmp(v.as.str, s) == 0;
+    st_kdl_value_free(&v);
+    return NULL;
+}
+
+/* ---- collection -------------------------------------------------------- */
+
+/* Read the `default` bool property of an option node. */
+static struct st_error *
+collect_option_default(const struct st_kdl_node *node, bool *out)
+{
+    const struct st_kdl_prop *prop;
+
+    *out = false;
+    for (prop = node->props; prop != NULL; prop = prop->next) {
+        bool is_default = false;
+        struct st_error *e = key_equals(&prop->key, "default", &is_default);
+        struct st_kdl_value v;
+
+        if (e != NULL) {
+            return e;
+        }
+        if (!is_default) {
+            continue;
+        }
+        e = st_kdl_value_from_token(&prop->value, &v);
+        if (e != NULL) {
+            struct st_error *r;
+            struct st_span sp = e->span != NULL
+                                    ? *e->span
+                                    : (struct st_span){ NULL, 0, 0 };
+
+            r = err_at_owned(sp, e->message != NULL ? e->message : "");
+            st_error_free(e);
+            return r;
+        }
+        if (v.kind != ST_KDL_VAL_BOOL) {
+            e = err_at_owned(prop->value.span,
+                             "option 'default' must be an unannotated "
+                             "#true or #false");
+            st_kdl_value_free(&v);
+            return e;
+        }
+        *out = v.as.b;
+        st_kdl_value_free(&v);
+        return NULL;
+    }
+    return NULL;
+}
+
+/* Parse the `project "<name>" version "<semver>"` node into owned
+ * strings. The schema guarantees the shape; this is defense in depth. */
+static struct st_error *
+collect_project(const struct st_kdl_node *node, struct st_gen_args *out)
+{
+    const struct st_kdl_arg *a0;
+    const struct st_kdl_arg *a1;
+    const struct st_kdl_arg *a2;
+    struct st_error *e;
+
+    a0 = node->args;
+    a1 = a0 != NULL ? a0->next : NULL;
+    a2 = a1 != NULL ? a1->next : NULL;
+    if (a0 == NULL || a1 == NULL || a2 == NULL) {
+        return err_at_owned(node->name.span,
+                            "project node is malformed (expected 'project "
+                            "\"name\" version \"semver\"')");
+    }
+    if (a1->value.kind != ST_TOK_IDENT || a1->value.len != 7 ||
+        memcmp(a1->value.text, "version", 7) != 0) {
+        return err_at_owned(a1->value.span,
+                            "project node is malformed (expected the "
+                            "'version' keyword before the version string)");
+    }
+    e = extract_string(&a0->value, "project name", &out->project_name);
+    if (e != NULL) {
+        return e;
+    }
+    e = extract_string(&a2->value, "project version", &out->project_version);
+    if (e != NULL) {
+        return e;
+    }
+    return NULL;
+}
+
+struct st_error *
+st_gen_args_collect(const struct st_kdl_document *doc, struct st_gen_args *out)
+{
+    struct st_error *err = NULL;
+    const struct st_kdl_node *node;
+    bool have_project = false;
+
+    if (doc == NULL || out == NULL) {
+        return st_error_usage("st_gen_args_collect: NULL argument");
+    }
+    memset(out, 0, sizeof(*out));
+    for (node = doc->nodes; node != NULL; node = node->next) {
+        struct st_kdl_value v;
+        struct st_error *e;
+        bool is_option = false;
+        bool is_project = false;
+
+        /* identify the node kind by name (any string form) */
+        if (node->name.kind == ST_TOK_IDENT) {
+            is_option = node->name.len == 6 &&
+                        memcmp(node->name.text, "option", 6) == 0;
+            is_project = node->name.len == 7 &&
+                         memcmp(node->name.text, "project", 7) == 0;
+        } else {
+            e = st_kdl_value_from_token(&node->name, &v);
+            if (e != NULL) {
+                struct st_span sp = e->span != NULL
+                                        ? *e->span
+                                        : (struct st_span){ NULL, 0, 0 };
+
+                err = err_at_owned(sp, e->message != NULL ? e->message : "");
+                st_error_free(e);
+                goto done;
+            }
+            is_option = v.kind == ST_KDL_VAL_STRING &&
+                        strcmp(v.as.str, "option") == 0;
+            is_project = v.kind == ST_KDL_VAL_STRING &&
+                         strcmp(v.as.str, "project") == 0;
+            st_kdl_value_free(&v);
+        }
+
+        if (is_project && !have_project) {
+            have_project = true;
+            err = collect_project(node, out);
+            if (err != NULL) {
+                goto done;
+            }
+            continue;
+        }
+        if (!is_option) {
+            continue;
+        }
+        {
+            char *name = NULL;
+            bool default_on = false;
+            size_t i;
+            char msg[256];
+
+            e = extract_string(&node->args->value, "option name", &name);
+            if (e != NULL) {
+                err = e;
+                goto done;
+            }
+            if (!valid_ident(name)) {
+                snprintf(msg, sizeof msg,
+                         "option name '%s' is not a valid shell identifier "
+                         "(--enable-<name> requires [A-Za-z_][A-Za-z0-9_]*)",
+                         name);
+                err = err_at_owned(node->args->value.span, msg);
+                free(name);
+                goto done;
+            }
+            e = collect_option_default(node, &default_on);
+            if (e != NULL) {
+                free(name);
+                err = e;
+                goto done;
+            }
+            for (i = 0; i < out->option_count; i++) {
+                if (strcmp(out->options[i].name, name) == 0) {
+                    snprintf(msg, sizeof msg, "duplicate option '%s'", name);
+                    err = err_at_owned(node->args->value.span, msg);
+                    free(name);
+                    goto done;
+                }
+            }
+            {
+                struct st_gen_option *grown = realloc(
+                    out->options,
+                    (out->option_count + 1) * sizeof(*out->options));
+
+                if (grown == NULL) {
+                    free(name);
+                    err = st_error_internal("out of memory collecting "
+                                            "options");
+                    goto done;
+                }
+                out->options = grown;
+                out->options[out->option_count].name = name;
+                out->options[out->option_count].default_on = default_on;
+                out->option_count++;
+            }
+        }
+    }
+    if (!have_project) {
+        err = st_error_kdl_schema("missing project node");
+        goto done;
+    }
+
+done:
+    if (err != NULL) {
+        st_gen_args_free(out);
+    }
+    return err;
+}
+
+void
+st_gen_args_free(struct st_gen_args *args)
+{
+    size_t i;
+
+    if (args == NULL) {
+        return;
+    }
+    for (i = 0; i < args->option_count; i++) {
+        free(args->options[i].name);
+    }
+    free(args->options);
+    free(args->project_name);
+    free(args->project_version);
+    memset(args, 0, sizeof(*args));
+}
+
+/* ---- fixed shell text (emitted verbatim via st_sh_emit_str) ------------ */
+
+/* The `%` in the emitted printf formats is why all of this is emitted
+ * with st_sh_emit_str (verbatim), not fprintf (which would eat `%s`). */
+
+static const char ARGS_PRE[] =
+    "\n"
+    "# --- PREAMBLE ---\n"
+    "# Full argument parsing (todo 18): --help/-h, --version, --prefix/\n"
+    "# --exec-prefix/--host/--build in both '=' and space forms, the\n"
+    "# per-option --enable-<name>/--disable-<name> flags, and generic\n"
+    "# VAR=VALUE overrides (positional, e.g. `./configure VAR=VALUE`, or\n"
+    "# exported by the invoking shell, e.g. `VAR=VALUE ./configure`).\n"
+    "# Unknown --* options error. The loop only READS \"$@\", so the\n"
+    "# config.log init right after this section still sees the complete\n"
+    "# original invocation.\n"
+    "prefix=/usr/local\n"
+    "exec_prefix=\n"
+    "srcdir=.\n"
+    "build=\n"
+    "host=\n"
+    "cross_compiling=no\n";
+
+static const char USAGE_HEAD[] =
+    "st_usage() {\n"
+    "    printf '%s\\n' 'Usage: ./configure [OPTION]... [VAR=VALUE]...'\n"
+    "    printf '%s\\n' ''\n"
+    "    printf '%s\\n' 'Configuration:'\n"
+    "    printf '%s\\n' '  --prefix=DIR, --prefix DIR'\n"
+    "    printf '%s\\n' '                        install architecture-independent files in DIR (default: /usr/local)'\n"
+    "    printf '%s\\n' '  --exec-prefix=DIR, --exec-prefix DIR'\n"
+    "    printf '%s\\n' '                        install architecture-dependent files in DIR (default: same as --prefix)'\n"
+    "    printf '%s\\n' '  --host=TRIPLET, --host TRIPLET'\n"
+    "    printf '%s\\n' '                        the platform the program will run on;'\n"
+    "    printf '%s\\n' '                        differs from --build -> cross-compiling'\n"
+    "    printf '%s\\n' '  --build=TRIPLET, --build TRIPLET'\n"
+    "    printf '%s\\n' '                        the platform the build is running on'\n"
+    "    printf '%s\\n' '  VAR=VALUE              override a variable before substitution;'\n"
+    "    printf '%s\\n' '                        both VAR=VALUE ./configure and'\n"
+    "    printf '%s\\n' '                        ./configure VAR=VALUE work'\n";
+
+static const char USAGE_TAIL[] =
+    "    printf '%s\\n' ''\n"
+    "    printf '%s\\n' 'Informational:'\n"
+    "    printf '%s\\n' '  -h, --help             print this help and exit'\n"
+    "    printf '%s\\n' '  --version              print the program version and exit'\n"
+    "}\n"
+    "\n";
+
+static const char LOOP_PRE[] =
+    "# The argument parser. A loop-carried $st_need implements the two-\n"
+    "# token lookahead the space forms need: when $st_need is set, the\n"
+    "# NEXT argument is the value of that option (a value that looks like\n"
+    "# an option is rejected). A still-pending $st_need after the loop\n"
+    "# is an error.\n"
+    "st_need=\n"
+    "for st_arg in \"$@\"; do\n"
+    "    if [ -n \"$st_need\" ]; then\n"
+    "        case \"$st_arg\" in\n"
+    "            -*)\n"
+    "                printf \"configure: error: option '--%s' requires an argument\\n\" \"$st_need\" >&2\n"
+    "                st_usage >&2\n"
+    "                exit 1\n"
+    "                ;;\n"
+    "            *)\n"
+    "                case \"$st_need\" in\n"
+    "                    prefix) prefix=$st_arg ;;\n"
+    "                    exec-prefix) exec_prefix=$st_arg ;;\n"
+    "                    host) host=$st_arg ;;\n"
+    "                    build) build=$st_arg ;;\n"
+    "                esac\n"
+    "                st_need=\n"
+    "                continue\n"
+    "                ;;\n"
+    "        esac\n"
+    "    fi\n"
+    "    case \"$st_arg\" in\n"
+    "        -h|--help)\n"
+    "            st_usage\n"
+    "            exit 0\n"
+    "            ;;\n";
+
+static const char LOOP_VALUE_ARMS[] =
+    "        --prefix=*)\n"
+    "            prefix=${st_arg#--prefix=}\n"
+    "            if [ -z \"$prefix\" ]; then\n"
+    "                printf '%s\\n' \"configure: error: option '--prefix' requires a non-empty argument\" >&2\n"
+    "                st_usage >&2\n"
+    "                exit 1\n"
+    "            fi\n"
+    "            ;;\n"
+    "        --exec-prefix=*)\n"
+    "            exec_prefix=${st_arg#--exec-prefix=}\n"
+    "            if [ -z \"$exec_prefix\" ]; then\n"
+    "                printf '%s\\n' \"configure: error: option '--exec-prefix' requires a non-empty argument\" >&2\n"
+    "                st_usage >&2\n"
+    "                exit 1\n"
+    "            fi\n"
+    "            ;;\n"
+    "        --host=*)\n"
+    "            host=${st_arg#--host=}\n"
+    "            if [ -z \"$host\" ]; then\n"
+    "                printf '%s\\n' \"configure: error: option '--host' requires a non-empty argument\" >&2\n"
+    "                st_usage >&2\n"
+    "                exit 1\n"
+    "            fi\n"
+    "            ;;\n"
+    "        --build=*)\n"
+    "            build=${st_arg#--build=}\n"
+    "            if [ -z \"$build\" ]; then\n"
+    "                printf '%s\\n' \"configure: error: option '--build' requires a non-empty argument\" >&2\n"
+    "                st_usage >&2\n"
+    "                exit 1\n"
+    "            fi\n"
+    "            ;;\n"
+    "        --prefix|--exec-prefix|--host|--build)\n"
+    "            st_need=${st_arg#--}\n"
+    "            ;;\n";
+
+static const char LOOP_TAIL[] =
+    "        --*=*)\n"
+    "            # an unknown option written in =value form\n"
+    "            printf 'configure: error: unrecognized option %s\\n' \"$st_arg\" >&2\n"
+    "            st_usage >&2\n"
+    "            exit 1\n"
+    "            ;;\n"
+    "        *=*)\n"
+    "            # VAR=VALUE: split at the FIRST '=', validate VAR as a\n"
+    "            # shell identifier, single-quote-escape the value and eval\n"
+    "            # the assignment. The value lands between REAL single\n"
+    "            # quotes in the eval string (the expansion happens in the\n"
+    "            # outer pass, eval re-parses the result), so nothing in it\n"
+    "            # is ever re-parsed or executed (autoconf's pattern).\n"
+    "            st_var=${st_arg%%=*}\n"
+    "            st_val=${st_arg#*=}\n"
+    "            case \"$st_var\" in\n"
+    "                ''|*[!A-Za-z0-9_]*|[0-9]*)\n"
+    "                    printf 'configure: error: invalid variable assignment %s\\n' \"$st_arg\" >&2\n"
+    "                    st_usage >&2\n"
+    "                    exit 1\n"
+    "                    ;;\n"
+    "            esac\n"
+    "            st_val_q=$(printf '%s' \"$st_val\" | sed \"s/'/'\\\\\\\\''/g\")\n"
+    "            eval \"$st_var='$st_val_q'\"\n"
+    "            ;;\n"
+    "        *)\n"
+    "            printf 'configure: error: unrecognized option %s\\n' \"$st_arg\" >&2\n"
+    "            st_usage >&2\n"
+    "            exit 1\n"
+    "            ;;\n"
+    "    esac\n"
+    "done\n"
+    "\n"
+    "# a still-pending space-form option had no value\n"
+    "if [ -n \"$st_need\" ]; then\n"
+    "    printf \"configure: error: option '--%s' requires an argument\\n\" \"$st_need\" >&2\n"
+    "    st_usage >&2\n"
+    "    exit 1\n"
+    "fi\n"
+    "\n"
+    "# exec_prefix defaults to prefix (autoconf semantics)\n"
+    "if [ -z \"$exec_prefix\" ]; then\n"
+    "    exec_prefix=$prefix\n"
+    "fi\n"
+    "\n"
+    "# cross-compiling when --host differs from --build (both set)\n"
+    "if [ -n \"$host\" ] && [ \"$host\" != \"$build\" ]; then\n"
+    "    cross_compiling=yes\n"
+    "fi\n";
+
+/* ---- emission ---------------------------------------------------------- */
+
+struct st_error *
+st_gen_args_emit(FILE *out, const struct st_gen_args *args)
+{
+    size_t i;
+    char *qn;
+    char *qv;
+
+    if (out == NULL || args == NULL) {
+        return st_error_usage("st_gen_args_emit: NULL argument");
+    }
+    if (st_sh_emit_str(out, ARGS_PRE) < 0) {
+        return st_error_io("I/O error emitting the preamble");
+    }
+
+    /* per-option defaults: enable_<name>=yes|no */
+    for (i = 0; i < args->option_count; i++) {
+        if (fprintf(out, "enable_%s=%s\n", args->options[i].name,
+                    args->options[i].default_on ? "yes" : "no") < 0) {
+            return st_error_io("I/O error emitting the preamble");
+        }
+    }
+
+    /* the st_usage() help text */
+    if (st_sh_emit_str(out, "\n") < 0 ||
+        st_sh_emit_str(out, USAGE_HEAD) < 0) {
+        return st_error_io("I/O error emitting the preamble");
+    }
+    if (args->option_count > 0) {
+        if (st_sh_emit_str(out,
+                           "    printf '%s\\n' ''\n"
+                           "    printf '%s\\n' 'Optional Features'\n"
+                           "    printf '%s\\n' '  (DSL option nodes; --enable "
+                           "sets the enable_<name> variable to yes)'\n") < 0) {
+            return st_error_io("I/O error emitting the preamble");
+        }
+    }
+    for (i = 0; i < args->option_count; i++) {
+        const char *name = args->options[i].name;
+
+        if (fprintf(out,
+                    "    printf '%%s\\n' '  --enable-%s          enable "
+                    "the %s option (default: %s)'\n"
+                    "    printf '%%s\\n' '  --disable-%s         disable "
+                    "the %s option'\n",
+                    name, name, args->options[i].default_on ? "yes" : "no",
+                    name, name) < 0) {
+            return st_error_io("I/O error emitting the preamble");
+        }
+    }
+    if (st_sh_emit_str(out, USAGE_TAIL) < 0) {
+        return st_error_io("I/O error emitting the preamble");
+    }
+
+    /* the parser loop */
+    if (st_sh_emit_str(out, LOOP_PRE) < 0) {
+        return st_error_io("I/O error emitting the preamble");
+    }
+    qn = st_sh_quote(args->project_name != NULL ? args->project_name : "");
+    qv = st_sh_quote(args->project_version != NULL ? args->project_version
+                                                   : "");
+    if (qn == NULL || qv == NULL) {
+        free(qn);
+        free(qv);
+        return st_error_internal("out of memory quoting the project "
+                                 "identity");
+    }
+    if (fprintf(out,
+                "        --version)\n"
+                "            printf 'configure for %%s %%s\\n' %s %s\n"
+                "            printf '%%s\\n' 'generated by stupidtools "
+                STUPIDTOOLS_VERSION
+                " - DO NOT EDIT'\n"
+                "            exit 0\n"
+                "            ;;\n",
+                qn, qv) < 0) {
+        free(qn);
+        free(qv);
+        return st_error_io("I/O error emitting the preamble");
+    }
+    free(qn);
+    free(qv);
+    if (st_sh_emit_str(out, LOOP_VALUE_ARMS) < 0) {
+        return st_error_io("I/O error emitting the preamble");
+    }
+
+    /* per-option enable/disable arms (names are validated identifiers) */
+    for (i = 0; i < args->option_count; i++) {
+        const char *name = args->options[i].name;
+
+        if (fprintf(out,
+                    "        --enable-%s) enable_%s=yes ;;\n"
+                    "        --disable-%s) enable_%s=no ;;\n",
+                    name, name, name, name) < 0) {
+            return st_error_io("I/O error emitting the preamble");
+        }
+    }
+    if (st_sh_emit_str(out, LOOP_TAIL) < 0) {
+        return st_error_io("I/O error emitting the preamble");
+    }
+    if (ferror(out)) {
+        return st_error_io("I/O error emitting the preamble");
+    }
+    return NULL;
+}

src/gen/args.h

@@ -0,0 +1,142 @@
+/*
+ * args.h - the generated ./configure preamble: --help + argument parsing
+ * (todo 18).
+ *
+ * This module REPLACES the v1 minimal preamble todo 16 emitted inline in
+ * configure.c (structurally marked `# --- PREAMBLE ---` there for exactly
+ * this). It generates the FULL argument-parsing section of the emitted
+ * POSIX-sh ./configure:
+ *
+ *   - `--help` / `-h`: a real usage text - the standard options
+ *     (--prefix=<dir>, --exec-prefix=<dir>, --host=<triplet>,
+ *     --build=<triplet>), the generic VAR=VALUE override, the per-option
+ *     enable/disable flags (--enable-<name> and --disable-<name>), and
+ *     --help/--version - then exit 0.
+ *   - `--version`: the DSL project's name + version (the project node),
+ *     exit 0.
+ *   - `--prefix=<dir>` / `--prefix <dir>` (both forms) and the same two
+ *     forms for `--exec-prefix`, `--host`, `--build`. An empty value
+ *     (`--prefix=`), a missing value, or a value that looks like an
+ *     option is a clean error: message + usage to stderr, exit 1.
+ *   - per-DSL-option `--enable-<name>` / `--disable-<name>` setting
+ *     `enable_<name>=yes|no`, defaulted from the option's `default`
+ *     property (see THE OPTION -> FLAG MAPPING below).
+ *   - generic positional `VAR=VALUE` overrides (`./configure CC=clang`);
+ *     the exported form (`CC=clang ./configure`) is the invoking shell's
+ *     ordinary environment contract and needs no parser support (both
+ *     land in $VAR, which the substitution and the toolchain defaults
+ *     read). VAR must be a valid shell identifier; the value is
+ *     single-quote-escaped and assigned via eval so nothing in it is
+ *     ever re-parsed or executed (autoconf's pattern; see EMITTED
+ *     SECTION LAYOUT).
+ *   - an unknown `--*` prints "unrecognized option" + the usage to
+ *     stderr and exits 1.
+ *   - `$cross_compiling=yes` when `--host` differs from `--build` (both
+ *     must be set; a simple string comparison).
+ *   - `$exec_prefix` defaults to `$prefix` (autoconf semantics).
+ *
+ * THE OPTION -> FLAG MAPPING (the contract todo 23 consumes)
+ * -----------------------------------------------------------
+ * A top-level DSL `option "name" default=#bool` node (src/kdl/schema.h)
+ * maps to the flag pair `--enable-<name>` / `--disable-<name>` and the
+ * shell variable `enable_<name>` (yes|no; the DSL `default` property,
+ * false when the property is absent). So `option "debug" default=#false`
+ * yields `--enable-debug` / `--disable-debug` with `enable_debug=no` by
+ * default. v1 maps EVERY option to --enable/--disable; the
+ * `--with-<x>` / `--without-<x>` pair is reserved for a future DSL node
+ * kind and is not generated today. The option name must be a valid POSIX
+ * shell identifier ([A-Za-z_][A-Za-z0-9_]*) - enforced at GENERATION
+ * time (a hostile name errors before any shell text is emitted), as is
+ * name uniqueness. The section is generated from the document, never
+ * hardcoded.
+ *
+ * EMITTED SECTION LAYOUT (inside the generated configure)
+ * -------------------------------------------------------
+ *   # --- PREAMBLE ---
+ *   prefix=/usr/local; exec_prefix=; srcdir=.; build=; host=;
+ *   cross_compiling=no; enable_<name>=<default> per option
+ *   st_usage() { ... }            the help text
+ *   for st_arg in "$@"; do ...    the parser; a loop-carried $st_need
+ *                                 variable implements the two-token
+ *                                 lookahead the space forms need (when
+ *                                 $st_need is set, the NEXT argument is
+ *                                 the value of that option)
+ *   done
+ *   trailing checks: a still-pending $st_need is an error; exec_prefix
+ *   defaults to $prefix; cross_compiling when host differs from build.
+ *
+ * The VAR=VALUE assignment is `st_val_q=$(printf '%s' "$st_val" | sed
+ * "s/'/'\\''/g")` followed by `eval "$st_var='$st_val_q'"`: the value
+ * lands between REAL single quotes in the eval string (the expansion
+ * happens in the outer pass, eval re-parses the result), so quotes,
+ * `$()`, backticks, `;` and newlines are all literal - the same
+ * sed-quote bake-in config.c uses for config.status.
+ *
+ * CONTRACT PRESERVED (todo 17): the parser only READS "$@" (a for loop
+ * never shifts), so the config.log init emitted right after this section
+ * still captures the complete original invocation into st_orig_args.
+ *
+ * POSIX-SH ONLY (AGENTS.md §4): no [[ ]], no arrays, no local, no ==, no
+ * <<<, no &>, no set -e; `$(...)` is used. sh -n / bash -n / zsh -n must
+ * pass (dash is not installed on this host - see issues.md).
+ *
+ * ERRORS
+ * ------
+ * st_gen_args_collect: NULL arguments -> ST_ERR_USAGE; a non-identifier
+ * or duplicate option name, or a malformed project node ->
+ * ST_ERR_KDL_SCHEMA (span heap-allocated in the same block as the error,
+ * the parser.c pattern); a value-model failure on a name/version/default
+ * is re-owned as a schema error. st_gen_args_emit: NULL arguments ->
+ * ST_ERR_USAGE; quoting/allocation failure -> ST_ERR_INTERNAL; stream
+ * write failure -> ST_ERR_IO. Both leave no owned memory behind; a
+ * failed collect leaves *out zeroed (free-able with st_gen_args_free).
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef ST_GEN_ARGS_H
+#define ST_GEN_ARGS_H
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdio.h>
+
+struct st_error;
+struct st_kdl_document;
+
+/* One collected DSL option: the --enable-<name>/--disable-<name> pair and
+ * its default. */
+struct st_gen_option {
+    char *name;      /* owned; validated POSIX shell identifier */
+    bool default_on; /* the `default` property; false when absent */
+};
+
+/* Everything the preamble emitter needs, collected from a validated
+ * document. All strings are owned; release with st_gen_args_free() (NULL
+ * args is a safe no-op). */
+struct st_gen_args {
+    char *project_name;    /* project "<name>" */
+    char *project_version; /* project ... version "<semver>" */
+    struct st_gen_option *options;
+    size_t option_count;
+};
+
+/* Collect the project name + version and the top-level option nodes from
+ * `doc` (schema-validated) into `out`. `out` is zeroed first; on error
+ * any partially-collected memory is released and `out` is left zeroed.
+ * Returns NULL on success, an owned st_error otherwise (see ERRORS). */
+struct st_error *st_gen_args_collect(const struct st_kdl_document *doc,
+                                     struct st_gen_args *out);
+
+/* Release everything owned by `args`. NULL is a safe no-op. */
+void st_gen_args_free(struct st_gen_args *args);
+
+/* Emit the `# --- PREAMBLE ---` section (the full argument parser, the
+ * st_usage() help text, the per-option enable_ defaults and flags, the
+ * VAR=VALUE handler, the trailing exec_prefix/cross_compiling checks)
+ * into `out` from a collected `args`. Returns NULL on success, an owned
+ * st_error otherwise (see ERRORS). */
+struct st_error *st_gen_args_emit(FILE *out, const struct st_gen_args *args);
+
+#endif /* ST_GEN_ARGS_H */

src/gen/config.c

@@ -0,0 +1,280 @@
+/*
+ * config.c - config.log / config.h / config.status emitters (todo 17).
+ *
+ * Four pure emitters; see gen/config.h for the model, the emitted text of
+ * each section, the sed-quote bake-in security argument, the v1
+ * limitations and the error categories.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "gen/config.h"
+
+#include "cli.h" /* STUPIDTOOLS_VERSION (the created-by / generated-by line) */
+
+#include "error.h"
+#include "gen/sh_emit.h"
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* ---- small helpers ----------------------------------------------------- */
+
+/* True when `s` is a valid POSIX shell identifier (the have_<name> /
+ * HAVE_<NAME> interpolation positions demand it; mirrors configure.c). */
+static bool
+valid_ident(const char *s)
+{
+    const unsigned char *p;
+
+    if (s == NULL || *s == '\0') {
+        return false;
+    }
+    p = (const unsigned char *)s;
+    if (!((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') ||
+          *p == '_')) {
+        return false;
+    }
+    for (p++; *p != '\0'; p++) {
+        if (!((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') ||
+              (*p >= '0' && *p <= '9') || *p == '_')) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/* Uppercase copy of a validated identifier: "pthread" -> "PTHREAD". */
+static char *
+ident_upper(const char *s)
+{
+    size_t i;
+    size_t n = strlen(s);
+    char *up = malloc(n + 1);
+
+    if (up == NULL) {
+        return NULL;
+    }
+    for (i = 0; i < n; i++) {
+        unsigned char c = (unsigned char)s[i];
+
+        up[i] = (char)((c >= 'a' && c <= 'z') ? c - 'a' + 'A' : c);
+    }
+    up[n] = '\0';
+    return up;
+}
+
+/* ---- fixed shell text (emitted verbatim via st_sh_emit_str) ------------ */
+
+/* Section A: config.log init + original-args capture. Runs right after
+ * the preamble. The `%` in `printf 'configure invocation: %s\n'` is why
+ * this is emitted verbatim (fprintf would eat it). The two sed pipelines
+ * rewrite every ' into '\'' so the values can later be baked into
+ * config.status as single-quoted literals. */
+static const char CONFIG_LOG_INIT[] =
+    "\n"
+    "# --- config.log: transcript of this configure run ---\n"
+    "# Probe snippets append their compiler stdout/stderr to $config_log\n"
+    "# (see the probe section below); a `## results` summary of every\n"
+    "# have_<feature> value is appended after probing. The original\n"
+    "# invocation is captured here for config.status (written at the end\n"
+    "# of this script), which re-runs configure with these arguments.\n"
+    "st_orig_args=\"$@\"\n"
+    "st_configure_path=$0\n"
+    "# Single-quote-escaped copies (every ' becomes '\\'' in shell): the\n"
+    "# values can then be baked into config.status as safe quoted\n"
+    "# literals - nothing in them is ever re-expanded when config.status\n"
+    "# runs.\n"
+    "st_orig_args_q=$(printf '%s' \"$st_orig_args\" | sed \"s/'/'\\\\\\\\''/g\")\n"
+    "st_configure_path_q=$(printf '%s' \"$st_configure_path\" | sed \"s/'/'\\\\\\\\''/g\")\n"
+    ": \"${config_log:=./config.log}\"\n"
+    "{\n"
+    "    printf '%s\\n' 'This file contains any messages produced by compilers while'\n"
+    "    printf '%s\\n' 'running configure, to aid debugging if configure makes a mistake.'\n"
+    "    printf '%s\\n' ''\n"
+    "    printf '%s\\n' 'It was created by stupidtools configure "
+    STUPIDTOOLS_VERSION
+    ".'\n"
+    "    printf 'configure invocation: %s\\n' \"$st_orig_args\"\n"
+    "    printf '%s\\n' \"timestamp: $(date)\"\n"
+    "    printf '%s\\n' \"host: $(uname -s) $(uname -m)\"\n"
+    "    printf '%s\\n' \"shell: ${SHELL:-unknown}\"\n"
+    "    printf '%s\\n' ''\n"
+    "} > \"$config_log\"\n";
+
+/* Section B (part 1): the `## results` summary appended to $config_log. */
+static const char RESULTS_PRE[] =
+    "\n"
+    "# --- probe results (appended to config.log) ---\n"
+    "# One have_<feature>=yes|no line per feature, as determined by the\n"
+    "# probes above. config.log is therefore: the header (top), every\n"
+    "# probe's compiler output (middle), this summary (end).\n"
+    "{\n"
+    "    printf '%s\\n' '## results'\n";
+
+static const char RESULTS_POST[] =
+    "} >> \"$config_log\"\n";
+
+/* Section B (part 2): the ./config.h writer. */
+static const char CONFIG_H_PRE[] =
+    "\n"
+    "# --- config.h ---\n"
+    "# HAVE_<FEATURE> defines written at CONFIGURE time: one define per\n"
+    "# feature whose probe result was 'yes' (the content reflects the\n"
+    "# actual probe results, never the generator's guesses). The\n"
+    "# ST_CONFIG_H guard keeps the file safe to include repeatedly.\n"
+    "{\n"
+    "    printf '%s\\n' '/* config.h - generated by stupidtools configure "
+    STUPIDTOOLS_VERSION
+    " - DO NOT EDIT. */'\n"
+    "    printf '%s\\n' '#ifndef ST_CONFIG_H'\n"
+    "    printf '%s\\n' '#define ST_CONFIG_H'\n"
+    "    printf '%s\\n' ''\n";
+
+static const char CONFIG_H_POST[] =
+    "    printf '%s\\n' ''\n"
+    "    printf '%s\\n' '#endif /* ST_CONFIG_H */'\n"
+    "} > ./config.h\n";
+
+/* Section C: the ./config.status writer. The here-document is UNQUOTED on
+ * purpose: configure-time expansion bakes $st_orig_args_q /
+ * $st_configure_path_q into the file (expansion results are never
+ * re-parsed, so nothing can execute), while every `\$` survives as a
+ * literal `$` for config.status to expand when IT runs. */
+static const char CONFIG_STATUS[] =
+    "\n"
+    "# --- config.status ---\n"
+    "# A self-contained POSIX-sh helper written at configure time. It\n"
+    "# re-runs ./configure with the arguments of the ORIGINAL invocation\n"
+    "# (captured at the top of this script and baked in here as quoted\n"
+    "# literals, so no value is ever re-expanded when config.status\n"
+    "# runs).\n"
+    "cat > ./config.status <<ST_STATUS_EOF\n"
+    "#!/bin/sh\n"
+    "# config.status - re-runs ./configure with the original arguments.\n"
+    "# Generated by stupidtools configure "
+    STUPIDTOOLS_VERSION
+    " - DO NOT EDIT.\n"
+    "\n"
+    "st_orig_args='$st_orig_args_q'\n"
+    "st_configure_path='$st_configure_path_q'\n"
+    "\n"
+    "case \"\\${1-}\" in\n"
+    "    --recheck|'')\n"
+    "        exec \"\\${SHELL:-sh}\" \"\\$st_configure_path\" \\$st_orig_args\n"
+    "        ;;\n"
+    "    --config)\n"
+    "        printf '%s\\n' \"\\$st_orig_args\"\n"
+    "        ;;\n"
+    "    --help)\n"
+    "        printf '%s\\n' 'Usage: ./config.status [OPTION]'\n"
+    "        printf '%s\\n' 'Re-run the original ./configure invocation.'\n"
+    "        printf '%s\\n' 'Options:'\n"
+    "        printf '%s\\n' '  --recheck  re-run ./configure with the original arguments'\n"
+    "        printf '%s\\n' '  --config   print the original configure arguments'\n"
+    "        printf '%s\\n' '  --help     print this help'\n"
+    "        ;;\n"
+    "    *)\n"
+    "        printf 'config.status: error: unrecognized option %s\\n' \"\\$1\" >&2\n"
+    "        exit 1\n"
+    "        ;;\n"
+    "esac\n"
+    "ST_STATUS_EOF\n"
+    "chmod +x ./config.status\n";
+
+/* ---- the public API ---------------------------------------------------- */
+
+struct st_error *
+st_gen_config_log_init_emit(FILE *out)
+{
+    if (out == NULL) {
+        return st_error_usage("st_gen_config_log_init_emit: NULL argument");
+    }
+    if (st_sh_emit_str(out, CONFIG_LOG_INIT) < 0) {
+        return st_error_io("I/O error emitting config.log init section");
+    }
+    return NULL;
+}
+
+struct st_error *
+st_gen_config_results_emit(FILE *out, const char *const *features,
+                           size_t count)
+{
+    size_t i;
+
+    if (out == NULL || (features == NULL && count > 0)) {
+        return st_error_usage("st_gen_config_results_emit: NULL argument");
+    }
+    if (st_sh_emit_str(out, RESULTS_PRE) < 0) {
+        return st_error_io("I/O error emitting probe results section");
+    }
+    for (i = 0; i < count; i++) {
+        if (!valid_ident(features[i])) {
+            return st_error_usage("feature name is not a valid shell "
+                                  "identifier");
+        }
+        if (fprintf(out, "    printf 'have_%s=%%s\\n' \"$have_%s\"\n",
+                    features[i], features[i]) < 0) {
+            return st_error_io("I/O error emitting probe results section");
+        }
+    }
+    if (st_sh_emit_str(out, RESULTS_POST) < 0) {
+        return st_error_io("I/O error emitting probe results section");
+    }
+    return NULL;
+}
+
+struct st_error *
+st_gen_config_h_emit(FILE *out, const char *const *features, size_t count)
+{
+    size_t i;
+
+    if (out == NULL || (features == NULL && count > 0)) {
+        return st_error_usage("st_gen_config_h_emit: NULL argument");
+    }
+    if (st_sh_emit_str(out, CONFIG_H_PRE) < 0) {
+        return st_error_io("I/O error emitting config.h section");
+    }
+    for (i = 0; i < count; i++) {
+        char *up;
+
+        if (!valid_ident(features[i])) {
+            return st_error_usage("feature name is not a valid shell "
+                                  "identifier");
+        }
+        up = ident_upper(features[i]);
+        if (up == NULL) {
+            return st_error_internal("out of memory uppercasing feature "
+                                     "name");
+        }
+        if (fprintf(out,
+                    "    if [ \"$have_%s\" = \"yes\" ]; then\n"
+                    "        printf '%%s\\n' '#define HAVE_%s 1'\n"
+                    "    fi\n",
+                    features[i], up) < 0) {
+            free(up);
+            return st_error_io("I/O error emitting config.h section");
+        }
+        free(up);
+    }
+    if (st_sh_emit_str(out, CONFIG_H_POST) < 0) {
+        return st_error_io("I/O error emitting config.h section");
+    }
+    return NULL;
+}
+
+struct st_error *
+st_gen_config_status_emit(FILE *out)
+{
+    if (out == NULL) {
+        return st_error_usage("st_gen_config_status_emit: NULL argument");
+    }
+    if (st_sh_emit_str(out, CONFIG_STATUS) < 0) {
+        return st_error_io("I/O error emitting config.status section");
+    }
+    return NULL;
+}

src/gen/config.h

@@ -0,0 +1,92 @@
+/*
+ * config.h - emitters for the configure-time auxiliary artifacts
+ * (todo 17): config.log, config.h and config.status.
+ *
+ * MODEL: like everything in src/gen/, these functions are PURE CODE
+ * GENERATORS. They emit POSIX-sh sections INTO the generated ./configure;
+ * the artifacts themselves are written AT CONFIGURE TIME by the generated
+ * script, so their contents always reflect the actual probe results and
+ * the actual invocation - never the generator's guesses.
+ *
+ * THE FOUR SECTIONS (see also gen/configure.h for their placement in the
+ * generated script):
+ *
+ *  st_gen_config_log_init_emit      after the preamble: capture the
+ *      original invocation (st_orig_args="$@", st_configure_path=$0,
+ *      plus single-quote-escaped copies built with sed) and truncate-
+ *      write the transcript header (created-by line, original
+ *      arguments, timestamp, host, shell) into $config_log. $config_log
+ *      is defaulted here with `:=`, idempotently with todo 12's cache
+ *      boilerplate. Probe snippets (todo 12) append their compiler
+ *      stdout/stderr to the same file.
+ *  st_gen_config_results_emit       after the probe section: append a
+ *      `## results` block to $config_log with one
+ *      `have_<feature>=yes|no` line per top-level feature.
+ *  st_gen_config_h_emit             after the probe section: write
+ *      ./config.h with the ST_CONFIG_H guard and one
+ *      `#define HAVE_<FEATURE> 1` per feature whose have_<feature>
+ *      resolved to "yes" at configure time (the feature name upper-
+ *      cased; a failed feature gets no define).
+ *  st_gen_config_status_emit        at the very end (after Makefile
+ *      substitution, before exit 0): write ./config.status - a
+ *      standalone POSIX-sh script with the captured arguments baked in
+ *      as quoted literals (so nothing in them is ever re-expanded when
+ *      config.status runs) - and chmod +x it. Its arms: ''/--recheck ->
+ *      `exec "${SHELL:-sh}" "$st_configure_path" $st_orig_args`;
+ *      --config -> print the original args; --help -> brief usage;
+ *      anything else -> error + exit 1.
+ *
+ * SECURITY (the sed-quote bake-in): the captured args/path are rewritten
+ * with `sed "s/'/'\\''/g"` (every `'` becomes `'\''`) and stored in
+ * st_orig_args_q / st_configure_path_q. config.status assigns them as
+ * single-quoted literals (`st_orig_args='...'`), so a value containing
+ * `$(...)`, backticks, spaces or `&` is inert both when configure writes
+ * config.status (here-document expansion never re-parses expansion
+ * results) and when config.status runs (the quotes are real script text
+ * there). Proven by the injection test (todo 17, case f).
+ *
+ * KNOWN v1 LIMITATIONS (documented, deliberately simple):
+ *  - the recheck arm expands $st_orig_args UNQUOTED, so positional args
+ *    containing spaces or glob characters are not preserved through
+ *    --recheck (the v1 surface is --prefix/--host/--build);
+ *  - st_configure_path is captured verbatim ($0), so config.status must
+ *    be run from the same directory configure was run from;
+ *  - args containing literal newlines are pathological (they would break
+ *    the one-line bake-in).
+ *
+ * ERRORS: NULL arguments and feature names that are not valid POSIX shell
+ * identifiers return ST_ERR_USAGE (the names land in have_<name> and
+ * #define HAVE_<NAME> positions, which cannot be shell-quoted); stream
+ * write failures return ST_ERR_IO.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef ST_GEN_CONFIG_H
+#define ST_GEN_CONFIG_H
+
+#include <stddef.h>
+#include <stdio.h>
+
+struct st_error;
+
+/* Emit the config.log init + original-args capture section. */
+struct st_error *st_gen_config_log_init_emit(FILE *out);
+
+/* Emit the post-probe `## results` summary appended to $config_log.
+ * `features` holds the top-level feature names (validated identifiers),
+ * one emitted `have_<name>=%s` line per entry. */
+struct st_error *st_gen_config_results_emit(FILE *out,
+                                            const char *const *features,
+                                            size_t count);
+
+/* Emit the ./config.h writer (ST_CONFIG_H guard + per-feature defines). */
+struct st_error *st_gen_config_h_emit(FILE *out,
+                                      const char *const *features,
+                                      size_t count);
+
+/* Emit the ./config.status writer (+ chmod +x). */
+struct st_error *st_gen_config_status_emit(FILE *out);
+
+#endif /* ST_GEN_CONFIG_H */

src/gen/configure.c

@@ -0,0 +1,811 @@
+/*
+ * configure.c - the ./configure generator (todo 16).
+ *
+ * Assembles the complete POSIX-sh ./configure from a schema-validated DSL
+ * document and an extension ctx. See gen/configure.h for the full emitted
+ * layout contract, the substitution approach (split-on-@, documented), the
+ * LIBS accumulation rules, and the error categories.
+ *
+ * Two load-bearing safety decisions carry through from the detect chain:
+ *   - Every user-supplied byte (feature names, check targets, registered
+ *     var values, package names) reaches the emitted script either through
+ *     st_sh_quote (single-quoted literal, inert) or through a
+ *     validated-identifier position (have_<name>, `VAR="${VAR:-...}"`).
+ *   - The substitution runs AT CONFIGURE TIME in shell, so the generated
+ *     script errors on an unknown @VAR@ it encounters (the generator
+ *     cannot know the user's Makefile.in contents); the value is carried
+ *     verbatim through `printf '%s'` so nothing is ever re-interpreted.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "gen/args.h"
+#include "gen/config.h"
+#include "gen/configure.h"
+
+#include "cli.h" /* STUPIDTOOLS_VERSION (the generated-by version string) */
+
+#include "detect/check_registry.h"
+#include "detect/checks.h"
+#include "detect/probe.h"
+#include "detect/resolve.h"
+#include "error.h"
+#include "ext/abi.h"
+#include "gen/sh_emit.h"
+#include "kdl/ast.h"
+#include "kdl/value.h"
+
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* ---- small helpers ----------------------------------------------------- */
+
+/* True when `s` is a valid POSIX shell identifier: letter/underscore, then
+ * letters/digits/underscores, non-empty. Feature names and registered var
+ * names must pass this (they land in variable-NAME positions). */
+static bool
+valid_ident(const char *s)
+{
+    const unsigned char *p;
+
+    if (s == NULL || *s == '\0') {
+        return false;
+    }
+    p = (const unsigned char *)s;
+    if (!((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') ||
+          *p == '_')) {
+        return false;
+    }
+    for (p++; *p != '\0'; p++) {
+        if (!((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') ||
+              (*p >= '0' && *p <= '9') || *p == '_')) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/* Build an owned ST_ERR_KDL_SCHEMA error whose span lives in the same
+ * allocation as the error struct (the parser.c pattern). Returns NULL only
+ * on allocation failure. */
+static struct st_error *
+err_at_owned(struct st_span sp, const char *msg)
+{
+    const size_t align = _Alignof(struct st_span);
+    const size_t esize =
+        (sizeof(struct st_error) + align - 1) & ~(align - 1);
+    struct st_error *e;
+    struct st_span *spc;
+    size_t mlen;
+
+    if (msg == NULL) {
+        msg = "";
+    }
+    e = malloc(esize + sizeof(struct st_span));
+    if (e == NULL) {
+        return NULL;
+    }
+    mlen = strlen(msg);
+    e->message = malloc(mlen + 1);
+    if (e->message == NULL) {
+        free(e);
+        return NULL;
+    }
+    memcpy(e->message, msg, mlen + 1);
+    e->category = ST_ERR_KDL_SCHEMA;
+    spc = (struct st_span *)((unsigned char *)e + esize);
+    *spc = sp;
+    e->span = spc;
+    return e;
+}
+
+/* Interpret `tok` as the non-empty unannotated string a slot requires; on
+ * success *out owns the string. Mirrors the value-model re-owning in
+ * checks.c (value failures become schema errors). */
+static struct st_error *
+extract_string(const struct st_kdl_token_ref *tok, const char *ctx,
+               char **out)
+{
+    struct st_kdl_value v;
+    struct st_error *e;
+    char msg[192];
+
+    *out = NULL;
+    e = st_kdl_value_from_token(tok, &v);
+    if (e != NULL) {
+        struct st_span sp = e->span != NULL ? *e->span
+                                            : (struct st_span){ NULL, 0, 0 };
+        struct st_error *r = err_at_owned(sp, e->message != NULL
+                                                    ? e->message : "");
+
+        st_error_free(e);
+        return r;
+    }
+    if (v.kind != ST_KDL_VAL_STRING) {
+        snprintf(msg, sizeof msg, "%s must be a non-empty string", ctx);
+        e = err_at_owned(tok->span, msg);
+        st_kdl_value_free(&v);
+        return e;
+    }
+    if (v.as.str[0] == '\0') {
+        snprintf(msg, sizeof msg, "%s must be a non-empty string", ctx);
+        e = err_at_owned(tok->span, msg);
+        st_kdl_value_free(&v);
+        return e;
+    }
+    *out = v.as.str;
+    v.as.str = NULL;
+    st_kdl_value_free(&v);
+    return NULL;
+}
+
+/* vsnprintf-based string builder (no reliance on POSIX strdup). */
+static char *
+strbuild(const char *fmt, ...)
+{
+    va_list ap;
+    va_list ap2;
+    int n;
+    char *out;
+
+    va_start(ap, fmt);
+    va_copy(ap2, ap);
+    n = vsnprintf(NULL, 0, fmt, ap);
+    va_end(ap);
+    if (n < 0) {
+        va_end(ap2);
+        return NULL;
+    }
+    out = malloc((size_t)n + 1);
+    if (out == NULL) {
+        va_end(ap2);
+        return NULL;
+    }
+    (void)vsnprintf(out, (size_t)n + 1, fmt, ap2);
+    va_end(ap2);
+    return out;
+}
+
+/* Compare a node name against a literal, accepting any string form
+ * (identifiers directly; other forms via the value model). */
+static struct st_error *
+name_equals(const struct st_kdl_token_ref *name, const char *s, bool *out)
+{
+    if (name->kind == ST_TOK_IDENT) {
+        *out = name->len == strlen(s) && memcmp(name->text, s, name->len) == 0;
+        return NULL;
+    }
+    {
+        struct st_kdl_value v;
+        struct st_error *e = st_kdl_value_from_token(name, &v);
+
+        if (e != NULL) {
+            struct st_error *r;
+            struct st_span sp = e->span != NULL
+                                    ? *e->span
+                                    : (struct st_span){ NULL, 0, 0 };
+
+            r = err_at_owned(sp, e->message != NULL ? e->message : "");
+            st_error_free(e);
+            *out = false;
+            return r;
+        }
+        *out = v.kind == ST_KDL_VAL_STRING && strcmp(v.as.str, s) == 0;
+        st_kdl_value_free(&v);
+        return NULL;
+    }
+}
+
+/* ---- fixed shell text (emitted verbatim via st_sh_emit_str) ------------ */
+
+/* The `%` in `printf '... %s ...'` is why these are emitted with
+ * st_sh_emit_str (verbatim), not fprintf (which would eat `%s`). */
+
+static const char HOST_DETECT_PRE[] =
+    "\n"
+    "# --- host detection ---\n";
+
+static const char HOST_DETECT_POST[] =
+    "st_os=$(uname -s)\n"
+    "st_os_norm\n"
+    "st_cc_id=unknown\n";
+
+static const char TOOLCHAIN_DEFAULTS_PRE[] =
+    "\n"
+    "# --- toolchain defaults (registered variables) ---\n"
+    "# Each registered variable defaults to its generation-time value, and\n"
+    "# may be overridden by an environment variable of the same name (the\n"
+    "# `${VAR:-...}` form). Emitted BEFORE the cache boilerplate so the\n"
+    "# boilerplate's `:=` fallbacks never clobber these.\n";
+
+static const char TOOLCHAIN_LIBS[] =
+    "# built-in link flags, accumulated by library/pkg_config probes\n"
+    "LIBS=\"\"\n";
+
+static const char SUBST_PRE[] =
+    "\n"
+    "# --- substitution: Makefile.in -> Makefile ---\n"
+    "# The @VAR@ token set is the registered variables plus the built-ins\n"
+    "# LIBS, prefix, srcdir. Substitution runs at CONFIGURE time (the\n"
+    "# generator cannot know the user's Makefile.in), so an unknown @VAR@\n"
+    "# is a configure-time error naming the variable.\n"
+    "\n"
+    "# st_subst_lookup NAME: print the value of substitution variable NAME\n"
+    "# verbatim via printf '%s' (no metacharacter is re-interpreted), or\n"
+    "# return 1 when NAME is unknown.\n"
+    "st_subst_lookup() {\n"
+    "    case \"$1\" in\n";
+
+static const char SUBST_LOOKUP_TAIL[] =
+    "        *) return 1 ;;\n"
+    "    esac\n"
+    "}\n"
+    "\n"
+    "# st_subst_line LINE: echo LINE with every @VAR@ replaced by $VAR.\n"
+    "# Why not sed: its 's' replacement re-interprets '&', '\\' and the\n"
+    "# delimiter, so a value with those bytes is corrupted unless escaped -\n"
+    "# fragile. Why not ${var//...}: a bash/zsh/ksh extension, not POSIX.\n"
+    "# Instead the line is split on '@' with pure POSIX parameter expansion\n"
+    "# (${v%%'@'*}, ${v#*'@'}): a '@' only starts a substitution when a\n"
+    "# second '@' follows on the same line, so a lone '@' is literal; the\n"
+    "# name between the two must be known, else configure errors naming it.\n"
+    "# Values are carried verbatim through printf '%s', so '/', spaces,\n"
+    "# '&', '$' and backticks all survive byte-exact and never execute.\n"
+    "# (v1 limitation: a value may not END in a newline - command\n"
+    "# substitution strips trailing newlines.)\n"
+    "st_subst_line() {\n"
+    "    st_rest=$1\n"
+    "    st_out=\n"
+    "    while :; do\n"
+    "        case \"$st_rest\" in\n"
+    "            *'@'*'@'*) : ;;\n"
+    "            *)\n"
+    "                st_out=\"$st_out$st_rest\"\n"
+    "                break\n"
+    "                ;;\n"
+    "        esac\n"
+    "        st_out=\"$st_out${st_rest%%'@'*}\"\n"
+    "        st_after=${st_rest#*'@'}\n"
+    "        st_name=${st_after%%'@'*}\n"
+    "        st_rest=${st_after#*'@'}\n"
+    "        if st_val=$(st_subst_lookup \"$st_name\"); then\n"
+    "            st_out=\"$st_out$st_val\"\n"
+    "        else\n"
+    "            printf 'configure: error: unknown variable @%s@ in Makefile.in\\n' \"$st_name\" >&2\n"
+    "            exit 1\n"
+    "        fi\n"
+    "    done\n"
+    "    printf '%s\\n' \"$st_out\"\n"
+    "}\n"
+    "\n"
+    "# st_subst: read ./Makefile.in (the source directory; v1 cwd contract),\n"
+    "# substitute every @VAR@, write ./Makefile.\n"
+    "st_subst() {\n"
+    "    if [ ! -f ./Makefile.in ]; then\n"
+    "        printf '%s\\n' 'configure: error: Makefile.in not found' >&2\n"
+    "        exit 1\n"
+    "    fi\n"
+    "    : > ./Makefile\n"
+    "    while IFS= read -r st_line || [ -n \"$st_line\" ]; do\n"
+    "        st_subst_line \"$st_line\" >> ./Makefile\n"
+    "    done < ./Makefile.in\n"
+    "}\n"
+    "\n"
+    "st_subst\n";
+
+/* ---- section emitters -------------------------------------------------- */
+
+/* One library/pkg_config check's link-flags contribution. */
+struct st_lib_entry {
+    enum st_check_kind kind; /* ST_CHECK_LIBRARY or ST_CHECK_PKG_CONFIG */
+    char *target;            /* owned library/package name */
+};
+
+/* Emit the substitution lookup function's case arms. `names` are already
+ * validated identifiers, safe in variable-NAME positions. */
+static struct st_error *
+emit_subst_lookup(FILE *out, const char *const *names, size_t count)
+{
+    size_t i;
+
+    if (st_sh_emit_str(out, SUBST_PRE) < 0) {
+        return st_error_io("I/O error emitting substitution section");
+    }
+    for (i = 0; i < count; i++) {
+        if (fprintf(out, "        %s) printf '%%s' \"$%s\" ;;\n",
+                    names[i], names[i]) < 0) {
+            return st_error_io("I/O error emitting substitution section");
+        }
+    }
+    if (st_sh_emit_str(out, SUBST_LOOKUP_TAIL) < 0) {
+        return st_error_io("I/O error emitting substitution section");
+    }
+    return NULL;
+}
+
+/* Emit the LIBS accumulation for one feature: for each library/pkg_config
+ * check, append the link flags when the feature resolved yes. Generic over
+ * the check kind; the pkg_config form is guarded by `command -v pkg-config`
+ * (v1). */
+static struct st_error *
+emit_libs_accumulation(FILE *out, const char *feature,
+                       const struct st_lib_entry *libs, size_t count)
+{
+    size_t i;
+
+    for (i = 0; i < count; i++) {
+        char *q;
+
+        if (libs[i].kind == ST_CHECK_LIBRARY) {
+            q = st_sh_quote(libs[i].target);
+            if (q == NULL) {
+                return st_error_internal("out of memory quoting library name");
+            }
+            /* `-l` inside the double quotes, the st_sh_quote'd name OUTSIDE
+             * them (single quotes are literal inside double quotes, which
+             * would turn -l'pthread' into a literal-quoted flag). */
+            if (fprintf(out,
+                        "if [ \"$have_%s\" = \"yes\" ]; then "
+                        "LIBS=\"$LIBS -l\"%s; fi\n",
+                        feature, q) < 0) {
+                free(q);
+                return st_error_io("I/O error emitting LIBS accumulation");
+            }
+            free(q);
+        } else { /* ST_CHECK_PKG_CONFIG */
+            q = st_sh_quote(libs[i].target);
+            if (q == NULL) {
+                return st_error_internal("out of memory quoting package name");
+            }
+            /* v1 pkg-config guard: only accumulate when pkg-config exists. */
+            if (fprintf(out,
+                        "if command -v pkg-config >/dev/null 2>&1; then\n"
+                        "    if [ \"$have_%s\" = \"yes\" ]; then "
+                        "LIBS=\"$LIBS $(pkg-config --libs %s)\"; fi\n"
+                        "fi\n",
+                        feature, q) < 0) {
+                free(q);
+                return st_error_io("I/O error emitting LIBS accumulation");
+            }
+            free(q);
+        }
+    }
+    if (ferror(out)) {
+        return st_error_io("I/O error emitting LIBS accumulation");
+    }
+    return NULL;
+}
+
+/* Emit ONE feature node: its probe snippets, its resolution (aggregation +
+ * when-gate), then its LIBS accumulation. */
+static struct st_error *
+emit_feature(FILE *out, const struct st_kdl_node *node)
+{
+    struct st_error *err = NULL;
+    struct st_when_ast *guard = NULL;
+    char *fname = NULL;
+    const struct st_kdl_node *child;
+    const struct st_kdl_prop *prop;
+    size_t n_checks = 0;
+    size_t i = 0;
+    char **check_names = NULL;
+    struct st_check_probe *probes = NULL;
+    struct st_lib_entry *libs = NULL;
+    size_t n_libs = 0;
+
+    /* the feature name (must be a valid shell identifier) */
+    if (node->args == NULL) {
+        return err_at_owned(node->name.span, "feature requires a name");
+    }
+    err = extract_string(&node->args->value, "feature name", &fname);
+    if (err != NULL) {
+        return err;
+    }
+    if (!valid_ident(fname)) {
+        char msg[192];
+
+        snprintf(msg, sizeof msg,
+                 "feature name '%s' is not a valid shell identifier "
+                 "(have_<name> requires [A-Za-z_][A-Za-z0-9_]*)", fname);
+        err = err_at_owned(node->args->value.span, msg);
+        goto done;
+    }
+
+    /* count checks */
+    for (child = node->children; child != NULL; child = child->next) {
+        n_checks++;
+    }
+
+    if (n_checks > 0) {
+        check_names = calloc(n_checks, sizeof(*check_names));
+        probes = calloc(n_checks, sizeof(*probes));
+        libs = calloc(n_checks, sizeof(*libs));
+        if (check_names == NULL || probes == NULL || libs == NULL) {
+            err = st_error_internal("out of memory building feature");
+            goto done;
+        }
+    }
+
+    /* build every check's probe + checkname, collecting lib/pkg_config */
+    for (child = node->children; child != NULL; child = child->next) {
+        enum st_check_kind kind;
+        char namebuf[128];
+
+        kind = st_check_kind_from_node(child, &err);
+        if (err != NULL) {
+            goto done;
+        }
+        if (st_resolve_check_name(fname, i, n_checks, namebuf,
+                                  sizeof namebuf) != 0) {
+            err = st_error_internal("failed to derive check name");
+            goto done;
+        }
+        check_names[i] = strbuild("%s", namebuf);
+        if (check_names[i] == NULL) {
+            err = st_error_internal("out of memory deriving check name");
+            goto done;
+        }
+        err = st_check_probe_build(kind, child, &probes[i]);
+        if (err != NULL) {
+            goto done;
+        }
+        if (kind == ST_CHECK_LIBRARY || kind == ST_CHECK_PKG_CONFIG) {
+            libs[n_libs].kind = kind;
+            err = extract_string(&child->args->value,
+                                 kind == ST_CHECK_LIBRARY
+                                     ? "library check argument"
+                                     : "pkg_config check argument",
+                                 &libs[n_libs].target);
+            if (err != NULL) {
+                goto done;
+            }
+            n_libs++;
+        }
+        i++;
+    }
+
+    /* emit the probe snippets (todo 12), in document order */
+    for (i = 0; i < n_checks; i++) {
+        err = st_probe_emit_snippet(check_names[i], &probes[i], out);
+        if (err != NULL) {
+            goto done;
+        }
+    }
+
+    /* the `when` guard (optional feature property) */
+    for (prop = node->props; prop != NULL; prop = prop->next) {
+        bool is_when = false;
+
+        err = name_equals(&prop->key, "when", &is_when);
+        if (err != NULL) {
+            goto done;
+        }
+        if (is_when) {
+            char *guard_str = NULL;
+
+            err = extract_string(&prop->value, "feature 'when'", &guard_str);
+            if (err != NULL) {
+                goto done;
+            }
+            err = st_when_parse_at(guard_str, &node->name.span, &guard);
+            free(guard_str);
+            if (err != NULL) {
+                goto done;
+            }
+            break;
+        }
+    }
+
+    /* feature resolution: aggregation + when-gate (todo 14) */
+    {
+        struct st_resolve_feature f;
+
+        f.name = fname;
+        f.check_names = (const char *const *)check_names;
+        f.check_count = n_checks;
+        f.guard = guard;
+        err = st_resolve_emit_feature(out, &f);
+        if (err != NULL) {
+            goto done;
+        }
+    }
+
+    /* LIBS accumulation (library/pkg_config checks), gated on have_<name> */
+    err = emit_libs_accumulation(out, fname, libs, n_libs);
+    if (err != NULL) {
+        goto done;
+    }
+
+done:
+    for (i = 0; i < n_checks; i++) {
+        st_check_probe_free(&probes[i]);
+        free(check_names != NULL ? check_names[i] : NULL);
+    }
+    for (i = 0; i < n_libs; i++) {
+        free(libs[i].target);
+    }
+    free(check_names);
+    free(probes);
+    free(libs);
+    st_when_free(guard);
+    free(fname);
+    return err;
+}
+
+/* Append `name` (owned) to the feature-name list, growing it as needed.
+ * Used by the probe-section loop to collect the names the todo-17 results
+ * summary + config.h defines are emitted from. */
+static struct st_error *
+collect_feature_name(char ***names, size_t *count, size_t *cap, char *name)
+{
+    if (*count == *cap) {
+        size_t ncap = *cap == 0 ? 8 : *cap * 2;
+        char **nn = realloc(*names, ncap * sizeof(*nn));
+
+        if (nn == NULL) {
+            return st_error_internal("out of memory collecting feature "
+                                     "names");
+        }
+        *names = nn;
+        *cap = ncap;
+    }
+    (*names)[(*count)++] = name;
+    return NULL;
+}
+
+/* ---- the public API ---------------------------------------------------- */
+
+struct st_error *
+st_gen_configure_emit(FILE *out, const struct st_kdl_document *doc,
+                      struct st_ext_ctx *ctx)
+{
+    struct st_registry *reg;
+    size_t n_reg;
+    size_t i;
+    struct st_error *err = NULL;
+    const struct st_kdl_node *node;
+    struct st_gen_args args;
+    char **subst_names = NULL;
+    size_t n_subst = 0;
+    char **feat_names = NULL;
+    size_t n_feat = 0;
+    size_t feat_cap = 0;
+
+    if (out == NULL || doc == NULL || ctx == NULL) {
+        return st_error_usage("st_gen_configure_emit: NULL argument");
+    }
+    memset(&args, 0, sizeof args);
+    err = st_gen_args_collect(doc, &args);
+    if (err != NULL) {
+        goto done;
+    }
+    reg = st_ext_var_registry(ctx);
+    if (reg == NULL) {
+        err = st_error_usage("st_gen_configure_emit: ctx has no variable "
+                             "registry");
+        goto done;
+    }
+    n_reg = st_registry_var_count(reg);
+
+    /* collect the full @VAR@ substitution set: registered vars + the
+     * built-ins LIBS/prefix/exec_prefix/srcdir/host/build/cross_compiling
+     * + one enable_<name> per DSL option (todo 18) */
+    n_subst = n_reg + 7 + args.option_count;
+    subst_names = calloc(n_subst, sizeof(*subst_names));
+    if (subst_names == NULL) {
+        err = st_error_internal("out of memory building substitution set");
+        goto done;
+    }
+    for (i = 0; i < n_reg; i++) {
+        const char *name = st_registry_var_name(reg, i);
+
+        if (!valid_ident(name)) {
+            char msg[192];
+
+            snprintf(msg, sizeof msg,
+                     "registered variable name '%s' is not a valid shell "
+                     "identifier", name != NULL ? name : "?");
+            err = st_error_usage(msg);
+            goto done;
+        }
+        subst_names[i] = (char *)name;
+    }
+    subst_names[n_reg + 0] = "LIBS";
+    subst_names[n_reg + 1] = "prefix";
+    subst_names[n_reg + 2] = "exec_prefix";
+    subst_names[n_reg + 3] = "srcdir";
+    subst_names[n_reg + 4] = "host";
+    subst_names[n_reg + 5] = "build";
+    subst_names[n_reg + 6] = "cross_compiling";
+    for (i = 0; i < args.option_count; i++) {
+        subst_names[n_reg + 7 + i] = strbuild("enable_%s",
+                                              args.options[i].name);
+        if (subst_names[n_reg + 7 + i] == NULL) {
+            err = st_error_internal("out of memory building substitution "
+                                    "set");
+            goto done;
+        }
+    }
+
+    /* 1. shebang + header comment */
+    if (st_sh_emit_str(out, "#!/bin/sh\n") < 0 ||
+        st_sh_emit_comment(out,
+                           "Generated by stupidtools " STUPIDTOOLS_VERSION
+                           " - DO NOT EDIT") < 0) {
+        err = st_error_io("I/O error emitting configure header");
+        goto done;
+    }
+
+    /* 2. preamble: full argument parsing (todo 18) */
+    err = st_gen_args_emit(out, &args);
+    if (err != NULL) {
+        goto done;
+    }
+
+    /* 3. config.log init + original-args capture (todo 17) */
+    err = st_gen_config_log_init_emit(out);
+    if (err != NULL) {
+        goto done;
+    }
+
+    /* 4. host detection */
+    if (st_sh_emit_str(out, HOST_DETECT_PRE) < 0) {
+        err = st_error_io("I/O error emitting host detection");
+        goto done;
+    }
+    err = st_resolve_emit_os_norm(out);
+    if (err != NULL) {
+        goto done;
+    }
+    if (st_sh_emit_str(out, HOST_DETECT_POST) < 0) {
+        err = st_error_io("I/O error emitting host detection");
+        goto done;
+    }
+
+    /* 5. toolchain defaults (before the cache boilerplate; see the header) */
+    if (st_sh_emit_str(out, TOOLCHAIN_DEFAULTS_PRE) < 0) {
+        err = st_error_io("I/O error emitting toolchain defaults");
+        goto done;
+    }
+    for (i = 0; i < n_reg; i++) {
+        const char *name = st_registry_var_name(reg, i);
+        const char *value = st_registry_var_value(reg, i);
+        char *q = st_sh_quote(value != NULL ? value : "");
+
+        if (q == NULL) {
+            err = st_error_internal("out of memory quoting registered "
+                                    "variable");
+            goto done;
+        }
+        /* No outer double quotes: inside "${VAR:-...}" the single quotes
+         * of a st_sh_quote'd default are LITERAL, so an empty default would
+         * become the two-character string "''". The unquoted ${VAR:-'...'}
+         * form is safe because assignment RHS is not field-split or globbed
+         * and quote-removal strips the single quotes, yielding the exact
+         * registry value (spaces/&/$ preserved). */
+        if (fprintf(out, "%s=${%s:-%s}\n", name, name, q) < 0) {
+            free(q);
+            err = st_error_io("I/O error emitting toolchain defaults");
+            goto done;
+        }
+        free(q);
+    }
+    if (st_sh_emit_str(out, TOOLCHAIN_LIBS) < 0) {
+        err = st_error_io("I/O error emitting toolchain defaults");
+        goto done;
+    }
+
+    /* 6. cache boilerplate (todo 12) */
+    err = st_probe_emit_cache_functions(out);
+    if (err != NULL) {
+        goto done;
+    }
+
+    /* 7. probe section: each top-level `feature` node in document order.
+     * The resolved feature names are collected here for the todo-17
+     * results summary + config.h defines, emitted right after the loop. */
+    for (node = doc->nodes; node != NULL; node = node->next) {
+        bool is_feature = false;
+        char *fname = NULL;
+
+        err = name_equals(&node->name, "feature", &is_feature);
+        if (err != NULL) {
+            goto done;
+        }
+        if (!is_feature) {
+            continue;
+        }
+        err = emit_feature(out, node);
+        if (err != NULL) {
+            goto done;
+        }
+        /* a successful emit_feature guarantees the name is a valid shell
+         * identifier (it errors otherwise), so the have_<name> /
+         * HAVE_<NAME> interpolation below is safe */
+        err = extract_string(&node->args->value, "feature name", &fname);
+        if (err != NULL) {
+            goto done;
+        }
+        err = collect_feature_name(&feat_names, &n_feat, &feat_cap, fname);
+        if (err != NULL) {
+            free(fname);
+            goto done;
+        }
+    }
+
+    /* 8. probe-results summary + config.h (todo 17) */
+    err = st_gen_config_results_emit(out, (const char *const *)feat_names,
+                                     n_feat);
+    if (err != NULL) {
+        goto done;
+    }
+    err = st_gen_config_h_emit(out, (const char *const *)feat_names, n_feat);
+    if (err != NULL) {
+        goto done;
+    }
+
+    /* 9. substitution section */
+    err = emit_subst_lookup(out, (const char *const *)subst_names, n_subst);
+    if (err != NULL) {
+        goto done;
+    }
+
+    /* 10. config.status (todo 17): written after substitution, before the
+     * final exit 0 */
+    err = st_gen_config_status_emit(out);
+    if (err != NULL) {
+        goto done;
+    }
+    if (st_sh_emit_str(out, "\nexit 0\n") < 0) {
+        err = st_error_io("I/O error emitting configure");
+        goto done;
+    }
+
+    /* 11. final stream check */
+    if (ferror(out)) {
+        err = st_error_io("I/O error emitting configure");
+        goto done;
+    }
+
+done:
+    for (i = 0; i < n_feat; i++) {
+        free(feat_names[i]);
+    }
+    free(feat_names);
+    /* the enable_<name> entries are owned (strbuild); the rest of
+     * subst_names holds borrowed literals/registry pointers */
+    if (subst_names != NULL && n_reg + 7 <= n_subst) {
+        for (i = n_reg + 7; i < n_subst; i++) {
+            free(subst_names[i]);
+        }
+    }
+    free(subst_names);
+    st_gen_args_free(&args);
+    return err;
+}
+
+struct st_error *
+st_gen_configure_emit_path(const char *path, const struct st_kdl_document *doc,
+                           struct st_ext_ctx *ctx)
+{
+    FILE *f;
+    struct st_error *err;
+
+    if (path == NULL) {
+        return st_error_usage("st_gen_configure_emit_path: NULL path");
+    }
+    f = fopen(path, "w");
+    if (f == NULL) {
+        return st_error_io("cannot open output file for writing");
+    }
+    err = st_gen_configure_emit(f, doc, ctx);
+    if (fclose(f) != 0 && err == NULL) {
+        err = st_error_io("I/O error closing output file");
+    }
+    return err;
+}

src/gen/configure.h

@@ -0,0 +1,157 @@
+/*
+ * configure.h - the ./configure generator (todo 16).
+ *
+ * THE INTEGRATION TODO: assembles everything the detect chain (todos
+ * 9/10/11/12/14) and the sh-emitter (15) built into a WORKING generated
+ * ./configure. Given a schema-validated DSL document (src/kdl/schema.h)
+ * plus an extension context (src/ext/abi.h) whose variable registry the
+ * C/C++ language modules have already populated, it EMITS a complete
+ * POSIX-sh ./configure to a FILE.
+ *
+ * GENERATED SCRIPT LAYOUT (the contract todos 17/18/23 consume)
+ * -------------------------------------------------------------
+ *  1. `#!/bin/sh` + a header comment (generated-by, version).
+ *  2. PREAMBLE — FULL argument handling (todo 18, emitted by
+ *     src/gen/args.h's st_gen_args_emit from the collected DSL project +
+ *     option nodes): the `# --- PREAMBLE ---` section sets
+ *     prefix=/usr/local, exec_prefix=, srcdir=., build=, host=,
+ *     cross_compiling=no and enable_<name>=<default> per DSL option,
+ *     defines st_usage(), then parses "$@" (READ-ONLY — the loop never
+ *     shifts, so st_orig_args stays complete for section 3):
+ *       - `-h`/`--help`: usage on stdout, exit 0;
+ *       - `--version`: project name + version, exit 0;
+ *       - `--prefix` / `--exec-prefix` / `--host` / `--build` in both
+ *         `--opt=value` and `--opt value` forms (a missing, empty or
+ *         option-looking value errors with usage on stderr, exit 1);
+ *       - per-option `--enable-<name>` / `--disable-<name>` setting
+ *         enable_<name>=yes|no (default from the option's `default`
+ *         property; a DSL `option "debug" default=#false` maps to
+ *         --enable-debug/--disable-debug with default no);
+ *       - generic positional VAR=VALUE (e.g. `./configure CC=clang`):
+ *         VAR is identifier-validated, the value is single-quote-escaped
+ *         and eval-assigned (nothing re-parsed); the exported form
+ *         (`CC=clang ./configure`) is the invoking shell's environment
+ *         contract and needs no parser support;
+ *       - an unknown `--*` prints "unrecognized option" + usage to
+ *         stderr and exits 1.
+ *     Trailing: exec_prefix defaults to $prefix; cross_compiling=yes
+ *     when --host differs from --build (both set).
+ *  3. CONFIG.LOG INIT (todo 17) — capture the original invocation
+ *     (st_orig_args="$@", st_configure_path=$0, plus single-quote-escaped
+ *     copies built with sed for the config.status bake-in) and
+ *     truncate-write the transcript header (created-by line, original
+ *     arguments, timestamp, host, shell) into $config_log (defaulted here
+ *     with `:=`, idempotently with todo 12's boilerplate default). Probe
+ *     snippets append their compiler stdout/stderr to the same file.
+ *  4. HOST DETECTION: `st_os=$(uname -s)`, then the st_os_norm() emitted by
+ *     resolve.h's st_resolve_emit_os_norm() rewrites it in place; `st_cc_id
+ *     =unknown` (v1, no compiler-id sniffing at configure time).
+ *  5. TOOLCHAIN DEFAULTS: for each registered var name (CC/CFLAGS/...) emit
+ *     `VAR="${VAR:-<default>}"` where <default> is the registry VALUE at
+ *     generation time (st_sh_quote'd; typically empty for CFLAGS), then
+ *     `LIBS=""`. Emitted BEFORE the probe cache boilerplate because that
+ *     boilerplate uses `:=` fallbacks that must not clobber these values.
+ *  6. CACHE BOILERPLATE: probe.h's st_probe_emit_cache_functions (todo 12).
+ *  7. PROBE SECTION: for each top-level `feature` node in document order,
+ *     for each check child, derive the checkname via resolve.h's
+ *     st_resolve_check_name, build the probe via checks.h's
+ *     st_check_probe_build, and emit the snippet via probe.h's
+ *     st_probe_emit_snippet; then the feature aggregation + when-gate via
+ *     st_resolve_emit_feature (todo 14); then the LIBS accumulation: for a
+ *     `library "X"` check, `if [ "$have_<name>" = "yes" ]; then
+ *     LIBS="$LIBS -l'X'"; fi`; for `pkg_config "X"`, the same wrapped in a
+ *     v1 pkg-config guard `if command -v pkg-config >/dev/null 2>&1; then
+ *     ... LIBS="$LIBS $(pkg-config --libs 'X')" ...; fi`. Generic over the
+ *     check kinds, never hardcoded per feature name.
+ *  8. PROBE RESULTS + CONFIG.H (todo 17) — append a `## results` block to
+ *     $config_log (one `have_<feature>=yes|no` line per top-level feature),
+ *     then write ./config.h with the ST_CONFIG_H guard and one
+ *     `#define HAVE_<FEATURE> 1` per feature whose have_<feature> resolved
+ *     to "yes". Both reflect the configure-time probe results, never
+ *     generation-time guesses; feature names are validated identifiers
+ *     (see ERRORS), so the have_<name> / HAVE_<NAME> interpolation is
+ *     safe.
+ *  9. SUBSTITUTION: reads ./Makefile.in (cwd, the v1 source-dir contract)
+ *     and replaces every `@VAR@` (VAR = registered vars ∪ {LIBS, prefix,
+ *     exec_prefix, srcdir, host, build, cross_compiling} ∪ {enable_<name>
+ *     per DSL option}) with the shell variable's value, writing
+ *     ./Makefile. An UNRESOLVED `@SOMETHING@` is a CONFIGURE-TIME error naming the
+ *     variable (the generator cannot know the user's Makefile.in), reported
+ *     after substitution via the per-line lookup; a missing Makefile.in is
+ *     a clean error. See the SUBSTITUTION approach note below.
+ * 10. CONFIG.STATUS (todo 17) — write ./config.status (a standalone
+ *     POSIX-sh script with the original arguments baked in as quoted
+ *     literals, so nothing in them is ever re-expanded when it runs) and
+ *     chmod +x it. Arms: ''/--recheck -> `exec "${SHELL:-sh}"
+ *     "$st_configure_path" $st_orig_args`; --config -> print the original
+ *     args; --help -> brief usage; unknown -> error + exit 1. v1
+ *     limitations (documented in gen/config.h): positional args with
+ *     spaces/globs are not preserved by the unquoted recheck expansion;
+ *     config.status must run from the same directory as configure.
+ * 11. `exit 0`.
+ *
+ * SUBSTITUTION APPROACH (documented because the plan flagged it)
+ * --------------------------------------------------------------
+ * `${var//...}` is NOT POSIX, and sed's `s` replacement re-interprets `&`,
+ * `\` and the delimiter (values with `/`, spaces, `&` would be corrupted or
+ * need fragile escaping). The generated script therefore splits each line
+ * on `@` with pure POSIX parameter expansion (${v%%'@'*}, ${v#*'@'}) and
+ * looks each token up in a generated `case` (one arm per known variable,
+ * `printf '%s' "$VAR"` — the value is carried verbatim and never
+ * re-interpreted, so `$`, backticks, `/`, spaces, `&` all survive
+ * byte-exact and never execute). A `@` starts a substitution only when a
+ * second `@` follows on the same line, so a lone `@` stays literal. Known
+ * v1 limitation: a value may not END in a newline (command substitution
+ * strips trailing newlines); documented in the emitted script.
+ *
+ * POSIX-SH ONLY (AGENTS.md §4): the emitted script uses no `[[ ]]`, no
+ * arrays, no `local`, no `==`, no `<<<`, no `&>`, no `set -e`; `$(...)`
+ * is used. `sh -n` / `bash -n` / `zsh -n` must all pass (dash is not
+ * installed on this host — see .omo/notepads/stupidtools/issues.md).
+ *
+ * ERRORS
+ * ------
+ * All functions return NULL on success or an owned st_error. Failures are
+ * ST_ERR_USAGE for NULL arguments; ST_ERR_KDL_SCHEMA (span heap-allocated
+ * in the same block as the error, the parser.c pattern) for a feature or
+ * option name that is not a valid POSIX shell identifier (option errors
+ * come from st_gen_args_collect, src/gen/args.h); ST_ERR_INTERNAL for
+ * quoting allocation failures; ST_ERR_IO for stream write failures or
+ * (emit_path) an unopenable path. The document is only read, never
+ * modified or freed; the ctx is only read (its registry values are
+ * borrowed).
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef ST_GEN_CONFIGURE_H
+#define ST_GEN_CONFIGURE_H
+
+#include <stdio.h>
+
+struct st_error;
+struct st_ext_ctx;
+struct st_kdl_document;
+
+/*
+ * Emit the complete POSIX-sh ./configure for `doc` (schema-validated) into
+ * `out`. Reads the registered variables from `ctx`'s variable registry and
+ * substitutes them by name; never hardcodes CC/CFLAGS/... in core. Returns
+ * NULL on success, or an owned st_error (see the header's ERRORS section).
+ */
+struct st_error *st_gen_configure_emit(FILE *out,
+                                       const struct st_kdl_document *doc,
+                                       struct st_ext_ctx *ctx);
+
+/*
+ * Convenience wrapper: open `path` for writing ("w", text) and emit into
+ * it. On success the file is fully written and closed; on failure it is
+ * closed (best-effort) and an owned st_error is returned (ST_ERR_IO when
+ * the file cannot be created, otherwise the emit error).
+ */
+struct st_error *st_gen_configure_emit_path(const char *path,
+                                            const struct st_kdl_document *doc,
+                                            struct st_ext_ctx *ctx);
+
+#endif /* ST_GEN_CONFIGURE_H */

src/gen/sh_emit.c

@@ -0,0 +1,162 @@
+#include "sh_emit.h"
+
+#include "error.h"
+
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+/*
+ * src/gen/sh_emit.c — POSIX-sh text emitter (todo 15).
+ *
+ * The quoting rules implemented here are the single-quote rules of the
+ * POSIX Shell Command Language (XBD 2.2.2 "Single-Quotes"): everything
+ * between two unescaped `'` characters is literal, and the ONLY way to
+ * embed a `'` is to close the quoted region, escape the quote with a
+ * backslash, and reopen it — the four-character sequence `'\''`.
+ */
+
+static struct st_error *
+quote_error(const char *message)
+{
+    return st_error_internal(message);
+}
+
+char *
+st_sh_quote_n(const char *value, size_t len, struct st_error **err)
+{
+    size_t i;
+    size_t out_len;
+    char *out;
+
+    if (err != NULL) {
+        *err = NULL;
+    }
+    if (value == NULL) {
+        if (err != NULL) {
+            *err = quote_error("st_sh_quote: value is NULL");
+        }
+        return NULL;
+    }
+    for (i = 0; i < len; i++) {
+        if (value[i] == '\0') {
+            if (err != NULL) {
+                *err = quote_error("st_sh_quote: value contains a NUL byte");
+            }
+            return NULL;
+        }
+    }
+    /* Worst case: every byte is a `'` and expands to 4. Guard the
+     * size computation against hostile (huge) lengths. */
+    if (len > (SIZE_MAX - 3) / 4) {
+        if (err != NULL) {
+            *err = quote_error("st_sh_quote: value too large to quote");
+        }
+        return NULL;
+    }
+    out_len = 1; /* opening quote */
+    for (i = 0; i < len; i++) {
+        out_len += (value[i] == '\'') ? 4 : 1;
+    }
+    out_len += 1; /* closing quote */
+    out = malloc(out_len + 1);
+    if (out == NULL) {
+        if (err != NULL) {
+            *err = quote_error("st_sh_quote: out of memory");
+        }
+        return NULL;
+    }
+    out_len = 0;
+    out[out_len++] = '\'';
+    for (i = 0; i < len; i++) {
+        if (value[i] == '\'') {
+            memcpy(out + out_len, "'\\''", 4);
+            out_len += 4;
+        } else {
+            out[out_len++] = value[i];
+        }
+    }
+    out[out_len++] = '\'';
+    out[out_len] = '\0';
+    return out;
+}
+
+char *
+st_sh_quote_ex(const char *value, struct st_error **err)
+{
+    if (value == NULL) {
+        if (err != NULL) {
+            *err = quote_error("st_sh_quote: value is NULL");
+        }
+        return NULL;
+    }
+    return st_sh_quote_n(value, strlen(value), err);
+}
+
+char *
+st_sh_quote(const char *value)
+{
+    return st_sh_quote_ex(value, NULL);
+}
+
+int
+st_sh_emit_str(FILE *out, const char *s)
+{
+    if (out == NULL || s == NULL) {
+        return -1;
+    }
+    return fputs(s, out) == EOF ? -1 : 0;
+}
+
+int
+st_sh_emit_comment(FILE *out, const char *text)
+{
+    const unsigned char *p;
+
+    if (out == NULL || text == NULL) {
+        return -1;
+    }
+    if (fputs("# ", out) == EOF) {
+        return -1;
+    }
+    for (p = (const unsigned char *)text; *p != '\0'; p++) {
+        if (putc(*p, out) == EOF) {
+            return -1;
+        }
+        if (*p == '\n' && fputs("# ", out) == EOF) {
+            return -1;
+        }
+    }
+    return putc('\n', out) == EOF ? -1 : 0;
+}
+
+int
+st_sh_emit_assign(FILE *out, const char *var, const char *quoted_value)
+{
+    if (out == NULL || var == NULL || quoted_value == NULL) {
+        return -1;
+    }
+    if (fputs(var, out) == EOF || putc('=', out) == EOF ||
+        fputs(quoted_value, out) == EOF || putc('\n', out) == EOF) {
+        return -1;
+    }
+    return 0;
+}
+
+int
+st_sh_emit_assign_q(FILE *out, const char *var, const char *value)
+{
+    char *quoted;
+    int rc;
+
+    if (out == NULL || var == NULL) {
+        return -1;
+    }
+    quoted = st_sh_quote(value);
+    if (quoted == NULL) {
+        return -1;
+    }
+    rc = st_sh_emit_assign(out, var, quoted);
+    free(quoted);
+    return rc;
+}

src/gen/sh_emit.h

@@ -0,0 +1,85 @@
+#ifndef ST_GEN_SH_EMIT_H
+#define ST_GEN_SH_EMIT_H
+
+/*
+ * POSIX-sh text emitter (todo 15).
+ *
+ * Everything this module writes is POSIX Shell Command Language only:
+ * the generated configure scripts must run unmodified under dash, bash
+ * and zsh. Policy (AGENTS.md §4): no `[[ ]]`, no arrays, no `local`,
+ * no `==` (use `=` inside `[ ]`), no `<<<`, no `&>`; `set -e` is POSIX
+ * but is AVOIDED by policy in generated scripts because its failure
+ * semantics vary across shells.
+ *
+ * Trust boundaries (callers MUST honor these):
+ *   - st_sh_quote() is the ONLY function here that makes arbitrary bytes
+ *     shell-safe. Everything written via st_sh_emit_str() and
+ *     st_sh_emit_assign() (3rd arg) is emitted verbatim — the caller
+ *     guarantees it is already safe shell text.
+ *   - `var` arguments to the assign helpers must be valid POSIX shell
+ *     identifiers (name followed by [A-Za-z0-9_]); they are not
+ *     validated or quoted.
+ */
+
+#include <stddef.h>
+#include <stdio.h>
+
+struct st_error;
+
+/*
+ * st_sh_quote(value) — the load-bearing primitive.
+ *
+ * Returns a malloc'd single-quoted shell literal that reproduces
+ * `value` byte-for-byte when assigned inside a shell script
+ * (e.g. `v=<result>`), or NULL on error.
+ *
+ * Form: the value is wrapped in `'…'` and every embedded `'` becomes
+ * the four-character sequence `'\''` (close quote, escaped quote, open
+ * quote). Nothing else is touched: inside single quotes NO character
+ * is special to the shell, so `$`, backticks, `"`, `\`, newlines and
+ * metacharacters pass through untouched — no injection is possible.
+ * The empty string quotes as `''`.
+ *
+ * Errors (NULL result): `value` is NULL, `value` contains a NUL byte
+ * (detectable only through the length-bounded variant), the required
+ * size overflows size_t, or allocation fails.
+ */
+char *st_sh_quote(const char *value);
+
+/* As st_sh_quote(), but on error and if `err` is non-NULL, *err
+ * receives a newly allocated st_error (category ST_ERR_INTERNAL) that
+ * the caller frees with st_error_free(). On success *err is left
+ * untouched; if the error itself cannot be allocated, *err is NULL. */
+char *st_sh_quote_ex(const char *value, struct st_error **err);
+
+/* Length-bounded core: quotes exactly `len` bytes starting at `value`.
+ * This is the only variant that can DETECT an embedded NUL byte (which
+ * is rejected with an error rather than silently truncating). Use it
+ * when the input is a counted buffer, not a C string. */
+char *st_sh_quote_n(const char *value, size_t len, struct st_error **err);
+
+/*
+ * Emitter helpers. All return 0 on success, -1 on failure (NULL stream
+ * or text, or an I/O error). They do not call exit()/abort().
+ */
+
+/* Writes `s` verbatim. The caller ensures `s` is safe shell text
+ * (usually it is hand-written code, or output of st_sh_quote()). */
+int st_sh_emit_str(FILE *out, const char *s);
+
+/* Writes a comment: `# `, then `text` with every embedded newline
+ * followed by `# `, then a terminating newline. `text` must not be
+ * NULL. */
+int st_sh_emit_comment(FILE *out, const char *text);
+
+/* Writes `var=<quoted_value>` plus a newline. `quoted_value` must be
+ * ALREADY shell-safe (typically the result of st_sh_quote()) — it is
+ * emitted verbatim. */
+int st_sh_emit_assign(FILE *out, const char *var, const char *quoted_value);
+
+/* Convenience: quotes `value` with st_sh_quote() and assigns it in one
+ * step. Returns -1 if quoting fails (NULL/NUL input, OOM) or on I/O
+ * error; the quoted literal is freed internally. */
+int st_sh_emit_assign_q(FILE *out, const char *var, const char *value);
+
+#endif

src/kdl/ast.h

@@ -0,0 +1,107 @@
+/*
+ * ast.h - KDL 2.0.0 syntax tree for stupidtools (todo 7).
+ *
+ * The tree mirrors the KDL node grammar:
+ *
+ *   document := node*
+ *   node     := [type-annotation] name (arg | prop)* children?
+ *
+ * Every element is a RAW TOKEN REFERENCE into the original source buffer:
+ * kind + span + text slice. Strings keep their delimiters and escapes,
+ * numbers keep their radix spelling, keywords keep their `#` spelling.
+ * INTERPRETATION (unescaping, radix conversion, keyword-to-value mapping,
+ * value-level type annotations) is the typed value model (todo 8) and
+ * deliberately does NOT happen here.
+ *
+ * OWNERSHIP
+ * ---------
+ * st_kdl_parse() allocates every node/arg/prop on the heap;
+ * st_kdl_document_free() releases the whole tree (NULL is a safe no-op).
+ * Token text slices and span `file` pointers are BORROWED from the
+ * caller's `src`/`filename` buffers, which must therefore outlive the
+ * document.
+ *
+ * ERROR-SPAN OWNERSHIP (unlike the lexer's borrowed span)
+ * ---------
+ * The lexer borrows its error span from the lexer object (src/kdl/lexer.h).
+ * The parser cannot do that: its context dies before st_kdl_parse()
+ * returns. Parse errors therefore carry a span that is heap-allocated IN
+ * THE SAME BLOCK as the error itself (error struct first, span struct
+ * immediately after it, aligned). st_error_free() frees the block, so the
+ * span needs no separate cleanup and is never dangling. Callers may read
+ * err->span until st_error_free(err), exactly like err->message.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef ST_KDL_AST_H
+#define ST_KDL_AST_H
+
+#include <stddef.h>
+
+#include "lexer.h" /* enum st_token_kind */
+
+struct st_error;
+
+/* One raw token reference. `text` is a borrowed slice into the source
+ * buffer; it is NOT NUL-terminated (use `len`). */
+struct st_kdl_token_ref {
+    enum st_token_kind kind;
+    struct st_span span;
+    const char *text;
+    size_t len;
+};
+
+/* A positional argument, in source order (spec mandates order). */
+struct st_kdl_arg {
+    struct st_kdl_token_ref value;
+    struct st_kdl_token_ref *annotation; /* NULL when not annotated */
+    struct st_kdl_arg *next;
+};
+
+/* A `key = value` property, in source order. The key is a string-ish
+ * token (identifier or any string form); the value is any value token.
+ * `annotation` is the value's type annotation (ST_TOK_TYPE), e.g. the
+ * `u8` in `key=(u8)42`; NULL when the value is not annotated. */
+struct st_kdl_prop {
+    struct st_kdl_token_ref key;
+    struct st_kdl_token_ref value;
+    struct st_kdl_token_ref *annotation; /* NULL when not annotated */
+    struct st_kdl_prop *next;
+};
+
+/* A node: optional type annotation, name, ordered arguments, ordered
+ * properties (interleaved in source, collapsed into the two lists while
+ * preserving relative order within each), and an optional children
+ * block. `next` links siblings in document order. */
+struct st_kdl_node {
+    struct st_kdl_token_ref *type; /* NULL when not annotated */
+    struct st_kdl_token_ref name;
+    struct st_kdl_arg *args;
+    struct st_kdl_prop *props;
+    struct st_kdl_node *children;
+    struct st_kdl_node *next;
+};
+
+/* A document: zero or more top-level nodes in source order. */
+struct st_kdl_document {
+    struct st_kdl_node *nodes;
+};
+
+/* Parse `src` (a NUL-terminated buffer, borrowed) into an AST. On success
+ * returns the document — possibly with zero nodes — and leaves `*err`
+ * untouched. On failure returns NULL and sets `*err` to an owned st_error
+ * of category ST_ERR_KDL_PARSE with a stable span (see the header
+ * comment). `err` is REQUIRED: it must point to a valid
+ * `struct st_error *` — every caller passes `&err`. NULL is tolerated
+ * only as a last-resort fallback (the diagnostic is then discarded, and
+ * the document is still NULL on failure), but no new caller should rely
+ * on it. `filename` is borrowed into every span. */
+struct st_kdl_document *st_kdl_parse(const char *src, const char *filename,
+                                     struct st_error **err);
+
+/* Release a document produced by st_kdl_parse. NULL is a safe no-op. */
+void st_kdl_document_free(struct st_kdl_document *doc);
+
+#endif /* ST_KDL_AST_H */

src/kdl/lexer.c

@@ -0,0 +1,943 @@
+/*
+ * lexer.c - KDL 2.0.0 tokenizer for stupidtools (todo 6).
+ *
+ * Produces a FLAT token stream with a source span on every token. It does
+ * NOT parse node/argument/property structure (the parser does, todo 7).
+ * See lexer.h for the full API + error-span-lifetime contract.
+ *
+ * Design decisions (mirrored in .omo/notepads/stupidtools/learnings.md):
+ *   - identifiers are scanned greedily; non-ASCII bytes are identifier
+ *     characters (the non-identifier set is the ASCII one from §3.10.2).
+ *   - bare `inf` / `-inf` / `nan` / `true` / `false` / `null` are syntax
+ *     errors; the `#`-prefixed keyword forms are distinct token kinds.
+ *   - multi-line strings are delimited by `"""` only; the spec's "first
+ *     line must be a newline" + dedent-prefix rules are VALUE rules and
+ *     are deferred to the value model (todo 8), so `"""multi"""` tokenizes.
+ *   - columns are byte-based (not codepoints); full Unicode grapheme
+ *     columns and disallowed-literal-code-point validation are deferred.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "kdl/lexer.h"
+
+#include "error.h"
+
+#include <stdbool.h>
+#include <stdlib.h>
+#include <string.h>
+
+struct st_lexer {
+    const char *src;      /* borrowed source buffer (NUL-terminated) */
+    const char *pos;      /* current scan position */
+    const char *filename; /* borrowed; stamped into every span */
+    size_t line;          /* current 1-based line */
+    size_t col;           /* current 1-based column (bytes) */
+    struct st_span err_span; /* stable span for the most recent error */
+};
+
+/*
+ * Character classes. Non-ASCII bytes are deliberately treated as
+ * identifier characters (see header note); the classification below only
+ * special-cases ASCII + the UTF-8 newline sequences (NEL/LS/PS).
+ */
+
+static bool
+is_digit(unsigned char c)
+{
+    return c >= '0' && c <= '9';
+}
+
+static bool
+is_hex_digit(unsigned char c)
+{
+    return is_digit(c) || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F');
+}
+
+static bool
+is_oct_digit(unsigned char c)
+{
+    return c >= '0' && c <= '7';
+}
+
+static bool
+is_bin_digit(unsigned char c)
+{
+    return c == '0' || c == '1';
+}
+
+/* Non-newline whitespace (ASCII subset; full Unicode White_Space deferred). */
+static bool
+is_space(unsigned char c)
+{
+    return c == ' ' || c == '\t';
+}
+
+/* Non-identifier ASCII chars per KDL §3.10.2: \ / ( ) { } ; [ ] " # = */
+static bool
+is_nonident(unsigned char c)
+{
+    switch (c) {
+    case '\\':
+    case '/':
+    case '(':
+    case ')':
+    case '{':
+    case '}':
+    case ';':
+    case '[':
+    case ']':
+    case '"':
+    case '#':
+    case '=':
+        return true;
+    default:
+        return false;
+    }
+}
+
+/* Newline sequences per KDL §3.18: CRLF (one newline), CR, LF, VT, FF,
+ * NEL (U+0085), LS (U+2028), PS (U+2029). */
+static bool
+is_newline_at(const char *p)
+{
+    unsigned char c = (unsigned char)p[0];
+
+    if (c == '\r' || c == '\n' || c == '\v' || c == '\f') {
+        return true;
+    }
+    if (c == 0xC2 && (unsigned char)p[1] == 0x85) {
+        return true; /* NEL */
+    }
+    if (c == 0xE2 && (unsigned char)p[1] == 0x80 &&
+        ((unsigned char)p[2] == 0xA8 || (unsigned char)p[2] == 0xA9)) {
+        return true; /* LS, PS */
+    }
+    return false;
+}
+
+/* Advance one character, updating line/col. CRLF counts as one newline. */
+static void
+advance(struct st_lexer *lx)
+{
+    unsigned char c = (unsigned char)*lx->pos;
+
+    if (c == '\0') {
+        return;
+    }
+    if (is_newline_at(lx->pos)) {
+        if (c == '\r' && lx->pos[1] == '\n') {
+            lx->pos += 2;
+        } else if (c == 0xC2) {
+            lx->pos += 2;
+        } else if (c == 0xE2) {
+            lx->pos += 3;
+        } else {
+            lx->pos += 1;
+        }
+        lx->line++;
+        lx->col = 1;
+        return;
+    }
+    lx->pos += 1;
+    lx->col += 1;
+}
+
+/* True when the cursor is on a byte that may continue an identifier. */
+static bool
+at_ident_char(const struct st_lexer *lx)
+{
+    unsigned char c = (unsigned char)*lx->pos;
+
+    if (c == '\0' || is_nonident(c) || is_space(c)) {
+        return false;
+    }
+    return !is_newline_at(lx->pos);
+}
+
+/* True when the cursor is on a byte that may START an identifier (i.e. not
+ * a digit, non-ident char, whitespace, or newline). `+`/`-`/`.` are handled
+ * by the caller because they can also begin numbers. */
+static bool
+at_ident_start(const struct st_lexer *lx)
+{
+    unsigned char c = (unsigned char)*lx->pos;
+
+    if (c == '\0' || is_digit(c) || is_nonident(c) || is_space(c)) {
+        return false;
+    }
+    return !is_newline_at(lx->pos);
+}
+
+/* Build a KDL-parse error at `sp` and return ST_TOK_ERROR. The span is
+ * stored in the lexer so the error's borrowed pointer stays valid until
+ * the next st_lexer_next/free (see lexer.h). */
+static enum st_token_kind
+fail(struct st_lexer *lx, struct st_span sp, const char *msg,
+     struct st_error **err)
+{
+    if (err != NULL) {
+        lx->err_span = sp;
+        *err = st_error_at(st_error_kdl_parse(msg), &lx->err_span);
+    }
+    return ST_TOK_ERROR;
+}
+
+static void
+emit(struct st_token *out, enum st_token_kind kind, struct st_span span,
+     const char *text, size_t len)
+{
+    out->kind = kind;
+    out->span = span;
+    out->text = text;
+    out->len = len;
+}
+
+/* Is `s` (len bytes) one of the bare keyword identifiers that KDL forbids
+ * as an identifier string (must be written with `#` or quoted)? */
+static bool
+is_bare_keyword(const char *s, size_t len)
+{
+    static const char *const keywords[] = {
+        "true", "false", "null", "inf", "-inf", "nan",
+    };
+    size_t i;
+
+    for (i = 0; i < sizeof(keywords) / sizeof(keywords[0]); i++) {
+        size_t klen = strlen(keywords[i]);
+        if (len == klen && memcmp(s, keywords[i], klen) == 0) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/* --- line continuations ------------------------------------------------ */
+
+/* Consume an escline: '\' ws* (single-line-comment | newline | eof).
+ * Returns 0 on success, -1 on error (*err set). */
+static int
+lex_escline(struct st_lexer *lx, struct st_error **err)
+{
+    struct st_span sp = { lx->filename, lx->line, lx->col };
+
+    advance(lx); /* '\' */
+    while (*lx->pos != '\0' && is_space((unsigned char)*lx->pos)) {
+        advance(lx);
+    }
+    if (*lx->pos == '\0') {
+        return 0; /* eof is a legal escline terminator */
+    }
+    if (is_newline_at(lx->pos)) {
+        advance(lx);
+        return 0;
+    }
+    if (lx->pos[0] == '/' && lx->pos[1] == '/') {
+        advance(lx);
+        advance(lx);
+        while (*lx->pos != '\0' && !is_newline_at(lx->pos)) {
+            advance(lx);
+        }
+        if (*lx->pos != '\0') {
+            advance(lx); /* the terminating newline */
+        }
+        return 0;
+    }
+    (void)fail(lx, sp,
+        "invalid line continuation: '\\' must be followed by a newline "
+        "or a line comment", err);
+    return -1;
+}
+
+/* --- identifiers ------------------------------------------------------- */
+
+static enum st_token_kind
+lex_ident(struct st_lexer *lx, struct st_token *out, struct st_span start,
+          struct st_error **err)
+{
+    const char *begin = lx->pos;
+
+    advance(lx); /* first char is a valid ident-start (caller guarantees) */
+    while (at_ident_char(lx)) {
+        advance(lx);
+    }
+
+    if (is_bare_keyword(begin, (size_t)(lx->pos - begin))) {
+        return fail(lx, start,
+            "bare keyword identifier; write it as a '#'-prefixed keyword "
+            "or a quoted string", err);
+    }
+
+    emit(out, ST_TOK_IDENT, start, begin, (size_t)(lx->pos - begin));
+    return ST_TOK_IDENT;
+}
+
+/* --- numbers ----------------------------------------------------------- */
+
+static enum st_token_kind
+lex_number(struct st_lexer *lx, struct st_token *out, struct st_span start,
+           struct st_error **err)
+{
+    const char *begin = lx->pos;
+
+    if (*lx->pos == '+' || *lx->pos == '-') {
+        advance(lx); /* sign */
+    }
+
+    if (lx->pos[0] == '0' && (lx->pos[1] == 'x' || lx->pos[1] == 'X')) {
+        advance(lx);
+        advance(lx); /* 0x */
+        if (!is_hex_digit((unsigned char)*lx->pos)) {
+            return fail(lx, start,
+                "invalid hexadecimal number: expected a hex digit after "
+                "'0x'", err);
+        }
+        while (is_hex_digit((unsigned char)*lx->pos) ||
+               *lx->pos == '_') {
+            advance(lx);
+        }
+    } else if (lx->pos[0] == '0' &&
+               (lx->pos[1] == 'o' || lx->pos[1] == 'O')) {
+        advance(lx);
+        advance(lx); /* 0o */
+        if (!is_oct_digit((unsigned char)*lx->pos)) {
+            return fail(lx, start,
+                "invalid octal number: expected an octal digit after '0o'",
+                err);
+        }
+        while (is_oct_digit((unsigned char)*lx->pos) || *lx->pos == '_') {
+            advance(lx);
+        }
+    } else if (lx->pos[0] == '0' &&
+               (lx->pos[1] == 'b' || lx->pos[1] == 'B')) {
+        advance(lx);
+        advance(lx); /* 0b */
+        if (!is_bin_digit((unsigned char)*lx->pos)) {
+            return fail(lx, start,
+                "invalid binary number: expected a binary digit after '0b'",
+                err);
+        }
+        while (is_bin_digit((unsigned char)*lx->pos) || *lx->pos == '_') {
+            advance(lx);
+        }
+    } else {
+        /* decimal: integer ('.' integer)? exponent? */
+        while (is_digit((unsigned char)*lx->pos) || *lx->pos == '_') {
+            advance(lx);
+        }
+        if (*lx->pos == '.' && is_digit((unsigned char)lx->pos[1])) {
+            advance(lx); /* '.' */
+            while (is_digit((unsigned char)*lx->pos) || *lx->pos == '_') {
+                advance(lx);
+            }
+        }
+        if (*lx->pos == 'e' || *lx->pos == 'E') {
+            const char *save = lx->pos;
+            size_t save_line = lx->line;
+            size_t save_col = lx->col;
+
+            advance(lx); /* e */
+            if (*lx->pos == '+' || *lx->pos == '-') {
+                advance(lx);
+            }
+            if (!is_digit((unsigned char)*lx->pos)) {
+                /* not a real exponent: back off */
+                lx->pos = save;
+                lx->line = save_line;
+                lx->col = save_col;
+            } else {
+                while (is_digit((unsigned char)*lx->pos) ||
+                       *lx->pos == '_') {
+                    advance(lx);
+                }
+            }
+        }
+    }
+
+    emit(out, ST_TOK_NUMBER, start, begin, (size_t)(lx->pos - begin));
+    return ST_TOK_NUMBER;
+}
+
+/* Dispatch for bytes that may start either a number or an identifier
+ * (digits, '+', '-', '.'). */
+static enum st_token_kind
+lex_value_start(struct st_lexer *lx, struct st_token *out,
+                struct st_span start, struct st_error **err)
+{
+    unsigned char c = (unsigned char)*lx->pos;
+
+    if (is_digit(c)) {
+        return lex_number(lx, out, start, err);
+    }
+    if (c == '+' || c == '-') {
+        unsigned char n = (unsigned char)lx->pos[1];
+
+        if (is_digit(n)) {
+            return lex_number(lx, out, start, err);
+        }
+        if (n == '.' && is_digit((unsigned char)lx->pos[2])) {
+            return fail(lx, start,
+                "number must have a leading digit before the decimal point",
+                err);
+        }
+        return lex_ident(lx, out, start, err);
+    }
+    if (c == '.') {
+        if (is_digit((unsigned char)lx->pos[1])) {
+            return fail(lx, start,
+                "number must have a leading digit (write '0.1', not '.1')",
+                err);
+        }
+        return lex_ident(lx, out, start, err);
+    }
+    return lex_ident(lx, out, start, err);
+}
+
+/* --- strings ----------------------------------------------------------- */
+
+/* Scan one escape sequence (at a '\'); validates it but does not unescape.
+ * Returns 0 on success, -1 on error. */
+static int
+lex_escape(struct st_lexer *lx, struct st_span start, struct st_error **err)
+{
+    unsigned char c;
+
+    advance(lx); /* '\' */
+    c = (unsigned char)*lx->pos;
+
+    if (c == '\0') {
+        (void)fail(lx, start, "unterminated escape sequence in string", err);
+        return -1;
+    }
+    switch (c) {
+    case 'n':
+    case 'r':
+    case 't':
+    case '\\':
+    case '"':
+    case 'b':
+    case 'f':
+    case 's':
+        advance(lx);
+        return 0;
+    case 'u': {
+        int ndigits = 0;
+
+        advance(lx); /* u */
+        if (*lx->pos != '{') {
+            (void)fail(lx, start,
+                "invalid unicode escape: expected '{' after '\\u'", err);
+            return -1;
+        }
+        advance(lx); /* { */
+        while (is_hex_digit((unsigned char)*lx->pos)) {
+            advance(lx);
+            ndigits++;
+        }
+        if (*lx->pos != '}') {
+            (void)fail(lx, start,
+                "invalid unicode escape: expected '}'", err);
+            return -1;
+        }
+        if (ndigits == 0 || ndigits > 6) {
+            (void)fail(lx, start,
+                "invalid unicode escape: expected 1-6 hex digits", err);
+            return -1;
+        }
+        advance(lx); /* } */
+        return 0;
+    }
+    default:
+        /* whitespace escape: '\' + one-or-more whitespace/newlines */
+        if (is_space(c) || is_newline_at(lx->pos)) {
+            while (*lx->pos != '\0' &&
+                   (is_space((unsigned char)*lx->pos) ||
+                    is_newline_at(lx->pos))) {
+                advance(lx);
+            }
+            return 0;
+        }
+        (void)fail(lx, start, "invalid escape sequence in string", err);
+        return -1;
+    }
+}
+
+/* Single-line quoted string: "..." (raw disables escapes). */
+static enum st_token_kind
+lex_quoted_string(struct st_lexer *lx, struct st_token *out,
+                  struct st_span start, struct st_error **err, bool raw)
+{
+    const char *begin = lx->pos;
+
+    advance(lx); /* opening '"' */
+
+    for (;;) {
+        unsigned char c = (unsigned char)*lx->pos;
+
+        if (c == '\0') {
+            return fail(lx, start, "unterminated string literal", err);
+        }
+        if (c == '"') {
+            advance(lx); /* closing '"' */
+            break;
+        }
+        if (!raw && c == '\\') {
+            if (lex_escape(lx, start, err) < 0) {
+                return ST_TOK_ERROR;
+            }
+            continue;
+        }
+        if (is_newline_at(lx->pos)) {
+            return fail(lx, start,
+                "unterminated string literal (newline before closing quote)",
+                err);
+        }
+        advance(lx);
+    }
+
+    emit(out, ST_TOK_STRING, start, begin, (size_t)(lx->pos - begin));
+    return ST_TOK_STRING;
+}
+
+/* Multi-line string: """...""" (raw disables escapes). Only the delimiters
+ * are recognized here; dedent/value rules are deferred to todo 8. */
+static enum st_token_kind
+lex_multiline_string(struct st_lexer *lx, struct st_token *out,
+                     struct st_span start, struct st_error **err, bool raw)
+{
+    const char *begin = lx->pos;
+
+    advance(lx);
+    advance(lx);
+    advance(lx); /* opening '"""' */
+
+    for (;;) {
+        if (*lx->pos == '\0') {
+            return fail(lx, start, "unterminated multi-line string", err);
+        }
+        if (lx->pos[0] == '"' && lx->pos[1] == '"' && lx->pos[2] == '"') {
+            advance(lx);
+            advance(lx);
+            advance(lx); /* closing '"""' */
+            break;
+        }
+        if (!raw && *lx->pos == '\\') {
+            if (lex_escape(lx, start, err) < 0) {
+                return ST_TOK_ERROR;
+            }
+            continue;
+        }
+        advance(lx);
+    }
+
+    emit(out, ST_TOK_MULTILINE_STRING, start, begin,
+         (size_t)(lx->pos - begin));
+    return ST_TOK_MULTILINE_STRING;
+}
+
+/* Raw string: '#'* '"' body '"' '#'*  or  '#'* '"""' body '"""' '#'*.
+ * The body may contain '"' / '#' as long as it is not the closing
+ * delimiter (the closing quote followed by exactly n '#'). */
+static enum st_token_kind
+lex_raw_string(struct st_lexer *lx, struct st_token *out,
+               struct st_span start, struct st_error **err)
+{
+    const char *begin = lx->pos;
+    size_t n = 0;
+    size_t i;
+    bool multi;
+
+    while (*lx->pos == '#') {
+        advance(lx);
+        n++;
+    }
+
+    multi = (lx->pos[0] == '"' && lx->pos[1] == '"' && lx->pos[2] == '"');
+
+    if (multi) {
+        advance(lx);
+        advance(lx);
+        advance(lx); /* '"""' */
+        for (;;) {
+            if (*lx->pos == '\0') {
+                return fail(lx, start,
+                    "unterminated raw multi-line string", err);
+            }
+            if (lx->pos[0] == '"' && lx->pos[1] == '"' &&
+                lx->pos[2] == '"') {
+                bool closes = true;
+
+                for (i = 0; i < n; i++) {
+                    if (lx->pos[3 + i] != '#') {
+                        closes = false;
+                        break;
+                    }
+                }
+                if (closes) {
+                    advance(lx);
+                    advance(lx);
+                    advance(lx);
+                    for (i = 0; i < n; i++) {
+                        advance(lx);
+                    }
+                    break;
+                }
+            }
+            advance(lx);
+        }
+    } else {
+        advance(lx); /* '"' */
+        for (;;) {
+            if (*lx->pos == '\0') {
+                return fail(lx, start,
+                    "unterminated raw string literal", err);
+            }
+            if (lx->pos[0] == '"') {
+                bool closes = true;
+
+                for (i = 0; i < n; i++) {
+                    if (lx->pos[1 + i] != '#') {
+                        closes = false;
+                        break;
+                    }
+                }
+                if (closes) {
+                    advance(lx); /* '"' */
+                    for (i = 0; i < n; i++) {
+                        advance(lx);
+                    }
+                    break;
+                }
+            }
+            if (is_newline_at(lx->pos)) {
+                return fail(lx, start,
+                    "unterminated raw string literal (newline before "
+                    "closing quote)", err);
+            }
+            advance(lx);
+        }
+    }
+
+    emit(out, ST_TOK_RAW_STRING, start, begin, (size_t)(lx->pos - begin));
+    return ST_TOK_RAW_STRING;
+}
+
+/* --- keywords (#inf / #-inf / #nan / #true / #false / #null) ----------- */
+
+static enum st_token_kind
+lex_keyword(struct st_lexer *lx, struct st_token *out, struct st_span start,
+            struct st_error **err)
+{
+    const char *begin = lx->pos;
+    const char *kw;
+    size_t kwlen;
+
+    advance(lx); /* '#' */
+    kw = lx->pos;
+    if (*lx->pos == '-') {
+        advance(lx);
+    }
+    while (at_ident_char(lx)) {
+        advance(lx);
+    }
+    kwlen = (size_t)(lx->pos - kw);
+
+    if (kwlen == 3 && memcmp(kw, "inf", 3) == 0) {
+        emit(out, ST_TOK_INF, start, begin, (size_t)(lx->pos - begin));
+        return ST_TOK_INF;
+    }
+    if (kwlen == 4 && memcmp(kw, "-inf", 4) == 0) {
+        emit(out, ST_TOK_NEG_INF, start, begin, (size_t)(lx->pos - begin));
+        return ST_TOK_NEG_INF;
+    }
+    if (kwlen == 3 && memcmp(kw, "nan", 3) == 0) {
+        emit(out, ST_TOK_NAN, start, begin, (size_t)(lx->pos - begin));
+        return ST_TOK_NAN;
+    }
+    if (kwlen == 4 && memcmp(kw, "true", 4) == 0) {
+        emit(out, ST_TOK_TRUE, start, begin, (size_t)(lx->pos - begin));
+        return ST_TOK_TRUE;
+    }
+    if (kwlen == 5 && memcmp(kw, "false", 5) == 0) {
+        emit(out, ST_TOK_FALSE, start, begin, (size_t)(lx->pos - begin));
+        return ST_TOK_FALSE;
+    }
+    if (kwlen == 4 && memcmp(kw, "null", 4) == 0) {
+        emit(out, ST_TOK_NULL, start, begin, (size_t)(lx->pos - begin));
+        return ST_TOK_NULL;
+    }
+    return fail(lx, start, "unknown '#'-prefixed keyword", err);
+}
+
+/* Dispatch on '#': raw string or keyword. */
+static enum st_token_kind
+lex_hash(struct st_lexer *lx, struct st_token *out, struct st_span start,
+         struct st_error **err)
+{
+    const char *p = lx->pos;
+
+    while (*p == '#') {
+        p++;
+    }
+    if (*p == '"') {
+        return lex_raw_string(lx, out, start, err);
+    }
+    if (lx->pos[1] == '#') {
+        return fail(lx, start,
+            "invalid token: '#' must be followed by a string or a keyword",
+            err);
+    }
+    return lex_keyword(lx, out, start, err);
+}
+
+/* --- type annotation --------------------------------------------------- */
+
+static enum st_token_kind
+lex_type(struct st_lexer *lx, struct st_token *out, struct st_span start,
+         struct st_error **err)
+{
+    const char *name;
+    size_t namelen;
+
+    advance(lx); /* '(' */
+    while (is_space((unsigned char)*lx->pos)) {
+        advance(lx);
+    }
+    if (!at_ident_start(lx)) {
+        return fail(lx, start, "expected a type name inside '('", err);
+    }
+    name = lx->pos;
+    advance(lx);
+    while (at_ident_char(lx)) {
+        advance(lx);
+    }
+    namelen = (size_t)(lx->pos - name);
+
+    while (is_space((unsigned char)*lx->pos)) {
+        advance(lx);
+    }
+    if (*lx->pos != ')') {
+        return fail(lx, start,
+            "unterminated type annotation (expected ')')", err);
+    }
+    advance(lx); /* ')' */
+
+    emit(out, ST_TOK_TYPE, start, name, namelen);
+    return ST_TOK_TYPE;
+}
+
+/* --- comments ---------------------------------------------------------- */
+
+static enum st_token_kind
+lex_comment(struct st_lexer *lx, struct st_token *out, struct st_span start,
+            struct st_error **err)
+{
+    const char *begin = lx->pos;
+
+    if (lx->pos[1] == '/') {
+        advance(lx);
+        advance(lx); /* '//' */
+        while (*lx->pos != '\0' && !is_newline_at(lx->pos)) {
+            advance(lx);
+        }
+        emit(out, ST_TOK_LINE_COMMENT, start, begin,
+             (size_t)(lx->pos - begin));
+        return ST_TOK_LINE_COMMENT;
+    }
+    if (lx->pos[1] == '*') {
+        int depth = 1;
+
+        advance(lx);
+        advance(lx); /* slash-star opener */
+        while (depth > 0) {
+            if (*lx->pos == '\0') {
+                return fail(lx, start, "unterminated block comment", err);
+            }
+            if (lx->pos[0] == '/' && lx->pos[1] == '*') {
+                advance(lx);
+                advance(lx);
+                depth++;
+                continue;
+            }
+            if (lx->pos[0] == '*' && lx->pos[1] == '/') {
+                advance(lx);
+                advance(lx);
+                depth--;
+                continue;
+            }
+            advance(lx);
+        }
+        emit(out, ST_TOK_BLOCK_COMMENT, start, begin,
+             (size_t)(lx->pos - begin));
+        return ST_TOK_BLOCK_COMMENT;
+    }
+    if (lx->pos[1] == '-') {
+        advance(lx);
+        advance(lx); /* '/-' */
+        emit(out, ST_TOK_SLASHDASH, start, begin,
+             (size_t)(lx->pos - begin));
+        return ST_TOK_SLASHDASH;
+    }
+    return fail(lx, start, "unexpected '/'", err);
+}
+
+/* --- public API -------------------------------------------------------- */
+
+struct st_lexer *
+st_lexer_new(const char *src, const char *filename)
+{
+    struct st_lexer *lx = calloc(1, sizeof(*lx));
+
+    if (lx == NULL) {
+        return NULL;
+    }
+    lx->src = src != NULL ? src : "";
+    lx->pos = lx->src;
+    lx->filename = filename;
+    lx->line = 1;
+    lx->col = 1;
+
+    /* Skip a leading BOM (U+FEFF = EF BB BF), legal only as the very first
+     * code point of a document. */
+    if ((unsigned char)lx->pos[0] == 0xEF &&
+        (unsigned char)lx->pos[1] == 0xBB &&
+        (unsigned char)lx->pos[2] == 0xBF) {
+        lx->pos += 3;
+    }
+    return lx;
+}
+
+void
+st_lexer_free(struct st_lexer *lx)
+{
+    free(lx);
+}
+
+enum st_token_kind
+st_lexer_next(struct st_lexer *lx, struct st_token *out, struct st_error **err)
+{
+    unsigned char c;
+    struct st_span start;
+
+    if (err != NULL) {
+        *err = NULL;
+    }
+
+    /* Skip whitespace, newlines, and line continuations. */
+    for (;;) {
+        while (*lx->pos != '\0' &&
+               (is_space((unsigned char)*lx->pos) || is_newline_at(lx->pos))) {
+            advance(lx);
+        }
+        if (*lx->pos == '\\') {
+            if (lex_escline(lx, err) < 0) {
+                return ST_TOK_ERROR;
+            }
+            continue;
+        }
+        break;
+    }
+
+    if (*lx->pos == '\0') {
+        emit(out, ST_TOK_EOF, (struct st_span){ lx->filename, lx->line,
+              lx->col }, lx->pos, 0);
+        return ST_TOK_EOF;
+    }
+
+    start = (struct st_span){ lx->filename, lx->line, lx->col };
+    c = (unsigned char)*lx->pos;
+
+    /* numbers, signs, and dotted identifiers */
+    if (is_digit(c) || c == '+' || c == '-' || c == '.') {
+        return lex_value_start(lx, out, start, err);
+    }
+
+    switch (c) {
+    case '{':
+        emit(out, ST_TOK_LBRACE, start, lx->pos, 1);
+        advance(lx);
+        break;
+    case '}':
+        emit(out, ST_TOK_RBRACE, start, lx->pos, 1);
+        advance(lx);
+        break;
+    case ';':
+        emit(out, ST_TOK_SEMICOLON, start, lx->pos, 1);
+        advance(lx);
+        break;
+    case '=':
+        emit(out, ST_TOK_EQUALS, start, lx->pos, 1);
+        advance(lx);
+        break;
+    case '"':
+        if (lx->pos[1] == '"' && lx->pos[2] == '"') {
+            return lex_multiline_string(lx, out, start, err, false);
+        }
+        return lex_quoted_string(lx, out, start, err, false);
+    case '#':
+        return lex_hash(lx, out, start, err);
+    case '(':
+        return lex_type(lx, out, start, err);
+    case '/':
+        return lex_comment(lx, out, start, err);
+    default:
+        if (at_ident_start(lx)) {
+            return lex_ident(lx, out, start, err);
+        }
+        return fail(lx, start, "unexpected character in source", err);
+    }
+
+    return out->kind;
+}
+
+const char *
+st_token_kind_name(enum st_token_kind kind)
+{
+    switch (kind) {
+    case ST_TOK_EOF:
+        return "eof";
+    case ST_TOK_ERROR:
+        return "error";
+    case ST_TOK_LBRACE:
+        return "lbrace";
+    case ST_TOK_RBRACE:
+        return "rbrace";
+    case ST_TOK_SEMICOLON:
+        return "semicolon";
+    case ST_TOK_EQUALS:
+        return "equals";
+    case ST_TOK_IDENT:
+        return "ident";
+    case ST_TOK_STRING:
+        return "string";
+    case ST_TOK_MULTILINE_STRING:
+        return "multiline-string";
+    case ST_TOK_RAW_STRING:
+        return "raw-string";
+    case ST_TOK_NUMBER:
+        return "number";
+    case ST_TOK_INF:
+        return "inf";
+    case ST_TOK_NEG_INF:
+        return "-inf";
+    case ST_TOK_NAN:
+        return "nan";
+    case ST_TOK_TRUE:
+        return "true";
+    case ST_TOK_FALSE:
+        return "false";
+    case ST_TOK_NULL:
+        return "null";
+    case ST_TOK_TYPE:
+        return "type";
+    case ST_TOK_LINE_COMMENT:
+        return "line-comment";
+    case ST_TOK_BLOCK_COMMENT:
+        return "block-comment";
+    case ST_TOK_SLASHDASH:
+        return "slashdash";
+    default:
+        return "?";
+    }
+}

src/kdl/lexer.h

@@ -0,0 +1,119 @@
+/*
+ * lexer.h - KDL 2.0.0 tokenizer for stupidtools.
+ *
+ * Produces a FLAT token stream; it does NOT parse node/argument/property
+ * structure (that is the parser, todo 7). Every token carries a source
+ * span (struct st_span) and a borrowed text slice into the source buffer.
+ *
+ * API
+ * ---
+ *   struct st_lexer *st_lexer_new(const char *src, const char *filename);
+ *   enum st_token_kind st_lexer_next(struct st_lexer *, struct st_token *,
+ *                                    struct st_error **err);
+ *   void st_lexer_free(struct st_lexer *);
+ *   const char *st_token_kind_name(enum st_token_kind);
+ *
+ * st_lexer_new() borrows `src` (never copies); the buffer must remain
+ * valid for the lexer's lifetime because token text slices point into it.
+ * `filename` is also borrowed and is stamped into every span.
+ *
+ * st_lexer_next() returns one token per call. It returns:
+ *   - a token kind (>= ST_TOK_LBRACE) and fills `*out` on success,
+ *   - ST_TOK_EOF at end of input (out->text/len are empty),
+ *   - ST_TOK_ERROR on a lex error, in which case `*err` is set to a
+ *     freshly allocated st_error (category ST_ERR_KDL_PARSE) and `*out`
+ *     is left unchanged. The caller owns `*err` and frees it with
+ *     st_error_free().
+ *
+ * ERROR-SPAN LIFETIME (borrowed span)
+ * ---
+ * st_error carries only a BORROWED span pointer (src/error.h), so the
+ * lexer cannot hand back a stack-local span. Instead the lexer stores the
+ * offending span in its own `err_span` field and passes &lx->err_span to
+ * st_error_at(). Consequence: the returned error's span is valid only
+ * until the NEXT st_lexer_next() call or st_lexer_free() — copy the span
+ * (or print the error) before re-lexing. This mirrors the span.h "file is
+ * borrowed" convention.
+ *
+ * TOKEN-ROLE NOTES (contract for todo 7, the parser)
+ * ---
+ * The lexer is deliberately role-agnostic. NODE_NAME / ARGUMENT / PROPERTY
+ * are parser-level roles, not lexical kinds: the parser classifies
+ * ST_TOK_IDENT as a node name, an argument value, or a property key
+ * followed by ST_TOK_EQUALS, by position. String/raw/multi-line text is
+ * the raw source slice (delimiters and escapes intact) — unescaping and
+ * multi-line dedenting belong to the value model (todo 8), not here.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef ST_KDL_LEXER_H
+#define ST_KDL_LEXER_H
+
+#include <stddef.h>
+
+#include "span.h"
+
+struct st_error;
+
+/* Token kinds, ordered so the punctuation kinds follow ST_TOK_ERROR. */
+enum st_token_kind {
+    ST_TOK_EOF = 0, /* end of input */
+    ST_TOK_ERROR,   /* lex error; only ever RETURNED, never stored in a token */
+
+    /* structural punctuation */
+    ST_TOK_LBRACE,  /* { children-block open */
+    ST_TOK_RBRACE,  /* } children-block close */
+    ST_TOK_SEMICOLON, /* ; node separator */
+    ST_TOK_EQUALS,  /* = property assignment */
+
+    /* strings (KDL §3.9) */
+    ST_TOK_IDENT,   /* bare identifier (node name / arg / property key) */
+    ST_TOK_STRING,  /* "quoted" single-line string */
+    ST_TOK_MULTILINE_STRING, /* """multi-line""" string */
+    ST_TOK_RAW_STRING,       /* #"raw"# or #"""raw multi-line"""# */
+
+    /* numbers (KDL §3.14) */
+    ST_TOK_NUMBER,  /* decimal / 0x hex / 0o octal / 0b binary */
+    ST_TOK_INF,     /* #inf */
+    ST_TOK_NEG_INF, /* #-inf */
+    ST_TOK_NAN,     /* #nan */
+
+    /* booleans and null (KDL §3.15-3.16) */
+    ST_TOK_TRUE,    /* #true */
+    ST_TOK_FALSE,   /* #false */
+    ST_TOK_NULL,    /* #null */
+
+    /* type annotation (KDL §3.8); text slice is the inner identifier */
+    ST_TOK_TYPE,    /* (u8) -> text "u8" */
+
+    /* comments (KDL §3.17) */
+    ST_TOK_LINE_COMMENT,  /* // ... */
+    ST_TOK_BLOCK_COMMENT, /* ... (possibly nested) */
+    ST_TOK_SLASHDASH,     /* /- node/entry-level comment */
+};
+
+/* One token. `span` is the 1-based line/col of the token's first byte;
+ * `text`/`len` are a borrowed slice into the source (NOT NUL-terminated;
+ * for strings it includes the delimiters). */
+struct st_token {
+    enum st_token_kind kind;
+    struct st_span span;
+    const char *text;
+    size_t len;
+};
+
+struct st_lexer;
+
+struct st_lexer *st_lexer_new(const char *src, const char *filename);
+void st_lexer_free(struct st_lexer *lx);
+
+enum st_token_kind st_lexer_next(struct st_lexer *lx, struct st_token *out,
+                                 struct st_error **err);
+
+/* Stable display name for a token kind (e.g. "ident"). Unknown kinds
+ * yield "?" rather than indexing out of range. */
+const char *st_token_kind_name(enum st_token_kind kind);
+
+#endif /* ST_KDL_LEXER_H */

src/kdl/parser.c

@@ -0,0 +1,705 @@
+/*
+ * parser.c - KDL 2.0.0 recursive-descent parser for stupidtools (todo 7).
+ *
+ * Consumes the lexer's flat token stream (src/kdl/lexer.h) and builds the
+ * AST from src/kdl/ast.h. Roles are assigned BY POSITION, per the lexer's
+ * contract: a string-ish token followed by ST_TOK_EQUALS (on the same
+ * line) is a property key, otherwise a bare value is an argument.
+ *
+ * Grammar implemented (see the plan, todo 7):
+ *
+ *   document := node*        (separated by whitespace/`;`; comments and
+ *                             `/-` are trivia, skipped)
+ *   node     := [type] name (arg | prop)* children?
+ *   children := '{' node* '}'   (`;`-separated, recursively)
+ *   arg      := value token
+ *   prop     := string-ish-token '=' value token
+ *
+ * Node termination: a node ends at `;`, `/-`, the end of its parent's
+ * child block (`}`), EOF, or a token on a LATER source line than the last
+ * consumed token (the lexer discards newlines, so the parser infers
+ * newline termination from token spans). Entries and the children block
+ * may span lines only via the lexer's line continuations (esclines), which
+ * the lexer consumes invisibly.
+ *
+ * ERRORS AND SPANS
+ * ----------------
+ * Every parse failure returns a st_error (ST_ERR_KDL_PARSE) carrying a
+ * span. Because st_error only holds a BORROWED span pointer (src/error.h
+ * is frozen), and the lexer's err_span dies with the lexer, the parser
+ * copies the span into storage that is heap-allocated IN THE SAME BLOCK
+ * as the error struct itself — st_error_free() releases both, so the span
+ * is never dangling and never leaked. Lexer errors are likewise copied
+ * into an owned block before the lexer is freed.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "kdl/ast.h"
+
+#include "error.h"
+#include "kdl/lexer.h"
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* ---- parser state ----------------------------------------------------- */
+
+struct st_parser {
+    struct st_lexer *lx;
+    struct st_token tok; /* one-token lookahead */
+    bool has_tok;        /* is `tok` a valid peeked token? */
+};
+
+/* ---- owned errors ----------------------------------------------------- */
+
+/* Build an owned ST_ERR_KDL_PARSE error whose span lives in the same
+ * allocation as the error struct (aligned right after it). Returns NULL
+ * only on allocation failure. */
+static struct st_error *
+err_at_owned(struct st_span sp, const char *msg)
+{
+    const size_t align = _Alignof(struct st_span);
+    const size_t esize =
+        (sizeof(struct st_error) + align - 1) & ~(align - 1);
+    struct st_error *e;
+    struct st_span *spc;
+    size_t mlen;
+
+    if (msg == NULL) {
+        msg = "";
+    }
+    e = malloc(esize + sizeof(struct st_span));
+    if (e == NULL) {
+        return NULL;
+    }
+    mlen = strlen(msg);
+    e->message = malloc(mlen + 1);
+    if (e->message == NULL) {
+        free(e);
+        return NULL;
+    }
+    memcpy(e->message, msg, mlen + 1);
+    e->category = ST_ERR_KDL_PARSE;
+    spc = (struct st_span *)((unsigned char *)e + esize);
+    *spc = sp;
+    e->span = spc;
+    return e;
+}
+
+/* ---- token plumbing --------------------------------------------------- */
+
+/* Pull the next token from the lexer into p->tok. On a lex error, copies
+ * the error (message + span value) into an owned block, frees the
+ * lexer's error, and returns ST_TOK_ERROR with *err set. */
+static enum st_token_kind
+p_fetch(struct st_parser *p, struct st_error **err)
+{
+    struct st_error *lexerr = NULL;
+    enum st_token_kind k;
+    struct st_span sp;
+
+    k = st_lexer_next(p->lx, &p->tok, &lexerr);
+    if (k != ST_TOK_ERROR) {
+        return k;
+    }
+    /* Duplicate the message while `lexerr` is still alive (its span value
+     * is copied by value; the message must be copied BEFORE the free). */
+    if (lexerr != NULL) {
+        sp = lexerr->span != NULL ? *lexerr->span : p->tok.span;
+        *err = err_at_owned(sp, st_error_message(lexerr));
+        st_error_free(lexerr);
+    } else {
+        *err = err_at_owned(p->tok.span, "lexer error");
+    }
+    return ST_TOK_ERROR;
+}
+
+/* Peek the next token (leaving it in the lookahead). ST_TOK_ERROR on a
+ * lex failure (*err set). */
+static enum st_token_kind
+p_peek(struct st_parser *p, struct st_error **err)
+{
+    if (!p->has_tok) {
+        enum st_token_kind k = p_fetch(p, err);
+
+        if (k == ST_TOK_ERROR) {
+            return ST_TOK_ERROR;
+        }
+        p->has_tok = true;
+    }
+    return p->tok.kind;
+}
+
+/* Discard the peeked token. */
+static void
+p_consume(struct st_parser *p)
+{
+    p->has_tok = false;
+}
+
+/* Skip separators/trivia at node-boundary level (document and children
+ * block): line/block comments, slashdash, semicolons. Returns 0 on
+ * success, -1 on lex error (*err set). */
+static int
+skip_trivia(struct st_parser *p, struct st_error **err)
+{
+    for (;;) {
+        enum st_token_kind k = p_peek(p, err);
+
+        if (k == ST_TOK_ERROR) {
+            return -1;
+        }
+        switch (k) {
+        case ST_TOK_LINE_COMMENT:
+        case ST_TOK_BLOCK_COMMENT:
+        case ST_TOK_SLASHDASH:
+        case ST_TOK_SEMICOLON:
+            p_consume(p);
+            continue;
+        default:
+            return 0;
+        }
+    }
+}
+
+/* Skip comments only (positions INSIDE a node, where `;` and `/-`
+ * terminate the node instead of being trivia). Returns 0 on success,
+ * -1 on lex error (*err set). */
+static int
+skip_comments(struct st_parser *p, struct st_error **err)
+{
+    for (;;) {
+        enum st_token_kind k = p_peek(p, err);
+
+        if (k == ST_TOK_ERROR) {
+            return -1;
+        }
+        if (k == ST_TOK_LINE_COMMENT || k == ST_TOK_BLOCK_COMMENT) {
+            p_consume(p);
+            continue;
+        }
+        return 0;
+    }
+}
+
+/* ---- token classification --------------------------------------------- */
+
+/* String-ish tokens: legal node names and property keys (the KDL grammar
+ * "string": identifiers plus every quoted/raw/multi-line string form). */
+static bool
+tok_is_stringish(enum st_token_kind k)
+{
+    return k == ST_TOK_IDENT || k == ST_TOK_STRING ||
+           k == ST_TOK_MULTILINE_STRING || k == ST_TOK_RAW_STRING;
+}
+
+/* Value tokens: anything usable as an argument or a property value. */
+static bool
+tok_is_value(enum st_token_kind k)
+{
+    return tok_is_stringish(k) || k == ST_TOK_NUMBER || k == ST_TOK_INF ||
+           k == ST_TOK_NEG_INF || k == ST_TOK_NAN || k == ST_TOK_TRUE ||
+           k == ST_TOK_FALSE || k == ST_TOK_NULL;
+}
+
+/* ---- AST construction ------------------------------------------------- */
+
+static void
+ref_from_token(struct st_kdl_token_ref *ref, const struct st_token *t)
+{
+    ref->kind = t->kind;
+    ref->span = t->span;
+    ref->text = t->text;
+    ref->len = t->len;
+}
+
+static struct st_kdl_arg *
+arg_new(const struct st_token *t, const struct st_token *ann, bool has_ann)
+{
+    struct st_kdl_arg *a = calloc(1, sizeof(*a));
+
+    if (a == NULL) {
+        return NULL;
+    }
+    ref_from_token(&a->value, t);
+    if (has_ann) {
+        a->annotation = malloc(sizeof(*a->annotation));
+        if (a->annotation == NULL) {
+            free(a);
+            return NULL;
+        }
+        ref_from_token(a->annotation, ann);
+    }
+    return a;
+}
+
+static struct st_kdl_prop *
+prop_new(const struct st_token *key, const struct st_token *value,
+         const struct st_token *ann, bool has_ann)
+{
+    struct st_kdl_prop *pr = calloc(1, sizeof(*pr));
+
+    if (pr == NULL) {
+        return NULL;
+    }
+    ref_from_token(&pr->key, key);
+    ref_from_token(&pr->value, value);
+    if (has_ann) {
+        pr->annotation = malloc(sizeof(*pr->annotation));
+        if (pr->annotation == NULL) {
+            free(pr);
+            return NULL;
+        }
+        ref_from_token(pr->annotation, ann);
+    }
+    return pr;
+}
+
+static struct st_kdl_node *
+node_new(const struct st_token *name, const struct st_token *type,
+         bool has_type)
+{
+    struct st_kdl_node *n = calloc(1, sizeof(*n));
+
+    if (n == NULL) {
+        return NULL;
+    }
+    ref_from_token(&n->name, name);
+    if (has_type) {
+        n->type = malloc(sizeof(*n->type));
+        if (n->type == NULL) {
+            free(n);
+            return NULL;
+        }
+        ref_from_token(n->type, type);
+    }
+    return n;
+}
+
+static void
+nodes_free(struct st_kdl_node *head);
+
+static void
+node_free(struct st_kdl_node *n)
+{
+    struct st_kdl_arg *a;
+    struct st_kdl_prop *pr;
+
+    if (n == NULL) {
+        return;
+    }
+    free(n->type);
+    for (a = n->args; a != NULL;) {
+        struct st_kdl_arg *nx = a->next;
+        free(a->annotation);
+        free(a);
+        a = nx;
+    }
+    for (pr = n->props; pr != NULL;) {
+        struct st_kdl_prop *px = pr->next;
+        free(pr->annotation);
+        free(pr);
+        pr = px;
+    }
+    nodes_free(n->children);
+    free(n);
+}
+
+static void
+nodes_free(struct st_kdl_node *head)
+{
+    while (head != NULL) {
+        struct st_kdl_node *nx = head->next;
+        node_free(head);
+        head = nx;
+    }
+}
+
+/* ---- the grammar ------------------------------------------------------ */
+
+static struct st_kdl_node *parse_node(struct st_parser *p,
+                                      struct st_error **err);
+
+/* Parse a children block. The opening `{` is already consumed; `lbrace`
+ * is its span (used for the unterminated-block error). Returns the child
+ * list head (NULL for an empty block), or NULL with *err set. */
+static struct st_kdl_node *
+parse_children(struct st_parser *p, struct st_span lbrace,
+               struct st_error **err)
+{
+    struct st_kdl_node *head = NULL;
+    struct st_kdl_node *tail = NULL;
+
+    for (;;) {
+        enum st_token_kind k;
+        struct st_kdl_node *n;
+
+        if (skip_trivia(p, err) < 0) {
+            nodes_free(head);
+            return NULL;
+        }
+        k = p_peek(p, err);
+        if (k == ST_TOK_ERROR) {
+            nodes_free(head);
+            return NULL;
+        }
+        if (k == ST_TOK_EOF) {
+            nodes_free(head);
+            *err = err_at_owned(lbrace,
+                "unterminated children block (missing closing '}')");
+            return NULL;
+        }
+        if (k == ST_TOK_RBRACE) {
+            p_consume(p);
+            return head;
+        }
+        n = parse_node(p, err);
+        if (n == NULL) {
+            nodes_free(head);
+            return NULL;
+        }
+        if (tail == NULL) {
+            head = tail = n;
+        } else {
+            tail->next = n;
+            tail = n;
+        }
+    }
+}
+
+/* Parse one node. Returns NULL with *err set on failure. The caller is
+ * responsible for freeing the node list when NULL comes back. */
+static struct st_kdl_node *
+parse_node(struct st_parser *p, struct st_error **err)
+{
+    struct st_kdl_node *n = NULL;
+    struct st_token name_tok;
+    struct st_token type_tok;
+    struct st_kdl_arg *args_tail = NULL;
+    struct st_kdl_prop *props_tail = NULL;
+    bool has_type = false;
+    size_t last_line;
+    enum st_token_kind k;
+
+    /* Optional type annotation. */
+    if (skip_comments(p, err) < 0) {
+        return NULL;
+    }
+    k = p_peek(p, err);
+    if (k == ST_TOK_ERROR) {
+        return NULL;
+    }
+    if (k == ST_TOK_TYPE) {
+        type_tok = p->tok;
+        has_type = true;
+        p_consume(p);
+        if (skip_comments(p, err) < 0) {
+            return NULL;
+        }
+        k = p_peek(p, err);
+        if (k == ST_TOK_ERROR) {
+            return NULL;
+        }
+    }
+
+    /* Name: any string-ish token. */
+    if (!tok_is_stringish(k)) {
+        *err = err_at_owned(p->tok.span, "expected a node name");
+        return NULL;
+    }
+    name_tok = p->tok;
+    p_consume(p);
+
+    n = node_new(&name_tok, &type_tok, has_type);
+    if (n == NULL) {
+        *err = err_at_owned(name_tok.span, "out of memory");
+        return NULL;
+    }
+    last_line = name_tok.span.line;
+
+    /* Entries: interleaved arguments and properties. */
+    for (;;) {
+        if (skip_comments(p, err) < 0) {
+            node_free(n);
+            return NULL;
+        }
+        k = p_peek(p, err);
+        if (k == ST_TOK_ERROR) {
+            node_free(n);
+            return NULL;
+        }
+        switch (k) {
+        case ST_TOK_EOF:
+        case ST_TOK_RBRACE:
+        case ST_TOK_SEMICOLON:
+        case ST_TOK_SLASHDASH:
+            /* Terminated: the peeked token belongs to the caller's level. */
+            return n;
+        default:
+            break;
+        }
+        if (p->tok.span.line > last_line) {
+            /* Newline termination (the lexer discards newlines). */
+            return n;
+        }
+        switch (k) {
+        case ST_TOK_LBRACE: {
+            struct st_span lbrace = p->tok.span;
+
+            p_consume(p);
+            n->children = parse_children(p, lbrace, err);
+            if (*err != NULL) {
+                node_free(n);
+                return NULL;
+            }
+            return n;
+        }
+        case ST_TOK_EQUALS:
+            /* The previous token was the node name or a non-key value. */
+            *err = err_at_owned(p->tok.span, "unexpected '='");
+            node_free(n);
+            return NULL;
+        case ST_TOK_TYPE: {
+            /* Value annotation: capture it, then require an argument value.
+             * (A type annotation in entry position prefixes a VALUE, so the
+             * annotated token is always an argument, never a property key.) */
+            struct st_token ann_tok = p->tok;
+            struct st_kdl_arg *a;
+
+            p_consume(p);
+            if (skip_comments(p, err) < 0) {
+                node_free(n);
+                return NULL;
+            }
+            k = p_peek(p, err);
+            if (k == ST_TOK_ERROR) {
+                node_free(n);
+                return NULL;
+            }
+            if (!tok_is_value(k)) {
+                *err = err_at_owned(p->tok.span,
+                    "expected a value after type annotation");
+                node_free(n);
+                return NULL;
+            }
+            a = arg_new(&p->tok, &ann_tok, true);
+            if (a == NULL) {
+                *err = err_at_owned(p->tok.span, "out of memory");
+                node_free(n);
+                return NULL;
+            }
+            last_line = p->tok.span.line;
+            p_consume(p);
+            if (args_tail == NULL) {
+                n->args = args_tail = a;
+            } else {
+                args_tail->next = a;
+                args_tail = a;
+            }
+            continue;
+        }
+        default:
+            if (!tok_is_value(k)) {
+                *err = err_at_owned(p->tok.span,
+                    "expected an argument or property");
+                node_free(n);
+                return NULL;
+            }
+            break;
+        }
+
+        /* A value-ish entry: classify as property (key `=` value) or
+         * argument. */
+        {
+            struct st_token val_tok = p->tok;
+
+            p_consume(p);
+            if (tok_is_stringish(val_tok.kind)) {
+                /* `=` lookahead, same source line only. */
+                if (skip_comments(p, err) < 0) {
+                    node_free(n);
+                    return NULL;
+                }
+                k = p_peek(p, err);
+                if (k == ST_TOK_ERROR) {
+                    node_free(n);
+                    return NULL;
+                }
+                if (k == ST_TOK_EQUALS &&
+                    p->tok.span.line == val_tok.span.line) {
+                    struct st_kdl_prop *pr;
+
+                    p_consume(p); /* '=' */
+                    if (skip_comments(p, err) < 0) {
+                        node_free(n);
+                        return NULL;
+                    }
+                    k = p_peek(p, err);
+                    if (k == ST_TOK_ERROR) {
+                        node_free(n);
+                        return NULL;
+                    }
+                    {
+                        struct st_token vann_tok = { 0 };
+                        bool has_vann = false;
+
+                        if (k == ST_TOK_TYPE) {
+                            vann_tok = p->tok;
+                            has_vann = true;
+                            p_consume(p);
+                            if (skip_comments(p, err) < 0) {
+                                node_free(n);
+                                return NULL;
+                            }
+                            k = p_peek(p, err);
+                            if (k == ST_TOK_ERROR) {
+                                node_free(n);
+                                return NULL;
+                            }
+                            if (!tok_is_value(k)) {
+                                *err = err_at_owned(p->tok.span,
+                                    "expected a value after type annotation");
+                                node_free(n);
+                                return NULL;
+                            }
+                        }
+                        if (!tok_is_value(k)) {
+                            *err = err_at_owned(p->tok.span,
+                                "expected a value after '='");
+                            node_free(n);
+                            return NULL;
+                        }
+                        pr = prop_new(&val_tok, &p->tok, &vann_tok, has_vann);
+                    }
+                    if (pr == NULL) {
+                        *err = err_at_owned(val_tok.span, "out of memory");
+                        node_free(n);
+                        return NULL;
+                    }
+                    last_line = p->tok.span.line;
+                    p_consume(p);
+                    if (props_tail == NULL) {
+                        n->props = props_tail = pr;
+                    } else {
+                        props_tail->next = pr;
+                        props_tail = pr;
+                    }
+                    continue;
+                }
+            }
+            /* Argument. */
+            {
+                struct st_kdl_arg *a = arg_new(&val_tok, NULL, false);
+
+                if (a == NULL) {
+                    *err = err_at_owned(val_tok.span, "out of memory");
+                    node_free(n);
+                    return NULL;
+                }
+                last_line = val_tok.span.line;
+                if (args_tail == NULL) {
+                    n->args = args_tail = a;
+                } else {
+                    args_tail->next = a;
+                    args_tail = a;
+                }
+            }
+        }
+    }
+}
+
+/* ---- public API ------------------------------------------------------- */
+
+struct st_kdl_document *
+st_kdl_parse(const char *src, const char *filename, struct st_error **err)
+{
+    struct st_parser parser;
+    struct st_kdl_document *doc;
+    struct st_kdl_node *head = NULL;
+    struct st_kdl_node *tail = NULL;
+    struct st_error *local_err = NULL;
+
+    if (err == NULL) {
+        /* last-resort fallback: the documented contract requires a
+         * non-NULL err; a NULL caller discards the diagnostic */
+        err = &local_err;
+    }
+    *err = NULL;
+
+    parser.lx = st_lexer_new(src, filename);
+    if (parser.lx == NULL) {
+        if (err != NULL) {
+            *err = err_at_owned((struct st_span){ filename, 0, 0 },
+                                "out of memory");
+        }
+        return NULL;
+    }
+    parser.has_tok = false;
+
+    doc = calloc(1, sizeof(*doc));
+    if (doc == NULL) {
+        st_lexer_free(parser.lx);
+        if (err != NULL) {
+            *err = err_at_owned((struct st_span){ filename, 0, 0 },
+                                "out of memory");
+        }
+        return NULL;
+    }
+
+    for (;;) {
+        enum st_token_kind k;
+        struct st_kdl_node *n;
+
+        if (skip_trivia(&parser, err) < 0) {
+            goto fail;
+        }
+        k = p_peek(&parser, err);
+        if (k == ST_TOK_ERROR) {
+            goto fail;
+        }
+        if (k == ST_TOK_EOF) {
+            break;
+        }
+        if (k == ST_TOK_RBRACE) {
+            *err = err_at_owned(parser.tok.span, "unexpected '}'");
+            goto fail;
+        }
+        n = parse_node(&parser, err);
+        if (n == NULL) {
+            goto fail;
+        }
+        if (tail == NULL) {
+            head = tail = n;
+        } else {
+            tail->next = n;
+            tail = n;
+        }
+    }
+
+    st_lexer_free(parser.lx);
+    doc->nodes = head;
+    return doc;
+
+fail:
+    st_lexer_free(parser.lx);
+    nodes_free(head);
+    free(doc);
+    if (err == &local_err && local_err != NULL) {
+        st_error_free(local_err);
+    }
+    return NULL;
+}
+
+void
+st_kdl_document_free(struct st_kdl_document *doc)
+{
+    if (doc == NULL) {
+        return;
+    }
+    nodes_free(doc->nodes);
+    free(doc);
+}

src/kdl/schema.c

@@ -0,0 +1,843 @@
+/*
+ * schema.c - stupidtools DSL schema validation (todo 9).
+ *
+ * Validates a parsed KDL document (src/kdl/ast.h) against the stupidtools
+ * DSL. The grammar is pinned in schema.h - the contract for todos 10/16/23.
+ * This module only READS the AST; it never modifies or frees it.
+ *
+ * Type checks go through the value model (src/kdl/value.h): names, files,
+ * version strings and check arguments must be non-empty unannotated
+ * strings; an option's `default` must be an unannotated boolean. Value-
+ * model failures (bad escapes, overflow) are re-owned as schema errors.
+ *
+ * ERRORS AND SPANS
+ * ----------------
+ * Every failure returns an owned st_error of category ST_ERR_KDL_SCHEMA
+ * whose span is heap-allocated IN THE SAME BLOCK as the error struct
+ * (the parser.c pattern), so err->span stays valid until st_error_free()
+ * and is never dangling. The span is borrowed-by-value from the AST's
+ * token refs, whose `file` pointer in turn borrows the caller's source
+ * buffer - the same lifetime contract as the parser. The single span-less
+ * error is "missing project" on an empty document: there is no source
+ * position (or file name) to point at.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "kdl/schema.h"
+
+#include "detect/check_registry.h"
+#include "error.h"
+#include "kdl/ast.h"
+#include "kdl/value.h"
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* ---- owned errors ----------------------------------------------------- */
+
+/* Build an owned ST_ERR_KDL_SCHEMA error whose span lives in the same
+ * allocation as the error struct (aligned right after it). Returns NULL
+ * only on allocation failure. */
+static struct st_error *
+err_at_owned(struct st_span sp, const char *msg)
+{
+    const size_t align = _Alignof(struct st_span);
+    const size_t esize =
+        (sizeof(struct st_error) + align - 1) & ~(align - 1);
+    struct st_error *e;
+    struct st_span *spc;
+    size_t mlen;
+
+    if (msg == NULL) {
+        msg = "";
+    }
+    e = malloc(esize + sizeof(struct st_span));
+    if (e == NULL) {
+        return NULL;
+    }
+    mlen = strlen(msg);
+    e->message = malloc(mlen + 1);
+    if (e->message == NULL) {
+        free(e);
+        return NULL;
+    }
+    memcpy(e->message, msg, mlen + 1);
+    e->category = ST_ERR_KDL_SCHEMA;
+    spc = (struct st_span *)((unsigned char *)e + esize);
+    *spc = sp;
+    e->span = spc;
+    return e;
+}
+
+/* Re-own a value-model (ST_ERR_KDL_PARSE) error as a schema error: copy
+ * the message and the span VALUE into a fresh block. The caller frees the
+ * original error. */
+static struct st_error *
+schema_err_from(const struct st_error *e)
+{
+    struct st_span sp;
+
+    if (e->span != NULL) {
+        sp = *e->span;
+    } else {
+        sp = (struct st_span){ NULL, 0, 0 };
+    }
+    return err_at_owned(sp, e->message != NULL ? e->message : "");
+}
+
+/* Interpret a token ref through the value model, converting any failure
+ * into an owned schema error (the original is freed here). On success
+ * `*out` holds the interpreted value (caller frees via
+ * st_kdl_value_free). */
+static struct st_error *
+value_interpret(const struct st_kdl_token_ref *tok,
+                const struct st_kdl_token_ref *ann,
+                struct st_kdl_value *out)
+{
+    struct st_error *e = st_kdl_value_from_token_annotated(tok, ann, out);
+
+    if (e != NULL) {
+        struct st_error *r = schema_err_from(e);
+
+        st_error_free(e);
+        return r;
+    }
+    return NULL;
+}
+
+/* ---- naming helpers --------------------------------------------------- */
+
+/* Copy a node name / property key into a fixed buffer for MESSAGE text,
+ * truncating to fit. Identifiers are copied raw (the common case, no
+ * allocation); other string forms are interpreted via the value model,
+ * falling back to "?" when that fails (message-only, never fatal). */
+static void
+name_into(const struct st_kdl_token_ref *name, char *buf, size_t cap)
+{
+    if (cap == 0) {
+        return;
+    }
+    if (name->kind == ST_TOK_IDENT) {
+        size_t n = name->len < cap - 1 ? name->len : cap - 1;
+
+        memcpy(buf, name->text, n);
+        buf[n] = '\0';
+        return;
+    }
+    {
+        struct st_kdl_value v;
+        struct st_error *e = st_kdl_value_from_token(name, &v);
+
+        if (e == NULL && v.kind == ST_KDL_VAL_STRING) {
+            snprintf(buf, cap, "%s", v.as.str);
+        } else {
+            snprintf(buf, cap, "?");
+        }
+        st_error_free(e);
+        st_kdl_value_free(&v);
+    }
+}
+
+/* Compare a node name against a literal, accepting every string form
+ * (identifiers compared directly; other forms via the value model).
+ * Sets *out and returns NULL on success, or an owned schema error when
+ * the name is a string the value model cannot interpret. */
+static struct st_error *
+name_equals(const struct st_kdl_token_ref *name, const char *s, bool *out)
+{
+    if (name->kind == ST_TOK_IDENT) {
+        *out = name->len == strlen(s) &&
+               memcmp(name->text, s, name->len) == 0;
+        return NULL;
+    }
+    {
+        struct st_kdl_value v;
+        struct st_error *e = st_kdl_value_from_token(name, &v);
+
+        if (e != NULL) {
+            struct st_error *r = schema_err_from(e);
+
+            st_error_free(e);
+            *out = false;
+            return r;
+        }
+        *out = v.kind == ST_KDL_VAL_STRING && strcmp(v.as.str, s) == 0;
+        st_kdl_value_free(&v);
+        return NULL;
+    }
+}
+
+/* ---- argument helpers ------------------------------------------------- */
+
+/* Interpret `tok` (with optional annotation) as the non-empty unannotated
+ * string a DSL slot requires; on success *out owns the string (caller
+ * frees). `ctx` names the slot in messages, e.g. "target name". */
+static struct st_error *
+require_string_arg(const struct st_kdl_token_ref *tok,
+                   const struct st_kdl_token_ref *ann,
+                   const char *ctx, char **out)
+{
+    struct st_kdl_value v;
+    struct st_error *e;
+    char msg[192];
+
+    *out = NULL;
+    e = value_interpret(tok, ann, &v);
+    if (e != NULL) {
+        return e;
+    }
+    if (v.annotation != NULL) {
+        snprintf(msg, sizeof msg, "%s must not carry a type annotation",
+                 ctx);
+        e = err_at_owned(tok->span, msg);
+        st_kdl_value_free(&v);
+        return e;
+    }
+    if (v.kind != ST_KDL_VAL_STRING) {
+        snprintf(msg, sizeof msg, "%s must be a non-empty string (got %s)",
+                 ctx, st_kdl_value_kind_name(v.kind));
+        e = err_at_owned(tok->span, msg);
+        st_kdl_value_free(&v);
+        return e;
+    }
+    if (v.as.str[0] == '\0') {
+        snprintf(msg, sizeof msg, "%s must be a non-empty string", ctx);
+        e = err_at_owned(tok->span, msg);
+        st_kdl_value_free(&v);
+        return e;
+    }
+    *out = v.as.str;
+    v.as.str = NULL;
+    st_kdl_value_free(&v); /* frees the annotation only */
+    return NULL;
+}
+
+/* The shared name shape of target/feature/option: exactly one non-empty
+ * string argument. `ctx` is the node kind ("target"). On success *out
+ * owns the name (caller frees). */
+static struct st_error *
+one_name_arg(const struct st_kdl_node *n, const char *ctx, char **out)
+{
+    char msg[192];
+    char cctx[96];
+
+    *out = NULL;
+    if (n->args == NULL) {
+        snprintf(msg, sizeof msg, "%s requires a name argument", ctx);
+        return err_at_owned(n->name.span, msg);
+    }
+    if (n->args->next != NULL) {
+        char nm[65];
+
+        name_into(&n->args->value, nm, sizeof nm);
+        snprintf(msg, sizeof msg, "%s '%s' takes exactly one argument",
+                 ctx, nm);
+        return err_at_owned(n->args->next->value.span, msg);
+    }
+    snprintf(cctx, sizeof cctx, "%s name", ctx);
+    return require_string_arg(&n->args->value, n->args->annotation, cctx,
+                              out);
+}
+
+/* ---- per-node validators ---------------------------------------------- */
+
+/* project "name" version "semver": the name is the first positional
+ * argument; the version string follows the LITERAL `version` keyword.
+ * No properties, no children, exactly three arguments. */
+static struct st_error *
+validate_project(const struct st_kdl_node *n)
+{
+    struct st_kdl_arg *a = n->args;
+    struct st_kdl_arg *ver_kw;
+    char msg[192];
+    char name[65];
+    char ctx[96];
+    struct st_error *e;
+    char *name_str = NULL;
+    char *ver_str = NULL;
+
+    if (a == NULL) {
+        return err_at_owned(n->name.span,
+                            "project requires a name argument");
+    }
+    e = require_string_arg(&a->value, a->annotation, "project name",
+                           &name_str);
+    if (e != NULL) {
+        return e;
+    }
+    name_into(&a->value, name, sizeof name);
+
+    a = a->next;
+    if (a == NULL) {
+        snprintf(msg, sizeof msg,
+            "project '%s' requires a version (expected: project \"name\" "
+            "version \"semver\")", name);
+        e = err_at_owned(n->name.span, msg);
+        goto done;
+    }
+    if (a->annotation != NULL ||
+        !(a->value.kind == ST_TOK_IDENT && a->value.len == 7 &&
+          memcmp(a->value.text, "version", 7) == 0)) {
+        snprintf(msg, sizeof msg,
+            "project '%s': expected the keyword 'version' as the second "
+            "argument", name);
+        e = err_at_owned(a->value.span, msg);
+        goto done;
+    }
+    ver_kw = a;
+    a = a->next;
+    if (a == NULL) {
+        snprintf(msg, sizeof msg,
+            "project '%s': 'version' requires the version string argument",
+            name);
+        e = err_at_owned(ver_kw->value.span, msg);
+        goto done;
+    }
+    snprintf(ctx, sizeof ctx, "project '%s' version", name);
+    e = require_string_arg(&a->value, a->annotation, ctx, &ver_str);
+    if (e != NULL) {
+        goto done;
+    }
+    if (a->next != NULL) {
+        snprintf(msg, sizeof msg,
+            "project '%s' takes exactly three arguments: the name, the "
+            "'version' keyword, and the version string", name);
+        e = err_at_owned(a->next->value.span, msg);
+        goto done;
+    }
+    if (n->props != NULL) {
+        char key[65];
+
+        name_into(&n->props->key, key, sizeof key);
+        snprintf(msg, sizeof msg, "project '%s' has unexpected property "
+                 "'%s'", name, key);
+        e = err_at_owned(n->props->key.span, msg);
+        goto done;
+    }
+    if (n->children != NULL) {
+        snprintf(msg, sizeof msg, "project '%s' takes no children", name);
+        e = err_at_owned(n->children->name.span, msg);
+        goto done;
+    }
+    e = NULL;
+done:
+    free(name_str);
+    free(ver_str);
+    return e;
+}
+
+/* One `src "<file>"` or `feature "<name>"` child of a target: exactly one
+ * non-empty string argument, no properties, no children. */
+static struct st_error *
+validate_target_child(const struct st_kdl_node *c, const char *ctx,
+                      bool is_src)
+{
+    const char *kind = is_src ? "src" : "feature";
+    const char *slot = is_src ? "file" : "name";
+    char cctx[192];
+    char msg[192];
+
+    if (c->args == NULL) {
+        snprintf(msg, sizeof msg, "%s '%s' requires a %s argument", ctx,
+                 kind, slot);
+        return err_at_owned(c->name.span, msg);
+    }
+    if (c->args->next != NULL) {
+        snprintf(msg, sizeof msg, "%s '%s' takes exactly one argument",
+                 ctx, kind);
+        return err_at_owned(c->args->next->value.span, msg);
+    }
+    if (c->props != NULL) {
+        snprintf(msg, sizeof msg, "%s '%s' takes no properties", ctx, kind);
+        return err_at_owned(c->props->key.span, msg);
+    }
+    if (c->children != NULL) {
+        snprintf(msg, sizeof msg, "%s '%s' takes no children", ctx, kind);
+        return err_at_owned(c->children->name.span, msg);
+    }
+    {
+        char *tmp = NULL;
+        struct st_error *e;
+
+        snprintf(cctx, sizeof cctx, "%s '%s' %s", ctx, kind, slot);
+        e = require_string_arg(&c->args->value, c->args->annotation, cctx,
+                               &tmp);
+        free(tmp);
+        return e;
+    }
+}
+
+/* target "name" { src ...; feature ...; }: the name shape plus a children
+ * block whose nodes are only `src` (a file) or `feature` (a reference to
+ * a top-level feature by name). Presence-checking the reference against
+ * the document is OPTIONAL for this todo - only the shape is enforced. */
+static struct st_error *
+validate_target(const struct st_kdl_node *n)
+{
+    char msg[256];
+    char name[65];
+    char ctx[96];
+    struct st_error *e;
+    char *name_str = NULL;
+    struct st_kdl_node *c;
+
+    e = one_name_arg(n, "target", &name_str);
+    if (e != NULL) {
+        return e;
+    }
+    name_into(&n->args->value, name, sizeof name);
+
+    if (n->props != NULL) {
+        char key[65];
+
+        name_into(&n->props->key, key, sizeof key);
+        snprintf(msg, sizeof msg, "target '%s' has unexpected property "
+                 "'%s'", name, key);
+        e = err_at_owned(n->props->key.span, msg);
+        goto done;
+    }
+
+    snprintf(ctx, sizeof ctx, "target '%s'", name);
+    for (c = n->children; c != NULL; c = c->next) {
+        bool is_src = false;
+        bool is_feat = false;
+
+        e = name_equals(&c->name, "src", &is_src);
+        if (e != NULL) {
+            goto done;
+        }
+        e = name_equals(&c->name, "feature", &is_feat);
+        if (e != NULL) {
+            goto done;
+        }
+        if (is_src || is_feat) {
+            e = validate_target_child(c, ctx, is_src);
+            if (e != NULL) {
+                goto done;
+            }
+            continue;
+        }
+        {
+            char cname[65];
+
+            name_into(&c->name, cname, sizeof cname);
+            snprintf(msg, sizeof msg,
+                "%s has unknown child node '%s' (expected 'src' or "
+                "'feature')", ctx, cname);
+            e = err_at_owned(c->name.span, msg);
+            goto done;
+        }
+    }
+    e = NULL;
+done:
+    free(name_str);
+    return e;
+}
+
+/* One check child of a feature: its kind has already been resolved by
+ * the registry (st_check_kind_from_node). Enforce the kind's DSL shape
+ * from the registry table - the required positional argument (a
+ * non-empty unannotated string), at most the kind's optional arguments
+ * (for library/pkg_config: the literal `version` keyword followed by a
+ * non-empty unannotated constraint string, mirroring the project
+ * node's spelling), no properties, and no children. */
+static struct st_error *
+validate_check(const struct st_kdl_node *c, enum st_check_kind kind,
+               const char *feature)
+{
+    const struct st_check_shape *shape = st_check_kind_shape(kind);
+    char msg[384];
+    char cname[65];
+    char cctx[192];
+    struct st_error *e;
+    struct st_kdl_arg *a;
+    size_t nargs = 1;
+    size_t max_args;
+    size_t i;
+    char *tmp = NULL;
+
+    name_into(&c->name, cname, sizeof cname);
+
+    if (c->args == NULL) {
+        snprintf(msg, sizeof msg,
+            "feature '%s': check '%s' requires an argument (the %s)",
+            feature, cname, shape->arg_meaning);
+        return err_at_owned(c->name.span, msg);
+    }
+    for (a = c->args->next; a != NULL; a = a->next) {
+        nargs++;
+    }
+    max_args = shape->required_args + shape->optional_args;
+    if (nargs > max_args) {
+        /* span the first argument beyond the kind's shape */
+        a = c->args;
+        for (i = 0; i < max_args; i++) {
+            a = a->next;
+        }
+        if (shape->optional_args == 0) {
+            snprintf(msg, sizeof msg,
+                "feature '%s': check '%s' takes exactly one argument",
+                feature, cname);
+        } else {
+            snprintf(msg, sizeof msg,
+                "feature '%s': check '%s' takes at most three arguments "
+                "(the %s, then the optional 'version' keyword and its "
+                "constraint)", feature, cname, shape->arg_meaning);
+        }
+        return err_at_owned(a->value.span, msg);
+    }
+    snprintf(cctx, sizeof cctx, "feature '%s': check '%s' argument",
+             feature, cname);
+    e = require_string_arg(&c->args->value, c->args->annotation, cctx,
+                           &tmp);
+    free(tmp);
+    if (e != NULL) {
+        return e;
+    }
+    if (shape->optional_args == 2) {
+        a = c->args->next;
+        if (a != NULL) {
+            if (a->annotation != NULL ||
+                !(a->value.kind == ST_TOK_IDENT && a->value.len == 7 &&
+                  memcmp(a->value.text, "version", 7) == 0)) {
+                snprintf(msg, sizeof msg,
+                    "feature '%s': check '%s': expected the keyword "
+                    "'version' as the second argument", feature, cname);
+                return err_at_owned(a->value.span, msg);
+            }
+            if (a->next == NULL) {
+                snprintf(msg, sizeof msg,
+                    "feature '%s': check '%s': 'version' requires the "
+                    "version constraint argument", feature, cname);
+                return err_at_owned(a->value.span, msg);
+            }
+            {
+                char vctx[192];
+
+                snprintf(vctx, sizeof vctx,
+                         "feature '%s': check '%s' version", feature,
+                         cname);
+                e = require_string_arg(&a->next->value,
+                                       a->next->annotation, vctx, &tmp);
+                free(tmp);
+                if (e != NULL) {
+                    return e;
+                }
+            }
+        }
+    }
+    if (c->props != NULL) {
+        char key[65];
+
+        name_into(&c->props->key, key, sizeof key);
+        snprintf(msg, sizeof msg,
+            "feature '%s': check '%s' has unexpected property '%s' "
+            "(checks take no properties)", feature, cname, key);
+        return err_at_owned(c->props->key.span, msg);
+    }
+    if (c->children != NULL) {
+        snprintf(msg, sizeof msg,
+            "feature '%s': check '%s' takes no children", feature, cname);
+        return err_at_owned(c->children->name.span, msg);
+    }
+    return NULL;
+}
+
+/* feature "name" when="<expr>" { <checks> }: the name shape plus an
+ * OPTIONAL `when` property (todo 14's guard placement, spelled
+ * `feature "pthread" when="os=linux" { ... }` — a KDL key=value property,
+ * value = a non-empty unannotated string; the guard STRING is parsed by
+ * src/detect/resolve.c, not here) and a children block of CHECK nodes.
+ * Each child's NAME is dispatched through the feature-check registry
+ * (src/detect/check_registry.h, todo 10) to one of the 8 kinds - header,
+ * function, library, type, sizeof, program, compiler_flag, pkg_config -
+ * and its argument/property shape is enforced from the registry table
+ * (see validate_check). Any property other than `when` is rejected. */
+static struct st_error *
+validate_feature(const struct st_kdl_node *n)
+{
+    char name[65];
+    struct st_error *e;
+    char *name_str = NULL;
+    struct st_kdl_node *c;
+    struct st_kdl_prop *p;
+    bool seen_when = false;
+
+    e = one_name_arg(n, "feature", &name_str);
+    if (e != NULL) {
+        return e;
+    }
+    name_into(&n->args->value, name, sizeof name);
+
+    for (p = n->props; p != NULL; p = p->next) {
+        bool is_when = false;
+        char key[65];
+        char msg[192];
+
+        name_into(&p->key, key, sizeof key);
+        e = name_equals(&p->key, "when", &is_when);
+        if (e != NULL) {
+            goto done;
+        }
+        if (!is_when) {
+            snprintf(msg, sizeof msg, "feature '%s' has unexpected "
+                     "property '%s'", name, key);
+            e = err_at_owned(p->key.span, msg);
+            goto done;
+        }
+        if (seen_when) {
+            snprintf(msg, sizeof msg, "feature '%s' has a duplicate 'when' "
+                     "property", name);
+            e = err_at_owned(p->key.span, msg);
+            goto done;
+        }
+        seen_when = true;
+        {
+            char cctx[192];
+            char *tmp = NULL;
+
+            snprintf(cctx, sizeof cctx, "feature '%s': 'when'", name);
+            e = require_string_arg(&p->value, p->annotation, cctx, &tmp);
+            free(tmp);
+            if (e != NULL) {
+                goto done;
+            }
+        }
+    }
+
+    for (c = n->children; c != NULL; c = c->next) {
+        /*
+         * HOOK (todo 10): dispatch the check node NAME through the
+         * feature-check registry (src/detect/check_registry.h) to
+         * validate the 8 kinds - header, function, library, type,
+         * sizeof, program, compiler_flag, pkg_config - and their
+         * argument/property shapes.
+         */
+        enum st_check_kind kind;
+        struct st_error *ke = NULL;
+
+        kind = st_check_kind_from_node(c, &ke);
+        if (ke != NULL) {
+            e = ke;
+            goto done;
+        }
+        e = validate_check(c, kind, name);
+        if (e != NULL) {
+            goto done;
+        }
+    }
+    e = NULL;
+done:
+    free(name_str);
+    return e;
+}
+
+/* option "name" (default=<bool>)?: the name shape, no children, and at
+ * most one `default` property whose value must be an unannotated boolean
+ * (#true/#false) once interpreted through the value model. */
+static struct st_error *
+validate_option(const struct st_kdl_node *n)
+{
+    char msg[256];
+    char name[65];
+    struct st_error *e;
+    char *name_str = NULL;
+    struct st_kdl_prop *p;
+    bool seen_default = false;
+
+    e = one_name_arg(n, "option", &name_str);
+    if (e != NULL) {
+        return e;
+    }
+    name_into(&n->args->value, name, sizeof name);
+
+    if (n->children != NULL) {
+        snprintf(msg, sizeof msg, "option '%s' takes no children", name);
+        e = err_at_owned(n->children->name.span, msg);
+        goto done;
+    }
+
+    for (p = n->props; p != NULL; p = p->next) {
+        bool is_def = false;
+
+        e = name_equals(&p->key, "default", &is_def);
+        if (e != NULL) {
+            goto done;
+        }
+        if (!is_def) {
+            char key[65];
+
+            name_into(&p->key, key, sizeof key);
+            snprintf(msg, sizeof msg,
+                "option '%s' has unexpected property '%s' (only 'default' "
+                "is allowed)", name, key);
+            e = err_at_owned(p->key.span, msg);
+            goto done;
+        }
+        if (seen_default) {
+            snprintf(msg, sizeof msg,
+                "option '%s' has a duplicate 'default' property", name);
+            e = err_at_owned(p->key.span, msg);
+            goto done;
+        }
+        seen_default = true;
+        {
+            struct st_kdl_value v;
+
+            e = value_interpret(&p->value, p->annotation, &v);
+            if (e != NULL) {
+                goto done;
+            }
+            if (v.annotation != NULL) {
+                snprintf(msg, sizeof msg,
+                    "option '%s': 'default' must not carry a type "
+                    "annotation", name);
+                e = err_at_owned(p->value.span, msg);
+                st_kdl_value_free(&v);
+                goto done;
+            }
+            if (v.kind != ST_KDL_VAL_BOOL) {
+                snprintf(msg, sizeof msg,
+                    "option '%s': 'default' must be a boolean (got %s)",
+                    name, st_kdl_value_kind_name(v.kind));
+                e = err_at_owned(p->value.span, msg);
+                st_kdl_value_free(&v);
+                goto done;
+            }
+            st_kdl_value_free(&v);
+        }
+    }
+    e = NULL;
+done:
+    free(name_str);
+    return e;
+}
+
+/* ---- top level -------------------------------------------------------- */
+
+/* Classify a top-level node name. */
+enum top_kind {
+    TOP_PROJECT = 0,
+    TOP_TARGET,
+    TOP_FEATURE,
+    TOP_OPTION,
+    TOP_UNKNOWN,
+};
+
+static struct st_error *
+classify_top(const struct st_kdl_node *n, enum top_kind *out)
+{
+    static const char *const names[] = { "project", "target", "feature",
+                                         "option" };
+    static const enum top_kind kinds[] = { TOP_PROJECT, TOP_TARGET,
+                                           TOP_FEATURE, TOP_OPTION };
+    size_t i;
+
+    for (i = 0; i < sizeof(names) / sizeof(names[0]); i++) {
+        bool eq = false;
+        struct st_error *e = name_equals(&n->name, names[i], &eq);
+
+        if (e != NULL) {
+            return e;
+        }
+        if (eq) {
+            *out = kinds[i];
+            return NULL;
+        }
+    }
+    *out = TOP_UNKNOWN;
+    return NULL;
+}
+
+/* ---- public API ------------------------------------------------------- */
+
+struct st_error *
+st_kdl_validate(const struct st_kdl_document *doc)
+{
+    struct st_kdl_node *n;
+    bool saw_goal = false; /* saw at least one target or feature */
+    struct st_error *e;
+
+    if (doc == NULL || doc->nodes == NULL) {
+        /* No source position (or file name) exists to point at. */
+        return st_error_kdl_schema("missing required 'project' node");
+    }
+
+    n = doc->nodes;
+    {
+        enum top_kind kind;
+
+        e = classify_top(n, &kind);
+        if (e != NULL) {
+            return e;
+        }
+        if (kind != TOP_PROJECT) {
+            char nm[65];
+            char msg[192];
+
+            name_into(&n->name, nm, sizeof nm);
+            snprintf(msg, sizeof msg,
+                "expected 'project' as the first top-level node, got '%s'",
+                nm);
+            return err_at_owned(n->name.span, msg);
+        }
+        e = validate_project(n);
+        if (e != NULL) {
+            return e;
+        }
+    }
+
+    for (n = n->next; n != NULL; n = n->next) {
+        enum top_kind kind;
+
+        e = classify_top(n, &kind);
+        if (e != NULL) {
+            return e;
+        }
+        switch (kind) {
+        case TOP_PROJECT:
+            return err_at_owned(n->name.span, "duplicate 'project' node");
+        case TOP_TARGET:
+            e = validate_target(n);
+            if (e != NULL) {
+                return e;
+            }
+            saw_goal = true;
+            break;
+        case TOP_FEATURE:
+            e = validate_feature(n);
+            if (e != NULL) {
+                return e;
+            }
+            saw_goal = true;
+            break;
+        case TOP_OPTION:
+            e = validate_option(n);
+            if (e != NULL) {
+                return e;
+            }
+            break;
+        case TOP_UNKNOWN: {
+            char nm[65];
+            char msg[192];
+
+            name_into(&n->name, nm, sizeof nm);
+            snprintf(msg, sizeof msg,
+                "unknown top-level node '%s' (expected 'target', "
+                "'feature', or 'option')", nm);
+            return err_at_owned(n->name.span, msg);
+        }
+        }
+    }
+
+    if (!saw_goal) {
+        return err_at_owned(doc->nodes->name.span,
+            "missing 'target' or 'feature' node after 'project'");
+    }
+    return NULL;
+}

src/kdl/schema.h

@@ -0,0 +1,63 @@
+/*
+ * schema.h - stupidtools DSL schema validation (todo 9).
+ *
+ * st_kdl_validate() checks a parsed document (src/kdl/ast.h) against the
+ * stupidtools build-file DSL - a KDL subset. THE GRAMMAR PINNED HERE IS THE
+ * CONTRACT consumed by todo 10 (feature-check registry), todo 16 (configure
+ * generation) and todo 23 (self-host). Change it only deliberately:
+ *
+ *   document := project (target | feature | option)*      project FIRST
+ *   project  := 'project' <name> version <semver>
+ *   target   := 'target' <name> '{' (src | feature)* '}'
+ *   src      := 'src' <file>
+ *   featref  := 'feature' <name>       (name of a top-level feature)
+ *   feature  := 'feature' <name> '{' check* '}'
+ *   check    := <name> <arg> props*    STRUCTURAL ONLY until todo 10
+ *   option   := 'option' <name> (default '=' <bool>)?
+ *
+ * <name>/<file>/<arg>/<semver> are KDL strings (identifier or any quoted/
+ * raw/multi-line form), all required to be NON-EMPTY and unannotated;
+ * <bool> is an unannotated #true/#false. At least one target or feature
+ * must follow the project node.
+ *
+ * PINNED DECISIONS (deliberate; the plan's shorthand left these open):
+ *   - project version syntax: `project "p" version "1.0.0"` - the version
+ *     is the argument AFTER the literal `version` keyword (a bare
+ *     identifier). The property form `version="..."` is NOT accepted.
+ *   - option default: an optional `default` PROPERTY (`option "x"
+ *     default=#true`), not a child node.
+ *   - feature children are validated structurally only: at least one
+ *     non-empty string argument, no children, arbitrary properties. The
+ *     8 check kinds (header/function/library/type/sizeof/program/
+ *     compiler_flag/pkg_config) and their exact argument/property shapes
+ *     are todo 10's job - see the marked HOOK in schema.c.
+ *   - the semver FORMAT is not checked (any non-empty string is accepted).
+ *   - duplicate NAMES among target/feature/option are not checked
+ *     (deferred to the generation todos; duplicate project IS rejected).
+ *
+ * ERRORS
+ * ------
+ * Returns NULL on success, or an owned st_error (ST_ERR_KDL_SCHEMA) whose
+ * span is heap-allocated IN THE SAME BLOCK as the error (the parser.c
+ * pattern), so err->span stays valid until st_error_free(err). The one
+ * span-less case: an empty (or NULL) document, where no source position or
+ * file name exists to point at.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef ST_KDL_SCHEMA_H
+#define ST_KDL_SCHEMA_H
+
+#include "ast.h" /* struct st_kdl_document */
+
+struct st_error;
+
+/* Validate a parsed document against the stupidtools DSL (grammar above).
+ * Returns NULL on success; on failure returns an owned ST_ERR_KDL_SCHEMA
+ * error naming the offending node. The document is only read - never
+ * modified and never freed. */
+struct st_error *st_kdl_validate(const struct st_kdl_document *doc);
+
+#endif /* ST_KDL_SCHEMA_H */

src/kdl/value.h

@@ -0,0 +1,126 @@
+/*
+ * value.h - typed KDL value model for stupidtools (todo 8).
+ *
+ * The parser (todo 7) produces RAW token references (src/kdl/ast.h); this
+ * module INTERPRETS them into typed values. A KDL value is one of:
+ *
+ *   - string  (identifier, quoted, raw, or multi-line; escapes resolved)
+ *   - integer (i64) and unsigned (u64) — numbers without a decimal point
+ *   - float   (f64) — numbers with a fraction/exponent, plus #inf/#-inf/#nan
+ *   - bool    (#true / #false)
+ *   - null    (#null)
+ *
+ * plus an optional type-annotation string (KDL §3.8), e.g. the `u8` in
+ * `(u8)42`, captured into `annotation` (an owned NUL-terminated copy, or
+ * NULL when the value was not annotated).
+ *
+ * SUBSET (documented deviation from KDL 2.0.0)
+ * --------------------------------------------
+ * KDL reserves the integer-width annotations i8/i16/i32/i64/isize and
+ * u8/u16/u32/u64/usize (plus i128/u128) and the float annotations f32/f64.
+ * This tool's value model supports at most 64-bit integers: an `i128` or
+ * `u128` annotation yields a clear "unsupported width" error
+ * (ST_ERR_KDL_PARSE) instead of a value. The `u*` annotations select the
+ * unsigned (u64) interpretation; `i*` the signed (i64) one; `f32`/`f64`
+ * the float interpretation. Any other annotation is captured verbatim and
+ * leaves the literal's natural interpretation unchanged (the DSL schema,
+ * todo 9, is responsible for rejecting application-invalid annotations).
+ *
+ * NUMBER INTERPRETATION (KDL §3.14)
+ * ---------------------------------
+ * Radix prefixes 0x/0o/0b (case-insensitive) and decimal; underscores
+ * allowed between/after digits; optional leading +/-. A literal with a
+ * decimal point or exponent is a float; otherwise an integer. Integers
+ * overflow-check to i64 (default) or u64 (u*-annotated) and produce a
+ * spanned error on overflow. #inf/#-inf/#nan map to INFINITY/-INFINITY/NAN
+ * (math.h macros; no libm linkage is required).
+ *
+ * STRING UNESCAPING (KDL §3.9/3.11/3.12)
+ * --------------------------------------
+ * Quoted and multi-line strings resolve the KDL escapes (\n \r \t \\ \" \b
+ * \f \s \u{...}) plus the lenient extras \' \a \v \xHH \U{...} (harmless
+ * superset; the lexer already rejects non-KDL escapes, so these only matter
+ * for directly-constructed token refs). A backslash followed by literal
+ * whitespace/newline is a whitespace escape and vanishes. Unknown escapes,
+ * a lone trailing backslash, and non-scalar-value unicode escapes are
+ * spanned errors. Multi-line strings additionally remove the leading
+ * newline and dedent by the closing line's whitespace (see value.c for the
+ * exact rule and its documented simplifications). `\0` is REJECTED: KDL
+ * forbids U+0000 and our value is a NUL-terminated C string, so a NUL byte
+ * cannot be represented.
+ *
+ * OWNERSHIP
+ * ---------
+ * st_kdl_value_from_token() writes into a caller-provided `struct
+ * st_kdl_value`; the string payload and the annotation are heap-allocated
+ * by this module and released by st_kdl_value_free() (NULL is a safe no-op;
+ * it also frees nothing for non-string kinds). The token ref's text slice
+ * remains borrowed.
+ *
+ * ERRORS
+ * ------
+ * All failures return an owned st_error of category ST_ERR_KDL_PARSE whose
+ * span is heap-allocated in the same block as the error (the parser.c
+ * pattern), so err->span stays valid until st_error_free(err). On error the
+ * output value is left zeroed (kind ST_KDL_VAL_NULL) and nothing leaks.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef ST_KDL_VALUE_H
+#define ST_KDL_VALUE_H
+
+#include <stdbool.h>
+#include <stddef.h>
+
+#include "ast.h" /* struct st_kdl_token_ref */
+
+struct st_error;
+
+/* The tagged kinds a KDL value can take. */
+enum st_kdl_value_kind {
+    ST_KDL_VAL_STRING = 0, /* as.str (owned, NUL-terminated) */
+    ST_KDL_VAL_INT,        /* as.i  (i64) */
+    ST_KDL_VAL_UINT,       /* as.u  (u64) */
+    ST_KDL_VAL_FLOAT,      /* as.f  (f64) */
+    ST_KDL_VAL_BOOL,       /* as.b  */
+    ST_KDL_VAL_NULL,       /* no payload */
+};
+
+/* A typed KDL value. `annotation` is an owned NUL-terminated copy of the
+ * type-annotation identifier, or NULL when the value was not annotated. */
+struct st_kdl_value {
+    enum st_kdl_value_kind kind;
+    union {
+        char *str;              /* STRING: owned, NUL-terminated */
+        long long i;            /* INT */
+        unsigned long long u;   /* UINT */
+        double f;               /* FLOAT */
+        bool b;                 /* BOOL */
+    } as;
+    char *annotation;           /* owned; may be NULL */
+};
+
+/* Interpret a raw value token ref into `out` (no type annotation). On
+ * success returns NULL and `out` is fully populated; on failure returns an
+ * owned error and `out` is left zeroed. */
+struct st_error *st_kdl_value_from_token(const struct st_kdl_token_ref *tok,
+                                         struct st_kdl_value *out);
+
+/* Same, but with an explicit type-annotation ref (ST_TOK_TYPE) captured
+ * into `out->annotation`. `annotation` may be NULL. */
+struct st_error *st_kdl_value_from_token_annotated(
+    const struct st_kdl_token_ref *tok,
+    const struct st_kdl_token_ref *annotation,
+    struct st_kdl_value *out);
+
+/* Release the payloads owned by `v` (string + annotation). NULL is a safe
+ * no-op. */
+void st_kdl_value_free(struct st_kdl_value *v);
+
+/* Stable display name for a value kind, e.g. "string". Unknown kinds yield
+ * "?" rather than indexing out of range. */
+const char *st_kdl_value_kind_name(enum st_kdl_value_kind kind);
+
+#endif /* ST_KDL_VALUE_H */

src/main.c

@@ -0,0 +1,240 @@
+/*
+ * stupidtools - the GNU AutoTools replacement for the moronic.
+ *
+ * Copyright (c) 2026 huntedbytheirs
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ * Entrypoint. Parses argv via cli.c, then runs the full pipeline for a
+ * single buildfile:
+ *
+ *   1. read the buildfile (argv[1]) into memory;
+ *   2. parse it (st_kdl_parse) and validate it against the DSL
+ *      (st_kdl_validate);
+ *   3. build the extension context + sandboxed Lua runtime, discover
+ *      every extension (builtin C modules first, then --ext-dir /
+ *      STUPIDTOOLS_EXT / the user dir / the builtin dir -- see
+ *      ext/discovery.h), flush Lua registrations into the ctx
+ *      (st_ext_bridge_lua), and detect the C toolchain
+ *      (st_ext_detect_language(ctx, "c"));
+ *   4. emit ./configure (st_gen_configure_emit_path) into the current
+ *      working directory -- the generated script reads ./Makefile.in
+ *      and writes ./Makefile there at configure time (the v1 source-dir
+ *      contract, see gen/configure.h);
+ *   5. print a one-line summary and exit 0.
+ *
+ * Any failure prints its diagnostic via st_error_print to stderr and
+ * exits 1 (runtime error); CLI usage errors exit 2 (see cli.h). Only
+ * main.c exits; every library path returns an error.
+ */
+
+#include "cli.h"
+
+#include "error.h"
+#include "ext/abi.h"
+#include "ext/api.h"
+#include "ext/discovery.h"
+#include "ext/lua.h"
+#include "gen/configure.h"
+#include "kdl/ast.h"
+#include "kdl/schema.h"
+
+#include <errno.h>
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* Discovery's log sink: route the "loaded extension: ..." lines to
+ * stdout so scripts can grep them cleanly. */
+static void
+stdout_log(const char *fmt, va_list ap)
+{
+	vfprintf(stdout, fmt, ap);
+}
+
+/* Reads the whole of `path` into a freshly malloc'd NUL-terminated
+ * buffer (owned by the caller). Returns NULL on success; an owned
+ * ST_ERR_IO error naming the file on failure (unreadable file or OOM).
+ * The read uses rb so embedded NULs don't truncate the parse. */
+static struct st_error *
+read_file(const char *path, char **out)
+{
+	FILE *f;
+	long size;
+	char *buf;
+	size_t got;
+	size_t need;
+	struct st_error *err;
+
+	f = fopen(path, "rb");
+	if (f == NULL) {
+		need = strlen(path) + 64;
+		buf = malloc(need);
+		if (buf == NULL)
+			return st_error_internal("out of memory");
+		(void)snprintf(buf, need, "cannot read build file '%s': %s",
+		    path, strerror(errno));
+		err = st_error_io(buf);
+		free(buf);
+		return err;
+	}
+	if (fseek(f, 0, SEEK_END) != 0) {
+		(void)fclose(f);
+		need = strlen(path) + 64;
+		buf = malloc(need);
+		if (buf == NULL)
+			return st_error_internal("out of memory");
+		(void)snprintf(buf, need, "cannot read build file '%s': %s",
+		    path, strerror(errno));
+		err = st_error_io(buf);
+		free(buf);
+		return err;
+	}
+	size = ftell(f);
+	if (size < 0 || fseek(f, 0, SEEK_SET) != 0) {
+		(void)fclose(f);
+		need = strlen(path) + 64;
+		buf = malloc(need);
+		if (buf == NULL)
+			return st_error_internal("out of memory");
+		(void)snprintf(buf, need, "cannot read build file '%s': %s",
+		    path, strerror(errno));
+		err = st_error_io(buf);
+		free(buf);
+		return err;
+	}
+	buf = malloc((size_t)size + 1);
+	if (buf == NULL) {
+		(void)fclose(f);
+		return st_error_internal("out of memory");
+	}
+	got = fread(buf, 1, (size_t)size, f);
+	if (got != (size_t)size) {
+		/* short read: close BEFORE the error return (no leak) */
+		(void)fclose(f);
+		free(buf);
+		need = strlen(path) + 64;
+		buf = malloc(need);
+		if (buf == NULL)
+			return st_error_internal("out of memory");
+		(void)snprintf(buf, need, "cannot read build file '%s': %s",
+		    path, strerror(errno));
+		err = st_error_io(buf);
+		free(buf);
+		return err;
+	}
+	if (fclose(f) != 0) {
+		free(buf);
+		need = strlen(path) + 64;
+		buf = malloc(need);
+		if (buf == NULL)
+			return st_error_internal("out of memory");
+		(void)snprintf(buf, need, "cannot read build file '%s': %s",
+		    path, strerror(errno));
+		err = st_error_io(buf);
+		free(buf);
+		return err;
+	}
+	buf[size] = '\0';
+	*out = buf;
+	return NULL;
+}
+
+int
+main(int argc, char **argv)
+{
+	struct cli_opts opts;
+	enum cli_action action;
+	struct st_error *err = NULL;
+	char *src = NULL;
+	struct st_kdl_document *doc = NULL;
+	struct st_ext_ctx *ctx = NULL;
+	struct st_lua_rt *rt = NULL;
+	int rc = CLI_EXIT_RUNTIME;
+
+	action = cli_parse(argc, argv, &opts);
+
+	switch (action) {
+	case CLI_ACTION_HELP:
+		return CLI_EXIT_OK;
+	case CLI_ACTION_VERSION:
+		printf("stupidtools %s\n", STUPIDTOOLS_VERSION);
+		return CLI_EXIT_OK;
+	case CLI_ACTION_ERROR:
+		return CLI_EXIT_USAGE;
+	case CLI_ACTION_RUN:
+		break;
+	}
+
+	if (opts.buildfile == NULL) {
+		fprintf(stderr, "%s: error: no build file given\n",
+		    opts.program);
+		cli_print_usage(stderr, opts.program);
+		return CLI_EXIT_RUNTIME;
+	}
+
+	/* 1. read the buildfile. */
+	err = read_file(opts.buildfile, &src);
+	if (err != NULL)
+		goto fail;
+
+	/* 2. parse + validate. `src` must outlive the document (the AST
+	 * borrows its token slices), so it is freed last. */
+	doc = st_kdl_parse(src, opts.buildfile, &err);
+	if (doc == NULL)
+		goto fail;
+
+	err = st_kdl_validate(doc);
+	if (err != NULL)
+		goto fail;
+
+	/* 3. extensions + toolchain. Discovery runs the builtin modules
+	 * itself (st_ext_init_builtins), so we never call it here. */
+	ctx = st_ext_ctx_new();
+	rt = st_lua_rt_new();
+	if (ctx == NULL || rt == NULL) {
+		err = st_error_internal("out of memory");
+		goto fail;
+	}
+
+	st_ext_discover_set_log(stdout_log);
+	err = st_ext_discover(ctx, rt, opts.ext_dirs, opts.ext_dir_count);
+	if (err != NULL)
+		goto fail;
+
+	err = st_ext_bridge_lua(ctx, rt);
+	if (err != NULL)
+		goto fail;
+
+	err = st_ext_detect_language(ctx, "c");
+	if (err != NULL)
+		goto fail;
+
+	/* 4. emit ./configure into the current working directory. */
+	err = st_gen_configure_emit_path("configure", doc, ctx);
+	if (err != NULL)
+		goto fail;
+
+	/* 5. summary. */
+	{
+		const char *cc = st_registry_get_var(st_ext_var_registry(ctx),
+		    "CC");
+
+		if (cc != NULL)
+			printf("wrote ./configure (CC=%s)\n", cc);
+		else
+			printf("wrote ./configure\n");
+	}
+	rc = CLI_EXIT_OK;
+
+fail:
+	if (err != NULL) {
+		st_error_print(stderr, err);
+		st_error_free(err);
+	}
+	st_lua_rt_free(rt);
+	st_ext_ctx_free(ctx);
+	st_kdl_document_free(doc);
+	free(src);
+	return rc;
+}

src/span.c

@@ -0,0 +1,33 @@
+#include "span.h"
+
+/* C23 only: ISO/IEC 9899:2024. */
+#define ST_SPAN_CARET_PAD_CAP 60
+
+void
+st_span_print(FILE *out, const struct st_span *span, const char *message)
+{
+    size_t pad;
+
+    if (out == NULL || span == NULL || span->file == NULL ||
+        message == NULL) {
+        return;
+    }
+    fprintf(out, "%s:%zu:%zu: %s\n", span->file, span->line, span->col,
+            message);
+    /*
+     * Caret line: 4-space indent, "..." elision, caret. The caret sits
+     * three cells past the reported column (the elision marker occupies
+     * those cells), so col 5 renders exactly "    ...^". Columns below
+     * 5 collapse onto the elision; columns above 5 push the caret right,
+     * capped to keep the line bounded.
+     */
+    fputs("    ...", out);
+    pad = span->col > 5 ? span->col - 5 : 0;
+    if (pad > ST_SPAN_CARET_PAD_CAP) {
+        pad = ST_SPAN_CARET_PAD_CAP;
+    }
+    while (pad-- > 0) {
+        fputc(' ', out);
+    }
+    fputs("^\n", out);
+}

src/span.h

@@ -0,0 +1,33 @@
+#ifndef ST_SPAN_H
+#define ST_SPAN_H
+
+#include <stddef.h>
+#include <stdio.h>
+
+/*
+ * A source span: 1-based line/column into a source file.
+ * `file` is borrowed (never freed); typically points into stable
+ * storage such as a file-name arena or a string literal.
+ */
+struct st_span {
+    const char *file;
+    size_t line;
+    size_t col;
+};
+
+/*
+ * Renders the canonical two-line diagnostic:
+ *
+ *   <file>:<line>:<col>: <message>
+ *       ...^
+ *
+ * The caret line is a fixed 4-space indent followed by a "..."
+ * elision marker and the caret. For the canonical span (col 5)
+ * this is exactly "    ...^"; the caret shifts right for larger
+ * columns and is capped so hostile spans cannot force unbounded
+ * output. NULL arguments are tolerated and render nothing.
+ */
+void st_span_print(FILE *out, const struct st_span *span,
+                   const char *message);
+
+#endif

stupid.kdl

@@ -0,0 +1,79 @@
+/* stupid.kdl - stupidtools' OWN build file (todo 23: self-host).
+ *
+ * The project describes itself in its own DSL. This is a sibling of
+ * tests/fixtures/stupid.kdl (the todo-9 grammar fixture): richer, with the
+ * REAL source list, so `src/stupidtools stupid.kdl` generates a ./configure
+ * that can rebuild the tool end to end. The autotools path (configure.ac +
+ * Makefile.am) remains the bootstrap; this file is what the self-host test
+ * (tests/selfhost.sh) drives.
+ *
+ * DSL grammar (src/kdl/schema.h): `project` first, then targets/features/
+ * options. The `target` source list is descriptive in v1 (the generated
+ * configure substitutes @VAR@ into a user-provided Makefile.in; it does not
+ * generate a Makefile) but lists every translation unit so the self-host
+ * Makefile.in can compile them all. */
+
+project "stupidtools" version "1.0.0"
+
+// The POSIX surface the tool itself relies on (fork/exec/pipe/readdir for
+// detection and discovery). A real check: the generated configure probes
+// unistd.h with the detected C compiler.
+feature "posix" {
+    header "unistd.h"
+}
+
+// The one artifact: every translation unit of the tool, plus the posix
+// feature it needs at build time.
+target "default" {
+    src "src/main.c"
+    src "src/cli.c"
+    src "src/error.c"
+    src "src/span.c"
+    src "src/kdl/lexer.c"
+    src "src/kdl/parser.c"
+    src "src/kdl/value.c"
+    src "src/kdl/schema.c"
+    src "src/detect/check_registry.c"
+    src "src/detect/checks.c"
+    src "src/detect/probe.c"
+    src "src/detect/resolve.c"
+    src "src/gen/sh_emit.c"
+    src "src/gen/configure.c"
+    src "src/gen/config.c"
+    src "src/gen/args.c"
+    src "src/ext/discovery.c"
+    src "src/ext/lua.c"
+    src "src/ext/abi.c"
+    src "src/ext/api.c"
+    src "src/ext/lang_c.c"
+    src "src/ext/lang_cpp.c"
+    src "thirdparty/lua/lapi.c"
+    src "thirdparty/lua/lauxlib.c"
+    src "thirdparty/lua/lbaselib.c"
+    src "thirdparty/lua/lcode.c"
+    src "thirdparty/lua/lctype.c"
+    src "thirdparty/lua/ldebug.c"
+    src "thirdparty/lua/ldo.c"
+    src "thirdparty/lua/ldump.c"
+    src "thirdparty/lua/lfunc.c"
+    src "thirdparty/lua/lgc.c"
+    src "thirdparty/lua/llex.c"
+    src "thirdparty/lua/lmem.c"
+    src "thirdparty/lua/lobject.c"
+    src "thirdparty/lua/lopcodes.c"
+    src "thirdparty/lua/lparser.c"
+    src "thirdparty/lua/lstate.c"
+    src "thirdparty/lua/lstring.c"
+    src "thirdparty/lua/ltable.c"
+    src "thirdparty/lua/ltm.c"
+    src "thirdparty/lua/lundump.c"
+    src "thirdparty/lua/lvm.c"
+    src "thirdparty/lua/lzio.c"
+    src "thirdparty/lua/lstrlib.c"
+    src "thirdparty/lua/ltablib.c"
+    feature "posix"
+}
+
+// --enable-debug / --disable-debug (default off), like configure.ac's
+// release/debug split.
+option "debug" default=#false

tests/fixtures/basic.kdl

@@ -0,0 +1,21 @@
+/* Parser fixture: a realistic multi-node build file exercising node names,
+   arguments, properties, children blocks, comments, a slashdash, and
+   semicolon separators. Parsed by tests/unit/test_parser.c against an
+   exact expected AST (counts, order, nesting, spans). */
+
+// top-level line comment
+project name="stupidtools" version="1.0.0"
+
+target "default" {
+    src "src/main.c" ; src "src/kdl/lexer.c"
+    cc-flags "-std=c23" "-Wall" // pinned warning flags
+    jobs 8
+    optimize #true debug=#false
+    feature "unit-tests" {
+        option "munit" { default #true }
+    }
+}
+
+/-
+
+(meta)credits "huntedbytheirs"

tests/fixtures/stupid.kdl

@@ -0,0 +1,43 @@
+/* stupid.kdl - the canonical stupidtools build file (todo 9 fixture).
+
+   Pins the stupidtools DSL grammar (enforced by src/kdl/schema.h):
+
+     project "name" version "semver"     required, MUST be the first node
+     target "name" { src "file" ... ; feature "name" ... }
+     feature "name" { <checks> }         checks: structural until todo 10
+     option "name" default=#bool         default is an optional bool property
+
+   This is the VALID fixture for tests/unit/test_schema.c and is reused by
+   todo 16 (configure generation) and todo 23 (self-host), so it is
+   representative of a real build file, not a minimal toy. */
+
+// The project node: the name is the first positional argument; the
+// version string follows the literal `version` keyword.
+project "stupidtools" version "1.0.0"
+
+// Features bundle the checks a target depends on. `header` and `library`
+// are two of the 8 check kinds (todo 10 defines them all); here they are
+// structural placeholders.
+feature "pthread" {
+    header "pthread.h"
+    library "pthread"
+}
+
+feature "math" {
+    library "m"
+}
+
+// A target: the sources that make up one artifact, plus the features it
+// needs at build/link time.
+target "default" {
+    src "src/main.c"
+    src "src/cli.c"
+    src "src/kdl/lexer.c"
+    src "src/kdl/parser.c"
+    feature "pthread"
+    feature "math"
+}
+
+// An option maps to --enable-debug / --disable-debug; `default` is an
+// optional boolean property (unannotated #true/#false only).
+option "debug" default=#false

tests/integration/fixture/Makefile.in

@@ -0,0 +1,27 @@
+# Makefile.in - integration-fixture template (plan todo 26).
+#
+# The substitution placeholders are filled by the generated ./configure
+# (they must stay literal here - never expand them in this file). CC and
+# CFLAGS come from the C language module's detection, LIBS from the feature
+# probes' link flags (-lpthread/-lm), prefix from the --prefix default or
+# override.
+#
+# NOTE: the substitution is LINE-BASED and runs on every line, comments
+# included - so no comment may contain a placeholder-shaped token (the
+# configure script would treat it as a variable to substitute).
+#
+# This file is NOT generated by stupidtools: the tool only substitutes
+# placeholders into it (Makefile generation is out of v1 scope by design).
+
+CC = @CC@
+CFLAGS = @CFLAGS@ -std=c23 -Wall -Wextra -Wpedantic
+LIBS = @LIBS@
+prefix = @prefix@
+
+all: demo
+
+demo: main.c demo.c demo.h
+	$(CC) $(CFLAGS) main.c demo.c -o demo $(LIBS)
+
+clean:
+	rm -f demo

tests/integration/fixture/demo.c

@@ -0,0 +1,16 @@
+/*
+ * demo.c - second translation unit of the integration fixture.
+ *
+ * Gives the fixture a real multi-file shape (the header demo.h is part of
+ * the deliverable "sources + headers"). Deliberately libm-free: the only
+ * libm dependency lives in main.c (sin), so a broken -lm accumulation is
+ * caught at LINK time there.
+ */
+
+#include "demo.h"
+
+int
+demo_compute(int x)
+{
+    return x * 3 + 1;
+}

tests/integration/fixture/demo.h

@@ -0,0 +1,10 @@
+/*
+ * demo.h - fixture header, included by main.c and demo.c.
+ */
+
+#ifndef HELLOTHREADS_DEMO_H
+#define HELLOTHREADS_DEMO_H
+
+int demo_compute(int x);
+
+#endif /* HELLOTHREADS_DEMO_H */

tests/integration/fixture/main.c

@@ -0,0 +1,63 @@
+/*
+ * main.c - integration-fixture entry point (plan todo 26).
+ *
+ * A REAL C23 program exercising both fixture features end to end:
+ *   - pthread: pthread_create()/pthread_join() run a worker thread (guarded
+ *     by the HAVE_PTHREAD define the generated config.h wrote), printing a
+ *     grep-able marker the runner asserts on;
+ *   - math: sin(0.5) from libm, printed with a fixed format the runner
+ *     greps (the link would fail without -lm, so a successful run proves
+ *     the LIBS accumulation reached the Makefile).
+ *
+ * _POSIX_C_SOURCE must be defined BEFORE the first include: under strict
+ * -std=c23 glibc sets __STRICT_ANSI__ and hides pthread_create's
+ * declaration, which C23 turns into an implicit-declaration ERROR
+ * (the same trap recorded for src/ in the project learnings).
+ */
+
+#ifndef _POSIX_C_SOURCE
+#define _POSIX_C_SOURCE 200809L
+#endif
+
+#include "config.h"
+#include "demo.h"
+
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+#ifdef HAVE_PTHREAD
+#include <pthread.h>
+
+static void *
+worker(void *arg)
+{
+    (void)arg;
+    printf("worker thread ran\n");
+    return NULL;
+}
+#endif
+
+int
+main(void)
+{
+    double s = sin(0.5);
+
+    printf("hellothreads demo: sin(0.5) = %.4f\n", s);
+    printf("demo_compute(2) = %d\n", demo_compute(2));
+#ifdef HAVE_PTHREAD
+    {
+        pthread_t t;
+
+        if (pthread_create(&t, NULL, worker, NULL) != 0) {
+            fprintf(stderr, "pthread_create failed\n");
+            return EXIT_FAILURE;
+        }
+        if (pthread_join(t, NULL) != 0) {
+            fprintf(stderr, "pthread_join failed\n");
+            return EXIT_FAILURE;
+        }
+    }
+#endif
+    return EXIT_SUCCESS;
+}

tests/integration/fixture/project-fail.kdl

@@ -0,0 +1,37 @@
+/* project-fail.kdl - the FAILURE variant of project.kdl (plan todo 26).
+ *
+ * Same shape as project.kdl, but the pthread feature is replaced by a
+ * feature checking a header that does not exist on any system:
+ *
+ *   feature "nope" { header "nope_missing_xyz.h" }
+ *
+ * The generated ./configure must handle the failed probe CLEANLY under
+ * every shell in the matrix: the failure is recorded (have_nope=no), the
+ * check is named in config.log (the compiler's diagnostic), config.h gets
+ * NO HAVE_NOPE define, and no shell reports a syntax error. A healthy
+ * second feature ("posix", unistd.h) proves configure continues after a
+ * failed check and the healthy feature still resolves.
+ *
+ * NOTE (deviation, tracked in .omo/notepads/stupidtools/issues.md): the
+ * v1 generator (todos 16/17, frozen to todo 26) follows autoconf
+ * semantics - a failed OPTIONAL check records have_<name>=no and
+ * configure still exits 0; it does not abort. The plan/todo text expected
+ * rc!=0 here. run.sh asserts the generator's REAL contract and exercises
+ * the genuinely-non-zero configure-error path via an unrecognized option.
+ */
+
+project "hellothreads-fail" version "1.0.0"
+
+feature "nope" {
+    header "nope_missing_xyz.h"
+}
+
+feature "posix" {
+    header "unistd.h"
+}
+
+target "default" {
+    src "main.c"
+    feature "nope"
+    feature "posix"
+}

tests/integration/fixture/project.kdl

@@ -0,0 +1,39 @@
+/* project.kdl - integration-fixture build file (plan todo 26).
+ *
+ * A small but REAL C project exercising the DSL the way a user would:
+ *   - feature "pthread": a header check (pthread.h) AND a library check
+ *     (pthread -> -lpthread), like the classic autoconf AC_CHECK_HEADER +
+ *     AC_CHECK_LIB pair;
+ *   - feature "math": an optional library check (m -> -lm). Not strictly
+ *     required by every build (an option maps to --enable-math/--disable
+ *     --math), but present so the generated Makefile accumulates -lm
+ *     when it resolves;
+ *   - target "default": the real source list of the fixture (descriptive
+ *     in v1 - the generated configure substitutes @VAR@ into Makefile.in,
+ *     it does not generate Makefiles);
+ *   - option "debug": an option node, proving the --enable-debug /
+ *     --disable-debug surface shows up in the generated --help.
+ *
+ * DSL grammar (src/kdl/schema.h): `project` first, then targets/features/
+ * options; feature children are checks (header/library/... from the 8
+ * registry kinds). */
+
+project "hellothreads" version "1.0.0"
+
+feature "pthread" {
+    header "pthread.h"
+    library "pthread"
+}
+
+feature "math" {
+    library "m"
+}
+
+target "default" {
+    src "main.c"
+    src "demo.c"
+    feature "pthread"
+    feature "math"
+}
+
+option "debug" default=#false

tests/integration/run.sh

@@ -0,0 +1,381 @@
+#!/bin/sh
+# tests/integration/run.sh - end-to-end integration test (plan todo 26).
+#
+# Drives a REAL fixture C project (tests/integration/fixture/) through the
+# full stupidtools pipeline, once per shell in the portability matrix
+# (dash/bash/zsh; sh stands in for dash when dash is not installed):
+#
+#   1. the wired binary ($TOP_DIR/src/stupidtools) generates ./configure
+#      from project.kdl into an isolated temp dir (one dir per shell);
+#   2. that ./configure runs UNDER THE SHELL (any non-POSIX emission dies
+#      as a syntax error right here), writing Makefile/config.h/config.log/
+#      config.status;
+#   3. make builds the fixture binary; assertions verify the build, the
+#      substituted Makefile (CC/CFLAGS/LIBS/prefix), config.h defines,
+#      config.log probe results and config.status --config.
+#
+# A second fixture (project-fail.kdl) checks a deliberately MISSING header:
+# the generated configure must handle the failed probe CLEANLY under every
+# shell - the failure is recorded (have_nope=no), the check is named in
+# config.log (the compiler's diagnostic), config.h gets NO HAVE_NOPE
+# define, and no shell may report a syntax error.
+#
+# NOTE (deviation, tracked in .omo/notepads/stupidtools/issues.md): the v1
+# generator (todos 16/17, frozen to todo 26) follows autoconf semantics -
+# a failed OPTIONAL check records have_<name>=no and configure still exits
+# 0; it does not abort. The plan/todo text expected rc!=0 for a missing
+# header. This runner asserts the generator's REAL contract (rc=0 + the
+# failure recorded), and additionally exercises the genuinely-non-zero
+# configure-error path (an unrecognized option exits 1 with a readable
+# message and no shell syntax error) so BOTH halves of "fails cleanly
+# (non-zero, readable message)" are covered by a real assertion.
+#
+# POSIX sh only (dash/bash/zsh safe): no [[ ]], arrays, local, ==, <<<, &>.
+# Exit 0 = every shell's happy case AND failure case passed.
+
+TOP_DIR=$(cd "$(dirname "$0")/../.." && pwd) || {
+    echo "FAIL: cannot resolve project root" >&2
+    exit 1
+}
+BIN="$TOP_DIR/src/stupidtools"
+FIX="$TOP_DIR/tests/integration/fixture"
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+# temp dirs created by new_work() are recorded in a file list; the trap
+# cleans them on every exit path (a file list + $(cat ...) splits under
+# every POSIX shell AND native zsh, unlike an unquoted variable).
+WORK_LIST="${TMPDIR:-/tmp}/stupidtools-int-worklist.$$"
+: > "$WORK_LIST"
+cleanup_dirs() {
+    [ -s "$WORK_LIST" ] && rm -rf $(cat "$WORK_LIST")
+    rm -f "$WORK_LIST"
+}
+trap cleanup_dirs EXIT HUP INT TERM
+
+pass() {
+    TESTS_RUN=$((TESTS_RUN + 1))
+    printf 'ok %d - %s\n' "$TESTS_RUN" "$1"
+}
+
+fail() {
+    TESTS_RUN=$((TESTS_RUN + 1))
+    TESTS_FAILED=$((TESTS_FAILED + 1))
+    printf 'not ok %d - %s\n' "$TESTS_RUN" "$1" >&2
+}
+
+# new_work: mktemp an isolated dir and record it for trap cleanup.
+new_work() {
+    WORK=$(mktemp -d "${TMPDIR:-/tmp}/stupidtools-int.XXXXXX") || {
+        fail "cannot create temp dir"
+        return 1
+    }
+    printf '%s\n' "$WORK" >> "$WORK_LIST"
+    return 0
+}
+
+# --- preconditions (fail honestly, never silently skip) ------------------
+if [ -x "$BIN" ]; then
+    pass "binary exists and is executable: $BIN"
+else
+    fail "binary missing: $BIN (run 'make' first)"
+fi
+
+for f in project.kdl project-fail.kdl Makefile.in main.c demo.c demo.h; do
+    if [ -f "$FIX/$f" ]; then
+        pass "fixture file present: $f"
+    else
+        fail "fixture file missing: $FIX/$f"
+    fi
+done
+
+# --- the shell matrix -----------------------------------------------------
+# Built as positional parameters and iterated with "$@" - the one portable
+# multi-word construct that behaves identically under POSIX sh AND native
+# zsh (an unquoted variable is NOT word-split in native zsh). dash when
+# available (it now is on this host), else sh as stand-in; the runner
+# prints which one it used - never a silent substitution.
+set --
+if command -v dash >/dev/null 2>&1; then
+    set -- "$@" dash
+    DASH_USED=yes
+else
+    set -- "$@" sh
+    DASH_USED=no
+    printf '# note: dash: unavailable - matrix uses sh instead of dash\n'
+fi
+for cand in bash zsh; do
+    if command -v "$cand" >/dev/null 2>&1; then
+        set -- "$@" "$cand"
+    else
+        fail "required shell not installed: $cand"
+    fi
+done
+SHELLS="$*"
+printf '# shell matrix: %s (dash used: %s)\n' "$SHELLS" "$DASH_USED"
+
+printf '# note: failed-check semantics per the frozen v1 generator: a failed\n'
+printf '#       optional check records have_<name>=no and configure exits 0;\n'
+printf '#       the non-zero configure-error path is asserted via an unknown\n'
+printf '#       option instead (see header + issues.md).\n'
+
+# --- happy case: one shell, one isolated dir ------------------------------
+run_happy() {
+    shell=$1
+
+    new_work || return 1
+    if cp "$FIX/project.kdl" "$FIX/Makefile.in" "$FIX/main.c" "$FIX/demo.c" \
+        "$FIX/demo.h" "$WORK/" \
+        && (cd "$WORK" && XDG_DATA_HOME="$WORK/xdg" STUPIDTOOLS_EXT= \
+            "$BIN" project.kdl >gen.log 2>&1) \
+        && [ -s "$WORK/configure" ]; then
+        pass "$shell: stupidtools generated ./configure from project.kdl"
+    else
+        fail "$shell: configure generation failed: $(cat "$WORK/gen.log" 2>/dev/null)"
+        return 1
+    fi
+
+    # real dash is the strict oracle when it is in the matrix
+    if [ "$shell" = "dash" ]; then
+        if dash -n "$WORK/configure" 2>"$WORK/dashn.err"; then
+            pass "dash: generated ./configure passes dash -n"
+        else
+            fail "dash: generated ./configure fails dash -n: $(cat "$WORK/dashn.err" 2>/dev/null)"
+        fi
+    fi
+
+    # run configure UNDER THE SHELL. CC/CFLAGS/CXX/CXXFLAGS are unset so
+    # the generated ${VAR:-default} toolchain defaults apply (and zsh's
+    # no-word-split on unquoted $CFLAGS cannot be fed a multi-word value).
+    conf_rc=0
+    (cd "$WORK" && unset CC CFLAGS CXX CXXFLAGS
+        "$shell" ./configure --prefix="$WORK/install" \
+            >configure.out 2>configure.err) || conf_rc=$?
+    if [ "$conf_rc" -eq 0 ]; then
+        pass "$shell: ./configure exited 0"
+    else
+        fail "$shell: ./configure exited rc=$conf_rc: $(cat "$WORK/configure.err" 2>/dev/null)"
+    fi
+    if grep -iE 'syntax error|parse error' "$WORK/configure.out" \
+        "$WORK/configure.err" >/dev/null 2>&1; then
+        fail "$shell: configure output carries a shell-syntax-error signature"
+    else
+        pass "$shell: no shell-syntax-error signature in configure output"
+    fi
+
+    # the substituted Makefile: no @VAR@ left, LIBS accumulated, prefix set
+    if [ -f "$WORK/Makefile" ]; then
+        pass "$shell: configure wrote Makefile"
+        if grep -E '@[A-Za-z_][A-Za-z0-9_]*@' "$WORK/Makefile" >/dev/null 2>&1; then
+            fail "$shell: Makefile still contains @VAR@ placeholders"
+        else
+            pass "$shell: no @VAR@ placeholders left in Makefile"
+        fi
+        if grep '^LIBS' "$WORK/Makefile" | grep -q -- '-lpthread'; then
+            pass "$shell: Makefile LIBS contains -lpthread"
+        else
+            fail "$shell: Makefile LIBS missing -lpthread: $(grep '^LIBS' "$WORK/Makefile")"
+        fi
+        if grep '^LIBS' "$WORK/Makefile" | grep -q -- '-lm'; then
+            pass "$shell: Makefile LIBS contains -lm"
+        else
+            fail "$shell: Makefile LIBS missing -lm: $(grep '^LIBS' "$WORK/Makefile")"
+        fi
+        if grep -qF "prefix = $WORK/install" "$WORK/Makefile"; then
+            pass "$shell: Makefile prefix substituted with --prefix value"
+        else
+            fail "$shell: Makefile prefix unexpected: $(grep '^prefix' "$WORK/Makefile")"
+        fi
+    else
+        fail "$shell: configure wrote no Makefile"
+    fi
+
+    # make (bounded via timeout when available)
+    make_rc=0
+    if command -v timeout >/dev/null 2>&1; then
+        (cd "$WORK" && timeout 300 make >make.log 2>&1) || make_rc=$?
+    else
+        (cd "$WORK" && make >make.log 2>&1) || make_rc=$?
+    fi
+    if [ "$make_rc" -eq 0 ] && [ -x "$WORK/demo" ]; then
+        pass "$shell: make built the demo binary"
+    else
+        fail "$shell: make failed (rc=$make_rc): $(tail -n 5 "$WORK/make.log" 2>/dev/null)"
+    fi
+
+    # the binary must RUN and print the markers (pthread + libm proven live)
+    if [ -x "$WORK/demo" ]; then
+        demo_out=$("$WORK/demo" 2>"$WORK/demo.err")
+        demo_rc=$?
+        if [ "$demo_rc" -eq 0 ]; then
+            pass "$shell: demo binary runs (exit 0)"
+        else
+            fail "$shell: demo binary exited rc=$demo_rc: $(cat "$WORK/demo.err" 2>/dev/null)"
+        fi
+        if printf '%s\n' "$demo_out" | grep -qF 'sin(0.5) = 0.4794'; then
+            pass "$shell: demo prints the libm marker 'sin(0.5) = 0.4794'"
+        else
+            fail "$shell: demo output missing libm marker: '$demo_out'"
+        fi
+        if printf '%s\n' "$demo_out" | grep -qF 'worker thread ran'; then
+            pass "$shell: demo prints the pthread marker 'worker thread ran'"
+        else
+            fail "$shell: demo output missing pthread marker: '$demo_out'"
+        fi
+    else
+        fail "$shell: skipping binary checks (no demo binary)"
+    fi
+
+    # config.h: HAVE_ defines for the resolved features
+    if grep -qF '#define HAVE_PTHREAD 1' "$WORK/config.h"; then
+        pass "$shell: config.h defines HAVE_PTHREAD 1"
+    else
+        fail "$shell: config.h missing '#define HAVE_PTHREAD 1': $(cat "$WORK/config.h" 2>/dev/null)"
+    fi
+    if grep -qF '#define HAVE_MATH 1' "$WORK/config.h"; then
+        pass "$shell: config.h defines HAVE_MATH 1"
+    else
+        fail "$shell: config.h missing '#define HAVE_MATH 1'"
+    fi
+
+    # config.log: the ## results summary records every feature's resolution
+    if grep -qF 'have_pthread=yes' "$WORK/config.log"; then
+        pass "$shell: config.log records have_pthread=yes"
+    else
+        fail "$shell: config.log missing have_pthread=yes"
+    fi
+    if grep -qF 'have_math=yes' "$WORK/config.log"; then
+        pass "$shell: config.log records have_math=yes"
+    else
+        fail "$shell: config.log missing have_math=yes"
+    fi
+
+    # config.status --config must print the original invocation
+    cs_rc=0
+    cs_out=$("$shell" "$WORK/config.status" --config 2>"$WORK/cs.err") || cs_rc=$?
+    if [ "$cs_rc" -eq 0 ]; then
+        case "$cs_out" in
+        *"$WORK/install"*)
+            pass "$shell: config.status --config prints the original args" ;;
+        *)
+            fail "$shell: config.status --config output unexpected: '$cs_out'" ;;
+        esac
+    else
+        fail "$shell: config.status --config exited rc=$cs_rc: $(cat "$WORK/cs.err" 2>/dev/null)"
+    fi
+
+    # --help lists the option node's --enable-debug surface
+    help_rc=0
+    help_out=$(cd "$WORK" && unset CC CFLAGS CXX CXXFLAGS
+        "$shell" ./configure --help 2>&1) || help_rc=$?
+    if [ "$help_rc" -eq 0 ] \
+        && printf '%s\n' "$help_out" | grep -qF -- '--enable-debug'; then
+        pass "$shell: --help exits 0 and lists --enable-debug"
+    else
+        fail "$shell: --help rc=$help_rc or --enable-debug missing"
+    fi
+}
+
+# --- failure case: missing header must fail cleanly, never a syntax error -
+run_failure() {
+    shell=$1
+
+    new_work || return 1
+    if cp "$FIX/project-fail.kdl" "$FIX/Makefile.in" "$WORK/" \
+        && (cd "$WORK" && XDG_DATA_HOME="$WORK/xdg" STUPIDTOOLS_EXT= \
+            "$BIN" project-fail.kdl >gen.log 2>&1) \
+        && [ -s "$WORK/configure" ]; then
+        pass "$shell: stupidtools generated ./configure from project-fail.kdl"
+    else
+        fail "$shell: failure-fixture generation failed: $(cat "$WORK/gen.log" 2>/dev/null)"
+        return 1
+    fi
+
+    # the frozen v1 generator records the failed check and exits 0 (see the
+    # header NOTE); rc=0 here IS the clean-failure contract being asserted
+    conf_rc=0
+    (cd "$WORK" && unset CC CFLAGS CXX CXXFLAGS
+        "$shell" ./configure >configure.out 2>configure.err) || conf_rc=$?
+    if [ "$conf_rc" -eq 0 ]; then
+        pass "$shell: missing-header configure completed cleanly (rc=0, v1 generator semantics)"
+    else
+        fail "$shell: missing-header configure exited rc=$conf_rc: $(cat "$WORK/configure.err" 2>/dev/null)"
+    fi
+    if grep -iE 'syntax error|parse error' "$WORK/configure.out" \
+        "$WORK/configure.err" >/dev/null 2>&1; then
+        fail "$shell: missing-header configure output carries a shell-syntax-error signature"
+    else
+        pass "$shell: no shell-syntax-error signature on the missing-header run"
+    fi
+
+    # the failure is honestly recorded: have_nope=no, the healthy feature
+    # still yes, and the compiler's diagnostic names the missing check
+    if grep -qF 'have_nope=no' "$WORK/config.log"; then
+        pass "$shell: config.log records have_nope=no"
+    else
+        fail "$shell: config.log missing have_nope=no"
+    fi
+    if grep -qF 'have_posix=yes' "$WORK/config.log"; then
+        pass "$shell: config.log records have_posix=yes (configure kept going)"
+    else
+        fail "$shell: config.log missing have_posix=yes"
+    fi
+    if grep -qF 'nope_missing_xyz.h' "$WORK/config.log"; then
+        pass "$shell: config.log names the failed check (nope_missing_xyz.h)"
+    else
+        fail "$shell: config.log does not name the failed check"
+    fi
+
+    # config.h: no HAVE_NOPE define; the healthy feature still gets one
+    if grep -qF 'HAVE_NOPE' "$WORK/config.h"; then
+        fail "$shell: config.h must NOT define HAVE_NOPE"
+    else
+        pass "$shell: config.h has no HAVE_NOPE define"
+    fi
+    if grep -qF '#define HAVE_POSIX 1' "$WORK/config.h"; then
+        pass "$shell: config.h still defines HAVE_POSIX 1"
+    else
+        fail "$shell: config.h missing '#define HAVE_POSIX 1'"
+    fi
+
+    # config.status --config works on the failure fixture too
+    cs_rc=0
+    "$shell" "$WORK/config.status" --config >"$WORK/cs.out" 2>&1 || cs_rc=$?
+    if [ "$cs_rc" -eq 0 ]; then
+        pass "$shell: config.status --config exits 0 (failure fixture)"
+    else
+        fail "$shell: config.status --config exited rc=$cs_rc"
+    fi
+
+    # the genuinely-non-zero configure-error path: an unknown option must
+    # exit 1 with a readable message and no shell syntax error
+    bogus_rc=0
+    bogus_err=$(cd "$WORK" && "$shell" ./configure --definitely-bogus-flag \
+        2>&1) || bogus_rc=$?
+    if [ "$bogus_rc" -eq 1 ] \
+        && printf '%s\n' "$bogus_err" | grep -qF 'unrecognized option'; then
+        pass "$shell: unknown option exits 1 with a readable message"
+    else
+        fail "$shell: unknown option rc=$bogus_rc: '$bogus_err'"
+    fi
+    if printf '%s\n' "$bogus_err" | grep -iE 'syntax error|parse error' \
+        >/dev/null 2>&1; then
+        fail "$shell: unknown-option failure output carries a syntax-error signature"
+    else
+        pass "$shell: no syntax-error signature on the unknown-option failure"
+    fi
+}
+
+# --- the matrix ------------------------------------------------------------
+for shell in "$@"; do
+    run_happy "$shell"
+    run_failure "$shell"
+done
+
+# --- summary ---------------------------------------------------------------
+if [ "$TESTS_FAILED" -ne 0 ]; then
+    printf 'FAILED: %d/%d checks failed\n' "$TESTS_FAILED" "$TESTS_RUN" >&2
+    exit 1
+fi
+printf 'All %d integration checks passed (matrix:%s).\n' "$TESTS_RUN" "$SHELLS"

tests/run.sh

@@ -0,0 +1,187 @@
+#!/bin/sh
+# tests/run.sh - test runner for stupidtools (skeleton).
+#
+# Grows with the project; today it proves the toolchain works end to end:
+# the binary must exist, run, and report its version.
+#
+# POSIX sh only (dash/bash/zsh safe). Fails fast on the first failed check.
+
+TOP_DIR=$(cd "$(dirname "$0")/.." && pwd) || {
+    echo "FAIL: cannot resolve project root" >&2
+    exit 1
+}
+BIN="$TOP_DIR/src/stupidtools"
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+pass() {
+    TESTS_RUN=$((TESTS_RUN + 1))
+    printf 'ok %d - %s\n' "$TESTS_RUN" "$1"
+}
+
+fail() {
+    TESTS_RUN=$((TESTS_RUN + 1))
+    TESTS_FAILED=$((TESTS_FAILED + 1))
+    printf 'not ok %d - %s\n' "$TESTS_RUN" "$1" >&2
+}
+
+# --- 1. the built binary must exist and be executable -------------------
+if [ -x "$BIN" ]; then
+    pass "binary exists and is executable: $BIN"
+else
+    fail "binary missing: $BIN (run 'make' first)"
+    printf 'FAILED: %d/%d checks failed\n' "$TESTS_FAILED" "$TESTS_RUN" >&2
+    exit 1
+fi
+
+# --- 2. --version must exit 0 and print exactly 'stupidtools <version>' -
+version_out=
+if version_out=$("$BIN" --version 2>&1); then
+    if [ "$version_out" = "stupidtools 1.0.0" ]; then
+        pass "--version reports: $version_out"
+    else
+        fail "--version output unexpected: '$version_out' (want 'stupidtools 1.0.0')"
+    fi
+else
+    rc=$?
+    fail "--version exited non-zero (rc=$rc): $version_out"
+fi
+
+# --- 3. --help must exit 0 and print usage on stdout ----------------------
+help_out=
+help_rc=0
+help_out=$("$BIN" --help 2>/dev/null) || help_rc=$?
+if [ "$help_rc" -eq 0 ]; then
+    case "$help_out" in
+    *"Usage: "*)
+        pass "--help exits 0 and prints usage on stdout" ;;
+    *)
+        fail "--help printed no usage on stdout: '$help_out'" ;;
+    esac
+else
+    fail "--help exited non-zero (rc=$help_rc): $help_out"
+fi
+
+# --- 4. unknown option must exit 2, usage on stderr, silent stdout -------
+bogus_out=
+bogus_rc=0
+bogus_out=$("$BIN" --bogus 2>&1 >/dev/null) || bogus_rc=$?
+if [ "$bogus_rc" -eq 2 ]; then
+    case "$bogus_out" in
+    *"Usage: "*)
+        pass "--bogus exits 2 and prints usage on stderr" ;;
+    *)
+        fail "--bogus printed no usage on stderr: '$bogus_out'" ;;
+    esac
+else
+    fail "--bogus exited rc=$bogus_rc (want 2): $bogus_out"
+fi
+if [ -z "$("$BIN" --bogus 2>/dev/null)" ]; then
+    pass "--bogus prints nothing on stdout"
+else
+    fail "--bogus leaked output on stdout"
+fi
+
+# --- 5. no arguments must exit 1 with usage on stderr ---------------------
+noargs_out=
+noargs_rc=0
+noargs_out=$("$BIN" 2>&1 >/dev/null) || noargs_rc=$?
+if [ "$noargs_rc" -eq 1 ]; then
+    case "$noargs_out" in
+    *"Usage: "*)
+        pass "no arguments exits 1 and prints usage on stderr" ;;
+    *)
+        fail "no arguments printed no usage on stderr: '$noargs_out'" ;;
+    esac
+else
+    fail "no arguments exited rc=$noargs_rc (want 1): $noargs_out"
+fi
+
+# --- 6. a missing buildfile is a runtime error (exit 1) -------------------
+"$BIN" buildfile.kdl >/dev/null 2>&1
+rc=$?
+if [ "$rc" -eq 1 ]; then
+    pass "missing buildfile exits 1 (runtime error)"
+else
+    fail "missing buildfile exited rc=$rc (want 1)"
+fi
+
+# --- 7. --version=1 is an unknown option form -> exit 2 -------------------
+"$BIN" --version=1 >/dev/null 2>&1
+rc=$?
+if [ "$rc" -eq 2 ]; then
+    pass "--version=1 exits 2 (unknown option)"
+else
+    fail "--version=1 exited rc=$rc (want 2)"
+fi
+
+# --- 8. -- ends option parsing; following text is positional --------------
+"$BIN" -- --bogus >/dev/null 2>&1
+rc=$?
+if [ "$rc" -eq 1 ]; then
+    pass "-- terminates option parsing (--bogus taken as a missing buildfile: rc=1, not 2)"
+else
+    fail "-- --bogus exited rc=$rc (want 1, proving --bogus was a buildfile not an option)"
+fi
+
+# --- 9. two positionals are a usage error -> exit 2 -----------------------
+"$BIN" a.kdl b.kdl >/dev/null 2>&1
+rc=$?
+if [ "$rc" -eq 2 ]; then
+    pass "two positionals exit 2 (usage error)"
+else
+    fail "two positionals exited rc=$rc (want 2)"
+fi
+
+# --- 10. unit tests (tests/unit/*.c via munit) ----------------------------
+# Harness contract (see .omo/notepads/stupidtools/learnings.md):
+#   - each tests/unit/<name>.c declares its extra link sources on its FIRST
+#     line as:  /* LINK: ../../src/foo.c ../../src/bar.c */
+#     (paths relative to tests/unit/, space-separated)
+#   - the harness adds -I <repo>/thirdparty/munit -I <repo>/src and
+#     thirdparty/munit/munit.c automatically, compiles with
+#     -std=c23 -Wall -Wextra -Wpedantic, and runs each binary.
+#   - a missing LINK line, a compile failure, or a non-zero exit all FAIL.
+UNIT_DIR="$TOP_DIR/tests/unit"
+UNIT_BUILD="$TOP_DIR/tests/.unit-build"
+if [ -d "$UNIT_DIR" ]; then
+    if ! mkdir -p "$UNIT_BUILD"; then
+        fail "cannot create unit build dir: $UNIT_BUILD"
+    fi
+    for t in "$UNIT_DIR"/*.c; do
+        [ -e "$t" ] || continue
+        name=$(basename "$t" .c)
+        # first line only: /* LINK: src1.c src2.c */
+        link=$(sed -n '1s|^/\* LINK: \(.*\) \*/$|\1|p' "$t")
+        if [ -z "$link" ]; then
+            fail "unit test $name: missing LINK comment on line 1"
+            continue
+        fi
+        # compile with cwd=tests/unit so LINK paths resolve relative to it;
+        # absolute paths for everything else.
+        if (cd "$UNIT_DIR" && cc -std=c23 -Wall -Wextra -Wpedantic \
+            -I "$TOP_DIR/thirdparty/munit" -I "$TOP_DIR/src" \
+            "$TOP_DIR/thirdparty/munit/munit.c" $link "$t" \
+            -o "$UNIT_BUILD/unit_$name") 2>"$UNIT_BUILD/unit_$name.build.log"
+        then
+            :
+        else
+            fail "unit test $name: compile failed (see $UNIT_BUILD/unit_$name.build.log)"
+            continue
+        fi
+        if "$UNIT_BUILD/unit_$name" >"$UNIT_BUILD/unit_$name.log" 2>&1; then
+            pass "unit test $name passed"
+        else
+            rc=$?
+            fail "unit test $name exited rc=$rc (see $UNIT_BUILD/unit_$name.log)"
+        fi
+    done
+fi
+
+# --- summary -------------------------------------------------------------
+if [ "$TESTS_FAILED" -ne 0 ]; then
+    printf 'FAILED: %d/%d checks failed\n' "$TESTS_FAILED" "$TESTS_RUN" >&2
+    exit 1
+fi
+printf 'All %d checks passed.\n' "$TESTS_RUN"

tests/selfhost.sh

@@ -0,0 +1,181 @@
+#!/bin/sh
+# tests/selfhost.sh - self-host integration test (plan todo 23).
+#
+# Proves stupidtools generates its OWN ./configure end to end: the tool
+# (already built by `make`) reads the repo's stupid.kdl, emits ./configure
+# into a TEMP dir, that configure produces a Makefile, and `make` builds a
+# working stupidtools whose compile line used -std=c23. The generated
+# configure/Makefile/binary live in the temp dir ONLY - the repo's own
+# autotools bootstrap (configure.ac + Makefile.am) is never touched, and no
+# in-tree residue is produced.
+#
+# POSIX sh only (dash/bash/zsh safe); no [[ ]], arrays, local, ==, <<<, &>.
+# Exit 0 = pass, non-zero = fail. Fails fast on a hard setup error.
+
+TOP_DIR=$(cd "$(dirname "$0")/.." && pwd) || {
+    echo "FAIL: cannot resolve project root" >&2
+    exit 1
+}
+BIN="$TOP_DIR/src/stupidtools"
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+pass() {
+    TESTS_RUN=$((TESTS_RUN + 1))
+    printf 'ok %d - %s\n' "$TESTS_RUN" "$1"
+}
+
+fail() {
+    TESTS_RUN=$((TESTS_RUN + 1))
+    TESTS_FAILED=$((TESTS_FAILED + 1))
+    printf 'not ok %d - %s\n' "$TESTS_RUN" "$1" >&2
+}
+
+# --- 1. the built binary must exist --------------------------------------
+if [ -x "$BIN" ]; then
+    pass "binary exists and is executable: $BIN"
+else
+    fail "binary missing: $BIN (run 'make' first)"
+    printf 'FAILED: %d/%d checks failed\n' "$TESTS_FAILED" "$TESTS_RUN" >&2
+    exit 1
+fi
+
+# --- temp dir (isolated; cleaned on every exit path) ---------------------
+WORK=$(mktemp -d "${TMPDIR:-/tmp}/stupidtools-selfhost.XXXXXX") || {
+    fail "cannot create temp dir"
+    exit 1
+}
+cleanup() { rm -rf "$WORK"; }
+trap cleanup EXIT HUP INT TERM
+
+# --- 2. copy stupid.kdl + write a Makefile.in into the temp dir ----------
+cp "$TOP_DIR/stupid.kdl" "$WORK/stupid.kdl" || {
+    fail "cannot copy stupid.kdl into temp dir"
+    exit 1
+}
+
+# The tool's own source list (repo-relative, kept in sync with stupid.kdl's
+# `target` and src/Makefile.am). Prefixed with $TOP_DIR so the self-hosted
+# build compiles the REAL sources from the isolated temp dir. The `\$(...)`
+# escapes keep CC/CFLAGS/LIBS as MAKE variables (substituted by configure);
+# `$SRCS` expands here (shell) into the absolute path list.
+SRCS="$TOP_DIR/src/main.c $TOP_DIR/src/cli.c $TOP_DIR/src/error.c $TOP_DIR/src/span.c \
+$TOP_DIR/src/kdl/lexer.c $TOP_DIR/src/kdl/parser.c $TOP_DIR/src/kdl/value.c $TOP_DIR/src/kdl/schema.c \
+$TOP_DIR/src/detect/check_registry.c $TOP_DIR/src/detect/checks.c $TOP_DIR/src/detect/probe.c $TOP_DIR/src/detect/resolve.c \
+$TOP_DIR/src/gen/sh_emit.c $TOP_DIR/src/gen/configure.c $TOP_DIR/src/gen/config.c $TOP_DIR/src/gen/args.c \
+$TOP_DIR/src/ext/discovery.c $TOP_DIR/src/ext/lua.c $TOP_DIR/src/ext/abi.c $TOP_DIR/src/ext/api.c \
+$TOP_DIR/src/ext/lang_c.c $TOP_DIR/src/ext/lang_cpp.c \
+$TOP_DIR/thirdparty/lua/lapi.c $TOP_DIR/thirdparty/lua/lauxlib.c \
+$TOP_DIR/thirdparty/lua/lbaselib.c $TOP_DIR/thirdparty/lua/lcode.c \
+$TOP_DIR/thirdparty/lua/lctype.c $TOP_DIR/thirdparty/lua/ldebug.c \
+$TOP_DIR/thirdparty/lua/ldo.c $TOP_DIR/thirdparty/lua/ldump.c \
+$TOP_DIR/thirdparty/lua/lfunc.c $TOP_DIR/thirdparty/lua/lgc.c \
+$TOP_DIR/thirdparty/lua/llex.c $TOP_DIR/thirdparty/lua/lmem.c \
+$TOP_DIR/thirdparty/lua/lobject.c $TOP_DIR/thirdparty/lua/lopcodes.c \
+$TOP_DIR/thirdparty/lua/lparser.c $TOP_DIR/thirdparty/lua/lstate.c \
+$TOP_DIR/thirdparty/lua/lstring.c $TOP_DIR/thirdparty/lua/ltable.c \
+$TOP_DIR/thirdparty/lua/ltm.c $TOP_DIR/thirdparty/lua/lundump.c \
+$TOP_DIR/thirdparty/lua/lvm.c $TOP_DIR/thirdparty/lua/lzio.c \
+$TOP_DIR/thirdparty/lua/lstrlib.c $TOP_DIR/thirdparty/lua/ltablib.c"
+
+cat > "$WORK/Makefile.in" <<EOF
+CC = @CC@
+CFLAGS = @CFLAGS@ -std=c23 -Wall -Wextra -Wpedantic -I$TOP_DIR/src
+LIBS = @LIBS@
+prefix = @prefix@
+
+all: stupidtools
+
+stupidtools: $SRCS
+	\$(CC) \$(CFLAGS) $SRCS -o stupidtools \$(LIBS)
+
+clean:
+	rm -f stupidtools
+EOF
+pass "copied stupid.kdl + wrote Makefile.in"
+
+# --- 3. generate ./configure from stupid.kdl ------------------------------
+# Isolate from the dev environment's extensions (XDG_DATA_HOME to a
+# nonexistent dir, STUPIDTOOLS_EXT emptied) so only the builtin modules
+# load. The binary writes ./configure to the CWD (the temp dir).
+if (cd "$WORK" && XDG_DATA_HOME="$WORK/xdg" STUPIDTOOLS_EXT= \
+        "$BIN" stupid.kdl >gen.log 2>&1); then
+    if [ -s "$WORK/configure" ]; then
+        pass "stupidtools generated a non-empty ./configure"
+    else
+        fail "stupidtools exited 0 but wrote no ./configure (see $WORK/gen.log)"
+    fi
+else
+    rc=$?
+    fail "stupidtools failed on stupid.kdl (rc=$rc): $(cat "$WORK/gen.log" 2>/dev/null)"
+fi
+
+# --- 4. run ./configure -> Makefile --------------------------------------
+if [ -s "$WORK/configure" ]; then
+    if sh -n "$WORK/configure" 2>"$WORK/configure.n.err"; then
+        pass "generated ./configure passes sh -n (POSIX syntax)"
+    else
+        fail "generated ./configure fails sh -n: $(cat "$WORK/configure.n.err" 2>/dev/null)"
+    fi
+
+    if (cd "$WORK" && sh ./configure >config.log 2>&1); then
+        if [ -s "$WORK/Makefile" ]; then
+            pass "./configure ran and wrote a non-empty Makefile"
+        else
+            fail "./configure exited 0 but wrote no Makefile (see $WORK/config.log)"
+        fi
+    else
+        rc=$?
+        fail "./configure failed (rc=$rc): $(cat "$WORK/config.log" 2>/dev/null)"
+    fi
+else
+    fail "skipping configure run (no ./configure was generated)"
+fi
+
+# --- 5+6. build with make V=1 and assert -std=c23 ------------------------
+if [ -s "$WORK/Makefile" ]; then
+    if command -v timeout >/dev/null 2>&1; then
+        timeout 300 make -C "$WORK" V=1 >"$WORK/make.log" 2>&1
+        make_rc=$?
+    else
+        make -C "$WORK" V=1 >"$WORK/make.log" 2>&1
+        make_rc=$?
+    fi
+    if [ "$make_rc" -eq 0 ] && [ -x "$WORK/stupidtools" ]; then
+        pass "make built a stupidtools binary in the temp dir"
+    else
+        fail "make failed (rc=$make_rc): $(tail -n 5 "$WORK/make.log" 2>/dev/null)"
+    fi
+
+    if grep -q -- '-std=c23' "$WORK/make.log"; then
+        pass "self-hosted compile line used -std=c23"
+    else
+        fail "compile line did NOT contain -std=c23 (see $WORK/make.log)"
+    fi
+else
+    fail "skipping make (no Makefile was written)"
+fi
+
+# --- 7. the self-hosted binary must run ----------------------------------
+if [ -x "$WORK/stupidtools" ]; then
+    if version_out=$("$WORK/stupidtools" --version 2>&1); then
+        if [ "$version_out" = "stupidtools 1.0.0" ]; then
+            pass "self-hosted binary --version reports: $version_out"
+        else
+            fail "self-hosted --version unexpected: '$version_out'"
+        fi
+    else
+        rc=$?
+        fail "self-hosted --version exited non-zero (rc=$rc): $version_out"
+    fi
+else
+    fail "skipping --version check (no self-hosted binary was built)"
+fi
+
+# --- summary -------------------------------------------------------------
+if [ "$TESTS_FAILED" -ne 0 ]; then
+    printf 'FAILED: %d/%d checks failed\n' "$TESTS_FAILED" "$TESTS_RUN" >&2
+    exit 1
+fi
+printf 'All %d self-host checks passed.\n' "$TESTS_RUN"

tests/unit/test_abi.c

@@ -0,0 +1,462 @@
+/* LINK: ../../src/ext/abi.c ../../src/ext/lang_c.c ../../src/ext/lang_cpp.c ../../src/error.c ../../src/span.c */
+/* tests/unit/test_abi.c
+ *
+ * Unit tests for the extension ABI (src/ext/abi.h) and the builtin C/C++
+ * language modules (plan todo 13).
+ *
+ * The magic LINK comment on line 1 is REQUIRED by tests/run.sh: it lists
+ * the extra .c sources to compile into this test binary (paths relative
+ * to tests/unit/, space-separated). munit.c and the include dirs are
+ * added automatically by the harness.
+ */
+#ifndef _POSIX_C_SOURCE
+#define _POSIX_C_SOURCE 200809L /* setenv/unsetenv (POSIX.1-2008) */
+#endif
+
+#include "munit.h"
+
+#include "ext/abi.h"
+
+#include <stdlib.h>
+#include <string.h>
+
+/* ---------- helpers ---------- */
+
+/* A fake detect fn proving the ABI invokes registered function pointers
+ * (exactly what a future Lua binding will do). module_ctx is an int*
+ * used as a call counter. */
+static struct st_error *
+fake_detect(struct st_ext_ctx *ctx, void *module_ctx,
+            struct st_toolchain *out)
+{
+    int *called = module_ctx;
+
+    (void)ctx;
+    if (called != NULL) {
+        *called = 1;
+    }
+    out->path = strdup("fakecc");
+    out->id = strdup("fake");
+    out->version = strdup("0.0");
+    return NULL;
+}
+
+static void
+reset_cc_env(void)
+{
+    unsetenv("CC");
+    unsetenv("CFLAGS");
+    unsetenv("CXX");
+    unsetenv("CXXFLAGS");
+}
+
+/* Does the host have a working <cmd>? (mirrors what detection does:
+ * actually execute, never guess from PATH strings). */
+static int
+host_has(const char *cmd)
+{
+    char *argv[] = { (char *)cmd, "--version", NULL };
+    char *out = NULL;
+    size_t out_len = 0;
+    int status = st_ext_run_capture(argv, &out, &out_len);
+
+    free(out);
+    return status == 0;
+}
+
+/* ---------- (a) builtin modules register over the generic ABI ---------- */
+
+static MunitResult
+test_builtins_register_languages(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_ext_ctx *ctx = st_ext_ctx_new();
+    struct st_error *err;
+
+    munit_assert_not_null(ctx);
+
+    /* before init: nothing registered */
+    munit_assert_size(st_ext_language_count(ctx), ==, 0);
+    munit_assert_size(st_ext_check_count(ctx), ==, 0);
+
+    err = st_ext_init_builtins(ctx);
+    munit_assert_null(err);
+
+    /* the C and C++ language modules registered themselves */
+    munit_assert_size(st_ext_language_count(ctx), ==, 2);
+    munit_assert_string_equal(st_ext_language_name(ctx, 0), "c");
+    munit_assert_string_equal(st_ext_language_name(ctx, 1), "cxx");
+
+    /* each language registered its check kinds (header is universal) */
+    munit_assert_size(st_ext_check_count(ctx), ==, 2);
+    munit_assert_string_equal(st_ext_check_language(ctx, 0), "c");
+    munit_assert_string_equal(st_ext_check_kind(ctx, 0), "header");
+    munit_assert_string_equal(st_ext_check_language(ctx, 1), "cxx");
+    munit_assert_string_equal(st_ext_check_kind(ctx, 1), "header");
+
+    /* no detection happened yet: no toolchain, no registered variables */
+    munit_assert_null(st_ext_language_toolchain(ctx, 0));
+    munit_assert_size(st_registry_var_count(st_ext_var_registry(ctx)), ==, 0);
+
+    st_ext_ctx_free(ctx);
+    return MUNIT_OK;
+}
+
+/* (a) detect finds a non-empty CC path + compiler id on this host. */
+static MunitResult
+test_detect_c(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_ext_ctx *ctx = st_ext_ctx_new();
+    struct st_error *err;
+    const struct st_toolchain *tc;
+    const char *cc;
+
+    munit_assert_not_null(ctx);
+    munit_assert_null(st_ext_init_builtins(ctx));
+
+    reset_cc_env();
+    err = st_ext_detect_language(ctx, "c");
+    munit_assert_null(err);
+
+    tc = st_ext_language_toolchain_named(ctx, "c");
+    munit_assert_not_null(tc);
+    munit_assert_not_null(tc->path);
+    munit_assert_int(strlen(tc->path), >, 0);
+    munit_assert_not_null(tc->id);
+    munit_assert_int(strlen(tc->id), >, 0);
+    munit_assert_not_null(tc->version);
+    munit_assert_int(strlen(tc->version), >, 0);
+
+    /* detection recorded the compiler command in CC */
+    cc = st_registry_get_var(st_ext_var_registry(ctx), "CC");
+    munit_assert_not_null(cc);
+    munit_assert_string_equal(cc, tc->path);
+
+    st_ext_ctx_free(ctx);
+    return MUNIT_OK;
+}
+
+/* (b) CC=clang env override: detection must return clang, not the
+ * default cc. */
+static MunitResult
+test_env_override_clang(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_ext_ctx *ctx = st_ext_ctx_new();
+    struct st_error *err;
+    const struct st_toolchain *tc;
+
+    munit_assert_not_null(ctx);
+    munit_assert_null(st_ext_init_builtins(ctx));
+
+    munit_assert_int(setenv("CC", "clang", 1), ==, 0);
+    err = st_ext_detect_language(ctx, "c");
+
+    if (host_has("clang")) {
+        /* Host with clang: id and CC are clang. */
+        munit_assert_null(err);
+        munit_assert_string_equal(
+            st_registry_get_var(st_ext_var_registry(ctx), "CC"), "clang");
+        tc = st_ext_language_toolchain_named(ctx, "c");
+        munit_assert_not_null(tc);
+        munit_assert_string_equal(tc->id, "clang");
+        munit_assert_string_equal(tc->path, "clang");
+    } else {
+        /* Host without clang: the override is still authoritative -- a
+         * clean error, and NO silent fallback to cc. */
+        munit_assert_not_null(err);
+        munit_assert_int(st_error_category_of(err), ==, ST_ERR_IO);
+        munit_assert_not_null(strstr(st_error_message(err), "not found"));
+        munit_assert_null(st_registry_get_var(st_ext_var_registry(ctx), "CC"));
+        st_error_free(err);
+        err = NULL;
+    }
+
+    st_ext_ctx_free(ctx);
+    return MUNIT_OK;
+}
+
+/* (b, host form) CC=gcc env override honored end to end. */
+static MunitResult
+test_env_override_gcc(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_ext_ctx *ctx = st_ext_ctx_new();
+    struct st_error *err;
+    const struct st_toolchain *tc;
+
+    munit_assert_not_null(ctx);
+    munit_assert_null(st_ext_init_builtins(ctx));
+
+    munit_assert_int(setenv("CC", "gcc", 1), ==, 0);
+    err = st_ext_detect_language(ctx, "c");
+    munit_assert_null(err);
+
+    munit_assert_string_equal(
+        st_registry_get_var(st_ext_var_registry(ctx), "CC"), "gcc");
+    tc = st_ext_language_toolchain_named(ctx, "c");
+    munit_assert_not_null(tc);
+    munit_assert_string_equal(tc->id, "gcc");
+
+    st_ext_ctx_free(ctx);
+    return MUNIT_OK;
+}
+
+/* (c) a bogus CC=/nonexistent yields a clean error, not a crash. */
+static MunitResult
+test_bogus_cc_clean_error(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_ext_ctx *ctx = st_ext_ctx_new();
+    struct st_error *err;
+
+    munit_assert_not_null(ctx);
+    munit_assert_null(st_ext_init_builtins(ctx));
+
+    munit_assert_int(
+        setenv("CC", "/nonexistent/stupidtools/not-a-compiler", 1), ==, 0);
+    err = st_ext_detect_language(ctx, "c");
+
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_IO);
+    munit_assert_not_null(strstr(st_error_message(err), "not found"));
+
+    /* failed detection must not half-register variables */
+    munit_assert_null(st_registry_get_var(st_ext_var_registry(ctx), "CC"));
+    munit_assert_null(st_ext_language_toolchain_named(ctx, "c"));
+
+    st_error_free(err);
+    st_ext_ctx_free(ctx);
+    return MUNIT_OK;
+}
+
+/* adversarial: empty PATH must yield a clean error, not a crash. */
+static MunitResult
+test_empty_path_clean_error(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_ext_ctx *ctx = st_ext_ctx_new();
+    struct st_error *err;
+    const char *saved = getenv("PATH");
+
+    munit_assert_not_null(ctx);
+    munit_assert_null(st_ext_init_builtins(ctx));
+
+    reset_cc_env();
+    munit_assert_int(setenv("PATH", "", 1), ==, 0);
+    err = st_ext_detect_language(ctx, "c");
+    munit_assert_not_null(err);
+    munit_assert_not_null(strstr(st_error_message(err), "no C compiler found"));
+    munit_assert_null(st_registry_get_var(st_ext_var_registry(ctx), "CC"));
+    st_error_free(err);
+
+    if (saved != NULL) {
+        munit_assert_int(setenv("PATH", saved, 1), ==, 0);
+    } else {
+        munit_assert_int(unsetenv("PATH"), ==, 0);
+    }
+
+    st_ext_ctx_free(ctx);
+    return MUNIT_OK;
+}
+
+/* (d) registered vars CC/CFLAGS are queryable from the generic registry;
+ * CFLAGS defaults empty and respects the environment. */
+static MunitResult
+test_registered_vars_queryable(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_ext_ctx *ctx = st_ext_ctx_new();
+    struct st_registry *reg;
+    struct st_error *err;
+
+    munit_assert_not_null(ctx);
+    munit_assert_null(st_ext_init_builtins(ctx));
+    reg = st_ext_var_registry(ctx);
+
+    reset_cc_env();
+    munit_assert_int(setenv("CFLAGS", "-std=c23 -pedantic", 1), ==, 0);
+    err = st_ext_detect_language(ctx, "c");
+    munit_assert_null(err);
+
+    munit_assert_not_null(st_registry_get_var(reg, "CC"));
+    munit_assert_int(strlen(st_registry_get_var(reg, "CC")), >, 0);
+    munit_assert_string_equal(st_registry_get_var(reg, "CFLAGS"),
+                              "-std=c23 -pedantic");
+
+    /* CXX/CXXFLAGS belong to the cxx module and are not set by C detect */
+    munit_assert_null(st_registry_get_var(reg, "CXX"));
+
+    st_ext_ctx_free(ctx);
+    return MUNIT_OK;
+}
+
+/* (d) the generic var registry itself: set/get/overwrite/unset semantics
+ * with no compiler involved. */
+static MunitResult
+test_var_registry_semantics(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_registry *reg = st_registry_new();
+
+    munit_assert_not_null(reg);
+    munit_assert_null(st_registry_get_var(reg, "X"));
+    munit_assert_size(st_registry_var_count(reg), ==, 0);
+
+    st_registry_set_var(reg, "X", "v1");
+    munit_assert_string_equal(st_registry_get_var(reg, "X"), "v1");
+    munit_assert_size(st_registry_var_count(reg), ==, 1);
+
+    /* overwrite replaces the value */
+    st_registry_set_var(reg, "X", "v2");
+    munit_assert_string_equal(st_registry_get_var(reg, "X"), "v2");
+    munit_assert_size(st_registry_var_count(reg), ==, 1);
+
+    /* NULL value unsets */
+    st_registry_set_var(reg, "X", NULL);
+    munit_assert_null(st_registry_get_var(reg, "X"));
+    munit_assert_size(st_registry_var_count(reg), ==, 0);
+
+    /* ordered iteration matches insertion order */
+    st_registry_set_var(reg, "CC", "cc");
+    st_registry_set_var(reg, "CFLAGS", "");
+    munit_assert_size(st_registry_var_count(reg), ==, 2);
+    munit_assert_string_equal(st_registry_var_name(reg, 0), "CC");
+    munit_assert_string_equal(st_registry_var_value(reg, 0), "cc");
+    munit_assert_string_equal(st_registry_var_name(reg, 1), "CFLAGS");
+    munit_assert_string_equal(st_registry_var_value(reg, 1), "");
+
+    /* get_var is borrowed, not owned: registry still frees cleanly */
+    st_registry_free(reg);
+    return MUNIT_OK;
+}
+
+/* the C++ language module detects over the same ABI (env CXX -> c++ ->
+ * g++/clang++) and registers CXX/CXXFLAGS. */
+static MunitResult
+test_detect_cxx(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_ext_ctx *ctx = st_ext_ctx_new();
+    struct st_error *err;
+    const struct st_toolchain *tc;
+
+    munit_assert_not_null(ctx);
+    munit_assert_null(st_ext_init_builtins(ctx));
+
+    reset_cc_env();
+    err = st_ext_detect_language(ctx, "cxx");
+
+    if (err != NULL) {
+        /* Host without a C++ compiler: clean error, no half-registration. */
+        munit_assert_not_null(strstr(st_error_message(err), "found"));
+        munit_assert_null(st_registry_get_var(st_ext_var_registry(ctx), "CXX"));
+        st_error_free(err);
+    } else {
+        tc = st_ext_language_toolchain_named(ctx, "cxx");
+        munit_assert_not_null(tc);
+        munit_assert_int(strlen(tc->path), >, 0);
+        munit_assert_int(strlen(tc->id), >, 0);
+        munit_assert_string_equal(
+            st_registry_get_var(st_ext_var_registry(ctx), "CXX"), tc->path);
+        munit_assert_not_null(
+            st_registry_get_var(st_ext_var_registry(ctx), "CXXFLAGS"));
+    }
+
+    st_ext_ctx_free(ctx);
+    return MUNIT_OK;
+}
+
+/* ABI robustness: duplicate registrations and unknown lookups error. */
+static MunitResult
+test_registry_errors(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_ext_ctx *ctx = st_ext_ctx_new();
+    struct st_error *err;
+    static const char *const vars[] = { "CC", NULL };
+    const struct st_toolchain *tc;
+    int fake_detect_called = 0;
+
+    munit_assert_not_null(ctx);
+
+    err = st_ext_register_language(ctx, "c", fake_detect,
+                                   &fake_detect_called, vars);
+    munit_assert_null(err);
+
+    /* duplicate language registration errors */
+    err = st_ext_register_language(ctx, "c", fake_detect, NULL, vars);
+    munit_assert_not_null(err);
+    st_error_free(err);
+
+    /* duplicate check registration errors */
+    err = st_ext_register_check(ctx, "c", "header", NULL);
+    munit_assert_null(err);
+    err = st_ext_register_check(ctx, "c", "header", NULL);
+    munit_assert_not_null(err);
+    st_error_free(err);
+
+    /* detecting an unknown language errors, does not crash */
+    err = st_ext_detect_language(ctx, "nope");
+    munit_assert_not_null(err);
+    st_error_free(err);
+
+    /* detection routes through the registered function pointer */
+    err = st_ext_detect_language(ctx, "c");
+    munit_assert_null(err);
+    munit_assert_int(fake_detect_called, ==, 1);
+    tc = st_ext_language_toolchain_named(ctx, "c");
+    munit_assert_not_null(tc);
+    munit_assert_string_equal(tc->id, "fake");
+
+    /* unknown-name toolchain lookup returns NULL */
+    munit_assert_null(st_ext_language_toolchain_named(ctx, "nope"));
+
+    st_ext_ctx_free(ctx);
+    return MUNIT_OK;
+}
+
+static MunitTest tests[] = {
+    { "/abi/builtins-register", test_builtins_register_languages, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/abi/detect-c", test_detect_c, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { "/abi/env-override-clang", test_env_override_clang, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/abi/env-override-gcc", test_env_override_gcc, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/abi/bogus-cc-clean-error", test_bogus_cc_clean_error, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/abi/empty-path-clean-error", test_empty_path_clean_error, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/abi/registered-vars-queryable", test_registered_vars_queryable, NULL,
+      NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/abi/var-registry-semantics", test_var_registry_semantics, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/abi/detect-cxx", test_detect_cxx, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { "/abi/registry-errors", test_registry_errors, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { NULL, NULL, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+};
+
+static const MunitSuite suite = {
+    "/abi", tests, NULL, 1, MUNIT_SUITE_OPTION_NONE,
+};
+
+int
+main(int argc, char *argv[MUNIT_ARRAY_PARAM(argc + 1)])
+{
+    return munit_suite_main(&suite, NULL, argc, argv);
+}

tests/unit/test_api.c

@@ -0,0 +1,402 @@
+/* LINK: ../../src/ext/api.c ../../src/ext/lua.c ../../src/ext/abi.c ../../src/ext/lang_c.c ../../src/ext/lang_cpp.c ../../src/error.c ../../src/span.c ../../thirdparty/lua/lapi.c ../../thirdparty/lua/lauxlib.c ../../thirdparty/lua/lbaselib.c ../../thirdparty/lua/lcode.c ../../thirdparty/lua/lctype.c ../../thirdparty/lua/ldebug.c ../../thirdparty/lua/ldo.c ../../thirdparty/lua/ldump.c ../../thirdparty/lua/lfunc.c ../../thirdparty/lua/lgc.c ../../thirdparty/lua/llex.c ../../thirdparty/lua/lmem.c ../../thirdparty/lua/lobject.c ../../thirdparty/lua/lopcodes.c ../../thirdparty/lua/lparser.c ../../thirdparty/lua/lstate.c ../../thirdparty/lua/lstring.c ../../thirdparty/lua/ltable.c ../../thirdparty/lua/ltm.c ../../thirdparty/lua/lundump.c ../../thirdparty/lua/lvm.c ../../thirdparty/lua/lzio.c ../../thirdparty/lua/lstrlib.c ../../thirdparty/lua/ltablib.c */
+
+#ifndef _POSIX_C_SOURCE
+#define _POSIX_C_SOURCE 200809L /* setenv/unsetenv, access */
+#endif
+
+/*
+ * tests/unit/test_api.c
+ *
+ * Unit tests for the Lua API over the extension ABI (src/ext/api.h,
+ * plan todo 21): st_ext_bridge_lua flushes a Lua runtime's registrations
+ * into a struct st_ext_ctx, and st_lua_probe_run resolves a probe spec
+ * against a detected C toolchain.
+ *
+ * The magic LINK comment on line 1 is REQUIRED by tests/run.sh: it lists
+ * the extra .c sources compiled into this test binary (paths relative to
+ * tests/unit/). It links api.c, the sandboxed Lua runtime (lua.c + the
+ * same 27 vendored Lua sources as test_lua.c, minus linit/lmathlib/
+ * loadlib/liolib/loslib/lua.c/luac.c -- see the -lm note there), the
+ * extension ABI + builtin C/C++ modules, and error/span.
+ */
+#include "munit.h"
+
+#include "ext/abi.h"
+#include "ext/api.h"
+#include "ext/lua.h"
+
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+/* ---------- helpers ---------- */
+
+static void
+reset_cc_env(void)
+{
+    unsetenv("CC");
+    unsetenv("CFLAGS");
+    unsetenv("CXX");
+    unsetenv("CXXFLAGS");
+}
+
+/* Fresh ctx + rt pair with the builtin C/C++ modules already registered
+ * (a bridge flushes Lua registrations on top of them). */
+static int
+fresh_setup(struct st_ext_ctx **ctx, struct st_lua_rt **rt)
+{
+    *ctx = st_ext_ctx_new();
+    *rt = st_lua_rt_new();
+    if (*ctx == NULL || *rt == NULL) {
+        return -1;
+    }
+    if (st_ext_init_builtins(*ctx) != NULL) {
+        return -1;
+    }
+    return 0;
+}
+
+/* ---------- (a) a Lua check lands in the ctx after bridging ---------- */
+
+static MunitResult
+test_bridge_check_visible(const MunitParameter params[], void *data)
+{
+    struct st_ext_ctx *ctx = NULL;
+    struct st_lua_rt *rt = NULL;
+    struct st_error *err;
+    size_t i, n;
+    int found = 0;
+
+    (void)params;
+    (void)data;
+
+    munit_assert_int(fresh_setup(&ctx, &rt), ==, 0);
+
+    err = st_lua_run(rt,
+                     "st.register_check(\"magic\", {kind=\"compile\", "
+                     "source=\"int main(void){return 0;}\"})",
+                     "=api-check");
+    munit_assert_null(err);
+
+    err = st_ext_bridge_lua(ctx, rt);
+    munit_assert_null(err);
+
+    /* builtin "c"/header + "cxx"/header + the bridged "c"/magic = 3 */
+    munit_assert_size(st_ext_check_count(ctx), ==, 3);
+    n = st_ext_check_count(ctx);
+    for (i = 0; i < n; i++) {
+        if (strcmp(st_ext_check_kind(ctx, i), "magic") != 0) {
+            continue;
+        }
+        const struct st_lua_probe_spec *spec =
+            st_ext_check_probe_spec(ctx, i);
+
+        found = 1;
+        munit_assert_string_equal(st_ext_check_language(ctx, i), "c");
+        munit_assert_not_null(spec);
+        munit_assert_string_equal(spec->kind, "compile");
+        munit_assert_not_null(strstr(spec->source, "int main"));
+    }
+    munit_assert_int(found, ==, 1);
+
+    /* the ctx borrows the spec from the runtime: free ctx first, rt last */
+    st_ext_ctx_free(ctx);
+    st_lua_rt_free(rt);
+    return MUNIT_OK;
+}
+
+/* ---------- (b) probe resolves true/false against the detected CC ---------- */
+
+static MunitResult
+test_probe_true_false(const MunitParameter params[], void *data)
+{
+    struct st_ext_ctx *ctx = NULL;
+    struct st_lua_rt *rt = NULL;
+    struct st_error *err;
+    const struct st_toolchain *tc;
+    struct st_lua_probe_spec valid;
+    struct st_lua_probe_spec invalid;
+    char *valid_eb = NULL;
+    char *invalid_eb = NULL;
+    int rv, ri;
+
+    (void)params;
+    (void)data;
+
+    munit_assert_int(fresh_setup(&ctx, &rt), ==, 0);
+    reset_cc_env();
+    err = st_ext_detect_language(ctx, "c");
+    munit_assert_null(err);
+    tc = st_ext_language_toolchain_named(ctx, "c");
+    munit_assert_not_null(tc);
+    munit_assert_not_null(tc->path);
+
+    valid.kind = "compile";
+    valid.source = "int main(void){return 0;}";
+    valid.link = NULL;
+    invalid.kind = "compile";
+    invalid.source = "int main(void){this is not C;}";
+    invalid.link = NULL;
+
+    rv = st_lua_probe_run(tc, &valid, &valid_eb);
+    ri = st_lua_probe_run(tc, &invalid, &invalid_eb);
+
+    munit_assert_int(rv, ==, 1);
+    munit_assert_null(valid_eb); /* a pass carries no error text */
+    munit_assert_int(ri, ==, 0);
+    /* the false probe must have ACTUALLY failed the compile: the captured
+     * compiler stderr is non-empty (misleading-success guard) */
+    munit_assert_not_null(invalid_eb);
+    munit_assert_int(strlen(invalid_eb), >, 0);
+
+    free(valid_eb);
+    free(invalid_eb);
+    st_ext_ctx_free(ctx);
+    st_lua_rt_free(rt);
+    return MUNIT_OK;
+}
+
+/* ---------- (c) a Lua language lands in the ctx after bridging ---------- */
+
+static MunitResult
+test_language_lands(const MunitParameter params[], void *data)
+{
+    struct st_ext_ctx *ctx = NULL;
+    struct st_lua_rt *rt = NULL;
+    struct st_error *err;
+    size_t i, n;
+    int found = 0;
+
+    (void)params;
+    (void)data;
+
+    munit_assert_int(fresh_setup(&ctx, &rt), ==, 0);
+    err = st_lua_run(rt, "st.register_language(\"fortran\", {})",
+                     "=api-lang");
+    munit_assert_null(err);
+    err = st_ext_bridge_lua(ctx, rt);
+    munit_assert_null(err);
+
+    n = st_ext_language_count(ctx);
+    munit_assert_size(n, ==, 3); /* c, cxx, fortran */
+    for (i = 0; i < n; i++) {
+        if (strcmp(st_ext_language_name(ctx, i), "fortran") == 0) {
+            found = 1;
+        }
+    }
+    munit_assert_int(found, ==, 1);
+
+    st_ext_ctx_free(ctx);
+    st_lua_rt_free(rt);
+    return MUNIT_OK;
+}
+
+/* ---------- (d) a Lua registration colliding with a builtin errors ---------- */
+
+static MunitResult
+test_duplicate_error(const MunitParameter params[], void *data)
+{
+    struct st_ext_ctx *ctx = NULL;
+    struct st_lua_rt *rt = NULL;
+    struct st_error *err;
+    const char *msg;
+
+    (void)params;
+    (void)data;
+
+    /* a Lua check named "header" collides with the builtin "c"/"header" */
+    munit_assert_int(fresh_setup(&ctx, &rt), ==, 0);
+    err = st_lua_run(rt, "st.register_check(\"header\")", "=api-dup");
+    munit_assert_null(err);
+    err = st_ext_bridge_lua(ctx, rt);
+    munit_assert_not_null(err);
+    msg = st_error_message(err);
+    munit_assert_not_null(strstr(msg, "already registered"));
+    st_error_free(err);
+    st_ext_ctx_free(ctx);
+    st_lua_rt_free(rt);
+
+    /* a Lua language named "c" collides with the builtin language */
+    munit_assert_int(fresh_setup(&ctx, &rt), ==, 0);
+    err = st_lua_run(rt, "st.register_language(\"c\")", "=api-dup2");
+    munit_assert_null(err);
+    err = st_ext_bridge_lua(ctx, rt);
+    munit_assert_not_null(err);
+    msg = st_error_message(err);
+    munit_assert_not_null(strstr(msg, "already registered"));
+    st_error_free(err);
+    st_ext_ctx_free(ctx);
+    st_lua_rt_free(rt);
+
+    return MUNIT_OK;
+}
+
+/* ---------- (e) malformed probe-spec tables are clean errors ---------- */
+
+static MunitResult
+test_malformed_spec_errors(const MunitParameter params[], void *data)
+{
+    struct st_lua_rt *rt;
+    struct st_error *err;
+    const char *msg;
+
+    (void)params;
+    (void)data;
+
+    rt = st_lua_rt_new();
+    munit_assert_not_null(rt);
+
+    /* non-table second argument */
+    err = st_lua_run(rt, "st.register_check(\"x\", \"not-a-table\")",
+                     "=api-bad1");
+    munit_assert_not_null(err);
+    msg = st_error_message(err);
+    munit_assert_not_null(strstr(msg, "table"));
+    st_error_free(err);
+
+    /* unknown kind */
+    err = st_lua_run(rt,
+                     "st.register_check(\"x\", {kind=\"bogus\", "
+                     "source=\"int x;\"})",
+                     "=api-bad2");
+    munit_assert_not_null(err);
+    msg = st_error_message(err);
+    munit_assert_not_null(strstr(msg, "kind"));
+    st_error_free(err);
+
+    /* missing source */
+    err = st_lua_run(rt, "st.register_check(\"x\", {kind=\"compile\"})",
+                     "=api-bad3");
+    munit_assert_not_null(err);
+    msg = st_error_message(err);
+    munit_assert_not_null(strstr(msg, "source"));
+    st_error_free(err);
+
+    /* the runtime stays usable after errors */
+    err = st_lua_run(rt, "st.register_check(\"ok\")", "=api-ok");
+    munit_assert_null(err);
+
+    st_lua_rt_free(rt);
+    return MUNIT_OK;
+}
+
+/* ---------- (f) shell metacharacters in a probe source stay inert ---------- */
+
+static MunitResult
+test_injection_inert(const MunitParameter params[], void *data)
+{
+    struct st_ext_ctx *ctx = NULL;
+    struct st_lua_rt *rt = NULL;
+    struct st_error *err;
+    const struct st_toolchain *tc;
+    struct st_lua_probe_spec spec;
+    static const char *marker = "/tmp/stprobe_injected_marker";
+    char *eb = NULL;
+    int rc;
+
+    (void)params;
+    (void)data;
+
+    munit_assert_int(fresh_setup(&ctx, &rt), ==, 0);
+    reset_cc_env();
+    err = st_ext_detect_language(ctx, "c");
+    munit_assert_null(err);
+    tc = st_ext_language_toolchain_named(ctx, "c");
+    munit_assert_not_null(tc);
+
+    (void)unlink(marker);
+
+    spec.kind = "compile";
+    spec.source = "int main(void){return 0;}\" ; touch "
+                  "/tmp/stprobe_injected_marker ; \"";
+    spec.link = NULL;
+
+    /* not valid C -> the probe fails; the injection must NOT have run */
+    rc = st_lua_probe_run(tc, &spec, &eb);
+    munit_assert_int(rc, ==, 0);
+    munit_assert_int(access(marker, F_OK), ==, -1);
+
+    free(eb);
+    (void)unlink(marker);
+    st_ext_ctx_free(ctx);
+    st_lua_rt_free(rt);
+    return MUNIT_OK;
+}
+
+/* ---------- (g) link/run probe modes and the link[] flag passthrough ---------- */
+
+static MunitResult
+test_probe_modes(const MunitParameter params[], void *data)
+{
+    struct st_ext_ctx *ctx = NULL;
+    struct st_lua_rt *rt = NULL;
+    struct st_error *err;
+    const struct st_toolchain *tc;
+    struct st_lua_probe_spec link;
+    struct st_lua_probe_spec run;
+    struct st_lua_probe_spec runfail;
+    struct st_lua_probe_spec badlink;
+    static char *bad_link[] = { "-l__stprobe_nonexistent_lib__", NULL };
+
+    (void)params;
+    (void)data;
+
+    munit_assert_int(fresh_setup(&ctx, &rt), ==, 0);
+    reset_cc_env();
+    err = st_ext_detect_language(ctx, "c");
+    munit_assert_null(err);
+    tc = st_ext_language_toolchain_named(ctx, "c");
+    munit_assert_not_null(tc);
+
+    link.kind = "link";
+    link.source = "int main(void){return 0;}";
+    link.link = NULL;
+    run.kind = "run";
+    run.source = "int main(void){return 0;}";
+    run.link = NULL;
+    runfail.kind = "run";
+    runfail.source = "int main(void){return 7;}";
+    runfail.link = NULL;
+    badlink.kind = "link";
+    badlink.source = "int main(void){return 0;}";
+    badlink.link = bad_link;
+
+    munit_assert_int(st_lua_probe_run(tc, &link, NULL), ==, 1);
+    munit_assert_int(st_lua_probe_run(tc, &run, NULL), ==, 1);
+    munit_assert_int(st_lua_probe_run(tc, &runfail, NULL), ==, 0);
+    /* a bogus -l flag reaches the linker and fails -> the link[] argv
+     * elements are genuinely passed through */
+    munit_assert_int(st_lua_probe_run(tc, &badlink, NULL), ==, 0);
+
+    st_ext_ctx_free(ctx);
+    st_lua_rt_free(rt);
+    return MUNIT_OK;
+}
+
+static MunitTest tests[] = {
+    { "/api/bridge-check-visible", test_bridge_check_visible, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/api/probe-true-false", test_probe_true_false, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/api/language-lands", test_language_lands, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/api/duplicate-error", test_duplicate_error, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/api/malformed-spec-errors", test_malformed_spec_errors, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/api/injection-inert", test_injection_inert, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/api/probe-modes", test_probe_modes, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { NULL, NULL, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+};
+
+static const MunitSuite suite = {
+    "/api", tests, NULL, 1, MUNIT_SUITE_OPTION_NONE,
+};
+
+int
+main(int argc, char *argv[MUNIT_ARRAY_PARAM(argc + 1)])
+{
+    return munit_suite_main(&suite, NULL, argc, argv);
+}

tests/unit/test_check_registry.c

@@ -0,0 +1,551 @@
+/* LINK: ../../src/detect/check_registry.c ../../src/kdl/schema.c ../../src/kdl/parser.c ../../src/kdl/lexer.c ../../src/kdl/value.c ../../src/error.c ../../src/span.c */
+/* tests/unit/test_check_registry.c
+ *
+ * Unit tests for the declarative feature-check registry (todo 10).
+ *
+ * The magic LINK comment on line 1 is REQUIRED by tests/run.sh: it lists
+ * the extra .c sources to compile into this test binary (paths relative
+ * to tests/unit/, space-separated). check_registry.c needs error.c (it
+ * frees/re-owns value-model errors); schema.c needs value.c + error.c;
+ * parser.c + lexer.c build documents end-to-end from source text;
+ * span.c via error.c's st_span_print. error.c and span.c extend the
+ * todo-10 file list because both linked units reference them.
+ *
+ * The registry under test maps a feature's CHECK child node (its name =
+ * the check kind, its first arg = the target) onto the 8 declarative
+ * kinds pinned in src/detect/check_registry.h, and src/kdl/schema.c's
+ * HOOK enforces each kind's argument/property shape. Assertions check
+ * REAL error properties: category (ST_ERR_KDL_SCHEMA), message text
+ * (must name the offending node), and exact line/col spans.
+ */
+#include "munit.h"
+
+#include "detect/check_registry.h"
+#include "error.h"
+#include "kdl/ast.h"
+#include "kdl/schema.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* ---- fixture loading -------------------------------------------------- */
+
+/* Locate tests/fixtures/stupid.kdl. The harness runs the test binary with
+ * cwd = repo top (make check) or tests/unit (manual run); probe both. */
+static const char *
+fixture_path(void)
+{
+    static const char *const candidates[] = {
+        "tests/fixtures/stupid.kdl",
+        "../fixtures/stupid.kdl",
+    };
+    size_t i;
+
+    for (i = 0; i < sizeof(candidates) / sizeof(candidates[0]); i++) {
+        FILE *f = fopen(candidates[i], "rb");
+        if (f != NULL) {
+            fclose(f);
+            return candidates[i];
+        }
+    }
+    return NULL;
+}
+
+/* Slurp the fixture into a NUL-terminated buffer. Caller frees. */
+static char *
+slurp_fixture(const char *path)
+{
+    FILE *f;
+    long n;
+    char *buf;
+
+    if (path == NULL) {
+        return NULL;
+    }
+    f = fopen(path, "rb");
+    if (f == NULL) {
+        return NULL;
+    }
+    if (fseek(f, 0, SEEK_END) != 0) {
+        fclose(f);
+        return NULL;
+    }
+    n = ftell(f);
+    if (n < 0 || fseek(f, 0, SEEK_SET) != 0) {
+        fclose(f);
+        return NULL;
+    }
+    buf = munit_malloc((size_t)n + 1);
+    if (fread(buf, 1, (size_t)n, f) != (size_t)n) {
+        free(buf);
+        fclose(f);
+        return NULL;
+    }
+    fclose(f);
+    buf[n] = '\0';
+    return buf;
+}
+
+/* ---- helpers ---------------------------------------------------------- */
+
+/* Parse a single-node document and return its one node (parse is
+ * asserted to succeed). The document is leaked on purpose: tests free
+ * it via the returned node's owning doc... it is NOT: the DOCUMENT is
+ * returned alongside so the caller can free it. */
+static struct st_kdl_node *
+parse_one_node(const char *src, struct st_kdl_document **doc_out)
+{
+    struct st_error *err = NULL;
+
+    *doc_out = st_kdl_parse(src, "t.kdl", &err);
+    munit_assert_null(err);
+    munit_assert_not_null(*doc_out);
+    return (*doc_out)->nodes;
+}
+
+/* Parse `src` and validate; assert a ST_ERR_KDL_SCHEMA error whose
+ * message contains `needle` and whose span is exactly (line, col). */
+static void
+assert_schema_error(const char *src, const char *needle, size_t line,
+                    size_t col)
+{
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc = st_kdl_parse(src, "t.kdl", &err);
+
+    munit_assert_null(err);
+    munit_assert_not_null(doc);
+    err = st_kdl_validate(doc);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+    munit_assert_not_null(err->span);
+    munit_assert_size(err->span->line, ==, line);
+    munit_assert_size(err->span->col, ==, col);
+    munit_assert_true(strstr(st_error_message(err), needle) != NULL);
+    st_error_free(err);
+    st_kdl_document_free(doc);
+}
+
+/* Parse `src` and validate; assert success. */
+static void
+assert_valid(const char *src)
+{
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc = st_kdl_parse(src, "t.kdl", &err);
+
+    munit_assert_null(err);
+    munit_assert_not_null(doc);
+    err = st_kdl_validate(doc);
+    munit_assert_null(err);
+    st_kdl_document_free(doc);
+}
+
+/* The 8 kinds in DSL order, each with a representative target argument.
+ * `arg_col` is the column of the target token in the single-line source
+ * `feature "f" { <kw> <arg> }` (col of kw + len(kw) + 1). */
+struct kind_case {
+    const char *kw;
+    enum st_check_kind kind;
+    const char *arg;
+    size_t arg_col;
+};
+
+static const struct kind_case kind_cases[] = {
+    { "header", ST_CHECK_HEADER, "pthread.h", 22 },
+    { "function", ST_CHECK_FUNCTION, "strdup", 24 },
+    { "library", ST_CHECK_LIBRARY, "pthread", 23 },
+    { "type", ST_CHECK_TYPE, "size_t", 20 },
+    { "sizeof", ST_CHECK_SIZEOF, "long", 22 },
+    { "program", ST_CHECK_PROGRAM, "pkg-config", 23 },
+    { "compiler_flag", ST_CHECK_COMPILER_FLAG, "-fsanitize=address", 29 },
+    { "pkg_config", ST_CHECK_PKG_CONFIG, "openssl", 26 },
+};
+
+/* ---- tests ------------------------------------------------------------ */
+
+/* (a) all 8 kinds map from a representative DSL node; kind name and
+ * shape-table accessors round-trip; the table itself is coherent
+ * (COUNT entries, each self-indexed, exactly one required arg). */
+static MunitResult
+test_all_kinds_map(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    size_t i;
+
+    munit_assert_size(st_check_kind_count(), ==, 8);
+    munit_assert_size(sizeof(kind_cases) / sizeof(kind_cases[0]), ==, 8);
+
+    for (i = 0; i < st_check_kind_count(); i++) {
+        char src[96];
+        int n;
+        struct st_error *err = NULL;
+        struct st_kdl_document *doc = NULL;
+        struct st_kdl_node *node;
+        enum st_check_kind kind;
+        const struct st_check_shape *shape;
+
+        /* a representative single-node document, e.g. header "pthread.h" */
+        n = snprintf(src, sizeof src, "%s \"%s\"", kind_cases[i].kw,
+                     kind_cases[i].arg);
+        munit_assert_int(n, >=, 0);
+        munit_assert_size((size_t)n, <, sizeof src);
+        node = parse_one_node(src, &doc);
+        munit_assert_not_null(node);
+
+        err = NULL;
+        kind = st_check_kind_from_node(node, &err);
+        munit_assert_null(err);
+        munit_assert_int(kind, ==, kind_cases[i].kind);
+        st_kdl_document_free(doc);
+
+        /* name round-trip: kind -> DSL keyword */
+        munit_assert_string_equal(st_check_kind_name(kind_cases[i].kind),
+                                  kind_cases[i].kw);
+
+        /* shape-table accessors agree with the kind */
+        shape = st_check_kind_shape(kind_cases[i].kind);
+        munit_assert_not_null(shape);
+        munit_assert_int(shape->kind, ==, kind_cases[i].kind);
+        munit_assert_string_equal(shape->name, kind_cases[i].kw);
+        munit_assert_size(shape->required_args, ==, 1);
+        munit_assert_not_null(shape->arg_meaning);
+        munit_assert_true(shape->arg_meaning[0] != '\0');
+
+        /* only library and pkg_config take the optional `version`
+         * keyword-argument pair */
+        if (kind_cases[i].kind == ST_CHECK_LIBRARY ||
+            kind_cases[i].kind == ST_CHECK_PKG_CONFIG) {
+            munit_assert_size(shape->optional_args, ==, 2);
+        } else {
+            munit_assert_size(shape->optional_args, ==, 0);
+        }
+    }
+
+    /* out-of-range accessors degrade safely */
+    munit_assert_null(st_check_kind_shape(ST_CHECK_KIND_COUNT));
+    munit_assert_string_equal(st_check_kind_name(ST_CHECK_KIND_COUNT), "?");
+    return MUNIT_OK;
+}
+
+/* (a) a quoted node name maps like a bare one (names are KDL strings in
+ * every string form), and each kind validates end-to-end inside a
+ * feature block. */
+static MunitResult
+test_quoted_and_feature_forms(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    size_t i;
+
+    for (i = 0; i < st_check_kind_count(); i++) {
+        char src[160];
+        int n;
+        struct st_error *err = NULL;
+        struct st_kdl_document *doc = NULL;
+        struct st_kdl_node *node;
+        enum st_check_kind kind;
+
+        /* quoted name form: "header" "pthread.h" */
+        n = snprintf(src, sizeof src, "\"%s\" \"%s\"", kind_cases[i].kw,
+                     kind_cases[i].arg);
+        munit_assert_int(n, >=, 0);
+        node = parse_one_node(src, &doc);
+        kind = st_check_kind_from_node(node, &err);
+        munit_assert_null(err);
+        munit_assert_int(kind, ==, kind_cases[i].kind);
+        st_kdl_document_free(doc);
+
+        /* full feature form validates clean (the schema HOOK path) */
+        n = snprintf(src, sizeof src,
+                     "project \"p\" version \"1.0\"\n"
+                     "feature \"f\" { %s \"%s\" }",
+                     kind_cases[i].kw, kind_cases[i].arg);
+        munit_assert_int(n, >=, 0);
+        assert_valid(src);
+    }
+    return MUNIT_OK;
+}
+
+/* (b) an unknown check kind errors with the node's name + span, both at
+ * the registry API and through schema validation; an empty node name and
+ * a NULL node also error. */
+static MunitResult
+test_unknown_kind(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc = NULL;
+    struct st_kdl_node *node;
+    enum st_check_kind kind;
+
+    /* registry API: bare unknown name */
+    node = parse_one_node("bogus \"x\"", &doc);
+    kind = st_check_kind_from_node(node, &err);
+    munit_assert_not_null(err);
+    munit_assert_int(kind, ==, ST_CHECK_KIND_COUNT);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+    munit_assert_not_null(err->span);
+    munit_assert_size(err->span->line, ==, 1);
+    munit_assert_size(err->span->col, ==, 1);
+    munit_assert_true(strstr(st_error_message(err), "'bogus'") != NULL);
+    st_error_free(err);
+    st_kdl_document_free(doc);
+
+    /* registry API: quoted unknown name */
+    node = parse_one_node("\"wat\" \"x\"", &doc);
+    kind = st_check_kind_from_node(node, &err);
+    munit_assert_not_null(err);
+    munit_assert_int(kind, ==, ST_CHECK_KIND_COUNT);
+    munit_assert_true(strstr(st_error_message(err), "'wat'") != NULL);
+    st_error_free(err);
+    st_kdl_document_free(doc);
+
+    /* schema end-to-end: the offending node + its span are named */
+    assert_schema_error("project \"p\" version \"1.0\"\n"
+                        "feature \"f\" { bogus \"x\" }",
+                        "'bogus'", 2, 15);
+
+    /* a hand-built node with an empty name token errors */
+    {
+        struct st_kdl_node empty = { 0 };
+
+        kind = st_check_kind_from_node(&empty, &err);
+        munit_assert_not_null(err);
+        munit_assert_int(kind, ==, ST_CHECK_KIND_COUNT);
+        munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+        munit_assert_not_null(err->span);
+        munit_assert_true(strstr(st_error_message(err), "empty name")
+                          != NULL);
+        st_error_free(err);
+    }
+
+    /* a NULL node errors without a span */
+    kind = st_check_kind_from_node(NULL, &err);
+    munit_assert_not_null(err);
+    munit_assert_int(kind, ==, ST_CHECK_KIND_COUNT);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+    munit_assert_null(err->span);
+    st_error_free(err);
+    return MUNIT_OK;
+}
+
+/* (c) a check without its required argument errors with the check node's
+ * span; an empty-string target is equally rejected. */
+static MunitResult
+test_missing_arg(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    assert_schema_error("project \"p\" version \"1.0\"\n"
+                        "feature \"f\" { header }",
+                        "check 'header' requires an argument", 2, 15);
+    assert_schema_error("project \"p\" version \"1.0\"\n"
+                        "feature \"f\" { library \"\" }",
+                        "must be a non-empty string", 2, 23);
+    return MUNIT_OK;
+}
+
+/* (d) the todo-9 fixture still validates clean end-to-end, and its
+ * feature children map to the expected kinds through the registry. */
+static MunitResult
+test_fixture_valid(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    const char *path = fixture_path();
+    char *src;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+    struct st_kdl_node *n;
+    enum st_check_kind expect[2] = { ST_CHECK_HEADER, ST_CHECK_LIBRARY };
+
+    munit_assert_not_null(path);
+    src = slurp_fixture(path);
+    munit_assert_not_null(src);
+
+    doc = st_kdl_parse(src, path, &err);
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+    munit_assert_null(st_kdl_validate(doc));
+
+    for (n = doc->nodes; n != NULL; n = n->next) {
+        if (n->name.kind == ST_TOK_IDENT && n->name.len == 7 &&
+            memcmp(n->name.text, "feature", 7) == 0) {
+            struct st_kdl_node *c;
+            size_t ci = 0;
+
+            for (c = n->children; c != NULL; c = c->next, ci++) {
+                enum st_check_kind kind;
+
+                if (ci == 0) {
+                    /* first child: `header` in pthread, `library` in math */
+                    if (c->name.kind == ST_TOK_IDENT &&
+                        c->name.len == 6 &&
+                        memcmp(c->name.text, "header", 6) == 0) {
+                        kind = st_check_kind_from_node(c, &err);
+                        munit_assert_null(err);
+                        munit_assert_int(kind, ==, ST_CHECK_HEADER);
+                    } else {
+                        kind = st_check_kind_from_node(c, &err);
+                        munit_assert_null(err);
+                        munit_assert_int(kind, ==, ST_CHECK_LIBRARY);
+                    }
+                } else {
+                    /* second child exists only in feature "pthread" */
+                    munit_assert_size(ci, ==, 1);
+                    kind = st_check_kind_from_node(c, &err);
+                    munit_assert_null(err);
+                    munit_assert_int(kind, ==, expect[ci]);
+                }
+            }
+        }
+    }
+
+    st_kdl_document_free(doc);
+    free(src);
+    return MUNIT_OK;
+}
+
+/* (e) required-arg enforcement per kind: each of the 8 kinds validates
+ * with its target argument, and fails - naming the check node - without
+ * it, with a wrong-typed target, with a second argument, or with a
+ * children block. */
+static MunitResult
+test_required_arg_per_kind(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    size_t i;
+
+    for (i = 0; i < st_check_kind_count(); i++) {
+        char src[192];
+        char needle[128];
+        int n;
+
+        /* missing target: span = the check name (col 15) */
+        n = snprintf(src, sizeof src,
+                     "project \"p\" version \"1.0\"\nfeature \"f\" { %s }",
+                     kind_cases[i].kw);
+        munit_assert_int(n, >=, 0);
+        n = snprintf(needle, sizeof needle, "check '%s' requires an argument",
+                     kind_cases[i].kw);
+        munit_assert_int(n, >=, 0);
+        assert_schema_error(src, needle, 2, 15);
+
+        /* wrong-typed target: number where a string belongs */
+        n = snprintf(src, sizeof src,
+                     "project \"p\" version \"1.0\"\nfeature \"f\" { %s 42 }",
+                     kind_cases[i].kw);
+        munit_assert_int(n, >=, 0);
+        n = snprintf(needle, sizeof needle,
+                     "check '%s' argument must be a non-empty string (got "
+                     "int)", kind_cases[i].kw);
+        munit_assert_int(n, >=, 0);
+        assert_schema_error(src, needle, 2, kind_cases[i].arg_col);
+
+        /* a second positional argument is rejected; for library and
+         * pkg_config it must be the literal `version` keyword */
+        n = snprintf(src, sizeof src,
+                     "project \"p\" version \"1.0\"\n"
+                     "feature \"f\" { %s \"x\" \"y\" }", kind_cases[i].kw);
+        munit_assert_int(n, >=, 0);
+        if (kind_cases[i].kind == ST_CHECK_LIBRARY ||
+            kind_cases[i].kind == ST_CHECK_PKG_CONFIG) {
+            n = snprintf(needle, sizeof needle,
+                         "check '%s': expected the keyword 'version'",
+                         kind_cases[i].kw);
+        } else {
+            n = snprintf(needle, sizeof needle,
+                         "check '%s' takes exactly one argument",
+                         kind_cases[i].kw);
+        }
+        munit_assert_int(n, >=, 0);
+        assert_schema_error(src, needle, 2, kind_cases[i].arg_col + 4);
+
+        /* a children block is rejected (child token at arg_col + 6) */
+        n = snprintf(src, sizeof src,
+                     "project \"p\" version \"1.0\"\n"
+                     "feature \"f\" { %s \"x\" { a } }", kind_cases[i].kw);
+        munit_assert_int(n, >=, 0);
+        n = snprintf(needle, sizeof needle, "check '%s' takes no children",
+                     kind_cases[i].kw);
+        munit_assert_int(n, >=, 0);
+        assert_schema_error(src, needle, 2, kind_cases[i].arg_col + 6);
+    }
+    return MUNIT_OK;
+}
+
+/* the optional `version` constraint on library/pkg_config: the literal
+ * `version` keyword followed by a non-empty unannotated string (spelled
+ * like the project node's version, todo 9's pinned decision). Other
+ * kinds reject any further argument, and NO check takes properties. */
+static MunitResult
+test_version_constraint(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    assert_valid("project \"p\" version \"1.0\"\n"
+                 "feature \"f\" { library \"curl\" version \">=7.0\" }");
+    assert_valid("project \"p\" version \"1.0\"\n"
+                 "feature \"f\" { pkg_config \"openssl\" version "
+                 "\">=1.1\" }");
+
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\nfeature \"f\" { library \"l\" "
+        "version }",
+        "'version' requires the version constraint argument", 2, 27);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\nfeature \"f\" { library \"l\" "
+        "version 42 }",
+        "version must be a non-empty string (got int)", 2, 35);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\nfeature \"f\" { library \"l\" "
+        "\"x\" }",
+        "expected the keyword 'version'", 2, 27);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\nfeature \"f\" { library \"l\" "
+        "version \"1\" \"x\" }",
+        "takes at most three arguments", 2, 39);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\nfeature \"f\" { header \"h.h\" "
+        "version \">=1\" }",
+        "takes exactly one argument", 2, 28);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\nfeature \"f\" { library \"l\" "
+        "version=\">=1\" }",
+        "has unexpected property 'version' (checks take no properties)",
+        2, 27);
+    return MUNIT_OK;
+}
+
+static MunitTest tests[] = {
+    { "/registry/all-kinds-map", test_all_kinds_map, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/registry/quoted-and-feature-forms", test_quoted_and_feature_forms,
+      NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/registry/unknown-kind", test_unknown_kind, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/registry/missing-arg", test_missing_arg, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/registry/fixture-valid", test_fixture_valid, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/registry/required-arg-per-kind", test_required_arg_per_kind, NULL,
+      NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/registry/version-constraint", test_version_constraint, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { NULL, NULL, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+};
+
+static const MunitSuite suite = {
+    "/registry", tests, NULL, 1, MUNIT_SUITE_OPTION_NONE,
+};
+
+int
+main(int argc, char *argv[MUNIT_ARRAY_PARAM(argc + 1)])
+{
+    return munit_suite_main(&suite, NULL, argc, argv);
+}

tests/unit/test_checks.c

@@ -0,0 +1,482 @@
+/* LINK: ../../src/detect/checks.c ../../src/detect/check_registry.c ../../src/kdl/schema.c ../../src/kdl/parser.c ../../src/kdl/lexer.c ../../src/kdl/value.c ../../src/error.c ../../src/span.c */
+
+#ifndef _POSIX_C_SOURCE
+#define _POSIX_C_SOURCE 200809L /* popen/pclose, sys/wait.h */
+#endif
+
+/*
+ * tests/unit/test_checks.c
+ *
+ * Unit tests for the check registry implementation (todo 11): for each of
+ * the 8 check kinds, src/detect/checks.c builds the exact PROBE SPEC
+ * (mode + C snippet + command argv + extra args) that todo 12 turns into
+ * configure-time compile/link/run/command invocations. This module builds
+ * specs ONLY - it never executes a probe and never emits shell text.
+ *
+ * The magic LINK comment on line 1 is REQUIRED by tests/run.sh: it lists
+ * the extra .c sources compiled into this test binary (paths relative to
+ * tests/unit/). checks.c needs check_registry.c (the shape table) + value.c
+ * (arg extraction); parser.c + lexer.c build documents end-to-end from
+ * source text; error.c + span.c via error.c's st_span_print; schema.c
+ * linked per the task's file list.
+ */
+#include "munit.h"
+
+#include "detect/check_registry.h"
+#include "detect/checks.h"
+#include "error.h"
+#include "kdl/ast.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/wait.h>
+
+/* ---- helpers ---------------------------------------------------------- */
+
+/* Parse a single-node document and return its one node (parse success is
+ * asserted). The caller frees the returned document. */
+static struct st_kdl_node *
+parse_one_node(const char *src, struct st_kdl_document **doc_out)
+{
+    struct st_error *err = NULL;
+
+    *doc_out = st_kdl_parse(src, "t.kdl", &err);
+    munit_assert_null(err);
+    munit_assert_not_null(*doc_out);
+    return (*doc_out)->nodes;
+}
+
+/* Parse `src` as a single check node, resolve its kind, and build its
+ * probe spec into `*out`. Asserts parse + kind resolution + build success
+ * and frees the document before returning (the probe is fully heap-owned
+ * and independent of the document). Returns the resolved kind. */
+static enum st_check_kind
+build_from(const char *src, struct st_check_probe *out)
+{
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc = NULL;
+    struct st_kdl_node *node;
+    enum st_check_kind kind;
+
+    node = parse_one_node(src, &doc);
+    kind = st_check_kind_from_node(node, &err);
+    munit_assert_null(err);
+    munit_assert_int(kind, !=, ST_CHECK_KIND_COUNT);
+    munit_assert_null(st_check_probe_build(kind, node, out));
+    st_kdl_document_free(doc);
+    return kind;
+}
+
+/* Compile `src` through a real cc on stdin (compile-only), with an
+ * optional leading flag ("" for none, or e.g. "-fno-builtin "). Returns
+ * the compiler's exit status, or -1 on any setup failure. The cc command
+ * is a fixed literal; `src` reaches cc via stdin, never via the shell. */
+static int
+cc_compile_stdin(const char *src, const char *flag)
+{
+    char cmd[256];
+    FILE *p;
+    int n;
+    int rc;
+    size_t len = strlen(src);
+
+    n = snprintf(cmd, sizeof cmd,
+        "cc -std=c23 -Wall -Wextra -Wpedantic %s-c -x c - -o /dev/null",
+        flag != NULL ? flag : "");
+    if (n < 0 || (size_t)n >= sizeof cmd) {
+        return -1;
+    }
+    p = popen(cmd, "w");
+    if (p == NULL) {
+        return -1;
+    }
+    if (fwrite(src, 1, len, p) != len) {
+        (void)pclose(p);
+        return -1;
+    }
+    rc = pclose(p);
+    if (rc == -1 || !WIFEXITED(rc)) {
+        return -1;
+    }
+    return WEXITSTATUS(rc);
+}
+
+/* ---- tests ------------------------------------------------------------ */
+
+/* (a) header "pthread.h" -> COMPILE probe whose source includes the
+ * header with the angle-bracket form. */
+static MunitResult
+test_header(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe p = { 0 };
+    enum st_check_kind kind = build_from("header \"pthread.h\"", &p);
+
+    munit_assert_int(kind, ==, ST_CHECK_HEADER);
+    munit_assert_int(p.mode, ==, ST_PROBE_COMPILE);
+    munit_assert_not_null(p.c_source);
+    munit_assert_true(strstr(p.c_source, "#include <pthread.h>") != NULL);
+    munit_assert_null(p.command);
+    munit_assert_null(p.extra_args);
+    munit_assert_null(p.version_constraint);
+    st_check_probe_free(&p);
+    return MUNIT_OK;
+}
+
+/* (b) function "strdup" -> LINK probe whose source declares and calls the
+ * symbol; -fno-builtin so GCC's builtin machinery can't reject/mis-type
+ * the declaration. */
+static MunitResult
+test_function(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe p = { 0 };
+    enum st_check_kind kind = build_from("function \"strdup\"", &p);
+
+    munit_assert_int(kind, ==, ST_CHECK_FUNCTION);
+    munit_assert_int(p.mode, ==, ST_PROBE_LINK);
+    munit_assert_not_null(p.c_source);
+    munit_assert_true(strstr(p.c_source, "extern void strdup(void)") != NULL);
+    munit_assert_true(strstr(p.c_source, "strdup();") != NULL);
+    munit_assert_not_null(p.extra_args);
+    munit_assert_string_equal(p.extra_args[0], "-fno-builtin");
+    munit_assert_null(p.extra_args[1]);
+    st_check_probe_free(&p);
+    return MUNIT_OK;
+}
+
+/* (c) library "pthread" -> LINK probe with extra_arg "-lpthread". */
+static MunitResult
+test_library(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe p = { 0 };
+    enum st_check_kind kind = build_from("library \"pthread\"", &p);
+
+    munit_assert_int(kind, ==, ST_CHECK_LIBRARY);
+    munit_assert_int(p.mode, ==, ST_PROBE_LINK);
+    munit_assert_not_null(p.c_source);
+    munit_assert_not_null(p.extra_args);
+    munit_assert_string_equal(p.extra_args[0], "-lpthread");
+    munit_assert_null(p.extra_args[1]);
+    munit_assert_null(p.version_constraint);
+    st_check_probe_free(&p);
+    return MUNIT_OK;
+}
+
+/* (d) type "size_t" -> COMPILE probe using sizeof(size_t) in a static
+ * assertion. */
+static MunitResult
+test_type(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe p = { 0 };
+    enum st_check_kind kind = build_from("type \"size_t\"", &p);
+
+    munit_assert_int(kind, ==, ST_CHECK_TYPE);
+    munit_assert_int(p.mode, ==, ST_PROBE_COMPILE);
+    munit_assert_not_null(p.c_source);
+    munit_assert_true(strstr(p.c_source, "sizeof(size_t)") != NULL);
+    munit_assert_true(strstr(p.c_source, "_Static_assert") != NULL);
+    st_check_probe_free(&p);
+    return MUNIT_OK;
+}
+
+/* (e) sizeof "long" -> RUN-capable probe: a _Static_assert sentinel plus a
+ * printf run path. */
+static MunitResult
+test_sizeof(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe p = { 0 };
+    enum st_check_kind kind = build_from("sizeof \"long\"", &p);
+
+    munit_assert_int(kind, ==, ST_CHECK_SIZEOF);
+    munit_assert_int(p.mode, ==, ST_PROBE_RUN);
+    munit_assert_not_null(p.c_source);
+    munit_assert_true(strstr(p.c_source, "sizeof(long)") != NULL);
+    munit_assert_true(strstr(p.c_source, "_Static_assert") != NULL);
+    munit_assert_true(strstr(p.c_source, "printf") != NULL);
+    st_check_probe_free(&p);
+    return MUNIT_OK;
+}
+
+/* (f) program "pkg-config" -> COMMAND argv {command, -v, pkg-config}. */
+static MunitResult
+test_program(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe p = { 0 };
+    enum st_check_kind kind = build_from("program \"pkg-config\"", &p);
+
+    munit_assert_int(kind, ==, ST_CHECK_PROGRAM);
+    munit_assert_int(p.mode, ==, ST_PROBE_COMMAND);
+    munit_assert_null(p.c_source);
+    munit_assert_not_null(p.command);
+    munit_assert_string_equal(p.command[0], "command");
+    munit_assert_string_equal(p.command[1], "-v");
+    munit_assert_string_equal(p.command[2], "pkg-config");
+    munit_assert_null(p.command[3]);
+    st_check_probe_free(&p);
+    return MUNIT_OK;
+}
+
+/* (g) compiler_flag "-fsanitize=address" -> COMPILE probe with the flag as
+ * an extra_arg. */
+static MunitResult
+test_compiler_flag(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe p = { 0 };
+    enum st_check_kind kind = build_from("compiler_flag \"-fsanitize=address\"",
+                                         &p);
+
+    munit_assert_int(kind, ==, ST_CHECK_COMPILER_FLAG);
+    munit_assert_int(p.mode, ==, ST_PROBE_COMPILE);
+    munit_assert_not_null(p.c_source);
+    munit_assert_not_null(p.extra_args);
+    munit_assert_string_equal(p.extra_args[0], "-fsanitize=address");
+    munit_assert_null(p.extra_args[1]);
+    st_check_probe_free(&p);
+    return MUNIT_OK;
+}
+
+/* (h) pkg_config "openssl" -> COMMAND argv {pkg-config, --cflags, --libs,
+ * openssl}. */
+static MunitResult
+test_pkg_config(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe p = { 0 };
+    enum st_check_kind kind = build_from("pkg_config \"openssl\"", &p);
+
+    munit_assert_int(kind, ==, ST_CHECK_PKG_CONFIG);
+    munit_assert_int(p.mode, ==, ST_PROBE_COMMAND);
+    munit_assert_null(p.c_source);
+    munit_assert_not_null(p.command);
+    munit_assert_string_equal(p.command[0], "pkg-config");
+    munit_assert_string_equal(p.command[1], "--cflags");
+    munit_assert_string_equal(p.command[2], "--libs");
+    munit_assert_string_equal(p.command[3], "openssl");
+    munit_assert_null(p.command[4]);
+    munit_assert_null(p.version_constraint);
+    st_check_probe_free(&p);
+    return MUNIT_OK;
+}
+
+/* The optional `version` constraint: library records it (and still links
+ * with plain -l); pkg_config maps >= to --atleast-version=. */
+static MunitResult
+test_version_constraints(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe lib = { 0 };
+    struct st_check_probe pk = { 0 };
+    struct st_check_probe pkeq = { 0 };
+
+    (void)build_from("library \"pthread\" version \">=2.0\"", &lib);
+    munit_assert_int(lib.mode, ==, ST_PROBE_LINK);
+    munit_assert_string_equal(lib.extra_args[0], "-lpthread");
+    munit_assert_string_equal(lib.version_constraint, ">=2.0");
+
+    (void)build_from("pkg_config \"openssl\" version \">=1.1\"", &pk);
+    munit_assert_int(pk.mode, ==, ST_PROBE_COMMAND);
+    munit_assert_string_equal(pk.command[0], "pkg-config");
+    munit_assert_string_equal(pk.command[1], "--atleast-version=1.1");
+    munit_assert_string_equal(pk.command[2], "--cflags");
+    munit_assert_string_equal(pk.command[3], "--libs");
+    munit_assert_string_equal(pk.command[4], "openssl");
+    munit_assert_null(pk.command[5]);
+    munit_assert_string_equal(pk.version_constraint, ">=1.1");
+
+    (void)build_from("pkg_config \"openssl\" version \"=1.2\"", &pkeq);
+    munit_assert_string_equal(pkeq.command[1], "--exact-version=1.2");
+
+    st_check_probe_free(&lib);
+    st_check_probe_free(&pk);
+    st_check_probe_free(&pkeq);
+    return MUNIT_OK;
+}
+
+/* A malformed version constraint (no operator) is rejected with a schema
+ * error naming the check. */
+static MunitResult
+test_malformed_constraint(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc = NULL;
+    struct st_kdl_node *node;
+    struct st_check_probe p = { 0 };
+
+    node = parse_one_node("library \"l\" version \"7.0\"", &doc);
+    err = st_check_probe_build(ST_CHECK_LIBRARY, node, &p);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+    munit_assert_true(strstr(st_error_message(err), "malformed version "
+                           "constraint") != NULL);
+    st_error_free(err);
+    st_kdl_document_free(doc);
+    return MUNIT_OK;
+}
+
+/* (j) unknown kind / NULL node / missing argument all error cleanly. */
+static MunitResult
+test_bad_input(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_check_probe p = { 0 };
+    struct st_kdl_document *doc = NULL;
+    struct st_kdl_node *node;
+
+    err = st_check_probe_build(ST_CHECK_KIND_COUNT, NULL, &p);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+    st_error_free(err);
+
+    err = st_check_probe_build(ST_CHECK_HEADER, NULL, &p);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+    st_error_free(err);
+
+    node = parse_one_node("header", &doc);
+    err = st_check_probe_build(ST_CHECK_HEADER, node, &p);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+    munit_assert_true(strstr(st_error_message(err), "requires an argument")
+                      != NULL);
+    st_error_free(err);
+    st_kdl_document_free(doc);
+    return MUNIT_OK;
+}
+
+/* (i) COMPILE-PROOF: three generated snippets actually compile under
+ * `cc -std=c23 -Wall -Wextra -Wpedantic -c -x c -` (exit 0); the function
+ * snippet additionally compiles clean with its own -fno-builtin arg. */
+static MunitResult
+test_compile_proof(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe hdr = { 0 };
+    struct st_check_probe lib = { 0 };
+    struct st_check_probe sz = { 0 };
+    struct st_check_probe fn = { 0 };
+
+    (void)build_from("header \"pthread.h\"", &hdr);
+    (void)build_from("library \"pthread\"", &lib);
+    (void)build_from("sizeof \"long\"", &sz);
+    (void)build_from("function \"strdup\"", &fn);
+
+    munit_assert_int(cc_compile_stdin(hdr.c_source, ""), ==, 0);
+    munit_assert_int(cc_compile_stdin(lib.c_source, ""), ==, 0);
+    munit_assert_int(cc_compile_stdin(sz.c_source, ""), ==, 0);
+    munit_assert_int(cc_compile_stdin(fn.c_source, "-fno-builtin "), ==, 0);
+
+    st_check_probe_free(&hdr);
+    st_check_probe_free(&lib);
+    st_check_probe_free(&sz);
+    st_check_probe_free(&fn);
+    return MUNIT_OK;
+}
+
+/* Adversarial: a header name with metacharacters yields a single-line
+ * quoted include (no injection, valid C); a non-identifier function name
+ * errors; a COMMAND probe carries its program name as ONE argv element. */
+static MunitResult
+test_adversarial(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe p = { 0 };
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc = NULL;
+    size_t len;
+
+    (void)build_from("header \"\\\"; rm -rf /\"", &p);
+    munit_assert_int(p.mode, ==, ST_PROBE_COMPILE);
+    munit_assert_true(strncmp(p.c_source, "#include \"", 10) == 0);
+    munit_assert_true(strstr(p.c_source, "rm -rf /") != NULL);
+    munit_assert_null(strchr(p.c_source, '<'));
+    len = strlen(p.c_source);
+    munit_assert_true(len >= 1);
+    munit_assert_true(p.c_source[len - 1] == '\n');
+    munit_assert_true(strchr(p.c_source, '\n') == &p.c_source[len - 1]);
+    st_check_probe_free(&p);
+
+    doc = st_kdl_parse("function \"foo bar\"", "t.kdl", &err);
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+    err = st_check_probe_build(ST_CHECK_FUNCTION, doc->nodes, &p);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+    munit_assert_true(strstr(st_error_message(err), "not a valid C "
+                           "identifier") != NULL);
+    st_error_free(err);
+    st_kdl_document_free(doc);
+
+    doc = NULL;
+    err = NULL;
+    doc = st_kdl_parse("program \"pkg-config; rm -rf /\"", "t.kdl", &err);
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+    munit_assert_null(st_check_probe_build(ST_CHECK_PROGRAM, doc->nodes, &p));
+    munit_assert_int(p.mode, ==, ST_PROBE_COMMAND);
+    munit_assert_string_equal(p.command[2], "pkg-config; rm -rf /");
+    munit_assert_null(p.command[3]);
+    st_check_probe_free(&p);
+    st_kdl_document_free(doc);
+    return MUNIT_OK;
+}
+
+static MunitTest tests[] = {
+    { "/checks/header", test_header, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { "/checks/function", test_function, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { "/checks/library", test_library, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { "/checks/type", test_type, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/checks/sizeof", test_sizeof, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { "/checks/program", test_program, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { "/checks/compiler-flag", test_compiler_flag, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/checks/pkg-config", test_pkg_config, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/checks/version-constraints", test_version_constraints, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/checks/malformed-constraint", test_malformed_constraint, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/checks/bad-input", test_bad_input, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { "/checks/compile-proof", test_compile_proof, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/checks/adversarial", test_adversarial, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { NULL, NULL, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+};
+
+static const MunitSuite suite = {
+    "/checks", tests, NULL, 1, MUNIT_SUITE_OPTION_NONE,
+};
+
+int
+main(int argc, char *argv[MUNIT_ARRAY_PARAM(argc + 1)])
+{
+    return munit_suite_main(&suite, NULL, argc, argv);
+}

tests/unit/test_discovery.c

@@ -0,0 +1,561 @@
+/* LINK: ../../src/ext/discovery.c ../../src/ext/lua.c ../../src/ext/abi.c ../../src/ext/lang_c.c ../../src/ext/lang_cpp.c ../../src/error.c ../../src/span.c ../../thirdparty/lua/lapi.c ../../thirdparty/lua/lauxlib.c ../../thirdparty/lua/lbaselib.c ../../thirdparty/lua/lcode.c ../../thirdparty/lua/lctype.c ../../thirdparty/lua/ldebug.c ../../thirdparty/lua/ldo.c ../../thirdparty/lua/ldump.c ../../thirdparty/lua/lfunc.c ../../thirdparty/lua/lgc.c ../../thirdparty/lua/llex.c ../../thirdparty/lua/lmem.c ../../thirdparty/lua/lobject.c ../../thirdparty/lua/lopcodes.c ../../thirdparty/lua/lparser.c ../../thirdparty/lua/lstate.c ../../thirdparty/lua/lstring.c ../../thirdparty/lua/ltable.c ../../thirdparty/lua/ltm.c ../../thirdparty/lua/lundump.c ../../thirdparty/lua/lvm.c ../../thirdparty/lua/lzio.c ../../thirdparty/lua/lstrlib.c ../../thirdparty/lua/ltablib.c */
+
+#ifndef _POSIX_C_SOURCE
+#define _POSIX_C_SOURCE 200809L /* mkdtemp, strdup */
+#endif
+
+/*
+ * tests/unit/test_discovery.c
+ *
+ * Unit tests for extension discovery and loading (src/ext/discovery.h,
+ * plan todo 20).
+ *
+ * The magic LINK comment on line 1 is REQUIRED by tests/run.sh: it
+ * lists the extra .c sources compiled into this test binary. It links
+ * discovery.c plus everything it needs -- the sandboxed Lua runtime
+ * (lua.c + the same 27 vendored Lua sources as test_lua.c, minus
+ * linit/lmathlib/loadlib/liolib/loslib/lua.c/luac.c, see the -lm note
+ * there), the extension ABI + builtin C/C++ modules, and error/span.
+ *
+ * Environment isolation: every test points XDG_DATA_HOME at an empty
+ * temp dir and unsets STUPIDTOOLS_EXT first, so host state can never
+ * leak into discovery. The builtin directory (builtin-ext relative to
+ * the cwd) ships no .lua modules in this todo, so it is a no-op as
+ * well; note that exact runtime-count assertions below assume that.
+ */
+#include "munit.h"
+
+#include "ext/abi.h"
+#include "ext/discovery.h"
+#include "ext/lua.h"
+
+#include <dirent.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+/* ---------- filesystem helpers ---------- */
+
+static char *
+make_temp_dir(void)
+{
+	char *d = strdup("/tmp/st_discovery_XXXXXX");
+
+	if (d == NULL || mkdtemp(d) == NULL) {
+		free(d);
+		return NULL;
+	}
+	return d;
+}
+
+static int
+write_file(const char *dir, const char *name, const char *content)
+{
+	char path[1024];
+	FILE *f;
+	size_t len = strlen(content);
+
+	if (snprintf(path, sizeof path, "%s/%s", dir, name) >=
+	    (int)sizeof path) {
+		return -1;
+	}
+	f = fopen(path, "wb");
+	if (f == NULL) return -1;
+	if (fwrite(content, 1, len, f) != len) {
+		(void)fclose(f);
+		return -1;
+	}
+	return fclose(f) == 0 ? 0 : -1;
+}
+
+static int
+write_bytes(const char *dir, const char *name, const unsigned char *bytes,
+            size_t len)
+{
+	char path[1024];
+	FILE *f;
+
+	if (snprintf(path, sizeof path, "%s/%s", dir, name) >=
+	    (int)sizeof path) {
+		return -1;
+	}
+	f = fopen(path, "wb");
+	if (f == NULL) return -1;
+	if (fwrite(bytes, 1, len, f) != len) {
+		(void)fclose(f);
+		return -1;
+	}
+	return fclose(f) == 0 ? 0 : -1;
+}
+
+/* Recursive delete (plain POSIX: unlink files, rmdir dirs). */
+static void
+rm_rf(const char *path)
+{
+	struct stat st;
+	DIR *d;
+	struct dirent *e;
+
+	if (lstat(path, &st) != 0) return;
+	if (!S_ISDIR(st.st_mode)) {
+		(void)unlink(path);
+		return;
+	}
+	d = opendir(path);
+	if (d == NULL) return;
+	while ((e = readdir(d)) != NULL) {
+		char sub[1024];
+
+		if (strcmp(e->d_name, ".") == 0 || strcmp(e->d_name, "..") == 0)
+			continue;
+		if (snprintf(sub, sizeof sub, "%s/%s", path, e->d_name) >=
+		    (int)sizeof sub)
+			continue;
+		rm_rf(sub);
+	}
+	(void)closedir(d);
+	(void)rmdir(path);
+}
+
+/* Fresh ctx + rt pair for one discovery run (discovery is one-shot per
+ * ctx: it re-runs the builtin init, so a second call would fail on
+ * duplicate registrations). */
+static int
+fresh_pair(struct st_ext_ctx **ctx, struct st_lua_rt **rt)
+{
+	*ctx = st_ext_ctx_new();
+	*rt = st_lua_rt_new();
+	return *ctx != NULL && *rt != NULL ? 0 : -1;
+}
+
+/* ---------- (a) a valid module registers into the runtime ---------- */
+
+static MunitResult
+test_valid_module(const MunitParameter params[], void *data)
+{
+	char *xdg = NULL;
+	char *ext = NULL;
+	struct st_ext_ctx *ctx = NULL;
+	struct st_lua_rt *rt = NULL;
+	struct st_error *err;
+	const char *dirs[1];
+
+	(void)params;
+	(void)data;
+
+	xdg = make_temp_dir();
+	ext = make_temp_dir();
+	munit_assert_not_null(xdg);
+	munit_assert_not_null(ext);
+	munit_assert_int(setenv("XDG_DATA_HOME", xdg, 1), ==, 0);
+	munit_assert_int(unsetenv("STUPIDTOOLS_EXT"), ==, 0);
+
+	munit_assert_int(write_file(ext, "hello.lua",
+	    "st.register_check(\"magic\")\n"
+	    "st.register_language(\"fortran\")\n"), ==, 0);
+
+	munit_assert_int(fresh_pair(&ctx, &rt), ==, 0);
+
+	dirs[0] = ext;
+	err = st_ext_discover(ctx, rt, dirs, 1);
+	munit_assert_null(err);
+
+	/* the module's registrations are enumerable from the runtime */
+	munit_assert_size(st_lua_check_count(rt), ==, 1);
+	munit_assert_string_equal(st_lua_check_name(rt, 0), "magic");
+	munit_assert_size(st_lua_language_count(rt), ==, 1);
+	munit_assert_string_equal(st_lua_language_name(rt, 0), "fortran");
+
+	/* the builtin C/C++ modules landed in the ABI ctx */
+	munit_assert_size(st_ext_language_count(ctx), ==, 2);
+	munit_assert_string_equal(st_ext_language_name(ctx, 0), "c");
+	munit_assert_string_equal(st_ext_language_name(ctx, 1), "cxx");
+
+	st_lua_rt_free(rt);
+	st_ext_ctx_free(ctx);
+	rm_rf(ext);
+	rm_rf(xdg);
+	free(ext);
+	free(xdg);
+	return MUNIT_OK;
+}
+
+/* ---------- (b) malformed module: clear error naming the file, fail-fast ---------- */
+
+static MunitResult
+test_malformed_fail_fast(const MunitParameter params[], void *data)
+{
+	char *xdg = NULL;
+	char *ext = NULL;
+	struct st_ext_ctx *ctx = NULL;
+	struct st_lua_rt *rt = NULL;
+	struct st_error *err;
+	const char *msg;
+	const char *dirs[1];
+
+	(void)params;
+	(void)data;
+
+	xdg = make_temp_dir();
+	ext = make_temp_dir();
+	munit_assert_not_null(xdg);
+	munit_assert_not_null(ext);
+	munit_assert_int(setenv("XDG_DATA_HOME", xdg, 1), ==, 0);
+	munit_assert_int(unsetenv("STUPIDTOOLS_EXT"), ==, 0);
+
+	munit_assert_int(write_file(ext, "bad.lua", "local x =\n"), ==, 0);
+	munit_assert_int(write_file(ext, "good.lua",
+	    "st.register_check(\"never\")\n"), ==, 0);
+
+	munit_assert_int(fresh_pair(&ctx, &rt), ==, 0);
+
+	dirs[0] = ext;
+	err = st_ext_discover(ctx, rt, dirs, 1);
+	munit_assert_not_null(err);
+	munit_assert_int(st_error_category_of(err), ==, ST_ERR_INTERNAL);
+	msg = st_error_message(err);
+	munit_assert_not_null(msg);
+	munit_assert_not_null(strstr(msg, "extension load failed"));
+	munit_assert_not_null(strstr(msg, "bad.lua"));
+	munit_assert_not_null(strstr(msg, ":2:")); /* file AND line named */
+
+	/* fail-fast: good.lua (which sorts after bad.lua) never ran */
+	munit_assert_size(st_lua_check_count(rt), ==, 0);
+	st_error_free(err);
+
+	st_lua_rt_free(rt);
+	st_ext_ctx_free(ctx);
+	rm_rf(ext);
+	rm_rf(xdg);
+	free(ext);
+	free(xdg);
+	return MUNIT_OK;
+}
+
+/* ---------- (c) a sandbox violation yields the sandbox error ---------- */
+
+static MunitResult
+test_sandbox_violation(const MunitParameter params[], void *data)
+{
+	char *xdg = NULL;
+	char *ext = NULL;
+	struct st_ext_ctx *ctx = NULL;
+	struct st_lua_rt *rt = NULL;
+	struct st_error *err;
+	const char *msg;
+	const char *dirs[1];
+
+	(void)params;
+	(void)data;
+
+	xdg = make_temp_dir();
+	ext = make_temp_dir();
+	munit_assert_not_null(xdg);
+	munit_assert_not_null(ext);
+	munit_assert_int(setenv("XDG_DATA_HOME", xdg, 1), ==, 0);
+	munit_assert_int(unsetenv("STUPIDTOOLS_EXT"), ==, 0);
+
+	munit_assert_int(write_file(ext, "evil.lua", "os.execute(\"id\")\n"),
+	    ==, 0);
+
+	munit_assert_int(fresh_pair(&ctx, &rt), ==, 0);
+
+	dirs[0] = ext;
+	err = st_ext_discover(ctx, rt, dirs, 1);
+	munit_assert_not_null(err);
+	munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+	msg = st_error_message(err);
+	munit_assert_not_null(msg);
+	munit_assert_not_null(strstr(msg, "sandbox blocked"));
+	munit_assert_not_null(strstr(msg, "evil.lua"));
+	st_error_free(err);
+
+	st_lua_rt_free(rt);
+	st_ext_ctx_free(ctx);
+	rm_rf(ext);
+	rm_rf(xdg);
+	free(ext);
+	free(xdg);
+	return MUNIT_OK;
+}
+
+/* ---------- (d) empty dir / missing dir / NULL dirs: clean no-op ---------- */
+
+static MunitResult
+test_empty_and_missing_dirs(const MunitParameter params[], void *data)
+{
+	char *xdg = NULL;
+	char *empty = NULL;
+	struct st_ext_ctx *ctx = NULL;
+	struct st_lua_rt *rt = NULL;
+	struct st_error *err;
+	const char *dirs[2];
+
+	(void)params;
+	(void)data;
+
+	xdg = make_temp_dir();
+	empty = make_temp_dir();
+	munit_assert_not_null(xdg);
+	munit_assert_not_null(empty);
+	munit_assert_int(setenv("XDG_DATA_HOME", xdg, 1), ==, 0);
+	munit_assert_int(unsetenv("STUPIDTOOLS_EXT"), ==, 0);
+
+	munit_assert_int(fresh_pair(&ctx, &rt), ==, 0);
+
+	/* a nonexistent dir and an empty dir are both silent no-ops */
+	dirs[0] = "/nonexistent/st_discovery_dir";
+	dirs[1] = empty;
+	err = st_ext_discover(ctx, rt, dirs, 2);
+	munit_assert_null(err);
+	munit_assert_size(st_lua_check_count(rt), ==, 0);
+	munit_assert_size(st_lua_language_count(rt), ==, 0);
+	munit_assert_size(st_ext_language_count(ctx), ==, 2); /* builtins only */
+
+	/* NULL/0 extra dirs are valid too (env + user + builtin only) */
+	st_lua_rt_free(rt);
+	st_ext_ctx_free(ctx);
+	munit_assert_int(fresh_pair(&ctx, &rt), ==, 0);
+	err = st_ext_discover(ctx, rt, NULL, 0);
+	munit_assert_null(err);
+	munit_assert_size(st_lua_check_count(rt), ==, 0);
+
+	/* discovery is one-shot per ctx: the builtin init re-runs and
+	 * duplicate registrations fail (documented contract) */
+	err = st_ext_discover(ctx, rt, NULL, 0);
+	munit_assert_not_null(err);
+	st_error_free(err);
+
+	st_lua_rt_free(rt);
+	st_ext_ctx_free(ctx);
+	rm_rf(empty);
+	rm_rf(xdg);
+	free(empty);
+	free(xdg);
+	return MUNIT_OK;
+}
+
+/* ---------- (e) a binary file named *.lua yields a load error ---------- */
+
+static MunitResult
+test_binary_file(const MunitParameter params[], void *data)
+{
+	static const unsigned char elf_head[] = { 0x7f, 'E', 'L', 'F', 0x02,
+	                                          0x01, 0x01 };
+	char *xdg = NULL;
+	char *ext = NULL;
+	struct st_ext_ctx *ctx = NULL;
+	struct st_lua_rt *rt = NULL;
+	struct st_error *err;
+	const char *msg;
+	const char *dirs[1];
+
+	(void)params;
+	(void)data;
+
+	xdg = make_temp_dir();
+	ext = make_temp_dir();
+	munit_assert_not_null(xdg);
+	munit_assert_not_null(ext);
+	munit_assert_int(setenv("XDG_DATA_HOME", xdg, 1), ==, 0);
+	munit_assert_int(unsetenv("STUPIDTOOLS_EXT"), ==, 0);
+
+	munit_assert_int(write_bytes(ext, "bin.lua", elf_head,
+	    sizeof elf_head), ==, 0);
+
+	munit_assert_int(fresh_pair(&ctx, &rt), ==, 0);
+
+	dirs[0] = ext;
+	err = st_ext_discover(ctx, rt, dirs, 1);
+	munit_assert_not_null(err);
+	msg = st_error_message(err);
+	munit_assert_not_null(msg);
+	munit_assert_not_null(strstr(msg, "extension load failed"));
+	munit_assert_not_null(strstr(msg, "bin.lua"));
+	st_error_free(err);
+
+	st_lua_rt_free(rt);
+	st_ext_ctx_free(ctx);
+	rm_rf(ext);
+	rm_rf(xdg);
+	free(ext);
+	free(xdg);
+	return MUNIT_OK;
+}
+
+/* ---------- (f) non-.lua entries (and a DIR named *.lua) are ignored ---------- */
+
+static MunitResult
+test_ignores_non_lua(const MunitParameter params[], void *data)
+{
+	char *xdg = NULL;
+	char *ext = NULL;
+	char sub[1024];
+	int sub_len;
+	struct st_ext_ctx *ctx = NULL;
+	struct st_lua_rt *rt = NULL;
+	struct st_error *err;
+	const char *dirs[1];
+
+	(void)params;
+	(void)data;
+
+	xdg = make_temp_dir();
+	ext = make_temp_dir();
+	munit_assert_not_null(xdg);
+	munit_assert_not_null(ext);
+	munit_assert_int(setenv("XDG_DATA_HOME", xdg, 1), ==, 0);
+	munit_assert_int(unsetenv("STUPIDTOOLS_EXT"), ==, 0);
+
+	munit_assert_int(write_file(ext, "notes.txt",
+	    "st.register_check(\"hidden\")\n"), ==, 0);
+	sub_len = snprintf(sub, sizeof sub, "%s/sub.lua", ext);
+	munit_assert_int(sub_len, >=, 0);
+	munit_assert_int(mkdir(sub, 0777), ==, 0);
+	munit_assert_int(write_file(ext, "sub.lua/inner.lua",
+	    "st.register_check(\"also-hidden\")\n"), ==, 0);
+
+	munit_assert_int(fresh_pair(&ctx, &rt), ==, 0);
+
+	dirs[0] = ext;
+	err = st_ext_discover(ctx, rt, dirs, 1);
+	munit_assert_null(err);
+	munit_assert_size(st_lua_check_count(rt), ==, 0);
+	munit_assert_size(st_lua_language_count(rt), ==, 0);
+
+	st_lua_rt_free(rt);
+	st_ext_ctx_free(ctx);
+	rm_rf(ext);
+	rm_rf(xdg);
+	free(ext);
+	free(xdg);
+	return MUNIT_OK;
+}
+
+/* ---------- (g) modules load in bytewise-lexicographic order ---------- */
+
+static MunitResult
+test_deterministic_order(const MunitParameter params[], void *data)
+{
+	char *xdg = NULL;
+	char *ext = NULL;
+	struct st_ext_ctx *ctx = NULL;
+	struct st_lua_rt *rt = NULL;
+	struct st_error *err;
+	const char *dirs[1];
+
+	(void)params;
+	(void)data;
+
+	xdg = make_temp_dir();
+	ext = make_temp_dir();
+	munit_assert_not_null(xdg);
+	munit_assert_not_null(ext);
+	munit_assert_int(setenv("XDG_DATA_HOME", xdg, 1), ==, 0);
+	munit_assert_int(unsetenv("STUPIDTOOLS_EXT"), ==, 0);
+
+	/* written in reverse order on purpose: discovery must sort */
+	munit_assert_int(write_file(ext, "b.lua",
+	    "st.register_check(\"second\")\n"), ==, 0);
+	munit_assert_int(write_file(ext, "a.lua",
+	    "st.register_check(\"first\")\n"), ==, 0);
+
+	munit_assert_int(fresh_pair(&ctx, &rt), ==, 0);
+
+	dirs[0] = ext;
+	err = st_ext_discover(ctx, rt, dirs, 1);
+	munit_assert_null(err);
+	munit_assert_size(st_lua_check_count(rt), ==, 2);
+	munit_assert_string_equal(st_lua_check_name(rt, 0), "first");
+	munit_assert_string_equal(st_lua_check_name(rt, 1), "second");
+
+	st_lua_rt_free(rt);
+	st_ext_ctx_free(ctx);
+	rm_rf(ext);
+	rm_rf(xdg);
+	free(ext);
+	free(xdg);
+	return MUNIT_OK;
+}
+
+/* ---------- (h) STUPIDTOOLS_EXT is honored, after the explicit dirs ---------- */
+
+static MunitResult
+test_env_dirs(const MunitParameter params[], void *data)
+{
+	char *xdg = NULL;
+	char *ext1 = NULL;
+	char *ext2 = NULL;
+	struct st_ext_ctx *ctx = NULL;
+	struct st_lua_rt *rt = NULL;
+	struct st_error *err;
+	const char *dirs[1];
+
+	(void)params;
+	(void)data;
+
+	xdg = make_temp_dir();
+	ext1 = make_temp_dir();
+	ext2 = make_temp_dir();
+	munit_assert_not_null(xdg);
+	munit_assert_not_null(ext1);
+	munit_assert_not_null(ext2);
+	munit_assert_int(setenv("XDG_DATA_HOME", xdg, 1), ==, 0);
+	munit_assert_int(setenv("STUPIDTOOLS_EXT", ext2, 1), ==, 0);
+
+	munit_assert_int(write_file(ext1, "one.lua",
+	    "st.register_check(\"one\")\n"), ==, 0);
+	munit_assert_int(write_file(ext2, "two.lua",
+	    "st.register_check(\"two\")\n"), ==, 0);
+
+	munit_assert_int(fresh_pair(&ctx, &rt), ==, 0);
+
+	dirs[0] = ext1;
+	err = st_ext_discover(ctx, rt, dirs, 1);
+	munit_assert_null(err);
+	munit_assert_size(st_lua_check_count(rt), ==, 2);
+	munit_assert_string_equal(st_lua_check_name(rt, 0), "one");
+	munit_assert_string_equal(st_lua_check_name(rt, 1), "two");
+
+	st_lua_rt_free(rt);
+	st_ext_ctx_free(ctx);
+	rm_rf(ext1);
+	rm_rf(ext2);
+	rm_rf(xdg);
+	free(ext1);
+	free(ext2);
+	free(xdg);
+	return MUNIT_OK;
+}
+
+static MunitTest tests[] = {
+    { "/discovery/valid-module", test_valid_module, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/discovery/malformed-fail-fast", test_malformed_fail_fast, NULL,
+      NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/discovery/sandbox-violation", test_sandbox_violation, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/discovery/empty-and-missing-dirs", test_empty_and_missing_dirs,
+      NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/discovery/binary-file", test_binary_file, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/discovery/ignores-non-lua", test_ignores_non_lua, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/discovery/deterministic-order", test_deterministic_order, NULL,
+      NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/discovery/env-dirs", test_env_dirs, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { NULL, NULL, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+};
+
+static const MunitSuite suite = {
+    "/discovery", tests, NULL, 1, MUNIT_SUITE_OPTION_NONE,
+};
+
+int
+main(int argc, char *argv[MUNIT_ARRAY_PARAM(argc + 1)])
+{
+    return munit_suite_main(&suite, NULL, argc, argv);
+}

tests/unit/test_error.c

@@ -0,0 +1,222 @@
+/* LINK: ../../src/error.c ../../src/span.c */
+/* tests/unit/test_error.c
+ *
+ * Unit tests for the error + source-span diagnostic infrastructure.
+ *
+ * The magic LINK comment on line 1 is REQUIRED by tests/run.sh: it lists
+ * the extra .c sources to compile into this test binary (paths relative
+ * to tests/unit/, space-separated). munit.c and the include dirs are
+ * added automatically by the harness.
+ */
+#include "munit.h"
+
+#include "error.h"
+#include "span.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* Render into a tmpfile and slurp it back into a NUL-terminated string.
+ * Returns NULL on any I/O failure. Caller frees with free(). */
+static char *
+capture(FILE *f)
+{
+    long n;
+    char *buf;
+
+    if (fseek(f, 0, SEEK_END) != 0) {
+        return NULL;
+    }
+    n = ftell(f);
+    if (n < 0 || fseek(f, 0, SEEK_SET) != 0) {
+        return NULL;
+    }
+    buf = munit_malloc((size_t)n + 1);
+    if (fread(buf, 1, (size_t)n, f) != (size_t)n) {
+        free(buf);
+        return NULL;
+    }
+    buf[n] = '\0';
+    return buf;
+}
+
+/* (a) the canonical span renders byte-for-byte per the plan's contract. */
+static MunitResult
+test_span_exact_rendering(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    const struct st_span span = { "file.kdl", 3, 5 };
+    FILE *f = tmpfile();
+    char *got;
+
+    munit_assert_not_null(f);
+    st_span_print(f, &span, "<msg>");
+    got = capture(f);
+    fclose(f);
+    munit_assert_not_null(got);
+    munit_assert_string_equal(got, "file.kdl:3:5: <msg>\n    ...^\n");
+    free(got);
+    return MUNIT_OK;
+}
+
+/* (b) a span at line 0 / col 0 renders without underflow: no crash,
+ * sane byte-exact output. */
+static MunitResult
+test_span_zero_coords_no_underflow(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    const struct st_span span = { "zero.kdl", 0, 0 };
+    FILE *f = tmpfile();
+    char *got;
+
+    munit_assert_not_null(f);
+    st_span_print(f, &span, "<msg>");
+    got = capture(f);
+    fclose(f);
+    munit_assert_not_null(got);
+    munit_assert_string_equal(got, "zero.kdl:0:0: <msg>\n    ...^\n");
+    free(got);
+    return MUNIT_OK;
+}
+
+/* (c) error categories round-trip through their constructors. */
+static MunitResult
+test_error_category_roundtrip(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *e = st_error_kdl_parse("<msg>");
+
+    munit_assert_not_null(e);
+    munit_assert_int(st_error_category_of(e), ==, ST_ERR_KDL_PARSE);
+    munit_assert_string_equal(st_error_message(e), "<msg>");
+    st_error_free(e);
+    return MUNIT_OK;
+}
+
+/* every category constructor tags its own category. */
+static MunitResult
+test_error_constructors(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *e;
+
+    e = st_error_kdl_schema("m");
+    munit_assert_int(st_error_category_of(e), ==, ST_ERR_KDL_SCHEMA);
+    st_error_free(e);
+
+    e = st_error_io("m");
+    munit_assert_int(st_error_category_of(e), ==, ST_ERR_IO);
+    st_error_free(e);
+
+    e = st_error_usage("m");
+    munit_assert_int(st_error_category_of(e), ==, ST_ERR_USAGE);
+    st_error_free(e);
+
+    e = st_error_internal("m");
+    munit_assert_int(st_error_category_of(e), ==, ST_ERR_INTERNAL);
+    st_error_free(e);
+
+    st_error_free(NULL); /* must be a safe no-op */
+    return MUNIT_OK;
+}
+
+/* category names exist, are non-empty, and are pairwise distinct. */
+static MunitResult
+test_error_category_names(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    int c;
+    const char *prev = NULL;
+
+    for (c = ST_ERR_KDL_PARSE; c <= ST_ERR_INTERNAL; c++) {
+        const char *n =
+            st_error_category_name((enum st_error_category)c);
+        munit_assert_not_null(n);
+        munit_assert_int(strlen(n), >, 0);
+        if (prev != NULL) {
+            munit_assert_string_not_equal(n, prev);
+        }
+        prev = n;
+    }
+    return MUNIT_OK;
+}
+
+/* st_error_print with a span renders span shape + category-prefixed msg. */
+static MunitResult
+test_error_print_with_span(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    const struct st_span span = { "file.kdl", 3, 5 };
+    struct st_error *e = st_error_at(st_error_kdl_parse("<msg>"), &span);
+    FILE *f = tmpfile();
+    char *got;
+
+    munit_assert_not_null(e);
+    munit_assert_not_null(f);
+    st_error_print(f, e);
+    got = capture(f);
+    fclose(f);
+    munit_assert_not_null(got);
+    munit_assert_string_equal(
+        got, "file.kdl:3:5: [kdl-parse] <msg>\n    ...^\n");
+    free(got);
+    st_error_free(e);
+    return MUNIT_OK;
+}
+
+/* st_error_print without a span renders category-prefixed message only. */
+static MunitResult
+test_error_print_without_span(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *e = st_error_io("disk on fire");
+    FILE *f = tmpfile();
+    char *got;
+
+    munit_assert_not_null(e);
+    munit_assert_not_null(f);
+    st_error_print(f, e);
+    got = capture(f);
+    fclose(f);
+    munit_assert_not_null(got);
+    munit_assert_string_equal(got, "[io] disk on fire\n");
+    free(got);
+    st_error_free(e);
+    return MUNIT_OK;
+}
+
+static MunitTest tests[] = {
+    { "/span/exact-rendering", test_span_exact_rendering, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/span/zero-coords-no-underflow", test_span_zero_coords_no_underflow,
+      NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/error/category-roundtrip", test_error_category_roundtrip, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/error/constructors", test_error_constructors, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/error/category-names", test_error_category_names, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/error/print-with-span", test_error_print_with_span, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/error/print-without-span", test_error_print_without_span, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { NULL, NULL, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+};
+
+static const MunitSuite suite = {
+    "/error", tests, NULL, 1, MUNIT_SUITE_OPTION_NONE,
+};
+
+int
+main(int argc, char *argv[MUNIT_ARRAY_PARAM(argc + 1)])
+{
+    return munit_suite_main(&suite, NULL, argc, argv);
+}

tests/unit/test_lexer.c

@@ -0,0 +1,624 @@
+/* LINK: ../../src/kdl/lexer.c ../../src/error.c ../../src/span.c */
+/* tests/unit/test_lexer.c
+ *
+ * Unit tests for the KDL 2.0.0 tokenizer (todo 6).
+ *
+ * The magic LINK comment on line 1 is REQUIRED by tests/run.sh: it lists
+ * the extra .c sources to compile into this test binary (paths relative
+ * to tests/unit/, space-separated). lexer.c depends on error.c (typed
+ * errors) and span.c (caret rendering), so all three are linked.
+ *
+ * These tests assert on REAL token streams — kind, span (line/col) and
+ * the text slice — never just "does not crash".
+ */
+#include "munit.h"
+
+#include "error.h"
+#include "kdl/lexer.h"
+
+#include <stdbool.h>
+#include <stdio.h>
+#include <string.h>
+
+#define MAX_TOKS 256
+#define MAX_TEXT 512
+
+/* A single captured token. `text` is a NUL-terminated copy of the lexer's
+ * text slice (which is otherwise not NUL-terminated). */
+struct captured_tok {
+    enum st_token_kind kind;
+    size_t line;
+    size_t col;
+    char text[MAX_TEXT];
+};
+
+/* A full captured stream. When the lexer hits an error, `had_error` is
+ * set and the error's category + span + message are copied out (values,
+ * not borrowed pointers) before the lexer is freed — this sidesteps the
+ * borrowed-span lifetime entirely inside the test. */
+struct capture {
+    struct captured_tok toks[MAX_TOKS];
+    size_t n;
+    bool had_error;
+    int err_category;
+    size_t err_line;
+    size_t err_col;
+    char err_msg[MAX_TEXT];
+};
+
+/* Tokenize `src` to completion. On a lex error the tokens produced before
+ * the error are still captured (and the error info is recorded). */
+static struct capture
+capture(const char *src)
+{
+    struct capture cap;
+    struct st_lexer *lx;
+    struct st_error *err = NULL;
+
+    memset(&cap, 0, sizeof cap);
+    lx = st_lexer_new(src, "test.kdl");
+    munit_assert_not_null(lx);
+
+    for (;;) {
+        struct st_token t;
+        enum st_token_kind k = st_lexer_next(lx, &t, &err);
+
+        if (k == ST_TOK_ERROR) {
+            cap.had_error = true;
+            if (err != NULL) {
+                cap.err_category = (int)st_error_category_of(err);
+                if (err->span != NULL) {
+                    cap.err_line = err->span->line;
+                    cap.err_col = err->span->col;
+                }
+                snprintf(cap.err_msg, sizeof cap.err_msg, "%s",
+                         st_error_message(err));
+                st_error_free(err);
+            }
+            break;
+        }
+
+        munit_assert_size(cap.n, <, MAX_TOKS);
+        cap.toks[cap.n].kind = k;
+        cap.toks[cap.n].line = t.span.line;
+        cap.toks[cap.n].col = t.span.col;
+        {
+            size_t len = t.len < MAX_TEXT - 1 ? t.len : MAX_TEXT - 1;
+            memcpy(cap.toks[cap.n].text, t.text, len);
+            cap.toks[cap.n].text[len] = '\0';
+        }
+        cap.n++;
+
+        if (k == ST_TOK_EOF) {
+            break;
+        }
+    }
+
+    st_lexer_free(lx);
+    return cap;
+}
+
+/* Assert token i is (kind, line, col, text). */
+static void
+assert_tok(const struct capture *cap, size_t i, enum st_token_kind kind,
+           size_t line, size_t col, const char *text)
+{
+    munit_assert_size(i, <, cap->n);
+    munit_assert_int(cap->toks[i].kind, ==, kind);
+    munit_assert_size(cap->toks[i].line, ==, line);
+    munit_assert_size(cap->toks[i].col, ==, col);
+    munit_assert_string_equal(cap->toks[i].text, text);
+}
+
+/* Assert a lex error occurred with the given (line, col) span. */
+static void
+assert_error(const struct capture *cap, size_t line, size_t col)
+{
+    munit_assert_true(cap->had_error);
+    munit_assert_int(cap->err_category, ==, ST_ERR_KDL_PARSE);
+    munit_assert_size(cap->err_line, ==, line);
+    munit_assert_size(cap->err_col, ==, col);
+}
+
+/* --- acceptance: the plan's canonical node ----------------------------- */
+static MunitResult
+test_acceptance_node(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("node 1 2 \"x\" key=\"v\" { child }");
+
+    munit_assert_false(cap.had_error);
+    assert_tok(&cap, 0, ST_TOK_IDENT, 1, 1, "node");
+    assert_tok(&cap, 1, ST_TOK_NUMBER, 1, 6, "1");
+    assert_tok(&cap, 2, ST_TOK_NUMBER, 1, 8, "2");
+    assert_tok(&cap, 3, ST_TOK_STRING, 1, 10, "\"x\"");
+    assert_tok(&cap, 4, ST_TOK_IDENT, 1, 14, "key");
+    assert_tok(&cap, 5, ST_TOK_EQUALS, 1, 17, "=");
+    assert_tok(&cap, 6, ST_TOK_STRING, 1, 18, "\"v\"");
+    assert_tok(&cap, 7, ST_TOK_LBRACE, 1, 22, "{");
+    assert_tok(&cap, 8, ST_TOK_IDENT, 1, 24, "child");
+    assert_tok(&cap, 9, ST_TOK_RBRACE, 1, 30, "}");
+    assert_tok(&cap, 10, ST_TOK_EOF, 1, 31, "");
+    munit_assert_size(cap.n, ==, 11);
+    return MUNIT_OK;
+}
+
+/* --- numbers: every radix + sign/float/exponent/underscore ------------ */
+static MunitResult
+test_numbers(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("0x10 0o17 0b101 123 3.14 1e10 1_000");
+
+    munit_assert_false(cap.had_error);
+    assert_tok(&cap, 0, ST_TOK_NUMBER, 1, 1, "0x10");
+    assert_tok(&cap, 1, ST_TOK_NUMBER, 1, 6, "0o17");
+    assert_tok(&cap, 2, ST_TOK_NUMBER, 1, 11, "0b101");
+    assert_tok(&cap, 3, ST_TOK_NUMBER, 1, 17, "123");
+    assert_tok(&cap, 4, ST_TOK_NUMBER, 1, 21, "3.14");
+    assert_tok(&cap, 5, ST_TOK_NUMBER, 1, 26, "1e10");
+    assert_tok(&cap, 6, ST_TOK_NUMBER, 1, 31, "1_000");
+    assert_tok(&cap, 7, ST_TOK_EOF, 1, 36, "");
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_signed_and_radix_numbers(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("-5 +7 -0x10 0XFF 0xff 1e-3");
+
+    munit_assert_false(cap.had_error);
+    assert_tok(&cap, 0, ST_TOK_NUMBER, 1, 1, "-5");
+    assert_tok(&cap, 1, ST_TOK_NUMBER, 1, 4, "+7");
+    assert_tok(&cap, 2, ST_TOK_NUMBER, 1, 7, "-0x10");
+    assert_tok(&cap, 3, ST_TOK_NUMBER, 1, 13, "0XFF");
+    assert_tok(&cap, 4, ST_TOK_NUMBER, 1, 18, "0xff");
+    assert_tok(&cap, 5, ST_TOK_NUMBER, 1, 23, "1e-3");
+    assert_tok(&cap, 6, ST_TOK_EOF, 1, 27, "");
+    return MUNIT_OK;
+}
+
+/* --- keyword numbers, booleans, null ---------------------------------- */
+static MunitResult
+test_keywords(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("#inf #-inf #nan #true #false #null");
+
+    munit_assert_false(cap.had_error);
+    assert_tok(&cap, 0, ST_TOK_INF, 1, 1, "#inf");
+    assert_tok(&cap, 1, ST_TOK_NEG_INF, 1, 6, "#-inf");
+    assert_tok(&cap, 2, ST_TOK_NAN, 1, 12, "#nan");
+    assert_tok(&cap, 3, ST_TOK_TRUE, 1, 17, "#true");
+    assert_tok(&cap, 4, ST_TOK_FALSE, 1, 23, "#false");
+    assert_tok(&cap, 5, ST_TOK_NULL, 1, 30, "#null");
+    assert_tok(&cap, 6, ST_TOK_EOF, 1, 35, "");
+    return MUNIT_OK;
+}
+
+/* --- type annotations -------------------------------------------------- */
+static MunitResult
+test_type_annotation(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("(u8)42 (published)date");
+
+    munit_assert_false(cap.had_error);
+    assert_tok(&cap, 0, ST_TOK_TYPE, 1, 1, "u8");
+    assert_tok(&cap, 1, ST_TOK_NUMBER, 1, 5, "42");
+    assert_tok(&cap, 2, ST_TOK_TYPE, 1, 8, "published");
+    assert_tok(&cap, 3, ST_TOK_IDENT, 1, 19, "date");
+    assert_tok(&cap, 4, ST_TOK_EOF, 1, 23, "");
+    return MUNIT_OK;
+}
+
+/* --- string forms: quoted, raw (single + double hash) ------------------ */
+static MunitResult
+test_strings_quoted_raw(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("\"hello\" #\"raw\"# ##\"raw2\"##");
+
+    munit_assert_false(cap.had_error);
+    assert_tok(&cap, 0, ST_TOK_STRING, 1, 1, "\"hello\"");
+    assert_tok(&cap, 1, ST_TOK_RAW_STRING, 1, 9, "#\"raw\"#");
+    assert_tok(&cap, 2, ST_TOK_RAW_STRING, 1, 17, "##\"raw2\"##");
+    assert_tok(&cap, 3, ST_TOK_EOF, 1, 27, "");
+    return MUNIT_OK;
+}
+
+/* --- multi-line string (delimiters only; dedent rules are todo 8) ------ */
+static MunitResult
+test_multiline_string(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("\"\"\"multi\"\"\"");
+
+    munit_assert_false(cap.had_error);
+    assert_tok(&cap, 0, ST_TOK_MULTILINE_STRING, 1, 1, "\"\"\"multi\"\"\"");
+    assert_tok(&cap, 1, ST_TOK_EOF, 1, 12, "");
+    return MUNIT_OK;
+}
+
+/* --- comments ---------------------------------------------------------- */
+static MunitResult
+test_line_comment(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("a // comment\nb");
+
+    munit_assert_false(cap.had_error);
+    assert_tok(&cap, 0, ST_TOK_IDENT, 1, 1, "a");
+    assert_tok(&cap, 1, ST_TOK_LINE_COMMENT, 1, 3, "// comment");
+    assert_tok(&cap, 2, ST_TOK_IDENT, 2, 1, "b");
+    assert_tok(&cap, 3, ST_TOK_EOF, 2, 2, "");
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_block_comment_nested(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("a /* x /* n */ */ b");
+
+    munit_assert_false(cap.had_error);
+    assert_tok(&cap, 0, ST_TOK_IDENT, 1, 1, "a");
+    assert_tok(&cap, 1, ST_TOK_BLOCK_COMMENT, 1, 3, "/* x /* n */ */");
+    assert_tok(&cap, 2, ST_TOK_IDENT, 1, 19, "b");
+    assert_tok(&cap, 3, ST_TOK_EOF, 1, 20, "");
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_slashdash(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("/- node");
+
+    munit_assert_false(cap.had_error);
+    assert_tok(&cap, 0, ST_TOK_SLASHDASH, 1, 1, "/-");
+    assert_tok(&cap, 1, ST_TOK_IDENT, 1, 4, "node");
+    assert_tok(&cap, 2, ST_TOK_EOF, 1, 8, "");
+    return MUNIT_OK;
+}
+
+/* --- structural tokens -------------------------------------------------- */
+static MunitResult
+test_semicolons_braces(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("a;b {c}");
+
+    munit_assert_false(cap.had_error);
+    assert_tok(&cap, 0, ST_TOK_IDENT, 1, 1, "a");
+    assert_tok(&cap, 1, ST_TOK_SEMICOLON, 1, 2, ";");
+    assert_tok(&cap, 2, ST_TOK_IDENT, 1, 3, "b");
+    assert_tok(&cap, 3, ST_TOK_LBRACE, 1, 5, "{");
+    assert_tok(&cap, 4, ST_TOK_IDENT, 1, 6, "c");
+    assert_tok(&cap, 5, ST_TOK_RBRACE, 1, 7, "}");
+    assert_tok(&cap, 6, ST_TOK_EOF, 1, 8, "");
+    return MUNIT_OK;
+}
+
+/* --- identifiers: sign / dotted / hyphen forms ------------------------- */
+static MunitResult
+test_ident_specials(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("--this .md foo-bar a+b _under");
+
+    munit_assert_false(cap.had_error);
+    assert_tok(&cap, 0, ST_TOK_IDENT, 1, 1, "--this");
+    assert_tok(&cap, 1, ST_TOK_IDENT, 1, 8, ".md");
+    assert_tok(&cap, 2, ST_TOK_IDENT, 1, 12, "foo-bar");
+    assert_tok(&cap, 3, ST_TOK_IDENT, 1, 20, "a+b");
+    assert_tok(&cap, 4, ST_TOK_IDENT, 1, 24, "_under");
+    assert_tok(&cap, 5, ST_TOK_EOF, 1, 30, "");
+    return MUNIT_OK;
+}
+
+/* --- bare keyword identifiers are syntax errors ------------------------ */
+static MunitResult
+test_bare_keywords_error(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    static const char *const bare[] = {
+        "inf", "-inf", "nan", "true", "false", "null",
+    };
+    size_t i;
+
+    for (i = 0; i < sizeof(bare) / sizeof(bare[0]); i++) {
+        struct capture cap = capture(bare[i]);
+        assert_error(&cap, 1, 1);
+    }
+
+    /* also rejected in position, with the span on the offending ident */
+    {
+        struct capture cap = capture("x inf");
+        assert_tok(&cap, 0, ST_TOK_IDENT, 1, 1, "x");
+        assert_error(&cap, 1, 3);
+    }
+    return MUNIT_OK;
+}
+
+/* --- unterminated strings (all three forms) ---------------------------- */
+static MunitResult
+test_unterminated_quoted(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("node \"unterminated");
+
+    assert_tok(&cap, 0, ST_TOK_IDENT, 1, 1, "node");
+    assert_error(&cap, 1, 6); /* span at the opening quote */
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_unterminated_raw(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("#\"unterminated");
+
+    assert_error(&cap, 1, 1); /* span at the opening '#' */
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_unterminated_multiline(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("\"\"\"multi");
+
+    assert_error(&cap, 1, 1); /* span at the opening '\"\"\"' */
+    return MUNIT_OK;
+}
+
+/* --- malformed numbers -------------------------------------------------- */
+static MunitResult
+test_bad_hex(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("0xZZ");
+
+    assert_error(&cap, 1, 1);
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_hex_no_digits(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("0x");
+
+    assert_error(&cap, 1, 1);
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_bad_octal_binary(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("0o8");
+
+    assert_error(&cap, 1, 1);
+
+    cap = capture("0b2");
+    assert_error(&cap, 1, 1);
+    return MUNIT_OK;
+}
+
+/* --- leading-dot numbers are errors ------------------------------------ */
+static MunitResult
+test_dot_number_error(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture(".5");
+
+    assert_error(&cap, 1, 1);
+    return MUNIT_OK;
+}
+
+/* --- invalid escape ----------------------------------------------------- */
+static MunitResult
+test_invalid_escape(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("\"\\q\"");
+
+    assert_error(&cap, 1, 1);
+    return MUNIT_OK;
+}
+
+/* --- stray '#' ---------------------------------------------------------- */
+static MunitResult
+test_hash_alone(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("#");
+
+    assert_error(&cap, 1, 1);
+
+    cap = capture("##foo");
+    assert_error(&cap, 1, 1);
+    return MUNIT_OK;
+}
+
+/* --- bad type annotation ------------------------------------------------ */
+static MunitResult
+test_bad_type_annotation(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("(u8");
+
+    assert_error(&cap, 1, 1);
+    return MUNIT_OK;
+}
+
+/* --- a stray '}' is a token, not a lexer error (nesting is todo 7) ----- */
+static MunitResult
+test_stray_brace_is_token(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("}");
+
+    munit_assert_false(cap.had_error);
+    assert_tok(&cap, 0, ST_TOK_RBRACE, 1, 1, "}");
+    assert_tok(&cap, 1, ST_TOK_EOF, 1, 2, "");
+    return MUNIT_OK;
+}
+
+/* --- hostile span: column well past 60 stays exact --------------------- */
+static MunitResult
+test_long_line_span(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    char src[256];
+
+    memset(src, ' ', 70);
+    memcpy(src + 70, "foo", 4);
+
+    {
+        struct capture cap = capture(src);
+        munit_assert_false(cap.had_error);
+        assert_tok(&cap, 0, ST_TOK_IDENT, 1, 71, "foo");
+        assert_tok(&cap, 1, ST_TOK_EOF, 1, 74, "");
+    }
+    return MUNIT_OK;
+}
+
+/* --- line/col tracking across newlines --------------------------------- */
+static MunitResult
+test_line_col_tracking(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct capture cap = capture("foo\n  bar");
+
+    munit_assert_false(cap.had_error);
+    assert_tok(&cap, 0, ST_TOK_IDENT, 1, 1, "foo");
+    assert_tok(&cap, 1, ST_TOK_IDENT, 2, 3, "bar");
+    assert_tok(&cap, 2, ST_TOK_EOF, 2, 6, "");
+
+    /* a multi-line string advances line/col for following tokens */
+    cap = capture("\"\"\"\nx\n\"\"\" tail");
+    munit_assert_false(cap.had_error);
+    assert_tok(&cap, 0, ST_TOK_MULTILINE_STRING, 1, 1, "\"\"\"\nx\n\"\"\"");
+    assert_tok(&cap, 1, ST_TOK_IDENT, 3, 5, "tail");
+    assert_tok(&cap, 2, ST_TOK_EOF, 3, 9, "");
+    return MUNIT_OK;
+}
+
+/* --- token kind names exist and are distinct --------------------------- */
+static MunitResult
+test_kind_names(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    const char *prev = NULL;
+    int k;
+
+    for (k = ST_TOK_EOF; k <= ST_TOK_SLASHDASH; k++) {
+        const char *n = st_token_kind_name((enum st_token_kind)k);
+        munit_assert_not_null(n);
+        munit_assert_int((int)strlen(n), >, 0);
+        if (prev != NULL) {
+            munit_assert_string_not_equal(n, prev);
+        }
+        prev = n;
+    }
+    return MUNIT_OK;
+}
+
+static MunitTest tests[] = {
+    { "/lexer/acceptance-node", test_acceptance_node, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/numbers", test_numbers, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/signed-radix-numbers", test_signed_and_radix_numbers, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/keywords", test_keywords, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/type-annotation", test_type_annotation, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/strings-quoted-raw", test_strings_quoted_raw, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/multiline-string", test_multiline_string, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/line-comment", test_line_comment, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/block-comment-nested", test_block_comment_nested, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/slashdash", test_slashdash, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/semicolons-braces", test_semicolons_braces, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/ident-specials", test_ident_specials, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/bare-keywords-error", test_bare_keywords_error, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/unterminated-quoted", test_unterminated_quoted, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/unterminated-raw", test_unterminated_raw, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/unterminated-multiline", test_unterminated_multiline, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/bad-hex", test_bad_hex, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/hex-no-digits", test_hex_no_digits, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/bad-octal-binary", test_bad_octal_binary, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/dot-number-error", test_dot_number_error, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/invalid-escape", test_invalid_escape, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/hash-alone", test_hash_alone, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/bad-type-annotation", test_bad_type_annotation, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/stray-brace-is-token", test_stray_brace_is_token, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/long-line-span", test_long_line_span, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/line-col-tracking", test_line_col_tracking, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lexer/kind-names", test_kind_names, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { NULL, NULL, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+};
+
+static const MunitSuite suite = {
+    "/lexer", tests, NULL, 1, MUNIT_SUITE_OPTION_NONE,
+};
+
+int
+main(int argc, char *argv[MUNIT_ARRAY_PARAM(argc + 1)])
+{
+    return munit_suite_main(&suite, NULL, argc, argv);
+}

tests/unit/test_lua.c

@@ -0,0 +1,295 @@
+/* LINK: ../../src/ext/lua.c ../../src/error.c ../../src/span.c ../../thirdparty/lua/lapi.c ../../thirdparty/lua/lauxlib.c ../../thirdparty/lua/lbaselib.c ../../thirdparty/lua/lcode.c ../../thirdparty/lua/lctype.c ../../thirdparty/lua/ldebug.c ../../thirdparty/lua/ldo.c ../../thirdparty/lua/ldump.c ../../thirdparty/lua/lfunc.c ../../thirdparty/lua/lgc.c ../../thirdparty/lua/llex.c ../../thirdparty/lua/lmem.c ../../thirdparty/lua/lobject.c ../../thirdparty/lua/lopcodes.c ../../thirdparty/lua/lparser.c ../../thirdparty/lua/lstate.c ../../thirdparty/lua/lstring.c ../../thirdparty/lua/ltable.c ../../thirdparty/lua/ltm.c ../../thirdparty/lua/lundump.c ../../thirdparty/lua/lvm.c ../../thirdparty/lua/lzio.c ../../thirdparty/lua/lstrlib.c ../../thirdparty/lua/ltablib.c */
+/* tests/unit/test_lua.c
+ *
+ * Unit tests for the embedded sandboxed Lua runtime (src/ext/lua.h,
+ * plan todo 19).
+ *
+ * The magic LINK comment on line 1 is REQUIRED by tests/run.sh: it lists
+ * the extra .c sources to compile into this test binary (paths relative
+ * to tests/unit/, space-separated). munit.c and the include dirs are
+ * added automatically by the harness.
+ *
+ * LINK LIST POLICY (the -lm trap):
+ *   The harness compiles with NO extra libraries -- in particular NO
+ *   -lm. Stock Lua needs libm in two ways: (1) lmathlib.c (sin/cos/pow/
+ *   log/...) and (2) the CORE itself (floor in lvm.c, frexp/fabs in
+ *   ltable.c, ldexp in lobject.c/lcode.c, fmod and pow via luaO_arith).
+ *   Therefore this test links:
+ *     - the 23 core .c files + lauxlib + lbaselib + lstrlib + ltablib;
+ *     - NOT lmathlib, linit (which references luaopen_math), loadlib
+ *       (package/require), liolib (io), loslib (we build our own
+ *       sandboxed os table), ldblib (debug), lcorolib, lutf8lib;
+ *     - NOT the lua.c / luac.c standalone mains.
+ *   The remaining core libm references are satisfied by portable
+ *   libm-free shims (fabs/floor/frexp/ldexp/fmod/pow) defined in
+ *   src/ext/lua.c itself -- the binary links with zero libm code.
+ */
+#include "munit.h"
+
+#include "ext/lua.h"
+
+#include <stdlib.h>
+#include <string.h>
+
+/* ---------- shared chunks ---------- */
+
+/* Registers one check and one language from Lua; every registration in
+ * this file must be visible through the C enumeration API afterwards. */
+static const char reg_chunk[] =
+    "st.register_check(\"magic\")\n"
+    "st.register_language(\"fortran\")\n";
+
+/* Every dangerous entry point must raise a "sandbox blocked:" error even
+ * when wrapped in pcall, and the module-loading / file-loading globals
+ * must not exist at all. */
+static const char audit_chunk[] =
+    "local function must_block(fn)\n"
+    "  local ok, err = pcall(fn)\n"
+    "  assert(ok == false, \"expected blocked call to succeed?\")\n"
+    "  assert(err:match(\"sandbox blocked\"), \"expected sandbox error, got: \" .. tostring(err))\n"
+    "end\n"
+    "must_block(function() os.execute(\"id\") end)\n"
+    "must_block(function() os.exit(0) end)\n"
+    "must_block(function() os.remove(\"/etc/passwd\") end)\n"
+    "must_block(function() os.rename(\"a\", \"b\") end)\n"
+    "assert(io == nil, \"io must not exist\")\n"
+    "assert(package == nil, \"package must not exist\")\n"
+    "assert(require == nil, \"require must not exist\")\n"
+    "assert(dofile == nil, \"dofile must not exist\")\n"
+    "assert(loadfile == nil, \"loadfile must not exist\")\n";
+
+/* The curated math library (libm-free subset) must work. */
+static const char math_chunk[] =
+    "assert(math.abs(-3) == 3)\n"
+    "assert(math.type(3) == \"integer\")\n"
+    "assert(math.type(1.5) == \"float\")\n"
+    "assert(math.tointeger(3.0) == 3)\n"
+    "assert(math.tointeger(1.5) == nil)\n"
+    "assert(math.max(1, 5, 3) == 5)\n"
+    "assert(math.min(2, -1) == -1)\n"
+    "assert(math.pi > 3.14 and math.pi < 3.15)\n"
+    "assert(math.huge > 1e300)\n";
+
+/* Operator smoke test for the libm-free shims inside src/ext/lua.c:
+ *   ^   -> pow    %   -> fmod    0x1p3  -> ldexp (compile-time folding)
+ *   float table keys -> frexp    math.tointeger -> floor
+ */
+static const char shim_chunk[] =
+    "assert(2.5 ^ 2 == 6.25)\n"
+    "assert(2.5 % 1.0 == 0.5)\n"
+    "assert(0x1p3 == 8.0)\n"
+    "assert(1e300 > 1e100)\n"
+    "local t = { [1.5] = \"x\" }\n"
+    "assert(t[1.5] == \"x\")\n"
+    "assert(string.format(\"%.1f\", 1.5) == \"1.5\")\n";
+
+/* ---------- (a) registrations land in the runtime's own registry ---------- */
+
+static MunitResult
+test_registration_visible(const MunitParameter params[], void *data)
+{
+    struct st_lua_rt *rt;
+    struct st_error *err;
+
+    (void)params;
+    (void)data;
+
+    rt = st_lua_rt_new();
+    munit_assert_not_null(rt);
+
+    err = st_lua_run(rt, reg_chunk, "=regtest");
+    munit_assert_null(err);
+
+    munit_assert_size(st_lua_check_count(rt), ==, 1);
+    munit_assert_string_equal(st_lua_check_name(rt, 0), "magic");
+    munit_assert_null(st_lua_check_probe_spec(rt, 0));
+    munit_assert_size(st_lua_language_count(rt), ==, 1);
+    munit_assert_string_equal(st_lua_language_name(rt, 0), "fortran");
+
+    /* C-side registration writes into the same registry (insertion
+     * order, so it is index 1). */
+    munit_assert_int(st_lua_register_check(rt, "via-c", NULL), ==, 0);
+    munit_assert_size(st_lua_check_count(rt), ==, 2);
+    munit_assert_string_equal(st_lua_check_name(rt, 0), "magic");
+    munit_assert_string_equal(st_lua_check_name(rt, 1), "via-c");
+
+    st_lua_rt_free(rt);
+    return MUNIT_OK;
+}
+
+/* ---------- (b) sandbox: os.execute & friends are blocked ---------- */
+
+static MunitResult
+test_sandbox_blocks_exec(const MunitParameter params[], void *data)
+{
+    struct st_lua_rt *rt;
+    struct st_error *err;
+    const char *msg;
+
+    (void)params;
+    (void)data;
+
+    rt = st_lua_rt_new();
+    munit_assert_not_null(rt);
+
+    /* direct call: error carries the actual block reason */
+    err = st_lua_run(rt, "os.execute(\"id\")", "=evil");
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+    msg = st_error_message(err);
+    munit_assert_not_null(msg);
+    munit_assert_not_null(strstr(msg, "sandbox blocked"));
+    munit_assert_not_null(strstr(msg, "os.execute"));
+    st_error_free(err);
+
+    /* pcall must not be an escape hatch: the call still fails, and the
+     * captured error still names the sandbox block. */
+    err = st_lua_run(rt,
+                     "local ok, e = pcall(os.execute, \"id\")\n"
+                     "assert(ok == false)\n"
+                     "assert(e:match(\"sandbox blocked\"))\n",
+                     "=evil-pcall");
+    munit_assert_null(err);
+
+    /* the rest of the dangerous surface, audited from inside the sandbox */
+    err = st_lua_run(rt, audit_chunk, "=audit");
+    munit_assert_null(err);
+
+    st_lua_rt_free(rt);
+    return MUNIT_OK;
+}
+
+/* ---------- (c) syntax errors yield a clean st_error ---------- */
+
+static MunitResult
+test_syntax_error_clean(const MunitParameter params[], void *data)
+{
+    struct st_lua_rt *rt;
+    struct st_error *err;
+    const char *msg;
+
+    (void)params;
+    (void)data;
+
+    rt = st_lua_rt_new();
+    munit_assert_not_null(rt);
+
+    err = st_lua_run(rt, "local x =", "broken.lua");
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_INTERNAL);
+    msg = st_error_message(err);
+    munit_assert_not_null(msg);
+    munit_assert_size(strlen(msg), >, 0);
+    munit_assert_not_null(strstr(msg, "broken.lua")); /* chunkname propagated */
+    st_error_free(err);
+
+    /* the runtime stays usable after an error */
+    err = st_lua_run(rt, "local y = 1", "=ok");
+    munit_assert_null(err);
+
+    st_lua_rt_free(rt);
+    return MUNIT_OK;
+}
+
+/* ---------- (d) math is allowed (curated, libm-free subset) ---------- */
+
+static MunitResult
+test_math_allowed(const MunitParameter params[], void *data)
+{
+    struct st_lua_rt *rt;
+    struct st_error *err;
+
+    (void)params;
+    (void)data;
+
+    rt = st_lua_rt_new();
+    munit_assert_not_null(rt);
+
+    err = st_lua_run(rt, math_chunk, "=math");
+    munit_assert_null(err);
+
+    st_lua_rt_free(rt);
+    return MUNIT_OK;
+}
+
+/* ---------- operator smoke for the libm-free shims ---------- */
+
+static MunitResult
+test_shims_through_operators(const MunitParameter params[], void *data)
+{
+    struct st_lua_rt *rt;
+    struct st_error *err;
+
+    (void)params;
+    (void)data;
+
+    rt = st_lua_rt_new();
+    munit_assert_not_null(rt);
+
+    err = st_lua_run(rt, shim_chunk, "=shims");
+    munit_assert_null(err);
+
+    st_lua_rt_free(rt);
+    return MUNIT_OK;
+}
+
+/* ---------- defensive API behavior: NULL args, duplicates ---------- */
+
+static MunitResult
+test_null_and_dup_defensive(const MunitParameter params[], void *data)
+{
+    struct st_lua_rt *rt;
+    struct st_error *err;
+
+    (void)params;
+    (void)data;
+
+    rt = st_lua_rt_new();
+    munit_assert_not_null(rt);
+
+    err = st_lua_run(rt, NULL, NULL);
+    munit_assert_not_null(err);
+    st_error_free(err);
+
+    munit_assert_int(st_lua_register_check(rt, NULL, NULL), ==, -1);
+    munit_assert_int(st_lua_register_language(rt, NULL), ==, -1);
+    munit_assert_int(st_lua_register_check(rt, "", NULL), ==, -1);
+
+    /* duplicates are rejected C-side and Lua-side */
+    munit_assert_int(st_lua_register_check(rt, "dup", NULL), ==, 0);
+    munit_assert_int(st_lua_register_check(rt, "dup", NULL), ==, -1);
+    err = st_lua_run(rt, "st.register_check(\"dup\")", "=dup");
+    munit_assert_not_null(err);
+    st_error_free(err);
+
+    /* freeing NULL is a no-op */
+    st_lua_rt_free(NULL);
+    st_lua_rt_free(rt);
+    return MUNIT_OK;
+}
+
+static MunitTest tests[] = {
+    { "/lua/registration-visible", test_registration_visible, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lua/sandbox-blocks-exec", test_sandbox_blocks_exec, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lua/syntax-error-clean", test_syntax_error_clean, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lua/math-allowed", test_math_allowed, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lua/shims-through-operators", test_shims_through_operators, NULL,
+      NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/lua/null-and-dup-defensive", test_null_and_dup_defensive, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { NULL, NULL, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+};
+
+static const MunitSuite suite = {
+    "/lua", tests, NULL, 1, MUNIT_SUITE_OPTION_NONE,
+};
+
+int
+main(int argc, char *argv[MUNIT_ARRAY_PARAM(argc + 1)])
+{
+    return munit_suite_main(&suite, NULL, argc, argv);
+}

tests/unit/test_parser.c

@@ -0,0 +1,690 @@
+/* LINK: ../../src/kdl/parser.c ../../src/kdl/lexer.c ../../src/error.c ../../src/span.c */
+/* tests/unit/test_parser.c
+ *
+ * Unit tests for the KDL 2.0.0 recursive-descent parser (todo 7).
+ *
+ * The magic LINK comment on line 1 is REQUIRED by tests/run.sh: it lists
+ * the extra .c sources to compile into this test binary (paths relative
+ * to tests/unit/, space-separated). parser.c depends on lexer.c (token
+ * stream), error.c (typed errors) and span.c (caret rendering).
+ *
+ * These tests assert on the REAL AST structure — node counts, argument
+ * and property order, children nesting, spans — never just "no crash".
+ * AST token slices are borrowed from the source buffer, so the source
+ * must outlive the document (both kept alive until st_kdl_document_free).
+ */
+#include "munit.h"
+
+#include "error.h"
+#include "kdl/ast.h"
+#include "kdl/lexer.h"
+#include "span.h"
+
+#include <stdbool.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* ---- fixture loading -------------------------------------------------- */
+
+/* Locate tests/fixtures/basic.kdl. The harness runs the test binary with
+ * cwd = repo top (make check) or tests/unit (manual run); probe both. */
+static const char *
+fixture_path(void)
+{
+    static const char *const candidates[] = {
+        "tests/fixtures/basic.kdl",
+        "../fixtures/basic.kdl",
+    };
+    size_t i;
+
+    for (i = 0; i < sizeof(candidates) / sizeof(candidates[0]); i++) {
+        FILE *f = fopen(candidates[i], "rb");
+        if (f != NULL) {
+            fclose(f);
+            return candidates[i];
+        }
+    }
+    return NULL;
+}
+
+/* Slurp the fixture into a NUL-terminated buffer (the lexer requires NUL
+ * termination). Returns NULL on any I/O failure. Caller frees. */
+static char *
+slurp_fixture(const char *path)
+{
+    FILE *f;
+    long n;
+    char *buf;
+
+    if (path == NULL) {
+        return NULL;
+    }
+    f = fopen(path, "rb");
+    if (f == NULL) {
+        return NULL;
+    }
+    if (fseek(f, 0, SEEK_END) != 0) {
+        fclose(f);
+        return NULL;
+    }
+    n = ftell(f);
+    if (n < 0 || fseek(f, 0, SEEK_SET) != 0) {
+        fclose(f);
+        return NULL;
+    }
+    buf = munit_malloc((size_t)n + 1);
+    if (fread(buf, 1, (size_t)n, f) != (size_t)n) {
+        free(buf);
+        fclose(f);
+        return NULL;
+    }
+    fclose(f);
+    buf[n] = '\0';
+    return buf;
+}
+
+/* ---- token-ref assertions --------------------------------------------- */
+
+static void
+assert_ref(const struct st_kdl_token_ref *ref, enum st_token_kind kind,
+           const char *text, size_t line, size_t col)
+{
+    munit_assert_not_null(ref);
+    munit_assert_int(ref->kind, ==, kind);
+    if (text != NULL) {
+        munit_assert_not_null(ref->text);
+        munit_assert_size(ref->len, ==, strlen(text));
+        munit_assert_memory_equal(ref->len, ref->text, text);
+    }
+    munit_assert_size(ref->span.line, ==, line);
+    munit_assert_size(ref->span.col, ==, col);
+}
+
+/* ---- tests ------------------------------------------------------------ */
+
+/* (a) tests/fixtures/basic.kdl parses to the expected AST: node count,
+ * names, arg order, prop key/value kinds, children nesting, spans. */
+static MunitResult
+test_parse_fixture(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    const char *path = fixture_path();
+    char *src;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+    struct st_kdl_node *n;
+    struct st_kdl_prop *p;
+
+    munit_assert_not_null(path);
+    src = slurp_fixture(path);
+    munit_assert_not_null(src);
+
+    doc = st_kdl_parse(src, path, &err);
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+
+    /* --- three top-level nodes: project, target, credits ------------- */
+    n = doc->nodes;
+    munit_assert_not_null(n);
+    assert_ref(&n->name, ST_TOK_IDENT, "project", 7, 1);
+
+    munit_assert_null(n->args);
+    p = n->props;
+    munit_assert_not_null(p);
+    assert_ref(&p->key, ST_TOK_IDENT, "name", 7, 9);
+    assert_ref(&p->value, ST_TOK_STRING, "\"stupidtools\"", 7, 14);
+    p = p->next;
+    munit_assert_not_null(p);
+    assert_ref(&p->key, ST_TOK_IDENT, "version", 7, 28);
+    assert_ref(&p->value, ST_TOK_STRING, "\"1.0.0\"", 7, 36);
+    munit_assert_null(p->next);
+
+    /* --- target "default" with 6 children ---------------------------- */
+    n = n->next;
+    munit_assert_not_null(n);
+    assert_ref(&n->name, ST_TOK_IDENT, "target", 9, 1);
+    munit_assert_not_null(n->args);
+    assert_ref(&n->args->value, ST_TOK_STRING, "\"default\"", 9, 8);
+    munit_assert_null(n->args->next);
+    munit_assert_null(n->props);
+
+    {
+        struct st_kdl_node *c = n->children;
+
+        /* child 1: src "src/main.c" */
+        munit_assert_not_null(c);
+        assert_ref(&c->name, ST_TOK_IDENT, "src", 10, 5);
+        munit_assert_not_null(c->args);
+        assert_ref(&c->args->value, ST_TOK_STRING, "\"src/main.c\"", 10, 9);
+        munit_assert_null(c->args->next);
+
+        /* child 2: src "src/kdl/lexer.c" (after ';') */
+        c = c->next;
+        munit_assert_not_null(c);
+        assert_ref(&c->name, ST_TOK_IDENT, "src", 10, 24);
+        assert_ref(&c->args->value, ST_TOK_STRING, "\"src/kdl/lexer.c\"", 10,
+                   28);
+        munit_assert_null(c->args->next);
+
+        /* child 3: cc-flags "-std=c23" "-Wall" */
+        c = c->next;
+        munit_assert_not_null(c);
+        assert_ref(&c->name, ST_TOK_IDENT, "cc-flags", 11, 5);
+        munit_assert_not_null(c->args);
+        assert_ref(&c->args->value, ST_TOK_STRING, "\"-std=c23\"", 11, 14);
+        assert_ref(&c->args->next->value, ST_TOK_STRING, "\"-Wall\"", 11, 25);
+        munit_assert_null(c->args->next->next);
+
+        /* child 4: jobs 8 */
+        c = c->next;
+        munit_assert_not_null(c);
+        assert_ref(&c->name, ST_TOK_IDENT, "jobs", 12, 5);
+        assert_ref(&c->args->value, ST_TOK_NUMBER, "8", 12, 10);
+        munit_assert_null(c->args->next);
+
+        /* child 5: optimize #true debug=#false */
+        c = c->next;
+        munit_assert_not_null(c);
+        assert_ref(&c->name, ST_TOK_IDENT, "optimize", 13, 5);
+        assert_ref(&c->args->value, ST_TOK_TRUE, "#true", 13, 14);
+        munit_assert_null(c->args->next);
+        munit_assert_not_null(c->props);
+        assert_ref(&c->props->key, ST_TOK_IDENT, "debug", 13, 20);
+        assert_ref(&c->props->value, ST_TOK_FALSE, "#false", 13, 26);
+        munit_assert_null(c->props->next);
+
+        /* child 6: feature "unit-tests" { option "munit" { default #true } } */
+        c = c->next;
+        munit_assert_not_null(c);
+        assert_ref(&c->name, ST_TOK_IDENT, "feature", 14, 5);
+        assert_ref(&c->args->value, ST_TOK_STRING, "\"unit-tests\"", 14, 13);
+        munit_assert_null(c->args->next);
+        munit_assert_not_null(c->children);
+        assert_ref(&c->children->name, ST_TOK_IDENT, "option", 15, 9);
+        assert_ref(&c->children->args->value, ST_TOK_STRING, "\"munit\"", 15,
+                   16);
+        munit_assert_not_null(c->children->children);
+        assert_ref(&c->children->children->name, ST_TOK_IDENT, "default", 15,
+                   26);
+        assert_ref(&c->children->children->args->value, ST_TOK_TRUE, "#true",
+                   15, 34);
+        munit_assert_null(c->children->children->args->next);
+        munit_assert_null(c->next);
+    }
+
+    /* --- credits with type annotation (meta) -------------------------- */
+    n = n->next;
+    munit_assert_not_null(n);
+    munit_assert_not_null(n->type);
+    /* the TYPE token's span starts at the opening '('; its text slice is
+     * the inner identifier without the parens (see lexer.h) */
+    assert_ref(n->type, ST_TOK_TYPE, "meta", 21, 1);
+    assert_ref(&n->name, ST_TOK_IDENT, "credits", 21, 7);
+    assert_ref(&n->args->value, ST_TOK_STRING, "\"huntedbytheirs\"", 21, 15);
+    munit_assert_null(n->args->next);
+    munit_assert_null(n->props);
+    munit_assert_null(n->next);
+
+    st_kdl_document_free(doc);
+    free(src);
+    return MUNIT_OK;
+}
+
+/* (b) `node {` — unterminated children block errors with the span of the
+ * `{` token. */
+static MunitResult
+test_unterminated_children(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    const char *src = "node {";
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+
+    doc = st_kdl_parse(src, "t.kdl", &err);
+    munit_assert_null(doc);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_PARSE);
+    /* the span must point at the `{` (line 1, col 6), not at EOF */
+    munit_assert_not_null(err->span);
+    munit_assert_size(err->span->line, ==, 1);
+    munit_assert_size(err->span->col, ==, 6);
+    munit_assert_true(strstr(st_error_message(err), "children") != NULL);
+    st_error_free(err);
+    return MUNIT_OK;
+}
+
+/* (c) a stray `}` at top level errors with the span of the `}`. */
+static MunitResult
+test_stray_rbrace(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+
+    doc = st_kdl_parse("}", "t.kdl", &err);
+    munit_assert_null(doc);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_PARSE);
+    munit_assert_not_null(err->span);
+    munit_assert_size(err->span->line, ==, 1);
+    munit_assert_size(err->span->col, ==, 1);
+    st_error_free(err);
+
+    /* also stray inside a completed children block: `node { child } }` */
+    err = NULL;
+    doc = st_kdl_parse("node { child } }", "t.kdl", &err);
+    munit_assert_null(doc);
+    munit_assert_not_null(err);
+    munit_assert_size(err->span->col, ==, 16);
+    st_error_free(err);
+    return MUNIT_OK;
+}
+
+/* (d) prop classification: a token followed by `=` is a key, the next
+ * value token is its value; bare values are args, in source order. */
+static MunitResult
+test_prop_classification(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+    struct st_kdl_node *n;
+    struct st_kdl_arg *a;
+    struct st_kdl_prop *p;
+
+    doc = st_kdl_parse("node key=value key2=\"v2\" 1 2 #true", "t.kdl", &err);
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+    n = doc->nodes;
+    munit_assert_not_null(n);
+    munit_assert_null(n->next);
+
+    p = n->props;
+    munit_assert_not_null(p);
+    assert_ref(&p->key, ST_TOK_IDENT, "key", 1, 6);
+    assert_ref(&p->value, ST_TOK_IDENT, "value", 1, 10);
+    p = p->next;
+    munit_assert_not_null(p);
+    assert_ref(&p->key, ST_TOK_IDENT, "key2", 1, 16);
+    assert_ref(&p->value, ST_TOK_STRING, "\"v2\"", 1, 21);
+    munit_assert_null(p->next);
+
+    a = n->args;
+    munit_assert_not_null(a);
+    assert_ref(&a->value, ST_TOK_NUMBER, "1", 1, 26);
+    a = a->next;
+    munit_assert_not_null(a);
+    assert_ref(&a->value, ST_TOK_NUMBER, "2", 1, 28);
+    a = a->next;
+    munit_assert_not_null(a);
+    assert_ref(&a->value, ST_TOK_TRUE, "#true", 1, 30);
+    munit_assert_null(a->next);
+
+    st_kdl_document_free(doc);
+    return MUNIT_OK;
+}
+
+/* (e) interleaved args/props keep their relative order within each list:
+ * `node a=1 b c=2 d` -> args [b, d], props [a=1, c=2]. */
+static MunitResult
+test_interleaved_order(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+    struct st_kdl_node *n;
+
+    doc = st_kdl_parse("node a=1 b c=2 d", "t.kdl", &err);
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+    n = doc->nodes;
+    munit_assert_not_null(n);
+
+    /* args, in order: b then d */
+    munit_assert_not_null(n->args);
+    assert_ref(&n->args->value, ST_TOK_IDENT, "b", 1, 10);
+    assert_ref(&n->args->next->value, ST_TOK_IDENT, "d", 1, 16);
+    munit_assert_null(n->args->next->next);
+
+    /* props, in order: a=1 then c=2 */
+    munit_assert_not_null(n->props);
+    assert_ref(&n->props->key, ST_TOK_IDENT, "a", 1, 6);
+    assert_ref(&n->props->value, ST_TOK_NUMBER, "1", 1, 8);
+    assert_ref(&n->props->next->key, ST_TOK_IDENT, "c", 1, 12);
+    assert_ref(&n->props->next->value, ST_TOK_NUMBER, "2", 1, 14);
+    munit_assert_null(n->props->next->next);
+
+    st_kdl_document_free(doc);
+    return MUNIT_OK;
+}
+
+/* (f) newline terminates a node: `a 1\nb 2` is two nodes, not one node
+ * with four entries. */
+static MunitResult
+test_newline_separates_nodes(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+    struct st_kdl_node *n;
+
+    doc = st_kdl_parse("a 1\nb 2", "t.kdl", &err);
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+
+    n = doc->nodes;
+    munit_assert_not_null(n);
+    assert_ref(&n->name, ST_TOK_IDENT, "a", 1, 1);
+    assert_ref(&n->args->value, ST_TOK_NUMBER, "1", 1, 3);
+    munit_assert_null(n->args->next);
+
+    n = n->next;
+    munit_assert_not_null(n);
+    assert_ref(&n->name, ST_TOK_IDENT, "b", 2, 1);
+    assert_ref(&n->args->value, ST_TOK_NUMBER, "2", 2, 3);
+    munit_assert_null(n->args->next);
+    munit_assert_null(n->next);
+
+    st_kdl_document_free(doc);
+    return MUNIT_OK;
+}
+
+/* (g) semicolons separate nodes; repeated separators are trivia. */
+static MunitResult
+test_semicolon_separators(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+    struct st_kdl_node *n;
+    size_t count = 0;
+
+    doc = st_kdl_parse("node ; ; node", "t.kdl", &err);
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+
+    for (n = doc->nodes; n != NULL; n = n->next) {
+        assert_ref(&n->name, ST_TOK_IDENT, "node", 1,
+                   (size_t)(count == 0 ? 1 : 10));
+        count++;
+    }
+    munit_assert_size(count, ==, 2);
+
+    st_kdl_document_free(doc);
+    return MUNIT_OK;
+}
+
+/* (h) an empty document parses to a document with zero nodes. */
+static MunitResult
+test_empty_document(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+
+    doc = st_kdl_parse("", "t.kdl", &err);
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+    munit_assert_null(doc->nodes);
+    st_kdl_document_free(doc);
+
+    /* whitespace/comment-only is also an empty document */
+    err = NULL;
+    doc = st_kdl_parse("  // nothing\n/* nor here */\n/- ;", "t.kdl", &err);
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+    munit_assert_null(doc->nodes);
+    st_kdl_document_free(doc);
+    return MUNIT_OK;
+}
+
+/* (i) `node = x` is invalid: the node name cannot be a property key. */
+static MunitResult
+test_equals_after_name(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+
+    doc = st_kdl_parse("node = x", "t.kdl", &err);
+    munit_assert_null(doc);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_PARSE);
+    munit_assert_not_null(err->span);
+    munit_assert_size(err->span->line, ==, 1);
+    munit_assert_size(err->span->col, ==, 6);
+    st_error_free(err);
+
+    /* a non-string value before `=` is equally invalid: `node 1 = 2` */
+    err = NULL;
+    doc = st_kdl_parse("node 1 = 2", "t.kdl", &err);
+    munit_assert_null(doc);
+    munit_assert_not_null(err);
+    munit_assert_size(err->span->col, ==, 8);
+    st_error_free(err);
+    return MUNIT_OK;
+}
+
+/* (j) a property needs a value: `node key =` errors at EOF; `node key = {`
+ * errors at the `{`. */
+static MunitResult
+test_prop_missing_value(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+
+    doc = st_kdl_parse("node key =", "t.kdl", &err);
+    munit_assert_null(doc);
+    munit_assert_not_null(err);
+    munit_assert_true(strstr(st_error_message(err), "value") != NULL);
+    munit_assert_not_null(err->span);
+    munit_assert_size(err->span->col, ==, 11);
+    st_error_free(err);
+
+    err = NULL;
+    doc = st_kdl_parse("node key = {", "t.kdl", &err);
+    munit_assert_null(doc);
+    munit_assert_not_null(err);
+    munit_assert_true(strstr(st_error_message(err), "value") != NULL);
+    munit_assert_size(err->span->col, ==, 12);
+    st_error_free(err);
+    return MUNIT_OK;
+}
+
+/* (k) a lexer error is propagated with its span, copied into owned
+ * storage: the span must still be readable after st_kdl_parse returns. */
+static MunitResult
+test_lexer_error_propagates(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+
+    doc = st_kdl_parse("node \"unterminated", "t.kdl", &err);
+    munit_assert_null(doc);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_PARSE);
+    munit_assert_not_null(err->span);
+    munit_assert_size(err->span->line, ==, 1);
+    munit_assert_size(err->span->col, ==, 6);
+    munit_assert_true(strstr(st_error_message(err), "unterminated") != NULL);
+    st_error_free(err);
+    return MUNIT_OK;
+}
+
+/* (l) type annotation attaches to the node name; quoted node names and
+ * string keys work. */
+static MunitResult
+test_annotation_and_string_names(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+    struct st_kdl_node *n;
+
+    doc = st_kdl_parse("(u8)size 4\n\"quoted node\" x\np \"k s\"=1", "t.kdl",
+                       &err);
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+
+    n = doc->nodes;
+    munit_assert_not_null(n);
+    munit_assert_not_null(n->type);
+    assert_ref(n->type, ST_TOK_TYPE, "u8", 1, 1);
+    assert_ref(&n->name, ST_TOK_IDENT, "size", 1, 5);
+    assert_ref(&n->args->value, ST_TOK_NUMBER, "4", 1, 10);
+    munit_assert_null(n->args->next);
+
+    n = n->next;
+    munit_assert_not_null(n);
+    assert_ref(&n->name, ST_TOK_STRING, "\"quoted node\"", 2, 1);
+    assert_ref(&n->args->value, ST_TOK_IDENT, "x", 2, 15);
+    munit_assert_null(n->args->next);
+
+    n = n->next;
+    munit_assert_not_null(n);
+    assert_ref(&n->name, ST_TOK_IDENT, "p", 3, 1);
+    munit_assert_not_null(n->props);
+    assert_ref(&n->props->key, ST_TOK_STRING, "\"k s\"", 3, 3);
+    assert_ref(&n->props->value, ST_TOK_NUMBER, "1", 3, 9);
+    munit_assert_null(n->props->next);
+    munit_assert_null(n->next);
+
+    st_kdl_document_free(doc);
+    return MUNIT_OK;
+}
+
+/* (m) single-line children blocks and nested blocks parse recursively. */
+static MunitResult
+test_children_nesting(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+    struct st_kdl_node *n;
+
+    doc = st_kdl_parse("p { a; b; c { d } }", "t.kdl", &err);
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+
+    n = doc->nodes;
+    munit_assert_not_null(n);
+    assert_ref(&n->name, ST_TOK_IDENT, "p", 1, 1);
+    munit_assert_not_null(n->children);
+    assert_ref(&n->children->name, ST_TOK_IDENT, "a", 1, 5);
+    assert_ref(&n->children->next->name, ST_TOK_IDENT, "b", 1, 8);
+    assert_ref(&n->children->next->next->name, ST_TOK_IDENT, "c", 1, 11);
+    munit_assert_not_null(n->children->next->next->children);
+    assert_ref(&n->children->next->next->children->name, ST_TOK_IDENT, "d",
+               1, 15);
+    munit_assert_null(n->children->next->next->next);
+    munit_assert_null(n->next);
+
+    st_kdl_document_free(doc);
+    return MUNIT_OK;
+}
+
+/* (n) `/-` and comments are trivia: a slashdash between entries vanishes,
+ * and a node ends at the slashdash/semicolon regardless of line. */
+static MunitResult
+test_trivia_skipped(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+    struct st_kdl_node *n;
+    size_t count = 0;
+
+    doc = st_kdl_parse("node a=1 /-\n; // still trivia\nb", "t.kdl", &err);
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+
+    n = doc->nodes;
+    munit_assert_not_null(n);
+    assert_ref(&n->name, ST_TOK_IDENT, "node", 1, 1);
+    munit_assert_not_null(n->props);
+    assert_ref(&n->props->key, ST_TOK_IDENT, "a", 1, 6);
+    assert_ref(&n->props->value, ST_TOK_NUMBER, "1", 1, 8);
+    munit_assert_null(n->props->next);
+    munit_assert_null(n->args);
+
+    for (n = n->next; n != NULL; n = n->next) {
+        count++;
+    }
+    munit_assert_size(count, ==, 1);
+    assert_ref(&doc->nodes->next->name, ST_TOK_IDENT, "b", 3, 1);
+
+    st_kdl_document_free(doc);
+    return MUNIT_OK;
+}
+
+/* (o) `st_kdl_document_free(NULL)` is a safe no-op. */
+static MunitResult
+test_free_null(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    st_kdl_document_free(NULL);
+    return MUNIT_OK;
+}
+
+static MunitTest tests[] = {
+    { "/parse/fixture-basic-kdl", test_parse_fixture, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/parse/unterminated-children", test_unterminated_children, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/parse/stray-rbrace", test_stray_rbrace, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/parse/prop-classification", test_prop_classification, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/parse/interleaved-order", test_interleaved_order, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/parse/newline-separates-nodes", test_newline_separates_nodes, NULL,
+      NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/parse/semicolon-separators", test_semicolon_separators, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/parse/empty-document", test_empty_document, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/parse/equals-after-name", test_equals_after_name, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/parse/prop-missing-value", test_prop_missing_value, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/parse/lexer-error-propagates", test_lexer_error_propagates, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/parse/annotation-and-string-names", test_annotation_and_string_names,
+      NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/parse/children-nesting", test_children_nesting, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/parse/trivia-skipped", test_trivia_skipped, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/parse/free-null", test_free_null, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { NULL, NULL, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+};
+
+static const MunitSuite suite = {
+    "/parser", tests, NULL, 1, MUNIT_SUITE_OPTION_NONE,
+};
+
+int
+main(int argc, char *argv[MUNIT_ARRAY_PARAM(argc + 1)])
+{
+    return munit_suite_main(&suite, NULL, argc, argv);
+}

tests/unit/test_probe.c

@@ -0,0 +1,758 @@
+/* LINK: ../../src/detect/probe.c ../../src/detect/checks.c ../../src/detect/check_registry.c ../../src/kdl/schema.c ../../src/kdl/parser.c ../../src/kdl/lexer.c ../../src/kdl/value.c ../../src/gen/sh_emit.c ../../src/error.c ../../src/span.c */
+
+#ifndef _POSIX_C_SOURCE
+#define _POSIX_C_SOURCE 200809L /* mkdtemp, system/WEXITSTATUS */
+#endif
+
+/*
+ * tests/unit/test_probe.c
+ *
+ * Unit tests for the configure-time probe snippet generator (todo 12):
+ * src/detect/probe.c. THE MODEL: probes do NOT run here, at stupidtools
+ * generation time — this module only EMITS POSIX-sh that runs at configure
+ * time inside the generated ./configure. These tests prove that emitted
+ * shell is syntactically valid (sh/bash/zsh -n), genuinely executes (real
+ * `cc` against real headers), short-circuits on config.cache, cross-compile
+ * guards RUN probes, and keeps hostile probe targets inert via st_sh_quote.
+ *
+ * The magic LINK comment on line 1 is REQUIRED by tests/run.sh (extra .c
+ * sources, relative to tests/unit/). probe.c needs sh_emit.c (st_sh_quote)
+ * + error.c + span.c; checks.c/check_registry.c/parser.c/lexer.c/value.c/
+ * schema.c are linked so canonical probes are built END-TO-END from DSL
+ * source (st_check_probe_build), exercising the real checks.c -> probe.c
+ * contract rather than hand-built structs alone.
+ */
+#include "munit.h"
+
+#include "detect/check_registry.h"
+#include "detect/checks.h"
+#include "detect/probe.h"
+#include "error.h"
+#include "kdl/ast.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <sys/wait.h>
+#include <unistd.h>
+
+/* ---- per-test temp dir ------------------------------------------------- */
+
+static char temp_dir[128];
+
+static void *
+setup(const MunitParameter params[], void *user_data)
+{
+    (void)params;
+    (void)user_data;
+    int n = snprintf(temp_dir, sizeof temp_dir, "/tmp/st_probe_XXXXXX");
+
+    if (n < 0) {
+        return NULL;
+    }
+    if (mkdtemp(temp_dir) == NULL) {
+        return NULL;
+    }
+    return (void *)1;
+}
+
+static void
+teardown(void *fixture)
+{
+    char cmd[160];
+    int n;
+
+    if (fixture == NULL || temp_dir[0] == '\0') {
+        return;
+    }
+    n = snprintf(cmd, sizeof cmd, "rm -rf -- '%s'", temp_dir);
+    if (n < 0 || (size_t)n >= sizeof cmd) {
+        return;
+    }
+    (void)system(cmd); /* best-effort; mkdtemp names are [A-Za-z0-9_]* */
+    temp_dir[0] = '\0';
+}
+
+/* Join temp_dir/`name` into `buf`; returns the snprintf result so callers
+ * can assert it without ever stringifying a %-carrying format (the munit
+ * %s-stringification trap, see .omo/notepads/stupidtools/learnings.md). */
+static int
+mkpath(char *buf, size_t sz, const char *name)
+{
+    return snprintf(buf, sz, "%s/%s", temp_dir, name);
+}
+
+/* ---- probe construction ------------------------------------------------- */
+
+/* Parse `src` as one check node, resolve its kind, build its probe spec
+ * into `*out` (fully heap-owned). Asserts each step succeeds and frees the
+ * document before returning. The caller frees via st_check_probe_free. */
+static enum st_check_kind
+build_from(const char *src, struct st_check_probe *out)
+{
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc = NULL;
+    struct st_kdl_node *node;
+    enum st_check_kind kind;
+
+    doc = st_kdl_parse(src, "t.kdl", &err);
+    munit_assert_null(err);
+    munit_assert_not_null(doc);
+    node = doc->nodes;
+    kind = st_check_kind_from_node(node, &err);
+    munit_assert_null(err);
+    munit_assert_int(kind, !=, ST_CHECK_KIND_COUNT);
+    munit_assert_null(st_check_probe_build(kind, node, out));
+    st_kdl_document_free(doc);
+    return kind;
+}
+
+/* ---- emit helpers ------------------------------------------------------ */
+
+/* Emit one check's snippet into a temp file, return its bytes (NUL-
+ * terminated). Returns NULL on any failure. The buffer is static (munit
+ * forks per test, so it is never shared across tests). */
+static const char *
+emit_snippet_text(const char *checkname, const struct st_check_probe *p)
+{
+    static char buf[8192];
+    char path[600];
+    FILE *f;
+    size_t n;
+    struct st_error *err;
+    int m;
+
+    m = mkpath(path, sizeof path, "snippet.sh");
+    if (m < 0) {
+        return NULL;
+    }
+    f = fopen(path, "w");
+    if (f == NULL) {
+        return NULL;
+    }
+    err = st_probe_emit_snippet(checkname, p, f);
+    fclose(f);
+    if (err != NULL) {
+        st_error_free(err);
+        return NULL;
+    }
+    f = fopen(path, "r");
+    if (f == NULL) {
+        return NULL;
+    }
+    n = fread(buf, 1, sizeof buf - 1, f);
+    fclose(f);
+    buf[n] = '\0';
+    return buf;
+}
+
+/* The configure-time environment the script's stub preamble plants. */
+struct env {
+    const char *cc;     /* CC value; NULL -> "cc" */
+    const char *cc_id;  /* st_cc_id; NULL -> "gcc" */
+    const char *cross;  /* "yes" -> cross_compiling=yes; else unset */
+};
+
+/* Write a runnable script: shebang, preamble assignments, the cache
+ * boilerplate, ONE snippet, and a dump of have_<name> + st_cross_<name>
+ * into have.out / cross.out under temp_dir. Returns 0 on success. */
+static int
+write_script(const char *checkname, const struct st_check_probe *p,
+             const struct env *env)
+{
+    char path[600];
+    FILE *f;
+    struct st_error *err;
+    int m;
+
+    m = mkpath(path, sizeof path, "run.sh");
+    if (m < 0) {
+        return -1;
+    }
+    f = fopen(path, "w");
+    if (f == NULL) {
+        return -1;
+    }
+    (void)fprintf(f, "#!/bin/sh\n");
+    (void)fprintf(f, "CC='%s'\n",
+                  env != NULL && env->cc != NULL ? env->cc : "cc");
+    (void)fprintf(f, "st_cc_id='%s'\n",
+                  env != NULL && env->cc_id != NULL ? env->cc_id : "gcc");
+    if (env != NULL && env->cross != NULL && strcmp(env->cross, "yes") == 0) {
+        (void)fprintf(f, "cross_compiling=yes\n");
+    }
+    (void)fprintf(f, "config_cache='%s/config.cache'\n", temp_dir);
+    (void)fprintf(f, "config_log='%s/config.log'\n", temp_dir);
+    (void)fprintf(f, "st_tmpdir='%s'\n", temp_dir);
+    err = st_probe_emit_cache_functions(f);
+    if (err != NULL) {
+        st_error_free(err);
+        fclose(f);
+        return -1;
+    }
+    err = st_probe_emit_snippet(checkname, p, f);
+    if (err != NULL) {
+        st_error_free(err);
+        fclose(f);
+        return -1;
+    }
+    (void)fprintf(f, "printf '%%s\\n' \"$have_%s\" > '%s/have.out'\n",
+                  checkname, temp_dir);
+    (void)fprintf(f, "printf '%%s\\n' \"${st_cross_%s:-}\" > '%s/cross.out'\n",
+                  checkname, temp_dir);
+    fclose(f);
+    return 0;
+}
+
+/* Run "sh <path>" via system(); return the shell's exit status or -1. */
+static int
+run_sh(const char *path)
+{
+    char cmd[700];
+    int rc;
+    int n = snprintf(cmd, sizeof cmd, "sh '%s'", path);
+
+    if (n < 0 || (size_t)n >= sizeof cmd) {
+        return -1;
+    }
+    rc = system(cmd);
+    if (rc == -1) {
+        return -1;
+    }
+    return WEXITSTATUS(rc);
+}
+
+/* As run_sh, but capture the script's stderr into `err_path`. */
+static int
+run_sh_err(const char *path, const char *err_path)
+{
+    char cmd[1400];
+    int rc;
+    int n = snprintf(cmd, sizeof cmd, "sh '%s' 2>'%s'", path, err_path);
+
+    if (n < 0 || (size_t)n >= sizeof cmd) {
+        return -1;
+    }
+    rc = system(cmd);
+    if (rc == -1) {
+        return -1;
+    }
+    return WEXITSTATUS(rc);
+}
+
+/* Read a tiny result file under temp_dir, strip the trailing newline.
+ * Returns a static buffer (empty string when the file is missing). */
+static const char *
+read_result(const char *file)
+{
+    static char buf[256];
+    char path[600];
+    FILE *f;
+    size_t n;
+    int m;
+
+    m = mkpath(path, sizeof path, file);
+    if (m < 0) {
+        return "";
+    }
+    f = fopen(path, "r");
+    if (f == NULL) {
+        return "";
+    }
+    n = fread(buf, 1, sizeof buf - 1, f);
+    fclose(f);
+    buf[n] = '\0';
+    buf[strcspn(buf, "\n")] = '\0';
+    return buf;
+}
+
+/* "<shell> -n <path>": return the shell's exit status or -1. */
+static int
+syntax_check(const char *shell, const char *path)
+{
+    char cmd[700];
+    int rc;
+    int n = snprintf(cmd, sizeof cmd, "%s -n '%s'", shell, path);
+
+    if (n < 0 || (size_t)n >= sizeof cmd) {
+        return -1;
+    }
+    rc = system(cmd);
+    if (rc == -1) {
+        return -1;
+    }
+    return WEXITSTATUS(rc);
+}
+
+/* ---- (a) snippet content ---------------------------------------------- */
+
+static MunitResult
+test_header_snippet_content(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe p = { 0 };
+    const char *s;
+
+    (void)build_from("header \"unistd.h\"", &p);
+    munit_assert_int(p.mode, ==, ST_PROBE_COMPILE);
+
+    s = emit_snippet_text("unistd_h", &p);
+    munit_assert_not_null(s);
+    munit_assert_not_null(strstr(s, "$CC"));
+    munit_assert_not_null(strstr(s, "-c"));
+    munit_assert_not_null(strstr(s, "have_unistd_h"));
+    munit_assert_not_null(strstr(s, "have_unistd_h=yes"));
+    munit_assert_not_null(strstr(s, "have_unistd_h=no"));
+    munit_assert_not_null(strstr(s, "#include <unistd.h>"));
+    munit_assert_not_null(strstr(s, "ac_cv_unistd_h_$st_cc_id"));
+    munit_assert_not_null(strstr(s, "st_cache_get"));
+    munit_assert_not_null(strstr(s, "st_cache_set"));
+
+    st_check_probe_free(&p);
+    return MUNIT_OK;
+}
+
+/* ---- (b) real execution: yes and no ----------------------------------- */
+
+static MunitResult
+test_header_runs_yes_no(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe yes = { 0 };
+    struct st_check_probe no = { 0 };
+    char run[600];
+    int m;
+
+    (void)build_from("header \"unistd.h\"", &yes);
+    munit_assert_int(write_script("unistd_h", &yes, NULL), ==, 0);
+    m = mkpath(run, sizeof run, "run.sh");
+    munit_assert_int(m, >, 0);
+    munit_assert_int(run_sh(run), ==, 0);
+    munit_assert_string_equal(read_result("have.out"), "yes");
+
+    (void)build_from("header \"nope_missing_xyz.h\"", &no);
+    munit_assert_int(write_script("nope", &no, NULL), ==, 0);
+    munit_assert_int(run_sh(run), ==, 0);
+    munit_assert_string_equal(read_result("have.out"), "no");
+
+    st_check_probe_free(&yes);
+    st_check_probe_free(&no);
+    return MUNIT_OK;
+}
+
+/* ---- (c) RUN probe: cross-compile guard ------------------------------- */
+
+static MunitResult
+test_run_cross_guard(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe p = { 0 };
+    struct env cross = { "/bin/false", "gcc", "yes" };
+    const char *s;
+    char run[600];
+    char errp[600];
+    char logpath[600];
+    int m;
+    int rc;
+
+    (void)build_from("sizeof \"long\"", &p);
+    munit_assert_int(p.mode, ==, ST_PROBE_RUN);
+
+    /* static: the emitted snippet carries a cross_compiling guard */
+    s = emit_snippet_text("sz", &p);
+    munit_assert_not_null(s);
+    munit_assert_not_null(strstr(s, "cross_compiling"));
+
+    /* dynamic: cross_compiling=yes + a failing CC -> skip, no compile */
+    munit_assert_int(write_script("sz", &p, &cross), ==, 0);
+    m = mkpath(run, sizeof run, "run.sh");
+    munit_assert_int(m, >, 0);
+    m = mkpath(errp, sizeof errp, "cross.err");
+    munit_assert_int(m, >, 0);
+    rc = run_sh_err(run, errp);
+    munit_assert_int(rc, ==, 0);
+    munit_assert_string_equal(read_result("have.out"), "no");
+    munit_assert_string_equal(read_result("cross.out"), "yes");
+    /* the warning landed on stderr */
+    {
+        const char *e = read_result("cross.err");
+
+        munit_assert_true(strstr(e, "cross-compiling") != NULL);
+    }
+    /* no compile was attempted: config.log was never created */
+    m = mkpath(logpath, sizeof logpath, "config.log");
+    munit_assert_int(m, >, 0);
+    munit_assert_int(access(logpath, F_OK), ==, -1);
+
+    /* dynamic: cross_compiling unset -> actually compiles and runs */
+    munit_assert_int(write_script("sz", &p, NULL), ==, 0);
+    munit_assert_int(run_sh(run), ==, 0);
+    munit_assert_string_equal(read_result("have.out"), "yes");
+    munit_assert_string_equal(read_result("cross.out"), "");
+    /* the run output (sizeof value) landed in config.log */
+    munit_assert_int(access(logpath, F_OK), ==, 0);
+
+    st_check_probe_free(&p);
+    return MUNIT_OK;
+}
+
+/* ---- (d) COMMAND probe: argv quoting ---------------------------------- */
+
+static MunitResult
+test_command_probe_quoting(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe prog = { 0 };
+    struct st_check_probe pk = { 0 };
+    const char *s;
+
+    (void)build_from("program \"pkg-config\"", &prog);
+    s = emit_snippet_text("pgc", &prog);
+    munit_assert_not_null(s);
+    munit_assert_not_null(strstr(s, "command -v 'pkg-config'"));
+
+    (void)build_from("pkg_config \"openssl\"", &pk);
+    s = emit_snippet_text("ossl", &pk);
+    munit_assert_not_null(s);
+    munit_assert_not_null(strstr(s, "pkg-config --cflags --libs 'openssl'"));
+
+    st_check_probe_free(&prog);
+    st_check_probe_free(&pk);
+    return MUNIT_OK;
+}
+
+/* ---- (e) config.cache short-circuit ----------------------------------- */
+
+static MunitResult
+test_cache_short_circuit(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe p = { 0 };
+    struct env bad = { "/bin/false", "gcc", NULL };
+    char cache[600];
+    char run[600];
+    char logpath[600];
+    FILE *f;
+    int m;
+    int wr;
+
+    /* pre-seed the cache with a "yes" for a header that does NOT exist,
+     * then point CC at /bin/false: only a cache hit can yield yes. */
+    (void)build_from("header \"nope_missing_xyz.h\"", &p);
+    m = mkpath(cache, sizeof cache, "config.cache");
+    munit_assert_int(m, >, 0);
+    f = fopen(cache, "w");
+    munit_assert_not_null(f);
+    wr = fputs("ac_cv_cached_gcc=yes\n", f);
+    munit_assert_int(wr, !=, EOF);
+    fclose(f);
+
+    munit_assert_int(write_script("cached", &p, &bad), ==, 0);
+    m = mkpath(run, sizeof run, "run.sh");
+    munit_assert_int(m, >, 0);
+    munit_assert_int(run_sh(run), ==, 0);
+    munit_assert_string_equal(read_result("have.out"), "yes");
+
+    /* no probe was attempted (compiler never ran) */
+    m = mkpath(logpath, sizeof logpath, "config.log");
+    munit_assert_int(m, >, 0);
+    munit_assert_int(access(logpath, F_OK), ==, -1);
+
+    /* the cached line was consumed, not overwritten with "no" */
+    {
+        const char *c = read_result("config.cache");
+
+        munit_assert_not_null(strstr(c, "ac_cv_cached_gcc=yes"));
+    }
+
+    st_check_probe_free(&p);
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_cache_write(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe p = { 0 };
+    char run[600];
+    const char *c;
+    int m;
+
+    (void)build_from("header \"unistd.h\"", &p);
+    munit_assert_int(write_script("writecc", &p, NULL), ==, 0);
+    m = mkpath(run, sizeof run, "run.sh");
+    munit_assert_int(m, >, 0);
+    munit_assert_int(run_sh(run), ==, 0);
+    munit_assert_string_equal(read_result("have.out"), "yes");
+
+    c = read_result("config.cache");
+    munit_assert_not_null(strstr(c, "ac_cv_writecc_gcc=yes"));
+
+    st_check_probe_free(&p);
+    return MUNIT_OK;
+}
+
+/* ---- (f) syntax: sh -n / bash -n / zsh -n + banned-construct sweep ---- */
+
+static MunitResult
+test_syntax_and_banned(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    static const char *const banned[] = {
+        "[[ ", "]]", "local ", "==", "<<<", "&>", "set -e",
+    };
+    struct st_check_probe hdr = { 0 };
+    struct st_check_probe fn = { 0 };
+    struct st_check_probe sz = { 0 };
+    struct st_check_probe prog = { 0 };
+    char path[600];
+    char *bytes;
+    FILE *f;
+    long n;
+    size_t i;
+    int m;
+
+    (void)build_from("header \"unistd.h\"", &hdr);
+    (void)build_from("function \"strdup\"", &fn);
+    (void)build_from("sizeof \"long\"", &sz);
+    (void)build_from("program \"pkg-config\"", &prog);
+
+    m = mkpath(path, sizeof path, "all.sh");
+    munit_assert_int(m, >, 0);
+    f = fopen(path, "w");
+    munit_assert_not_null(f);
+    (void)fprintf(f, "#!/bin/sh\n");
+    munit_assert_null(st_probe_emit_cache_functions(f));
+    munit_assert_null(st_probe_emit_snippet("hdr", &hdr, f));
+    munit_assert_null(st_probe_emit_snippet("fn", &fn, f));
+    munit_assert_null(st_probe_emit_snippet("sz", &sz, f));
+    munit_assert_null(st_probe_emit_snippet("prog", &prog, f));
+    fclose(f);
+
+    munit_assert_int(syntax_check("sh", path), ==, 0);
+    munit_assert_int(syntax_check("bash", path), ==, 0);
+    munit_assert_int(syntax_check("zsh", path), ==, 0);
+
+    /* banned-construct sweep on the real emitted bytes */
+    f = fopen(path, "rb");
+    munit_assert_not_null(f);
+    munit_assert_int(fseek(f, 0, SEEK_END), ==, 0);
+    n = ftell(f);
+    munit_assert_int(n, >, 0);
+    munit_assert_int(fseek(f, 0, SEEK_SET), ==, 0);
+    bytes = munit_malloc((size_t)n + 1);
+    munit_assert_size(fread(bytes, 1, (size_t)n, f), ==, (size_t)n);
+    fclose(f);
+    bytes[n] = '\0';
+    for (i = 0; i < sizeof banned / sizeof banned[0]; i++) {
+        munit_assert_null(strstr(bytes, banned[i]));
+    }
+    free(bytes);
+
+    st_check_probe_free(&hdr);
+    st_check_probe_free(&fn);
+    st_check_probe_free(&sz);
+    st_check_probe_free(&prog);
+    return MUNIT_OK;
+}
+
+/* ---- (g) injection: hostile probe target stays inert ------------------ */
+
+static MunitResult
+test_injection_inert(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    char marker[600];
+    char csrc[700];
+    char run[600];
+    int m;
+    int rc;
+    struct st_check_probe p;
+
+    /* A C source that, if the shell ever interpreted it (unquoted), would
+     * remove `marker`'s directory. st_sh_quote makes it a literal; the
+     * compile just fails and the shell never executes the embedded rm. */
+    m = snprintf(marker, sizeof marker, "%s/victim.txt", temp_dir);
+    munit_assert_int(m, >, 0);
+    m = snprintf(csrc, sizeof csrc,
+                 "#include <unistd.h>\n; rm -rf %s; \"\n", marker);
+    munit_assert_int(m, >, 0);
+    p = (struct st_check_probe){
+        .mode = ST_PROBE_COMPILE,
+        .c_source = csrc,
+    };
+    munit_assert_int(write_script("hostile", &p, NULL), ==, 0);
+    m = mkpath(run, sizeof run, "run.sh");
+    munit_assert_int(m, >, 0);
+    rc = run_sh(run);
+    munit_assert_int(rc, ==, 0);
+    munit_assert_string_equal(read_result("have.out"), "no");
+    munit_assert_int(access(marker, F_OK), ==, -1);
+    return MUNIT_OK;
+}
+
+/* ---- emit_all: a feature's list of checks ----------------------------- */
+
+static MunitResult
+test_emit_all(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe a = { .mode = ST_PROBE_COMPILE,
+                                .c_source = "#include <unistd.h>\n" };
+    struct st_check_probe b = { .mode = ST_PROBE_COMPILE,
+                                .c_source = "#include <stddef.h>\n" };
+    struct st_probe_entry entries[2];
+    char path[600];
+    FILE *f;
+    struct st_error *err;
+    char *bytes;
+    long n;
+    int m;
+
+    entries[0].name = "alpha";
+    entries[0].probe = &a;
+    entries[1].name = "beta";
+    entries[1].probe = &b;
+
+    m = mkpath(path, sizeof path, "all2.sh");
+    munit_assert_int(m, >, 0);
+    f = fopen(path, "w");
+    munit_assert_not_null(f);
+    munit_assert_null(st_probe_emit_cache_functions(f));
+    err = st_probe_emit_all(entries, 2, f);
+    munit_assert_null(err);
+    fclose(f);
+
+    f = fopen(path, "rb");
+    munit_assert_not_null(f);
+    munit_assert_int(fseek(f, 0, SEEK_END), ==, 0);
+    n = ftell(f);
+    munit_assert_int(fseek(f, 0, SEEK_SET), ==, 0);
+    bytes = munit_malloc((size_t)n + 1);
+    munit_assert_size(fread(bytes, 1, (size_t)n, f), ==, (size_t)n);
+    fclose(f);
+    bytes[n] = '\0';
+    munit_assert_not_null(strstr(bytes, "have_alpha"));
+    munit_assert_not_null(strstr(bytes, "have_beta"));
+    munit_assert_not_null(strstr(bytes, "ac_cv_alpha_$st_cc_id"));
+    munit_assert_not_null(strstr(bytes, "ac_cv_beta_$st_cc_id"));
+    free(bytes);
+
+    /* empty list is a clean no-op */
+    f = tmpfile();
+    munit_assert_not_null(f);
+    err = st_probe_emit_all(NULL, 0, f);
+    munit_assert_null(err);
+    fclose(f);
+
+    return MUNIT_OK;
+}
+
+/* ---- error handling ---------------------------------------------------- */
+
+static MunitResult
+test_errors(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_check_probe good = { .mode = ST_PROBE_COMPILE,
+                                   .c_source = "#include <x.h>\n" };
+    struct st_check_probe nocmd = { .mode = ST_PROBE_COMMAND,
+                                    .command = NULL };
+    struct st_check_probe nosrc = { .mode = ST_PROBE_COMPILE,
+                                    .c_source = NULL };
+    struct st_check_probe badmode = { .mode = (enum st_check_probe_mode)999,
+                                      .c_source = "x" };
+    FILE *f = tmpfile();
+    struct st_error *err;
+
+    munit_assert_not_null(f);
+
+    err = st_probe_emit_snippet(NULL, &good, f);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_USAGE);
+    st_error_free(err);
+
+    err = st_probe_emit_snippet("bad name", &good, f);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_USAGE);
+    st_error_free(err);
+
+    err = st_probe_emit_snippet("ok", NULL, f);
+    munit_assert_not_null(err);
+    st_error_free(err);
+
+    err = st_probe_emit_snippet("ok", &good, NULL);
+    munit_assert_not_null(err);
+    st_error_free(err);
+
+    err = st_probe_emit_snippet("ok", &badmode, f);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_USAGE);
+    st_error_free(err);
+
+    err = st_probe_emit_snippet("ok", &nocmd, f);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_USAGE);
+    st_error_free(err);
+
+    err = st_probe_emit_snippet("ok", &nosrc, f);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_USAGE);
+    st_error_free(err);
+
+    err = st_probe_emit_cache_functions(NULL);
+    munit_assert_not_null(err);
+    st_error_free(err);
+
+    /* a valid emit returns no error */
+    err = st_probe_emit_snippet("ok", &good, f);
+    munit_assert_null(err);
+
+    fclose(f);
+    return MUNIT_OK;
+}
+
+static MunitTest tests[] = {
+    { "/probe/header-snippet-content", test_header_snippet_content, setup,
+      teardown, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/probe/header-runs-yes-no", test_header_runs_yes_no, setup, teardown,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/probe/run-cross-guard", test_run_cross_guard, setup, teardown,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/probe/command-quoting", test_command_probe_quoting, setup, teardown,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/probe/cache-short-circuit", test_cache_short_circuit, setup, teardown,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/probe/cache-write", test_cache_write, setup, teardown,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/probe/syntax-banned", test_syntax_and_banned, setup, teardown,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/probe/injection-inert", test_injection_inert, setup, teardown,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/probe/emit-all", test_emit_all, setup, teardown,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/probe/errors", test_errors, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { NULL, NULL, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+};
+
+static const MunitSuite suite = {
+    "/probe", tests, NULL, 1, MUNIT_SUITE_OPTION_NONE,
+};
+
+int
+main(int argc, char *argv[MUNIT_ARRAY_PARAM(argc + 1)])
+{
+    return munit_suite_main(&suite, NULL, argc, argv);
+}

tests/unit/test_resolve.c

@@ -0,0 +1,732 @@
+/* LINK: ../../src/detect/resolve.c ../../src/gen/sh_emit.c ../../src/kdl/schema.c ../../src/detect/check_registry.c ../../src/kdl/value.c ../../src/kdl/parser.c ../../src/kdl/lexer.c ../../src/error.c ../../src/span.c */
+
+#ifndef _POSIX_C_SOURCE
+#define _POSIX_C_SOURCE 200809L /* mkdtemp, system/WEXITSTATUS */
+#endif
+
+/*
+ * tests/unit/test_resolve.c
+ *
+ * Unit tests for feature resolution + `when` guards (todo 14):
+ * src/detect/resolve.c. THE MODEL: guards are PARSED + EMITTED here, at
+ * stupidtools generation time, but they are EVALUATED at configure time
+ * inside the generated ./configure — against the shell variables
+ * $have_<feature> (set by todo 12's probe snippets) and the normalized
+ * $st_os. These tests prove the emitted guard shell is syntactically valid
+ * (sh/bash/zsh -n), genuinely evaluates (real `sh` execution against
+ * seeded variables), parses malformed guards into spanned errors, maps the
+ * os table both C-side and via the emitted shell, and that the schema
+ * accepts the `when` feature property (the todo-14 DSL placement).
+ *
+ * The magic LINK comment on line 1 is REQUIRED by tests/run.sh (extra .c
+ * sources, relative to tests/unit/). resolve.c needs sh_emit.c (st_sh_quote)
+ * + error.c + span.c; schema.c/check_registry.c/value.c/parser.c/lexer.c
+ * are linked for the schema `when` acceptance test (st_kdl_parse +
+ * st_kdl_validate).
+ */
+#include "munit.h"
+
+#include "detect/resolve.h"
+#include "error.h"
+#include "kdl/ast.h"
+#include "kdl/schema.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/wait.h>
+#include <unistd.h>
+
+/* ---- per-test temp dir ------------------------------------------------- */
+
+static char temp_dir[128];
+
+static void *
+setup(const MunitParameter params[], void *user_data)
+{
+    (void)params;
+    (void)user_data;
+    int n = snprintf(temp_dir, sizeof temp_dir, "/tmp/st_resolve_XXXXXX");
+
+    if (n < 0) {
+        return NULL;
+    }
+    if (mkdtemp(temp_dir) == NULL) {
+        return NULL;
+    }
+    return (void *)1;
+}
+
+static void
+teardown(void *fixture)
+{
+    char cmd[160];
+    int n;
+
+    if (fixture == NULL || temp_dir[0] == '\0') {
+        return;
+    }
+    n = snprintf(cmd, sizeof cmd, "rm -rf -- '%s'", temp_dir);
+    if (n < 0 || (size_t)n >= sizeof cmd) {
+        return;
+    }
+    (void)system(cmd);
+    temp_dir[0] = '\0';
+}
+
+/* Join temp_dir/`name` into `buf`; returns the snprintf result so callers
+ * can assert it without ever stringifying a %-carrying format (the munit
+ * %s-stringification trap, see .omo/notepads/stupidtools/learnings.md). */
+static int
+mkpath(char *buf, size_t sz, const char *name)
+{
+    return snprintf(buf, sz, "%s/%s", temp_dir, name);
+}
+
+/* Read a tiny result file under temp_dir, strip the trailing newline.
+ * Returns a static buffer (empty string when the file is missing). */
+static const char *
+read_result(const char *file)
+{
+    static char buf[256];
+    char path[600];
+    FILE *f;
+    size_t n;
+    int m;
+
+    m = mkpath(path, sizeof path, file);
+    if (m < 0) {
+        return "";
+    }
+    f = fopen(path, "r");
+    if (f == NULL) {
+        return "";
+    }
+    n = fread(buf, 1, sizeof buf - 1, f);
+    fclose(f);
+    buf[n] = '\0';
+    buf[strcspn(buf, "\n")] = '\0';
+    return buf;
+}
+
+/* Run "sh <path>" via system(); return the shell's exit status or -1. */
+static int
+run_sh(const char *path)
+{
+    char cmd[700];
+    int rc;
+    int n = snprintf(cmd, sizeof cmd, "sh '%s'", path);
+
+    if (n < 0 || (size_t)n >= sizeof cmd) {
+        return -1;
+    }
+    rc = system(cmd);
+    if (rc == -1) {
+        return -1;
+    }
+    return WEXITSTATUS(rc);
+}
+
+/* Run "sh <path>" capturing stdout into out_path; return exit status. */
+static int
+run_sh_out(const char *path, const char *out_path)
+{
+    char cmd[1400];
+    int rc;
+    int n = snprintf(cmd, sizeof cmd, "sh '%s' > '%s' 2>/dev/null", path,
+                     out_path);
+
+    if (n < 0 || (size_t)n >= sizeof cmd) {
+        return -1;
+    }
+    rc = system(cmd);
+    if (rc == -1) {
+        return -1;
+    }
+    return WEXITSTATUS(rc);
+}
+
+/* "<shell> -n <path>": return the shell's exit status or -1. */
+static int
+syntax_check(const char *shell, const char *path)
+{
+    char cmd[700];
+    int rc;
+    int n = snprintf(cmd, sizeof cmd, "%s -n '%s'", shell, path);
+
+    if (n < 0 || (size_t)n >= sizeof cmd) {
+        return -1;
+    }
+    rc = system(cmd);
+    if (rc == -1) {
+        return -1;
+    }
+    return WEXITSTATUS(rc);
+}
+
+/* ---- guard emission helpers ------------------------------------------- */
+
+/* Parse + emit a guard into a static buffer; returns the emitted bytes. */
+static const char *
+emit_guard_text(const char *guard)
+{
+    static char buf[1024];
+    FILE *f = tmpfile();
+    struct st_when_ast *ast = NULL;
+    size_t n;
+
+    munit_assert_not_null(f);
+    munit_assert_null(st_when_parse(guard, &ast));
+    munit_assert_not_null(ast);
+    munit_assert_null(st_when_emit(f, ast));
+    st_when_free(ast);
+    munit_assert_int(fflush(f), ==, 0);
+    munit_assert_int(fseek(f, 0, SEEK_SET), ==, 0);
+    n = fread(buf, 1, sizeof buf - 1, f);
+    fclose(f);
+    buf[n] = '\0';
+    return buf;
+}
+
+/* Write a script that evaluates `guard` under `assigns` (raw "var=value"
+ * lines, test-controlled constants) and echoes yes/no to stdout; capture
+ * and return the result ("yes" or "no"). */
+static const char *
+guard_eval(const char *guard, const char *const *assigns, size_t nassign)
+{
+    char path[600];
+    char out[600];
+    FILE *f;
+    struct st_when_ast *ast = NULL;
+    size_t i;
+    int m;
+
+    m = mkpath(path, sizeof path, "guard.sh");
+    munit_assert_int(m, >, 0);
+    m = mkpath(out, sizeof out, "guard.out");
+    munit_assert_int(m, >, 0);
+
+    f = fopen(path, "w");
+    munit_assert_not_null(f);
+    (void)fprintf(f, "#!/bin/sh\n");
+    for (i = 0; i < nassign; i++) {
+        (void)fprintf(f, "%s\n", assigns[i]);
+    }
+    (void)fprintf(f, "if ");
+    munit_assert_null(st_when_parse(guard, &ast));
+    munit_assert_not_null(ast);
+    munit_assert_null(st_when_emit(f, ast));
+    st_when_free(ast);
+    (void)fprintf(f, "; then\n    echo yes\nelse\n    echo no\nfi\n");
+    fclose(f);
+
+    munit_assert_int(run_sh_out(path, out), ==, 0);
+    return read_result("guard.out");
+}
+
+/* Emit one feature's resolution under `assigns`, then dump have_<name>
+ * into feature.out; return that value. */
+static const char *
+feature_eval(const struct st_resolve_feature *f,
+             const char *const *assigns, size_t nassign)
+{
+    char path[600];
+    char out[600];
+    FILE *fp;
+    size_t i;
+    int m;
+
+    m = mkpath(path, sizeof path, "feature.sh");
+    munit_assert_int(m, >, 0);
+    m = mkpath(out, sizeof out, "feature.out");
+    munit_assert_int(m, >, 0);
+
+    fp = fopen(path, "w");
+    munit_assert_not_null(fp);
+    (void)fprintf(fp, "#!/bin/sh\n");
+    for (i = 0; i < nassign; i++) {
+        (void)fprintf(fp, "%s\n", assigns[i]);
+    }
+    munit_assert_null(st_resolve_emit_feature(fp, f));
+    (void)fprintf(fp, "printf '%%s\\n' \"$have_%s\" > '%s'\n", f->name, out);
+    fclose(fp);
+
+    munit_assert_int(run_sh(path), ==, 0);
+    return read_result("feature.out");
+}
+
+/* Run the emitted st_os_norm() over `raw`, returning the normalized name
+ * the shell produced (the raw uname -s string is assigned to $st_os). */
+static const char *
+os_norm_shell(const char *raw)
+{
+    char path[600];
+    char out[600];
+    FILE *f;
+    int m;
+
+    m = mkpath(path, sizeof path, "osnorm.sh");
+    munit_assert_int(m, >, 0);
+    m = mkpath(out, sizeof out, "osnorm.out");
+    munit_assert_int(m, >, 0);
+
+    f = fopen(path, "w");
+    munit_assert_not_null(f);
+    (void)fprintf(f, "#!/bin/sh\n");
+    munit_assert_null(st_resolve_emit_os_norm(f));
+    (void)fprintf(f, "st_os='%s'\nst_os_norm\nprintf '%%s\\n' \"$st_os\" > '%s'\n",
+                  raw, out);
+    fclose(f);
+
+    munit_assert_int(run_sh(path), ==, 0);
+    return read_result("osnorm.out");
+}
+
+/* ---- (content) parse + emit ------------------------------------------- */
+
+static MunitResult
+test_parse_emit_content(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_when_ast *ast = NULL;
+    const char *s;
+
+    /* os=linux and have_pthread parses and emits the two leaf tests ANDed */
+    s = emit_guard_text("os=linux and have_pthread");
+    munit_assert_not_null(strstr(s, "\"$st_os\" = 'linux'"));
+    munit_assert_not_null(strstr(s, "\"$have_pthread\" = \"yes\""));
+    munit_assert_not_null(strstr(s, "&&"));
+
+    /* not os=macos: negated os test */
+    s = emit_guard_text("not os=macos");
+    munit_assert_not_null(strstr(s, "!"));
+    munit_assert_not_null(strstr(s, "\"$st_os\" = 'macos'"));
+
+    /* NULL / empty guard -> NULL ast (always true) */
+    munit_assert_null(st_when_parse(NULL, &ast));
+    munit_assert_null(ast);
+    munit_assert_null(st_when_parse("", &ast));
+    munit_assert_null(ast);
+
+    /* NULL out is a usage error, not a crash */
+    {
+        struct st_error *err = st_when_parse("os=linux", NULL);
+
+        munit_assert_not_null(err);
+        munit_assert_int(st_error_category_of(err), ==, ST_ERR_USAGE);
+        st_error_free(err);
+    }
+    /* NULL stream is a usage error */
+    {
+        struct st_when_ast *a = NULL;
+        struct st_error *err;
+
+        munit_assert_null(st_when_parse("os=linux", &a));
+        munit_assert_not_null(a);
+        err = st_when_emit(NULL, a);
+        munit_assert_not_null(err);
+        munit_assert_int(st_error_category_of(err), ==, ST_ERR_USAGE);
+        st_error_free(err);
+        st_when_free(a);
+    }
+    return MUNIT_OK;
+}
+
+/* ---- (a) os=linux and have_pthread: real sh eval ---------------------- */
+
+static MunitResult
+test_guard_eval(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    static const char *const yes[] = { "have_pthread=yes", "st_os=linux" };
+    static const char *const no[] = { "have_pthread=no", "st_os=linux" };
+
+    munit_assert_string_equal(
+        guard_eval("os=linux and have_pthread", yes, 2), "yes");
+    munit_assert_string_equal(
+        guard_eval("os=linux and have_pthread", no, 2), "no");
+    return MUNIT_OK;
+}
+
+/* ---- (b) not os=macos: true on linux, false on macos ------------------ */
+
+static MunitResult
+test_not_os(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    static const char *const linux[] = { "st_os=linux" };
+    static const char *const macos[] = { "st_os=macos" };
+
+    munit_assert_string_equal(guard_eval("not os=macos", linux, 1), "yes");
+    munit_assert_string_equal(guard_eval("not os=macos", macos, 1), "no");
+    return MUNIT_OK;
+}
+
+/* ---- (c) precedence: have_a or (have_b and os=linux) ------------------ */
+
+static MunitResult
+test_precedence(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    static const char *const c1[] = { "have_a=yes", "have_b=no",
+                                      "st_os=macos" };
+    static const char *const c2[] = { "have_a=no", "have_b=yes",
+                                      "st_os=linux" };
+    static const char *const c3[] = { "have_a=no", "have_b=yes",
+                                      "st_os=macos" };
+
+    /* c1: have_a true -> true regardless of the right operand */
+    munit_assert_string_equal(
+        guard_eval("have_a or (have_b and os=linux)", c1, 3), "yes");
+    /* c2: have_a false, (have_b && os=linux) true -> true */
+    munit_assert_string_equal(
+        guard_eval("have_a or (have_b and os=linux)", c2, 3), "yes");
+    /* c3: have_a false and (have_b && os=linux) false -> false */
+    munit_assert_string_equal(
+        guard_eval("have_a or (have_b and os=linux)", c3, 3), "no");
+    return MUNIT_OK;
+}
+
+/* ---- (d) malformed guards -> spanned errors --------------------------- */
+
+static void
+assert_parse_error(const char *guard, const char *needle, size_t col)
+{
+    struct st_when_ast *ast = NULL;
+    struct st_error *err = NULL;
+
+    err = st_when_parse(guard, &ast);
+    munit_assert_not_null(err);
+    munit_assert_null(ast);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+    munit_assert_not_null(err->span);
+    munit_assert_size(err->span->line, ==, 1);
+    munit_assert_size(err->span->col, ==, col);
+    munit_assert_true(strstr(st_error_message(err), needle) != NULL);
+    st_error_free(err);
+}
+
+static MunitResult
+test_parse_errors(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    /* the acceptance case: an unbalanced paren */
+    assert_parse_error("((x", "unknown token 'x'", 3);
+    /* empty feature name after have_ */
+    assert_parse_error("have_", "missing feature name", 1);
+    /* invalid feature identifier */
+    assert_parse_error("have_1x", "invalid feature name", 1);
+    /* empty os name */
+    assert_parse_error("os=", "missing os name", 1);
+    /* unknown word */
+    assert_parse_error("bogus", "unknown token 'bogus'", 1);
+    /* unterminated group */
+    assert_parse_error("(", "unexpected end", 2);
+    /* trailing close paren */
+    assert_parse_error("os=linux )", "unexpected token ')'", 10);
+    return MUNIT_OK;
+}
+
+/* ---- (e) os mapping: C-side table + emitted shell --------------------- */
+
+static MunitResult
+test_os_mapping(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    /* C-side mapping function */
+    munit_assert_string_equal(st_os_normalize("Linux"), "linux");
+    munit_assert_string_equal(st_os_normalize("Darwin"), "macos");
+    munit_assert_string_equal(st_os_normalize("FreeBSD"), "bsd");
+    munit_assert_string_equal(st_os_normalize("OpenBSD"), "bsd");
+    munit_assert_string_equal(st_os_normalize("NetBSD"), "bsd");
+    munit_assert_string_equal(st_os_normalize("Solaris"), "other");
+    munit_assert_string_equal(st_os_normalize("Linux-gnu"), "other");
+    munit_assert_string_equal(st_os_normalize(NULL), "other");
+
+    /* the emitted st_os_norm() reproduces the mapping under real sh */
+    munit_assert_string_equal(os_norm_shell("Linux"), "linux");
+    munit_assert_string_equal(os_norm_shell("Darwin"), "macos");
+    munit_assert_string_equal(os_norm_shell("FreeBSD"), "bsd");
+    munit_assert_string_equal(os_norm_shell("OpenBSD"), "bsd");
+    munit_assert_string_equal(os_norm_shell("Solaris"), "other");
+    return MUNIT_OK;
+}
+
+/* ---- (f) emitted guard shells pass sh -n / bash -n / zsh -n ----------- */
+
+static MunitResult
+test_syntax(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    static const char *const banned[] = {
+        "[[ ", "]]", "local ", "==", "<<<", "&>", "set -e",
+    };
+    static const char *const guards[] = {
+        "os=linux and have_pthread",
+        "not os=macos",
+        "have_a or (have_b and os=linux)",
+        "not (have_a and not os=bsd)",
+        "os=other",
+    };
+    char path[600];
+    FILE *f;
+    struct st_when_ast *ast = NULL;
+    size_t i;
+    int m;
+    char *bytes;
+    long n;
+
+    m = mkpath(path, sizeof path, "syntax.sh");
+    munit_assert_int(m, >, 0);
+    f = fopen(path, "w");
+    munit_assert_not_null(f);
+    (void)fprintf(f, "#!/bin/sh\n");
+    munit_assert_null(st_resolve_emit_os_norm(f));
+    for (i = 0; i < sizeof guards / sizeof guards[0]; i++) {
+        (void)fprintf(f, "if ");
+        munit_assert_null(st_when_parse(guards[i], &ast));
+        munit_assert_not_null(ast);
+        munit_assert_null(st_when_emit(f, ast));
+        st_when_free(ast);
+        (void)fprintf(f, "; then :; fi\n");
+    }
+    fclose(f);
+
+    munit_assert_int(syntax_check("sh", path), ==, 0);
+    munit_assert_int(syntax_check("bash", path), ==, 0);
+    munit_assert_int(syntax_check("zsh", path), ==, 0);
+
+    /* banned-construct sweep on the real emitted bytes */
+    f = fopen(path, "rb");
+    munit_assert_not_null(f);
+    munit_assert_int(fseek(f, 0, SEEK_END), ==, 0);
+    n = ftell(f);
+    munit_assert_int(n, >, 0);
+    munit_assert_int(fseek(f, 0, SEEK_SET), ==, 0);
+    bytes = munit_malloc((size_t)n + 1);
+    munit_assert_size(fread(bytes, 1, (size_t)n, f), ==, (size_t)n);
+    fclose(f);
+    bytes[n] = '\0';
+    for (i = 0; i < sizeof banned / sizeof banned[0]; i++) {
+        munit_assert_null(strstr(bytes, banned[i]));
+    }
+    free(bytes);
+    return MUNIT_OK;
+}
+
+/* ---- feature aggregation: multi-check AND ----------------------------- */
+
+static MunitResult
+test_emit_feature_aggregate(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    static const char *const both[] = { "have_pthread_0=yes",
+                                        "have_pthread_1=yes" };
+    static const char *const one[] = { "have_pthread_0=yes",
+                                       "have_pthread_1=no" };
+    static const char *const none[] = { "have_pthread_0=no",
+                                        "have_pthread_1=no" };
+    const char *check_names[2] = { "pthread_0", "pthread_1" };
+    struct st_resolve_feature f = { "pthread", check_names, 2, NULL };
+
+    munit_assert_string_equal(feature_eval(&f, both, 2), "yes");
+    munit_assert_string_equal(feature_eval(&f, one, 2), "no");
+    munit_assert_string_equal(feature_eval(&f, none, 2), "no");
+    return MUNIT_OK;
+}
+
+/* ---- feature guard gating: when-guard forces have_<f>=no ------------- */
+
+static MunitResult
+test_emit_feature_guard(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    const char *check_names[1] = { "pthread" };
+    struct st_when_ast *ast = NULL;
+    struct st_resolve_feature f;
+    static const char *const linux[] = { "have_pthread=yes", "st_os=linux" };
+    static const char *const macos[] = { "have_pthread=yes", "st_os=macos" };
+
+    munit_assert_null(st_when_parse("os=linux", &ast));
+    f.name = "pthread";
+    f.check_names = check_names;
+    f.check_count = 1;
+    f.guard = ast;
+
+    /* guard holds -> the probe's have_pthread=yes survives */
+    munit_assert_string_equal(feature_eval(&f, linux, 2), "yes");
+    /* guard fails -> have_pthread is forced to no */
+    munit_assert_string_equal(feature_eval(&f, macos, 2), "no");
+
+    st_when_free(ast);
+    return MUNIT_OK;
+}
+
+/* ---- check-name scheme (the todo-12/16 naming contract) --------------- */
+
+static MunitResult
+test_check_name(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    char buf[64];
+
+    /* single-check feature -> the feature name itself */
+    munit_assert_int(st_resolve_check_name("pthread", 0, 1, buf,
+                                           sizeof buf), ==, 0);
+    munit_assert_string_equal(buf, "pthread");
+
+    /* multi-check feature -> <name>_0, <name>_1, ... */
+    munit_assert_int(st_resolve_check_name("pthread", 0, 2, buf,
+                                           sizeof buf), ==, 0);
+    munit_assert_string_equal(buf, "pthread_0");
+    munit_assert_int(st_resolve_check_name("pthread", 1, 2, buf,
+                                           sizeof buf), ==, 0);
+    munit_assert_string_equal(buf, "pthread_1");
+
+    /* invalid feature name / out-of-range index / zero count -> -1 */
+    munit_assert_int(st_resolve_check_name("1bad", 0, 1, buf,
+                                           sizeof buf), ==, -1);
+    munit_assert_int(st_resolve_check_name("pthread", 1, 1, buf,
+                                           sizeof buf), ==, -1);
+    munit_assert_int(st_resolve_check_name("pthread", 0, 0, buf,
+                                           sizeof buf), ==, -1);
+    return MUNIT_OK;
+}
+
+/* ---- schema: the `when` feature property (todo-14 placement) ---------- */
+
+static MunitResult
+test_schema_when(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+
+    /* a feature may carry one `when "<expr>"` property */
+    doc = st_kdl_parse("project \"p\" version \"1.0\"\n"
+                       "feature \"pthread\" when=\"os=linux\" "
+                       "{ header \"pthread.h\" }",
+                       "t.kdl", &err);
+    munit_assert_null(err);
+    munit_assert_not_null(doc);
+    munit_assert_null(st_kdl_validate(doc));
+    st_kdl_document_free(doc);
+
+    /* the guard string is NOT parsed by the schema (that is resolve's job):
+     * a malformed guard is still structurally a non-empty string */
+    doc = st_kdl_parse("project \"p\" version \"1.0\"\n"
+                       "feature \"pthread\" when=\"((x\" "
+                       "{ header \"pthread.h\" }",
+                       "t.kdl", &err);
+    munit_assert_null(err);
+    munit_assert_not_null(doc);
+    munit_assert_null(st_kdl_validate(doc));
+    st_kdl_document_free(doc);
+
+    /* `when` must be a non-empty string */
+    doc = st_kdl_parse("project \"p\" version \"1.0\"\n"
+                       "feature \"pthread\" when=42 "
+                       "{ header \"pthread.h\" }",
+                       "t.kdl", &err);
+    munit_assert_null(err);
+    munit_assert_not_null(doc);
+    err = st_kdl_validate(doc);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+    munit_assert_true(strstr(st_error_message(err), "non-empty string") !=
+                      NULL);
+    st_error_free(err);
+    st_kdl_document_free(doc);
+
+    /* empty when string is rejected too */
+    doc = st_kdl_parse("project \"p\" version \"1.0\"\n"
+                       "feature \"pthread\" when=\"\" "
+                       "{ header \"pthread.h\" }",
+                       "t.kdl", &err);
+    munit_assert_null(err);
+    munit_assert_not_null(doc);
+    err = st_kdl_validate(doc);
+    munit_assert_not_null(err);
+    munit_assert_true(strstr(st_error_message(err), "non-empty string") !=
+                      NULL);
+    st_error_free(err);
+    st_kdl_document_free(doc);
+
+    /* duplicate `when` is rejected */
+    doc = st_kdl_parse("project \"p\" version \"1.0\"\n"
+                       "feature \"pthread\" when=\"os=linux\" when=\"os=bsd\" "
+                       "{ header \"pthread.h\" }",
+                       "t.kdl", &err);
+    munit_assert_null(err);
+    munit_assert_not_null(doc);
+    err = st_kdl_validate(doc);
+    munit_assert_not_null(err);
+    munit_assert_true(strstr(st_error_message(err), "duplicate 'when'") !=
+                      NULL);
+    st_error_free(err);
+    st_kdl_document_free(doc);
+
+    /* a non-when property on a feature is still rejected (unchanged) */
+    doc = st_kdl_parse("project \"p\" version \"1.0\"\n"
+                       "feature \"f\" foo=1 { header \"h.h\" }",
+                       "t.kdl", &err);
+    munit_assert_null(err);
+    munit_assert_not_null(doc);
+    err = st_kdl_validate(doc);
+    munit_assert_not_null(err);
+    munit_assert_true(strstr(st_error_message(err),
+                             "unexpected property 'foo'") != NULL);
+    st_error_free(err);
+    st_kdl_document_free(doc);
+
+    return MUNIT_OK;
+}
+
+static MunitTest tests[] = {
+    { "/resolve/parse-emit-content", test_parse_emit_content, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/resolve/guard-eval", test_guard_eval, setup, teardown,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/resolve/not-os", test_not_os, setup, teardown,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/resolve/precedence", test_precedence, setup, teardown,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/resolve/parse-errors", test_parse_errors, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/resolve/os-mapping", test_os_mapping, setup, teardown,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/resolve/syntax", test_syntax, setup, teardown,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/resolve/emit-feature-aggregate", test_emit_feature_aggregate, setup,
+      teardown, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/resolve/emit-feature-guard", test_emit_feature_guard, setup, teardown,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/resolve/check-name", test_check_name, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/resolve/schema-when", test_schema_when, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { NULL, NULL, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+};
+
+static const MunitSuite suite = {
+    "/resolve", tests, NULL, 1, MUNIT_SUITE_OPTION_NONE,
+};
+
+int
+main(int argc, char *argv[MUNIT_ARRAY_PARAM(argc + 1)])
+{
+    return munit_suite_main(&suite, NULL, argc, argv);
+}

tests/unit/test_schema.c

@@ -0,0 +1,534 @@
+/* LINK: ../../src/kdl/schema.c ../../src/detect/check_registry.c ../../src/kdl/value.c ../../src/kdl/parser.c ../../src/kdl/lexer.c ../../src/error.c ../../src/span.c */
+/* tests/unit/test_schema.c
+ *
+ * Unit tests for the stupidtools DSL schema validator (todo 9).
+ *
+ * The magic LINK comment on line 1 is REQUIRED by tests/run.sh: it lists
+ * the extra .c sources to compile into this test binary (paths relative
+ * to tests/unit/, space-separated). schema.c depends on value.c (typed
+ * value interpretation) and error.c (typed errors); parser.c + lexer.c
+ * are linked so documents can be built end-to-end from source text, and
+ * span.c via error.c's st_span_print.
+ *
+ * The grammar under test is pinned in src/kdl/schema.h. Assertions check
+ * REAL error properties: category (always ST_ERR_KDL_SCHEMA), message
+ * text (must name the offending node), and exact line/col spans — never
+ * just "returns an error".
+ */
+#include "munit.h"
+
+#include "error.h"
+#include "kdl/ast.h"
+#include "kdl/schema.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* ---- fixture loading -------------------------------------------------- */
+
+/* Locate tests/fixtures/stupid.kdl. The harness runs the test binary with
+ * cwd = repo top (make check) or tests/unit (manual run); probe both. */
+static const char *
+fixture_path(void)
+{
+    static const char *const candidates[] = {
+        "tests/fixtures/stupid.kdl",
+        "../fixtures/stupid.kdl",
+    };
+    size_t i;
+
+    for (i = 0; i < sizeof(candidates) / sizeof(candidates[0]); i++) {
+        FILE *f = fopen(candidates[i], "rb");
+        if (f != NULL) {
+            fclose(f);
+            return candidates[i];
+        }
+    }
+    return NULL;
+}
+
+/* Slurp the fixture into a NUL-terminated buffer (the lexer requires NUL
+ * termination). Returns NULL on any I/O failure. Caller frees. */
+static char *
+slurp_fixture(const char *path)
+{
+    FILE *f;
+    long n;
+    char *buf;
+
+    if (path == NULL) {
+        return NULL;
+    }
+    f = fopen(path, "rb");
+    if (f == NULL) {
+        return NULL;
+    }
+    if (fseek(f, 0, SEEK_END) != 0) {
+        fclose(f);
+        return NULL;
+    }
+    n = ftell(f);
+    if (n < 0 || fseek(f, 0, SEEK_SET) != 0) {
+        fclose(f);
+        return NULL;
+    }
+    buf = munit_malloc((size_t)n + 1);
+    if (fread(buf, 1, (size_t)n, f) != (size_t)n) {
+        free(buf);
+        fclose(f);
+        return NULL;
+    }
+    fclose(f);
+    buf[n] = '\0';
+    return buf;
+}
+
+/* ---- helpers ---------------------------------------------------------- */
+
+/* Parse `src` (asserting parse success) and validate; assert the result
+ * is a ST_ERR_KDL_SCHEMA error whose message contains `needle` and whose
+ * span is exactly (line, col). */
+static void
+assert_schema_error(const char *src, const char *needle, size_t line,
+                    size_t col)
+{
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc = st_kdl_parse(src, "t.kdl", &err);
+
+    munit_assert_null(err);
+    munit_assert_not_null(doc);
+    err = st_kdl_validate(doc);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+    munit_assert_not_null(err->span);
+    munit_assert_size(err->span->line, ==, line);
+    munit_assert_size(err->span->col, ==, col);
+    munit_assert_true(strstr(st_error_message(err), needle) != NULL);
+    st_error_free(err);
+    st_kdl_document_free(doc);
+}
+
+/* Parse `src` (asserting parse success) and validate; assert success. */
+static void
+assert_valid(const char *src)
+{
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc = st_kdl_parse(src, "t.kdl", &err);
+
+    munit_assert_null(err);
+    munit_assert_not_null(doc);
+    err = st_kdl_validate(doc);
+    munit_assert_null(err);
+    st_kdl_document_free(doc);
+}
+
+/* ---- tests ------------------------------------------------------------ */
+
+/* (a) tests/fixtures/stupid.kdl validates clean and carries the expected
+ * canonical shapes: project first (name + version keyword + semver), a
+ * target with src/feature children, features with header/library check
+ * placeholders, and an option with a bool default. */
+static MunitResult
+test_valid_fixture(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    const char *path = fixture_path();
+    char *src;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+    struct st_kdl_node *n;
+    size_t top_count = 0;
+    size_t target_children = 0;
+
+    munit_assert_not_null(path);
+    src = slurp_fixture(path);
+    munit_assert_not_null(src);
+
+    doc = st_kdl_parse(src, path, &err);
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+
+    /* validates clean (the core acceptance of this todo) */
+    munit_assert_null(st_kdl_validate(doc));
+
+    /* five top-level nodes: project, feature, feature, target, option */
+    for (n = doc->nodes; n != NULL; n = n->next) {
+        top_count++;
+    }
+    munit_assert_size(top_count, ==, 5);
+
+    /* project spans (hand-verified against cat -n of the fixture) */
+    n = doc->nodes;
+    munit_assert_size(n->name.span.line, ==, 16);
+    munit_assert_size(n->name.span.col, ==, 1);
+    munit_assert_not_null(n->args);
+    munit_assert_size(n->args->value.span.col, ==, 9);        /* "stupidtools" */
+    munit_assert_size(n->args->next->value.span.col, ==, 23); /* version kw */
+    munit_assert_size(n->args->next->next->value.span.col, ==, 31); /* "1.0.0" */
+
+    /* target "default" has 6 children: 4 src + 2 feature refs */
+    for (n = doc->nodes; n != NULL && top_count-- > 0; n = n->next) {
+        if (n->name.kind == ST_TOK_IDENT && n->name.len == 6 &&
+            memcmp(n->name.text, "target", 6) == 0) {
+            struct st_kdl_node *c;
+            for (c = n->children; c != NULL; c = c->next) {
+                target_children++;
+            }
+        }
+    }
+    munit_assert_size(target_children, ==, 6);
+
+    /* option "debug" default=#false: key and value spans */
+    n = doc->nodes->next->next->next->next;
+    munit_assert_size(n->name.span.line, ==, 43);
+    munit_assert_size(n->args->value.span.col, ==, 8); /* "debug" */
+    munit_assert_not_null(n->props);
+    munit_assert_size(n->props->key.span.col, ==, 16);   /* default */
+    munit_assert_size(n->props->value.span.col, ==, 24); /* #false */
+
+    st_kdl_document_free(doc);
+    free(src);
+    return MUNIT_OK;
+}
+
+/* (c) missing project: an empty document (and a NULL document) yields a
+ * schema error with NO span (no file name is available for an empty
+ * document). */
+static MunitResult
+test_missing_project(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc;
+
+    doc = st_kdl_parse("", "t.kdl", &err);
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+    err = st_kdl_validate(doc);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+    munit_assert_null(err->span);
+    munit_assert_true(
+        strstr(st_error_message(err), "missing required 'project'") != NULL);
+    st_error_free(err);
+    st_kdl_document_free(doc);
+
+    /* comment-only documents are equally empty */
+    doc = st_kdl_parse("// nothing\n", "t.kdl", &err);
+    munit_assert_not_null(doc);
+    err = st_kdl_validate(doc);
+    munit_assert_not_null(err);
+    munit_assert_null(err->span);
+    st_error_free(err);
+    st_kdl_document_free(doc);
+
+    /* a NULL document is the same failure */
+    err = st_kdl_validate(NULL);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_SCHEMA);
+    st_error_free(err);
+    return MUNIT_OK;
+}
+
+/* (c/d) project must be FIRST: a document starting with a non-project
+ * node errors naming that node with its span. */
+static MunitResult
+test_project_not_first(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    assert_schema_error("target \"x\" { src \"a.c\" }\n"
+                        "project \"p\" version \"1.0\"",
+                        "'target'", 1, 1);
+    assert_schema_error("feature \"f\" { header \"h.h\" }\n"
+                        "project \"p\" version \"1.0\"",
+                        "'feature'", 1, 1);
+    return MUNIT_OK;
+}
+
+/* (b) unknown top-level node names the node + span, in any position after
+ * the project. */
+static MunitResult
+test_unknown_top_level(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    assert_schema_error("project \"p\" version \"1.0\"\n"
+                        "bogus \"x\"\n",
+                        "'bogus'", 2, 1);
+    assert_schema_error("project \"p\" version \"1.0\"\n"
+                        "target \"t\" { src \"a.c\" }\n"
+                        "wat 1\n",
+                        "'wat'", 3, 1);
+    return MUNIT_OK;
+}
+
+/* duplicate project nodes are rejected with the second project's span. */
+static MunitResult
+test_duplicate_project(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    assert_schema_error("project \"p\" version \"1.0\"\n"
+                        "project \"q\" version \"2.0\"\n"
+                        "target \"t\" { src \"a.c\" }\n",
+                        "duplicate 'project'", 2, 1);
+    return MUNIT_OK;
+}
+
+/* (e) missing/extra required arguments on every node shape. */
+static MunitResult
+test_missing_args(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    /* project argument shapes */
+    assert_schema_error("project", "requires a name argument", 1, 1);
+    assert_schema_error("project \"p\"", "requires a version", 1, 1);
+    assert_schema_error("project \"p\" version",
+                        "requires the version string", 1, 13);
+    assert_schema_error("project \"p\" version \"1.0\" extra",
+                        "exactly three arguments", 1, 27);
+
+    /* target/feature/option names */
+    assert_schema_error("project \"p\" version \"1.0\"\ntarget",
+                        "target requires a name argument", 2, 1);
+    assert_schema_error("project \"p\" version \"1.0\"\ntarget \"t\" \"u\"",
+                        "takes exactly one argument", 2, 12);
+    assert_schema_error("project \"p\" version \"1.0\"\nfeature",
+                        "feature requires a name argument", 2, 1);
+    assert_schema_error("project \"p\" version \"1.0\"\noption",
+                        "option requires a name argument", 2, 1);
+
+    /* project-only: a build file needs at least one target or feature */
+    assert_schema_error("project \"p\" version \"1.0\"",
+                        "missing 'target' or 'feature'", 1, 1);
+    assert_schema_error("project \"p\" version \"1.0\"\noption \"x\"",
+                        "missing 'target' or 'feature'", 1, 1);
+    return MUNIT_OK;
+}
+
+/* wrong argument types are rejected via the value model, naming what was
+ * expected and what was found. */
+static MunitResult
+test_wrong_arg_types(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    assert_schema_error("project 42 version \"1.0\"",
+                        "project name must be a non-empty string (got int)",
+                        1, 9);
+    assert_schema_error("project \"p\" 99 \"1.0\"",
+                        "expected the keyword 'version'", 1, 13);
+    assert_schema_error("project \"p\" version 42",
+                        "version must be a non-empty string (got int)", 1, 21);
+    assert_schema_error("project \"p\" version \"\"",
+                        "version must be a non-empty string", 1, 21);
+    assert_schema_error("project \"p\" version \"1.0\"\ntarget 42",
+                        "target name must be a non-empty string (got int)",
+                        2, 8);
+    return MUNIT_OK;
+}
+
+/* project extras: properties and children are not part of the pinned
+ * grammar. */
+static MunitResult
+test_project_extras(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    assert_schema_error("project \"p\" version \"1.0\" foo=1",
+                        "unexpected property 'foo'", 1, 27);
+    assert_schema_error(
+        "project \"p\" version \"1.0\" { target \"t\" { src \"a.c\" } }",
+        "takes no children", 1, 29);
+    return MUNIT_OK;
+}
+
+/* (g) unknown target children name the child + span; known children get
+ * their argument/property/children shapes enforced. */
+static MunitResult
+test_target_children(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\ntarget \"t\" { cc-flags \"-O2\" }",
+        "'cc-flags'", 2, 14);
+    assert_schema_error("project \"p\" version \"1.0\"\ntarget \"t\" { jobs 8 }",
+                        "'jobs'", 2, 14);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\ntarget \"t\" { src }",
+        "'src' requires a file argument", 2, 14);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\ntarget \"t\" { src 42 }",
+        "'src' file must be a non-empty string (got int)", 2, 18);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\ntarget \"t\" { src \"a.c\" extra }",
+        "'src' takes exactly one argument", 2, 24);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\ntarget \"t\" { src \"a.c\" foo=1 }",
+        "'src' takes no properties", 2, 24);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\ntarget \"t\" { src \"a.c\" { x } }",
+        "'src' takes no children", 2, 26);
+
+    /* feature references inside a target */
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\ntarget \"t\" { feature }",
+        "'feature' requires a name argument", 2, 14);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\ntarget \"t\" { feature 42 }",
+        "'feature' name must be a non-empty string (got int)", 2, 22);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\ntarget \"t\" { feature \"p\" foo=1 }",
+        "'feature' takes no properties", 2, 26);
+    return MUNIT_OK;
+}
+
+/* feature children: each check's NAME must be one of the 8 kinds from
+ * the feature-check registry (todo 10), and the kind's argument shape is
+ * enforced (exactly one non-empty string target, no children; the
+ * optional `version` property is todo 10's too - see
+ * test_check_registry.c for the per-kind table). */
+static MunitResult
+test_feature_checks_structural(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    /* the two fixture kinds plus the rest of the 8 kinds pass */
+    assert_valid("project \"p\" version \"1.0\"\n"
+                 "feature \"f\" { header \"h.h\"\nlibrary \"l\" }");
+    assert_valid("project \"p\" version \"1.0\"\n"
+                 "feature \"f\" { type \"size_t\"\nsizeof \"int\"\n"
+                 "function \"strdup\"\nprogram \"gcc\"\n"
+                 "compiler_flag \"-Wall\"\npkg_config \"zlib\" }");
+
+    /* unknown check kinds are rejected (registry dispatch, todo 10) */
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\nfeature \"f\" { frobnicate \"x\" }",
+        "'frobnicate'", 2, 15);
+
+    /* but a check still needs its argument (a non-empty string) */
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\nfeature \"f\" { header }",
+        "check 'header' requires an argument", 2, 15);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\nfeature \"f\" { header 42 }",
+        "check 'header' argument must be a non-empty string (got int)",
+        2, 22);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\nfeature \"f\" { header \"h.h\" { x } }",
+        "check 'header' takes no children", 2, 30);
+
+    /* feature shapes */
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\nfeature \"f\" \"g\" { header \"h.h\" }",
+        "feature 'f' takes exactly one argument", 2, 13);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\nfeature \"f\" foo=1 { header \"h.h\" }",
+        "feature 'f' has unexpected property 'foo'", 2, 13);
+    return MUNIT_OK;
+}
+
+/* (f) option: `default` is an optional bool property; non-bool defaults
+ * are rejected with the value's span, as are other properties, duplicate
+ * defaults, children, and annotated values. */
+static MunitResult
+test_option_default(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    assert_valid("project \"p\" version \"1.0\"\n"
+                 "target \"t\" { src \"a.c\" }\n"
+                 "option \"debug\" default=#true");
+    assert_valid("project \"p\" version \"1.0\"\n"
+                 "target \"t\" { src \"a.c\" }\n"
+                 "option \"x\"");
+
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\n"
+        "target \"t\" { src \"a.c\" }\n"
+        "option \"x\" default=\"yes\"",
+        "'default' must be a boolean (got string)", 3, 20);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\n"
+        "target \"t\" { src \"a.c\" }\n"
+        "option \"x\" default=1",
+        "'default' must be a boolean (got int)", 3, 20);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\n"
+        "target \"t\" { src \"a.c\" }\n"
+        "option \"x\" default=#null",
+        "'default' must be a boolean (got null)", 3, 20);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\n"
+        "target \"t\" { src \"a.c\" }\n"
+        "option \"x\" default=(bool)#true",
+        "'default' must not carry a type annotation", 3, 26);
+
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\n"
+        "target \"t\" { src \"a.c\" }\n"
+        "option \"x\" foo=1",
+        "unexpected property 'foo' (only 'default' is allowed)", 3, 12);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\n"
+        "target \"t\" { src \"a.c\" }\n"
+        "option \"x\" default=#true default=#false",
+        "duplicate 'default' property", 3, 26);
+    assert_schema_error(
+        "project \"p\" version \"1.0\"\n"
+        "target \"t\" { src \"a.c\" }\n"
+        "option \"x\" { default #true }",
+        "option 'x' takes no children", 3, 14);
+    return MUNIT_OK;
+}
+
+static MunitTest tests[] = {
+    { "/schema/valid-fixture", test_valid_fixture, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/schema/missing-project", test_missing_project, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/schema/project-not-first", test_project_not_first, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/schema/unknown-top-level", test_unknown_top_level, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/schema/duplicate-project", test_duplicate_project, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/schema/missing-args", test_missing_args, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/schema/wrong-arg-types", test_wrong_arg_types, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/schema/project-extras", test_project_extras, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/schema/target-children", test_target_children, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/schema/feature-checks-structural", test_feature_checks_structural,
+      NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/schema/option-default", test_option_default, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { NULL, NULL, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+};
+
+static const MunitSuite suite = {
+    "/schema", tests, NULL, 1, MUNIT_SUITE_OPTION_NONE,
+};
+
+int
+main(int argc, char *argv[MUNIT_ARRAY_PARAM(argc + 1)])
+{
+    return munit_suite_main(&suite, NULL, argc, argv);
+}

tests/unit/test_sh_emit.c

@@ -0,0 +1,613 @@
+/* LINK: ../../src/gen/sh_emit.c ../../src/error.c ../../src/span.c */
+#define _POSIX_C_SOURCE 200809L /* mkdtemp(3) under -std=c23 */
+/* tests/unit/test_sh_emit.c
+ *
+ * Unit tests for the POSIX-sh text emitter (todo 15).
+ *
+ * The magic LINK comment on line 1 is REQUIRED by tests/run.sh: it lists
+ * the extra .c sources to compile into this test binary (paths relative
+ * to tests/unit/, space-separated). munit.c and the include dirs are
+ * added automatically by the harness.
+ *
+ * Strategy: st_sh_quote() is the load-bearing primitive, so the core
+ * proof is the ROUND-TRIP — the quoted literal, dropped into a real
+ * shell script as `v=<quoted>; printf '%s' "$v" > <out>`, must reproduce
+ * the exact input bytes when the script is executed by sh, bash and zsh.
+ * The same machinery proves the injection attempt stays inert.
+ *
+ * No command substitution is used to capture output anywhere here: it
+ * strips trailing newlines, which would mask a broken round-trip.
+ */
+#include "munit.h"
+
+#include "error.h"
+#include "gen/sh_emit.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <sys/wait.h>
+#include <unistd.h>
+
+/* Per-test temp dir, created in setup, removed in teardown. */
+static char temp_dir[128];
+
+static void *
+setup(const MunitParameter params[], void *user_data)
+{
+    (void)params;
+    (void)user_data;
+    if (snprintf(temp_dir, sizeof temp_dir, "/tmp/st_emit_XXXXXX") < 0) {
+        return NULL;
+    }
+    if (mkdtemp(temp_dir) == NULL) {
+        return NULL;
+    }
+    return (void *)1;
+}
+
+static void
+teardown(void *fixture)
+{
+    char cmd[160];
+
+    if (fixture == NULL || temp_dir[0] == '\0') {
+        return;
+    }
+    if (snprintf(cmd, sizeof cmd, "rm -rf -- '%s'", temp_dir) < 0) {
+        return;
+    }
+    (void)system(cmd); /* best-effort; mkdtemp names are [A-Za-z0-9_]* */
+    temp_dir[0] = '\0';
+}
+
+/* Run "<shell> -n <path>", return the shell's exit status, or -1 if the
+ * command could not even be spawned. */
+static int
+syntax_check(const char *shell, const char *path)
+{
+    char cmd[512];
+    int rc;
+
+    if (snprintf(cmd, sizeof cmd, "%s -n %s", shell, path) < 0) {
+        return -1;
+    }
+    rc = system(cmd);
+    if (rc == -1) {
+        return -1;
+    }
+    return WEXITSTATUS(rc);
+}
+
+/* Round-trip `value` through one shell: write a script that assigns
+ * st_sh_quote(value) to a variable and printf's it into a file, execute
+ * it, and byte-compare the file with the original. Returns the shell's
+ * exit status, or -1 on setup failure. */
+static int
+roundtrip_one(const char *shell, const char *value, size_t len,
+              const char *pathbase)
+{
+    char script_path[512];
+    char out_path[512];
+    char *q, *qout;
+    FILE *f;
+    FILE *in;
+    char *got;
+    long n;
+    int rc;
+
+    q = st_sh_quote_n(value, len, NULL);
+    if (q == NULL) {
+        return -1;
+    }
+    if (snprintf(script_path, sizeof script_path, "%s/%s.sh", temp_dir,
+                 pathbase) < 0) {
+        free(q);
+        return -1;
+    }
+    if (snprintf(out_path, sizeof out_path, "%s/%s.out", temp_dir,
+                 pathbase) < 0) {
+        free(q);
+        return -1;
+    }
+    qout = st_sh_quote(out_path);
+    if (qout == NULL) {
+        free(q);
+        return -1;
+    }
+    f = fopen(script_path, "w");
+    if (f == NULL) {
+        free(q);
+        free(qout);
+        return -1;
+    }
+    /* q and qout are st_sh_quote() output: shell-safe by construction. */
+    if (fprintf(f, "v=%s\nprintf '%%s' \"$v\" > %s\n", q, qout) < 0) {
+        fclose(f);
+        free(q);
+        free(qout);
+        return -1;
+    }
+    fclose(f);
+    free(q);
+    free(qout);
+
+    {
+        char cmd[1200];
+        int spawned;
+
+        if (snprintf(cmd, sizeof cmd, "%s %s", shell, script_path) < 0) {
+            return -1;
+        }
+        spawned = system(cmd);
+        if (spawned == -1) {
+            return -1;
+        }
+        rc = WEXITSTATUS(spawned);
+    }
+    if (rc != 0) {
+        return rc;
+    }
+    in = fopen(out_path, "rb");
+    if (in == NULL) {
+        return -1;
+    }
+    if (fseek(in, 0, SEEK_END) != 0) {
+        fclose(in);
+        return -1;
+    }
+    n = ftell(in);
+    if (n < 0 || fseek(in, 0, SEEK_SET) != 0) {
+        fclose(in);
+        return -1;
+    }
+    got = munit_malloc((size_t)n + 1);
+    if (fread(got, 1, (size_t)n, in) != (size_t)n) {
+        free(got);
+        fclose(in);
+        return -1;
+    }
+    fclose(in);
+    got[n] = '\0';
+    if ((size_t)n != len || memcmp(got, value, len) != 0) {
+        free(got);
+        return -2; /* round-trip mismatch */
+    }
+    free(got);
+    return 0;
+}
+
+/* Round-trip through sh, bash and zsh; -2 means content mismatch. */
+static void
+roundtrip_assert(const char *value, size_t len, const char *pathbase)
+{
+    munit_assert_int(roundtrip_one("sh", value, len, pathbase), ==, 0);
+    munit_assert_int(roundtrip_one("bash", value, len, pathbase), ==, 0);
+    munit_assert_int(roundtrip_one("zsh", value, len, pathbase), ==, 0);
+}
+
+static void
+roundtrip_assert_str(const char *value, const char *pathbase)
+{
+    roundtrip_assert(value, strlen(value), pathbase);
+}
+
+/* --- exact literal format ------------------------------------------------- */
+
+static MunitResult
+test_quote_empty(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    char *q = st_sh_quote("");
+
+    munit_assert_not_null(q);
+    munit_assert_string_equal(q, "''");
+    free(q);
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_quote_plain(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    char *q = st_sh_quote("abc");
+
+    munit_assert_not_null(q);
+    munit_assert_string_equal(q, "'abc'");
+    free(q);
+    return MUNIT_OK;
+}
+
+/* The canonical escape shape is locked byte-for-byte: each `'` becomes
+ * the 4-char sequence '\'' between the two surrounding quotes. */
+static MunitResult
+test_quote_literal_format(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    char *q;
+
+    q = st_sh_quote("'");
+    munit_assert_not_null(q);
+    munit_assert_string_equal(q, "''\\'''");
+    free(q);
+
+    q = st_sh_quote("a'b");
+    munit_assert_not_null(q);
+    munit_assert_string_equal(q, "'a'\\''b'");
+    free(q);
+    return MUNIT_OK;
+}
+
+/* --- round-trips through real shells -------------------------------------- */
+
+static MunitResult
+test_quote_roundtrip_fixed(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    static const char *const hostile[] = {
+        "a'b\"c $d",
+        "''",
+        "'''",
+        "$(rm -rf /)",
+        "`rm -rf /`",
+        "\\", "$", "\"", "'", "`",
+        "line1\nline2\n",
+        "\nleading",
+        "trailing\n",
+        "\t tab\t$HOME\t",
+        "$PATH ${HOME} ~ *.txt ?[a] ; | & > <",
+        "#! /bin/sh",
+        "--prefix=/tmp/x y",
+        "=;:,%^(){}[]<>!#~",
+        "h\xC3\xA9llo w\xC3\xB6rld \xE2\x9C\x93", /* UTF-8 */
+        "",
+    };
+    size_t i;
+
+    for (i = 0; i < sizeof hostile / sizeof hostile[0]; i++) {
+        char base[64];
+
+        if (snprintf(base, sizeof base, "fixed%zu", i) < 0) {
+            return MUNIT_ERROR;
+        }
+        roundtrip_assert_str(hostile[i], base);
+    }
+    return MUNIT_OK;
+}
+
+/* xorshift32 with a fixed seed: deterministic property test. */
+static uint32_t rng_state = 0x2E3A5B7Fu;
+
+static uint32_t
+rng_next(void)
+{
+    uint32_t x = rng_state;
+
+    x ^= x << 13;
+    x ^= x >> 17;
+    x ^= x << 5;
+    rng_state = x;
+    return x;
+}
+
+static MunitResult
+test_quote_roundtrip_random(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    /* Hostile alphabet: every byte class that matters to a shell. */
+    static const char alphabet[] =
+        "'\"\\$`();|&><*?[]{}!~#%^=:,./- \t\n"
+        "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+    char buf[80];
+    int iter;
+
+    for (iter = 0; iter < 96; iter++) {
+        size_t len = (size_t)(rng_next() % sizeof buf);
+        size_t i;
+        char base[64];
+
+        for (i = 0; i < len; i++) {
+            buf[i] = alphabet[rng_next() % (sizeof alphabet - 1)];
+        }
+        if (snprintf(base, sizeof base, "rnd%d", iter) < 0) {
+            return MUNIT_ERROR;
+        }
+        roundtrip_assert(buf, len, base);
+    }
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_quote_long_single_quotes(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    char *big = munit_malloc(1001);
+    size_t i;
+
+    for (i = 0; i < 1000; i++) {
+        big[i] = '\'';
+    }
+    big[1000] = '\0';
+    roundtrip_assert_str(big, "big");
+    free(big);
+    return MUNIT_OK;
+}
+
+/* --- injection proof ------------------------------------------------------ */
+
+static MunitResult
+test_quote_injection_inert(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    char marker[512];
+    char script_path[512];
+    char out_path[512];
+    char *payload, *q, *qout;
+    FILE *f;
+    FILE *in;
+    char *got;
+    long n;
+    int rc;
+
+    (void)params;
+    (void)data;
+    if (snprintf(marker, sizeof marker, "%s/PWNED", temp_dir) < 0) {
+        return MUNIT_ERROR;
+    }
+    /* Classic break-out: close the quote, run a command, reopen it. */
+    payload = munit_malloc(512);
+    if (snprintf(payload, 512, "'; echo PWNED > %s; echo '", marker) < 0) {
+        free(payload);
+        return MUNIT_ERROR;
+    }
+    q = st_sh_quote(payload);
+    munit_assert_not_null(q);
+    if (snprintf(script_path, sizeof script_path, "%s/inject.sh", temp_dir) < 0) {
+        free(payload);
+        free(q);
+        return MUNIT_ERROR;
+    }
+    if (snprintf(out_path, sizeof out_path, "%s/inject.out", temp_dir) < 0) {
+        free(payload);
+        free(q);
+        return MUNIT_ERROR;
+    }
+    qout = st_sh_quote(out_path);
+    munit_assert_not_null(qout);
+    f = fopen(script_path, "w");
+    munit_assert_not_null(f);
+    {
+        int wr = fprintf(f, "v=%s\nprintf '%%s' \"$v\" > %s\n", q, qout);
+
+        munit_assert_int(wr, >=, 0);
+    }
+    fclose(f);
+    free(q);
+    free(qout);
+
+    {
+        char cmd[1200];
+        int spawned;
+        int snrc = snprintf(cmd, sizeof cmd, "sh %s", script_path);
+
+        munit_assert_int(snrc, >=, 0);
+        spawned = system(cmd);
+        munit_assert_int(spawned, !=, -1);
+        rc = WEXITSTATUS(spawned);
+    }
+    munit_assert_int(rc, ==, 0);
+    /* The attack command must NOT have run. */
+    munit_assert_int(access(marker, F_OK), ==, -1);
+
+    /* And the output must be the exact payload bytes. */
+    in = fopen(out_path, "rb");
+    munit_assert_not_null(in);
+    munit_assert_int(fseek(in, 0, SEEK_END), ==, 0);
+    n = ftell(in);
+    munit_assert_int(n, ==, (long)strlen(payload));
+    munit_assert_int(fseek(in, 0, SEEK_SET), ==, 0);
+    got = munit_malloc((size_t)n + 1);
+    munit_assert_size(fread(got, 1, (size_t)n, in), ==, (size_t)n);
+    fclose(in);
+    got[n] = '\0';
+    munit_assert_memory_equal((size_t)n, got, payload);
+    free(got);
+    free(payload);
+    return MUNIT_OK;
+}
+
+/* --- NUL / NULL input handling ------------------------------------------- */
+
+static MunitResult
+test_quote_null_input(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    char *q;
+
+    q = st_sh_quote(NULL);
+    munit_assert_null(q);
+
+    q = st_sh_quote_ex(NULL, &err);
+    munit_assert_null(q);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_INTERNAL);
+    munit_assert_int(strlen(st_error_message(err)), >, 0);
+    st_error_free(err);
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_quote_nul_byte(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    char *q;
+
+    /* embedded NUL detected through the length-bounded variant */
+    q = st_sh_quote_n("a\0b", 3, &err);
+    munit_assert_null(q);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_INTERNAL);
+    st_error_free(err);
+
+    /* same input, truncated to the bytes before the NUL: fine */
+    q = st_sh_quote_n("a\0b", 1, NULL);
+    munit_assert_not_null(q);
+    munit_assert_string_equal(q, "'a'");
+    free(q);
+    return MUNIT_OK;
+}
+
+/* --- emitter helpers: the sample script ----------------------------------- */
+
+/* Assembles a small representative configure-style script exclusively
+ * through the emitter API, then proves on the ACTUAL emitted bytes:
+ *  - sh -n, bash -n and zsh -n all accept it,
+ *  - none of the banned constructs appear,
+ *  - it actually runs and prints the expected line. */
+static MunitResult
+test_emit_sample_script(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    static const char *const banned[] = {
+        "[[ ", "]]", "local ", "==", "<<<", "&>", "set -e",
+    };
+    char script_path[512];
+    FILE *f;
+    char *q;
+    FILE *in;
+    char *bytes;
+    long n;
+    size_t i;
+
+    if (snprintf(script_path, sizeof script_path, "%s/sample.sh", temp_dir) < 0) {
+        return MUNIT_ERROR;
+    }
+    f = fopen(script_path, "w");
+    munit_assert_not_null(f);
+
+    munit_assert_int(st_sh_emit_str(f, "#!/bin/sh\n"), ==, 0);
+    munit_assert_int(st_sh_emit_comment(f, "generated sample\nline two"), ==, 0);
+    munit_assert_int(st_sh_emit_assign_q(f, "prefix", "/usr/local"), ==, 0);
+    q = st_sh_quote("it's fine");
+    munit_assert_not_null(q);
+    munit_assert_int(st_sh_emit_assign(f, "greeting", q), ==, 0);
+    free(q);
+    munit_assert_int(st_sh_emit_str(f, "if [ \"$1\" = \"--help\" ]; then\n"
+        "    echo 'usage: configure [--prefix=DIR] [VAR=VALUE]'\n"
+        "    exit 0\n"
+        "fi\n"
+        "case \"$1\" in\n"
+        "    --prefix=*)\n"
+        "        prefix=${1#--prefix=}\n"
+        "        ;;\n"
+        "    '')\n"
+        "        ;;\n"
+        "    *)\n"
+        "        echo \"unrecognized option: $1\" >&2\n"
+        "        exit 1\n"
+        "        ;;\n"
+        "esac\n"
+        "echo \"prefix is $prefix; greeting is $greeting\"\n"), ==, 0);
+    fclose(f);
+
+    /* lock the comment/assign byte shapes */
+    in = fopen(script_path, "rb");
+    munit_assert_not_null(in);
+    munit_assert_int(fseek(in, 0, SEEK_END), ==, 0);
+    n = ftell(in);
+    munit_assert_int(n, >, 0);
+    munit_assert_int(fseek(in, 0, SEEK_SET), ==, 0);
+    bytes = munit_malloc((size_t)n + 1);
+    munit_assert_size(fread(bytes, 1, (size_t)n, in), ==, (size_t)n);
+    fclose(in);
+    bytes[n] = '\0';
+
+    munit_assert_not_null(strstr(bytes, "# generated sample\n# line two\n"));
+    munit_assert_not_null(strstr(bytes, "prefix='/usr/local'\n"));
+    munit_assert_not_null(strstr(bytes, "greeting='it'\\''s fine'\n"));
+
+    /* the banned-construct sweep on the real emitted bytes */
+    for (i = 0; i < sizeof banned / sizeof banned[0]; i++) {
+        munit_assert_null(strstr(bytes, banned[i]));
+    }
+
+    /* syntax: sh -n / bash -n / zsh -n on the actual file */
+    munit_assert_int(syntax_check("sh", script_path), ==, 0);
+    munit_assert_int(syntax_check("bash", script_path), ==, 0);
+    munit_assert_int(syntax_check("zsh", script_path), ==, 0);
+
+    /* behavior: the script must actually run (exit 0, expected echo) */
+    {
+        char cmd[1200];
+        int spawned;
+        int snrc = snprintf(cmd, sizeof cmd, "sh %s", script_path);
+
+        munit_assert_int(snrc, >=, 0);
+        spawned = system(cmd);
+        munit_assert_int(spawned, !=, -1);
+        munit_assert_int(WEXITSTATUS(spawned), ==, 0);
+    }
+
+    free(bytes);
+    return MUNIT_OK;
+}
+
+/* defensive behavior of the emitters (never write on bad input) */
+static MunitResult
+test_emit_null_guards(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    FILE *f = tmpfile();
+
+    munit_assert_not_null(f);
+    munit_assert_int(st_sh_emit_str(NULL, "x"), ==, -1);
+    munit_assert_int(st_sh_emit_str(f, NULL), ==, -1);
+    munit_assert_int(st_sh_emit_comment(NULL, "x"), ==, -1);
+    munit_assert_int(st_sh_emit_comment(f, NULL), ==, -1);
+    munit_assert_int(st_sh_emit_assign(NULL, "a", "b"), ==, -1);
+    munit_assert_int(st_sh_emit_assign(f, NULL, "b"), ==, -1);
+    munit_assert_int(st_sh_emit_assign(f, "a", NULL), ==, -1);
+    munit_assert_int(st_sh_emit_assign_q(NULL, "a", "b"), ==, -1);
+    munit_assert_int(st_sh_emit_assign_q(f, "a", NULL), ==, -1);
+    fclose(f);
+    return MUNIT_OK;
+}
+
+static MunitTest tests[] = {
+    { "/quote/empty", test_quote_empty, setup, teardown, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/quote/plain", test_quote_plain, setup, teardown, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/quote/literal-format", test_quote_literal_format, setup, teardown, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/quote/roundtrip-fixed", test_quote_roundtrip_fixed, setup, teardown, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/quote/roundtrip-random", test_quote_roundtrip_random, setup, teardown, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/quote/long-single-quotes", test_quote_long_single_quotes, setup, teardown, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/quote/injection-inert", test_quote_injection_inert, setup, teardown, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/quote/null-input", test_quote_null_input, setup, teardown, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/quote/nul-byte", test_quote_nul_byte, setup, teardown, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/emit/sample-script", test_emit_sample_script, setup, teardown, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/emit/null-guards", test_emit_null_guards, setup, teardown, MUNIT_TEST_OPTION_NONE, NULL },
+    { NULL, NULL, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+};
+
+static const MunitSuite suite = {
+    "/sh_emit", tests, NULL, 1, MUNIT_SUITE_OPTION_NONE,
+};
+
+int
+main(int argc, char *argv[MUNIT_ARRAY_PARAM(argc + 1)])
+{
+    return munit_suite_main(&suite, NULL, argc, argv);
+}

tests/unit/test_value.c

@@ -0,0 +1,632 @@
+/* LINK: ../../src/kdl/value.c ../../src/kdl/parser.c ../../src/kdl/lexer.c ../../src/error.c ../../src/span.c */
+/* tests/unit/test_value.c
+ *
+ * Unit tests for the typed KDL value model (todo 8).
+ *
+ * The magic LINK comment on line 1 is REQUIRED by tests/run.sh: it lists the
+ * extra .c sources to compile into this test binary (paths relative to
+ * tests/unit/, space-separated). value.c depends on error.c (typed errors) and
+ * span.c (caret rendering); parser.c + lexer.c are linked so the value-level
+ * type-annotation integration can be tested END-TO-END through the parser.
+ *
+ * Most value-model cases are exercised by constructing a token ref DIRECTLY
+ * (mkref), which bypasses the lexer's already-strict escape/radix validation
+ * and lets us probe the value model's own boundary handling (unknown escapes,
+ * `0xZZ`, overflow, i128 width) that the lexer would otherwise reject first.
+ * Assertions check CONCRETE parsed values (kind + payload + annotation), never
+ * just "does not crash".
+ */
+#include "munit.h"
+
+#include "error.h"
+#include "kdl/ast.h"
+#include "kdl/lexer.h"
+#include "kdl/value.h"
+
+#include <math.h>
+#include <stdbool.h>
+#include <stdio.h>
+#include <string.h>
+
+/* ---- token-ref construction ------------------------------------------- */
+
+/* Build a borrowed token ref over a NUL-terminated C string (the string
+ * literal outlives the value call, so the borrow is safe). */
+static struct st_kdl_token_ref
+mkref(enum st_token_kind kind, const char *text)
+{
+    struct st_kdl_token_ref r;
+
+    r.kind = kind;
+    r.span.file = "test.kdl";
+    r.span.line = 1;
+    r.span.col = 1;
+    r.text = text;
+    r.len = strlen(text);
+    return r;
+}
+
+/* Parse a value token directly (no annotation); assert success and return
+ * the value. munit's longjmp aborts the test on assertion failure. */
+static struct st_kdl_value
+ok_value(enum st_token_kind kind, const char *text)
+{
+    struct st_kdl_token_ref r = mkref(kind, text);
+    struct st_kdl_value v;
+    struct st_error *err = st_kdl_value_from_token(&r, &v);
+
+    munit_assert_null(err);
+    return v;
+}
+
+/* Parse a value token with an explicit type-annotation ref; assert success. */
+static struct st_kdl_value
+ok_annotated(enum st_token_kind kind, const char *text, const char *ann)
+{
+    struct st_kdl_token_ref r = mkref(kind, text);
+    struct st_kdl_token_ref a = mkref(ST_TOK_TYPE, ann);
+    struct st_kdl_value v;
+    struct st_error *err = st_kdl_value_from_token_annotated(&r, &a, &v);
+
+    munit_assert_null(err);
+    return v;
+}
+
+/* Assert that parsing `text` (kind) fails with category KDL_PARSE and a
+ * message containing `needle`. */
+static void
+expect_error(enum st_token_kind kind, const char *text, const char *needle)
+{
+    struct st_kdl_token_ref r = mkref(kind, text);
+    struct st_kdl_value v;
+    struct st_error *err = st_kdl_value_from_token(&r, &v);
+
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_PARSE);
+    munit_assert_not_null(err->span);
+    munit_assert_true(strstr(st_error_message(err), needle) != NULL);
+    st_error_free(err);
+}
+
+/* ---- number tests ------------------------------------------------------ */
+
+static MunitResult
+test_radix_ints(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_kdl_value v;
+
+    v = ok_value(ST_TOK_NUMBER, "0xff");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_INT);
+    munit_assert_llong(v.as.i, ==, 255);
+
+    v = ok_value(ST_TOK_NUMBER, "0o17");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_INT);
+    munit_assert_llong(v.as.i, ==, 15);
+
+    v = ok_value(ST_TOK_NUMBER, "0b101");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_INT);
+    munit_assert_llong(v.as.i, ==, 5);
+
+    st_kdl_value_free(&v);
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_decimal_and_sign(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_kdl_value v;
+
+    v = ok_value(ST_TOK_NUMBER, "42");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_INT);
+    munit_assert_llong(v.as.i, ==, 42);
+
+    v = ok_value(ST_TOK_NUMBER, "-42");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_INT);
+    munit_assert_llong(v.as.i, ==, -42);
+
+    v = ok_value(ST_TOK_NUMBER, "+7");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_INT);
+    munit_assert_llong(v.as.i, ==, 7);
+
+    v = ok_value(ST_TOK_NUMBER, "1_000");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_INT);
+    munit_assert_llong(v.as.i, ==, 1000);
+
+    st_kdl_value_free(&v);
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_floats(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_kdl_value v;
+
+    v = ok_value(ST_TOK_NUMBER, "1.5");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_FLOAT);
+    munit_assert_double_equal(v.as.f, 1.5, 12);
+
+    /* trailing dot, no fraction digits (direct ref: the lexer splits this) */
+    v = ok_value(ST_TOK_NUMBER, "3.");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_FLOAT);
+    munit_assert_double_equal(v.as.f, 3.0, 12);
+
+    st_kdl_value_free(&v);
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_exponents(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_kdl_value v;
+
+    v = ok_value(ST_TOK_NUMBER, "1e10");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_FLOAT);
+    munit_assert_double_equal(v.as.f, 1e10, 12);
+
+    v = ok_value(ST_TOK_NUMBER, "2.5e-3");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_FLOAT);
+    munit_assert_double_equal(v.as.f, 2.5e-3, 12);
+
+    st_kdl_value_free(&v);
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_keyword_numbers(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_kdl_value v;
+
+    v = ok_value(ST_TOK_INF, "#inf");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_FLOAT);
+    munit_assert_true(isinf(v.as.f));
+    munit_assert_true(v.as.f > 0);
+
+    v = ok_value(ST_TOK_NEG_INF, "#-inf");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_FLOAT);
+    munit_assert_true(isinf(v.as.f));
+    munit_assert_true(v.as.f < 0);
+
+    v = ok_value(ST_TOK_NAN, "#nan");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_FLOAT);
+    munit_assert_true(isnan(v.as.f));
+
+    st_kdl_value_free(&v);
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_bool_null(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_kdl_value v;
+
+    v = ok_value(ST_TOK_TRUE, "#true");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_BOOL);
+    munit_assert_true(v.as.b);
+
+    v = ok_value(ST_TOK_FALSE, "#false");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_BOOL);
+    munit_assert_false(v.as.b);
+
+    v = ok_value(ST_TOK_NULL, "#null");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_NULL);
+
+    st_kdl_value_free(&v);
+    return MUNIT_OK;
+}
+
+/* ---- string tests ------------------------------------------------------ */
+
+static MunitResult
+test_ident_and_quoted(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_kdl_value v;
+
+    v = ok_value(ST_TOK_IDENT, "foo");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_STRING);
+    munit_assert_string_equal(v.as.str, "foo");
+    st_kdl_value_free(&v);
+
+    v = ok_value(ST_TOK_STRING, "\"hello\"");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_STRING);
+    munit_assert_string_equal(v.as.str, "hello");
+    st_kdl_value_free(&v);
+
+    /* empty quoted string */
+    v = ok_value(ST_TOK_STRING, "\"\"");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_STRING);
+    munit_assert_string_equal(v.as.str, "");
+    st_kdl_value_free(&v);
+
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_escapes(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_kdl_value v;
+
+    /* "a\nb" -> a, newline, b */
+    v = ok_value(ST_TOK_STRING, "\"a\\nb\"");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_STRING);
+    munit_assert_string_equal(v.as.str, "a\nb");
+    st_kdl_value_free(&v);
+
+    /* backslash + quote + tab + carriage return */
+    v = ok_value(ST_TOK_STRING, "\"\\\\\\\"\\t\\r\"");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_STRING);
+    munit_assert_string_equal(v.as.str, "\\\"\t\r");
+    st_kdl_value_free(&v);
+
+    /* space escape \s */
+    v = ok_value(ST_TOK_STRING, "\"a\\sb\"");
+    munit_assert_string_equal(v.as.str, "a b");
+    st_kdl_value_free(&v);
+
+    /* backspace + form feed + vertical tab + bell + apostrophe (lenient) */
+    v = ok_value(ST_TOK_STRING, "\"\\b\\f\\v\\a\\'\"");
+    munit_assert_string_equal(v.as.str, "\b\f\v\a'");
+    st_kdl_value_free(&v);
+
+    /* hex byte \x41 -> 'A' */
+    v = ok_value(ST_TOK_STRING, "\"\\x41\"");
+    munit_assert_string_equal(v.as.str, "A");
+    st_kdl_value_free(&v);
+
+    /* unicode \u{1F600} -> U+1F600 (UTF-8 F0 9F 98 80) */
+    v = ok_value(ST_TOK_STRING, "\"\\u{1F600}\"");
+    munit_assert_string_equal(v.as.str, "\xF0\x9F\x98\x80");
+    st_kdl_value_free(&v);
+
+    /* \u{10FFFF} is the maximum Unicode scalar value (UTF-8 F4 8F BF BF) */
+    v = ok_value(ST_TOK_STRING, "\"\\u{10FFFF}\"");
+    munit_assert_string_equal(v.as.str, "\xF4\x8F\xBF\xBF");
+    st_kdl_value_free(&v);
+
+    /* whitespace escape: backslash + spaces + newline -> nothing */
+    v = ok_value(ST_TOK_STRING, "\"Hello \\    World\"");
+    munit_assert_string_equal(v.as.str, "Hello World");
+    st_kdl_value_free(&v);
+
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_raw_string(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_kdl_value v;
+
+    /* #"raw\n"# -> literal backslash-n (no escape processing) */
+    v = ok_value(ST_TOK_RAW_STRING, "#\"raw\\n\"#");
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_STRING);
+    munit_assert_string_equal(v.as.str, "raw\\n");
+    st_kdl_value_free(&v);
+
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_multiline_dedent(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_kdl_value v;
+    const char *ml = "\"\"\"\n    foo\n    bar\n    \"\"\"";
+
+    v = ok_value(ST_TOK_MULTILINE_STRING, ml);
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_STRING);
+    munit_assert_string_equal(v.as.str, "foo\nbar");
+    st_kdl_value_free(&v);
+
+    /* no trailing newline issues: an empty multi-line string */
+    v = ok_value(ST_TOK_MULTILINE_STRING, "\"\"\"\n    \"\"\"");
+    munit_assert_string_equal(v.as.str, "");
+    st_kdl_value_free(&v);
+
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_multiline_escaped_newline(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_kdl_value v;
+    /* interior \n escape stays a newline (not dedented away) */
+    const char *ml = "\"\"\"\n    a\\nb\n    \"\"\"";
+
+    v = ok_value(ST_TOK_MULTILINE_STRING, ml);
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_STRING);
+    munit_assert_string_equal(v.as.str, "a\nb");
+    st_kdl_value_free(&v);
+
+    return MUNIT_OK;
+}
+
+/* ---- error tests ------------------------------------------------------- */
+
+static MunitResult
+test_unknown_escape(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    /* '\q' is not a KDL escape (direct ref; the lexer would reject it) */
+    expect_error(ST_TOK_STRING, "\"a\\qb\"", "unknown escape");
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_unterminated_escape(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    /* lone trailing backslash inside the quotes ("abc\" -> body "abc\") */
+    expect_error(ST_TOK_STRING, "\"abc\\\"", "unterminated");
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_bad_radix(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    expect_error(ST_TOK_NUMBER, "0xZZ", "invalid digit");
+    expect_error(ST_TOK_NUMBER, "0o8", "invalid digit");
+    expect_error(ST_TOK_NUMBER, "0b2", "invalid digit");
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_integer_overflow(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    /* 24 digits, far beyond u64 (and i64) */
+    expect_error(ST_TOK_NUMBER, "999999999999999999999999", "overflow");
+
+    /* 2^63 as an unannotated (signed) literal is one past i64 max */
+    expect_error(ST_TOK_NUMBER, "9223372036854775808", "overflow");
+    return MUNIT_OK;
+}
+
+/* ---- annotation tests -------------------------------------------------- */
+
+static MunitResult
+test_unicode_out_of_range(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    /* above the scalar-value range */
+    expect_error(ST_TOK_STRING, "\"\\u{110000}\"", "Unicode scalar");
+    /* a UTF-16 surrogate is not a scalar value */
+    expect_error(ST_TOK_STRING, "\"\\u{D800}\"", "Unicode scalar");
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_annotation_u8(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_kdl_value v = ok_annotated(ST_TOK_NUMBER, "42", "u8");
+
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_UINT);
+    munit_assert_ullong(v.as.u, ==, 42);
+    munit_assert_not_null(v.annotation);
+    munit_assert_string_equal(v.annotation, "u8");
+
+    st_kdl_value_free(&v);
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_annotation_unsigned_rejects_negative(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_kdl_token_ref r = mkref(ST_TOK_NUMBER, "-1");
+    struct st_kdl_token_ref a = mkref(ST_TOK_TYPE, "u8");
+    struct st_kdl_value v;
+    struct st_error *err = st_kdl_value_from_token_annotated(&r, &a, &v);
+
+    munit_assert_not_null(err);
+    munit_assert_true(strstr(st_error_message(err), "unsigned") != NULL);
+    st_error_free(err);
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_annotation_unsupported_width(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_kdl_token_ref r = mkref(ST_TOK_NUMBER, "42");
+    struct st_kdl_token_ref a128 = mkref(ST_TOK_TYPE, "i128");
+    struct st_kdl_token_ref u128 = mkref(ST_TOK_TYPE, "u128");
+    struct st_kdl_value v;
+    struct st_error *err;
+
+    err = st_kdl_value_from_token_annotated(&r, &a128, &v);
+    munit_assert_not_null(err);
+    munit_assert_int(st_error_category_of(err), ==, ST_ERR_KDL_PARSE);
+    munit_assert_true(strstr(st_error_message(err), "unsupported") != NULL);
+    st_error_free(err);
+
+    err = st_kdl_value_from_token_annotated(&r, &u128, &v);
+    munit_assert_not_null(err);
+    munit_assert_true(strstr(st_error_message(err), "unsupported") != NULL);
+    st_error_free(err);
+    return MUNIT_OK;
+}
+
+/* ---- end-to-end annotation integration (through the parser) ------------ */
+
+static MunitResult
+test_parser_annotation_arg(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc = st_kdl_parse("node (u8)42", "t.kdl", &err);
+    struct st_kdl_node *n;
+    struct st_kdl_value v;
+
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+
+    n = doc->nodes;
+    munit_assert_not_null(n);
+    munit_assert_not_null(n->args);
+    munit_assert_int(n->args->value.kind, ==, ST_TOK_NUMBER);
+    munit_assert_not_null(n->args->annotation);
+    munit_assert_int(n->args->annotation->kind, ==, ST_TOK_TYPE);
+    munit_assert_memory_equal(2, n->args->annotation->text, "u8");
+
+    err = st_kdl_value_from_token_annotated(&n->args->value,
+                                            n->args->annotation, &v);
+    munit_assert_null(err);
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_UINT);
+    munit_assert_ullong(v.as.u, ==, 42);
+    munit_assert_string_equal(v.annotation, "u8");
+    st_kdl_value_free(&v);
+
+    st_kdl_document_free(doc);
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_parser_annotation_prop(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+    struct st_error *err = NULL;
+    struct st_kdl_document *doc = st_kdl_parse("node key=(u8)42", "t.kdl", &err);
+    struct st_kdl_node *n;
+    struct st_kdl_value v;
+
+    munit_assert_not_null(doc);
+    munit_assert_null(err);
+
+    n = doc->nodes;
+    munit_assert_not_null(n);
+    munit_assert_not_null(n->props);
+    munit_assert_int(n->props->value.kind, ==, ST_TOK_NUMBER);
+    munit_assert_not_null(n->props->annotation);
+    munit_assert_int(n->props->annotation->kind, ==, ST_TOK_TYPE);
+    munit_assert_memory_equal(2, n->props->annotation->text, "u8");
+
+    err = st_kdl_value_from_token_annotated(&n->props->value,
+                                            n->props->annotation, &v);
+    munit_assert_null(err);
+    munit_assert_int(v.kind, ==, ST_KDL_VAL_UINT);
+    munit_assert_ullong(v.as.u, ==, 42);
+    st_kdl_value_free(&v);
+
+    st_kdl_document_free(doc);
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_free_null(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    st_kdl_value_free(NULL);
+    return MUNIT_OK;
+}
+
+static MunitResult
+test_kind_name(const MunitParameter params[], void *data)
+{
+    (void)params;
+    (void)data;
+
+    munit_assert_string_equal(st_kdl_value_kind_name(ST_KDL_VAL_STRING),
+                              "string");
+    munit_assert_string_equal(st_kdl_value_kind_name(ST_KDL_VAL_NULL), "null");
+    munit_assert_string_equal(st_kdl_value_kind_name((enum st_kdl_value_kind)99),
+                              "?");
+    return MUNIT_OK;
+}
+
+static MunitTest tests[] = {
+    { "/value/radix-ints", test_radix_ints, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/decimal-and-sign", test_decimal_and_sign, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/floats", test_floats, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/exponents", test_exponents, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { "/value/keyword-numbers", test_keyword_numbers, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/bool-null", test_bool_null, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { "/value/ident-and-quoted", test_ident_and_quoted, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/escapes", test_escapes, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { "/value/raw-string", test_raw_string, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { "/value/multiline-dedent", test_multiline_dedent, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/multiline-escaped-newline", test_multiline_escaped_newline, NULL,
+      NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/unknown-escape", test_unknown_escape, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/unterminated-escape", test_unterminated_escape, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/unicode-out-of-range", test_unicode_out_of_range, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/bad-radix", test_bad_radix, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { "/value/integer-overflow", test_integer_overflow, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/annotation-u8", test_annotation_u8, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/annotation-unsigned-negative", test_annotation_unsigned_rejects_negative,
+      NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/annotation-unsupported-width", test_annotation_unsupported_width,
+      NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/parser-annotation-arg", test_parser_annotation_arg, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/parser-annotation-prop", test_parser_annotation_prop, NULL, NULL,
+      MUNIT_TEST_OPTION_NONE, NULL },
+    { "/value/free-null", test_free_null, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { "/value/kind-name", test_kind_name, NULL, NULL, MUNIT_TEST_OPTION_NONE,
+      NULL },
+    { NULL, NULL, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL },
+};
+
+static const MunitSuite suite = {
+    "/value", tests, NULL, 1, MUNIT_SUITE_OPTION_NONE,
+};
+
+int
+main(int argc, char *argv[MUNIT_ARRAY_PARAM(argc + 1)])
+{
+    return munit_suite_main(&suite, NULL, argc, argv);
+}

thirdparty/README.md

@@ -0,0 +1,15 @@
+# thirdparty/
+
+Vendored third-party libraries, per AGENTS.md §2. Every library is copied
+in-tree (no git submodules) and carries three things:
+
+- a verbatim upstream `LICENSE` file (never stubbed),
+- an `UPSTREAM` file recording the source URL and pinned commit SHA,
+- a row in the provenance table below.
+
+## Provenance table
+
+| name | version | license | SHA |
+| --- | --- | --- | --- |
+| lua | 5.4.9 | MIT | 312b9efaa1061c2c4cad08554dbc1351c3270eef (git tag `v5.4.9` on the lua/lua mirror; tarball sha256 `2335b6c582a52654f94612bf10d2f4672805d05329aa6568b1d8cd9e5c6fb8e6`) |
+| munit | 0.2.0 | MIT | ad67a3a2ca6b0e106c9c8d515772359eadcefad6 (git tag `v0.2.0`) |

thirdparty/lua/LICENSE

@@ -0,0 +1,27 @@
+Lua is licensed under the terms of the MIT license reproduced below.
+This means that Lua is free software and can be used for both academic
+and commercial purposes at absolutely no cost.
+
+There is also a simplified FAQ available for the Lua mailing list.
+
+---------------------------------------------------------------------------
+Copyright (C) 1994-2026 Lua.org, PUC-Rio.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+---------------------------------------------------------------------------

thirdparty/lua/UPSTREAM

@@ -0,0 +1,18 @@
+name: Lua
+version: 5.4.9
+source: https://www.lua.org/ftp/lua-5.4.9.tar.gz
+license: MIT (https://www.lua.org/license.html)
+
+pinned-commit: 312b9efaa1061c2c4cad08554dbc1351c3270eef
+  git tag v5.4.9 on the official lua/lua GitHub mirror
+  (https://github.com/lua/lua/tree/v5.4.9); the lua.org tarball has no git
+  history, so the mirror tag SHA pins the exact source revision.
+
+tarball-sha256: 2335b6c582a52654f94612bf10d2f4672805d05329aa6568b1d8cd9e5c6fb8e6
+  sha256 published on https://www.lua.org/ftp/ for lua-5.4.9.tar.gz
+  (verified at vendoring time; `sha256sum -c` passes).
+
+vendored-files: src/*.c + src/*.h from the official tarball (61 files,
+  including the lua.c/luac.c standalone mains); LICENSE (verbatim MIT text
+  as shipped in doc/readme.html and lua.h). The src/Makefile is not
+  vendored; the library is built by the project's own build.

thirdparty/lua/lapi.h

@@ -0,0 +1,52 @@
+/*
+** $Id: lapi.h $
+** Auxiliary functions from Lua API
+** See Copyright Notice in lua.h
+*/
+
+#ifndef lapi_h
+#define lapi_h
+
+
+#include "llimits.h"
+#include "lstate.h"
+
+
+/* Increments 'L->top.p', checking for stack overflows */
+#define api_incr_top(L)	{L->top.p++; \
+			 api_check(L, L->top.p <= L->ci->top.p, \
+					"stack overflow");}
+
+
+/*
+** If a call returns too many multiple returns, the callee may not have
+** stack space to accommodate all results. In this case, this macro
+** increases its stack space ('L->ci->top.p').
+*/
+#define adjustresults(L,nres) \
+    { if ((nres) <= LUA_MULTRET && L->ci->top.p < L->top.p) \
+	L->ci->top.p = L->top.p; }
+
+
+/* Ensure the stack has at least 'n' elements */
+#define api_checknelems(L,n) \
+	api_check(L, (n) < (L->top.p - L->ci->func.p), \
+			  "not enough elements in the stack")
+
+
+/*
+** To reduce the overhead of returning from C functions, the presence of
+** to-be-closed variables in these functions is coded in the CallInfo's
+** field 'nresults', in a way that functions with no to-be-closed variables
+** with zero, one, or "all" wanted results have no overhead. Functions
+** with other number of wanted results, as well as functions with
+** variables to be closed, have an extra check.
+*/
+
+#define hastocloseCfunc(n)	((n) < LUA_MULTRET)
+
+/* Map [-1, inf) (range of 'nresults') into (-inf, -2] */
+#define codeNresults(n)		(-(n) - 3)
+#define decodeNresults(n)	(-(n) - 3)
+
+#endif

thirdparty/lua/lauxlib.h

@@ -0,0 +1,301 @@
+/*
+** $Id: lauxlib.h $
+** Auxiliary functions for building Lua libraries
+** See Copyright Notice in lua.h
+*/
+
+
+#ifndef lauxlib_h
+#define lauxlib_h
+
+
+#include <stddef.h>
+#include <stdio.h>
+
+#include "luaconf.h"
+#include "lua.h"
+
+
+/* global table */
+#define LUA_GNAME	"_G"
+
+
+typedef struct luaL_Buffer luaL_Buffer;
+
+
+/* extra error code for 'luaL_loadfilex' */
+#define LUA_ERRFILE     (LUA_ERRERR+1)
+
+
+/* key, in the registry, for table of loaded modules */
+#define LUA_LOADED_TABLE	"_LOADED"
+
+
+/* key, in the registry, for table of preloaded loaders */
+#define LUA_PRELOAD_TABLE	"_PRELOAD"
+
+
+typedef struct luaL_Reg {
+  const char *name;
+  lua_CFunction func;
+} luaL_Reg;
+
+
+#define LUAL_NUMSIZES	(sizeof(lua_Integer)*16 + sizeof(lua_Number))
+
+LUALIB_API void (luaL_checkversion_) (lua_State *L, lua_Number ver, size_t sz);
+#define luaL_checkversion(L)  \
+	  luaL_checkversion_(L, LUA_VERSION_NUM, LUAL_NUMSIZES)
+
+LUALIB_API int (luaL_getmetafield) (lua_State *L, int obj, const char *e);
+LUALIB_API int (luaL_callmeta) (lua_State *L, int obj, const char *e);
+LUALIB_API const char *(luaL_tolstring) (lua_State *L, int idx, size_t *len);
+LUALIB_API int (luaL_argerror) (lua_State *L, int arg, const char *extramsg);
+LUALIB_API int (luaL_typeerror) (lua_State *L, int arg, const char *tname);
+LUALIB_API const char *(luaL_checklstring) (lua_State *L, int arg,
+                                                          size_t *l);
+LUALIB_API const char *(luaL_optlstring) (lua_State *L, int arg,
+                                          const char *def, size_t *l);
+LUALIB_API lua_Number (luaL_checknumber) (lua_State *L, int arg);
+LUALIB_API lua_Number (luaL_optnumber) (lua_State *L, int arg, lua_Number def);
+
+LUALIB_API lua_Integer (luaL_checkinteger) (lua_State *L, int arg);
+LUALIB_API lua_Integer (luaL_optinteger) (lua_State *L, int arg,
+                                          lua_Integer def);
+
+LUALIB_API void (luaL_checkstack) (lua_State *L, int sz, const char *msg);
+LUALIB_API void (luaL_checktype) (lua_State *L, int arg, int t);
+LUALIB_API void (luaL_checkany) (lua_State *L, int arg);
+
+LUALIB_API int   (luaL_newmetatable) (lua_State *L, const char *tname);
+LUALIB_API void  (luaL_setmetatable) (lua_State *L, const char *tname);
+LUALIB_API void *(luaL_testudata) (lua_State *L, int ud, const char *tname);
+LUALIB_API void *(luaL_checkudata) (lua_State *L, int ud, const char *tname);
+
+LUALIB_API void (luaL_where) (lua_State *L, int lvl);
+LUALIB_API int (luaL_error) (lua_State *L, const char *fmt, ...);
+
+LUALIB_API int (luaL_checkoption) (lua_State *L, int arg, const char *def,
+                                   const char *const lst[]);
+
+LUALIB_API int (luaL_fileresult) (lua_State *L, int stat, const char *fname);
+LUALIB_API int (luaL_execresult) (lua_State *L, int stat);
+
+
+/* predefined references */
+#define LUA_NOREF       (-2)
+#define LUA_REFNIL      (-1)
+
+LUALIB_API int (luaL_ref) (lua_State *L, int t);
+LUALIB_API void (luaL_unref) (lua_State *L, int t, int ref);
+
+LUALIB_API int (luaL_loadfilex) (lua_State *L, const char *filename,
+                                               const char *mode);
+
+#define luaL_loadfile(L,f)	luaL_loadfilex(L,f,NULL)
+
+LUALIB_API int (luaL_loadbufferx) (lua_State *L, const char *buff, size_t sz,
+                                   const char *name, const char *mode);
+LUALIB_API int (luaL_loadstring) (lua_State *L, const char *s);
+
+LUALIB_API lua_State *(luaL_newstate) (void);
+
+LUALIB_API lua_Integer (luaL_len) (lua_State *L, int idx);
+
+LUALIB_API void (luaL_addgsub) (luaL_Buffer *b, const char *s,
+                                     const char *p, const char *r);
+LUALIB_API const char *(luaL_gsub) (lua_State *L, const char *s,
+                                    const char *p, const char *r);
+
+LUALIB_API void (luaL_setfuncs) (lua_State *L, const luaL_Reg *l, int nup);
+
+LUALIB_API int (luaL_getsubtable) (lua_State *L, int idx, const char *fname);
+
+LUALIB_API void (luaL_traceback) (lua_State *L, lua_State *L1,
+                                  const char *msg, int level);
+
+LUALIB_API void (luaL_requiref) (lua_State *L, const char *modname,
+                                 lua_CFunction openf, int glb);
+
+/*
+** ===============================================================
+** some useful macros
+** ===============================================================
+*/
+
+
+#define luaL_newlibtable(L,l)	\
+  lua_createtable(L, 0, sizeof(l)/sizeof((l)[0]) - 1)
+
+#define luaL_newlib(L,l)  \
+  (luaL_checkversion(L), luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
+
+#define luaL_argcheck(L, cond,arg,extramsg)	\
+	((void)(luai_likely(cond) || luaL_argerror(L, (arg), (extramsg))))
+
+#define luaL_argexpected(L,cond,arg,tname)	\
+	((void)(luai_likely(cond) || luaL_typeerror(L, (arg), (tname))))
+
+#define luaL_checkstring(L,n)	(luaL_checklstring(L, (n), NULL))
+#define luaL_optstring(L,n,d)	(luaL_optlstring(L, (n), (d), NULL))
+
+#define luaL_typename(L,i)	lua_typename(L, lua_type(L,(i)))
+
+#define luaL_dofile(L, fn) \
+	(luaL_loadfile(L, fn) || lua_pcall(L, 0, LUA_MULTRET, 0))
+
+#define luaL_dostring(L, s) \
+	(luaL_loadstring(L, s) || lua_pcall(L, 0, LUA_MULTRET, 0))
+
+#define luaL_getmetatable(L,n)	(lua_getfield(L, LUA_REGISTRYINDEX, (n)))
+
+#define luaL_opt(L,f,n,d)	(lua_isnoneornil(L,(n)) ? (d) : f(L,(n)))
+
+#define luaL_loadbuffer(L,s,sz,n)	luaL_loadbufferx(L,s,sz,n,NULL)
+
+
+/*
+** Perform arithmetic operations on lua_Integer values with wrap-around
+** semantics, as the Lua core does.
+*/
+#define luaL_intop(op,v1,v2)  \
+	((lua_Integer)((lua_Unsigned)(v1) op (lua_Unsigned)(v2)))
+
+
+/* push the value used to represent failure/error */
+#define luaL_pushfail(L)	lua_pushnil(L)
+
+
+/*
+** Internal assertions for in-house debugging
+*/
+#if !defined(lua_assert)
+
+#if defined LUAI_ASSERT
+  #include <assert.h>
+  #define lua_assert(c)		assert(c)
+#else
+  #define lua_assert(c)		((void)0)
+#endif
+
+#endif
+
+
+
+/*
+** {======================================================
+** Generic Buffer manipulation
+** =======================================================
+*/
+
+struct luaL_Buffer {
+  char *b;  /* buffer address */
+  size_t size;  /* buffer size */
+  size_t n;  /* number of characters in buffer */
+  lua_State *L;
+  union {
+    LUAI_MAXALIGN;  /* ensure maximum alignment for buffer */
+    char b[LUAL_BUFFERSIZE];  /* initial buffer */
+  } init;
+};
+
+
+#define luaL_bufflen(bf)	((bf)->n)
+#define luaL_buffaddr(bf)	((bf)->b)
+
+
+#define luaL_addchar(B,c) \
+  ((void)((B)->n < (B)->size || luaL_prepbuffsize((B), 1)), \
+   ((B)->b[(B)->n++] = (c)))
+
+#define luaL_addsize(B,s)	((B)->n += (s))
+
+#define luaL_buffsub(B,s)	((B)->n -= (s))
+
+LUALIB_API void (luaL_buffinit) (lua_State *L, luaL_Buffer *B);
+LUALIB_API char *(luaL_prepbuffsize) (luaL_Buffer *B, size_t sz);
+LUALIB_API void (luaL_addlstring) (luaL_Buffer *B, const char *s, size_t l);
+LUALIB_API void (luaL_addstring) (luaL_Buffer *B, const char *s);
+LUALIB_API void (luaL_addvalue) (luaL_Buffer *B);
+LUALIB_API void (luaL_pushresult) (luaL_Buffer *B);
+LUALIB_API void (luaL_pushresultsize) (luaL_Buffer *B, size_t sz);
+LUALIB_API char *(luaL_buffinitsize) (lua_State *L, luaL_Buffer *B, size_t sz);
+
+#define luaL_prepbuffer(B)	luaL_prepbuffsize(B, LUAL_BUFFERSIZE)
+
+/* }====================================================== */
+
+
+
+/*
+** {======================================================
+** File handles for IO library
+** =======================================================
+*/
+
+/*
+** A file handle is a userdata with metatable 'LUA_FILEHANDLE' and
+** initial structure 'luaL_Stream' (it may contain other fields
+** after that initial structure).
+*/
+
+#define LUA_FILEHANDLE          "FILE*"
+
+
+typedef struct luaL_Stream {
+  FILE *f;  /* stream (NULL for incompletely created streams) */
+  lua_CFunction closef;  /* to close stream (NULL for closed streams) */
+} luaL_Stream;
+
+/* }====================================================== */
+
+/*
+** {==================================================================
+** "Abstraction Layer" for basic report of messages and errors
+** ===================================================================
+*/
+
+/* print a string */
+#if !defined(lua_writestring)
+#define lua_writestring(s,l)   fwrite((s), sizeof(char), (l), stdout)
+#endif
+
+/* print a newline and flush the output */
+#if !defined(lua_writeline)
+#define lua_writeline()        (lua_writestring("\n", 1), fflush(stdout))
+#endif
+
+/* print an error message */
+#if !defined(lua_writestringerror)
+#define lua_writestringerror(s,p) \
+        (fprintf(stderr, (s), (p)), fflush(stderr))
+#endif
+
+/* }================================================================== */
+
+
+/*
+** {============================================================
+** Compatibility with deprecated conversions
+** =============================================================
+*/
+#if defined(LUA_COMPAT_APIINTCASTS)
+
+#define luaL_checkunsigned(L,a)	((lua_Unsigned)luaL_checkinteger(L,a))
+#define luaL_optunsigned(L,a,d)	\
+	((lua_Unsigned)luaL_optinteger(L,a,(lua_Integer)(d)))
+
+#define luaL_checkint(L,n)	((int)luaL_checkinteger(L, (n)))
+#define luaL_optint(L,n,d)	((int)luaL_optinteger(L, (n), (d)))
+
+#define luaL_checklong(L,n)	((long)luaL_checkinteger(L, (n)))
+#define luaL_optlong(L,n,d)	((long)luaL_optinteger(L, (n), (d)))
+
+#endif
+/* }============================================================ */
+
+
+
+#endif
+
+

thirdparty/lua/lbaselib.c

@@ -0,0 +1,549 @@
+/*
+** $Id: lbaselib.c $
+** Basic library
+** See Copyright Notice in lua.h
+*/
+
+#define lbaselib_c
+#define LUA_LIB
+
+#include "lprefix.h"
+
+
+#include <ctype.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "lua.h"
+
+#include "lauxlib.h"
+#include "lualib.h"
+
+
+static int luaB_print (lua_State *L) {
+  int n = lua_gettop(L);  /* number of arguments */
+  int i;
+  for (i = 1; i <= n; i++) {  /* for each argument */
+    size_t l;
+    const char *s = luaL_tolstring(L, i, &l);  /* convert it to string */
+    if (i > 1)  /* not the first element? */
+      lua_writestring("\t", 1);  /* add a tab before it */
+    lua_writestring(s, l);  /* print it */
+    lua_pop(L, 1);  /* pop result */
+  }
+  lua_writeline();
+  return 0;
+}
+
+
+/*
+** Creates a warning with all given arguments.
+** Check first for errors; otherwise an error may interrupt
+** the composition of a warning, leaving it unfinished.
+*/
+static int luaB_warn (lua_State *L) {
+  int n = lua_gettop(L);  /* number of arguments */
+  int i;
+  luaL_checkstring(L, 1);  /* at least one argument */
+  for (i = 2; i <= n; i++)
+    luaL_checkstring(L, i);  /* make sure all arguments are strings */
+  for (i = 1; i < n; i++)  /* compose warning */
+    lua_warning(L, lua_tostring(L, i), 1);
+  lua_warning(L, lua_tostring(L, n), 0);  /* close warning */
+  return 0;
+}
+
+
+#define SPACECHARS	" \f\n\r\t\v"
+
+static const char *b_str2int (const char *s, int base, lua_Integer *pn) {
+  lua_Unsigned n = 0;
+  int neg = 0;
+  s += strspn(s, SPACECHARS);  /* skip initial spaces */
+  if (*s == '-') { s++; neg = 1; }  /* handle sign */
+  else if (*s == '+') s++;
+  if (!isalnum((unsigned char)*s))  /* no digit? */
+    return NULL;
+  do {
+    int digit = (isdigit((unsigned char)*s)) ? *s - '0'
+                   : (toupper((unsigned char)*s) - 'A') + 10;
+    if (digit >= base) return NULL;  /* invalid numeral */
+    n = n * base + digit;
+    s++;
+  } while (isalnum((unsigned char)*s));
+  s += strspn(s, SPACECHARS);  /* skip trailing spaces */
+  *pn = (lua_Integer)((neg) ? (0u - n) : n);
+  return s;
+}
+
+
+static int luaB_tonumber (lua_State *L) {
+  if (lua_isnoneornil(L, 2)) {  /* standard conversion? */
+    if (lua_type(L, 1) == LUA_TNUMBER) {  /* already a number? */
+      lua_settop(L, 1);  /* yes; return it */
+      return 1;
+    }
+    else {
+      size_t l;
+      const char *s = lua_tolstring(L, 1, &l);
+      if (s != NULL && lua_stringtonumber(L, s) == l + 1)
+        return 1;  /* successful conversion to number */
+      /* else not a number */
+      luaL_checkany(L, 1);  /* (but there must be some parameter) */
+    }
+  }
+  else {
+    size_t l;
+    const char *s;
+    lua_Integer n = 0;  /* to avoid warnings */
+    lua_Integer base = luaL_checkinteger(L, 2);
+    luaL_checktype(L, 1, LUA_TSTRING);  /* no numbers as strings */
+    s = lua_tolstring(L, 1, &l);
+    luaL_argcheck(L, 2 <= base && base <= 36, 2, "base out of range");
+    if (b_str2int(s, (int)base, &n) == s + l) {
+      lua_pushinteger(L, n);
+      return 1;
+    }  /* else not a number */
+  }  /* else not a number */
+  luaL_pushfail(L);  /* not a number */
+  return 1;
+}
+
+
+static int luaB_error (lua_State *L) {
+  int level = (int)luaL_optinteger(L, 2, 1);
+  lua_settop(L, 1);
+  if (lua_type(L, 1) == LUA_TSTRING && level > 0) {
+    luaL_where(L, level);   /* add extra information */
+    lua_pushvalue(L, 1);
+    lua_concat(L, 2);
+  }
+  return lua_error(L);
+}
+
+
+static int luaB_getmetatable (lua_State *L) {
+  luaL_checkany(L, 1);
+  if (!lua_getmetatable(L, 1)) {
+    lua_pushnil(L);
+    return 1;  /* no metatable */
+  }
+  luaL_getmetafield(L, 1, "__metatable");
+  return 1;  /* returns either __metatable field (if present) or metatable */
+}
+
+
+static int luaB_setmetatable (lua_State *L) {
+  int t = lua_type(L, 2);
+  luaL_checktype(L, 1, LUA_TTABLE);
+  luaL_argexpected(L, t == LUA_TNIL || t == LUA_TTABLE, 2, "nil or table");
+  if (l_unlikely(luaL_getmetafield(L, 1, "__metatable") != LUA_TNIL))
+    return luaL_error(L, "cannot change a protected metatable");
+  lua_settop(L, 2);
+  lua_setmetatable(L, 1);
+  return 1;
+}
+
+
+static int luaB_rawequal (lua_State *L) {
+  luaL_checkany(L, 1);
+  luaL_checkany(L, 2);
+  lua_pushboolean(L, lua_rawequal(L, 1, 2));
+  return 1;
+}
+
+
+static int luaB_rawlen (lua_State *L) {
+  int t = lua_type(L, 1);
+  luaL_argexpected(L, t == LUA_TTABLE || t == LUA_TSTRING, 1,
+                      "table or string");
+  lua_pushinteger(L, lua_rawlen(L, 1));
+  return 1;
+}
+
+
+static int luaB_rawget (lua_State *L) {
+  luaL_checktype(L, 1, LUA_TTABLE);
+  luaL_checkany(L, 2);
+  lua_settop(L, 2);
+  lua_rawget(L, 1);
+  return 1;
+}
+
+static int luaB_rawset (lua_State *L) {
+  luaL_checktype(L, 1, LUA_TTABLE);
+  luaL_checkany(L, 2);
+  luaL_checkany(L, 3);
+  lua_settop(L, 3);
+  lua_rawset(L, 1);
+  return 1;
+}
+
+
+static int pushmode (lua_State *L, int oldmode) {
+  if (oldmode == -1)
+    luaL_pushfail(L);  /* invalid call to 'lua_gc' */
+  else
+    lua_pushstring(L, (oldmode == LUA_GCINC) ? "incremental"
+                                             : "generational");
+  return 1;
+}
+
+
+/*
+** check whether call to 'lua_gc' was valid (not inside a finalizer)
+*/
+#define checkvalres(res) { if (res == -1) break; }
+
+static int luaB_collectgarbage (lua_State *L) {
+  static const char *const opts[] = {"stop", "restart", "collect",
+    "count", "step", "setpause", "setstepmul",
+    "isrunning", "generational", "incremental", NULL};
+  static const int optsnum[] = {LUA_GCSTOP, LUA_GCRESTART, LUA_GCCOLLECT,
+    LUA_GCCOUNT, LUA_GCSTEP, LUA_GCSETPAUSE, LUA_GCSETSTEPMUL,
+    LUA_GCISRUNNING, LUA_GCGEN, LUA_GCINC};
+  int o = optsnum[luaL_checkoption(L, 1, "collect", opts)];
+  switch (o) {
+    case LUA_GCCOUNT: {
+      int k = lua_gc(L, o);
+      int b = lua_gc(L, LUA_GCCOUNTB);
+      checkvalres(k);
+      lua_pushnumber(L, (lua_Number)k + ((lua_Number)b/1024));
+      return 1;
+    }
+    case LUA_GCSTEP: {
+      int step = (int)luaL_optinteger(L, 2, 0);
+      int res = lua_gc(L, o, step);
+      checkvalres(res);
+      lua_pushboolean(L, res);
+      return 1;
+    }
+    case LUA_GCSETPAUSE:
+    case LUA_GCSETSTEPMUL: {
+      int p = (int)luaL_optinteger(L, 2, 0);
+      int previous = lua_gc(L, o, p);
+      checkvalres(previous);
+      lua_pushinteger(L, previous);
+      return 1;
+    }
+    case LUA_GCISRUNNING: {
+      int res = lua_gc(L, o);
+      checkvalres(res);
+      lua_pushboolean(L, res);
+      return 1;
+    }
+    case LUA_GCGEN: {
+      int minormul = (int)luaL_optinteger(L, 2, 0);
+      int majormul = (int)luaL_optinteger(L, 3, 0);
+      return pushmode(L, lua_gc(L, o, minormul, majormul));
+    }
+    case LUA_GCINC: {
+      int pause = (int)luaL_optinteger(L, 2, 0);
+      int stepmul = (int)luaL_optinteger(L, 3, 0);
+      int stepsize = (int)luaL_optinteger(L, 4, 0);
+      return pushmode(L, lua_gc(L, o, pause, stepmul, stepsize));
+    }
+    default: {
+      int res = lua_gc(L, o);
+      checkvalres(res);
+      lua_pushinteger(L, res);
+      return 1;
+    }
+  }
+  luaL_pushfail(L);  /* invalid call (inside a finalizer) */
+  return 1;
+}
+
+
+static int luaB_type (lua_State *L) {
+  int t = lua_type(L, 1);
+  luaL_argcheck(L, t != LUA_TNONE, 1, "value expected");
+  lua_pushstring(L, lua_typename(L, t));
+  return 1;
+}
+
+
+static int luaB_next (lua_State *L) {
+  luaL_checktype(L, 1, LUA_TTABLE);
+  lua_settop(L, 2);  /* create a 2nd argument if there isn't one */
+  if (lua_next(L, 1))
+    return 2;
+  else {
+    lua_pushnil(L);
+    return 1;
+  }
+}
+
+
+static int pairscont (lua_State *L, int status, lua_KContext k) {
+  (void)L; (void)status; (void)k;  /* unused */
+  return 3;
+}
+
+static int luaB_pairs (lua_State *L) {
+  luaL_checkany(L, 1);
+  if (luaL_getmetafield(L, 1, "__pairs") == LUA_TNIL) {  /* no metamethod? */
+    lua_pushcfunction(L, luaB_next);  /* will return generator, */
+    lua_pushvalue(L, 1);  /* state, */
+    lua_pushnil(L);  /* and initial value */
+  }
+  else {
+    lua_pushvalue(L, 1);  /* argument 'self' to metamethod */
+    lua_callk(L, 1, 3, 0, pairscont);  /* get 3 values from metamethod */
+  }
+  return 3;
+}
+
+
+/*
+** Traversal function for 'ipairs'
+*/
+static int ipairsaux (lua_State *L) {
+  lua_Integer i = luaL_checkinteger(L, 2);
+  i = luaL_intop(+, i, 1);
+  lua_pushinteger(L, i);
+  return (lua_geti(L, 1, i) == LUA_TNIL) ? 1 : 2;
+}
+
+
+/*
+** 'ipairs' function. Returns 'ipairsaux', given "table", 0.
+** (The given "table" may not be a table.)
+*/
+static int luaB_ipairs (lua_State *L) {
+  luaL_checkany(L, 1);
+  lua_pushcfunction(L, ipairsaux);  /* iteration function */
+  lua_pushvalue(L, 1);  /* state */
+  lua_pushinteger(L, 0);  /* initial value */
+  return 3;
+}
+
+
+static int load_aux (lua_State *L, int status, int envidx) {
+  if (l_likely(status == LUA_OK)) {
+    if (envidx != 0) {  /* 'env' parameter? */
+      lua_pushvalue(L, envidx);  /* environment for loaded function */
+      if (!lua_setupvalue(L, -2, 1))  /* set it as 1st upvalue */
+        lua_pop(L, 1);  /* remove 'env' if not used by previous call */
+    }
+    return 1;
+  }
+  else {  /* error (message is on top of the stack) */
+    luaL_pushfail(L);
+    lua_insert(L, -2);  /* put before error message */
+    return 2;  /* return fail plus error message */
+  }
+}
+
+
+static int luaB_loadfile (lua_State *L) {
+  const char *fname = luaL_optstring(L, 1, NULL);
+  const char *mode = luaL_optstring(L, 2, NULL);
+  int env = (!lua_isnone(L, 3) ? 3 : 0);  /* 'env' index or 0 if no 'env' */
+  int status = luaL_loadfilex(L, fname, mode);
+  return load_aux(L, status, env);
+}
+
+
+/*
+** {======================================================
+** Generic Read function
+** =======================================================
+*/
+
+
+/*
+** reserved slot, above all arguments, to hold a copy of the returned
+** string to avoid it being collected while parsed. 'load' has four
+** optional arguments (chunk, source name, mode, and environment).
+*/
+#define RESERVEDSLOT	5
+
+
+/*
+** Reader for generic 'load' function: 'lua_load' uses the
+** stack for internal stuff, so the reader cannot change the
+** stack top. Instead, it keeps its resulting string in a
+** reserved slot inside the stack.
+*/
+static const char *generic_reader (lua_State *L, void *ud, size_t *size) {
+  (void)(ud);  /* not used */
+  luaL_checkstack(L, 2, "too many nested functions");
+  lua_pushvalue(L, 1);  /* get function */
+  lua_call(L, 0, 1);  /* call it */
+  if (lua_isnil(L, -1)) {
+    lua_pop(L, 1);  /* pop result */
+    *size = 0;
+    return NULL;
+  }
+  else if (l_unlikely(!lua_isstring(L, -1)))
+    luaL_error(L, "reader function must return a string");
+  lua_replace(L, RESERVEDSLOT);  /* save string in reserved slot */
+  return lua_tolstring(L, RESERVEDSLOT, size);
+}
+
+
+static int luaB_load (lua_State *L) {
+  int status;
+  size_t l;
+  const char *s = lua_tolstring(L, 1, &l);
+  const char *mode = luaL_optstring(L, 3, "bt");
+  int env = (!lua_isnone(L, 4) ? 4 : 0);  /* 'env' index or 0 if no 'env' */
+  if (s != NULL) {  /* loading a string? */
+    const char *chunkname = luaL_optstring(L, 2, s);
+    status = luaL_loadbufferx(L, s, l, chunkname, mode);
+  }
+  else {  /* loading from a reader function */
+    const char *chunkname = luaL_optstring(L, 2, "=(load)");
+    luaL_checktype(L, 1, LUA_TFUNCTION);
+    lua_settop(L, RESERVEDSLOT);  /* create reserved slot */
+    status = lua_load(L, generic_reader, NULL, chunkname, mode);
+  }
+  return load_aux(L, status, env);
+}
+
+/* }====================================================== */
+
+
+static int dofilecont (lua_State *L, int d1, lua_KContext d2) {
+  (void)d1;  (void)d2;  /* only to match 'lua_Kfunction' prototype */
+  return lua_gettop(L) - 1;
+}
+
+
+static int luaB_dofile (lua_State *L) {
+  const char *fname = luaL_optstring(L, 1, NULL);
+  lua_settop(L, 1);
+  if (l_unlikely(luaL_loadfile(L, fname) != LUA_OK))
+    return lua_error(L);
+  lua_callk(L, 0, LUA_MULTRET, 0, dofilecont);
+  return dofilecont(L, 0, 0);
+}
+
+
+static int luaB_assert (lua_State *L) {
+  if (l_likely(lua_toboolean(L, 1)))  /* condition is true? */
+    return lua_gettop(L);  /* return all arguments */
+  else {  /* error */
+    luaL_checkany(L, 1);  /* there must be a condition */
+    lua_remove(L, 1);  /* remove it */
+    lua_pushliteral(L, "assertion failed!");  /* default message */
+    lua_settop(L, 1);  /* leave only message (default if no other one) */
+    return luaB_error(L);  /* call 'error' */
+  }
+}
+
+
+static int luaB_select (lua_State *L) {
+  int n = lua_gettop(L);
+  if (lua_type(L, 1) == LUA_TSTRING && *lua_tostring(L, 1) == '#') {
+    lua_pushinteger(L, n-1);
+    return 1;
+  }
+  else {
+    lua_Integer i = luaL_checkinteger(L, 1);
+    if (i < 0) i = n + i;
+    else if (i > n) i = n;
+    luaL_argcheck(L, 1 <= i, 1, "index out of range");
+    return n - (int)i;
+  }
+}
+
+
+/*
+** Continuation function for 'pcall' and 'xpcall'. Both functions
+** already pushed a 'true' before doing the call, so in case of success
+** 'finishpcall' only has to return everything in the stack minus
+** 'extra' values (where 'extra' is exactly the number of items to be
+** ignored).
+*/
+static int finishpcall (lua_State *L, int status, lua_KContext extra) {
+  if (l_unlikely(status != LUA_OK && status != LUA_YIELD)) {  /* error? */
+    lua_pushboolean(L, 0);  /* first result (false) */
+    lua_pushvalue(L, -2);  /* error message */
+    return 2;  /* return false, msg */
+  }
+  else
+    return lua_gettop(L) - (int)extra;  /* return all results */
+}
+
+
+static int luaB_pcall (lua_State *L) {
+  int status;
+  luaL_checkany(L, 1);
+  lua_pushboolean(L, 1);  /* first result if no errors */
+  lua_insert(L, 1);  /* put it in place */
+  status = lua_pcallk(L, lua_gettop(L) - 2, LUA_MULTRET, 0, 0, finishpcall);
+  return finishpcall(L, status, 0);
+}
+
+
+/*
+** Do a protected call with error handling. After 'lua_rotate', the
+** stack will have <f, err, true, f, [args...]>; so, the function passes
+** 2 to 'finishpcall' to skip the 2 first values when returning results.
+*/
+static int luaB_xpcall (lua_State *L) {
+  int status;
+  int n = lua_gettop(L);
+  luaL_checktype(L, 2, LUA_TFUNCTION);  /* check error function */
+  lua_pushboolean(L, 1);  /* first result */
+  lua_pushvalue(L, 1);  /* function */
+  lua_rotate(L, 3, 2);  /* move them below function's arguments */
+  status = lua_pcallk(L, n - 2, LUA_MULTRET, 2, 2, finishpcall);
+  return finishpcall(L, status, 2);
+}
+
+
+static int luaB_tostring (lua_State *L) {
+  luaL_checkany(L, 1);
+  luaL_tolstring(L, 1, NULL);
+  return 1;
+}
+
+
+static const luaL_Reg base_funcs[] = {
+  {"assert", luaB_assert},
+  {"collectgarbage", luaB_collectgarbage},
+  {"dofile", luaB_dofile},
+  {"error", luaB_error},
+  {"getmetatable", luaB_getmetatable},
+  {"ipairs", luaB_ipairs},
+  {"loadfile", luaB_loadfile},
+  {"load", luaB_load},
+  {"next", luaB_next},
+  {"pairs", luaB_pairs},
+  {"pcall", luaB_pcall},
+  {"print", luaB_print},
+  {"warn", luaB_warn},
+  {"rawequal", luaB_rawequal},
+  {"rawlen", luaB_rawlen},
+  {"rawget", luaB_rawget},
+  {"rawset", luaB_rawset},
+  {"select", luaB_select},
+  {"setmetatable", luaB_setmetatable},
+  {"tonumber", luaB_tonumber},
+  {"tostring", luaB_tostring},
+  {"type", luaB_type},
+  {"xpcall", luaB_xpcall},
+  /* placeholders */
+  {LUA_GNAME, NULL},
+  {"_VERSION", NULL},
+  {NULL, NULL}
+};
+
+
+LUAMOD_API int luaopen_base (lua_State *L) {
+  /* open lib into global table */
+  lua_pushglobaltable(L);
+  luaL_setfuncs(L, base_funcs, 0);
+  /* set global _G */
+  lua_pushvalue(L, -1);
+  lua_setfield(L, -2, LUA_GNAME);
+  /* set global _VERSION */
+  lua_pushliteral(L, LUA_VERSION);
+  lua_setfield(L, -2, "_VERSION");
+  return 1;
+}
+

thirdparty/lua/lcode.h

@@ -0,0 +1,101 @@
+/*
+** $Id: lcode.h $
+** Code generator for Lua
+** See Copyright Notice in lua.h
+*/
+
+#ifndef lcode_h
+#define lcode_h
+
+#include "llex.h"
+#include "lobject.h"
+#include "lopcodes.h"
+#include "lparser.h"
+
+
+/*
+** Marks the end of a patch list. It is an invalid value both as an absolute
+** address, and as a list link (would link an element to itself).
+*/
+#define NO_JUMP (-1)
+
+
+/*
+** grep "ORDER OPR" if you change these enums  (ORDER OP)
+*/
+typedef enum BinOpr {
+  /* arithmetic operators */
+  OPR_ADD, OPR_SUB, OPR_MUL, OPR_MOD, OPR_POW,
+  OPR_DIV, OPR_IDIV,
+  /* bitwise operators */
+  OPR_BAND, OPR_BOR, OPR_BXOR,
+  OPR_SHL, OPR_SHR,
+  /* string operator */
+  OPR_CONCAT,
+  /* comparison operators */
+  OPR_EQ, OPR_LT, OPR_LE,
+  OPR_NE, OPR_GT, OPR_GE,
+  /* logical operators */
+  OPR_AND, OPR_OR,
+  OPR_NOBINOPR
+} BinOpr;
+
+
+/* true if operation is foldable (that is, it is arithmetic or bitwise) */
+#define foldbinop(op)	((op) <= OPR_SHR)
+
+
+#define luaK_codeABC(fs,o,a,b,c)	luaK_codeABCk(fs,o,a,b,c,0)
+
+
+typedef enum UnOpr { OPR_MINUS, OPR_BNOT, OPR_NOT, OPR_LEN, OPR_NOUNOPR } UnOpr;
+
+
+/* get (pointer to) instruction of given 'expdesc' */
+#define getinstruction(fs,e)	((fs)->f->code[(e)->u.info])
+
+
+#define luaK_setmultret(fs,e)	luaK_setreturns(fs, e, LUA_MULTRET)
+
+#define luaK_jumpto(fs,t)	luaK_patchlist(fs, luaK_jump(fs), t)
+
+LUAI_FUNC int luaK_code (FuncState *fs, Instruction i);
+LUAI_FUNC int luaK_codeABx (FuncState *fs, OpCode o, int A, unsigned int Bx);
+LUAI_FUNC int luaK_codeABCk (FuncState *fs, OpCode o, int A,
+                                            int B, int C, int k);
+LUAI_FUNC int luaK_exp2const (FuncState *fs, const expdesc *e, TValue *v);
+LUAI_FUNC void luaK_fixline (FuncState *fs, int line);
+LUAI_FUNC void luaK_nil (FuncState *fs, int from, int n);
+LUAI_FUNC void luaK_reserveregs (FuncState *fs, int n);
+LUAI_FUNC void luaK_checkstack (FuncState *fs, int n);
+LUAI_FUNC void luaK_int (FuncState *fs, int reg, lua_Integer n);
+LUAI_FUNC void luaK_dischargevars (FuncState *fs, expdesc *e);
+LUAI_FUNC int luaK_exp2anyreg (FuncState *fs, expdesc *e);
+LUAI_FUNC void luaK_exp2anyregup (FuncState *fs, expdesc *e);
+LUAI_FUNC void luaK_exp2nextreg (FuncState *fs, expdesc *e);
+LUAI_FUNC void luaK_exp2val (FuncState *fs, expdesc *e);
+LUAI_FUNC void luaK_self (FuncState *fs, expdesc *e, expdesc *key);
+LUAI_FUNC void luaK_indexed (FuncState *fs, expdesc *t, expdesc *k);
+LUAI_FUNC void luaK_goiftrue (FuncState *fs, expdesc *e);
+LUAI_FUNC void luaK_goiffalse (FuncState *fs, expdesc *e);
+LUAI_FUNC void luaK_storevar (FuncState *fs, expdesc *var, expdesc *e);
+LUAI_FUNC void luaK_setreturns (FuncState *fs, expdesc *e, int nresults);
+LUAI_FUNC void luaK_setoneret (FuncState *fs, expdesc *e);
+LUAI_FUNC int luaK_jump (FuncState *fs);
+LUAI_FUNC void luaK_ret (FuncState *fs, int first, int nret);
+LUAI_FUNC void luaK_patchlist (FuncState *fs, int list, int target);
+LUAI_FUNC void luaK_patchtohere (FuncState *fs, int list);
+LUAI_FUNC void luaK_concat (FuncState *fs, int *l1, int l2);
+LUAI_FUNC int luaK_getlabel (FuncState *fs);
+LUAI_FUNC void luaK_prefix (FuncState *fs, UnOpr op, expdesc *v, int line);
+LUAI_FUNC void luaK_infix (FuncState *fs, BinOpr op, expdesc *v);
+LUAI_FUNC void luaK_posfix (FuncState *fs, BinOpr op, expdesc *v1,
+                            expdesc *v2, int line);
+LUAI_FUNC void luaK_settablesize (FuncState *fs, int pc,
+                                  int ra, int asize, int hsize);
+LUAI_FUNC void luaK_setlist (FuncState *fs, int base, int nelems, int tostore);
+LUAI_FUNC void luaK_finish (FuncState *fs);
+LUAI_FUNC l_noret luaK_semerror (LexState *ls, const char *msg);
+
+
+#endif

thirdparty/lua/lcorolib.c

@@ -0,0 +1,210 @@
+/*
+** $Id: lcorolib.c $
+** Coroutine Library
+** See Copyright Notice in lua.h
+*/
+
+#define lcorolib_c
+#define LUA_LIB
+
+#include "lprefix.h"
+
+
+#include <stdlib.h>
+
+#include "lua.h"
+
+#include "lauxlib.h"
+#include "lualib.h"
+
+
+static lua_State *getco (lua_State *L) {
+  lua_State *co = lua_tothread(L, 1);
+  luaL_argexpected(L, co, 1, "thread");
+  return co;
+}
+
+
+/*
+** Resumes a coroutine. Returns the number of results for non-error
+** cases or -1 for errors.
+*/
+static int auxresume (lua_State *L, lua_State *co, int narg) {
+  int status, nres;
+  if (l_unlikely(!lua_checkstack(co, narg))) {
+    lua_pushliteral(L, "too many arguments to resume");
+    return -1;  /* error flag */
+  }
+  lua_xmove(L, co, narg);
+  status = lua_resume(co, L, narg, &nres);
+  if (l_likely(status == LUA_OK || status == LUA_YIELD)) {
+    if (l_unlikely(!lua_checkstack(L, nres + 1))) {
+      lua_pop(co, nres);  /* remove results anyway */
+      lua_pushliteral(L, "too many results to resume");
+      return -1;  /* error flag */
+    }
+    lua_xmove(co, L, nres);  /* move yielded values */
+    return nres;
+  }
+  else {
+    lua_xmove(co, L, 1);  /* move error message */
+    return -1;  /* error flag */
+  }
+}
+
+
+static int luaB_coresume (lua_State *L) {
+  lua_State *co = getco(L);
+  int r;
+  r = auxresume(L, co, lua_gettop(L) - 1);
+  if (l_unlikely(r < 0)) {
+    lua_pushboolean(L, 0);
+    lua_insert(L, -2);
+    return 2;  /* return false + error message */
+  }
+  else {
+    lua_pushboolean(L, 1);
+    lua_insert(L, -(r + 1));
+    return r + 1;  /* return true + 'resume' returns */
+  }
+}
+
+
+static int luaB_auxwrap (lua_State *L) {
+  lua_State *co = lua_tothread(L, lua_upvalueindex(1));
+  int r = auxresume(L, co, lua_gettop(L));
+  if (l_unlikely(r < 0)) {  /* error? */
+    int stat = lua_status(co);
+    if (stat != LUA_OK && stat != LUA_YIELD) {  /* error in the coroutine? */
+      stat = lua_closethread(co, L);  /* close its tbc variables */
+      lua_assert(stat != LUA_OK);
+      lua_xmove(co, L, 1);  /* move error message to the caller */
+    }
+    if (stat != LUA_ERRMEM &&  /* not a memory error and ... */
+        lua_type(L, -1) == LUA_TSTRING) {  /* ... error object is a string? */
+      luaL_where(L, 1);  /* add extra info, if available */
+      lua_insert(L, -2);
+      lua_concat(L, 2);
+    }
+    return lua_error(L);  /* propagate error */
+  }
+  return r;
+}
+
+
+static int luaB_cocreate (lua_State *L) {
+  lua_State *NL;
+  luaL_checktype(L, 1, LUA_TFUNCTION);
+  NL = lua_newthread(L);
+  lua_pushvalue(L, 1);  /* move function to top */
+  lua_xmove(L, NL, 1);  /* move function from L to NL */
+  return 1;
+}
+
+
+static int luaB_cowrap (lua_State *L) {
+  luaB_cocreate(L);
+  lua_pushcclosure(L, luaB_auxwrap, 1);
+  return 1;
+}
+
+
+static int luaB_yield (lua_State *L) {
+  return lua_yield(L, lua_gettop(L));
+}
+
+
+#define COS_RUN		0
+#define COS_DEAD	1
+#define COS_YIELD	2
+#define COS_NORM	3
+
+
+static const char *const statname[] =
+  {"running", "dead", "suspended", "normal"};
+
+
+static int auxstatus (lua_State *L, lua_State *co) {
+  if (L == co) return COS_RUN;
+  else {
+    switch (lua_status(co)) {
+      case LUA_YIELD:
+        return COS_YIELD;
+      case LUA_OK: {
+        lua_Debug ar;
+        if (lua_getstack(co, 0, &ar))  /* does it have frames? */
+          return COS_NORM;  /* it is running */
+        else if (lua_gettop(co) == 0)
+            return COS_DEAD;
+        else
+          return COS_YIELD;  /* initial state */
+      }
+      default:  /* some error occurred */
+        return COS_DEAD;
+    }
+  }
+}
+
+
+static int luaB_costatus (lua_State *L) {
+  lua_State *co = getco(L);
+  lua_pushstring(L, statname[auxstatus(L, co)]);
+  return 1;
+}
+
+
+static int luaB_yieldable (lua_State *L) {
+  lua_State *co = lua_isnone(L, 1) ? L : getco(L);
+  lua_pushboolean(L, lua_isyieldable(co));
+  return 1;
+}
+
+
+static int luaB_corunning (lua_State *L) {
+  int ismain = lua_pushthread(L);
+  lua_pushboolean(L, ismain);
+  return 2;
+}
+
+
+static int luaB_close (lua_State *L) {
+  lua_State *co = getco(L);
+  int status = auxstatus(L, co);
+  switch (status) {
+    case COS_DEAD: case COS_YIELD: {
+      status = lua_closethread(co, L);
+      if (status == LUA_OK) {
+        lua_pushboolean(L, 1);
+        return 1;
+      }
+      else {
+        lua_pushboolean(L, 0);
+        lua_xmove(co, L, 1);  /* move error message */
+        return 2;
+      }
+    }
+    default:  /* normal or running coroutine */
+      return luaL_error(L, "cannot close a %s coroutine", statname[status]);
+  }
+}
+
+
+static const luaL_Reg co_funcs[] = {
+  {"create", luaB_cocreate},
+  {"resume", luaB_coresume},
+  {"running", luaB_corunning},
+  {"status", luaB_costatus},
+  {"wrap", luaB_cowrap},
+  {"yield", luaB_yield},
+  {"isyieldable", luaB_yieldable},
+  {"close", luaB_close},
+  {NULL, NULL}
+};
+
+
+
+LUAMOD_API int luaopen_coroutine (lua_State *L) {
+  luaL_newlib(L, co_funcs);
+  return 1;
+}
+

thirdparty/lua/lctype.c

@@ -0,0 +1,64 @@
+/*
+** $Id: lctype.c $
+** 'ctype' functions for Lua
+** See Copyright Notice in lua.h
+*/
+
+#define lctype_c
+#define LUA_CORE
+
+#include "lprefix.h"
+
+
+#include "lctype.h"
+
+#if !LUA_USE_CTYPE	/* { */
+
+#include <limits.h>
+
+
+#if defined (LUA_UCID)		/* accept UniCode IDentifiers? */
+/* consider all non-ascii codepoints to be alphabetic */
+#define NONA		0x01
+#else
+#define NONA		0x00	/* default */
+#endif
+
+
+LUAI_DDEF const lu_byte luai_ctype_[UCHAR_MAX + 2] = {
+  0x00,  /* EOZ */
+  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,	/* 0. */
+  0x00,  0x08,  0x08,  0x08,  0x08,  0x08,  0x00,  0x00,
+  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,	/* 1. */
+  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,
+  0x0c,  0x04,  0x04,  0x04,  0x04,  0x04,  0x04,  0x04,	/* 2. */
+  0x04,  0x04,  0x04,  0x04,  0x04,  0x04,  0x04,  0x04,
+  0x16,  0x16,  0x16,  0x16,  0x16,  0x16,  0x16,  0x16,	/* 3. */
+  0x16,  0x16,  0x04,  0x04,  0x04,  0x04,  0x04,  0x04,
+  0x04,  0x15,  0x15,  0x15,  0x15,  0x15,  0x15,  0x05,	/* 4. */
+  0x05,  0x05,  0x05,  0x05,  0x05,  0x05,  0x05,  0x05,
+  0x05,  0x05,  0x05,  0x05,  0x05,  0x05,  0x05,  0x05,	/* 5. */
+  0x05,  0x05,  0x05,  0x04,  0x04,  0x04,  0x04,  0x05,
+  0x04,  0x15,  0x15,  0x15,  0x15,  0x15,  0x15,  0x05,	/* 6. */
+  0x05,  0x05,  0x05,  0x05,  0x05,  0x05,  0x05,  0x05,
+  0x05,  0x05,  0x05,  0x05,  0x05,  0x05,  0x05,  0x05,	/* 7. */
+  0x05,  0x05,  0x05,  0x04,  0x04,  0x04,  0x04,  0x00,
+  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,	/* 8. */
+  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,
+  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,	/* 9. */
+  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,
+  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,	/* a. */
+  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,
+  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,	/* b. */
+  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,
+  0x00,  0x00,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,	/* c. */
+  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,
+  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,	/* d. */
+  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,
+  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,	/* e. */
+  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,  NONA,
+  NONA,  NONA,  NONA,  NONA,  NONA,  0x00,  0x00,  0x00,	/* f. */
+  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00
+};
+
+#endif			/* } */

thirdparty/lua/lctype.h

@@ -0,0 +1,101 @@
+/*
+** $Id: lctype.h $
+** 'ctype' functions for Lua
+** See Copyright Notice in lua.h
+*/
+
+#ifndef lctype_h
+#define lctype_h
+
+#include "lua.h"
+
+
+/*
+** WARNING: the functions defined here do not necessarily correspond
+** to the similar functions in the standard C ctype.h. They are
+** optimized for the specific needs of Lua.
+*/
+
+#if !defined(LUA_USE_CTYPE)
+
+#if 'A' == 65 && '0' == 48
+/* ASCII case: can use its own tables; faster and fixed */
+#define LUA_USE_CTYPE	0
+#else
+/* must use standard C ctype */
+#define LUA_USE_CTYPE	1
+#endif
+
+#endif
+
+
+#if !LUA_USE_CTYPE	/* { */
+
+#include <limits.h>
+
+#include "llimits.h"
+
+
+#define ALPHABIT	0
+#define DIGITBIT	1
+#define PRINTBIT	2
+#define SPACEBIT	3
+#define XDIGITBIT	4
+
+
+#define MASK(B)		(1 << (B))
+
+
+/*
+** add 1 to char to allow index -1 (EOZ)
+*/
+#define testprop(c,p)	(luai_ctype_[(c)+1] & (p))
+
+/*
+** 'lalpha' (Lua alphabetic) and 'lalnum' (Lua alphanumeric) both include '_'
+*/
+#define lislalpha(c)	testprop(c, MASK(ALPHABIT))
+#define lislalnum(c)	testprop(c, (MASK(ALPHABIT) | MASK(DIGITBIT)))
+#define lisdigit(c)	testprop(c, MASK(DIGITBIT))
+#define lisspace(c)	testprop(c, MASK(SPACEBIT))
+#define lisprint(c)	testprop(c, MASK(PRINTBIT))
+#define lisxdigit(c)	testprop(c, MASK(XDIGITBIT))
+
+
+/*
+** In ASCII, this 'ltolower' is correct for alphabetic characters and
+** for '.'. That is enough for Lua needs. ('check_exp' ensures that
+** the character either is an upper-case letter or is unchanged by
+** the transformation, which holds for lower-case letters and '.'.)
+*/
+#define ltolower(c)  \
+  check_exp(('A' <= (c) && (c) <= 'Z') || (c) == ((c) | ('A' ^ 'a')),  \
+            (c) | ('A' ^ 'a'))
+
+
+/* one entry for each character and for -1 (EOZ) */
+LUAI_DDEC(const lu_byte luai_ctype_[UCHAR_MAX + 2];)
+
+
+#else			/* }{ */
+
+/*
+** use standard C ctypes
+*/
+
+#include <ctype.h>
+
+
+#define lislalpha(c)	(isalpha(c) || (c) == '_')
+#define lislalnum(c)	(isalnum(c) || (c) == '_')
+#define lisdigit(c)	(isdigit(c))
+#define lisspace(c)	(isspace(c))
+#define lisprint(c)	(isprint(c))
+#define lisxdigit(c)	(isxdigit(c))
+
+#define ltolower(c)	(tolower(c))
+
+#endif			/* } */
+
+#endif
+

thirdparty/lua/ldblib.c

@@ -0,0 +1,483 @@
+/*
+** $Id: ldblib.c $
+** Interface from Lua to its debug API
+** See Copyright Notice in lua.h
+*/
+
+#define ldblib_c
+#define LUA_LIB
+
+#include "lprefix.h"
+
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "lua.h"
+
+#include "lauxlib.h"
+#include "lualib.h"
+
+
+/*
+** The hook table at registry[HOOKKEY] maps threads to their current
+** hook function.
+*/
+static const char *const HOOKKEY = "_HOOKKEY";
+
+
+/*
+** If L1 != L, L1 can be in any state, and therefore there are no
+** guarantees about its stack space; any push in L1 must be
+** checked.
+*/
+static void checkstack (lua_State *L, lua_State *L1, int n) {
+  if (l_unlikely(L != L1 && !lua_checkstack(L1, n)))
+    luaL_error(L, "stack overflow");
+}
+
+
+static int db_getregistry (lua_State *L) {
+  lua_pushvalue(L, LUA_REGISTRYINDEX);
+  return 1;
+}
+
+
+static int db_getmetatable (lua_State *L) {
+  luaL_checkany(L, 1);
+  if (!lua_getmetatable(L, 1)) {
+    lua_pushnil(L);  /* no metatable */
+  }
+  return 1;
+}
+
+
+static int db_setmetatable (lua_State *L) {
+  int t = lua_type(L, 2);
+  luaL_argexpected(L, t == LUA_TNIL || t == LUA_TTABLE, 2, "nil or table");
+  lua_settop(L, 2);
+  lua_setmetatable(L, 1);
+  return 1;  /* return 1st argument */
+}
+
+
+static int db_getuservalue (lua_State *L) {
+  int n = (int)luaL_optinteger(L, 2, 1);
+  if (lua_type(L, 1) != LUA_TUSERDATA)
+    luaL_pushfail(L);
+  else if (lua_getiuservalue(L, 1, n) != LUA_TNONE) {
+    lua_pushboolean(L, 1);
+    return 2;
+  }
+  return 1;
+}
+
+
+static int db_setuservalue (lua_State *L) {
+  int n = (int)luaL_optinteger(L, 3, 1);
+  luaL_checktype(L, 1, LUA_TUSERDATA);
+  luaL_checkany(L, 2);
+  lua_settop(L, 2);
+  if (!lua_setiuservalue(L, 1, n))
+    luaL_pushfail(L);
+  return 1;
+}
+
+
+/*
+** Auxiliary function used by several library functions: check for
+** an optional thread as function's first argument and set 'arg' with
+** 1 if this argument is present (so that functions can skip it to
+** access their other arguments)
+*/
+static lua_State *getthread (lua_State *L, int *arg) {
+  if (lua_isthread(L, 1)) {
+    *arg = 1;
+    return lua_tothread(L, 1);
+  }
+  else {
+    *arg = 0;
+    return L;  /* function will operate over current thread */
+  }
+}
+
+
+/*
+** Variations of 'lua_settable', used by 'db_getinfo' to put results
+** from 'lua_getinfo' into result table. Key is always a string;
+** value can be a string, an int, or a boolean.
+*/
+static void settabss (lua_State *L, const char *k, const char *v) {
+  lua_pushstring(L, v);
+  lua_setfield(L, -2, k);
+}
+
+static void settabsi (lua_State *L, const char *k, int v) {
+  lua_pushinteger(L, v);
+  lua_setfield(L, -2, k);
+}
+
+static void settabsb (lua_State *L, const char *k, int v) {
+  lua_pushboolean(L, v);
+  lua_setfield(L, -2, k);
+}
+
+
+/*
+** In function 'db_getinfo', the call to 'lua_getinfo' may push
+** results on the stack; later it creates the result table to put
+** these objects. Function 'treatstackoption' puts the result from
+** 'lua_getinfo' on top of the result table so that it can call
+** 'lua_setfield'.
+*/
+static void treatstackoption (lua_State *L, lua_State *L1, const char *fname) {
+  if (L == L1)
+    lua_rotate(L, -2, 1);  /* exchange object and table */
+  else
+    lua_xmove(L1, L, 1);  /* move object to the "main" stack */
+  lua_setfield(L, -2, fname);  /* put object into table */
+}
+
+
+/*
+** Calls 'lua_getinfo' and collects all results in a new table.
+** L1 needs stack space for an optional input (function) plus
+** two optional outputs (function and line table) from function
+** 'lua_getinfo'.
+*/
+static int db_getinfo (lua_State *L) {
+  lua_Debug ar;
+  int arg;
+  lua_State *L1 = getthread(L, &arg);
+  const char *options = luaL_optstring(L, arg+2, "flnSrtu");
+  checkstack(L, L1, 3);
+  luaL_argcheck(L, options[0] != '>', arg + 2, "invalid option '>'");
+  if (lua_isfunction(L, arg + 1)) {  /* info about a function? */
+    options = lua_pushfstring(L, ">%s", options);  /* add '>' to 'options' */
+    lua_pushvalue(L, arg + 1);  /* move function to 'L1' stack */
+    lua_xmove(L, L1, 1);
+  }
+  else {  /* stack level */
+    if (!lua_getstack(L1, (int)luaL_checkinteger(L, arg + 1), &ar)) {
+      luaL_pushfail(L);  /* level out of range */
+      return 1;
+    }
+  }
+  if (!lua_getinfo(L1, options, &ar))
+    return luaL_argerror(L, arg+2, "invalid option");
+  lua_newtable(L);  /* table to collect results */
+  if (strchr(options, 'S')) {
+    lua_pushlstring(L, ar.source, ar.srclen);
+    lua_setfield(L, -2, "source");
+    settabss(L, "short_src", ar.short_src);
+    settabsi(L, "linedefined", ar.linedefined);
+    settabsi(L, "lastlinedefined", ar.lastlinedefined);
+    settabss(L, "what", ar.what);
+  }
+  if (strchr(options, 'l'))
+    settabsi(L, "currentline", ar.currentline);
+  if (strchr(options, 'u')) {
+    settabsi(L, "nups", ar.nups);
+    settabsi(L, "nparams", ar.nparams);
+    settabsb(L, "isvararg", ar.isvararg);
+  }
+  if (strchr(options, 'n')) {
+    settabss(L, "name", ar.name);
+    settabss(L, "namewhat", ar.namewhat);
+  }
+  if (strchr(options, 'r')) {
+    settabsi(L, "ftransfer", ar.ftransfer);
+    settabsi(L, "ntransfer", ar.ntransfer);
+  }
+  if (strchr(options, 't'))
+    settabsb(L, "istailcall", ar.istailcall);
+  if (strchr(options, 'L'))
+    treatstackoption(L, L1, "activelines");
+  if (strchr(options, 'f'))
+    treatstackoption(L, L1, "func");
+  return 1;  /* return table */
+}
+
+
+static int db_getlocal (lua_State *L) {
+  int arg;
+  lua_State *L1 = getthread(L, &arg);
+  int nvar = (int)luaL_checkinteger(L, arg + 2);  /* local-variable index */
+  if (lua_isfunction(L, arg + 1)) {  /* function argument? */
+    lua_pushvalue(L, arg + 1);  /* push function */
+    lua_pushstring(L, lua_getlocal(L, NULL, nvar));  /* push local name */
+    return 1;  /* return only name (there is no value) */
+  }
+  else {  /* stack-level argument */
+    lua_Debug ar;
+    const char *name;
+    int level = (int)luaL_checkinteger(L, arg + 1);
+    if (l_unlikely(!lua_getstack(L1, level, &ar)))  /* out of range? */
+      return luaL_argerror(L, arg+1, "level out of range");
+    checkstack(L, L1, 1);
+    name = lua_getlocal(L1, &ar, nvar);
+    if (name) {
+      lua_xmove(L1, L, 1);  /* move local value */
+      lua_pushstring(L, name);  /* push name */
+      lua_rotate(L, -2, 1);  /* re-order */
+      return 2;
+    }
+    else {
+      luaL_pushfail(L);  /* no name (nor value) */
+      return 1;
+    }
+  }
+}
+
+
+static int db_setlocal (lua_State *L) {
+  int arg;
+  const char *name;
+  lua_State *L1 = getthread(L, &arg);
+  lua_Debug ar;
+  int level = (int)luaL_checkinteger(L, arg + 1);
+  int nvar = (int)luaL_checkinteger(L, arg + 2);
+  if (l_unlikely(!lua_getstack(L1, level, &ar)))  /* out of range? */
+    return luaL_argerror(L, arg+1, "level out of range");
+  luaL_checkany(L, arg+3);
+  lua_settop(L, arg+3);
+  checkstack(L, L1, 1);
+  lua_xmove(L, L1, 1);
+  name = lua_setlocal(L1, &ar, nvar);
+  if (name == NULL)
+    lua_pop(L1, 1);  /* pop value (if not popped by 'lua_setlocal') */
+  lua_pushstring(L, name);
+  return 1;
+}
+
+
+/*
+** get (if 'get' is true) or set an upvalue from a closure
+*/
+static int auxupvalue (lua_State *L, int get) {
+  const char *name;
+  int n = (int)luaL_checkinteger(L, 2);  /* upvalue index */
+  luaL_checktype(L, 1, LUA_TFUNCTION);  /* closure */
+  name = get ? lua_getupvalue(L, 1, n) : lua_setupvalue(L, 1, n);
+  if (name == NULL) return 0;
+  lua_pushstring(L, name);
+  lua_insert(L, -(get+1));  /* no-op if get is false */
+  return get + 1;
+}
+
+
+static int db_getupvalue (lua_State *L) {
+  return auxupvalue(L, 1);
+}
+
+
+static int db_setupvalue (lua_State *L) {
+  luaL_checkany(L, 3);
+  return auxupvalue(L, 0);
+}
+
+
+/*
+** Check whether a given upvalue from a given closure exists and
+** returns its index
+*/
+static void *checkupval (lua_State *L, int argf, int argnup, int *pnup) {
+  void *id;
+  int nup = (int)luaL_checkinteger(L, argnup);  /* upvalue index */
+  luaL_checktype(L, argf, LUA_TFUNCTION);  /* closure */
+  id = lua_upvalueid(L, argf, nup);
+  if (pnup) {
+    luaL_argcheck(L, id != NULL, argnup, "invalid upvalue index");
+    *pnup = nup;
+  }
+  return id;
+}
+
+
+static int db_upvalueid (lua_State *L) {
+  void *id = checkupval(L, 1, 2, NULL);
+  if (id != NULL)
+    lua_pushlightuserdata(L, id);
+  else
+    luaL_pushfail(L);
+  return 1;
+}
+
+
+static int db_upvaluejoin (lua_State *L) {
+  int n1, n2;
+  checkupval(L, 1, 2, &n1);
+  checkupval(L, 3, 4, &n2);
+  luaL_argcheck(L, !lua_iscfunction(L, 1), 1, "Lua function expected");
+  luaL_argcheck(L, !lua_iscfunction(L, 3), 3, "Lua function expected");
+  lua_upvaluejoin(L, 1, n1, 3, n2);
+  return 0;
+}
+
+
+/*
+** Call hook function registered at hook table for the current
+** thread (if there is one)
+*/
+static void hookf (lua_State *L, lua_Debug *ar) {
+  static const char *const hooknames[] =
+    {"call", "return", "line", "count", "tail call"};
+  lua_getfield(L, LUA_REGISTRYINDEX, HOOKKEY);
+  lua_pushthread(L);
+  if (lua_rawget(L, -2) == LUA_TFUNCTION) {  /* is there a hook function? */
+    lua_pushstring(L, hooknames[(int)ar->event]);  /* push event name */
+    if (ar->currentline >= 0)
+      lua_pushinteger(L, ar->currentline);  /* push current line */
+    else lua_pushnil(L);
+    lua_assert(lua_getinfo(L, "lS", ar));
+    lua_call(L, 2, 0);  /* call hook function */
+  }
+}
+
+
+/*
+** Convert a string mask (for 'sethook') into a bit mask
+*/
+static int makemask (const char *smask, int count) {
+  int mask = 0;
+  if (strchr(smask, 'c')) mask |= LUA_MASKCALL;
+  if (strchr(smask, 'r')) mask |= LUA_MASKRET;
+  if (strchr(smask, 'l')) mask |= LUA_MASKLINE;
+  if (count > 0) mask |= LUA_MASKCOUNT;
+  return mask;
+}
+
+
+/*
+** Convert a bit mask (for 'gethook') into a string mask
+*/
+static char *unmakemask (int mask, char *smask) {
+  int i = 0;
+  if (mask & LUA_MASKCALL) smask[i++] = 'c';
+  if (mask & LUA_MASKRET) smask[i++] = 'r';
+  if (mask & LUA_MASKLINE) smask[i++] = 'l';
+  smask[i] = '\0';
+  return smask;
+}
+
+
+static int db_sethook (lua_State *L) {
+  int arg, mask, count;
+  lua_Hook func;
+  lua_State *L1 = getthread(L, &arg);
+  if (lua_isnoneornil(L, arg+1)) {  /* no hook? */
+    lua_settop(L, arg+1);
+    func = NULL; mask = 0; count = 0;  /* turn off hooks */
+  }
+  else {
+    const char *smask = luaL_checkstring(L, arg+2);
+    luaL_checktype(L, arg+1, LUA_TFUNCTION);
+    count = (int)luaL_optinteger(L, arg + 3, 0);
+    func = hookf; mask = makemask(smask, count);
+  }
+  if (!luaL_getsubtable(L, LUA_REGISTRYINDEX, HOOKKEY)) {
+    /* table just created; initialize it */
+    lua_pushliteral(L, "k");
+    lua_setfield(L, -2, "__mode");  /** hooktable.__mode = "k" */
+    lua_pushvalue(L, -1);
+    lua_setmetatable(L, -2);  /* metatable(hooktable) = hooktable */
+  }
+  checkstack(L, L1, 1);
+  lua_pushthread(L1); lua_xmove(L1, L, 1);  /* key (thread) */
+  lua_pushvalue(L, arg + 1);  /* value (hook function) */
+  lua_rawset(L, -3);  /* hooktable[L1] = new Lua hook */
+  lua_sethook(L1, func, mask, count);
+  return 0;
+}
+
+
+static int db_gethook (lua_State *L) {
+  int arg;
+  lua_State *L1 = getthread(L, &arg);
+  char buff[5];
+  int mask = lua_gethookmask(L1);
+  lua_Hook hook = lua_gethook(L1);
+  if (hook == NULL) {  /* no hook? */
+    luaL_pushfail(L);
+    return 1;
+  }
+  else if (hook != hookf)  /* external hook? */
+    lua_pushliteral(L, "external hook");
+  else {  /* hook table must exist */
+    lua_getfield(L, LUA_REGISTRYINDEX, HOOKKEY);
+    checkstack(L, L1, 1);
+    lua_pushthread(L1); lua_xmove(L1, L, 1);
+    lua_rawget(L, -2);   /* 1st result = hooktable[L1] */
+    lua_remove(L, -2);  /* remove hook table */
+  }
+  lua_pushstring(L, unmakemask(mask, buff));  /* 2nd result = mask */
+  lua_pushinteger(L, lua_gethookcount(L1));  /* 3rd result = count */
+  return 3;
+}
+
+
+static int db_debug (lua_State *L) {
+  for (;;) {
+    char buffer[250];
+    lua_writestringerror("%s", "lua_debug> ");
+    if (fgets(buffer, sizeof(buffer), stdin) == NULL ||
+        strcmp(buffer, "cont\n") == 0)
+      return 0;
+    if (luaL_loadbuffer(L, buffer, strlen(buffer), "=(debug command)") ||
+        lua_pcall(L, 0, 0, 0))
+      lua_writestringerror("%s\n", luaL_tolstring(L, -1, NULL));
+    lua_settop(L, 0);  /* remove eventual returns */
+  }
+}
+
+
+static int db_traceback (lua_State *L) {
+  int arg;
+  lua_State *L1 = getthread(L, &arg);
+  const char *msg = lua_tostring(L, arg + 1);
+  if (msg == NULL && !lua_isnoneornil(L, arg + 1))  /* non-string 'msg'? */
+    lua_pushvalue(L, arg + 1);  /* return it untouched */
+  else {
+    int level = (int)luaL_optinteger(L, arg + 2, (L == L1) ? 1 : 0);
+    luaL_traceback(L, L1, msg, level);
+  }
+  return 1;
+}
+
+
+static int db_setcstacklimit (lua_State *L) {
+  int limit = (int)luaL_checkinteger(L, 1);
+  int res = lua_setcstacklimit(L, limit);
+  lua_pushinteger(L, res);
+  return 1;
+}
+
+
+static const luaL_Reg dblib[] = {
+  {"debug", db_debug},
+  {"getuservalue", db_getuservalue},
+  {"gethook", db_gethook},
+  {"getinfo", db_getinfo},
+  {"getlocal", db_getlocal},
+  {"getregistry", db_getregistry},
+  {"getmetatable", db_getmetatable},
+  {"getupvalue", db_getupvalue},
+  {"upvaluejoin", db_upvaluejoin},
+  {"upvalueid", db_upvalueid},
+  {"setuservalue", db_setuservalue},
+  {"sethook", db_sethook},
+  {"setlocal", db_setlocal},
+  {"setmetatable", db_setmetatable},
+  {"setupvalue", db_setupvalue},
+  {"traceback", db_traceback},
+  {"setcstacklimit", db_setcstacklimit},
+  {NULL, NULL}
+};
+
+
+LUAMOD_API int luaopen_debug (lua_State *L) {
+  luaL_newlib(L, dblib);
+  return 1;
+}
+

thirdparty/lua/ldebug.c

@@ -0,0 +1,971 @@
+/*
+** $Id: ldebug.c $
+** Debug Interface
+** See Copyright Notice in lua.h
+*/
+
+#define ldebug_c
+#define LUA_CORE
+
+#include "lprefix.h"
+
+
+#include <stdarg.h>
+#include <stddef.h>
+#include <string.h>
+
+#include "lua.h"
+
+#include "lapi.h"
+#include "lcode.h"
+#include "ldebug.h"
+#include "ldo.h"
+#include "lfunc.h"
+#include "lobject.h"
+#include "lopcodes.h"
+#include "lstate.h"
+#include "lstring.h"
+#include "ltable.h"
+#include "ltm.h"
+#include "lvm.h"
+
+
+
+#define LuaClosure(f)		((f) != NULL && (f)->c.tt == LUA_VLCL)
+
+
+static const char *funcnamefromcall (lua_State *L, CallInfo *ci,
+                                                   const char **name);
+
+static const char strlocal[] = "local";
+static const char strupval[] = "upvalue";
+
+
+static int currentpc (CallInfo *ci) {
+  lua_assert(isLua(ci));
+  return pcRel(ci->u.l.savedpc, ci_func(ci)->p);
+}
+
+
+/*
+** Get a "base line" to find the line corresponding to an instruction.
+** Base lines are regularly placed at MAXIWTHABS intervals, so usually
+** an integer division gets the right place. When the source file has
+** large sequences of empty/comment lines, it may need extra entries,
+** so the original estimate needs a correction.
+** If the original estimate is -1, the initial 'if' ensures that the
+** 'while' will run at least once.
+** The assertion that the estimate is a lower bound for the correct base
+** is valid as long as the debug info has been generated with the same
+** value for MAXIWTHABS or smaller. (Previous releases use a little
+** smaller value.)
+*/
+static int getbaseline (const Proto *f, int pc, int *basepc) {
+  if (f->sizeabslineinfo == 0 || pc < f->abslineinfo[0].pc) {
+    *basepc = -1;  /* start from the beginning */
+    return f->linedefined;
+  }
+  else {
+    int i = cast_uint(pc) / MAXIWTHABS - 1;  /* get an estimate */
+    /* estimate must be a lower bound of the correct base */
+    lua_assert(i < 0 ||
+              (i < f->sizeabslineinfo && f->abslineinfo[i].pc <= pc));
+    while (i + 1 < f->sizeabslineinfo && pc >= f->abslineinfo[i + 1].pc)
+      i++;  /* low estimate; adjust it */
+    *basepc = f->abslineinfo[i].pc;
+    return f->abslineinfo[i].line;
+  }
+}
+
+
+/*
+** Get the line corresponding to instruction 'pc' in function 'f';
+** first gets a base line and from there does the increments until
+** the desired instruction.
+*/
+int luaG_getfuncline (const Proto *f, int pc) {
+  if (f->lineinfo == NULL)  /* no debug information? */
+    return -1;
+  else {
+    int basepc;
+    int baseline = getbaseline(f, pc, &basepc);
+    while (basepc++ < pc) {  /* walk until given instruction */
+      lua_assert(f->lineinfo[basepc] != ABSLINEINFO);
+      baseline += f->lineinfo[basepc];  /* correct line */
+    }
+    return baseline;
+  }
+}
+
+
+static int getcurrentline (CallInfo *ci) {
+  return luaG_getfuncline(ci_func(ci)->p, currentpc(ci));
+}
+
+
+/*
+** Set 'trap' for all active Lua frames.
+** This function can be called during a signal, under "reasonable"
+** assumptions. A new 'ci' is completely linked in the list before it
+** becomes part of the "active" list, and we assume that pointers are
+** atomic; see comment in next function.
+** (A compiler doing interprocedural optimizations could, theoretically,
+** reorder memory writes in such a way that the list could be
+** temporarily broken while inserting a new element. We simply assume it
+** has no good reasons to do that.)
+*/
+static void settraps (CallInfo *ci) {
+  for (; ci != NULL; ci = ci->previous)
+    if (isLua(ci))
+      ci->u.l.trap = 1;
+}
+
+
+/*
+** This function can be called during a signal, under "reasonable"
+** assumptions.
+** Fields 'basehookcount' and 'hookcount' (set by 'resethookcount')
+** are for debug only, and it is no problem if they get arbitrary
+** values (causes at most one wrong hook call). 'hookmask' is an atomic
+** value. We assume that pointers are atomic too (e.g., gcc ensures that
+** for all platforms where it runs). Moreover, 'hook' is always checked
+** before being called (see 'luaD_hook').
+*/
+LUA_API void lua_sethook (lua_State *L, lua_Hook func, int mask, int count) {
+  if (func == NULL || mask == 0) {  /* turn off hooks? */
+    mask = 0;
+    func = NULL;
+  }
+  L->hook = func;
+  L->basehookcount = count;
+  resethookcount(L);
+  L->hookmask = cast_byte(mask);
+  if (mask)
+    settraps(L->ci);  /* to trace inside 'luaV_execute' */
+}
+
+
+LUA_API lua_Hook lua_gethook (lua_State *L) {
+  return L->hook;
+}
+
+
+LUA_API int lua_gethookmask (lua_State *L) {
+  return L->hookmask;
+}
+
+
+LUA_API int lua_gethookcount (lua_State *L) {
+  return L->basehookcount;
+}
+
+
+LUA_API int lua_getstack (lua_State *L, int level, lua_Debug *ar) {
+  int status;
+  CallInfo *ci;
+  if (level < 0) return 0;  /* invalid (negative) level */
+  lua_lock(L);
+  for (ci = L->ci; level > 0 && ci != &L->base_ci; ci = ci->previous)
+    level--;
+  if (level == 0 && ci != &L->base_ci) {  /* level found? */
+    status = 1;
+    ar->i_ci = ci;
+  }
+  else status = 0;  /* no such level */
+  lua_unlock(L);
+  return status;
+}
+
+
+static const char *upvalname (const Proto *p, int uv) {
+  TString *s = check_exp(uv < p->sizeupvalues, p->upvalues[uv].name);
+  if (s == NULL) return "?";
+  else return getstr(s);
+}
+
+
+static const char *findvararg (CallInfo *ci, int n, StkId *pos) {
+  if (clLvalue(s2v(ci->func.p))->p->is_vararg) {
+    int nextra = ci->u.l.nextraargs;
+    if (n >= -nextra) {  /* 'n' is negative */
+      *pos = ci->func.p - nextra - (n + 1);
+      return "(vararg)";  /* generic name for any vararg */
+    }
+  }
+  return NULL;  /* no such vararg */
+}
+
+
+const char *luaG_findlocal (lua_State *L, CallInfo *ci, int n, StkId *pos) {
+  StkId base = ci->func.p + 1;
+  const char *name = NULL;
+  if (isLua(ci)) {
+    if (n < 0)  /* access to vararg values? */
+      return findvararg(ci, n, pos);
+    else
+      name = luaF_getlocalname(ci_func(ci)->p, n, currentpc(ci));
+  }
+  if (name == NULL) {  /* no 'standard' name? */
+    StkId limit = (ci == L->ci) ? L->top.p : ci->next->func.p;
+    if (limit - base >= n && n > 0) {  /* is 'n' inside 'ci' stack? */
+      /* generic name for any valid slot */
+      name = isLua(ci) ? "(temporary)" : "(C temporary)";
+    }
+    else
+      return NULL;  /* no name */
+  }
+  if (pos)
+    *pos = base + (n - 1);
+  return name;
+}
+
+
+LUA_API const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n) {
+  const char *name;
+  lua_lock(L);
+  if (ar == NULL) {  /* information about non-active function? */
+    if (!isLfunction(s2v(L->top.p - 1)))  /* not a Lua function? */
+      name = NULL;
+    else  /* consider live variables at function start (parameters) */
+      name = luaF_getlocalname(clLvalue(s2v(L->top.p - 1))->p, n, 0);
+  }
+  else {  /* active function; get information through 'ar' */
+    StkId pos = NULL;  /* to avoid warnings */
+    name = luaG_findlocal(L, ar->i_ci, n, &pos);
+    if (name) {
+      setobjs2s(L, L->top.p, pos);
+      api_incr_top(L);
+    }
+  }
+  lua_unlock(L);
+  return name;
+}
+
+
+LUA_API const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n) {
+  StkId pos = NULL;  /* to avoid warnings */
+  const char *name;
+  lua_lock(L);
+  name = luaG_findlocal(L, ar->i_ci, n, &pos);
+  if (name) {
+    setobjs2s(L, pos, L->top.p - 1);
+    L->top.p--;  /* pop value */
+  }
+  lua_unlock(L);
+  return name;
+}
+
+
+static void funcinfo (lua_Debug *ar, Closure *cl) {
+  if (!LuaClosure(cl)) {
+    ar->source = "=[C]";
+    ar->srclen = LL("=[C]");
+    ar->linedefined = -1;
+    ar->lastlinedefined = -1;
+    ar->what = "C";
+  }
+  else {
+    const Proto *p = cl->l.p;
+    if (p->source) {
+      ar->source = getstr(p->source);
+      ar->srclen = tsslen(p->source);
+    }
+    else {
+      ar->source = "=?";
+      ar->srclen = LL("=?");
+    }
+    ar->linedefined = p->linedefined;
+    ar->lastlinedefined = p->lastlinedefined;
+    ar->what = (ar->linedefined == 0) ? "main" : "Lua";
+  }
+  luaO_chunkid(ar->short_src, ar->source, ar->srclen);
+}
+
+
+static int nextline (const Proto *p, int currentline, int pc) {
+  if (p->lineinfo[pc] != ABSLINEINFO)
+    return currentline + p->lineinfo[pc];
+  else
+    return luaG_getfuncline(p, pc);
+}
+
+
+static void collectvalidlines (lua_State *L, Closure *f) {
+  if (!LuaClosure(f)) {
+    setnilvalue(s2v(L->top.p));
+    api_incr_top(L);
+  }
+  else {
+    const Proto *p = f->l.p;
+    int currentline = p->linedefined;
+    Table *t = luaH_new(L);  /* new table to store active lines */
+    sethvalue2s(L, L->top.p, t);  /* push it on stack */
+    api_incr_top(L);
+    if (p->lineinfo != NULL) {  /* proto with debug information? */
+      int i;
+      TValue v;
+      setbtvalue(&v);  /* boolean 'true' to be the value of all indices */
+      if (!p->is_vararg)  /* regular function? */
+        i = 0;  /* consider all instructions */
+      else {  /* vararg function */
+        lua_assert(GET_OPCODE(p->code[0]) == OP_VARARGPREP);
+        currentline = nextline(p, currentline, 0);
+        i = 1;  /* skip first instruction (OP_VARARGPREP) */
+      }
+      for (; i < p->sizelineinfo; i++) {  /* for each instruction */
+        currentline = nextline(p, currentline, i);  /* get its line */
+        luaH_setint(L, t, currentline, &v);  /* table[line] = true */
+      }
+    }
+  }
+}
+
+
+static const char *getfuncname (lua_State *L, CallInfo *ci, const char **name) {
+  /* calling function is a known function? */
+  if (ci != NULL && !(ci->callstatus & CIST_TAIL))
+    return funcnamefromcall(L, ci->previous, name);
+  else return NULL;  /* no way to find a name */
+}
+
+
+static int auxgetinfo (lua_State *L, const char *what, lua_Debug *ar,
+                       Closure *f, CallInfo *ci) {
+  int status = 1;
+  for (; *what; what++) {
+    switch (*what) {
+      case 'S': {
+        funcinfo(ar, f);
+        break;
+      }
+      case 'l': {
+        ar->currentline = (ci && isLua(ci)) ? getcurrentline(ci) : -1;
+        break;
+      }
+      case 'u': {
+        ar->nups = (f == NULL) ? 0 : f->c.nupvalues;
+        if (!LuaClosure(f)) {
+          ar->isvararg = 1;
+          ar->nparams = 0;
+        }
+        else {
+          ar->isvararg = f->l.p->is_vararg;
+          ar->nparams = f->l.p->numparams;
+        }
+        break;
+      }
+      case 't': {
+        ar->istailcall = (ci) ? ci->callstatus & CIST_TAIL : 0;
+        break;
+      }
+      case 'n': {
+        ar->namewhat = getfuncname(L, ci, &ar->name);
+        if (ar->namewhat == NULL) {
+          ar->namewhat = "";  /* not found */
+          ar->name = NULL;
+        }
+        break;
+      }
+      case 'r': {
+        if (ci == NULL || !(ci->callstatus & CIST_TRAN))
+          ar->ftransfer = ar->ntransfer = 0;
+        else {
+          ar->ftransfer = ci->u2.transferinfo.ftransfer;
+          ar->ntransfer = ci->u2.transferinfo.ntransfer;
+        }
+        break;
+      }
+      case 'L':
+      case 'f':  /* handled by lua_getinfo */
+        break;
+      default: status = 0;  /* invalid option */
+    }
+  }
+  return status;
+}
+
+
+LUA_API int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar) {
+  int status;
+  Closure *cl;
+  CallInfo *ci;
+  TValue *func;
+  lua_lock(L);
+  if (*what == '>') {
+    ci = NULL;
+    func = s2v(L->top.p - 1);
+    api_check(L, ttisfunction(func), "function expected");
+    what++;  /* skip the '>' */
+    L->top.p--;  /* pop function */
+  }
+  else {
+    ci = ar->i_ci;
+    func = s2v(ci->func.p);
+    lua_assert(ttisfunction(func));
+  }
+  cl = ttisclosure(func) ? clvalue(func) : NULL;
+  status = auxgetinfo(L, what, ar, cl, ci);
+  if (strchr(what, 'f')) {
+    setobj2s(L, L->top.p, func);
+    api_incr_top(L);
+  }
+  if (strchr(what, 'L'))
+    collectvalidlines(L, cl);
+  lua_unlock(L);
+  return status;
+}
+
+
+/*
+** {======================================================
+** Symbolic Execution
+** =======================================================
+*/
+
+
+static int filterpc (int pc, int jmptarget) {
+  if (pc < jmptarget)  /* is code conditional (inside a jump)? */
+    return -1;  /* cannot know who sets that register */
+  else return pc;  /* current position sets that register */
+}
+
+
+/*
+** Try to find last instruction before 'lastpc' that modified register 'reg'.
+*/
+static int findsetreg (const Proto *p, int lastpc, int reg) {
+  int pc;
+  int setreg = -1;  /* keep last instruction that changed 'reg' */
+  int jmptarget = 0;  /* any code before this address is conditional */
+  if (testMMMode(GET_OPCODE(p->code[lastpc])))
+    lastpc--;  /* previous instruction was not actually executed */
+  for (pc = 0; pc < lastpc; pc++) {
+    Instruction i = p->code[pc];
+    OpCode op = GET_OPCODE(i);
+    int a = GETARG_A(i);
+    int change;  /* true if current instruction changed 'reg' */
+    switch (op) {
+      case OP_LOADNIL: {  /* set registers from 'a' to 'a+b' */
+        int b = GETARG_B(i);
+        change = (a <= reg && reg <= a + b);
+        break;
+      }
+      case OP_TFORCALL: {  /* affect all regs above its base */
+        change = (reg >= a + 2);
+        break;
+      }
+      case OP_CALL:
+      case OP_TAILCALL: {  /* affect all registers above base */
+        change = (reg >= a);
+        break;
+      }
+      case OP_JMP: {  /* doesn't change registers, but changes 'jmptarget' */
+        int b = GETARG_sJ(i);
+        int dest = pc + 1 + b;
+        /* jump does not skip 'lastpc' and is larger than current one? */
+        if (dest <= lastpc && dest > jmptarget)
+          jmptarget = dest;  /* update 'jmptarget' */
+        change = 0;
+        break;
+      }
+      default:  /* any instruction that sets A */
+        change = (testAMode(op) && reg == a);
+        break;
+    }
+    if (change)
+      setreg = filterpc(pc, jmptarget);
+  }
+  return setreg;
+}
+
+
+/*
+** Find a "name" for the constant 'c'.
+*/
+static const char *kname (const Proto *p, int index, const char **name) {
+  TValue *kvalue = &p->k[index];
+  if (ttisstring(kvalue)) {
+    *name = getstr(tsvalue(kvalue));
+    return "constant";
+  }
+  else {
+    *name = "?";
+    return NULL;
+  }
+}
+
+
+static const char *basicgetobjname (const Proto *p, int *ppc, int reg,
+                                    const char **name) {
+  int pc = *ppc;
+  *name = luaF_getlocalname(p, reg + 1, pc);
+  if (*name)  /* is a local? */
+    return strlocal;
+  /* else try symbolic execution */
+  *ppc = pc = findsetreg(p, pc, reg);
+  if (pc != -1) {  /* could find instruction? */
+    Instruction i = p->code[pc];
+    OpCode op = GET_OPCODE(i);
+    switch (op) {
+      case OP_MOVE: {
+        int b = GETARG_B(i);  /* move from 'b' to 'a' */
+        if (b < GETARG_A(i))
+          return basicgetobjname(p, ppc, b, name);  /* get name for 'b' */
+        break;
+      }
+      case OP_GETUPVAL: {
+        *name = upvalname(p, GETARG_B(i));
+        return strupval;
+      }
+      case OP_LOADK: return kname(p, GETARG_Bx(i), name);
+      case OP_LOADKX: return kname(p, GETARG_Ax(p->code[pc + 1]), name);
+      default: break;
+    }
+  }
+  return NULL;  /* could not find reasonable name */
+}
+
+
+/*
+** Find a "name" for the register 'c'.
+*/
+static void rname (const Proto *p, int pc, int c, const char **name) {
+  const char *what = basicgetobjname(p, &pc, c, name); /* search for 'c' */
+  if (!(what && *what == 'c'))  /* did not find a constant name? */
+    *name = "?";
+}
+
+
+/*
+** Find a "name" for a 'C' value in an RK instruction.
+*/
+static void rkname (const Proto *p, int pc, Instruction i, const char **name) {
+  int c = GETARG_C(i);  /* key index */
+  if (GETARG_k(i))  /* is 'c' a constant? */
+    kname(p, c, name);
+  else  /* 'c' is a register */
+    rname(p, pc, c, name);
+}
+
+
+/*
+** Check whether table being indexed by instruction 'i' is the
+** environment '_ENV'. If the table is an upvalue, get its name;
+** otherwise, find some "name" for the table and check whether
+** that name is the name of a local variable (and not, for instance,
+** a string). Then check that, if there is a name, it is '_ENV'.
+*/
+static const char *isEnv (const Proto *p, int pc, Instruction i, int isup) {
+  int t = GETARG_B(i);  /* table index */
+  const char *name;  /* name of indexed variable */
+  if (isup)  /* is 't' an upvalue? */
+    name = upvalname(p, t);
+  else {  /* 't' is a register */
+    const char *what = basicgetobjname(p, &pc, t, &name);
+    if (what != strlocal && what != strupval)
+      name = NULL;  /* cannot be the variable _ENV */
+  }
+  return (name && strcmp(name, LUA_ENV) == 0) ? "global" : "field";
+}
+
+
+/*
+** Extend 'basicgetobjname' to handle table accesses
+*/
+static const char *getobjname (const Proto *p, int lastpc, int reg,
+                               const char **name) {
+  const char *kind = basicgetobjname(p, &lastpc, reg, name);
+  if (kind != NULL)
+    return kind;
+  else if (lastpc != -1) {  /* could find instruction? */
+    Instruction i = p->code[lastpc];
+    OpCode op = GET_OPCODE(i);
+    switch (op) {
+      case OP_GETTABUP: {
+        int k = GETARG_C(i);  /* key index */
+        kname(p, k, name);
+        return isEnv(p, lastpc, i, 1);
+      }
+      case OP_GETTABLE: {
+        int k = GETARG_C(i);  /* key index */
+        rname(p, lastpc, k, name);
+        return isEnv(p, lastpc, i, 0);
+      }
+      case OP_GETI: {
+        *name = "integer index";
+        return "field";
+      }
+      case OP_GETFIELD: {
+        int k = GETARG_C(i);  /* key index */
+        kname(p, k, name);
+        return isEnv(p, lastpc, i, 0);
+      }
+      case OP_SELF: {
+        rkname(p, lastpc, i, name);
+        return "method";
+      }
+      default: break;  /* go through to return NULL */
+    }
+  }
+  return NULL;  /* could not find reasonable name */
+}
+
+
+/*
+** Try to find a name for a function based on the code that called it.
+** (Only works when function was called by a Lua function.)
+** Returns what the name is (e.g., "for iterator", "method",
+** "metamethod") and sets '*name' to point to the name.
+*/
+static const char *funcnamefromcode (lua_State *L, const Proto *p,
+                                     int pc, const char **name) {
+  TMS tm = (TMS)0;  /* (initial value avoids warnings) */
+  Instruction i = p->code[pc];  /* calling instruction */
+  switch (GET_OPCODE(i)) {
+    case OP_CALL:
+    case OP_TAILCALL:
+      return getobjname(p, pc, GETARG_A(i), name);  /* get function name */
+    case OP_TFORCALL: {  /* for iterator */
+      *name = "for iterator";
+       return "for iterator";
+    }
+    /* other instructions can do calls through metamethods */
+    case OP_SELF: case OP_GETTABUP: case OP_GETTABLE:
+    case OP_GETI: case OP_GETFIELD:
+      tm = TM_INDEX;
+      break;
+    case OP_SETTABUP: case OP_SETTABLE: case OP_SETI: case OP_SETFIELD:
+      tm = TM_NEWINDEX;
+      break;
+    case OP_MMBIN: case OP_MMBINI: case OP_MMBINK: {
+      tm = cast(TMS, GETARG_C(i));
+      break;
+    }
+    case OP_UNM: tm = TM_UNM; break;
+    case OP_BNOT: tm = TM_BNOT; break;
+    case OP_LEN: tm = TM_LEN; break;
+    case OP_CONCAT: tm = TM_CONCAT; break;
+    case OP_EQ: tm = TM_EQ; break;
+    /* no cases for OP_EQI and OP_EQK, as they don't call metamethods */
+    case OP_LT: case OP_LTI: case OP_GTI: tm = TM_LT; break;
+    case OP_LE: case OP_LEI: case OP_GEI: tm = TM_LE; break;
+    case OP_CLOSE: case OP_RETURN: tm = TM_CLOSE; break;
+    default:
+      return NULL;  /* cannot find a reasonable name */
+  }
+  *name = getshrstr(G(L)->tmname[tm]) + 2;
+  return "metamethod";
+}
+
+
+/*
+** Try to find a name for a function based on how it was called.
+*/
+static const char *funcnamefromcall (lua_State *L, CallInfo *ci,
+                                                   const char **name) {
+  if (ci->callstatus & CIST_HOOKED) {  /* was it called inside a hook? */
+    *name = "?";
+    return "hook";
+  }
+  else if (ci->callstatus & CIST_FIN) {  /* was it called as a finalizer? */
+    *name = "__gc";
+    return "metamethod";  /* report it as such */
+  }
+  else if (isLua(ci))
+    return funcnamefromcode(L, ci_func(ci)->p, currentpc(ci), name);
+  else
+    return NULL;
+}
+
+/* }====================================================== */
+
+
+
+/*
+** Check whether pointer 'o' points to some value in the stack frame of
+** the current function and, if so, returns its index.  Because 'o' may
+** not point to a value in this stack, we cannot compare it with the
+** region boundaries (undefined behavior in ISO C).
+*/
+static int instack (CallInfo *ci, const TValue *o) {
+  int pos;
+  StkId base = ci->func.p + 1;
+  for (pos = 0; base + pos < ci->top.p; pos++) {
+    if (o == s2v(base + pos))
+      return pos;
+  }
+  return -1;  /* not found */
+}
+
+
+/*
+** Checks whether value 'o' came from an upvalue. (That can only happen
+** with instructions OP_GETTABUP/OP_SETTABUP, which operate directly on
+** upvalues.)
+*/
+static const char *getupvalname (CallInfo *ci, const TValue *o,
+                                 const char **name) {
+  LClosure *c = ci_func(ci);
+  int i;
+  for (i = 0; i < c->nupvalues; i++) {
+    if (c->upvals[i]->v.p == o) {
+      *name = upvalname(c->p, i);
+      return strupval;
+    }
+  }
+  return NULL;
+}
+
+
+static const char *formatvarinfo (lua_State *L, const char *kind,
+                                                const char *name) {
+  if (kind == NULL)
+    return "";  /* no information */
+  else
+    return luaO_pushfstring(L, " (%s '%s')", kind, name);
+}
+
+/*
+** Build a string with a "description" for the value 'o', such as
+** "variable 'x'" or "upvalue 'y'".
+*/
+static const char *varinfo (lua_State *L, const TValue *o) {
+  CallInfo *ci = L->ci;
+  const char *name = NULL;  /* to avoid warnings */
+  const char *kind = NULL;
+  if (isLua(ci)) {
+    kind = getupvalname(ci, o, &name);  /* check whether 'o' is an upvalue */
+    if (!kind) {  /* not an upvalue? */
+      int reg = instack(ci, o);  /* try a register */
+      if (reg >= 0)  /* is 'o' a register? */
+        kind = getobjname(ci_func(ci)->p, currentpc(ci), reg, &name);
+    }
+  }
+  return formatvarinfo(L, kind, name);
+}
+
+
+/*
+** Raise a type error
+*/
+static l_noret typeerror (lua_State *L, const TValue *o, const char *op,
+                          const char *extra) {
+  const char *t = luaT_objtypename(L, o);
+  luaG_runerror(L, "attempt to %s a %s value%s", op, t, extra);
+}
+
+
+/*
+** Raise a type error with "standard" information about the faulty
+** object 'o' (using 'varinfo').
+*/
+l_noret luaG_typeerror (lua_State *L, const TValue *o, const char *op) {
+  typeerror(L, o, op, varinfo(L, o));
+}
+
+
+/*
+** Raise an error for calling a non-callable object. Try to find a name
+** for the object based on how it was called ('funcnamefromcall'); if it
+** cannot get a name there, try 'varinfo'.
+*/
+l_noret luaG_callerror (lua_State *L, const TValue *o) {
+  CallInfo *ci = L->ci;
+  const char *name = NULL;  /* to avoid warnings */
+  const char *kind = funcnamefromcall(L, ci, &name);
+  const char *extra = kind ? formatvarinfo(L, kind, name) : varinfo(L, o);
+  typeerror(L, o, "call", extra);
+}
+
+
+l_noret luaG_forerror (lua_State *L, const TValue *o, const char *what) {
+  luaG_runerror(L, "bad 'for' %s (number expected, got %s)",
+                   what, luaT_objtypename(L, o));
+}
+
+
+l_noret luaG_concaterror (lua_State *L, const TValue *p1, const TValue *p2) {
+  if (ttisstring(p1) || cvt2str(p1)) p1 = p2;
+  luaG_typeerror(L, p1, "concatenate");
+}
+
+
+l_noret luaG_opinterror (lua_State *L, const TValue *p1,
+                         const TValue *p2, const char *msg) {
+  if (!ttisnumber(p1))  /* first operand is wrong? */
+    p2 = p1;  /* now second is wrong */
+  luaG_typeerror(L, p2, msg);
+}
+
+
+/*
+** Error when both values are convertible to numbers, but not to integers
+*/
+l_noret luaG_tointerror (lua_State *L, const TValue *p1, const TValue *p2) {
+  lua_Integer temp;
+  if (!luaV_tointegerns(p1, &temp, LUA_FLOORN2I))
+    p2 = p1;
+  luaG_runerror(L, "number%s has no integer representation", varinfo(L, p2));
+}
+
+
+l_noret luaG_ordererror (lua_State *L, const TValue *p1, const TValue *p2) {
+  const char *t1 = luaT_objtypename(L, p1);
+  const char *t2 = luaT_objtypename(L, p2);
+  if (strcmp(t1, t2) == 0)
+    luaG_runerror(L, "attempt to compare two %s values", t1);
+  else
+    luaG_runerror(L, "attempt to compare %s with %s", t1, t2);
+}
+
+
+/* add src:line information to 'msg' */
+const char *luaG_addinfo (lua_State *L, const char *msg, TString *src,
+                                        int line) {
+  char buff[LUA_IDSIZE];
+  if (src)
+    luaO_chunkid(buff, getstr(src), tsslen(src));
+  else {  /* no source available; use "?" instead */
+    buff[0] = '?'; buff[1] = '\0';
+  }
+  return luaO_pushfstring(L, "%s:%d: %s", buff, line, msg);
+}
+
+
+l_noret luaG_errormsg (lua_State *L) {
+  if (L->errfunc != 0) {  /* is there an error handling function? */
+    StkId errfunc = restorestack(L, L->errfunc);
+    lua_assert(ttisfunction(s2v(errfunc)));
+    setobjs2s(L, L->top.p, L->top.p - 1);  /* move argument */
+    setobjs2s(L, L->top.p - 1, errfunc);  /* push function */
+    L->top.p++;  /* assume EXTRA_STACK */
+    luaD_callnoyield(L, L->top.p - 2, 1);  /* call it */
+  }
+  luaD_throw(L, LUA_ERRRUN);
+}
+
+
+l_noret luaG_runerror (lua_State *L, const char *fmt, ...) {
+  CallInfo *ci = L->ci;
+  const char *msg;
+  va_list argp;
+  luaC_checkGC(L);  /* error message uses memory */
+  va_start(argp, fmt);
+  msg = luaO_pushvfstring(L, fmt, argp);  /* format message */
+  va_end(argp);
+  if (isLua(ci)) {  /* if Lua function, add source:line information */
+    luaG_addinfo(L, msg, ci_func(ci)->p->source, getcurrentline(ci));
+    setobjs2s(L, L->top.p - 2, L->top.p - 1);  /* remove 'msg' */
+    L->top.p--;
+  }
+  luaG_errormsg(L);
+}
+
+
+/*
+** Check whether new instruction 'newpc' is in a different line from
+** previous instruction 'oldpc'. More often than not, 'newpc' is only
+** one or a few instructions after 'oldpc' (it must be after, see
+** caller), so try to avoid calling 'luaG_getfuncline'. If they are
+** too far apart, there is a good chance of a ABSLINEINFO in the way,
+** so it goes directly to 'luaG_getfuncline'.
+*/
+static int changedline (const Proto *p, int oldpc, int newpc) {
+  if (p->lineinfo == NULL)  /* no debug information? */
+    return 0;
+  if (newpc - oldpc < MAXIWTHABS / 2) {  /* not too far apart? */
+    int delta = 0;  /* line difference */
+    int pc = oldpc;
+    for (;;) {
+      int lineinfo = p->lineinfo[++pc];
+      if (lineinfo == ABSLINEINFO)
+        break;  /* cannot compute delta; fall through */
+      delta += lineinfo;
+      if (pc == newpc)
+        return (delta != 0);  /* delta computed successfully */
+    }
+  }
+  /* either instructions are too far apart or there is an absolute line
+     info in the way; compute line difference explicitly */
+  return (luaG_getfuncline(p, oldpc) != luaG_getfuncline(p, newpc));
+}
+
+
+/*
+** Traces Lua calls. If code is running the first instruction of a function,
+** and function is not vararg, and it is not coming from an yield,
+** calls 'luaD_hookcall'. (Vararg functions will call 'luaD_hookcall'
+** after adjusting its variable arguments; otherwise, they could call
+** a line/count hook before the call hook. Functions coming from
+** an yield already called 'luaD_hookcall' before yielding.)
+*/
+int luaG_tracecall (lua_State *L) {
+  CallInfo *ci = L->ci;
+  Proto *p = ci_func(ci)->p;
+  ci->u.l.trap = 1;  /* ensure hooks will be checked */
+  if (ci->u.l.savedpc == p->code) {  /* first instruction (not resuming)? */
+    if (p->is_vararg)
+      return 0;  /* hooks will start at VARARGPREP instruction */
+    else if (!(ci->callstatus & CIST_HOOKYIELD))  /* not yieded? */
+      luaD_hookcall(L, ci);  /* check 'call' hook */
+  }
+  return 1;  /* keep 'trap' on */
+}
+
+
+/*
+** Traces the execution of a Lua function. Called before the execution
+** of each opcode, when debug is on. 'L->oldpc' stores the last
+** instruction traced, to detect line changes. When entering a new
+** function, 'npci' will be zero and will test as a new line whatever
+** the value of 'oldpc'.  Some exceptional conditions may return to
+** a function without setting 'oldpc'. In that case, 'oldpc' may be
+** invalid; if so, use zero as a valid value. (A wrong but valid 'oldpc'
+** at most causes an extra call to a line hook.)
+** This function is not "Protected" when called, so it should correct
+** 'L->top.p' before calling anything that can run the GC.
+*/
+int luaG_traceexec (lua_State *L, const Instruction *pc) {
+  CallInfo *ci = L->ci;
+  lu_byte mask = L->hookmask;
+  const Proto *p = ci_func(ci)->p;
+  int counthook;
+  if (!(mask & (LUA_MASKLINE | LUA_MASKCOUNT))) {  /* no hooks? */
+    ci->u.l.trap = 0;  /* don't need to stop again */
+    return 0;  /* turn off 'trap' */
+  }
+  pc++;  /* reference is always next instruction */
+  ci->u.l.savedpc = pc;  /* save 'pc' */
+  counthook = (mask & LUA_MASKCOUNT) && (--L->hookcount == 0);
+  if (counthook)
+    resethookcount(L);  /* reset count */
+  else if (!(mask & LUA_MASKLINE))
+    return 1;  /* no line hook and count != 0; nothing to be done now */
+  if (ci->callstatus & CIST_HOOKYIELD) {  /* hook yielded last time? */
+    ci->callstatus &= ~CIST_HOOKYIELD;  /* erase mark */
+    return 1;  /* do not call hook again (VM yielded, so it did not move) */
+  }
+  if (!isIT(*(ci->u.l.savedpc - 1)))  /* top not being used? */
+    L->top.p = ci->top.p;  /* correct top */
+  if (counthook)
+    luaD_hook(L, LUA_HOOKCOUNT, -1, 0, 0);  /* call count hook */
+  if (mask & LUA_MASKLINE) {
+    /* 'L->oldpc' may be invalid; use zero in this case */
+    int oldpc = (L->oldpc < p->sizecode) ? L->oldpc : 0;
+    int npci = pcRel(pc, p);
+    if (npci <= oldpc ||  /* call hook when jump back (loop), */
+        changedline(p, oldpc, npci)) {  /* or when enter new line */
+      int newline = luaG_getfuncline(p, npci);
+      luaD_hook(L, LUA_HOOKLINE, newline, 0, 0);  /* call line hook */
+    }
+    L->oldpc = npci;  /* 'pc' of last call to line hook */
+  }
+  if (L->status == LUA_YIELD) {  /* did hook yield? */
+    if (counthook)
+      L->hookcount = 1;  /* undo decrement to zero */
+    ci->callstatus |= CIST_HOOKYIELD;  /* mark that it yielded */
+    luaD_throw(L, LUA_YIELD);
+  }
+  return 1;  /* keep 'trap' on */
+}
+

thirdparty/lua/ldebug.h

@@ -0,0 +1,64 @@
+/*
+** $Id: ldebug.h $
+** Auxiliary functions from Debug Interface module
+** See Copyright Notice in lua.h
+*/
+
+#ifndef ldebug_h
+#define ldebug_h
+
+
+#include "lstate.h"
+
+
+#define pcRel(pc, p)	(cast_int((pc) - (p)->code) - 1)
+
+
+/* Active Lua function (given call info) */
+#define ci_func(ci)		(clLvalue(s2v((ci)->func.p)))
+
+
+#define resethookcount(L)	(L->hookcount = L->basehookcount)
+
+/*
+** mark for entries in 'lineinfo' array that has absolute information in
+** 'abslineinfo' array
+*/
+#define ABSLINEINFO	(-0x80)
+
+
+/*
+** MAXimum number of successive Instructions WiTHout ABSolute line
+** information. (A power of two allows fast divisions.)
+*/
+#if !defined(MAXIWTHABS)
+#define MAXIWTHABS	128
+#endif
+
+
+LUAI_FUNC int luaG_getfuncline (const Proto *f, int pc);
+LUAI_FUNC const char *luaG_findlocal (lua_State *L, CallInfo *ci, int n,
+                                                    StkId *pos);
+LUAI_FUNC l_noret luaG_typeerror (lua_State *L, const TValue *o,
+                                                const char *opname);
+LUAI_FUNC l_noret luaG_callerror (lua_State *L, const TValue *o);
+LUAI_FUNC l_noret luaG_forerror (lua_State *L, const TValue *o,
+                                               const char *what);
+LUAI_FUNC l_noret luaG_concaterror (lua_State *L, const TValue *p1,
+                                                  const TValue *p2);
+LUAI_FUNC l_noret luaG_opinterror (lua_State *L, const TValue *p1,
+                                                 const TValue *p2,
+                                                 const char *msg);
+LUAI_FUNC l_noret luaG_tointerror (lua_State *L, const TValue *p1,
+                                                 const TValue *p2);
+LUAI_FUNC l_noret luaG_ordererror (lua_State *L, const TValue *p1,
+                                                 const TValue *p2);
+LUAI_FUNC l_noret luaG_runerror (lua_State *L, const char *fmt, ...);
+LUAI_FUNC const char *luaG_addinfo (lua_State *L, const char *msg,
+                                                  TString *src, int line);
+LUAI_FUNC l_noret luaG_errormsg (lua_State *L);
+LUAI_FUNC int luaG_traceexec (lua_State *L, const Instruction *pc);
+LUAI_FUNC int luaG_tracecall (lua_State *L);
+
+
+#endif