Nickel keymap-ncl-to-json is too slow; explore native lowering to keymap.json

[rgoulter]

Below was from an exploration with an LLM investigating which part is slow in the current compilation process.

Key summary

Using Nickel for the keymap-ncl-to-json compilation pass is too slow for complex keymaps.

• We'll still keep keymap.ncl for authoring keymaps.
• Treat keymap.json as the stable IR.
• Explore native lowering to that IR.
• JSON → Rust source codegen (keymap-codegen) is comparatively cheap and can stay in Nickel for now.

Product constraints

Layer	Decision	Why
keymap.ncl authoring + contracts	Keep (must)	Preferred authoring surface; contract validation belongs with authoring
Dense keymap.json	Keep as stable IR	Real API: serde / Cucumber / full-profile Vec system already consume it
ncl → json passes in Nickel	Too slow; explore native	~10s on rich maps; tiny IR; interpreter tax
json → rust codegen in Nickel	Defer rewrite	~1s; not the bottleneck; fak/kirei lineage still works

Measurements (casual wall-clock)

Casual profiling only (time around nickel export / existing scripts). Nickel 1.16 has no built-in profiler. Each --field export is a cold process. (Although I'd note: the full integration test suite is affected by cold processes). Order-of-magnitude; local machine (M4 Macbook Air) measured on 2026-07-26.

(tests/ncl/keymap-36key-rgoulter is my keymap; relatively sophisticated. Miryoku-ish, with some chording).

Fixture focus: tests/ncl/keymap-36key-rgoulter (real-ish layered map: 36 keys, ~28 KB JSON — not a large IR).

Stage	What	Wall
Binary start	nickel --version	~4 ms
Load / surface only	--field=layers (almost no passes)	~1.0–1.3 s
Full ncl → json	keymap-ncl-to-json.sh / --field=json_keymap	~10 s (rich 36-key)
json → rust	keymap-codegen.sh	~1.2 s
Simpler maps ncl → json	e.g. 2-key named / 48-key basic	~1–2.5 s

Stage walk (36-key rgoulter; cold export per field; Δ ≈ new work after shared load):

Forced field	Wall	Approx marginal
layers	~1.5 s	load + author surface
layered_keys / chorded_keys	~1.6–2.3 s	early passes
automation_transform	~4.2 s	+automation
json_keymap	~10 s	+~6 s named-layers, pad, to_json_value

Reading: startup is negligible. A large fixed cost (~1s) is loading/evaluating the Nickel program graph. Variable cost scales with keymap richness, not raw key count alone (48-key basic ~2.3s vs 36-key rich ~10s). The bulk of the expensive path sits after automation_transform, inside json_keymap.

This is not “slow because the problem instance is huge.” Same logical work in a native language on a 36-node IR should be milliseconds-class; Nickel pays large constant factors (interpreter, contracts, repeated tree walks, dynamic key-module dispatch, record/array updates).

Target shape

keymap.ncl  --[Nickel: author + contracts; stop before heavy passes]-->  handoff
            --[native: lower to dense keymap.json]--------------------->  keymap.json
            --[Nickel or later Rust: codegen]-------------------------->  keymap.rs
                 ~1 s?                         ~ms–tens of ms              ~1 s

A product budget of ~1s Nickel + cheap native lower + ~1s codegen is reasonable for keymap/firmware builds once the hot passes leave Nickel.

Methodology (repro)

time ncl/scripts/keymap-ncl-to-json.sh tests/ncl/keymap-36key-rgoulter
time ncl/scripts/keymap-codegen.sh tests/ncl/keymap-36key-rgoulter

for f in layers layers_of_keys layered_keys chorded_keys \
         automation_transform json_keymap; do
  echo -n "$f  "
  time nickel export --format=json \
    --import-path=ncl --import-path=tests/ncl/keymap-36key-rgoulter \
    keymap-ncl-to-json.ncl keymap.ncl --field="$f" >/dev/null
done

Optional: add temporary exportable intermediates inside json_keymap (post–named-layers, post-pad, post–to_json_value) to split the ~6s tail further.

Recommended exploration

Spike (primary): Nickel keeps authoring + contracts; export a handoff IR; Rust lowers to dense keymap.json with snapshot parity against tests/ncl/**/keymap.json.

Related paths

• Frontend: ncl/keymap-ncl-to-json.ncl, ncl/passes/*
• Backend: ncl/keymap-codegen.ncl, ncl/key_system/
• Scripts: ncl/scripts/keymap-ncl-to-json.sh, keymap-codegen.sh
• Helper (combined eval): smart-keymap-nickel-helper
• Local write-up: notes/nickel-compiler-passes-perf.org

Discussion: Nickel used for three roles

Nickel currently does three jobs that got conflated:

1. Authoring DSL — keep.
2. Compiler frontend (ncl → dense JSON) — too slow; main target.
3. Compiler backend (JSON → Rust source) — acceptable cost; defer.

(1) and (2) sharing a language was interesting and coherent with fak/kirei; measurements say (2) is not worth keeping in Nickel long-term if multi-second (or 10s+) maps are normal.

[yannham]

Hello! I am always looking for slow Nickel program to try to improve the interpreter (or the stdlib). If I understand correctly, tests/ncl/keymap-36key-rgoulter is taking around 10s to evaluate to JSON? Are there any specific options or can I just run the test as it is? Also note that sorting is currently embarrassingly slow (but this is being fixed! nickel-lang/nickel#2643), so if you're sorting a bunch of arrays often, it could also be the reason. I'll take a look at see if there's something hiding in here

[rgoulter]

Hi @yannham,

Yup. Indeed, you can just run from repo root:

nickel export --format=json \
          --import-path=ncl --import-path=tests/ncl/keymap-36key-rgoulter \
          keymap-ncl-to-json.ncl keymap.ncl --field=json_keymap

and on my M4 MacBook Air, this takes around 10s.

Just to give a bit more context about what this repo is doing & what it's trying to do with Nickel:

• Overall, the project: use Nickel to author keymap definitions.
• The Nickel configuration input is used to output a copious amount of Rust source code. (This is more/less what the 36key-rgoulter test ncl is used to output).
• The input keymap.ncl gets transformed with a frontend (keymap-ncl-to-json.ncl) to a keymap.json, where the json can be used for Serde values, as well as used for the Rust source codegen (keymap-codegen.ncl).
• Per the "Measurements" section in the top comment, the frontend step takes 10s itself.
• The 'Stage walk' comment in the OP tries digging into that: if I understand correctly, it involves several 'tree walks' where each tree walk / transformation takes a couple of seconds. (The comment says "6s", but locally I'd asked LLM coding agent to break that 6s up further).

Disclaiming LLM use:

• I've had the LLM make refactoring to the ncl/keymap-ncl-to-json (factoring it into passes), as well as the ncl/key_system stuff. I did review these to check that the code was more/less in line with how I'd expect it to be. So, it's not thoughtless slop. :)