Language Standard

KEC Lisp is built in layers. This page describes them and links to the reference pages that enumerate each layer’s forms.

The layers

Layer	What it is	In this repo	Reference
Fe Kernel	26 compiled-in primitives + reader + evaluator + arena/GC.	Vendored `rxi/fe` 1.0 with the changes in The Fe kernel below.	Built-ins
KEC Core	The standard library — `map`, `filter`, `fold-left`, `cond`, `when`, `defn`, … — written in KEC Lisp, loaded into every context before user code runs.	`core/*.lsp`, baked into the `kec` binary at build time.	Core Library Reference
Runtime / host primitives	Portable C exposed to KEC Lisp — error control, `type-of`, math, string ops, I/O, a few system calls.	`runtime/kec.c` and `host/host.c`, registered through `kec_bind_fe`.	Language Reference
Extended Library (editor/REPL tier)	A host-agnostic, `provide`-gated library above Core: the text buffer, undo, keymap-as-data + dispatch, the token ranker, the REPL engine, and the SEAM host contract that knEmacs and `kec repl` are built from.	`editor/*.lsp`, loaded on demand (not baked into every context).	Extended Library Reference
Device primitives + cart grammar	The KN-86 runtime FFI (graphics, audio, save, missions, CIPHER) and the `defcell`/`defmission` macros.	Not in this repo — in the firmware.	The KN-86 firmware

Which primitives a context is created with determines what it can call; see the FFI Bridge.

The Fe kernel

The 26 compiled-in primitives:

let  set  if  fn  mac  while  quote  and  or  do
cons  car  cdr  setcar  setcdr  list  not  is  atom  print
<  <=  +  -  *  /

Full reference: Built-ins. Single-precision-float numbers; immutable strings; nil is false and the empty list; quasiquote reader sugar; no booleans, vectors, hash tables, keyword args, TCO, or eval-from-Lisp.

The kernel is rxi’s Fe, vendored. Its changes from upstream Fe:

Assignment is set, not = — = is equality, supplied by Core.
Top-level let binds globally instead of being a silent no-op.
GCSTACKSIZE is compile-time configurable — default 256, raised to 8192 on the desktop build.

Recorded in the CHANGELOG. For the full kernel implementation — object encoding, GC mechanics, and known constraints — see Fe Kernel — Internals.

Core and runtime / host primitives

KEC Core is the standard library, written in KEC Lisp and loaded into every context before user code runs: definition macros (defn, defmacro, define), list/sequence functions, comparison (=, ==, /=, >, >=, …), type predicates, alist helpers, error value helpers, control macros (cond, case, when, dotimes, …), quasiquote expansion, higher-order functions, and string/format helpers. Its list/sequence functions are written iteratively. Summarized in the Language Reference; full per-function reference in the Core Library Reference.

Runtime / host primitives are C functions that need only the runtime or C library — error control, type-of, math, string ops, I/O, and a few system calls — bound per profile: SANDBOX is the portable set; FULL adds load, file I/O, environment, args, and exit. Enumerated in the Language Reference.

The Extended Library (editor/REPL tier)

Above Core, editor/*.lsp is a second, provide-gated Lisp library (ADR-0002): a text buffer + undo, a keymap-as-data dispatcher, a completion ranker, a REPL engine, and the SEAM contract a host wires up to get knEmacs and a standalone REPL. It’s not loaded into every context — only sessions that (require ...) it — and it’s entirely portable Lisp: the kec CLI is the reference host today, and the KN-86 firmware wires the same SEAM against its own input/display. Full reference: Extended Library Reference. Using it as an editor day-to-day: knEmacs.

The FFI bridge

A C function becomes a KEC Lisp symbol through kec_bind_fe(ctx, "name", fn). Registration, the C↔Lisp type table, opaque handles, profiles, error propagation, and arena discipline are on the FFI Bridge page. This is how both this repo’s runtime/host primitives and the firmware’s device primitives are added.

The KN-86 firmware

The KN-86 firmware vendors this repo and adds its device primitives — graphics, audio, save state, missions, the CIPHER voice — and the cartridge authoring macros (defcell, defmission, …), through the same FFI bridge. None of that is in this repo. See What’s Here.