{"id":50693922,"url":"https://github.com/pyrex41/shen-lua","last_synced_at":"2026-06-09T05:05:31.002Z","repository":{"id":363337511,"uuid":"1262855519","full_name":"pyrex41/shen-lua","owner":"pyrex41","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-08T13:45:19.000Z","size":181,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T14:16:23.883Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pyrex41.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-08T11:41:08.000Z","updated_at":"2026-06-08T13:46:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pyrex41/shen-lua","commit_stats":null,"previous_names":["pyrex41/shen-lua"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pyrex41/shen-lua","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fshen-lua","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fshen-lua/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fshen-lua/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fshen-lua/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyrex41","download_url":"https://codeload.github.com/pyrex41/shen-lua/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fshen-lua/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34092319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-09T05:05:30.113Z","updated_at":"2026-06-09T05:05:30.965Z","avatar_url":"https://github.com/pyrex41.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# shen-lua — a speed-focused LuaJIT port of the Shen kernel\n\n`shen-lua` runs the [Shen](http://shenlanguage.org) language on **LuaJIT 2.1**.\nShen programs compile down to **KLambda (Kλ)** — a small, untyped Lisp kernel of\n~46 primitives — and a \"port\" of Shen consists of (a) implementing those\nprimitives on a host runtime and (b) translating the kernel's `.kl` files into\nthat host. This port does both by **compiling KLambda to Lua source** that\nLuaJIT then trace-compiles to machine code.\n\nIt targets **Shen 41.1** (via the KLambda in `ShenOSKernel-41.1/klambda`).\nEarlier versions were certified against the Shen 22.4 kernel test suite.\n\n## Why a compiler (not an interpreter)\n\nThe design goal is speed, so the host backend is a **source-to-source compiler**,\nnot a tree-walker:\n\n* KLambda special forms (`if`, `cond`, `let`, `do`, `and`, `or`, `trap-error`,\n  `lambda`, `freeze`, `defun`, `type`) compile to **native Lua control flow**.\n* Tail positions emit real Lua `return`/`if`-`elseif` chains, so deep recursion\n  uses LuaJIT's **proper tail calls** (the kernel relies on TCO heavily).\n* Function application uses **currying-on-demand**: when the callee's arity is\n  statically known the call is a direct, exact-arity table call; otherwise a\n  generic `APP` builds and applies closures.\n* `type` is **erased** at the Kλ boundary (it is identity), per the porting spec —\n  the actual type *checking* is the kernel's own Shen code and runs unchanged.\n\n## Architecture\n\n| File | Lines | Role |\n|------|------:|------|\n| `runtime.lua`  | 213 | data representation, symbol interning, the KLambda reader |\n| `compiler.lua` | 365 | KLambda → Lua source compiler (statement-based codegen) |\n| `prims.lua`    | 325 | runtime env: the primitive set, apply/curry machinery, loader |\n| `boot.lua`     |  80 | wires up streams, platform globals, loads the 41.1 kernel `.kl` files, runs `shen.initialise` |\n\nData representation (chosen so hot paths stay trace-JIT-friendly):\n\n* numbers → Lua numbers; strings → Lua strings; KL `true`/`false` → Lua booleans\n* symbols → interned tables (identity `==`); `()` → a unique `NIL`\n* cons → `{h, t}` with a `Cons` metatable; vectors (absvector) → `{n=size, [0..n-1]}`\n* functions → Lua functions, arity tracked in a weak table; exceptions → tagged tables\n\n## Requirements\n\n* **LuaJIT 2.1** (Lua 5.1 semantics). On Debian/Ubuntu: `apt-get install luajit`.\n* Nothing else — the **Shen 41.1 KLambda sources** (`klambda/`) are vendored in this\n  repository for a self-contained clone-and-run experience. You can still point\n  `SHEN_KL_DIR` at an external checkout if you are working against a different\n  ShenOSKernel tree.\n\nNo build step is needed — the kernel is compiled from `.kl` to Lua **on boot**. \n\n## Running a program\n\n```sh\n# load and run a .shen file (the kernel reader handles full Shen syntax)\nLUA_PATH=\"/path/to/shen-lua/?.lua;;\" luajit run-shen.lua myprogram.shen\n```\n\nProgrammatically:\n\n```lua\nlocal P = require(\"boot\")\nP.load_kernel(false)   -- compile + load the 41.1 kernel (~21 .kl files incl. stlib)\nP.initialise()         -- (shen.initialise) — required before most kernel services work\n-- evaluate a Shen top-level form through the real pipeline:\nlocal R = require(\"runtime\")\nP.F[\"eval\"](R.read_all('(define square X -\u003e (* X X))')[1])\nprint(require(\"runtime\").to_str(P.F[\"square\"](9)))   -- 81\n```\n\n## Certification / Testing\n\nSee [41.1-STATUS.md](41.1-STATUS.md) for the current state of the 41.1 port,\nincluding what works, what is broken, and how to run the official test suite.\n\nThe port loads and initialises the full 41.1 kernel (including `stlib` and the new\nextensions). However, the test harness does not yet run successfully (see the status\ndoc for details and error symptoms).\n\nThe old `cert-22.4-result.txt` is historical only.\n\n## Benchmarks\n\nSee `BENCHMARKS.md` for the historical (Shen 22.4) report and LuaJIT trace analysis.\nThe numbers below are from that era; re-benchmarking against a current `shen-c` built\nfor 41.1 would be the fair comparison.\n\nHeadline versus the `shen-c` 0.2.3 interpreter on the **same machine** (22.4 baseline):\n\n* **fib** (compute-bound recursion): **66–79× faster**.\n* **n-queens** (functional, allocation-heavy): **~2.5× faster**; shen-c segfaults at\n  board 6 (no TCO), shen-lua completes it.\n* **Einstein's riddle** (Prolog backtracking, CPS + heavy allocation): **~1.5× slower** —\n  the one workload class where a low-constant-factor C interpreter wins. Honest analysis\n  in `BENCHMARKS.md`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyrex41%2Fshen-lua","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyrex41%2Fshen-lua","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyrex41%2Fshen-lua/lists"}