@divmain/jdm-asm 0.2.0

package/src/runtime/strings.ts

@@ -0,0 +1,260 @@
+// assembly/runtime/strings.ts (AssemblyScript)
+// UTF-16 string handling for WASM linear memory
+
+import { heapAlloc } from './memory';
+
+// ============================================================================
+// String Memory Format
+// ============================================================================
+
+/**
+ * String memory layout: [length: u32][utf16 chars...]
+ *
+ * We use a length-prefixed format; this allows O(1) length checks and efficient substring
+ * operations without scanning for null terminators. Also matches AssemblyScript's native
+ * string representation. The first 4 bytes contain the length (number of UTF-16 code units).
+ * Following that are the UTF-16 code units, each 2 bytes.
+ */
+
+// ============================================================================
+// String Constants
+// ============================================================================
+
+/**
+ * Size of the length field header in bytes.
+ */
+export const STRING_LENGTH_SIZE: usize = 4;
+
+/**
+ * Size of each UTF-16 code unit in bytes.
+ */
+export const UTF16_CODE_UNIT_SIZE: usize = 2;
+
+/**
+ * Minimum string length to use bulk memory operations.
+ * For strings shorter than this, character-by-character writes are used
+ * as the setup overhead dominates. For longer strings, bulk operations
+ * provide significant performance benefits.
+ */
+const MIN_BULK_COPY_STRING_LENGTH: usize = 32;
+
+// ============================================================================
+// String Writing
+// ============================================================================
+
+/**
+ * Write a string to memory and return its pointer.
+ *
+ * Memory is allocated from the runtime heap using heapAlloc().
+ * The memory is aligned to 4 bytes for efficient access.
+ *
+ * @param s - The string to write to memory
+ * @returns Pointer to the allocated string data, or 0 if allocation failed
+ */
+export function writeString(s: string): usize {
+  const len: usize = <usize>s.length;
+
+  // Calculate total size: length field (4 bytes) + UTF-16 characters (2 bytes each)
+  const totalSize = STRING_LENGTH_SIZE + len * UTF16_CODE_UNIT_SIZE;
+
+  // Four-byte alignment ensures proper alignment for u32 loads/stores, avoiding unaligned access
+  // penalties on some architectures. WASM requires aligned memory access for multi-byte types.
+  // Allocate memory from heap
+  const ptr = heapAlloc(totalSize);
+
+  // Return 0 if allocation failed
+  if (ptr == 0) {
+    return 0;
+  }
+
+  // Write length (number of UTF-16 code units)
+  store<u32>(ptr, len);
+
+  // Handle empty string case (len == 0)
+  if (len == 0) {
+    return ptr;
+  }
+
+  // For long strings, use bulk memory copy for better performance.
+  // AssemblyScript strings are internally UTF-16, matching our memory format.
+  if (len >= MIN_BULK_COPY_STRING_LENGTH) {
+    // Get pointer to the string's internal UTF-16 data
+    const srcPtr = changetype<usize>(s);
+    // Copy the UTF-16 data directly
+    memory.copy(ptr + STRING_LENGTH_SIZE, srcPtr, len * UTF16_CODE_UNIT_SIZE);
+  } else {
+    // For short strings, character-by-character writes avoid bulk operation overhead
+    for (let i: usize = 0; i < len; i++) {
+      const codeUnit: u16 = unchecked(<u16>s.charCodeAt(<i32>i));
+      store<u16>(ptr + STRING_LENGTH_SIZE + i * UTF16_CODE_UNIT_SIZE, codeUnit);
+    }
+  }
+
+  return ptr;
+}
+
+// ============================================================================
+// String Reading
+// ============================================================================
+
+/**
+ * Read a string from memory.
+ *
+ * @param ptr - Pointer to the string data in memory
+ * @returns The read string, or empty string if pointer is null
+ */
+export function readString(ptr: usize): string {
+  // Return empty string for null pointer
+  if (ptr == 0) {
+    return '';
+  }
+
+  // Read length (number of UTF-16 code units)
+  const len: usize = <usize>load<u32>(ptr);
+
+  // Handle empty string case
+  if (len == 0) {
+    return '';
+  }
+
+  // Use bulk memory read for O(n) performance instead of O(n²) string concatenation.
+  // String.UTF16.decodeUnsafe reads UTF-16 data directly from memory in a single allocation,
+  // avoiding the repeated string allocations that occur with character-by-character concatenation.
+  return String.UTF16.decodeUnsafe(ptr + STRING_LENGTH_SIZE, len * UTF16_CODE_UNIT_SIZE);
+}
+
+// ============================================================================
+// String Utility Functions
+// ============================================================================
+
+/**
+ * Calculate the size in bytes needed to store a string in memory.
+ *
+ * @param len - The length of the string (number of UTF-16 code units)
+ * @returns The total size in bytes including the length header
+ */
+export function getStringSize(len: usize): usize {
+  return STRING_LENGTH_SIZE + len * UTF16_CODE_UNIT_SIZE;
+}
+
+/**
+ * Calculate the length of a string from its pointer in memory.
+ *
+ * @param ptr - Pointer to the string data in memory
+ * @returns The length of the string (number of UTF-16 code units), or 0 if null
+ */
+export function getStringLength(ptr: usize): usize {
+  if (ptr == 0) {
+    return 0;
+  }
+  return load<u32>(ptr);
+}
+
+/**
+ * Check if a string pointer points to an empty string.
+ *
+ * @param ptr - Pointer to the string data in memory
+ * @returns true if the string is empty or pointer is null, false otherwise
+ */
+export function isStringEmpty(ptr: usize): bool {
+  if (ptr == 0) {
+    return true;
+  }
+  return load<u32>(ptr) == 0;
+}
+
+/**
+ * Compare two strings in memory.
+ *
+ * @param ptr1 - Pointer to the first string
+ * @param ptr2 - Pointer to the second string
+ * @returns true if the strings are equal, false otherwise
+ */
+export function stringsEqual(ptr1: usize, ptr2: usize): bool {
+  // If both are null, they're equal
+  if (ptr1 == 0 && ptr2 == 0) {
+    return true;
+  }
+
+  // If only one is null, they're not equal
+  if (ptr1 == 0 || ptr2 == 0) {
+    return false;
+  }
+
+  // Compare lengths
+  const len1 = load<u32>(ptr1);
+  const len2 = load<u32>(ptr2);
+
+  if (len1 != len2) {
+    return false;
+  }
+
+  // Compare each UTF-16 code unit
+  for (let i: usize = 0; i < <usize>len1; i++) {
+    const offset = STRING_LENGTH_SIZE + i * UTF16_CODE_UNIT_SIZE;
+    const char1 = load<u16>(ptr1 + offset);
+    const char2 = load<u16>(ptr2 + offset);
+    if (char1 != char2) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Calculate a simple hash of a string in memory.
+ *
+ * This can be used for quick comparisons or deduplication.
+ * Uses a simple polynomial rolling hash algorithm.
+ *
+ * @param ptr - Pointer to the string data in memory
+ * @returns A hash value for the string (0 if null)
+ */
+export function hashString(ptr: usize): u32 {
+  if (ptr == 0) {
+    return 0;
+  }
+
+  const len: usize = <usize>load<u32>(ptr);
+  let hash: u32 = 5381;
+
+  for (let i: usize = 0; i < len; i++) {
+    const charCode = load<u16>(ptr + STRING_LENGTH_SIZE + i * UTF16_CODE_UNIT_SIZE);
+    hash = unchecked((hash << 5) + hash + unchecked(charCode)); // hash * 33 + charCode
+  }
+
+  return hash;
+}
+
+/**
+ * Copy a string within memory.
+ *
+ * Creates a new copy of the string at a new location in the heap.
+ *
+ * @param srcPtr - Pointer to the source string
+ * @returns Pointer to the newly allocated copy, or 0 if allocation failed
+ */
+export function copyString(srcPtr: usize): usize {
+  if (srcPtr == 0) {
+    return 0;
+  }
+
+  // Get the length of the source string
+  const len: usize = <usize>load<u32>(srcPtr);
+
+  // Calculate total size
+  const totalSize = STRING_LENGTH_SIZE + len * UTF16_CODE_UNIT_SIZE;
+
+  // Allocate new memory
+  const dstPtr = heapAlloc(totalSize);
+
+  if (dstPtr == 0) {
+    return 0;
+  }
+
+  // Copy the entire string data (length header + UTF-16 code units)
+  memory.copy(dstPtr, srcPtr, totalSize);
+
+  return dstPtr;
+}

package/src/runtime/tables.ts

@@ -0,0 +1,96 @@
+// assembly/runtime/tables.ts (AssemblyScript)
+import { Value } from './values';
+import { Context } from './context';
+import { valuesEqual } from './expressions';
+
+/**
+ * Condition for decision table row evaluation.
+ * Uses Value tagged union consistently.
+ */
+export class Condition {
+  field: string;
+  op: string;
+  value: Value;
+
+  constructor(field: string, op: string, value: Value) {
+    this.field = field;
+    this.op = op;
+    this.value = value;
+  }
+
+  evaluate(ctx: Context): bool {
+    const actual = ctx.get(this.field);
+    const expected = this.value;
+
+    // Handle null cases
+    if (actual.isNull()) {
+      if (this.op == '==' && expected.isNull()) return true;
+      if (this.op == '!=' && !expected.isNull()) return true;
+      return false;
+    }
+
+    // Numeric comparisons
+    if (actual.isNumber() && expected.isNumber()) {
+      const a = actual.asFloat();
+      const e = expected.asFloat();
+
+      if (this.op == '==') return a == e;
+      if (this.op == '!=') return a != e;
+      if (this.op == '<') return a < e;
+      if (this.op == '<=') return a <= e;
+      if (this.op == '>') return a > e;
+      if (this.op == '>=') return a >= e;
+    }
+
+    // String comparisons
+    if (actual.isString() && expected.isString()) {
+      const a = actual.asString();
+      const e = expected.asString();
+
+      if (this.op == '==') return a == e;
+      if (this.op == '!=') return a != e;
+      // Lexicographic comparison for strings
+      if (this.op == '<') return a < e;
+      if (this.op == '<=') return a <= e;
+      if (this.op == '>') return a > e;
+      if (this.op == '>=') return a >= e;
+    }
+
+    // Boolean equality
+    if (actual.isBool() && expected.isBool()) {
+      if (this.op == '==') return actual.boolVal == expected.boolVal;
+      if (this.op == '!=') return actual.boolVal != expected.boolVal;
+    }
+
+    // Generic equality via valuesEqual
+    if (this.op == '==') return valuesEqual(actual, expected);
+    if (this.op == '!=') return !valuesEqual(actual, expected);
+
+    return false;
+  }
+}
+
+/**
+ * Check if a value is within an interval (range).
+ * Supports open/closed boundaries: [a..b], (a..b), [a..b), (a..b]
+ */
+export function inInterval(
+  val: Value,
+  start: Value,
+  end: Value,
+  startInclusive: bool,
+  endInclusive: bool,
+): bool {
+  if (!val.isNumber() || !start.isNumber() || !end.isNumber()) {
+    return false;
+  }
+
+  const v = val.asFloat();
+  const s = start.asFloat();
+  const e = end.asFloat();
+
+  const aboveStart = startInclusive ? v >= s : v > s;
+  const belowEnd = endInclusive ? v <= e : v < e;
+
+  return aboveStart && belowEnd;
+}

package/src/runtime/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "assemblyscript/std/assembly.json",
+  "include": ["./**/*.ts"]
+}

package/src/runtime/values.ts

@@ -0,0 +1,209 @@
+// assembly/runtime/values.ts
+// Type tags for runtime type checking
+export const TYPE_NULL: i32 = 0;
+export const TYPE_BOOL: i32 = 1;
+export const TYPE_INT: i32 = 2;
+export const TYPE_FLOAT: i32 = 3;
+export const TYPE_STRING: i32 = 4;
+export const TYPE_ARRAY: i32 = 5;
+export const TYPE_OBJECT: i32 = 6;
+
+// Pre-allocated singleton values for frequently used immutable types.
+// This avoids allocations in hot paths for null/boolean/small integer/common float values.
+let _nullSingleton: Value | null = null;
+let _trueSingleton: Value | null = null;
+let _falseSingleton: Value | null = null;
+let _emptyStringSingleton: Value | null = null;
+let _zeroFloatSingleton: Value | null = null;
+let _oneFloatSingleton: Value | null = null;
+
+// Cache for small integers (-1 to 10) - covers common array indices, loop counters, etc.
+// Using 12-element array: index 0 = -1, index 1 = 0, ..., index 11 = 10
+const SMALL_INT_CACHE_MIN: i64 = -1;
+const SMALL_INT_CACHE_MAX: i64 = 10;
+const SMALL_INT_CACHE_SIZE: i32 = 12;
+let _smallIntCache: StaticArray<Value | null> | null = null;
+
+/**
+ * Tagged union for dynamic JSON-like values.
+ * Only one field is valid based on the `type` tag.
+ */
+export class Value {
+  type: i32 = TYPE_NULL;
+  boolVal: bool = false;
+  intVal: i64 = 0;
+  floatVal: f64 = 0.0;
+  stringVal: string | null = null;
+  arrayVal: Array<Value> | null = null;
+  objectVal: Map<string, Value> | null = null;
+
+  static Null(): Value {
+    // Return singleton null value to avoid allocations
+    if (_nullSingleton === null) {
+      const v = new Value();
+      v.type = TYPE_NULL;
+      _nullSingleton = v;
+    }
+    return _nullSingleton!;
+  }
+
+  static Bool(val: bool): Value {
+    // Return singleton boolean values to avoid allocations
+    if (val) {
+      if (_trueSingleton === null) {
+        const v = new Value();
+        v.type = TYPE_BOOL;
+        v.boolVal = true;
+        _trueSingleton = v;
+      }
+      return _trueSingleton!;
+    } else {
+      if (_falseSingleton === null) {
+        const v = new Value();
+        v.type = TYPE_BOOL;
+        v.boolVal = false;
+        _falseSingleton = v;
+      }
+      return _falseSingleton!;
+    }
+  }
+
+  static Int(val: i64): Value {
+    // Fast path for common small integers to avoid allocations
+    if (val >= SMALL_INT_CACHE_MIN && val <= SMALL_INT_CACHE_MAX) {
+      if (_smallIntCache === null) {
+        _smallIntCache = new StaticArray<Value | null>(SMALL_INT_CACHE_SIZE);
+      }
+      const idx = <i32>(val - SMALL_INT_CACHE_MIN);
+      if (unchecked(_smallIntCache![idx]) === null) {
+        const v = new Value();
+        v.type = TYPE_INT;
+        v.intVal = val;
+        unchecked((_smallIntCache![idx] = v));
+      }
+      return unchecked(_smallIntCache![idx])!;
+    }
+    const v = new Value();
+    v.type = TYPE_INT;
+    v.intVal = val;
+    return v;
+  }
+
+  static Float(val: f64): Value {
+    // Fast path for common float values (0.0, 1.0) to avoid allocations
+    if (val == 0.0) {
+      if (_zeroFloatSingleton === null) {
+        const v = new Value();
+        v.type = TYPE_FLOAT;
+        v.floatVal = 0.0;
+        _zeroFloatSingleton = v;
+      }
+      return _zeroFloatSingleton!;
+    }
+    if (val == 1.0) {
+      if (_oneFloatSingleton === null) {
+        const v = new Value();
+        v.type = TYPE_FLOAT;
+        v.floatVal = 1.0;
+        _oneFloatSingleton = v;
+      }
+      return _oneFloatSingleton!;
+    }
+    const v = new Value();
+    v.type = TYPE_FLOAT;
+    v.floatVal = val;
+    return v;
+  }
+
+  static String(val: string): Value {
+    // Fast path for empty string to avoid allocations
+    if (val.length == 0) {
+      if (_emptyStringSingleton === null) {
+        const v = new Value();
+        v.type = TYPE_STRING;
+        v.stringVal = '';
+        _emptyStringSingleton = v;
+      }
+      return _emptyStringSingleton!;
+    }
+    const v = new Value();
+    v.type = TYPE_STRING;
+    v.stringVal = val;
+    return v;
+  }
+
+  static Array(val: Array<Value>): Value {
+    const v = new Value();
+    v.type = TYPE_ARRAY;
+    v.arrayVal = val;
+    return v;
+  }
+
+  static Object(val: Map<string, Value>): Value {
+    const v = new Value();
+    v.type = TYPE_OBJECT;
+    v.objectVal = val;
+    return v;
+  }
+
+  // Type checking
+  isNull(): bool {
+    return this.type == TYPE_NULL;
+  }
+  isBool(): bool {
+    return this.type == TYPE_BOOL;
+  }
+  isNumber(): bool {
+    return this.type == TYPE_INT || this.type == TYPE_FLOAT;
+  }
+  isString(): bool {
+    return this.type == TYPE_STRING;
+  }
+  isArray(): bool {
+    return this.type == TYPE_ARRAY;
+  }
+  isObject(): bool {
+    return this.type == TYPE_OBJECT;
+  }
+
+  // Returning defaults (0, false, "") instead of throwing errors provides more
+  // forgiving evaluation semantics matching JavaScript's type coercion behavior.
+  asBool(): bool {
+    return this.type == TYPE_BOOL ? this.boolVal : false;
+  }
+  asInt(): i64 {
+    return this.type == TYPE_INT ? this.intVal : 0;
+  }
+  asFloat(): f64 {
+    if (this.type == TYPE_FLOAT) return this.floatVal;
+    if (this.type == TYPE_INT) return <f64>this.intVal;
+    return 0.0;
+  }
+  asString(): string {
+    // Convert value to string representation
+    if (this.type == TYPE_STRING && this.stringVal != null) return this.stringVal!;
+    if (this.type == TYPE_NULL) return '';
+    if (this.type == TYPE_BOOL) return this.boolVal ? 'true' : 'false';
+    if (this.type == TYPE_INT) return this.intVal.toString();
+    if (this.type == TYPE_FLOAT) {
+      // JavaScript developers expect "3" not "3.0" for integer-valued floats. We check if
+      // the float is exactly representable as i64 (no fractional part, within range) and
+      // format as integer in that case. Otherwise use AS's default float formatting.
+      const f = this.floatVal;
+      // Check if it's an integer
+      if (f == <f64>(<i64>f) && f >= <f64>i64.MIN_VALUE && f <= <f64>i64.MAX_VALUE) {
+        return (<i64>f).toString();
+      }
+      return f.toString();
+    }
+    return '';
+  }
+  asArray(): Array<Value> {
+    return this.arrayVal != null ? this.arrayVal! : new Array<Value>();
+  }
+  asObject(): Map<string, Value> {
+    return this.objectVal != null ? this.objectVal! : new Map<string, Value>();
+  }
+}
+
+export type Result = Map<string, Value>;

package/test-data/README.md

@@ -0,0 +1,83 @@
+# Test Data Organization
+
+This directory contains test fixtures ported from `@gorules/zen-engine` to ensure compatibility and validate the correctness of the JDM-ASM compiler.
+
+## Test Porting Strategy
+
+The test porting process follows a structured approach:
+
+1. **Clone Reference Tests**: Tests are cloned from the `gorules/zen` repository to `test-data/zen-reference/`
+2. **Analyze Coverage**: The `analyze-coverage.ts` script analyzes JDM files to understand node types and features
+3. **Categorize Tests**: The `categorize-tests.ts` script automatically categorizes tests based on their node types:
+   - Expression nodes → `expressions/`
+   - Decision table nodes → `decision-tables/`
+   - Switch nodes → `switch-nodes/`
+   - Decision nodes (sub-decision references) → `sub-decisions/`
+   - Function nodes are currently skipped (not yet supported)
+   - Other node types are placed in `other/`
+4. **Further Organization**: Within each category, tests are organized by feature subsets (e.g., arithmetic, logical, string for expressions)
+
+
+
+## Directory Structure
+
+### expressions/
+Tests for the ZEN expression language parser and evaluation, including:
+- Arithmetic operations
+- Logical operations
+- String operations
+- Comparisons
+- Function calls
+
+### decision-tables/
+Tests for decision table nodes, including:
+- Simple decision tables
+- Multiple input/output columns
+- Hit policies (First, Collect Sum, Collect Count, etc.)
+- Priority rules
+
+### switch-nodes/
+Tests for switch/case logic, including:
+- String matching
+- Number ranges
+- Multiple conditions
+- Default cases
+
+### sub-decisions/
+Tests for sub-decision nodes and complex decision graphs:
+- Nested decisions
+- Decision calls
+- Result propagation
+
+### other/
+Tests that don't fit into standard categories:
+- Custom node types
+- Simple Input/Output tests
+- Schema-related tests
+
+## Running Test Analysis
+
+To analyze test coverage:
+```bash
+npx tsx tests/scripts/analyze-coverage.ts > test-data/analysis.md
+```
+
+To categorize and organize tests:
+```bash
+npx tsx tests/scripts/categorize-tests.ts test-data/zen-reference test-data
+```
+
+## Test Format
+
+Each test consists of:
+1. **JDM JSON**: The decision model definition
+2. **Input data**: Sample input values (typically from zen-engine test harness)
+3. **Expected output**: The expected result structure
+4. (Optional) **Schema**: TypeBox schema for type-safe marshaling
+
+See individual test files for examples.
+
+## Reference Source
+
+ Tests are ported from: https://github.com/gorules/zen
+Reference tests located in: `test-data/zen-reference/`