Native math opcode allocation and VM integration plan
Existing ISA boundary
The executable source/native ISA now ends at opcode 195. Existing assignments 0–194 are frozen and append-only; 195 is the first implemented math opcode. In particular, the Native IPC worker opcodes remain one contiguous group:
- 179 —
OP_IPC_OPEN - 180 —
OP_IPC_CALL - 181 —
OP_IPC_CLOSE
Opcodes 182–194 retain their existing meanings. The old native-math branches
assigned OP_MATH_CALL to 179; that assignment conflicts with IPC and must
never be imported.
Reserved native-math allocation
The machine-readable allocation mirror is
tools/isa/opcode-registry-3.0.json. It records assigned instruction
IDs, family boundaries, fail-closed reservations, and the current operand
contract documentation status. tools/verify-opcode-registry.py checks this
catalog against the authoritative lib/vm/InstructionSet.sleela source order
and native SLOp enum. The catalog does not make a reserved ID executable.
The following ranges are now the canonical family allocation. Opcode 195 is implemented; all other vacant positions remain reserved for their family. Ranges are inclusive and must not be filled by unrelated instructions.
| Opcode range | Family | Reserved positions |
|---|---|---|
| 195–199 | Shared native math | 195 implemented; 196–199 reserved |
| 200–207 | Vector | 8 |
| 208–215 | Matrix | 8 |
| 216–223 | Complex | 8 |
| 224–231 | Decomposition | 8 |
| 232–281 | Transform | 50 |
The shared native-math block has these initial planned identifiers:
- 195 —
OP_MATH_CALL: implemented scalar IEEE-754 dispatch using the stableSLMATHFunctionID table and the original fallback stack contract[fallback marker, helper-name String, numeric arguments...]. - 196 —
OP_MATH_ARRAY_CALL: planned typed VM-array dispatch throughslmath_vm_dispatch, after the VM ownership, validation, and marshalling adapter is implemented. - 197–199 remain reserved for future shared math dispatch extensions.
The canonical family order is Vector, Matrix, Complex, Decomposition, Transform. Transform begins at 232 and ends at 281 inclusive. The 50-position Transform block is deliberate capacity, not a claim that 50 instructions already exist.
Reservation is not implementation. Opcode 195 is the one implemented
exception in the allocation block. Do not add placeholder instructions for
196–281 to InstructionSet.sleela or the native SLOp enum, and do not
advertise reserved IDs as executable. A reserved ID becomes an executable opcode only when its
compiler contract, native dispatch, artifact validation, supported VM
generation behavior, tests, and documentation are implemented together.
Unknown/reserved IDs must fail closed. Never renumber or repurpose an existing
opcode.
What is integrated now
The standalone native scalar math C ABI is present in math_kernel.hpp,
sleela_math_kernel_c.h/.cpp, with an opt-in
make -C impl test-native-math-kernel qualification target. It covers the
IEEE-754 scalar function set and stable function-ID/arity/method-name dispatch.
The native linear-algebra C ABI is present in linear_algebra.h/.cpp, with an
opt-in make -C impl test-linear-algebra qualification target. It covers
vectors, matrices, LU/QR, complex arithmetic, eigen decomposition, FFT, and
typed buffer dispatch.
This is a native library boundary. Scalar OP_MATH_CALL now reaches this C ABI
from compiler-generated bytecode and preserves the Core helper fallback. The
typed array ABI still does not pin VM-owned arrays, validate VM object layouts,
or marshal VM arrays into typed descriptors. Standalone linear-algebra C ABI
tests must not be described as VM bytecode integration.
Required integration continuity
The VM work must complete the original scalar native-math integration as well
as the typed array/linear-algebra path. The scalar function-ID table,
sl_math_kernel_* C ABI, compiler lowering, native dispatch, and documented
bytecode fallback are not to be dropped or replaced by an array-only design.
The historical branch is a source of implementation behavior, not an ISA
source: its OP_MATH_CALL = 179 assignment conflicts with the fixed IPC block.
The full ownership, marshalling, compiler, artifact, regression, and delivery
contracts are maintained in
NATIVE-MATH-VM-INTEGRATION-PLAN.md.
Allocation and integration rules
- Preserve all existing opcode assignments 0–194 exactly.
- Keep each future math family within its allocated inclusive range.
- Leave unused positions vacant; never borrow them for another family.
- Keep scalar math function IDs and typed operation IDs separate from opcode IDs. One opcode may dispatch multiple stable function/operation IDs.
- Keep VM arrays VM-owned. Native kernels receive only bridge-owned snapshots or buffers valid for the synchronous call.
- Older VM generations must reject unsupported opcodes explicitly; they must never reinterpret them.
- Update source registry, native enum, compile-time assertions, dispatch, compiler, artifact validation, opcode map, VM generation contracts, tests, and trusted manifests as one coordinated implementation change.