The canonical VM ISA is 156 opcodes (codes 0–155), and the `lib/opcodes` wrapper family now provides one single-opcode class for **every** one of them (156 `SLOp*` classes, codes 0–155). This page documents that full wrapper set.
# SLeeLa `/lib/opcodes` — Core Opcode Wrapper Subset
**Family:** `lib/opcodes`
**Revision:** 0.1
**Canonical ISA:** `lib/vm/InstructionSet.sleela` / `lib/vm/OPCODE-MAP.md`
**Native bridge:** `native/include/sleela_opcode.h`, `native/src/sleela_opcode.cpp`
The `/lib/opcodes` family expresses the **full** SLeeLa virtual-machine
instruction set as one SLeeLa source class per opcode. It covers codes 0–155 —
the complete canonical ISA defined by `lib/vm/InstructionSet.sleela` (156
opcodes). Each class in this package carries exactly one opcode and nothing else.
## What is here
| Count | Content |
|------:|---------|
| 1 | `SLOpcodeBase.sleela` — the shared single-opcode contract |
| 1 | `SLOpcodeStream.sleela` — the verbatim, ordered opcode sequence driver |
| 156 | `SLOp*.sleela` — one class per opcode, codes **0–155** (the full ISA) |
| 1 | `OPCODES.md` — this document |
| 8 | `governance/` — the Registrar · Listener · Event Observer series (see `governance/GOVERNANCE.md`) |
| 6 | `running/` — grouping, conditional-reactive, and warming helpers (see `running/RUNNING.md`) |
Codes **0–97** are the **base 98** opcodes (`OP_NOP` … `OP_AUDIO_PLATFORM`).
Codes **98–102** are the five array-extension opcodes added for syntax 1.4
(`OP_NEWARRAY`, `OP_ARRGET`, `OP_ARRSET`, `OP_ARRLEN`, `OP_ARRPUSH`). Codes
**103–154** complete the set: the operating-system system calls
(103–123, `OP_OS_*`), the GC/system ops (124 `OP_GC_HINT`, 125 `OP_RAN_MEM`),
the idea-canvas native-bridge ops (126–147, `OP_IC_*`), the VM-selection op
(148, `OP_VM_SELECT`), the Modium file-resolution scan (149, `OP_MODIUM_SCAN`),
and the tail ops `OP_UI_CALL` (150), `OP_SSEND` (151), `OP_CHECKCAST` (152),
`OP_INSTANCEOF` (153), `OP_DUP2` (154), and `OP_OSLS_CALL` (155). The package therefore ships **a
wrapper class for every opcode in the 156-opcode canonical ISA** (156 wrappers
total), mirroring `lib/vm/InstructionSet.sleela` one-for-one.
## The single-opcode contract
Every opcode class extends `SLOpcodeBase` and carries one `CODE` and one
`MNEMONIC`. The base defines the ordered contract the user asked for — *order
the opcodes toward the VM as SLeeLa source that immediately, carefully calls the
VM to the next instruction, then executes the single opcode*:
```
step(frame):
ip = advance(frame) // 1. carefully call the VM to the NEXT instruction (fetch)
return fire(frame, ip)// 2. execute THIS one opcode, return the next ip
```
This mirrors the authoritative native dispatch loop in `impl/core/sleela_core.c`:
```c
SLInstr in = vm->code[ip++]; /* fetch: advance to the next instruction */
switch (in.op) { ... } /* dispatch exactly one decoded opcode */
```
`advance()` is the `ip++` fetch; `fire()` is the single `switch` case. Because
each object does one fetch and one dispatch and then returns the next
instruction pointer, a program is simply a stream of these objects handed to the
VM in order.
### Ordering the stream toward the VM
`SLOpcodeStream` is the verbatim, ordered container. `run()` walks the stream in
program order and, for each opcode object, performs the contract — fetch the
next instruction, execute the one opcode — flowing control `1,2,3,…,N` exactly
as emitted. The VM owns the instruction pointer; the stream only hands it the
next single opcode. A negative return (from `OP_HALT` or a rejected opcode) ends
the stream, matching the runtime rule below.
### Governance — considering a program before it runs
A developer *may* run opcodes raw via `SLOpcodeStream.run()`. Usually, though, a
program should be **considered before, watched during, and judged after** it
runs. The `governance/` sub-family adds that discretion in SLeeLa herself: a
**Registrar** considers the program A → B before any opcode runs, a **Listener**
confirms the admitted sequence fits the live VM program as it comes, and an
**Event Observer** decides whether the operations form a musical, ordered process
about architecture, breadth, height, and purpose — issuing warnings or patching
faults with known symbol maps. SLeeLa and the VM both listen for ordering at the
`BEFORE` / `DURING` / `AFTER` phases. See `governance/GOVERNANCE.md`.
### Running helpers — grouping, conditional-reactive, warming
Beyond a flat stream, the `running/` sub-family offers richer ways to run
opcodes: **grouping** (`SLOpcodeGroup`, `SLOpcodeGroupSet`) runs cohesive
clusters as units; a **conditional-reactive** layer (`SLOpcodeCondition`,
`SLOpcodeConditionalReactive`, `SLOpcodeReactorBank`) reacts to program state by
warming, gating, running, or skipping a group; and **warming**
(`SLOpcodeWarmer`) readies hot paths before they run. These compose with the
governance series. See `running/RUNNING.md`.
## Native bridge and the runtime rule
The two primitives below the SLeeLa layer are:
- `sleela_opcode_vm_next(frame)` — the fetch (advance the instruction pointer).
- `sleela_opcode_execute_one(frame, code, ip)` — dispatch exactly one opcode.
Consistent with `lib/vm/OPCODE-MAP.md`, an **unknown opcode is rejected, never
silently treated as a no-op**: `execute_one` returns `-1` and records
`"unsupported opcode"`. `OP_HALT` also returns `-1` to stop the stream. The
authoritative execution semantics remain in `/impl/core`; this bridge models the
fetch/dispatch discipline and the mnemonic table (156 entries, codes 0–155).
Build and self-test:
```sh
cd native
make test # builds + self-tests audio, crypto, and opcode bridges
```
---
## Why 98 opcodes is complete for a modern program and developer
A deliberate claim of this ISA is that a compact, well-chosen set of 98 opcodes
(codes 0–97) is **functionally complete** for building modern software — not
merely Turing-complete in theory, but practically sufficient for the programs a
working developer actually writes. The set is small because it is organised by
*capability*, and each capability is covered without redundant encodings:
**1. Computation and data flow (0–22).**
Constants, stack discipline (`OP_POP`, `OP_DUP`), global and local load/store,
the full arithmetic set (`ADD` … `NEG`), the full comparison set (`EQ` … `GE`),
and boolean logic (`AND`, `OR`, `NOT`). Any pure expression a program evaluates
reduces to these. `OP_ADD` is overloaded for string concatenation, so text
assembly needs no separate opcode.
**2. Control flow and procedures (23–27).**
`OP_JMP`, `OP_JMPF`, `OP_CALL`, `OP_RET`. Conditional and unconditional branching
plus call/return are the complete basis for every higher-level control
structure — `if`, `while`, `for`, `switch`, recursion, and early return are all
lowered onto exactly these four. No structured-control opcodes are needed because
structure is a *compiler* concern, not an *ISA* concern.
**3. Observable output (27).**
`OP_PRINT` gives programs a direct, honest observable effect.
**4. Concurrency and synchronization (28–33).**
`OP_SPAWN`, `OP_JOINALL`, `OP_LOCK`, `OP_UNLOCK`, `OP_SEND`, `OP_RECV`. Threads,
joins, mutual exclusion, and channel message-passing. This is enough to express
both shared-memory and message-passing concurrency — the two models modern
software actually uses — without baking in a specific scheduler.
**5. Networking (34–42).**
Full socket life-cycle (`LISTEN`, `ACCEPT`, `CONNECT`, `SOCKREAD`, `SOCKWRITE`,
`SOCKCLOSE`) plus pipes and FIFOs. A server or client program needs no more than
these to speak to the outside world; higher protocols (HTTP, RMI) are libraries
built *on* them.
**6. Files and the filesystem (43–47).**
Open, read, write, close, unlink. The complete minimal set for durable storage.
**7. Lifecycle (48).**
`OP_HALT` cleanly stops the machine.
**8. Time (49–57).**
UTC and monotonic clocks, precision, location, and interchange formats (HTTP
date, JSON, NTP). Modern programs are deeply time-aware — logging, scheduling,
tokens, caching — so time is a first-class ISA capability rather than an
afterthought.
**9. Structured data (58–62).**
Struct construction, field get/set, and pack/unpack to JSON. This gives
programs composite records and a serialization boundary in five opcodes.
**10. Honest measurement and reach — Synchro, Munction, Best-of (63–90).**
These three capability groups cover network probing with honest measurement,
reach composition, and configurable route/accuracy selection — the operations a
modern distributed program performs when it must *choose* among peers and report
truthfully about what it did.
**11. Native media (91–97).**
The audio job life-cycle and host-platform query, delegating heavy media work to
the native bridge rather than pretending the VM is a mixer.
### Why not fewer, and why not many more
- **Not fewer:** every group above is a distinct *capability class*. Removing any
one removes a kind of program a developer must write (you cannot drop sockets
and still write a server). Within each group the opcodes are orthogonal — no
opcode is expressible as a short, obvious sequence of the others at the same
layer.
- **Not many more:** richer behaviour is layered as *libraries and compiler
lowering*, not new opcodes. `if`/`while`/`for`, exceptions, iterators,
pattern matching, HTTP, TLS, and the rest of the standard library all compile
down to this set. Keeping the ISA at ~100 opcodes keeps the VM small enough to
audit, port, and verify — the native dispatch is a single reviewable `switch`.
The array extension (98–102) demonstrates the growth discipline: dynamic arrays
were a genuinely new *capability* (a growable indexed sequence) that the base 98
could not express cheaply, so five opcodes were appended **at the end** so no
existing serialized-artifact opcode number shifted. New opcodes are added only
when a true new capability appears, following the maintenance rule in
`lib/vm/OPCODE-MAP.md`.
**The result:** a developer writing a modern program — concurrent, networked,
time-aware, persisting structured data, producing media, and choosing among
peers honestly — is fully served by the 98 base opcodes, with the whole ISA
remaining small enough to hold in your head and trust.
**Max Rupplin — MEARVK LLC — 2026**