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.	Language 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
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. Enumerated in the Language 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 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.