@divmain/jdm-asm 0.2.1 → 0.2.3

package/src/runtime/index.ts

@@ -1,8 +0,0 @@
-// Main entry point - exports runtime components
-
-export * from './values';
-export * from './context';
-export * from './expressions';
-export * from './tables';
-export * from './memory';
-export * from './strings';

package/src/runtime/memory.ts

@@ -1,607 +0,0 @@
-// assembly/runtime/memory.ts (AssemblyScript)
-// Memory layout and management utilities for WASM linear memory
-
-import { writeString } from './strings';
-
-// ============================================================================
-// Memory Layout Constants
-// ============================================================================
-
-// Reserved space for null pointer trap (first 4 bytes)
-// Accessing address 0 should trap, catching null/nullish pointer bugs
-export const NULL_POINTER_TRAP_SIZE: usize = 4;
-
-// Fixed memory region offsets
-export const INPUT_BUFFER_START: usize = NULL_POINTER_TRAP_SIZE; // 0x0004
-
-// Schema-specific field layouts require different buffer sizes. Computing sizes at
-// compile time based on actual schema ensures optimal memory usage per decision.
-export let INPUT_BUFFER_SIZE: usize = 0;
-
-// Variable-length input data starts after the fixed input buffer
-export let INPUT_VAR_START: usize = 0;
-
-// Output buffer follows input variable data
-export let OUTPUT_START: usize = 0;
-
-// Computed at compilation time based on input/output schema field sizes
-export let OUTPUT_BUFFER_SIZE: usize = 0;
-
-// Variable-length output data starts after the fixed output buffer
-export let OUTPUT_VAR_START: usize = 0;
-
-// Runtime heap for intermediate values (temporary arrays, string concat buffers, etc.)
-export let HEAP_START: usize = 0;
-
-// ============================================================================
-// Header Constants
-// ============================================================================
-
-// Schema hash size in bytes
-export const SCHEMA_HASH_SIZE: usize = 8;
-
-// String descriptor format: [offset (4 bytes)] [length (4 bytes)]
-export const STRING_DESC_SIZE: usize = 8;
-
-// Array descriptor format: [offset (4 bytes)] [length (4 bytes)]
-export const ARRAY_DESC_SIZE: usize = 8;
-
-// ============================================================================
-// Memory Allocation
-// ============================================================================
-
-// Decision evaluation is single-pass (no GC needed), and most allocations are temporary
-// (freed after result is marshaled). Linear bump allocator is fast and simple.
-let heapPointer: usize = 0;
-
-/**
- * Initialize memory layout.
- *
- * This function must be called once at startup with the computed sizes
- * for the input and output buffers based on the schema.
- *
- * @param inputFixedSize - Size of fixed input fields in bytes
- * @param outputFixedSize - Size of fixed output fields in bytes
- */
-export function initializeMemoryLayout(inputFixedSize: usize, outputFixedSize: usize): void {
-  INPUT_BUFFER_SIZE = inputFixedSize;
-  INPUT_VAR_START = INPUT_BUFFER_START + inputFixedSize;
-
-  OUTPUT_BUFFER_SIZE = outputFixedSize;
-  OUTPUT_START = INPUT_VAR_START; // Output follows input variable data
-  OUTPUT_VAR_START = OUTPUT_START + outputFixedSize;
-
-  HEAP_START = OUTPUT_VAR_START; // Heap follows output variable data
-  heapPointer = HEAP_START; // Reset heap pointer
-}
-
-/**
- * Get the current memory layout info.
- *
- * @returns Object with all memory region offsets and sizes
- */
-export function getMemoryLayout(): MemoryLayout {
-  return new MemoryLayout(
-    NULL_POINTER_TRAP_SIZE,
-    INPUT_BUFFER_START,
-    INPUT_BUFFER_SIZE,
-    INPUT_VAR_START,
-    OUTPUT_START,
-    OUTPUT_BUFFER_SIZE,
-    OUTPUT_VAR_START,
-    HEAP_START,
-  );
-}
-
-/**
- * Memory layout information structure.
- */
-export class MemoryLayout {
-  nullPointerTrapSize: usize;
-  inputBufferStart: usize;
-  inputBufferSize: usize;
-  inputVarStart: usize;
-  outputStart: usize;
-  outputBufferSize: usize;
-  outputVarStart: usize;
-  heapStart: usize;
-
-  constructor(
-    nullPointerTrapSize: usize,
-    inputBufferStart: usize,
-    inputBufferSize: usize,
-    inputVarStart: usize,
-    outputStart: usize,
-    outputBufferSize: usize,
-    outputVarStart: usize,
-    heapStart: usize,
-  ) {
-    this.nullPointerTrapSize = nullPointerTrapSize;
-    this.inputBufferStart = inputBufferStart;
-    this.inputBufferSize = inputBufferSize;
-    this.inputVarStart = inputVarStart;
-    this.outputStart = outputStart;
-    this.outputBufferSize = outputBufferSize;
-    this.outputVarStart = outputVarStart;
-    this.heapStart = heapStart;
-  }
-}
-
-// ============================================================================
-// Simple Linear Heap Allocator
-// ============================================================================
-
-/**
- * Allocate memory from the runtime heap.
- *
- * A simple linear allocator - memory is never freed during a single evaluation.
- * Suitable for short-lived operations like decision table evaluation.
- *
- * Memory is never freed during a single evaluation because:
- * (1) evaluations are short-lived (milliseconds),
- * (2) heap is reset between evaluations, and
- * (3) avoiding free list management simplifies allocator and improves performance.
- *
- * @param size - Number of bytes to allocate (must be > 0)
- * @returns Pointer to allocated memory
- * @throws Calls abort() on OUT_OF_MEMORY - this is a critical error that halts execution
- */
-export function heapAlloc(size: usize): usize {
-  if (size == 0) return 0;
-
-  // Get current memory size in bytes (1 page = 64KB = 65536 bytes)
-  const memorySize: usize = (<usize>memory.size()) << 16;
-
-  // Align the heap pointer to 8-byte boundary
-  const alignedPtr = alignPtr(heapPointer, 8);
-
-  // Check for overflow when computing aligned pointer
-  // If alignedPtr wrapped around (became smaller than heapPointer), we've overflowed
-  if (alignedPtr < heapPointer) {
-    SetLastError(RuntimeErrorCode.OUT_OF_MEMORY);
-    return 0;
-  }
-
-  // Check for overflow when computing new heap pointer
-  // If newHeapPointer would wrap around, we've overflowed
-  const maxAllowedSize = memorySize - alignedPtr;
-  if (size > maxAllowedSize) {
-    SetLastError(RuntimeErrorCode.OUT_OF_MEMORY);
-    return 0;
-  }
-
-  const newHeapPointer = alignedPtr + size;
-
-  // Bounds check: ensure new heap pointer doesn't exceed memory
-  if (newHeapPointer > memorySize) {
-    SetLastError(RuntimeErrorCode.OUT_OF_MEMORY);
-    return 0;
-  }
-
-  // All checks passed, update heap pointer and return allocation
-  heapPointer = newHeapPointer;
-  return alignedPtr;
-}
-
-/**
- * Get the current heap pointer (next allocation will start here).
- *
- * @returns Current heap pointer address
- */
-export function getHeapPointer(): usize {
-  return heapPointer;
-}
-
-/**
- * Reset the heap pointer to the start of the heap region.
- *
- * This allows reusing heap memory for multiple evaluations.
- */
-export function resetHeap(): void {
-  heapPointer = HEAP_START;
-}
-
-/**
- * Save the current heap pointer state.
- *
- * @returns Current heap pointer address
- */
-export function saveHeapPointer(): usize {
-  return heapPointer;
-}
-
-/**
- * Restore the heap pointer to a previously saved state.
- *
- * @param saved - Saved heap pointer address from saveHeapPointer()
- */
-export function restoreHeapPointer(saved: usize): usize {
-  const old = heapPointer;
-  heapPointer = saved;
-  return old;
-}
-
-// ============================================================================
-// Pointer Utilities
-// ============================================================================
-
-/**
- * Align a pointer to the specified alignment boundary.
- *
- * @param ptr - Pointer to align
- * @param alignment - Alignment boundary (must be a power of 2)
- * @returns Aligned pointer
- */
-export function alignPtr(ptr: usize, alignment: usize): usize {
-  return (ptr + alignment - 1) & ~(alignment - 1);
-}
-
-/**
- * Check if a pointer is null (0).
- *
- * @param ptr - Pointer to check
- * @returns true if pointer is 0, false otherwise
- */
-export function isNullPtr(ptr: usize): bool {
-  return ptr == 0;
-}
-
-/**
- * Check if a pointer is valid (non-null and aligned).
- *
- * @param ptr - Pointer to check
- * @param alignment - Required alignment (default: 4 bytes)
- * @returns true if pointer is valid, false otherwise
- */
-export function isValidPtr(ptr: usize, alignment: usize = 4): bool {
-  if (ptr == 0) return false;
-  return (ptr & (alignment - 1)) == 0;
-}
-
-// ============================================================================
-// Buffer Access Helpers
-// ============================================================================
-
-/**
- * Get the pointer to a schema hash field.
- *
- * @param basePtr - Base pointer of the buffer
- * @returns Pointer to the schema hash field
- */
-export function getSchemaHashPtr(basePtr: usize): usize {
-  return basePtr;
-}
-
-/**
- * Read a schema hash from a buffer.
- *
- * @param basePtr - Base pointer of the buffer
- * @returns Schema hash as u64
- */
-export function readSchemaHash(basePtr: usize): u64 {
-  return load<u64>(basePtr);
-}
-
-/**
- * Write a schema hash to a buffer.
- *
- * @param basePtr - Base pointer of the buffer
- * @param hash - Schema hash to write
- */
-export function writeSchemaHash(basePtr: usize, hash: u64): void {
-  store<u64>(basePtr, hash);
-}
-
-/**
- * Get the pointer to a field in a fixed-size buffer.
- *
- * @param bufferPtr - Base pointer of the buffer
- * @param fieldOffset - Offset of the field from the buffer start
- * @returns Pointer to the field
- */
-export function getFieldPtr(bufferPtr: usize, fieldOffset: usize): usize {
-  return bufferPtr + fieldOffset;
-}
-
-// ============================================================================
-// String Descriptor Helpers
-// ============================================================================
-
-/**
- * Get the offset and length components of a string descriptor.
- *
- * String descriptor format: [offset (4 bytes)] [length (4 bytes)]
- *
- * @param descPtr - Pointer to the string descriptor
- * @returns Object with offset and length
- */
-export function readStringDesc(descPtr: usize): StringDesc {
-  return new StringDesc(load<u32>(descPtr), load<u32>(descPtr + 4));
-}
-
-/**
- * Write a string descriptor.
- *
- * @param descPtr - Pointer to the string descriptor
- * @param offset - Offset to the string data
- * @param length - Length of the string data
- */
-export function writeStringDesc(descPtr: usize, offset: u32, length: u32): void {
-  store<u32>(descPtr, offset);
-  store<u32>(descPtr + 4, length);
-}
-
-/**
- * String descriptor structure.
- */
-export class StringDesc {
-  offset: u32;
-  length: u32;
-
-  constructor(offset: u32, length: u32) {
-    this.offset = offset;
-    this.length = length;
-  }
-
-  isEmpty(): bool {
-    return this.length == 0;
-  }
-}
-
-// ============================================================================
-// Array Descriptor Helpers
-// ============================================================================
-
-/**
- * Get the offset and length components of an array descriptor.
- *
- * Array descriptor format: [offset (4 bytes)] [length (4 bytes)]
- *
- * @param descPtr - Pointer to the array descriptor
- * @returns Object with offset and length
- */
-export function readArrayDesc(descPtr: usize): ArrayDesc {
-  return new ArrayDesc(load<u32>(descPtr), load<u32>(descPtr + 4));
-}
-
-/**
- * Write an array descriptor.
- *
- * @param descPtr - Pointer to the array descriptor
- * @param offset - Offset to the array data
- * @param length - Number of elements in the array
- */
-export function writeArrayDesc(descPtr: usize, offset: u32, length: u32): void {
-  store<u32>(descPtr, offset);
-  store<u32>(descPtr + 4, length);
-}
-
-/**
- * Array descriptor structure.
- */
-export class ArrayDesc {
-  offset: u32;
-  length: u32;
-
-  constructor(offset: u32, length: u32) {
-    this.offset = offset;
-    this.length = length;
-  }
-
-  isEmpty(): bool {
-    return this.length == 0;
-  }
-}
-
-// ============================================================================
-// Runtime Error Handling
-// ============================================================================
-
-// Error codes for runtime failures
-export enum RuntimeErrorCode {
-  NONE = 0,
-  SCHEMA_MISMATCH = 1,
-  NULL_POINTER = 2,
-  INVALID_ACCESS = 3,
-  EVALUATION_ERROR = 4,
-  OUT_OF_MEMORY = 5,
-}
-
-// Last error that occurred during evaluation
-let lastErrorCode: RuntimeErrorCode = RuntimeErrorCode.NONE;
-
-// Optional error message (allocated on heap for variable-length messages)
-let errorMessagePtr: usize = 0;
-
-/**
- * Check if an error code represents a critical error that should abort execution.
- *
- * Critical errors are unrecoverable conditions where continuing execution would
- * likely lead to memory corruption, crashes, or incorrect results. These errors
- * call abort() to immediately halt the WASM module.
- *
- * Critical errors:
- * - OUT_OF_MEMORY: Memory allocation failed; continuing could corrupt state
- * - NULL_POINTER: Null pointer dereference; memory safety violation
- * - INVALID_ACCESS: Invalid memory access; memory safety violation
- *
- * Non-critical errors (set flag, caller must check hasError()):
- * - SCHEMA_MISMATCH: Input doesn't match schema; recoverable
- * - EVALUATION_ERROR: Logic error in decision evaluation; recoverable
- *
- * @param code - The error code to check
- * @returns true if the error is critical and should abort
- */
-export function isCriticalError(code: RuntimeErrorCode): bool {
-  return (
-    code === RuntimeErrorCode.OUT_OF_MEMORY ||
-    code === RuntimeErrorCode.NULL_POINTER ||
-    code === RuntimeErrorCode.INVALID_ACCESS
-  );
-}
-
-/**
- * Get the last error code that occurred during evaluation.
- *
- * @returns The last error code
- */
-export function getLastError(): RuntimeErrorCode {
-  return lastErrorCode;
-}
-
-/**
- * Set the last error code and optional message.
- *
- * For critical errors (OUT_OF_MEMORY, NULL_POINTER, INVALID_ACCESS), this function
- * calls abort() to immediately halt execution. Critical errors indicate unrecoverable
- * conditions where continuing would lead to memory corruption or undefined behavior.
- *
- * For non-critical errors (SCHEMA_MISMATCH, EVALUATION_ERROR), callers MUST check
- * hasError() after operations that can fail and handle the error appropriately.
- * Failure to check error state may result in incorrect evaluation results.
- *
- * @param code - The error code
- * @param message - Optional error message (allocated on heap)
- */
-export function SetLastError(code: RuntimeErrorCode, message: usize = 0): void {
-  lastErrorCode = code;
-  errorMessagePtr = message;
-
-  // Critical errors abort immediately to prevent corrupted state propagation
-  if (isCriticalError(code)) {
-    abort();
-  }
-}
-
-/**
- * Clear the last error (reset to NONE).
- */
-export function clearLastError(): void {
-  lastErrorCode = RuntimeErrorCode.NONE;
-  errorMessagePtr = 0;
-}
-
-/**
- * Set an error with a string message.
- *
- * This is a convenience function that combines SetLastError() with writeString().
- * The error message is allocated on the heap and will be freed by the next error.
- *
- * For critical errors (OUT_OF_MEMORY, NULL_POINTER, INVALID_ACCESS), this function
- * will call abort() after setting the error, immediately halting execution.
- *
- * For non-critical errors (SCHEMA_MISMATCH, EVALUATION_ERROR), callers MUST check
- * hasError() after operations that can fail.
- *
- * @param code - The error code
- * @param message - The error message string
- */
-export function SetLastErrorWithMessage(code: RuntimeErrorCode, message: string): void {
-  const messagePtr = writeString(message);
-  SetLastError(code, messagePtr);
-}
-
-/**
- * Get the pointer to the error message.
- *
- * @returns Pointer to error message (0 if no message)
- */
-export function getErrorMessagePtr(): usize {
-  return errorMessagePtr;
-}
-
-/**
- * Check if an error occurred.
- *
- * Callers MUST check this function after operations that can set non-critical errors
- * (SCHEMA_MISMATCH, EVALUATION_ERROR). Critical errors (OUT_OF_MEMORY, NULL_POINTER,
- * INVALID_ACCESS) abort immediately and never reach this check.
- *
- * Example usage:
- * ```assemblyscript
- * let result = someOperationThatCanFail();
- * if (hasError()) {
- *   // Handle error - return early, propagate error, etc.
- *   return Value.Null();
- * }
- * // Continue with valid result
- * ```
- *
- * @returns true if a non-critical error occurred, false otherwise
- */
-export function hasError(): bool {
-  return lastErrorCode !== RuntimeErrorCode.NONE;
-}
-
-// ============================================================================
-// Memory Validation Helpers
-// ============================================================================
-
-/**
- * Check if a pointer is within the valid memory range.
- *
- * This is a basic check that can help catch out-of-bounds accesses.
- * Note: In production, you may want to disable these checks for performance.
- *
- * @param ptr - Pointer to check
- * @param size - Size of the region to check
- * @return true if pointer is within valid range, false otherwise
- */
-export function isValidMemoryRange(ptr: usize, size: usize): bool {
-  if (ptr == 0) return false;
-
-  // Get current memory size (AssemblyScript runtime provides this)
-  const memorySize: usize = memory.size() << 16; // 1 page = 64KB
-
-  return ptr + size <= memorySize;
-}
-
-/**
- * Check if a pointer is within the input buffer region.
- *
- * @param ptr - Pointer to check
- * @return true if pointer is within input buffer, false otherwise
- */
-export function isWithinInputBuffer(ptr: usize): bool {
-  return ptr >= INPUT_BUFFER_START && ptr < INPUT_VAR_START;
-}
-
-/**
- * Check if a pointer is within the input variable data region.
- *
- * @param ptr - Pointer to check
- * @return true if pointer is within input variable data, false otherwise
- */
-export function isWithinInputVar(ptr: usize): bool {
-  return ptr >= INPUT_VAR_START && ptr < OUTPUT_START;
-}
-
-/**
- * Check if a pointer is within the output buffer region.
- *
- * @param ptr - Pointer to check
- * @return true if pointer is within output buffer, false otherwise
- */
-export function isWithinOutputBuffer(ptr: usize): bool {
-  return ptr >= OUTPUT_START && ptr < OUTPUT_VAR_START;
-}
-
-/**
- * Check if a pointer is within the output variable data region.
- *
- * @param ptr - Pointer to check
- * @return true if pointer is within output variable data, false otherwise
- */
-export function isWithinOutputVar(ptr: usize): bool {
-  return ptr >= OUTPUT_VAR_START && ptr < HEAP_START;
-}
-
-/**
- * Check if a pointer is within the heap region.
- *
- * @param ptr - Pointer to check
- * @return true if pointer is within heap, false otherwise
- */
-export function isWithinHeap(ptr: usize): bool {
-  return ptr >= HEAP_START;
-}