# SLeeLa 3.0 — Singapore (SG)


A native systems language, compiler, runtime, and virtual-machine ecosystem.

> **Singapore multilingual edition.** This file provides the complete English technical edition (sections I–XIX, mirroring the canonical README) together with introductions in Simplified Chinese, Bahasa Melayu and Tamil. Complete translations of the whole README into Simplified Chinese and Bahasa Melayu are maintained in [README.CN.md](README.CN.md) and [README.MY.md](README.MY.md); a complete Tamil translation is not yet available. Technical identifiers, source code, commands, filenames, links and API names are unchanged.
## Language editions
## English
SLeeLa is a native systems programming language, compiler, runtime, and virtual-machine ecosystem. It brings together the language, compiler, libraries, developer tools, and platform contracts needed to build and run software.
## 简体中文
SLeeLa 是一套原生系统编程语言、编译器、运行时和虚拟机生态系统。它将语言、编译器、函式库、开发工具及平台契约整合在一起,用于构建和运行软件。
## Bahasa Melayu
SLeeLa ialah bahasa pengaturcaraan sistem natif yang merangkumi pengkompil, persekitaran masa jalan dan ekosistem mesin maya. Bahasa, pengkompil, pustaka, alat pembangunan dan kontrak platformnya bekerjasama untuk membina serta menjalankan perisian.
## தமிழ்
SLeeLa என்பது ஒரு இயல்பான கணினி அமைப்பு நிரலாக்க மொழி; இதில் தொகுப்பி, இயக்கநேரச் சூழல் மற்றும் மெய்நிகர் இயந்திரச் சூழல் அடங்கும். மொழி, தொகுப்பி, நூலகங்கள், உருவாக்குநர் கருவிகள் மற்றும் தள ஒப்பந்தங்கள் இணைந்து மென்பொருளை உருவாக்கவும் இயக்கவும் உதவுகின்றன.
---
**The Now. The Ingredient.** A language is more than syntax: it is the compiler, runtime, libraries, tools, and platform contracts that make software usable.
**What SLeeLa is involved in.** SLeeLa is involved in **Math**, **Object**,
**Science**, and **Reach** — the four faces of its work: the calculable
(Math), the settled thing standing in the catalogue of what is (Object), the
disciplined study of the true (Science), and the extension of a system's hand
to other systems and people (Reach). **National Interests remain** — they are
not set aside by any of the four; where a subject bears on a nation's interest,
that standing is kept (recorded faithfully, e.g. in each class's Metadata
`metaOrigin` / `metaNationalSchedule`), never dissolved.
## I. Start Here
- [Build the native implementation](../../impl/README.md)
- [Virtual machines & Modium — hands-on user guide](../../virtual-machine/USER-GUIDE.md) (`sleela vm`, `sleela modium`)
- [CPU stack in SLeeLa source](../../lib/cpu/CPU.md) — a full gates→ALU→cores→OS→programs machine, a roster of 130+ CPU profiles, and adjustable [voltages, variable clocks, and expert timings](../../lib/cpu/TIMING.md) you can [run at spec and overclock](../../lib/cpu/components/README.md)
- [Documentation index](../../docs/README.md)
- [CSPML data source and Salt & Salary research reference](../reference/CSPML.DATA.SOURCE.AND.SALT-AND-SALARY.REFERENCE.md) — external U.S. place, socioeconomic, workforce, education, and public-school data provenance and integration guidance.
- [Generated API documentation](../../docs/api/README.md) — current HTML reference, versioned API edition, and regeneration instructions
- [API catalogue](../../api/README.md)
- [Computational comparison standards](../../comparison/README.md) — SLeeLa VM, Java/JVM, and native C/C++ type, memory, ABI, and conformance standards.
- [Recursion stanchion — C and C++ prototypes](../../recursion/stanchion/README.md) — primitive-specialized examples for Boolean, Byte, Character, Integer, Long, Float, and Double, alongside generic, applied, scientific, and teaching recursion patterns.
- [Platform support and validation matrix](../../docs/PLATFORM-SUPPORT.md)
- [Brand guide](../../docs/BRAND-GUIDE.md)
- [Merchandise concepts and assets](../../merchandise/README.md)
- [NitroWebExpress logo](../../images/nitro-web-express/nitrowebexpress-logo-004.jpeg)
- [Testing policy and release gates](../../markdown/TESTING.md)
## II. News
Recent additions to the language, drivers, and standard library:
- **The `advantage` standard-library package — advantaging a dividend, with
math, physics, integration, grading, and routable output.**
[`lib/advantage/`](../../lib/advantage/README.md) encapsulates *advantaging a
unique dividend with respect to a model* as a layered **Sequitur onion**
(dividend → review → concerns → maths → additions → subtraction → regrouping
→ iteration), navigable inward/outward with full dynamic update and
restitute, exposed through a simple **user's model** and a full-control
**developer's model**. It carries five subject areas: **`math/`** bilateral
trade economics (joint profit maximization, Nash bargaining, the bilateral
newsvendor critical ratio), **`physics/`** a structural-economics "physics of
trust fields" (trust as a metric tensor, the transactional geodesic, an
announcement contact structure, a CIR+jump trust-decay SDE — a modelling
analogy, flagged as such), **`integration/`** a recursively-composable
vertical-integration model for capitalism/retail (compartments, engineering
bays, trial compartments, newton median trays, and a system-sophistication
score), **`grading/`** a sophistication circuit grader that rates each module
and any set of winning/losing/grader/absolute modules A–D, and **`output/`**
a routable emit seam that sends module output to the terminal, a
**CommonRails**-formatted surface, or a socket/connector (framed for a native
`slnet_write`). Every class carries the Metadata-Class record; five runnable
demos validate the subjects, and the companion
[`DEFINITIONS.md`](../../lib/advantage/DEFINITIONS.md),
[`MATH.md`](../../lib/advantage/MATH.md), and
[`PHYSICS.md`](../../lib/advantage/PHYSICS.md) document them. A native C/C++
consumer under [`advantage/`](../../advantage/README.md) (the C core
`advantage_value`/`advantage_mean`, an XML knowledge store, a secure
HTTPS/SFTP/SSH acquisition + keystore + DH/ECDH transport library) links the
model into worked
[trade examples](../../advantage/examples/README.md) — positive trades from
presumed internet sources, an audience-relevance sequence (Traders,
Consumers, Helpers, Healers), and eight models ranked A–D (D = most Cement,
A = most Brand).
- **Loop-timing annotations — `@loopDelay` / `@loopBudget` (+ a `sleep(ms)`
built-in).** The first **statement-level, behavioral** annotations in SLeeLa:
written on their own line before a `for` / `while` / `do` loop, they insert a
real pause into the loop's execution. `@loopDelay(ms = 250)` /
`@loopDelay(seconds = 2)` sleeps a fixed amount per iteration (a bare
`@loopDelay(250)` defaults to milliseconds); `@loopBudget(seconds = 10,
iterations = 1000)` spreads a known iteration count evenly over a total
wall-clock budget. Both lower to the new append-only opcode **`OP_SLEEP`**
(ISA 157), which also backs a general **`sleep()`** built-in callable
anywhere; the pause is implemented portably (`nanosleep` / `Sleep`). Specified
in [`SLEELA.syntax` §32](../../SLEELA.syntax); API reference in
[`api/sleela/3.0/LOOP_TIMING_API.md`](../../api/sleela/3.0/LOOP_TIMING_API.md);
runnable
[`examples/loop-timing-annotation-demo.sleela`](../../examples/loop-timing-annotation-demo.sleela).
A session-additions index (including this, the native `OP_BIGMUL`
big-integer multiply, and the standalone **[local-generator](../../local-generator/README.md)**
and **[pi-generator](../../pi-generator/README.md)** tools) lives at
[`api/sleela/3.0/SESSION-ADDITIONS-API.md`](../../api/sleela/3.0/SESSION-ADDITIONS-API.md).
The three generated API surfaces
([`sleeladoc-api/`](../../sleeladoc-api/README.md),
[`docs/api/`](../../docs/api/README.md), and the immutable
[`api/sleela/3.0/version-014/`](../../api/sleela/3.0/version-014/index.html)
snapshot) were rebuilt with `make api-docs` and now carry the new `SLISASleep`
/ `SLISABigMul` instruction entries on their `vm` package page.
- **SleelaDoc from the command line — `sleela docs`.** SleelaDoc is now reachable
straight from the terminal. `sleela docs` lists every documentable topic;
`sleela docs crypto` shows a package; `sleela docs stringbuilder` resolves a
class (case-insensitively, and by the `SL` standard-library prefix →
`SLStringBuilder`) and prints a rich page — **definition, design purpose,
relationships, structure, user clays, and a five-rung mastery ladder** — with
ranked "did you mean" results for a near miss. Authors enrich any page simply
by adding SleelaDoc `@`-tags (`@intent`, `@thesis`, `@axiom`, `@param`,
`@see`, `@mastery`). `sleela docs --generate [dir]` writes a plain-text corpus
(one page per class + a `TOPICS.index`) that the CLI then reads offline;
**`make sleeladoc`** bundles that corpus **and the matching `.sleela` sources**
into `sleeladoc/build/sleeladoc.jar`. For facade-only subjects (e.g.
`psychiatry`, `politico`), `sleela docs --facade ` searches the
filesystem at runtime and lists the real **folders (then files, as natural
motion)**, bounded by user-overridable caps of **6 MB / 6000 files / 6
minutes**. The `lib/sleeladoc` units are maintained at the current edition,
**`#sleela 3.0`**. See [`man/man1/sleela.1`](../../man/man1/sleela.1) and
[`lib/sleeladoc/README.md`](../../lib/sleeladoc/README.md).
- **SleelaDoc — a Javadoc-style documentation solution, with a generated HTML
site.** **SleelaDoc** is SLeeLa's in-source doc-comment convention
(angle-bracket comments sentinelled with `@doc` / `@page`; see
[`manifesto/SLEELADOC.md`](../../manifesto/SLEELADOC.md)), and
[`lib/sleeladoc`](../../lib/sleeladoc/README.md) is the **extractor** that renders a
`.sleela` unit as a Markdown or HTML API page — the way `javadoc` renders Java,
documenting *intent*. A complete, browsable **HTML documentation site for the
entire `/lib`** is generated into [`/sleeladoc-api`](../../sleeladoc-api/README.md)
by `tools/generate-sleeladoc-api.py` (open `sleeladoc-api/index.html`; a clean
blue / light-blue / light-grey / white style with a package → class → member
hierarchy and a glossary written for the *Student 2* reader). The compiler also
emits author-marked doc outputs as a byproduct of compilation (`--wiki`
MediaWiki page + an originated source twin), documented in
[`manifesto/SLEELADOC.WIKI.md`](../../manifesto/SLEELADOC.WIKI.md). Runnable:
[`lib/sleeladoc/sleeladoc-demo.sleela`](../../lib/sleeladoc/sleeladoc-demo.sleela).
- **XML Document Object Model (`lib/xml`).** A SLeeLa-side XML DOM — a document
owning a tree of element/text/comment/CDATA/PI nodes with ordered children and
named attributes, a serializer (compact/pretty, XML 1.0 §2.4 escaping), a
char-cell parser, and the `SLXmlAspect` quality register. Node equality is a
three-rung tie of trust (identity → same subject → structure), reflexive,
symmetric, and deterministic. See [`lib/xml/README.md`](../../lib/xml/README.md) and
the runnable [`lib/xml/xml-dom.sleela`](../../lib/xml/xml-dom.sleela).
- **Wide signed integer primitives (`long`, `int64`, `int128`).** `int`, `long`,
and `int64` are all 64-bit signed integers that type-check and run identically;
`int128` is accepted as an integer type (64-bit-backed for now, with true
128-bit a documented follow-up). The base-2 signed series `int32`..`int16777216`
(syntax 2.7) and the matching unsigned series `uint32`..`uint16777216`
(syntax 2.8) extend this. See [`SLEELA.syntax`](../../SLEELA.syntax) §21, §24, §25.
- **`@mix` consequent fields (syntax 2.9).** A class may declare multiple
instance fields with the **same name** when each repeat carries `@mix`; the
language understands the group as consequent (an array / list keyed by index),
top-down `1,2,3,…` by default or manual via `@mix(1,2,3,...)` whose index
count must match the number of fields. See [`SLEELA.syntax`](../../SLEELA.syntax) §28.
- **Document markers — the Natural Process, titled the Preonems
(`author`/`authorial`, `material`, `memory`, `determine`, `object`, `field`).**
These bare document-marker words are collectively titled the **Preonems**
(one marker is a *Preonem*; the set, the *Preonems* — see
[`SLEELA.syntax`](../../SLEELA.syntax) §26.1). First-class, declarative-only
document markers naming what a document *is* in the order of making:
`author`/`authorial` (syntax 2.4; handled by professional council — the one
member with a behavioral effect), `material;` (settled Source) and `memory;`
(syntax 2.5), `determine;` (syntax 2.6; a document open to be processed
further by a doctor, physician, or ghost toward completion by legal hand),
and the two newest, **`object;`** (a settled thing standing in the catalogue
of what is — **reified, given concrete standing, at syntax 2.8**) and
**`field;`** (the ground of relation in which objects stand and move) —
both gated from syntax 2.6. Each is bare, contextual, and version-gated by the
front end with no effect on parsing, typing, or codegen; outside the marker
position every one stays an ordinary identifier (so `field` never disturbs a
class member or a `.field` access). See [`SLEELA.syntax`](../../SLEELA.syntax)
§18–§20, §23, and §26.
- **Nordshrift at syntax 3.0 with full library reach.** Nordshrift resolves
through the same recursive `/lib` index as the compiler, reaching every
package and `.sleela` unit; `nordshrift check` reports the whole-tree counts.
- **Recursion stanchion.** The [`recursion/stanchion/`](../../recursion/stanchion/README.md) directory now includes dedicated C and C++ reference prototypes for the seven documented primitive contracts, plus generic, applied, scientific, and teaching examples. These are reference sources; compile and test them before treating them as verified.
- **Angle-bracket comments (`<` / `<<`).** A new go-forward comment style —
`< line >` and `<< block >>` — lexed by the SLeeLa frontend and documented in
[`SLEELA.syntax`](../../SLEELA.syntax) §1.1.
- **Radix integer literals.** `int` literals now accept hexadecimal (`0x`),
binary (`0b`), and octal (`0o`) forms with `_` digit separators, in both the
SLeeLa source language ([`SLEELA.syntax`](../../SLEELA.syntax) §1.4) and the
[`.xlt` CPU-model format](../../lib/xlt/README.md).
- **The Metadata Class standard across the library.** The descriptive-metadata
metapattern (provenance, legality, jurisdictional scope) is now carried by
every class-bearing `.sleela` file under `/lib`; see
[`SLEELA.syntax`](../../SLEELA.syntax) §15 and
[the tutorial lesson](../../tutorial/13-metadata-class.md).
- **A richer text / String family.** `lib/text` gains real in-language helpers,
a char-cell view giving genuine `charAt`/`substring`/`indexOf`/`reverse`/
column-alignment, and a real positional templater — see the
[text & String tutorial](../../tutorial/14-text-and-strings.md) and the runnable
[`lib/text/text-string-demo.sleela`](../../lib/text/text-string-demo.sleela).
- **First-class `String` in Nordshrift sheets.** A `.sst` sheet can declare a
typed `strings:` block that contributes to the build's component manifest;
see the [Nordshrift Sheet Reference](../../wiki/Nordshrift-Sheet-Reference.md).
- **CPU models run by both opcodes and function-call equivalence.** Every
`SLCPU` inherits the basis of running a native instruction stream
through its fetch-decode-execute loop *and* running the code of an assumed
other process by equivalent calls on the shared VM substrate — see
[`lib/cpu/EXECUTION.md`](../../lib/cpu/EXECUTION.md) §5.
## III. Build and Test
**Prerequisites:** a C/C++ toolchain (GCC or Clang) and GNU Make; Python 3 for
the manifest/flow tooling; on Linux the X11/Xrandr development packages for the
display products (a module's `make deps` reports/installs what it needs). The
`impl/` build is fail-closed on a trusted SHA-256 manifest, which the root
`Makefile` points at automatically.
From a clean checkout, the quickest start:
```sh
make # build everything from the repo root
```
Or build and test just the native core:
```sh
make -C impl all # build the core compiler/runtime only
bash ./test-suites/run-all.sh --all # run the full test suite
```
The repo-root `make` builds every product (core, VM, codecs, churn,
antivirus, …) and ends by building the **registry** and materializing its
baseline table — so a built tree ships a reviewable registry out of the box.
The essential targets:
```sh
make # build everything (alias of `make all`; registry runs last)
make all # the same full build, named explicitly
sudo make install # install commands + runtime support (see §IV)
make clean # remove build outputs from every dispatched build system
make help # list every target the root Makefile provides
```
Other useful targets:
```sh
make registry # just the registry: build + materialize the table
./build-registry.sh # same thing, invoked directly
make tests # build and run the test suite
make ballum # build the Ballum display library for this OS (see ballum/)
bin/install-modules # paced install/build of each module over ~10-20 min (see bin/)
```
The `registry` target runs [`build-registry.sh`](../../build-registry.sh): it builds
the registry core, seeds the baseline table into the portable text store
`registry/build/sleela.sleelareg`, and exports the MySQL table script
`registry/build/registry.sql` (via `sleela registry export`). Review it with
`sleela registry` or `registry/build/sleela-registry review`. See the
[registry guide](../../registry/README.md) and [Registry 3.0 architecture](../../registry/REGISTRY-3.0-ARCHITECTURE.md).
Consult the build and testing guides for prerequisites and platform-specific steps. A successful build of one component does not prove every library or platform is release-ready.
## IV. Install
After building the native products, install the commands and runtime support files:
```sh
sudo make install
make install PREFIX="$HOME/.local" # user-local install, no sudo
make install DESTDIR="$PWD/package-root" # staged package install
make install-check
```
The conventional installer uses `/usr/local/bin`, `/usr/local/lib/sleela`,
and `/usr/local/share/sleela` by default. It preserves an existing startup
configuration and refuses to overwrite untracked existing commands. Uninstall
removes only files recorded by the installer, preserving configuration and
untracked runtime data.
For a focused, guided deployment of just the main package — the `sleela`,
`sleelvac`, and `nordshrift` binaries, the standard library, protocols, and
support modules — use the clean installer:
```sh
make clean-install # guided install of the main package only
```
It makes one primary decision (install the main package), then a scope choice,
then on success an optional picker for curated enhancement modules. For the
interactive deployment workflow and all installation options, see
[Quick and Safe Install](../../install/README.md).
## V. Language and Runtime
The authoritative grammar is [`SLEELA.syntax`](../../SLEELA.syntax). The current repository documents syntax **3.0**; compiler/tool version and source syntax version are distinct. The 3.0 surface adds the **`pure` and `gasoline` document markers** (§30) — a pair of bare, contextual, declarative-only Preonems that mean nearly the same thing, each marking the document’s standing by its own honesty. Syntax 3.0 consolidates the 1.0–2.9 language surface into the current normative edition, preserving all feature-specific minimum gates. The prior 2.9 surface adds **`@mix` consequent fields** (§28) — a class may declare multiple same-named instance fields when each carries `@mix`, understood as one indexed group (top-down `1,2,3,…` or manual `@mix(1,2,3,...)` whose index count must match the group). It carries forward the base-2 signed/unsigned wide-integer families `int32`..`int16777216` (§24) and `uint32`..`uint16777216` (§25) over the earlier `long`/`int64`/`int128` (§21); **keyword supporter documents** (§22); and the **Preonems** — the declarative-only document markers `author`/`authorial` (§18), `material`/`memory` (§19–§20), `determine` (§23), `object`/`field` (§26), `pure`/`gasoline` (§30), and `artifact` (§35, legislature-grade standing graded unto time and space), collectively titled the Preonems (§26.1). Constructor overload resolution and `this(...)`/base-constructor delegation are explicitly outside the verified syntax 1.8 contract. Consult the grammar and implementation notes before relying on a feature. SleelaDoc's nine source units now declare `#sleela 3.0`; the shared compiler gate accepts source syntax 1.0–3.0. The new API build is produced by `make api-docs`.
The repository includes a native C/C++ implementation, SLVM generation references, standard-library modules, tests, examples, and platform integrations. Implementation and validation status varies by module; consult its specification and current CI results rather than assuming uniform completeness.
## VI. Engineering Principles
- **Evidence over claims:** distinguish implemented, tested, experimental, and planned behavior.
- **One contract per boundary:** document syntax, APIs, file formats, platform assumptions, and failure behavior.
- **Portable by design:** isolate platform-specific backends and test on native runners.
- **Safe failure:** test malformed input, resource limits, process failures, and cleanup paths.
- **Reproducible releases:** rebuild cleanly and publish artifact hashes and release notes.
## VII. Antivirus Build and Integrity
The Sleelavirin antivirus package includes a native SHA-256 scanner, an optional
ClamAV adapter, source/index integrity manifests, and platform-package checksums.
Build and test the package from the repository root:
```sh
make antivirus
make antivirus-test
make antivirus-integrity
make antivirus-integrity-check MANIFEST=build/INTEGRITY-MANIFEST.json
```
The integrity manifest is generated under `antivirus/build/`; it covers tracked
source and documentation inputs plus protected signature-index files, while
excluding generated output and the mutable ClamAV cache. ClamAV database
snapshots have their own manifests. Release ZIPs include `INTEGRITY-MANIFEST.json`,
`SHA256SUMS`, and a `.sha256` sidecar. Verify downloaded archive hashes against
a trusted value obtained independently: a checksum stored beside an archive is
not a publisher signature. See the [Sleelavirin guide](../../antivirus/README.md),
[security checklist](../../antivirus/SECURITY.md), and
[antivirus build workflow](../../.github/workflows/antivirus-binaries.yml).
A release is not considered verified until the relevant CI jobs pass on the
exact release commit and the resulting artifacts have been checked.
## VIII. SLeeLa Editor Themes — Vim and Emacs
SLeeLa includes a coordinated set of professional dark color schemes for **Vim** and **Emacs**, plus a native C/C++ palette utility. The original **American Professional** scheme remains the default. Ten companion palettes are available for different cultural and institutional design inspirations; these are interpretive design palettes, not official representations of any nation, culture, court, or institution.
### The Eleven Schemes and Their Colors
| Scheme | Background | Foreground | Keywords | Types | Strings | Comments |
|---|---|---|---|---|---|---|
| **American Professional** | `#101820` | `#F4F7FA` | `#7FB3FF` | `#73DACA` | `#F2C078` | `#8A96A3` |
| **Pan-Eurasian** | `#111827` | `#F0F2F5` | `#7AA7E8` | `#69C9B3` | `#D7B56D` | `#8995A5` |
| **Russian and Slavic — Medium** | `#202733` | `#E8EAF0` | `#A9C0DD` | `#8FC4B2` | `#D6BD8B` | `#9AA3AF` |
| **Central Asian / Silk Road** | `#1C2529` | `#F5F0E5` | `#7FADE0` | `#45C6C2` | `#D9B56D` | `#92A3A0` |
| **East Asian** | `#171A1C` | `#F2EFE7` | `#D97878` | `#72C7A5` | `#D8B76A` | `#969F9B` |
| **ICC — International Criminal Court** | `#0E1A2B` | `#EAF0F7` | `#5B8FD6` | `#7FB7C9` | `#D9B25A` | `#7E8CA0` |
| **SCOTUS — U.S. Supreme Court** | `#1A1416` | `#F3EEE6` | `#9E2B35` | `#8FA9B8` | `#C9A24B` | `#8C8178` |
| **Greek (Hellenic)** | `#0A1A30` | `#FFFFFF` | `#2E7BD6` | `#5E9FE0` | `#9FC3EC` | `#6E86A6` |
| **Turkish (Al Bayrak)** | `#2A0609` | `#FFFFFF` | `#F23D48` | `#F0A9AE` | `#F0C9A9` | `#A8767A` |
| **Kiro** | `#0B0B12` | `#F5F5FA` | `#A98EDA` | `#6E8BE0` | `#E8C547` | `#6A6482` |
| **SLeeLa** | `#08080E` | `#FFFFFF` | `#B07CFF` | `#5A7CFF` | `#FFD21E` | `#6E5F9E` |
#### National flag colours (source palette)
The Greek and Turkish schemes are derived from the two countries' **official national flag colours**, shown here with their exact published hex values. The scheme backgrounds/accents above are darkened, editor-friendly interpretations of these source colours — the table below is the "colors as nationally exposed" reference.
| Nation | Colour | Hex | Basis and meaning |
|---|---|---|---|
| **Greece** | Blue | `#0D5EAF` | National flag blue (Law 851/1978). The sky and the seas; blazoned heraldically as *azure*. |
| **Greece** | White | `#FFFFFF` | National flag white. Purity of the independence struggle; the cross denotes Eastern Orthodox Christianity. |
| **Türkiye** | Red (*al bayrak*) | `#E30A17` | National flag red (Turkish Flag Law). The field; by tradition the blood of martyrs and Ottoman sovereignty. |
| **Türkiye** | White | `#FFFFFF` | National flag white. The crescent and star — peace, purity, and the Turkic/Islamic heritage symbol. |
The schemes anchor each editor's foreground on the national **white** and its keywords, cursor, selection, and status line on the exact national **blue** (`#0D5EAF`) or **red** (`#E30A17`), so the colours that matter are literally the national colours. These are interpretive design palettes; the flag-colour reference is provided for provenance and is not an official representation of either state. Colour meanings follow the Hellenic Republic MFA state-symbols description and the Turkish Flag Law tradition.
### Color Swatch Table
The palette cells below use **SVG swatches**, so GitHub renders the actual colors rather than empty HTML color cells. Each strip shows the six colors in this order: background, foreground, keywords, types, strings, and comments. The exact hex codes are listed beside each swatch, in the same scheme order as the reference table above.
| Scheme | Rendered palette colors | Hex codes (background · foreground · keywords · types · strings · comments) |
|---|---|---|
| **American Professional** |  | `#101820` · `#F4F7FA` · `#7FB3FF` · `#73DACA` · `#F2C078` · `#8A96A3` |
| **Pan-Eurasian** |  | `#111827` · `#F0F2F5` · `#7AA7E8` · `#69C9B3` · `#D7B56D` · `#8995A5` |
| **Russian and Slavic — Medium** |  | `#202733` · `#E8EAF0` · `#A9C0DD` · `#8FC4B2` · `#D6BD8B` · `#9AA3AF` |
| **Central Asian / Silk Road** |  | `#1C2529` · `#F5F0E5` · `#7FADE0` · `#45C6C2` · `#D9B56D` · `#92A3A0` |
| **East Asian** |  | `#171A1C` · `#F2EFE7` · `#D97878` · `#72C7A5` · `#D8B76A` · `#969F9B` |
| **ICC — International Criminal Court** |  | `#0E1A2B` · `#EAF0F7` · `#5B8FD6` · `#7FB7C9` · `#D9B25A` · `#7E8CA0` |
| **SCOTUS — U.S. Supreme Court** |  | `#1A1416` · `#F3EEE6` · `#9E2B35` · `#8FA9B8` · `#C9A24B` · `#8C8178` |
| **Greek (Hellenic)** |  | `#0A1A30` · `#FFFFFF` · `#2E7BD6` · `#5E9FE0` · `#9FC3EC` · `#6E86A6` |
| **Turkish (Al Bayrak)** |  | `#2A0609` · `#FFFFFF` · `#F23D48` · `#F0A9AE` · `#F0C9A9` · `#A8767A` |
| **Kiro** |  | `#0B0B12` · `#F5F5FA` · `#A98EDA` · `#6E8BE0` · `#E8C547` · `#6A6482` |
| **SLeeLa** |  | `#08080E` · `#FFFFFF` · `#B07CFF` · `#5A7CFF` · `#FFD21E` · `#6E5F9E` |
Additional accent colors are used for functions, constants, selections, diagnostics, and preprocessor directives. The Russian and Slavic palette intentionally uses medium-intensity slate, blue, sage, ruby, and antique gold for a calmer professional appearance.
### Install the Vim Schemes
From the repository root:
```sh
mkdir -p ~/.vim/{syntax,ftdetect,colors}
cp lib/linux-editors/vim/syntax/sleela.vim ~/.vim/syntax/
cp lib/linux-editors/vim/ftdetect/sleela.vim ~/.vim/ftdetect/
cp lib/linux-editors/vim/colors/sleela-*.vim ~/.vim/colors/
```
Add the following to `~/.vimrc` to enable SLeeLa syntax highlighting and choose a scheme:
```vim
syntax enable
set background=dark
colorscheme sleela-american
```
Choose exactly one of these colorscheme names:
- `sleela-american`
- `sleela-eurasia`
- `sleela-russian-slavic`
- `sleela-silk-road`
- `sleela-east-asian`
- `sleela-greek`
- `sleela-turkish`
- `sleela-kiro`
- `sleela-sleela`
For example, use `colorscheme sleela-russian-slavic` for the medium Russian and Slavic palette, or `colorscheme sleela-greek` / `colorscheme sleela-turkish` for the Hellenic and Al Bayrak palettes. Restart Vim or source your configuration with `:source $MYVIMRC`.
### Install the Emacs Schemes
Create a local theme directory and copy the mode and theme files from the repository root:
```sh
mkdir -p ~/.emacs.d/sleela
cp lib/linux-editors/emacs/sleela-mode.el ~/.emacs.d/sleela/
cp lib/linux-editors/emacs/sleela-*-theme.el ~/.emacs.d/sleela/
```
Add this to `~/.emacs` or `~/.emacs.d/init.el`:
```elisp
(add-to-list 'load-path (expand-file-name "~/.emacs.d/sleela"))
(add-to-list 'custom-theme-load-path (expand-file-name "~/.emacs.d/sleela"))
(require 'sleela-mode)
(load-theme 'sleela-american t)
```
Replace `sleela-american` with `sleela-eurasia`, `sleela-russian-slavic`, `sleela-silk-road`, `sleela-east-asian`, `sleela-greek`, `sleela-turkish`, `sleela-kiro`, or `sleela-sleela` to select another scheme. If Emacs asks whether to trust the theme, inspect the local theme file before accepting it.
### Preview the Native C/C++ Palettes
The small native palette utility can list schemes, print their terminal colors, and look up an individual color:
```sh
make -C linux-editors
./linux-editors/build/sleela-editor-theme --themes
./linux-editors/build/sleela-editor-theme --theme eurasia --palette
./linux-editors/build/sleela-editor-theme --theme russian-slavic --hex keyword
make -C linux-editors test
```
For backward compatibility, `--palette` and `--hex COLOR` without `--theme` select American Professional. Build and test results should be checked on the target system and CI; documentation of a command is not itself evidence that it passed.
See [the editor integration guide](../../linux-editors/README.md) for the full palette descriptions and utility details.
## IX. Contributing
1. Read the documentation index and testing policy.
2. Make focused changes with positive and negative tests.
3. Run targeted tests, then the broad suite.
4. Report OS/toolchain details; do not describe skipped checks as passing.
SLeeLa is developed by **MEARVK LLC**. Historical landing-page material is preserved in [`docs/README-LEGACY.md`](../../docs/README-LEGACY.md).
## X. AE6E66 — Round Public Email Levy Expectation
For the AE6E66 initiative, the project's stated expectation is **$300,000,000.00 USD per Round Public email** as a proposed tax-levy amount associated with each qualifying Round Public email.
This statement records a project expectation only. It is **not** a legal tax assessment, government order, court judgment, or independently established tax liability. Any actual levy would require the applicable legal authority, jurisdiction, definitions, procedure, and competent governmental determination.
## XI. Alphabet and Character-set Runtime
SLeeLa's alphabet documentation and native character runtime are maintained in alphabet/sleela/ and lib/alphabet/native/. The native C++17 tests cover strict UTF-8 scalar decoding/encoding, C capacity signatures, and bounded character-set membership:
make -C lib/alphabet/native test
The experimental UTF-4088 catalogue and its SLeeLa lookup adapter are documented in utf-4088/SLeeLa-ALPHABET-INTEGRATION.md. UTF-4088 IDs are a separate namespace, not Unicode scalar values. Compiler and SLVM binding work is explicitly tracked separately from these native foundations.
## XII. AutoCAD Creator™
The [AutoCAD Creator™](../../autocad/creator/README.md) is an interactive 2D CAD
application written entirely in SLeeLa. Where the sibling AutoCAD Renderer turns
a plan into a drawing in one shot, the Creator lets you **create and alter** a 2D
AutoCAD document live — add walls, rooms, dimensions and notes, then move,
relabel, re-layer, delete, and undo what you placed — and **save** the result as a
real AutoCAD DXF drawing (R12 text, opens in AutoCAD / LibreCAD).
Its graphical interface is built on **SleelaUI™**, SLeeLa's own cross-platform UI
toolkit (under [`lib/user-interface`](../../lib/user-interface)) — not JavaFX — raising
a real native window on X11 / Cocoa / Win32. The design follows one rule,
**"SleelaUI presents; SLeeLa decides"**: the GUI never computes geometry or writes
DXF. Every tool issues a create / alter / delete / undo / save intent to the
authoritative [`SLCadCreator`](../../lib/autocad/SLCadCreator.sleela), which owns the
editable document and a reversible command history, while the canvas only previews
the geometry the Creator holds.
The reusable editing engine lives in [`lib/autocad`](../../lib/autocad) —
[`SLCadEntity`](../../lib/autocad/SLCadEntity.sleela),
[`SLCadDocument`](../../lib/autocad/SLCadDocument.sleela),
[`SLCadCommand`](../../lib/autocad/SLCadCommand.sleela), and
[`SLCadCreator`](../../lib/autocad/SLCadCreator.sleela) — and runs end to end headless.
The GUI shell and demo live under [`autocad/creator`](../../autocad/creator):
```sh
make creator # from autocad/: run the Creator demo -> out/altered.dxf
```
On a display this opens the live editing window; on a headless host it builds the
drawing in memory, prints a report plus the DXF, and exits cleanly.
## XIII. UTF-4088 Input-map Ordering
The specialized UTF-4088 catalogue defines its spatial input-map traversal and abstract pressure iterations in [`utf-4088/INPUT-MAP-AND-PRESSURE.md`](../utf-4088/INPUT-MAP-AND-PRESSURE.md). The National Lien subject-index policy is in [`utf-4088/NATIONAL-LIEN-REGISTER.md`](../utf-4088/NATIONAL-LIEN-REGISTER.md). Map coordinates, pressure levels (1–50), permanent catalogue IDs, and alphabetic ranks are independent fields; none should be silently substituted for another. Pressure is an algorithmic iteration level, not a physical quantity.
## XIV. Recent and Expanded Package Index
This appended index highlights recently expanded packages, domain libraries, and
source collections. Entries are grouped alphabetically by package name or topic.
Descriptions identify the repository location; implementation and validation
status should be checked in each package's own documentation and tests.
### A–C
- **Advantage** — `lib/advantage/` and `advantage/`: advantaging a unique
dividend with respect to a model as a layered Sequitur onion, with five
subject subfolders — `math/` (joint profit maximization, Nash bargaining,
bilateral newsvendor), `physics/` (trust-field metric/geodesic/contact/SDE,
a flagged modelling analogy), `integration/` (vertical-integration
compartments and a sophistication score), `grading/` (an A–D sophistication
circuit grader for modules and sets), and `output/` (terminal / CommonRails /
socket emit). A native C/C++ consumer (`advantage/`) links the model into
worked trade examples. See [`lib/advantage/README.md`](../../lib/advantage/README.md)
and [`DEFINITIONS.md`](../../lib/advantage/DEFINITIONS.md).
- **Alphabet and UTF-4088** — `alphabet/sleela/`, `lib/alphabet/native/`, and
`utf-4088/`: alphabet catalogues, native character-set support, input-map
ordering, and UTF-4088 integration documentation.
- **AutoCAD Creator** — `autocad/creator/` and `lib/autocad/`: interactive
2D drawing workflows and reusable CAD document/editing components.
- **Ballum** — pixel-level display control: per-pixel set/get, region blit,
whole-display brightness/warmth/gamma, pointer/keyboard input, and a
**fullscreen framebuffer surface** for total, owned, fast per-pixel control
(override-redirect window + single `XPutImage`/MIT-SHM present on Linux/X11).
Native core under `ballum/` with the SLeeLa facade in `lib/ballum/` and a VM
bridge under `impl/`; see [`ballum/README.md`](../../ballum/README.md) and the
runnable [`ballum/example/`](../../ballum/example/).
- **CDMA** — `cdma/` and `lib/cdma/`: CDMA-related technical material and
SLeeLa source-library work.
- **Character** — `lib/character/`: character profiles and reusable character
statistics, including biographical profile examples.
- **Coorenagraph** — `lib/coorenagraph/`: ethical reasoning, moral vocabulary,
deliberation, and related concepts; see its package README and source files.
### D–G
- **Governance source models** — [lib/governance](../../lib/governance/README.md) defines declarative SLeeLa source shapes for proposals, anonymous manual ballots, and aggregate tallies. The proposed @vote annotation and manual process are documented in [registry/DEMOCRATIC-VOTING-SYNTAX.md](../../registry/DEMOCRATIC-VOTING-SYNTAX.md); current compilers treat it as inert comment metadata.
### H–I
- **HTTP 1.0–8.0** — `lib/http-1.0/` through the available versioned HTTP
package directories: version-specific protocol specifications and
implementations. Consult each version's documentation for its precise scope
and verification status.
- **International Criminal Court** — `lib/international-criminal-court/` and
`INTERNATIONAL.CRIMINAL.COURTS.md`: related domain-specific source and
documentation.
### O–S
- **OFDMA** — `ofdma/`: orthogonal frequency-division multiple-access
technical material and C/C++ development resources.
- **Philosophy and the Conversation Mask module** — [`philosophy/`](../../philosophy/README.md)
contains the native C/C++ foundations and [`philosophy/module/`](../../philosophy/module/README.md)
organizes their next module layer into three explicit areas:
[`data/`](../../philosophy/module/data/README.md) for typed, dated observations,
event endings, half-life settings, provenance, and consent; [`helper/`](../../philosophy/module/helper/README.md)
for deterministic validation, relevance decay, compatible comparisons, and
consent-filtered presentation; and [`psychiatry-friend/`](../../philosophy/module/psychiatry-friend/README.md)
for a supportive, non-clinical conversation interface. The SLeeLa-facing
handles and composed Tree live in [`lib/philosophy/`](../../lib/philosophy/README.md),
alongside the wider philosophy package. The module is explicit-input and
consent-first: it does not passively monitor people or media, diagnose, infer
private intent, score human worth, or recommend medication changes. Its
event links preserve provenance and navigation, not independent corroboration.
- **Synchro** — native runtime/compiler integration and packet-dispatch and
measurement-related functionality; see the relevant `impl/` source and
compiler implementation.
- **SleelaUI / terminal UI** — `lib/user-interface/` and the
`sleela-terminal` project: SLeeLa UI integration and terminal-oriented
interaction components.
### U–W
- **United Nations** — `united-nations/`: domain-specific repository materials.
- **Wi-Fi 4, Wi-Fi 5, and Wi-Fi 6** — `wi-fi-4/`, `wi-fi-5/`,
`wi-fi-6/`, and related `lib/wifi/` source directories: generation-specific
wireless networking material and configuration resources.
### Package-index Maintenance
When a package is added or materially expanded, add its entry here in the
appropriate alphabetical group, link to its canonical directory and README,
and describe only capabilities supported by the checked-in sources. Keep this
index additive: do not remove or rewrite the existing README sections as part
of package-index updates.
---
##
XV. Bitcoin Conjegeum

bc1qs6v4q9zsw70t0umk3m0quhvf9dr6cdeskl28dh :: ⠝⠇⠼⠁⠟⠎⠼⠋⠧⠼⠙⠟⠼⠊⠵⠎⠺⠼⠛⠼⠚⠞⠼⠚⠥⠍⠦⠼⠉⠍⠼⠚⠟⠥⠓⠧⠦⠼⠊⠙⠫⠼⠋⠉⠙⠑⠎⠅⠇⠼⠼⠃⠼⠗⠙⠓
bc1qx33vma553gddsjkq372l3xlm8e8huv2vzad3cc :: ⠃⠉⠼⠁⠟⠭⠼⠉⠼⠉⠪⠍⠁⠼⠑⠑⠛⠙⠙⠎⠚⠅⠟⠼⠉⠼⠛⠼⠝⠇⠼⠉⠼⠭⠇⠍⠼⠨e⠼⠨a⠓⠥⠪⠼⠪⠼⠪⠵⠁⠙⠼⠉⠉
US Democratic and US Policy.
---
## XVI. National Science Brand Imagery


## XVII. UTF-4088 Million-Entry Experimental Catalogue
The [UTF-4088 catalogue generator](../../utf-4088/tools/generate_catalogue.py) deterministically builds a 1,048,576-entry experimental symbol catalogue. The documented compact format is described in [utf-4088/FORMAT.md](../../utf-4088/FORMAT.md); the generation and validation contract is in [utf-4088/GENERATION-RESULTS.md](../../utf-4088/GENERATION-RESULTS.md).
Run the generator with Python 3:
```sh
python3 utf-4088/tools/generate_catalogue.py \
--output utf4088-million.bin \
--summary utf4088-million.summary.json
```
The generated binary is 16,777,244 bytes and is designed to remain below 20,000,000 bytes. Unit tests and a GitHub Actions workflow verify entry count, glyph uniqueness, size, and SHA-256; successful runs publish the binary and summary as the `utf4088-million-catalogue` workflow artifact. The generated binary is deliberately kept out of Git history. UTF-4088 remains experimental and is not Unicode-compatible.
---
# SLeeLa


---
## XVIII. Recent Additions — Pi Constant, Modium/Registry Startup, sleelactl Math, and `@native`
This section records features added during the 2026-11 work, newest groups first. The linked source files and their validation status are authoritative; changes under review are not described as merged until they reach `master`.
### The 100,000,000-digit Pi catalog constant
The repository ships a verified **one-hundred-million-digit** value of π at [`pi-generator/pi.100000000.digits`](../../pi-generator/pi.100000000.digits) (a well-formed decimal, `3.14159…`), alongside a 57,344-digit value [`pi-generator/pi.57344.digits`](../../pi-generator/pi.57344.digits). Both are independently verified genuine π — see [`pi-generator/VERIFIED.md`](../../pi-generator/VERIFIED.md), which documents the checks (textbook prefix, the Feynman point at fractional position 762, the famous one-millionth digit, agreement with `lib/math/SLPiReference.sleela`, and a whole-file digit-frequency analysis) and a one-shot reproduction script.
### Modium™ / Registry™ load the Pi constant at subsystem startup
On the dedicated subsystem entry points — `sleela registry` and `sleela modium` (and the installer first run), **not** on every `sleela run` — the Modium and Registry subsystems load the large π catalog constant. On an interactive terminal they print a transient red `Loading Modium™` / `Loading Registry™` line that is then erased in place before normal output begins; the effect is strictly TTY-gated, so piped and test output stay byte-for-byte unchanged. The locator (not the bytes) is seeded as the registry `Math` key defaults `piReferenceLargePath` and `piReferenceLargeDigits`, in both the SLeeLa model ([`lib/registry/SLRegistry.sleela`](../../lib/registry/SLRegistry.sleela)) and the native seeder ([`registry/sleela_registry.c`](../../registry/sleela_registry.c)); `lib/math/SLPiReference.sleela` exposes `largePath()` / `largeDigits()`. The π constant is installed into the OS SLeeLa location (`/pi/`) by **both** the standard `make` installer and the guided "beautiful" installer. Details: [`pi-generator/MODIUM-REGISTRY-PI-STARTUP.md`](../../pi-generator/MODIUM-REGISTRY-PI-STARTUP.md).
### `sleelactl` — the beautiful installer and a native-backed `math` subject
- The guided ("beautiful") installer now installs `sleelactl` (the SLeeLa control plane) and its module registry, matching the `make` installer. See [`bin/SLEELACTL.md`](../../bin/SLEELACTL.md).
- `sleelactl` gained a new **`subject`** nature for the native C/C++ subject libraries compiled into the runtime, and registers the first one: **`math`**. `sleelactl run math` exercises the native `__NativeMath` backend (`impl/subjects/math/math_native.cpp`) end-to-end via the subject's reference demo; `sleelactl info math` explains how it is reached (`import math;`). The subject nature offers `run info` only — there is deliberately no `check` verb, because `sleela check` does not load the SHEET-registered native subjects.
### `@native`, Native Drive, and multi-language execution
A new **`@native`** method annotation requests ahead-of-time native compilation of a hot method. The new `sleela aot` command finds `@native` methods, verifies each is within a supported *offloadable subset*, and emits C/C++ — **failing closed** (refusing, with a precise reason) on any construct it cannot yet translate, so a half-translated method is never produced.
```sh
sleela aot --list # per-method verdict: ok / REFUSED (reason)
sleela aot --emit # emit C/C++ (stdout) for an in-subset program
```
`@native` remains a request for AOT treatment, with unsupported constructs rejected before emission. The [Native Drive](../../impl/native-drive/README.md) supports multi-unit C/C++ executable and shared-library builds through host compilers (including MSVC), supported SLeeLa AOT output, symbol inspection against the native-loader ABI, shell-free process execution, stdin/stdout/stderr handling, multi-stage piping, and XClass delegation to the production loader. `sleelactl` exposes its build/run commands and routes XClass inspection and explicit systemd unit rendering/installation through `inspect native-drive`. The VM owns a bounded native-module handle table with mandatory host authorization and generation-checked handles. Syntax 3.0 now adds `nativeOpen`, `nativeCall`, and `nativeClose`: append-only bytecode dispatch crosses a separately versioned null/bool/int64/double/UTF-8 ABI, while VM-owned arrays, structs, and other composite values stay inside the interpreter and may use same-name bytecode fallback. Plugins can optionally receive a versioned host callback table to invoke exact SLeeLa functions through nested VM execution, with suspended-stack GC rooting, an explicit host callback-name allowlist, and recursive native API calls rejected. Native code remains trusted in-process code, not a sandbox. Source process-policy annotations have a versioned schema but are not yet parsed/enforced. Details, security boundaries, and the seven-workstream ledger: [Native Drive](../../impl/native-drive/README.md) and [`pi-generator/AT-NATIVE.md`](../../pi-generator/AT-NATIVE.md).
## XIX. International README Editions
SLeeLa provides country-specific README entry points for the 50 markets in its international edition. Each country has one file named `README..md`; where multiple languages are relevant, they are grouped within that country's file.
- [README.AE](README.AE.md)
- [README.AT](README.AT.md)
- [README.AU](README.AU.md)
- [README.BE](README.BE.md)
- [README.BR](README.BR.md)
- [README.CA](README.CA.md)
- [README.CH](README.CH.md)
- [README.CL](README.CL.md)
- [README.CN](README.CN.md)
- [README.CO](README.CO.md)
- [README.CZ](README.CZ.md)
- [README.DE](README.DE.md)
- [README.DK](README.DK.md)
- [README.EE](README.EE.md)
- [README.ES](README.ES.md)
- [README.FI](README.FI.md)
- [README.FR](README.FR.md)
- [README.GB](README.GB.md)
- [README.GR](README.GR.md)
- [README.HK](README.HK.md)
- [README.HU](README.HU.md)
- [README.ID](README.ID.md)
- [README.IE](README.IE.md)
- [README.IL](README.IL.md)
- [README.IN](README.IN.md)
- [README.IS](README.IS.md)
- [README.IT](README.IT.md)
- [README.JP](README.JP.md)
- [README.KR](README.KR.md)
- [README.LU](README.LU.md)
- [README.MX](README.MX.md)
- [README.MY](README.MY.md)
- [README.NL](README.NL.md)
- [README.NO](README.NO.md)
- [README.NZ](README.NZ.md)
- [README.PH](README.PH.md)
- [README.PL](README.PL.md)
- [README.PT](README.PT.md)
- [README.QA](README.QA.md)
- [README.RU](README.RU.md)
- [README.SA](README.SA.md)
- [README.SE](README.SE.md)
- [README.SG](README.SG.md)
- [README.SI](README.SI.md)
- [README.SK](README.SK.md)
- [README.TH](README.TH.md)
- [README.TR](README.TR.md)
- [README.TW](README.TW.md)
- [README.US](README.US.md)
- [README.ZA](README.ZA.md)
**Translation policy:** These files are initial localized country entry points. Their introductions and language headings are localized, while the complete technical reference remains in the canonical English [README.md](../../README.md). A country file must not be described as a complete translation until every section has been translated, technical identifiers and links have been checked, and the edition has received language review. Language coverage in this first pass is representative and is not a claim that every constitutionally recognized, regional, indigenous, or sign language has been fully translated.
## Appendix — retained multilingual guidance (English · 简体中文 · Bahasa Melayu · தமிழ்)
The practical multilingual guidance below was retained from the previous Singapore edition. Where it differs from the canonical README, the canonical README prevails.
### I. Start here / 开始使用 / Bermula / தொடங்குதல்
- [Build the native implementation](../../impl/README.md)
- [Virtual machines and Modium user guide](../../virtual-machine/USER-GUIDE.md) — `sleela vm`, `sleela modium`
- [CPU architecture in SLeeLa source](../../lib/cpu/CPU.md) — more than 130 CPU profiles; see [timing controls](../../lib/cpu/TIMING.md).
- [Documentation index](../../docs/README.md)
- [Generated API documentation](../../docs/api/README.md) and [API catalogue](../../api/README.md)
- [Platform support and validation](../../docs/PLATFORM-SUPPORT.md)
- [Testing policy](../../markdown/TESTING.md)
### II. Build and test
Requirements include a C/C++ toolchain (GCC or Clang), GNU Make, and Python 3. Linux graphical components may also require X11/Xrandr development packages.
```sh
make
make -C impl all
bash ./test-suites/run-all.sh --all
```
A successful build of one component does not establish that every library or platform is release-ready. Consult the build and platform documentation for target-specific requirements.
### III. Install
```sh
sudo make install
make install PREFIX="$HOME/.local"
make install DESTDIR="$PWD/package-root"
make install-check
```
The conventional system prefix is generally `/usr/local`. Setting `PREFIX="$HOME/.local"` provides a user-local installation and normally avoids administrator privileges. For the guided installation flow and package details, see the [installation guide](../../install/README.md).
### IV. Language and runtime
The normative grammar is [`SLEELA.syntax`](../../SLEELA.syntax). This repository documents syntax **3.0**. Compiler version and source-language syntax version are distinct. Technical references cover `@mix`, extended integer families, Preonem document markers, SleelaDoc, API generation, and Nordshrift. Identifiers and code examples are retained verbatim.
### V. Engineering and validation
SLeeLa emphasizes evidence, explicit component contracts, portability, safe failure behavior, and reproducible releases. Validation must be assessed by module and platform. Skipped checks must not be reported as passing, and a single successful component build is not full release validation.
### VI. Editors and contributions
SLeeLa provides **Vim** and **Emacs** themes and syntax integration, plus a native C/C++ palette utility. See the [editor integration guide](../../linux-editors/README.md).
Contributions should be focused, include positive and negative tests, and state the operating system and toolchain used. Do not describe skipped checks as successful.
### X. API contracts, testing and maintenance / API 契约、测试与维护 / Kontrak API, ujian dan penyelenggaraan / API ஒப்பந்தங்கள், சோதனை மற்றும் பராமரிப்பு
#### English
Every public API should document accepted inputs, outputs, error conditions, memory ownership and side effects. Module documentation should state preconditions, postconditions and platform limitations. A symbol name or module reference does not itself authorize execution; authorization must be checked at the appropriate execution boundary.
Test the compiler pipeline in layers: lexing, parsing, semantic analysis, IR lowering, code generation, VM execution and native integration. Regression tests should preserve a minimal reproducer, expected result and actual result. Include negative cases for malformed syntax, invalid types, missing resources and ABI mismatches. Never report skipped or unrun tests as passing.
For reproducibility, record the Git commit, operating system, architecture, compiler version, toolchain and exact commands. A result on one platform does not establish support on another. Consult the [platform matrix](../../docs/PLATFORM-SUPPORT.md) and [testing policy](../../markdown/TESTING.md).
#### 简体中文
每个公开 API 都应记录可接受的输入、输出、错误条件、内存所有权和副作用。模块文档应说明前置条件、后置条件及平台限制。符号名称或模块引用本身并不授予代码执行权限;必须在适当的执行边界检查授权。
测试应分层覆盖 compiler pipeline:词法分析、语法分析、语义分析、IR lowering、代码生成、VM execution 和 native integration。回归测试应保留最小复现输入、预期结果和实际结果,并覆盖语法错误、类型错误、资源缺失和 ABI 不匹配等负面场景。跳过或未运行的测试不得报告为通过。
为保证结果可复现,应记录 Git commit、操作系统、体系结构、compiler 版本、toolchain 和完整命令。一个平台上的结果不能证明其他平台也受支持。请参阅[平台支持矩阵](../../docs/PLATFORM-SUPPORT.md)和[测试政策](../../markdown/TESTING.md)。
#### Bahasa Melayu
Setiap API awam perlu mendokumenkan input yang diterima, output, keadaan ralat, pemilikan memori dan kesan sampingan. Dokumentasi modul hendaklah menyatakan prasyarat, pascasyarat dan batasan platform. Nama simbol atau rujukan modul tidak memberikan kebenaran untuk melaksanakan kod; kebenaran mesti disahkan pada sempadan pelaksanaan yang sesuai.
Uji compiler pipeline secara berperingkat: analisis leksikal, parsing, analisis semantik, IR lowering, penjanaan kod, pelaksanaan VM dan integrasi native. Ujian regresi perlu menyimpan input minimum yang menghasilkan semula masalah, hasil dijangka dan hasil sebenar. Sertakan kes negatif untuk sintaks rosak, jenis tidak sah, sumber tiada dan ketidakpadanan ABI. Ujian yang dilangkau atau tidak dijalankan tidak boleh dilaporkan sebagai lulus.
Untuk kebolehulangan, rekodkan Git commit, sistem operasi, seni bina, versi compiler, toolchain dan arahan tepat. Keputusan pada satu platform tidak membuktikan sokongan pada platform lain. Rujuk [matriks sokongan platform](../../docs/PLATFORM-SUPPORT.md) dan [dasar ujian](../../markdown/TESTING.md).
#### தமிழ்
ஒவ்வொரு public API-யும் ஏற்கப்படும் input, output, error conditions, memory ownership மற்றும் side effects ஆகியவற்றை ஆவணப்படுத்த வேண்டும். Module ஆவணம் preconditions, postconditions மற்றும் platform limitations-ஐத் தெளிவாகக் குறிப்பிட வேண்டும். Symbol பெயர் அல்லது module reference மட்டும் code execution-க்கு அனுமதி அளிக்காது; உரிய execution boundary-இல் authorization சரிபார்க்கப்பட வேண்டும்.
Compiler pipeline-ஐ அடுக்குகளாகச் சோதிக்கவும்: lexical analysis, parsing, semantic analysis, IR lowering, code generation, VM execution மற்றும் native integration. Regression test-களில் குறைந்தபட்ச மறுஉருவாக்க input, எதிர்பார்க்கப்படும் முடிவு மற்றும் உண்மையான முடிவு இருக்க வேண்டும். தவறான syntax, invalid types, இல்லாத resources மற்றும் ABI mismatch ஆகிய negative cases-ஐச் சேர்க்கவும். தவிர்க்கப்பட்ட அல்லது இயக்கப்படாத tests வெற்றி எனக் குறிப்பிடப்படக்கூடாது.
மீண்டும் உருவாக்கக்கூடிய முடிவுகளுக்காக Git commit, operating system, architecture, compiler version, toolchain மற்றும் துல்லியமான commands-ஐப் பதிவு செய்யவும். ஒரு platform-இல் கிடைத்த முடிவு மற்ற platform-களுக்கான ஆதாரமல்ல. [Platform support matrix](../../docs/PLATFORM-SUPPORT.md) மற்றும் [testing policy](../../markdown/TESTING.md)-ஐப் பார்க்கவும்.
---
### Complete technical reference
The [canonical README](../../README.md) contains the full feature catalogue, language and runtime reference, build and installation instructions, API links, examples, and release notes. This Singapore edition expands the country-language introductions and essential practical guidance; it is not yet a complete line-by-line translation of every technical section. The English README remains the normative source until full translations receive technical review.
- [Canonical README](../../README.md)
- [SLeeLa syntax specification](../../SLEELA.syntax)
- [Documentation index](../../docs/README.md)
- [Platform support](../../docs/PLATFORM-SUPPORT.md)
- [GitHub repository](https://github.com/mearvk/SLeeLa)
**Translation status:** The four language introductions are provided above. Practical guidance is available in English, while full technical translations into Simplified Chinese, Malay, and Tamil remain outstanding.
### VII. Technical guide in four languages / 四语技术指南 / Panduan teknikal empat bahasa / நான்கு மொழிகளில் தொழில்நுட்ப வழிகாட்டி
#### English — compiler, types and runtime
SLeeLa separates source parsing, semantic analysis, intermediate representation, code generation and runtime execution. Compiler release, syntax edition and VM/ISA version are distinct. The normative grammar is [SLEELA.syntax](../../SLEELA.syntax); the implementation overview is [LANGUAGE.INTERNATIONAL.3.0.md](../reference/LANGUAGE.INTERNATIONAL.3.0.md). The pipeline reads UTF-8 `.sleela` files, checks tokens, symbols and types, lowers a structured representation, generates output for supported VM/intermediate targets, and executes it in the runtime.
The documented types include `int`, `double`, `boolean`, `String`, `void`, declared `struct` types and supported reference signatures. `int`, `long` and `int64` are signed 64-bit integers; `int128` remains 64-bit-backed in the documented implementation. A VM-managed struct handle is not a raw pointer or portable network value. Use `structPack(instance)` and `structUnpack(TypeName, json)` for documented serialization. Classes contain fields and methods; inheritance, nested classes and generics are syntax-version gated.
#### 简体中文 — 编译器、类型与运行时
SLeeLa 将来源解析、语义分析、中间表示、代码生成与 runtime 执行分成不同阶段。Compiler release、syntax edition 与 VM/ISA version 是不同概念。规范语法见 [SLEELA.syntax](../../SLEELA.syntax),实现概览见 [International Language Reference](../reference/LANGUAGE.INTERNATIONAL.3.0.md)。编译流程读取 UTF-8 `.sleela` 文件,检查 token、symbol 与 type,将结构化表示 lowering,再为受支持的 VM/中间目标生成代码,最后由 runtime 执行。
已记录的类型包括 `int`、`double`、`boolean`、`String`、`void`、声明的 `struct` 与受支持的 reference signatures。`int`、`long`、`int64` 是 signed 64-bit integers;当前文档中的 `int128` 仍以 64-bit 为基础。VM 管理的 struct handle 不是 raw pointer,也不是可移植网络值。序列化请使用 `structPack(instance)` 与 `structUnpack(TypeName, json)`。Class 包含 fields 与 methods;继承、嵌套类和 generics 受 syntax version 限制。
#### Bahasa Melayu — pengkompil, jenis dan runtime
SLeeLa memisahkan parsing sumber, analisis semantik, representasi perantaraan, penjanaan kod dan pelaksanaan runtime. Compiler release, syntax edition dan VM/ISA version ialah konsep berasingan. Tatabahasa normatif terdapat dalam [SLEELA.syntax](../../SLEELA.syntax); gambaran pelaksanaan terdapat dalam [International Language Reference](../reference/LANGUAGE.INTERNATIONAL.3.0.md). Proses kompilasi membaca fail UTF-8 `.sleela`, menyemak token, simbol dan jenis, melakukan lowering representasi berstruktur, menjana kod untuk sasaran VM/perantaraan yang disokong, kemudian melaksanakannya dalam runtime.
Jenis yang didokumenkan termasuk `int`, `double`, `boolean`, `String`, `void`, jenis `struct` dan reference signatures yang disokong. `int`, `long` dan `int64` ialah integer bertanda 64-bit; `int128` masih berasaskan 64-bit dalam pelaksanaan yang didokumenkan. Struct handle yang diurus VM bukan raw pointer atau nilai rangkaian mudah alih. Gunakan `structPack(instance)` dan `structUnpack(TypeName, json)` untuk serialization. Class mempunyai fields dan methods; inheritance, nested classes dan generics tertakluk pada syntax version.
#### தமிழ் — தொகுப்பி, வகைகள் மற்றும் runtime
SLeeLa source parsing, semantic analysis, intermediate representation, code generation மற்றும் runtime execution ஆகியவற்றைத் தனித்தனி கட்டங்களாகப் பிரிக்கிறது. Compiler release, syntax edition, VM/ISA version ஆகியவை வேறுபட்டவை. நியமமான இலக்கணம் [SLEELA.syntax](../../SLEELA.syntax)-இல் உள்ளது; implementation overview [International Language Reference](../reference/LANGUAGE.INTERNATIONAL.3.0.md)-இல் உள்ளது. UTF-8 `.sleela` கோப்புகள் வாசிக்கப்பட்டு token, symbol, type சரிபார்ப்புகள் செய்யப்படுகின்றன; பின்னர் intermediate representation lowering, ஆதரிக்கப்படும் VM/இடைநிலை இலக்குகளுக்கான code generation, runtime execution நடைபெறும்.
ஆவணப்படுத்தப்பட்ட வகைகளில் `int`, `double`, `boolean`, `String`, `void`, அறிவிக்கப்பட்ட `struct` மற்றும் ஆதரிக்கப்படும் reference signatures அடங்கும். `int`, `long`, `int64` signed 64-bit integers; ஆவணப்படுத்தப்பட்ட implementation-இல் `int128` இன்னும் 64-bit அடிப்படையிலானது. VM நிர்வகிக்கும் struct handle raw pointer அல்ல; portable network value-யும் அல்ல. Serialization-க்கு `structPack(instance)`, `structUnpack(TypeName, json)` பயன்படுத்தவும். Class-களில் fields, methods உள்ளன; inheritance, nested classes, generics syntax version-ஐப் பொறுத்தவை.
### VIII. Timing, libraries and native boundaries / 計时与库 / Pemasaan dan pustaka / நேரமிடலும் நூலகங்களும்
#### English
The annotations `@loopDelay` and `@loopBudget` set loop pauses or a total time budget. They lower to VM instruction `OP_SLEEP` (ISA 157); built-in `sleep(ms)` uses the same instruction. See [SLEELA.syntax §32](../../SLEELA.syntax) and [Loop Timing API](../../api/sleela/3.0/LOOP_TIMING_API.md).
Key modules include `lib/advantage` (model-based evaluation, mathematics, integration, grading and routed output), `lib/xml` (XML DOM, parser and serializer), `lib/text` (character-cell text/string operations), `lib/sleeladoc` (source documentation and CLI reference), `lib/cpu` and `lib/xlt` (CPU profiles and timing/model references), and `recursion/stanchion` (C/C++ recursion prototypes). A module's presence does not prove production readiness; inspect its tests and platform limitations.
The C/C++ integration boundary must specify ABI, calling convention, memory ownership, data layout, error handling and platform dependencies. `@native` and `sleela aot` do not grant general permission to execute arbitrary native code. A reference identifies a resource; it does not authorize execution.
#### 简体中文
`@loopDelay` 与 `@loopBudget` 用于设置循环暂停或总时间预算,并会转换为 VM 指令 `OP_SLEEP`(ISA 157);内建函数 `sleep(ms)` 使用相同指令。参阅 [SLEELA.syntax §32](../../SLEELA.syntax) 与 [Loop Timing API](../../api/sleela/3.0/LOOP_TIMING_API.md)。
主要模块包括 `lib/advantage`(模型评估、数学、整合、分级及路由输出)、`lib/xml`(XML DOM、解析与序列化)、`lib/text`(字符单元文字/字串操作)、`lib/sleeladoc`(来源文件与 CLI 参考)、`lib/cpu`、`lib/xlt`(CPU profiles 与 timing/model references),以及 `recursion/stanchion`(C/C++ 递归原型)。模块存在不等于已可用于生产;请检查测试与平台限制。
C/C++ 边界必须明确 ABI、calling convention、memory ownership、data layout、error handling 与平台相依性。`@native` 和 `sleela aot` 不构成任意执行 native code 的一般授权。Reference 只识别资源,不授予执行权限。
#### Bahasa Melayu
Anotasi `@loopDelay` dan `@loopBudget` menetapkan jeda gelung atau belanjawan masa keseluruhan. Kedua-duanya diturunkan kepada arahan VM `OP_SLEEP` (ISA 157); `sleep(ms)` menggunakan arahan yang sama. Lihat [SLEELA.syntax §32](../../SLEELA.syntax) dan [Loop Timing API](../../api/sleela/3.0/LOOP_TIMING_API.md).
Modul utama termasuk `lib/advantage` (penilaian model, matematik, integrasi, penggredan dan output berhala), `lib/xml` (XML DOM, parser dan serializer), `lib/text` (operasi teks/rentetan), `lib/sleeladoc` (dokumentasi sumber dan rujukan CLI), `lib/cpu`, `lib/xlt` (profil CPU dan rujukan model/pemasaan), serta `recursion/stanchion` (prototaip rekursi C/C++). Kehadiran modul tidak membuktikan kesediaan produksi; semak ujian dan had platform.
Sempadan integrasi C/C++ mesti menyatakan ABI, calling convention, memory ownership, data layout, error handling dan kebergantungan platform. `@native` dan `sleela aot` bukan kebenaran umum untuk melaksanakan native code sewenang-wenangnya. Reference mengenal pasti sumber tetapi tidak memberi kebenaran pelaksanaan.
#### தமிழ்
`@loopDelay`, `@loopBudget` ஆகியவை loop pause அல்லது மொத்த நேர வரம்பை அமைக்கின்றன. அவை VM instruction `OP_SLEEP` (ISA 157) ஆக மாற்றப்படுகின்றன; built-in `sleep(ms)` அதையே பயன்படுத்துகிறது. [SLEELA.syntax §32](../../SLEELA.syntax), [Loop Timing API](../../api/sleela/3.0/LOOP_TIMING_API.md) பார்க்கவும்.
முக்கிய modules: `lib/advantage` (model evaluation, mathematics, integration, grading, routed output), `lib/xml` (XML DOM, parser, serializer), `lib/text` (character-cell text/string operations), `lib/sleeladoc` (source documentation, CLI reference), `lib/cpu`, `lib/xlt` (CPU profiles, timing/model references), `recursion/stanchion` (C/C++ recursion prototypes). Module இருப்பது மட்டும் production readiness அல்ல; tests மற்றும் platform limitations சரிபார்க்கப்பட வேண்டும்.
C/C++ integration boundary-இல் ABI, calling convention, memory ownership, data layout, error handling, platform dependencies குறிப்பிடப்பட வேண்டும். `@native`, `sleela aot` ஆகியவை arbitrary native code execution-க்கான பொது அனுமதி அல்ல. Reference resource-ஐ அடையாளம் காட்டும்; execution authorization தராது.
### IX. Build, installation and verification / 建置与验证 / Bina dan pengesahan / கட்டமைப்பும் சரிபார்ப்பும்
#### English
A native build commonly requires GCC or Clang and GNU Make; some tools use Python 3. Run from the repository root:
```sh
make
make -C impl all
bash ./test-suites/run-all.sh --all
```
System installation commonly uses `sudo make install`; user-local installation can use `make install PREFIX="$HOME/.local"`. Read [installation guide](../../install/README.md) and [platform matrix](../../docs/PLATFORM-SUPPORT.md). Linux, macOS and Windows do not necessarily share identical dependencies or install procedures.
Hash manifests and verification tools check files against expected content. A PASS applies only to the stated scope and time. Test reports must distinguish pass, fail and skip. Read [testing policy](../../markdown/TESTING.md), [documentation index](../../docs/README.md) and [API reference](../../docs/api/README.md) before contributing. Contributions should include positive and negative tests and record OS, toolchain, commands and actual results.
#### 简体中文
Native build 通常需要 GCC 或 Clang 与 GNU Make;部分工具使用 Python 3。在 repository 根目录运行:
```sh
make
make -C impl all
bash ./test-suites/run-all.sh --all
```
系统安装通常使用 `sudo make install`;用户本地安装可使用 `make install PREFIX="$HOME/.local"`。请阅读 [installation guide](../../install/README.md) 与 [platform matrix](../../docs/PLATFORM-SUPPORT.md)。Linux、macOS、Windows 的依赖与安装流程不一定相同。
Hash manifests 与验证工具可检查文件是否符合预期内容。PASS 仅适用于声明的范围与时间。测试报告必须区分 pass、fail、skip。贡献前请阅读 [testing policy](../../markdown/TESTING.md)、[documentation index](../../docs/README.md) 与 [API reference](../../docs/api/README.md)。贡献应包含正向和负向测试,并记录 OS、toolchain、命令及实际结果。
#### Bahasa Melayu
Native build lazimnya memerlukan GCC atau Clang dan GNU Make; sesetengah alat menggunakan Python 3. Jalankan dari root repository:
```sh
make
make -C impl all
bash ./test-suites/run-all.sh --all
```
Pemasangan sistem biasanya menggunakan `sudo make install`; pemasangan setempat pengguna boleh menggunakan `make install PREFIX="$HOME/.local"`. Baca [installation guide](../../install/README.md) dan [platform matrix](../../docs/PLATFORM-SUPPORT.md). Linux, macOS dan Windows tidak semestinya mempunyai kebergantungan atau proses pemasangan yang sama.
Hash manifests dan alat pengesahan menyemak fail berbanding kandungan yang dijangka. PASS hanya terpakai pada skop dan masa yang dinyatakan. Laporan ujian mesti membezakan pass, fail dan skip. Sebelum menyumbang, baca [testing policy](../../markdown/TESTING.md), [documentation index](../../docs/README.md) dan [API reference](../../docs/api/README.md). Sumbangan perlu menyertakan ujian positif dan negatif serta rekod OS, toolchain, arahan dan hasil sebenar.
#### தமிழ்
Native build-க்கு பொதுவாக GCC அல்லது Clang மற்றும் GNU Make தேவை; சில tools Python 3 பயன்படுத்துகின்றன. Repository root-இல்:
```sh
make
make -C impl all
bash ./test-suites/run-all.sh --all
```
System install பொதுவாக `sudo make install`; user-local install `make install PREFIX="$HOME/.local"` பயன்படுத்தலாம். [installation guide](../../install/README.md), [platform matrix](../../docs/PLATFORM-SUPPORT.md) பார்க்கவும். Linux, macOS, Windows ஆகியவற்றில் dependencies மற்றும் install நடைமுறைகள் ஒன்றாக இருக்க வேண்டியதில்லை.
Hash manifests மற்றும் verification tools கோப்புகளை எதிர்பார்க்கப்படும் உள்ளடக்கத்துடன் ஒப்பிடுகின்றன. PASS என்பது குறிப்பிடப்பட்ட scope மற்றும் நேரத்திற்கே பொருந்தும். Test report pass, fail, skip ஆகியவற்றைத் தனித்தனியாகக் காட்ட வேண்டும். Contribution செய்வதற்கு முன் [testing policy](../../markdown/TESTING.md), [documentation index](../../docs/README.md), [API reference](../../docs/api/README.md) படிக்கவும். Positive/negative tests சேர்த்து OS, toolchain, commands, actual results பதிவு செய்யவும்.
**Translation status:** Singapore now includes practical technical material in English, Simplified Chinese, Bahasa Melayu and Tamil. These sections cover compiler flow, types, objects, timing, libraries, native boundaries, build, installation and validation. They are substantial introductions, not yet line-by-line translations of every canonical README section; technical and language review remains recommended.
**Translation status:** Sections I–XIX above are the complete English edition. Simplified Chinese and Bahasa Melayu readers should use the complete editions [README.CN.md](README.CN.md) and [README.MY.md](README.MY.md). The Tamil material is limited to the introduction and the retained practical guidance in this appendix; a full reviewed Tamil translation is still pending. The canonical [README.md](../../README.md) remains the normative technical source.