# 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 stable `SLMATHFunction` ID table and the original fallback stack contract `[fallback marker, helper-name String, numeric arguments...]`. - 196 — `OP_MATH_ARRAY_CALL`: planned typed VM-array dispatch through `slmath_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`](NATIVE-MATH-VM-INTEGRATION-PLAN.md). ## Allocation and integration rules 1. Preserve all existing opcode assignments 0–194 exactly. 2. Keep each future math family within its allocated inclusive range. 3. Leave unused positions vacant; never borrow them for another family. 4. Keep scalar math function IDs and typed operation IDs separate from opcode IDs. One opcode may dispatch multiple stable function/operation IDs. 5. Keep VM arrays VM-owned. Native kernels receive only bridge-owned snapshots or buffers valid for the synchronous call. 6. Older VM generations must reject unsupported opcodes explicitly; they must never reinterpret them. 7. 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.