Home /Modules/impl/README.md

README.md

impl/README.md · 495 line(s) · markdown

<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 .sleela file 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). ".sleela file", "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:

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:

FeatureNotes
Classesclass Name { ... }; methods are flattened into core funcs
Typesint, double, boolean, String, void (parsed; core is dynamic)
Methodsparams, recursion, calls; main() is the entry point
Localsint x = ...; typed declarations
Control flowif / else, while, for
Operators+ - * / %, == != < <= > >=, && || !, unary -
Stringsliterals with escapes; + concatenates (Java-style)
I/Oprint(expr) built-in
returnwith or without a value
Fieldsclass-level int total = 0; — shared state (compile to globals)
Threadingspawn(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-inMeaning
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-inMeaning
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

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 under src/ 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:

  1. Depth — the relevant system depth is 3024: the maximum nesting/reachability from System to any leaf object (SHEET.sheet → system.depth; the DepthLimit congrain).
  2. Connectivity — up to 3024 congruent-linear systems may be connected (system.congruent-linear-systems-max).
  3. Complexity degree — the connection order between systems must be ≤ 4 (system.complexity-degree-max; the ComplexityDegree congrain). Degrees: 1 direct · 2 mediated · 3 brokered · 4 federated.
  4. The connect rule — connect(n) is permitted iff n ≤ 3024 and degree(topology) ≤ 4. These are surfaced in Sleela as sysdepth() (3024) and degreemax() (4).

Article II — Congrains grouping (the binding constraints)

In SHEET.sheet order (section congrains):

#ConstraintOrdinance
1Invarianta condition that must always hold for an object
2Preconditionwhat must be true before an operation runs
3Postconditionwhat the operation promises afterward
4Constrainta restriction on legal object states/relations
5Dependencya binding one object has on another (co-grained)
6Couplingstrength of inter-object binding (keep it loose)
7Congruencestructural sameness enabling congruent-linear connection
8Contractthe bundle of congrains an object honors

Article III — Limits grouping (the bounding constraints)

In SHEET.sheet order (section limits):

#LimitOrdinance
1Boundan inclusive/exclusive extent on a value
2Quotaa permitted amount over a scope/time
3RateLimitcap on operations per unit time
4Timeouta limit on how long an operation may take
5Capacitythe maximum a container/resource may hold
6Thresholda boundary value that changes behavior when crossed
7DepthLimitmaximum reachable depth — here the System depth is 3024
8ComplexityDegreethe 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:

MetricConstraint
Watchdogno line of execution is stalled (heartbeat within its Timeout)
Monitorobserved metrics stay within their Thresholds
Throughputwork completed per unit time stays above its floor
Capacityno Resource exceeds its Capacity / high-water mark
Exceptionunhandled 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:

MetricConstraint
Insightevery conducted object resolves an insight(...) (a known gloss)
Congruencerelated objects route(...) to a known congruence (no dead ends)
Couplinginter-object coupling stays loose (Article II·6)
Contracteach object's pre/post/invariant Contract is stated
Optimizationa 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.