<img align="right" src="https://github.com/mearvk/SLeeLa/blob/master/images/debian/debian-logo.png" width="75" height="75" alt="SLeeLa">
<img src="https://github.com/mearvk/SLeeLa/blob/master/images/sleela/sleela-logo-004.jpg" alt="SLeeLa">
Sleela
Sleela is a small, Java-like programming language that runs on top of a
purpose-built C/C++ execution core. The core is a Turing-complete,
stack-based bytecode virtual machine with a stable C ABI. The Sleela language
sits above the core and drives it entirely through the core's single dispatch
entry point — the exchange function (slcore_exchange). Sleela source is
never interpreted directly: it is lexed, parsed, and compiled down to core
bytecode, then executed by the C/C++ engine underneath.
Wrapper™ — the name of the
.sleelafile type. A Wrapper™ is a Sleela source file: the program unit that carries the metadocument addend (it is governed by the Sleela Language Metadocument, SL-META-0001). ".sleelafile", "Sleela source file", and "Wrapper™" are used interchangeably below.
Sleela source — a Wrapper™ (.sleela)
|
v
[ Sleela front end — C++ ]
lexer -> parser -> AST -> compiler
|
| emits opcodes + drives the core via the exchange API
v
[ Sleela Core — C, stable ABI ]
value model | operand stack | call frames | opcode dispatch loop
---- slcore_exchange(): the executable "exchange" API ----
Why this shape
The request was for a C/C++-backed interpreter where the C/C++ layer provides a complete, Turing-responsible execution API (an "exchange" function), and the Sleela language sits above it and calls that exchange function. That is exactly the boundary here:
- The core (
core/) knows nothing about Sleela. It is an embeddable VM that understands opcodes and values. Everything an embedder needs — assembling a program and running it — is reachable through the one symbolslcore_exchange(). (Typed builder helpers such asslvm_emitare thin convenience wrappers over that same dispatch.) - The language (
frontend/) is a compiler front end. It turns Java-like source into core bytecode and hands it to the core.
Any language could target this core; Sleela is the first.
Building
Requires a C11 compiler and a C++17 compiler. The HTTP/2 server is built from
the committed include/nghttp2-1.70.0.zip: the Makefile unpacks it under
build/, compiles it into a static libnghttp2.a, and links that directly, so
no system-installed libnghttp2 (or -lnghttp2) is required. unzip must be
available on the build host.
Linux (POSIX):
cd impl
make # produces build/sleela
macOS (Darwin, Apple clang): the same POSIX backend of the abstraction
layer builds natively with clang. Use the helper script (from the repo root) or
plain make:
./scripts/build-macos.sh # clang; installs to /usr/local/bin
# or, in-tree only:
cd impl && make CC=clang CXX=clang++ # -> build/sleela
The Makefile detects Darwin via uname -s and drops -ldl (dlopen is in
libSystem on macOS); -pthread and clock_gettime work as-is. The runtime
reports its backend as macos (e.g. path_platform_smoke prints
paths/filesystem platform: macos). macOS builds are exercised in CI by
.github/workflows/build-macos.yml.
Windows 10+ (MinGW-w64): the core is OS-neutral — threads, TCP sockets,
files, pipes/named-pipes, paths, terminals, dynamic libraries and time all go
through the OS-aware layer in core/ (sleela_thread/net/io/path/
terminal/library/time), which has a complete Win32 backend (Win32
threads + CONDITION_VARIABLE, Winsock2, CreateFile/CreatePipe/named
pipes, LoadLibrary, ConPTY, QueryPerformanceCounter). Build it with the
MinGW toolchain via the helper script (from the repo root):
powershell -ExecutionPolicy Bypass -File build-windows.ps1 # -> impl\build\sleela.exe
The GNU Makefile detects Windows (OS=Windows_NT) and automatically links
Winsock (-lws2_32), drops -ldl/-pthread, and appends the .exe suffix.
MSVC is not supported (the pthread compatibility shim uses GCC's
#include_next); use MinGW-w64. Windows builds are exercised in CI by
.github/workflows/build-windows.yml.
Running
./build/sleela run examples/hello.sleela # run a Wrapper™ (.sleela file)
./build/sleela check examples/hello.sleela # validate (incl. #sleela version), don't run
./build/sleela version # version + supported .sleela syntax range
make test # runs every example under examples/ (incl. version tests)
Version awareness (SL-META-0001 §4.4)
The compiler is version aware. A Wrapper™ declares its syntax version with a
#sleela MAJOR.MINOR pragma on the first non-blank, non-comment line:
#sleela 1.0
class Hello { void main() { print("Hello, Sleela!"); } }
The compiler rejects any file whose declared version is outside its
supported range (shown by sleela version, currently 1.0 .. 3.1); a file with
no pragma is accepted with a warning and assumed to be the floor version. The
supported range is defined in frontend/version.h. The current
normative language grammar is ../SLEELA.syntax, syntax version
3.0. Syntax 2.7 adds the signed wide-integer family (int32 through
int16777216); syntax 2.8 adds the matching unsigned family (uint32 through
uint16777216); syntax 2.9 adds @mix consequent fields (multiple same-named
fields understood as one indexed group, top-down 1,2,3,… or manual
@mix(1,2,3,...) whose count must match the group). See
../markdown/SOURCE.md for the type-signature contract.
The language (first pass)
Sleela looks like a small Java. A program is one or more classes; execution
starts at main().
class Factorial {
int fact(int n) {
if (n <= 1) {
return 1;
}
return n * fact(n - 1);
}
void main() {
int i = 1;
while (i <= 10) {
print("fact(" + i + ") = " + fact(i));
i = i + 1;
}
}
}
Supported today:
| Feature | Notes |
|---|---|
| Classes | class Name { ... }; methods are flattened into core funcs |
| Types | int, double, boolean, String, void (parsed; core is dynamic) |
| Methods | params, recursion, calls; main() is the entry point |
| Locals | int x = ...; typed declarations |
| Control flow | if / else, while, for |
| Operators | + - * / %, == != < <= > >=, && || !, unary - |
| Strings | literals with escapes; + concatenates (Java-style) |
| I/O | print(expr) built-in |
return | with or without a value |
| Fields | class-level int total = 0; — shared state (compile to globals) |
| Threading | spawn(m), join(), lock(n)/unlock(n), send(slot,v)/recv(slot) |
See examples/ for hello, factorial, fibonacci, fizzbuzz, and
threads (spawns 8 workers, guards a shared field with a lock, and coordinates
via the 2-tuple mailbox).
Threading built-ins
The core ships a clean, bounded threading model (up to 128 threads); the Sleela surface exposes it as built-ins:
| Built-in | Meaning |
|---|---|
spawn(method) | run a no-arg method on a new thread; yields a thread id |
join() | wait for all spawned threads to finish |
lock(n)/unlock(n) | acquire/release lock-table slot n (a compile-time int) |
send(slot, value) | send the 2-tuple (slot, value) onto the mailbox line |
recv(slot) | block until a tuple arrives on slot; yields its value |
Class fields are shared across threads (they compile to the core's
thread-safe globals); method locals are per-thread. print output is
atomic per line. See DESIGN.md for the full model.
Conducted methods (SHEET.sheet)
Sleela draws its system-object vocabulary from ../SHEET.sheet,
the catalog of common system objects (129 objects across 16 role categories,
carrying the System root and its invariants — depth 3024, complexity
degree 4). These are conducted methods: sheet-backed grooves the compiler
resolves at compile time, giving a program method control, routing, and insight.
| Built-in | Meaning |
|---|---|
conduct("Name") | true if Name is a conducted (catalogued) method |
role("Name") | the object's conduct role (e.g. piping, smart-move) |
insight("Name") | the object's insight/gloss (an insight about the object/gain) |
congruent("A","B") | true if A and B route to a known congruence |
route("A","B") | "A -> B" when congruent, else "" (no route) |
sysdepth() | the relevant system depth (3024) |
degreemax() | the max complexity degree (4) |
class Conduct {
void main() {
print("depth " + sysdepth() + ", degree " + degreemax());
print(role("Pipeline")); // piping
print(insight("Reward")); // accrued value guiding ...
print(route("Pipeline", "Stream")); // Pipeline -> Stream
}
}
Run with the sheet located (via $SLEELA_SHEET or a nearby SHEET.sheet):
SLEELA_SHEET=../SHEET.sheet ./build/sleela run examples/conduct.sleela.
The catalog is parsed by the shared catalog/ module, which Nordshrift also
uses for its object-compatibility list.
The exchange API (core C ABI)
Declared in core/sleela_core.h. The whole core can be
driven through one symbol:
SLResult slcore_exchange(SLVM* vm, SLExchangeOp op, SLExchangeArg* arg);
SLExchangeOp selects the operation (reset, add-const, declare-global,
begin/end-func, emit, patch, set-entry, run, get-result); SLExchangeArg is the
tagged in/out packet. core/exchange_smoke.c assembles and runs
main() { print(6 * 7); } using only slcore_exchange — no builder helpers —
as a proof that the exchange function alone is sufficient to program the core.
Build and run that proof:
gcc -std=c11 -O2 core/exchange_smoke.c core/sleela_core.c -o /tmp/smoke && /tmp/smoke
# prints: 42
VM at a glance
- Value model (
SLValue): tagged union ofnull,int(int64),double,bool, and internedString. - Stack machine: operand stack, constant pool, globals, and call frames
(
CALL/RETwith a locals region per frame). Unbounded conditional jumps plus recursion make it Turing-complete. - Opcodes:
CONST/POP/DUP,LOADG/STOREG/LOADL/STOREL, arithmetic, comparisons, logic,JMP/JMPF,CALL/RET,PRINT,HALT.
Full details are in DESIGN.md.
Layout
impl/
core/ C/C++ execution core (the exchange API + VM)
sleela_core.h public C ABI
sleela_core.c stack VM + dispatch loop
exchange_smoke.c proof the core is drivable via slcore_exchange alone
frontend/ Sleela language layer (C++)
lexer.{h,cpp} Java-like tokenizer
ast.h AST nodes
parser.{h,cpp} recursive-descent parser
compiler.{h,cpp} AST -> core bytecode
version.{h,cpp} #sleela syntax-version awareness (SL-META-0001 §4.4)
driver.cpp the `sleela` CLI
subjects/ subject libraries (one folder per subject) — see subjects/README.md
native/ shared native dispatcher + AST builders (math/physics/economics)
native_api.{h,cpp} validate imports, enforce math dependency, dispatch, lower calls
native_builders.h shared inline AST-builder helpers (V/D/Bn/C0..M4)
native_add.h declarations for addMath/addPhysics/addEconomics
math/math_native.cpp addMath (__NativeMath class)
physics/physics_native.cpp addPhysics (__NativePhysics class)
economics/economics_native.cpp addEconomics (__NativeEconomics class)
chemistry/ chemistry library + frontend chemistry API + models
chemistry.{h,cpp}, chemistry_api.{h,cpp}, *.model
finance/ financial library + frontend financial API + model
financial.{h,cpp}, financial_api.{h,cpp}, FINANCIAL.model, README.md
examples/ sample Wrapper™ (.sleela) programs (incl. conduct.sleela)
catalog/ shared SHEET.sheet parser (conduct + object compat)
sheet_catalog.{h,cpp} Catalog model: objects, roles, congruence, invariants
nordshrift/ Nordshrift: the .sst transpiler driver (NS-SST-0001)
sst_lexer/parser, sheet_model, source_resolve, sleela_emit,
object_compat (compatibility list + relevance), nordshrift CLI
Makefile
DESIGN.md
README.md
Note on the repository. This
impl/tree is the current C/C++-backed implementation. The older 2019 Java "Nordshrift" exploration remains undersrc/as project history and is untouched.
Nordshrift (the .sst transpiler driver)
Layered on top of Sleela is Nordshrift — the transpiler driver defined by
the normative spec NS-SST-0001 (/SST.model). It reads a .sst control
sheet (indentation-significant, pragma-first) that names Sleela source files
and selects a target, (each a Wrapper™) then drives their transpilation into the triplet —
Java, Sleela (executed on the C core here), or C — chosen by the
sheet's target-language directive.
./build/nordshrift check nordshrift/examples/demo/build.sst # validate; NSS-* diagnostics
./build/nordshrift build nordshrift/examples/demo/build.sst # transpile + (sleela) run on core
Nordshrift also carries the ../SHEET.sheet objects in an
object compatibility list and converts each into a per-target relevance —
either direct (a concrete target construct, e.g. Thread -> pthread_t) or
model (an abstract role/pattern) — for eventual OS-executable compilation:
./build/nordshrift objects # the 129-object compatibility list
./build/nordshrift relevance --target=c Thread # direct -> pthread_t
./build/nordshrift relevance --target=java # whole-catalog table + direct/model tally
See nordshrift/README.md and
nordshrift/NORDSHRIFT.md.
The Constitution — ordained constraints, in order
This is the ordered constitution of governing constraints ("congrains") the
system honors. Every rule here is enforced or expressible today; each is drawn
from SHEET.sheet (the congrains and limits sections and the system
invariants) or from the NS-SST-0001 diagnostics. Constraints are organized into
named groupings. Two of the groupings — Health and IQ — are
system metric groupings (system health and system insight/quality); they
describe the software system's own condition, nothing about people.
Article I — System invariants (ordained, always in force)
In order of precedence:
- Depth — the relevant system depth is 3024: the maximum
nesting/reachability from
Systemto any leaf object (SHEET.sheet→system.depth; theDepthLimitcongrain). - Connectivity — up to 3024 congruent-linear systems may be connected
(
system.congruent-linear-systems-max). - Complexity degree — the connection order between systems must be ≤ 4
(
system.complexity-degree-max; theComplexityDegreecongrain). Degrees:1direct ·2mediated ·3brokered ·4federated. - The connect rule —
connect(n)is permitted iffn ≤ 3024anddegree(topology) ≤ 4. These are surfaced in Sleela assysdepth()(3024) anddegreemax()(4).
Article II — Congrains grouping (the binding constraints)
In SHEET.sheet order (section congrains):
| # | Constraint | Ordinance |
|---|---|---|
| 1 | Invariant | a condition that must always hold for an object |
| 2 | Precondition | what must be true before an operation runs |
| 3 | Postcondition | what the operation promises afterward |
| 4 | Constraint | a restriction on legal object states/relations |
| 5 | Dependency | a binding one object has on another (co-grained) |
| 6 | Coupling | strength of inter-object binding (keep it loose) |
| 7 | Congruence | structural sameness enabling congruent-linear connection |
| 8 | Contract | the bundle of congrains an object honors |
Article III — Limits grouping (the bounding constraints)
In SHEET.sheet order (section limits):
| # | Limit | Ordinance |
|---|---|---|
| 1 | Bound | an inclusive/exclusive extent on a value |
| 2 | Quota | a permitted amount over a scope/time |
| 3 | RateLimit | cap on operations per unit time |
| 4 | Timeout | a limit on how long an operation may take |
| 5 | Capacity | the maximum a container/resource may hold |
| 6 | Threshold | a boundary value that changes behavior when crossed |
| 7 | DepthLimit | maximum reachable depth — here the System depth is 3024 |
| 8 | ComplexityDegree | the connection order between systems — capped at 4 |
Article IV — Health grouping (system-health metrics)
System Health is the grouping of runtime-condition constraints the system
watches (drawn from the catalog's attention and gain roles). A system is
healthy while all hold:
| Metric | Constraint |
|---|---|
Watchdog | no line of execution is stalled (heartbeat within its Timeout) |
Monitor | observed metrics stay within their Thresholds |
Throughput | work completed per unit time stays above its floor |
Capacity | no Resource exceeds its Capacity / high-water mark |
Exception | unhandled exceptions do not cross a system boundary |
Article V — IQ grouping (system insight / quality)
System IQ is the grouping of insight/quality constraints — how well the
system understands and expresses itself (drawn from the gain and
congruence roles and Sleela's conducted-method insights). Higher IQ = more of
these satisfied:
| Metric | Constraint |
|---|---|
Insight | every conducted object resolves an insight(...) (a known gloss) |
Congruence | related objects route(...) to a known congruence (no dead ends) |
Coupling | inter-object coupling stays loose (Article II·6) |
Contract | each object's pre/post/invariant Contract is stated |
Optimization | a defined objective (gain) is being measured and improved |
Query these from Sleela via the conducted methods (insight, role,
congruent, route, sysdepth, degreemax) and from Nordshrift via
nordshrift objects / nordshrift relevance.
Status
Version 0.1.2 (see ../VERSION.md for the full version record —
toolchain, language syntax, Nordshrift, and the governing specs). A working
end-to-end pipeline (lex → parse → compile → execute on
the C core) with recursion, loops, arithmetic, strings, and I/O, and a
version-aware front end that enforces the #sleela syntax-version pragma
(SL-META-0001 §4.4) across both the sleela CLI and Nordshrift. Next
candidates: short-circuit &&/||, arrays, a REPL, and a static type checker
on top of the Java-like surface.
Corrections
The front end previously did not compile: parser.cpp constructed ~16 Java
statement/expression AST node types that were never declared in ast.h and were
not handled by semantic.cpp or compiler.cpp. Those nodes were added and
wired through the analyzer and the bytecode compiler, a latent Binary-operand
bug was fixed, and several build-blocking source/Makefile defects were repaired.
cd impl && make builds sleela and nordshrift, and make test passes every
target. See the 2026-10-03 entry in ../REVISIONS.md.
SLeeLa
<p align="center"><img src="images/sleela/sleela-wordmark.svg" alt="SLeeLa — The Now. The Ingredient." width="560"></p> <p align="center"><img src="https://github.com/mearvk/SLeeLa/blob/master/images/sleela-programming-language-002.jpg" alt="SLeeLa Marketing Logo" width="560"></p>
Current language edition
The normative SLeeLa language edition is 3.1. Sleela and Sleelvac share the
same native frontend and version resolver; both report and enforce source syntax
1.0–3.1. Nordshrift delegates to that resolver. Older source declarations
remain accepted, and historical feature gates (such as @mix at syntax 2.9)
remain in force. Tool release numbers are independent of the language edition.
Native Drive: bytecode-to-native dispatch
Syntax 3.0 exposes the host-authorized nativeOpen(path),
nativeCall(handle, method, ...args), and nativeClose(handle) built-ins.
The VM owns the generation-checked module handles and dispatches calls through
the separately versioned SLNativeValue scalar/UTF-8 contract. Internal
SLValue memory, arrays, structs, and VM handles are never passed to plugins.
When a native method reports SL_NATIVE_CALL_NOT_HANDLED, or its arguments
cannot be represented by the scalar ABI, the interpreter may dispatch a
same-name, same-arity SLeeLa bytecode method. Plugin failures and ABI mismatches
remain errors and do not trigger fallback. Plugins may optionally export
sl_native_bind_host to receive a versioned callback table and invoke an exact,
unique SLeeLa function from native code. The host must separately install
slvm_set_native_callback_authorizer; callback names are denied by default. Callback execution uses a nested VM
stack, preserves suspended GC roots, and rejects recursive native-module API
calls to avoid deadlocks.
The host must install slvm_set_native_authorizer before execution. With no
authorization callback, native module loading is denied. Native code runs in the
host process and is not sandboxed. See
os-level-support/loader/README.md
and the normative Native Drive syntax contract.
The focused VM bridge smoke test is opt-in and is not part of the default test aggregate:
make -C impl test-native-call
It builds a small typed plugin and exercises host-authorized module open, typed bytecode dispatch, NOT_HANDLED interpreter fallback, and close. This target has been added for local verification; no CI workflow is started by it.