KidLisp — Score #
The KidLisp "score": one place to track the language spec, the reference implementation, every conforming runtime in the monorepo, and the conformance corpus they're all graded against.
KidLisp is a language, not a file.
system/public/aesthetic.computer/lib/kidlisp.mjsis the reference implementation; the specification isKidLisp Decree '26. Any runtime — JS, Common Lisp, Swift, WASM, Game Boy ROM — claims a conformance level against the Decree and runs the same corpus.
1. Specification #
| Document | Path | Role |
|---|---|---|
| Decree '26 | kidlisp/docs/core/kidlisp-decree-26.md |
Normative ABI + conformance levels |
| Decree (latest pointer) | kidlisp/docs/core/kidlisp-decree.md |
Always points at the current stable decree |
| Language reference | kidlisp/docs/core/language-reference.md |
Syntax + constructs |
| Complete API map | kidlisp/COMPLETE_API_MAP.md |
All 118 built-ins, grouped |
Conformance levels (Decree '26 §3):
Core— parser, evaluator, lifecycle ABI, host shapeRender— offscreen buffers,page/paste, alpha compositingAudio—amp/micglobals + ranges
Named profiles:
RBP-26—$rozBaseline Profile (Decree '26 §13.1). Minimum surface to run$rozcorrectly:ink/line/circle/scroll/spin/zoom/contrast/?/1s.../2s.../0.5s/fade:…, magic varsw/h/w/2/h/2.
Canonical claim format: KidLisp Decree '26: Core + Render (extend with + Audio and/or + RBP-26 as supported).
2. Reference Implementation #
| Path | Surface |
|---|---|
system/public/aesthetic.computer/lib/kidlisp.mjs |
The canonical evaluator — JS, runs in browser + Node + JSC |
system/netlify/functions/store-kidlisp.mjs |
Source storage / $code resolution / hit counting |
kidlisp/tools/ |
api-summary.mjs, source-tree.mjs, etc. |
The reference impl is load-bearing for deployment (web runtime, service worker cache, disk.mjs imports, session server). Its path is frozen; do not move it.
3. Runtime Registry #
Every implementation in the monorepo, with claimed conformance level and current status. Update this row when you change a runtime's surface.
| Runtime | Path | Decree claim | Status | Notes |
|---|---|---|---|---|
| JS (reference) | system/public/aesthetic.computer/lib/kidlisp.mjs |
'26: Core + Render + Audio |
shipping baseline | Canonical; local opt-in execution controls and numeric-plan tooling are experimental (see §9) |
| Common Lisp (AC Native) | fedac/native/cl/kidlisp-*.lisp |
'26: Core + Render (target) |
in progress | Tree-walker, DRM/KMS framebuffer; replacing QuickJS path |
| Swift (Menuband) | slab/menuband/ |
'26: Core + Render (planned) |
not started | This document's motivating port; Metal blit + CPU framebuffer |
| WASM | kidlisp-wasm/; lib/kidlisp-plan-wasm.mjs |
unclaimed | experimental | Existing f32 renderer compiler; separate f64 numeric-v1 backend preserves audited JS arithmetic (§9) |
| WebGPU benchmark | kidlisp/benchmarks/raytrace-gpu.mjs |
unclaimed | experimental | f32 WGSL ray kernel lowered from the numeric plan; bounded handwritten scene host, CPU fallback (§9) |
| WebGPU feedback graph | kidlisp/graph/ |
unclaimed | experimental | Pinned $roz reference controls → ordered integer GPU effects; persistent buffers and 2D preview (§9) |
| Playdate | kidlisp-playdate/ |
unclaimed | experimental | C runtime for Panic Playdate |
| Game Boy | kidlisp-gameboy/ |
unclaimed | experimental | GBDK C + asm |
| N64 | kidlisp-n64/ |
unclaimed | experimental | Bare-metal asm exploration |
| CLI | kidlisp-cli/ |
host-runner | shipping | Public kidlisp CLI |
| Sidecar | kidlisp-sidecar/ |
host-service | shipping | Clojure service |
| VS Code syntax | vscode-extension/kidlisp-syntax.ts |
tooling | shipping | Editor highlighting only |
| kidlisp.com | kidlisp.com/ |
site | shipping | Landing page |
| Knowledge base | kidlisp-knowledge/ |
docs | shipping | LLM-oriented documentation aggregator |
| Analysis tools | kidlisp-tools/, kidlisp/tools/ |
tooling | shipping | Probe + source-tree (two locations — see Open Questions) |
4. Conformance Corpus #
The corpus is the top KidLisp pieces by live hit count, pulled from production. Any new runtime is expected to render these pixel-comparably against the reference implementation.
Refresh command: node kidlisp/conformance/oracle.mjs refresh --top 40 (pins the top 40 into conformance/corpus.json). The JS reference is graded against itself by the pixel oracle: node kidlisp/conformance/oracle.mjs check renders the corpus from origin/main and this checkout and fails on blank, gone or newly-erroring pieces — see conformance/README.md.
Top 10 (refreshed 2026-05-25) #
| # | Code | Hits | Chars | Source / feature footprint |
|---|---|---|---|---|
| 1 | $bop |
14,708 | 25 | purple, ink, line, blur 5 — bare-color wipe, bare commands, blur |
| 2 | $pie |
10,363 | 153 | (fps 24), timing wipe, magic vars, scroll frame frame |
| 3 | $roz |
9,106 | 239 | fade: gradient, 1s.../2s.../0.5s, ?, spin/zoom/contrast/scroll/circle → RBP-26 reference |
| 4 | $4xa |
8,330 | 4 | blue — bare color = implicit wipe |
| 5 | $ceo |
8,167 | 82 | coat fade:…:frame animated gradient + zoom |
| 6 | $cow |
7,819 | 52 | ($39i 0 0 w h 128) ($r2f …) — $code embeds (recursive eval) |
| 7 | $4bb |
5,629 | 215 | bake/burn, ink … erase, scroll vectors, blur |
| 8 | $wib |
5,424 | 11 | (wipe blue) |
| 9 | $39i |
5,332 | 275 | flood, circle, timed zoom/blur/contrast, multi-statement |
| 10 | $nsh |
5,326 | 7 | kidlisp (bare identifier) |
Suggested phasing for a new port #
- $bop · $wib · $4xa — bare color → wipe, bare commands,
(wipe color),blur N - $pie · $39i —
(fps N), timing tokens, magic vars (w/h/width/height/frame),scroll,flood,circle,zoom,contrast - $roz · $ceo —
fade:gradients with:frameanimation,spin,coat,?/...cycle → claimsRBP-26 - $cow —
$codeembed (recursive sub-region eval + network/cache fetch) - $4bb —
bake/burn(offscreen page semantics, Decree '26 §6)
A port hitting phase 3 can publish KidLisp Decree '26: Core + Render + RBP-26.
5. Adding a New Runtime #
- Pick a path. Sibling-of-monorepo (
kidlisp-foo/) for hardware/platform ports; embedded inside a host app (slab/menuband/,fedac/native/cl/) for ports tied to a specific runtime. - Add a row to §3 above with
claim = unclaimed,status = not started. - Build through the §4 phases. After each phase, render the corpus and diff against reference frames.
- When all
RBP-26tokens render correctly, update the row to'26: Core + Render + RBP-26. - Conformance test artifacts (frame PNGs, diff reports) should land under
kidlisp/conformance/<runtime>/.
6. Open Questions #
kidlisp/tools/vskidlisp-tools/— two tool homes; the sibling should probably absorb the sub-dir or vice versa. Not urgent, but document the decision when made.- Physical reorg — should the reference impl be re-homed under
kidlisp/and re-exported fromsystem/public/aesthetic.computer/lib/? Conceptually cleaner, but the blast radius (service worker cache keys, bundler resolution, WebSocket module loader prefetch, everydisk.mjsimport path) hasn't earned its cost. Decision: keepkidlisp.mjswhere it is;kidlisp/is the house (spec, corpus, docs, registry), not the runtime location. KDL-26test suite — the Decree §10 reserves this name for the formal conformance suite. Land the corpus in §4 here, then graduate it toKDL-26once stable.- Sibling consolidation —
kidlisp-knowledge/andkidlisp/docs/overlap; resolve before they drift further.
7. Pointers #
- Decree '26:
docs/core/kidlisp-decree-26.md - Language reference:
docs/core/language-reference.md - API map:
COMPLETE_API_MAP.md - Directory map:
STRUCTURE.md - Top-level project score:
../SCORE.md
8. High-level assembly direction (proposal) #
KidLisp source is a compact, human-editable instruction language for a visual computer. A compiler can lower its expressions into an execution plan with explicit values, resources, effects, and update dependencies. Programs retain their source and meaning across hosts; each host implements the same operations using its own renderer and media system.
This is an optimization direction, not a new Decree conformance claim or a replacement compiler already implemented across the language. The existing WASM compiler and JS precompile paths are precedents to consult before adding a shared intermediate representation.
Execution contract #
| Stage | Responsibility |
|---|---|
| Parse | Source locations and canonical syntax; preserve inspectable source |
| Resolve | Bind operations and variables to known operations and value slots |
| Lower | Record pure calculations, ordered effects, resources, and dependencies |
| Prepare | Load data and build reusable layouts, buffers, and input regions |
| Update | Recompute values whose inputs changed; execute required effects in source order |
| Host | Draw, play media, and deliver input without changing language semantics |
An operation records its inputs, result shape, effect class, dependencies, and host capability. Constant arithmetic may fold; stable text may lay out once; viewport expressions update on resize; media bindings update from the media clock. Clock, frame, random, ink, page, timers, input, and network operations have distinct dependencies. Unknown operations keep the reference evaluator path until their behavior has an explicit contract.
Optimization must preserve evaluation order, random consumption, timer behavior, mutable graphics state, errors, and lifecycle cleanup. A drawing or random effect cannot disappear because its arguments stayed constant. Fetching data cannot execute source. Unsupported host capabilities must be discoverable and fail explicitly. Future compiled plans should be versioned and inspectable alongside the original source, with stable operation identifiers and source mappings.
First example: a prepared reader #
(wipe black)
(def episode (fetch "episode.json"))
(flow (listen episode))
The local JS prototype lowers the episode into cached text lines, link regions,
and positioned word fragments. It validates canonical prose and ordered cues
once per loaded resource. A viewport change rebuilds geometry; an audio-clock
update selects a cue by binary search and paints visible lines. Resource records
are immutable after loading: replace the record to change its contents. Generic
flow expressions still compare their values so dynamic prose keeps working.
The reader uses a specialized execution plan. The local numeric-v1 compiler
now also lowers an audited arithmetic subset into constant, input-slot, and call
instructions; it is available explicitly and does not replace reference
evaluation. fetch, get, listen, and rich-text forms are local JS extensions;
other runtimes have not claimed them.
Performance evidence and gates #
Run node kidlisp/tools/bench-rich-text.mjs [path-to-rich-text-module] for a
repeatable synthetic reader benchmark. On Neo, an initial before/after sample
put 295-word steady-frame bookkeeping at approximately 7 μs / 1 μs; a 10,000-word
sample was approximately 77 μs / 1 μs. Preparation became more expensive because
it builds the word geometry up front. These figures exclude glyph rasterization,
the KidLisp interpreter, audio decoding, and GPU presentation. They establish a
specific optimization, not total frame latency or a device-wide speed claim.
A five-second headless Chrome sample of the packed reader at 990 × 270 while playing narration measured 0.599 seconds of main-thread task time (0.469 seconds of script time). That covers the packed host as well as the reader; it excludes startup, other browser processes, and GPU/audio work. Playback, pause, seek, and the highlighted render were checked separately. This is one desktop sample, not a mobile or frame-rate guarantee.
A compiler optimization needs semantic differential tests and rendered evidence under fixed input, clock, and random seeds. Measure preparation time, steady frame median and tail latency, allocation/GC, memory, audio clock lag, and dropped frames separately. Test representative pieces and long resources on intended hosts. Keep the current corpus oracle for deployment regression checks; its noise-tolerant images cannot establish exact compiler equivalence by themselves.
9. Engineering constraints #
These are the rules for growing KidLisp. Existing paths that do not yet meet a rule need an explicit limitation and a migration test; an optimization does not establish a new language behavior merely by being faster.
- Preserve meaning. Changes to evaluation order, numeric edge cases, random consumption, timers, graphics state, or lifecycle are language changes. Optimizations need differential tests against the reference evaluator.
- Make execution reproducible. Conformance profiles declare their clock, seed, input stream, viewport, resources, and host capabilities. State belongs to a runtime instance; tests must not patch global time or randomness.
- Declare instruction contracts. Audited operations specify stable IDs, arguments, results, effects, dependencies, and supported profiles. Tooling derives its metadata from that registry. Unknown effects stay unoptimized.
- Bound work and ownership. Nested evaluation shares a work budget; depth, source size, memory, caches, requests, and media have explicit limits and owners. Leaving a piece disposes its resources. Exhaustion must be actionable and unwind cleanly.
- Make measurement observational. Enabling a profiler must preserve program behavior. Report preparation, execution, rendering, allocation, memory, and slow-frame results separately, with the host and workload specified.
- Preserve inspectability and portability. Keep canonical source and content, source mappings, versioned plans, declared capabilities, and pinned assets. An unsupported host capability must fail explicitly.
Implemented foundation (local, opt-in) #
The JS reference accepts new KidLisp({ execution }), where execution is a
KidLispExecution from lib/kidlisp-execution.mjs. The host calls
execution.beginFrame(frame) once before that frame's inputs and evaluation.
The context supplies a uint32 seed, epoch, frame duration, and shared work/depth
ledger. Embedded instances derive labeled seeds and inherit that ledger. Source
parsing is capped at one million characters and the selected nesting depth.
Budget failures include a code, frame, work count, and operation; failed frames
remain failed until the host begins the next frame. Function scope is unwound.
kidlisp/conformance/replay.mjs exposes the bounded commands-v1 fixture runner.
lib/kidlisp-ops.mjs owns eight audited numeric contracts and their aliases;
node kidlisp/tools/operations.mjs emits their versioned JSON manifest.
lib/kidlisp-plan.mjs exposes compileNumeric(expression, { bindings, fold })
and runNumeric(plan, inputs, execution?). Plans carry source AST paths, explicit
input slots, and numeric encoding that survives JSON even for -0, NaN, and
infinities. Compilation has a node/depth budget. Plans contain data and execute
without dynamic JavaScript generation. Effects and undeclared bindings are
rejected. This numeric ABI is experimental, not a ratified Decree guarantee.
Controlled evaluation bypasses the legacy profiler-dependent arithmetic cache and diagnostic early-stop heuristic so monitoring is observational in this profile. Default browser execution and its existing profiler paths have not been migrated. The work ledger measures evaluator/plan work; host rasterization, buffer allocation, network, and media still need their own resource budgets. Command replay does not establish pixel conformance or complete media replay. The registry covers the audited numeric subset; migrating the remaining instructions and generated editor/reference documentation is subsequent work.
kidlisp/conformance/pixels.mjs check now provides exact pixels-v1 CPU renders
through the reference module lifecycle and real software rasterizer. Five pinned
fixtures check every RGBA byte, including alpha, against reviewed PNGs and a
second isolated run. It rejects unsupported capabilities, stale goldens, and
swallowed rendering errors. Its first failure exposed boot-time color detection
executing arbitrary first operations; detection now consults registered colors.
The profile's fixed simulation cadence, bounds, and exclusions are specified in
conformance/README.md; it does not claim full browser or GPU conformance.
lib/kidlisp-plan-wasm.mjs compiles the eight numeric-v1 operations to native
f64 Wasm, retaining reference division, remainder, rounding, NaN, and signed-zero
behavior. It imports only pure remainder when needed, validates inputs, and
charges the supplied execution ledger before running. It is an explicit backend,
not the default evaluator. The older f32 compiler remains a separate experiment.
kidlisp/benchmarks/ray-sphere.lisp is a first rendering-kernel workload: three
spheres, a checker floor, hard shadows, and two reflection bounces. The benchmark
checks exact frames across reference evaluation, numeric plans, Wasm, and direct
JS. It reports preparation, median and p95 whole CPU frame time, resolution,
ray/intersection counts, host, and hashes. JS still owns scene traversal, shading,
and the pixel loop. Include that boundary cost; do not call kernel timing full
runtime performance or promise photorealism from this scene. Compile larger
batches only after measuring this baseline and preserving its pixels.
The next benchmark stage now includes a whole-frame f64 Wasm renderer and an f32 WebGPU renderer. Both embed the same audited numeric plan's ray kernel; their scene/shading hosts are still handwritten. Wasm runs one frame with no host imports, fixed memory, and a bounded reflection stack. GPU compute writes directly to a persistent texture and presents without pixel readback. The preview has capability/device-loss fallback to frame Wasm. CPU tests require exact pixels; the documented GPU profile uses bounded color-error tolerances. Measure completed GPU work and presentation separately from submission; browser timestamp quantization can produce zero for short dispatches. See the conformance README for build hashes, benchmark commands, scope and numerical limits.
kidlisp/graph/ adds the pinned roz-feedback-v1 experiment. The reference
evaluator parses $roz once and resolves seeded/timed controls each frame.
Ordered line, spin, zoom, contrast, scroll and circle nodes operate on two reused
GPU buffers. Fixed transform gather maps come from the real CPU rasterizer;
integer arithmetic and blend lookup tables retain its pixel quirks. Preparation
has a 512 × 512 limit; frames have at most six nodes and a shared evaluator work
budget. Unknown source and unsupported command parameters fail explicitly.
No model inference or shader recompilation occurs during animation.
The preview displays the source’s own 2D image. A fixed-step accumulator keeps
60 simulation updates per second independently of presentation cadence. Each
GPU submission can contain up to four ordered updates, with at most two
submissions queued. Normal animation does not wait for a GPU fence; diagnostic
runs await completion separately. GPU failure restarts the seeded CPU canvas.
The browser gate checks exact single/batched/queued pixels, wall-clock cadence,
pause/reset/resize and device loss. This controlled host is not a full browser
lifecycle or RBP-26 conformance claim. Commands and limits are documented in
conformance/README.md. A backend preview must display the authored source;
additional geometry belongs in a separate explicitly authored example.
For live audio, the intended host is AudioWorklet with bounded Wasm DSP blocks. GPU processing is a separate option for buffered/offline workloads; audio's render thread must not wait on the graphics queue. Moving evaluator traversal or compilation to Wasm requires its own representation and benchmark; whole-frame numeric rendering speed does not establish a speedup for object-heavy AST work.
Compilation direction beyond the benchmark #
Compile source and plans when source changes; reuse prepared code, resources, and layouts while frame inputs change. Runtime execution requires no model inference. Counted loops should stay inside the compiled backend, with numeric slots and reused buffers. Hoist only proven pure expressions with stable inputs; retain ordered drawing, random consumption, clock reads and errors.
Future tail-call support must include mutual tail calls with bounded host stack use; lower them to frame reuse, jumps or a trampoline. Other recursion needs explicit call frames and a shared work budget. Nested lists/records need a general value representation and ownership/collection rules; specialize known numeric shapes into packed layouts without silently changing aliasing or mutation. GPU kernels require statically bounded layouts. These are design constraints, not features implemented by the current numeric plan compiler.
Required next gates: fonts/media/GPU in controlled pixel profiles; host memory/resource ownership; the remaining instruction contracts; then effectful compiler lowering. Keep the browser corpus gate alongside deterministic checks until its resources and frame delivery are controlled end to end.