Home /Modules/vm/OPCODE-MAP.md

OPCODE-MAP.md

lib/vm/OPCODE-MAP.md · 339 line(s) · markdown

SLeeLa VM Opcode Map

Max Rupplin - MEARVK LLC - 2026

This is the human-readable support map for the canonical source-defined SLeeLa ISA in lib/vm/InstructionSet.sleela.

Canonical ordering and allocation catalog

lib/vm/InstructionSet.sleela is the sole authoritative ordered source registry; the native SLOp enum in impl/core/sleela_core.h must match it exactly by mnemonic and numeric position. tools/isa/opcode-registry-3.0.json is the machine-readable allocation/status catalog, not a second source of opcode assignments. Its verifier checks the source registry, native enum, contiguous family allocations, and the complete reserved tail through 281:

python3 tools/verify-opcode-registry.py
make -C impl test-opcode-registry

The standard make -C impl test suite runs this verifier. The sleela-build.py inventory-lib gate also runs it before accepting the library inventory. Do not reorder or renumber existing entries to make a family look tidier: preserve IDs and add new executable instructions only through the append-only registry workflow. Reserved IDs are family-owned and remain absent from the executable enum and source opcode records until the full implementation is ready.

Compatibility contract (CI-gated): the frozen pre-OSLS ISA contains 155 opcodes (0..154), including the original OS-call range 103–123. OP_OSLS_CALL is the append-only 156th entry (155). tools/verify-osls-isa-extension.py compares the complete source and native enum sequences against tools/isa/osls-isa-baseline-155.txt; the cross-platform workflow also builds and executes the OSLS native registry and VM binding tests. The tail groups are the array ops (98–102), 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_*, from idea/realtime), the VM-selection service op (148, OP_VM_SELECT), the Modium file-resolution scan op (149, OP_MODIUM_SCAN), OP_UI_CALL (150), OP_SSEND (151), and runtime type/stack ops OP_CHECKCAST (152), OP_INSTANCEOF (153), OP_DUP2 (154), and OP_OSLS_CALL (155) — all appended to the end of the enum so earlier opcode numbers are unchanged.

Sync note: the source registry, native enum, and map now cover the appended OP_IC_* group (126–147), OP_VM_SELECT (148), OP_MODIUM_SCAN (149), and opcodes 150–155. OP_OSLS_CALL (155) dispatches the typed osls_* ABI binding table. The coverage checks compare the ordered source records against the native enum; CI remains the final build-level verification. OP_VM_SELECT (148) is the service-exit seam the Sleela VM selector (virtual-machine/vm-version/SLVmRegistry + the SLVmVersionNNN manifests) binds to, so choosing a VM parks a VM-exit the host services by building and booting the chosen version's native main.

CodeOpcodeRuntime statusNative dispatch
00OP_NOPImplementedimpl/core/sleela_core.c
01OP_CONSTImplementedimpl/core/sleela_core.c
02OP_POPImplementedimpl/core/sleela_core.c
03OP_DUPImplementedimpl/core/sleela_core.c
04OP_LOADGImplementedimpl/core/sleela_core.c
05OP_STOREGImplementedimpl/core/sleela_core.c
06OP_LOADLImplementedimpl/core/sleela_core.c
07OP_STORELImplementedimpl/core/sleela_core.c
08OP_ADDImplementedimpl/core/sleela_core.c
09OP_SUBImplementedimpl/core/sleela_core.c
10OP_MULImplementedimpl/core/sleela_core.c
11OP_DIVImplementedimpl/core/sleela_core.c
12OP_MODImplementedimpl/core/sleela_core.c
13OP_NEGImplementedimpl/core/sleela_core.c
14OP_EQImplementedimpl/core/sleela_core.c
15OP_NEImplementedimpl/core/sleela_core.c
16OP_LTImplementedimpl/core/sleela_core.c
17OP_LEImplementedimpl/core/sleela_core.c
18OP_GTImplementedimpl/core/sleela_core.c
19OP_GEImplementedimpl/core/sleela_core.c
20OP_ANDImplementedimpl/core/sleela_core.c
21OP_ORImplementedimpl/core/sleela_core.c
22OP_NOTImplementedimpl/core/sleela_core.c
23OP_JMPImplementedimpl/core/sleela_core.c
24OP_JMPFImplementedimpl/core/sleela_core.c
25OP_CALLImplementedimpl/core/sleela_core.c
26OP_RETImplementedimpl/core/sleela_core.c
27OP_PRINTImplementedimpl/core/sleela_core.c
28OP_SPAWNImplementedimpl/core/sleela_core.c
29OP_JOINALLImplementedimpl/core/sleela_core.c
30OP_LOCKImplementedimpl/core/sleela_core.c
31OP_UNLOCKImplementedimpl/core/sleela_core.c
32OP_SENDImplementedimpl/core/sleela_core.c
33OP_RECVImplementedimpl/core/sleela_core.c
34OP_LISTENImplementedimpl/core/sleela_core.c
35OP_ACCEPTImplementedimpl/core/sleela_core.c
36OP_CONNECTImplementedimpl/core/sleela_core.c
37OP_SOCKREADImplementedimpl/core/sleela_core.c
38OP_SOCKWRITEImplementedimpl/core/sleela_core.c
39OP_SOCKCLOSEImplementedimpl/core/sleela_core.c
40OP_PIPEImplementedimpl/core/sleela_core.c
41OP_PIPEPEERImplementedimpl/core/sleela_core.c
42OP_FIFO_MKImplementedimpl/core/sleela_core.c
43OP_FILEOPENImplementedimpl/core/sleela_core.c
44OP_FILEREADImplementedimpl/core/sleela_core.c
45OP_FILEWRITEImplementedimpl/core/sleela_core.c
46OP_FILECLOSEImplementedimpl/core/sleela_core.c
47OP_FILEUNLINKImplementedimpl/core/sleela_core.c
48OP_HALTImplementedimpl/core/sleela_core.c
49OP_TIME_UTC_MSImplementedimpl/core/sleela_core.c
50OP_TIME_UTC_NSImplementedimpl/core/sleela_core.c
51OP_TIME_MONO_NSImplementedimpl/core/sleela_core.c
52OP_TIME_PRECISION_MSImplementedimpl/core/sleela_core.c
53OP_TIME_LOCATIONImplementedimpl/core/sleela_core.c
54OP_TIME_HTTP_DATEImplementedimpl/core/sleela_core.c
55OP_TIME_JSONImplementedimpl/core/sleela_core.c
56OP_TIME_NTPImplementedimpl/core/sleela_core.c
57OP_TIME_SET_LOCATIONImplementedimpl/core/sleela_core.c
58OP_NEWSTRUCTImplementedimpl/core/sleela_core.c
59OP_GETFIELDImplementedimpl/core/sleela_core.c
60OP_SETFIELDImplementedimpl/core/sleela_core.c
61OP_STRUCTPACKImplementedimpl/core/sleela_core.c
62OP_STRUCTUNPACKImplementedimpl/core/sleela_core.c
63OP_SYN_OPENImplementedimpl/core/sleela_core.c
64OP_SYN_DISPATCHImplementedimpl/core/sleela_core.c
65OP_SYN_STATImplementedimpl/core/sleela_core.c
66OP_SYN_REPORTImplementedimpl/core/sleela_core.c
67OP_SYN_CLOSEImplementedimpl/core/sleela_core.c
68OP_MUN_STARTImplementedimpl/core/sleela_core.c
69OP_MUN_CONNECTImplementedimpl/core/sleela_core.c
70OP_MUN_ENABLEImplementedimpl/core/sleela_core.c
71OP_MUN_SENDImplementedimpl/core/sleela_core.c
72OP_MUN_THATCHImplementedimpl/core/sleela_core.c
73OP_MUN_CONSUMEImplementedimpl/core/sleela_core.c
74OP_MUN_LATCHImplementedimpl/core/sleela_core.c
75OP_MUN_RECEPTIONImplementedimpl/core/sleela_core.c
76OP_MUN_CLOSEImplementedimpl/core/sleela_core.c
77OP_BEST_NEWImplementedimpl/core/sleela_core.c
78OP_BEST_WEIGHTImplementedimpl/core/sleela_core.c
79OP_BEST_MINVERImplementedimpl/core/sleela_core.c
80OP_BEST_BUDGETImplementedimpl/core/sleela_core.c
81OP_BEST_CANDImplementedimpl/core/sleela_core.c
82OP_BEST_RECORDImplementedimpl/core/sleela_core.c
83OP_BEST_SCOREImplementedimpl/core/sleela_core.c
84OP_BEST_BESTImplementedimpl/core/sleela_core.c
85OP_BEST_STATImplementedimpl/core/sleela_core.c
86OP_BEST_CHOICEImplementedimpl/core/sleela_core.c
87OP_BEST_REPORTImplementedimpl/core/sleela_core.c
88OP_BEST_ARCHImplementedimpl/core/sleela_core.c
89OP_BEST_ARCH_STATEImplementedimpl/core/sleela_core.c
90OP_BEST_CLOSEImplementedimpl/core/sleela_core.c
91OP_AUDIO_NEWImplementedimpl/core/sleela_core.c
92OP_AUDIO_ADDImplementedimpl/core/sleela_core.c
93OP_AUDIO_CONTROLSImplementedimpl/core/sleela_core.c
94OP_AUDIO_VALIDATEImplementedimpl/core/sleela_core.c
95OP_AUDIO_RENDERImplementedimpl/core/sleela_core.c
96OP_AUDIO_CLOSEImplementedimpl/core/sleela_core.c
97OP_AUDIO_PLATFORMImplementedimpl/core/sleela_core.c
98OP_NEWARRAYImplementedimpl/core/sleela_core.c
99OP_ARRGETImplementedimpl/core/sleela_core.c
100OP_ARRSETImplementedimpl/core/sleela_core.c
101OP_ARRLENImplementedimpl/core/sleela_core.c
102OP_ARRPUSHImplementedimpl/core/sleela_core.c
103OP_OS_PLATFORMImplementedimpl/core/sleela_core.c (sleela_os.c)
104OP_OS_CAPABILITYImplementedimpl/core/sleela_core.c (sleela_os.c)
105OP_OS_GETENVImplementedimpl/core/sleela_core.c (sleela_os.c)
106OP_OS_SETENVImplementedimpl/core/sleela_core.c (sleela_os.c)
107OP_OS_CWDImplementedimpl/core/sleela_core.c (sleela_os.c)
108OP_OS_CHDIRImplementedimpl/core/sleela_core.c (sleela_os.c)
109OP_OS_HOSTNAMEImplementedimpl/core/sleela_core.c (sleela_os.c)
110OP_OS_USERNAMEImplementedimpl/core/sleela_core.c (sleela_os.c)
111OP_OS_TEMPDIRImplementedimpl/core/sleela_core.c (sleela_os.c)
112OP_OS_PIDImplementedimpl/core/sleela_core.c (sleela_os.c)
113OP_OS_EXISTSImplementedimpl/core/sleela_core.c (sleela_os.c)
114OP_OS_ISDIRImplementedimpl/core/sleela_core.c (sleela_os.c)
115OP_OS_FILESIZEImplementedimpl/core/sleela_core.c (sleela_os.c)
116OP_OS_MKDIRImplementedimpl/core/sleela_core.c (sleela_os.c)
117OP_OS_REMOVEImplementedimpl/core/sleela_core.c (sleela_os.c)
118OP_OS_RENAMEImplementedimpl/core/sleela_core.c (sleela_os.c)
119OP_OS_RUNImplementedimpl/core/sleela_core.c (sleela_os.c)
120OP_OS_SPAWNImplementedimpl/core/sleela_core.c (sleela_os.c)
121OP_OS_WAITImplementedimpl/core/sleela_core.c (sleela_os.c)
122OP_OS_KILLImplementedimpl/core/sleela_core.c (sleela_os.c)
123OP_OS_PCLOSEImplementedimpl/core/sleela_core.c (sleela_os.c)
124OP_GC_HINTImplementedimpl/core/sleela_core.c
125OP_RAN_MEMImplementedimpl/core/sleela_core.c
126OP_IC_CREATEImplementedimpl/core/sleela_core.c
127OP_IC_DESTROYImplementedimpl/core/sleela_core.c
128OP_IC_COLSImplementedimpl/core/sleela_core.c
129OP_IC_ROWSImplementedimpl/core/sleela_core.c
130OP_IC_COUNTImplementedimpl/core/sleela_core.c
131OP_IC_SETPARAMSImplementedimpl/core/sleela_core.c
132OP_IC_EXCITEImplementedimpl/core/sleela_core.c
133OP_IC_STEPImplementedimpl/core/sleela_core.c
134OP_IC_ADVANCEImplementedimpl/core/sleela_core.c
135OP_IC_TIMESTEPImplementedimpl/core/sleela_core.c
136OP_IC_INTENSITYImplementedimpl/core/sleela_core.c
137OP_IC_HASRENDImplementedimpl/core/sleela_core.c
138OP_IC_OPENWINImplementedimpl/core/sleela_core.c
139OP_IC_SHOULDCLOSEImplementedimpl/core/sleela_core.c
140OP_IC_PRESENTImplementedimpl/core/sleela_core.c
141OP_IC_RUNImplementedimpl/core/sleela_core.c
142OP_IC_SETPOLICYImplementedimpl/core/sleela_core.c
143OP_IC_POLICYImplementedimpl/core/sleela_core.c
144OP_IC_BACKENDImplementedimpl/core/sleela_core.c
145OP_IC_GPUAVAILImplementedimpl/core/sleela_core.c
146OP_IC_MEASHZImplementedimpl/core/sleela_core.c
147OP_IC_MIGRATEImplementedimpl/core/sleela_core.c
148OP_VM_SELECTImplementedimpl/core/sleela_core.c
149OP_MODIUM_SCANImplementedimpl/core/sleela_core.c
150OP_UI_CALLImplementedimpl/core/sleela_core.c
151OP_SSENDImplementedimpl/core/sleela_core.c
152OP_CHECKCASTImplementedimpl/core/sleela_core.c
153OP_INSTANCEOFImplementedimpl/core/sleela_core.c
154OP_DUP2Implementedimpl/core/sleela_core.c
155OP_OSLS_CALLImplementedimpl/core/sleela_core.c (os-level-support/osls_vm_bridge.c) — typed OSLS ABI registry; JSON result marshalling

156 | OP_BIGMUL | Implemented | impl/core/sleela_core.c 157 | OP_SLEEP | Implemented | impl/core/sleela_core.c 158 | OP_BIGADD | Implemented | impl/core/sleela_core.c 159 | OP_BIGDIVMOD | Implemented | impl/core/sleela_core.c 160 | OP_BIGSUB | Implemented | impl/core/sleela_core.c 161 | OP_BIGDIV | Implemented | impl/core/sleela_core.c 162 | OP_BIGISQRT | Implemented | impl/core/sleela_core.c 163 | OP_NATIVE_CALL | Implemented | impl/core/sleela_core.c 164 | OP_NATIVE_OPEN | Implemented | impl/core/sleela_core.c 165 | OP_NATIVE_CLOSE | Implemented | impl/core/sleela_core.c 166 | OP_JSTR_LENGTH | Implemented | impl/core/sleela_core.c 167 | OP_JSTR_CHAR_AT | Implemented | impl/core/sleela_core.c 168 | OP_JSTR_CODE_POINT_AT | Implemented | impl/core/sleela_core.c 169 | OP_JSTR_CODE_POINT_COUNT | Implemented | impl/core/sleela_core.c 170 | OP_JSTR_OFFSET_BY_CODE_POINTS | Implemented | impl/core/sleela_core.c 171 | OP_JSTR_SUBSTRING | Implemented | impl/core/sleela_core.c 172 | OP_JSTR_CONCAT | Implemented | impl/core/sleela_core.c 173 | OP_JSTR_HASH_CODE | Implemented | impl/core/sleela_core.c 174 | OP_JSTR_COMPARE_TO | Implemented | impl/core/sleela_core.c 175 | OP_JSTR_FROM_UTF8 | Implemented | impl/core/sleela_core.c 176 | OP_TRY_PUSH | Implemented | impl/core/sleela_core.c 177 | OP_TRY_POP | Implemented | impl/core/sleela_core.c 178 | OP_THROW | Implemented | impl/core/sleela_core.c 179 | OP_IPC_OPEN | Reserved; fail-closed pending process supervisor and VM worker table | impl/core/sleela_core.c 180 | OP_IPC_CALL | Reserved; fail-closed pending process supervisor and VM worker table | impl/core/sleela_core.c 181 | OP_IPC_CLOSE | Reserved; fail-closed pending process supervisor and VM worker table | impl/core/sleela_core.c 182 | OP_REF | Implemented | impl/core/sleela_core.c 183 | OP_JSTR_TO_UTF8 | Implemented | impl/core/sleela_core.c 184 | OP_JSTR_FROM_CODE_UNIT | Implemented | impl/core/sleela_core.c 185 | OP_BAND | Implemented | impl/core/sleela_core.c 186 | OP_BOR | Implemented | impl/core/sleela_core.c 187 | OP_BXOR | Implemented | impl/core/sleela_core.c 188 | OP_BSHL | Implemented | impl/core/sleela_core.c 189 | OP_BSHR | Implemented | impl/core/sleela_core.c 190 | OP_BUSHR | Implemented | impl/core/sleela_core.c 191 | OP_BNOT | Implemented | impl/core/sleela_core.c 192 | OP_CHARSTR | Implemented | impl/core/sleela_core.c 193 | OP_ADDCHAR | Implemented | impl/core/sleela_core.c 194 | OP_NEWARRAYND | Implemented | impl/core/sleela_core.c 195 | OP_MATH_CALL | Implemented | impl/core/sleela_core.c (sl_math_kernel_* C ABI; Core bytecode fallback)

The operating-system opcodes (OP_OS_*) are the host System Call API: the os* built-ins (osRun/osSpawn/osGetEnv/osExists/...) lower to these opcodes, which the VM services through impl/core/sleela_os.c on Windows (Win32), Linux, and macOS (POSIX). A spawned process is a VM-local bounded handle, the same discipline as sockets and files. Source-side they are mirrored by the SLISAOs* classes in lib/vm/InstructionSet.sleela and surfaced to a VM via lib/vm/SleelaVMSystemCallBridge.sleela. Because every VM generation (SLVM/1 through SLVM/11) shares this one ISA, the system-call surface is available to all of them, not just the base VM.

Native IPC worker opcode reservation

Opcodes 179–181 are append-only ABI reservations: OP_IPC_OPEN, OP_IPC_CALL, and OP_IPC_CLOSE. Their numeric IDs are fixed and included in the native/source ISA equality check. Artifact validation checks their operand shapes. The interpreter currently rejects all three with an explicit fail-closed diagnostic; they do not launch a worker or create a live handle yet. Runtime execution becomes available only after the native process supervisor, host capability authorizer, and VM-owned worker-handle table are integrated.

Object reference opcode

Opcode 182 is the append-only OP_REF, the VM-level view of an object (the second tier of the two-tier object model; see /POINTERS.md). Its single operand packs a selector in the low 4 bits and, for DEREF, the class type index above them: a = (typeIndex << 4) | selector. Selectors: OF, DEREF, VALID, ID, GEN, TYPE, FIELDS, BYTES, AGE, OLD, LIVE, LIMIT.

A ref is an ordinary SL_INT packed as (generation << 32) | (slot + 1), so 0 is the null ref. It is a weak, generation-checked handle, never a machine address: every use validates the slot (in range, active, same generation) and a ref that fails validation reads as invalid rather than aliasing a different object. Artifact validation checks the selector and the class operand. The VM artifact ABI minor version advances to 7; artifact serialization layout is unchanged, and older runtimes reject artifacts that contain the new opcode.

Reserved native math opcode ranges

The native-math ISA allocation is reserved by family so future additions do not fragment the instruction set. Opcode 195 is implemented; all remaining positions in these ranges are allocation reservations only and must be rejected as unsupported until each instruction is implemented and validated across the compiler, artifact loader, native VM, and supported VM generations.

Opcode rangeFamilyAllocation
195–199Shared native math195 OP_MATH_CALL implemented; 196 planned for OP_MATH_ARRAY_CALL; 197–199 reserved
200–207Vector8 positions
208–215Matrix8 positions
216–223Complex8 positions
224–231Decomposition8 positions
232–281Transform50 positions

All ranges are inclusive. Vacant positions remain reserved for their family; they are not general-purpose gaps. In particular, Transform begins at 232 and ends at 281. Existing opcode IDs 0–194, including IPC 179–181, are unchanged. Opcode 195 is the first executable math-family instruction. Do not create enum placeholders or source-registry entries for reserved IDs: the source/native ISA equality verifier must continue to describe executable instructions only.

Runtime rule

The authoritative runtime is /impl/core. An opcode not present in the canonical map is not silently ignored or treated as a no-op.

When an unknown/unsupported opcode reaches the VM dispatch loop:

  1. the VM writes a diagnostic to standard error; and
  2. if SLEELA_OPCODE_LOG is set to a writable path, the diagnostic is appended to that log instead; and
  3. execution is rejected with an unsupported opcode VM error.

Example:

SLEELA_OPCODE_LOG=/var/log/sleela/opcodes.log ./impl/build/sleela ...

The environment variable is optional. Standard error remains the fallback when the configured log cannot be opened.

Maintenance rule

Any new source-defined opcode must be added in this order:

  1. lib/vm/InstructionSet.sleela
  2. native SLOp enum in impl/core/sleela_core.h
  3. native dispatch in impl/core/sleela_core.c
  4. this support map
  5. the source/ISA coverage verifier
  6. SLVM/1 through SLVM/11 source-to-VM contracts.

A source opcode is not considered supported merely because it appears in the source registry. Native dispatch is required.

The OP_OS_* system-call group followed this rule end to end: added to InstructionSet.sleela (step 1), the native SLOp enum (step 2) and dispatch (step 3), this map (step 4), and reflected in the SLVM/1–11 runtime-services contract (step 6) via RUNTIME-SERVICES.md.