@divmain/jdm-asm 0.2.0

package/src/runtime/index.ts

@@ -0,0 +1,8 @@
+// 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

@@ -0,0 +1,607 @@
+// 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;
+}