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.
<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 /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:
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:
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 reviewableswitch.
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