Home /Modules/impl/NATIVE-MATH-VM-INTEGRATION-PLAN.md

NATIVE-MATH-VM-INTEGRATION-PLAN.md

impl/subjects/math/NATIVE-MATH-VM-INTEGRATION-PLAN.md · 204 line(s) · markdown

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 typed array/linear-algebra integration is also required:

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:

Opcodes 182–194 remain unchanged. The reserved native-math allocation is:

RangeFamily
195–199Shared native math
200–207Vector
208–215Matrix
216–223Complex
224–231Decomposition
232–281Transform

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:

  1. Validate each operand is an active VM array handle.
  2. Validate every element is a supported numeric tag (SL_INT, SL_INT128, or SL_DOUBLE); reject mixed/non-numeric data unless the specific operation explicitly defines a conversion.
  3. Validate dimensions, multiplication overflow, required lengths, and output capacity before allocating scratch buffers or entering a kernel.
  4. Keep all participating array values rooted on the executing VM stack until dispatch and write-back finish. Do not pop the roots early.
  5. 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.
  6. Marshal into bridge-owned scratch buffers. Never give the kernel a pointer into a resizable SLArrayInstance::elems allocation.
  7. Copy results back only after a successful kernel status. On failure, leave output arrays unchanged.
  8. 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:

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:

  1. Vector
  2. Matrix
  3. Complex
  4. Decomposition
  5. 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:

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

Scalar integration

Typed operation integration

Delivery sequence

  1. 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.
  2. Harden array handle identity across all array operations and GC slot reuse; slot-only handles cannot reject stale references after reuse.
  3. Implement the VM-owned array validation, rooting, locking, and transactional snapshot/write-back adapter.
  4. Connect the existing typed C ABI through that adapter; preserve VM ownership and never retain pointers into VM array storage.
  5. Append and validate OP_MATH_ARRAY_CALL at 196 only after steps 3–4 define its complete stack, shape, and aliasing contract.
  6. Add deterministic typed compiler lowering and explicit diagnostics; retain the scalar lowering at 195.
  7. Add scalar and typed-array regression coverage, including artifact round-trip, fallback, ownership, marshalling, and numerical behavior.
  8. 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.
  9. 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.