Native Math VM Integration — Completion Plan
Integration objective
Complete the original native-math integration rather than replacing it with a new or reduced implementation. The deliverable is one coherent path from SLeeLa source through compiler lowering and VM dispatch to the existing native math C ABIs, with deterministic results and explicit failure behavior.
The original scalar math integration is now restored on current master:
- The scalar IEEE-754 kernel and stable function-ID table are preserved.
OP_MATH_CALLis appended at 195, with compiler lowering and native VM dispatch adapted from the historical implementation.- The original SLeeLa bytecode fallback remains available when the native kernel declines a request.
- The historical branch's opcode numbering and stale enum were not imported.
The typed array/linear-algebra integration is also required:
- Use the existing
slmath_vm_dispatchC ABI andslmath_bufferdescriptors. - Support vector, matrix, complex, decomposition, and transform operations in that canonical family order.
- Do not create a second VM array representation or expose VM pointers to a kernel as long-lived storage.
ISA and compatibility constraints
The executable source/native ISA now ends at opcode 195. Scalar native math dispatch is implemented at 195; typed-array dispatch and later family opcodes remain reserved. Existing assignments 0–194 are frozen and append-only, including the fixed IPC block:
- 179 —
OP_IPC_OPEN - 180 —
OP_IPC_CALL - 181 —
OP_IPC_CLOSE
Opcodes 182–194 remain unchanged. The reserved native-math allocation is:
| Range | Family |
|---|---|
| 195–199 | Shared native math |
| 200–207 | Vector |
| 208–215 | Matrix |
| 216–223 | Complex |
| 224–231 | Decomposition |
| 232–281 | Transform |
Within the shared block, 195 is implemented as scalar OP_MATH_CALL, 196 is
reserved for typed OP_MATH_ARRAY_CALL, and 197–199 remain vacant. All ranges are
inclusive; unused positions remain reserved for their family. Transform has
50 positions, 232 through 281.
Except for implemented opcode 195, these are reservations, not executable
instructions. Do not insert placeholder entries into the source registry or
native enum. Reserved IDs must fail closed until implementation, compiler
lowering, dispatch, artifact validation, supported VM-generation contracts,
tests, and documentation land together.
Function IDs and typed operation IDs remain distinct from opcode IDs. The
historical native-math branch's assignment of OP_MATH_CALL to 179 is invalid
for this repository state.
VM-owned array adapter contract
The implementation contract is maintained in VM-ARRAY-ADAPTER-CONTRACT.md.
The 2026-11-15 source audit found an additional prerequisite: array handles are
currently slot-based and the active-slot validity check has no incarnation
counter. Harden handle identity consistently across all array opcodes and GC
slot reuse before implementing the math adapter. See
VM-ARRAY-ADAPTER-SOURCE-AUDIT.md.
It fixes the ownership, lock, snapshot, shape, alias, rollback, and qualification requirements before opcode 196 is activated. In particular, the first adapter transaction uses the existing array_mtx across validation, snapshot, native dispatch, and commit; the interpreter's workers_cached fast path is not treated as permission to bypass native-dispatch synchronization. No placeholder opcode is added for any reserved position.
VM-generation and decompiler boundary
The premium SLVM/1 through SLVM/11 runners are generated as thin, grade-specific
admission layers over the shared impl/build/libslcore.a. Their Makefiles link
that archive rather than carrying independent opcode dispatch loops. Adding
the math kernel object to SLCORE_OBJS therefore supplies opcode 195 to all
eleven runner builds; each runner still requires a build/self-check against the
new archive before release qualification.
The current native decompiler under decompiler/ decodes native executable
and object-code instruction sets (x86, x86-64, ARM, AArch64). It does not
currently parse the SLeeLa .sleela VM artifact container or its bytecode
stream. Consequently, it has no SLeeLa VM opcode decoder in which to add a
special OP_MATH_CALL rendering. A separate SLeeLa artifact reader and
bytecode-to-SLIR path is required before decompiler support can be claimed.
Do not confuse this with the existing native-binary disassembler.
VM array ownership and safety contract
VM arrays remain SL_ARRAY values containing VM-local handles into the
existing bounded SLArrayInstance table. The VM owns allocation, GC
reachability, element tags, and lifetime.
Before a native array operation:
- Validate each operand is an active VM array handle.
- Validate every element is a supported numeric tag (
SL_INT,SL_INT128, orSL_DOUBLE); reject mixed/non-numeric data unless the specific operation explicitly defines a conversion. - Validate dimensions, multiplication overflow, required lengths, and output capacity before allocating scratch buffers or entering a kernel.
- Keep all participating array values rooted on the executing VM stack until dispatch and write-back finish. Do not pop the roots early.
- Serialize access to participating arrays for the complete snapshot/kernel/ write-back transaction, or use an equivalent pin/version protocol that prevents concurrent mutation and reclamation.
- Marshal into bridge-owned scratch buffers. Never give the kernel a pointer
into a resizable
SLArrayInstance::elemsallocation. - Copy results back only after a successful kernel status. On failure, leave output arrays unchanged.
- Release locks and scratch allocations on every success and error path.
Native kernels are synchronous and must not retain descriptor pointers after return. The VM remains the sole owner of all source and destination arrays. Aliasing rules are operation-specific and must be validated before dispatch.
Typed buffer and shape contract
The existing slmath_buffer descriptor carries:
data: bridge-owneddoublestorage for the duration of dispatch;length: allocated element count;rowsandcols: explicit logical shape.
Shape products must be checked for size_t overflow. The VM adapter must
validate both descriptor capacity and the operation's shape constraints before
calling slmath_vm_dispatch. Dimensions must be explicit at the SLeeLa
call/lowering boundary; they must not be guessed from a flat array's length.
Kernel dispatch and operation families
Keep the scalar C ABI (sl_math_kernel_*) and typed structure C ABI
(slmath_vm_dispatch) as distinct, versionable interfaces behind one VM-owned
dispatch boundary. The scalar function-ID table remains stable and append-only.
Typed operation IDs remain those declared by linear_algebra.h.
Canonical extension order:
- Vector
- Matrix
- Complex
- Decomposition
- Transform
Do not allocate extra opcodes for individual math functions unless a reviewed implementation proves one generic dispatch instruction cannot express the required contract.
Compiler and artifact contract
Compiler lowering must be deterministic:
- Resolve supported scalar names to stable scalar function IDs.
- Resolve typed operations to stable operation IDs.
- Emit all operands and dimensions in the documented stack order.
- Reject unsupported arity, type, or shape combinations at compile time where statically knowable; retain runtime checks for dynamic values.
- Never silently substitute a different native operation.
- Preserve scalar bytecode fallback only for the scalar ABI's documented decline case; typed-array validation/kernel errors are explicit failures.
Artifact validation must reject unknown operation IDs, invalid operands, impossible argument counts, and malformed stack contracts before execution.
Required regression coverage
Array ownership and marshalling
- Invalid, stale, and wrong-type handles.
- Empty arrays, unsupported element tags, mixed numeric tags, and conversion boundaries.
- Dimension/length mismatch and integer overflow in shape products.
- Output capacity failures and allocation failures.
- Input/output aliasing, including exact aliases where supported.
- GC pressure while arrays are rooted; verify no use-after-free or stale write.
- Concurrent readers/writers; verify transaction semantics and no partial write-back.
- Kernel failure leaves destination arrays unchanged.
Scalar integration
- Every scalar function ID, exact arity, constants, and invalid IDs.
- Numeric conversion boundaries and non-finite IEEE-754 behavior.
- Native success and bytecode fallback when the native kernel declines.
- Compiler lowering and artifact round-trip preserve function IDs.
Typed operation integration
- Positive and negative cases for each vector, matrix, complex, decomposition, and transform operation.
- Numerical tolerances, dimensions, aliasing, singularity, and convergence behavior.
- Cross-platform C ABI layout and symbol checks.
Delivery sequence
- Recover and reconcile the original scalar integration against current master — complete: opcode 195, stable function-ID lowering, VM dispatch, C ABI linkage, artifact operand validation, and the original Core bytecode fallback are integrated.
- Harden array handle identity across all array operations and GC slot reuse; slot-only handles cannot reject stale references after reuse.
- Implement the VM-owned array validation, rooting, locking, and transactional snapshot/write-back adapter.
- Connect the existing typed C ABI through that adapter; preserve VM ownership and never retain pointers into VM array storage.
- Append and validate
OP_MATH_ARRAY_CALLat 196 only after steps 3–4 define its complete stack, shape, and aliasing contract. - Add deterministic typed compiler lowering and explicit diagnostics; retain the scalar lowering at 195.
- Add scalar and typed-array regression coverage, including artifact round-trip, fallback, ownership, marshalling, and numerical behavior.
- Update the opcode map, SLVM/1–11 shared-Core compatibility contracts, API docs, and trusted manifests. Add a dedicated SLeeLa VM-artifact decoder to the decompiler before claiming bytecode decompilation support.
- Run targeted scalar and typed qualification, then the broader platform/build matrix. Do not create broad CI runs before the targeted source and build causes are understood.
Do not describe standalone C ABI qualification as proof of VM bytecode integration. Do not mark this integration complete until the source compiler, artifact loader, VM dispatch, tests, decompiler boundary, and documentation all agree.