@divmain/jdm-asm 0.2.0

package/src/compiler/runtime.ts

@@ -0,0 +1,452 @@
+// src/compiler/runtime.ts
+// Runtime execution support for evaluating compiled JDM decisions
+
+import type { CompilationResult } from './types';
+import {
+  loadGeneratedMarshaling,
+  loadGeneratedValidation,
+  type MarshalFn,
+  type UnmarshalFn,
+  type ValidateFn,
+} from './runtime-codegen';
+
+// ============================================================================
+// Memory Constants
+// ============================================================================
+
+/**
+ * WebAssembly page size in bytes (64KB).
+ * This is a fixed constant defined by the WebAssembly specification.
+ * Used to calculate memory requirements and convert between pages and bytes.
+ */
+const WASM_PAGE_SIZE_BYTES = 65536;
+
+/**
+ * Default maximum memory pages for compiled decisions (256 pages = 16MB).
+ *
+ * This limit balances:
+ * 1. Allowing large decision tables with many rules
+ * 2. Preventing unbounded memory growth
+ * 3. Browser compatibility (most browsers support at least 32MB per WASM instance)
+ *
+ * Can be overridden via CompiledDecisionOptions.maximumMemoryPages.
+ */
+const DEFAULT_MAX_MEMORY_PAGES = 256;
+
+/**
+ * Input buffer start offset in bytes (after null pointer trap).
+ *
+ * Must match INPUT_BUFFER_START in src/runtime/memory.ts (which equals
+ * NULL_POINTER_TRAP_SIZE = 4 bytes). This ensures correct memory layout
+ * coordination between JavaScript marshaling and WASM memory access.
+ *
+ * The first 4 bytes are reserved as a null pointer trap zone - accessing
+ * address 0 will read/write this trap zone, helping catch null pointer bugs.
+ */
+const INPUT_BUFFER_START_OFFSET = 4;
+
+/**
+ * Error type for runtime evaluation errors.
+ */
+export class RuntimeError extends Error {
+  constructor(
+    message: string,
+    public readonly code: number = -1,
+    public readonly context?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'RuntimeError';
+  }
+}
+
+/**
+ * Ensure WASM memory is large enough for the required size.
+ *
+ * This function checks if the current memory buffer is large enough
+ * and grows it by 64KB pages if needed.
+ *
+ * @param memory - The WebAssembly.Memory instance
+ * @param required - The required memory size in bytes
+ * @throws {RuntimeError} If memory cannot be grown (e.g., exceeds maximum)
+ *
+ * @example
+ * ```typescript
+ * ensureMemory(memory, 131072); // Ensure at least 128KB is available
+ * ```
+ */
+export function ensureMemory(memory: WebAssembly.Memory, required: number): void {
+  const current = memory.buffer.byteLength;
+  if (required <= current) {
+    return; // Already have enough memory
+  }
+
+  // Calculate how many pages to grow
+  const pagesNeeded = Math.ceil((required - current) / WASM_PAGE_SIZE_BYTES);
+
+  // Attempt to grow memory
+  try {
+    const oldPages = memory.grow(pagesNeeded);
+    if (oldPages < 0) {
+      throw new RuntimeError(`Failed to grow memory by ${pagesNeeded} pages`, 5); // OUT_OF_MEMORY
+    }
+  } catch (error) {
+    // Re-throw RuntimeError as-is
+    if (error instanceof RuntimeError) {
+      throw error;
+    }
+    throw new RuntimeError(
+      `Cannot grow WASM memory: required ${required} bytes, ` +
+        `current ${current} bytes, need ${pagesNeeded} more pages. ` +
+        (error instanceof Error ? error.message : String(error)),
+      5, // OUT_OF_MEMORY
+    );
+  }
+}
+
+// Re-export type definitions from runtime-codegen for backward compatibility
+export type { MarshalFn, UnmarshalFn, ValidateFn } from './runtime-codegen';
+
+/**
+ * Options for creating a CompiledDecision instance.
+ */
+export interface CompiledDecisionOptions {
+  /** The compiled WASM binary */
+  wasm: Uint8Array;
+  /** Schema hash for validation */
+  schemaHash: bigint;
+  /** Function to marshal input to WASM memory */
+  marshal: MarshalFn;
+  /** Function to unmarshal output from WASM memory */
+  unmarshal: UnmarshalFn;
+  /** Function to validate input against schema */
+  validate?: ValidateFn;
+  /** Initial memory size in pages (default: 1 page = 64KB) */
+  initialMemoryPages?: number;
+  /** Maximum memory pages (default: DEFAULT_MAX_MEMORY_PAGES = 256 pages = 16MB) */
+  maximumMemoryPages?: number;
+}
+
+/**
+ * A compiled JDM decision ready for evaluation.
+ *
+ * This class manages the lifecycle of evaluating a compiled decision:
+ * 1. Validates input against schema (fail fast with good error)
+ * 2. Marshals input to WASM memory
+ * 3. Resets heap for fresh evaluation
+ * 4. Runs evaluation
+ * 5. Checks for runtime errors (schema mismatch, etc.)
+ * 6. Unmarshals output from WASM memory
+ *
+ * @example
+ * ```typescript
+ * const decision = new CompiledDecision({
+ *   wasm: compilationResult.wasm,
+ *   schemaHash: compilationResult.schemaHash,
+ *   marshal: marshalInput,
+ *   unmarshal: unmarshalOutput,
+ *   validate: validateInput,
+ * });
+ *
+ * const output = await decision.evaluate({ age: 25, name: 'Alice' });
+ * ```
+ */
+export class CompiledDecision {
+  private instance: WebAssembly.Instance | null = null;
+  private memory: WebAssembly.Memory | null = null;
+  private module: WebAssembly.Module;
+  private marshal: MarshalFn;
+  private unmarshal: UnmarshalFn;
+  private validate?: ValidateFn;
+
+  constructor(private options: CompiledDecisionOptions) {
+    // WebAssembly.Module requires an ArrayBuffer starting at offset 0, but Uint8Array may
+    // be a view into a larger buffer at a non-zero offset, which would cause Module
+    // construction to fail. Create a proper Uint8Array view that the Module constructor
+    // can safely access, ensuring we only pass the exact bytes of the WASM binary.
+    const buffer = new Uint8Array(
+      options.wasm.buffer,
+      options.wasm.byteOffset,
+      options.wasm.byteLength,
+    );
+    this.module = new WebAssembly.Module(buffer as unknown as ArrayBuffer);
+
+    this.marshal = options.marshal;
+    this.unmarshal = options.unmarshal;
+    this.validate = options.validate;
+  }
+
+  /**
+   * Initialize the WebAssembly instance.
+   * This is done lazily on first evaluation, or can be called explicitly.
+   */
+  private async initialize(): Promise<void> {
+    if (this.instance !== null) {
+      return;
+    }
+
+    // Don't provide memory via import - let the WASM module use its own exported memory.
+    // AssemblyScript's incremental GC runtime requires specific memory initialization
+    // that only works correctly with the module's own memory.
+    this.instance = await WebAssembly.instantiate(this.module, {
+      env: {
+        abort: () => {
+          throw new RuntimeError('WASM abort called');
+        },
+        seed: () => {
+          return Date.now();
+        },
+        'Date.now': () => Date.now(),
+      },
+      // Empty index module provided for AssemblyScript compatibility
+      index: {},
+    });
+
+    // Get memory from the WASM module's exports
+    this.memory = this.instance.exports.memory as WebAssembly.Memory;
+  }
+
+  /**
+   * Evaluate the decision with the given input.
+   *
+   * @param input - The input data to evaluate
+   * @returns The output of the decision evaluation
+   * @throws {RuntimeError} If evaluation fails
+   * @throws {ValidationError} If input validation fails (if validate is provided)
+   */
+  async evaluate<I = Record<string, unknown>, O = Record<string, unknown>>(input: I): Promise<O> {
+    await this.initialize();
+
+    if (!this.instance || !this.memory) {
+      throw new RuntimeError('WASM instance not initialized');
+    }
+
+    // Local references to avoid null checks in the hot path
+    const memory = this.memory;
+    const instance = this.instance;
+
+    // 1. Validate input against schema (fail fast with good error)
+    if (this.validate) {
+      try {
+        this.validate(input);
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new RuntimeError(`Input validation failed: ${error.message}`, 1, { input });
+        }
+        throw error;
+      }
+    }
+
+    // Clear any stale error state from previous evaluations before starting new evaluation.
+    // This ensures each evaluation starts with a clean slate.
+    const clearLastErrorFn = instance.exports.clearLastError as () => void;
+    if (clearLastErrorFn) {
+      clearLastErrorFn();
+    }
+
+    try {
+      // 2. Marshal input to WASM memory
+      const inputPtr: number = this.marshal(input as Record<string, unknown>, memory);
+
+      // Verify input pointer is valid
+      if (inputPtr < INPUT_BUFFER_START_OFFSET) {
+        throw new RuntimeError(
+          `Invalid input pointer: ${inputPtr} (must be >= ${INPUT_BUFFER_START_OFFSET})`,
+        );
+      }
+
+      // 3. Reset heap for fresh evaluation
+      const resetHeapFn = instance.exports.resetHeap as () => void;
+      if (resetHeapFn) {
+        resetHeapFn();
+      }
+
+      // 4. Run evaluation
+      const evaluateFn = instance.exports.evaluate as (ptr: number) => number;
+      if (!evaluateFn) {
+        throw new RuntimeError('evaluate function not exported from WASM module');
+      }
+
+      const outputPtr: number = evaluateFn(inputPtr);
+
+      // 5. Check for runtime errors (schema mismatch, etc.)
+      const getLastErrorFn = instance.exports.getLastError as () => number;
+      if (getLastErrorFn) {
+        const errorCode = getLastErrorFn();
+        if (errorCode !== 0) {
+          throw new RuntimeError(this.getErrorMessage(errorCode), errorCode, { input, outputPtr });
+        }
+      }
+
+      // Verify output pointer is valid
+      // Output pointer validity is verified during unmarshal - we only check it's within
+      // addressable memory here to avoid segfault.
+      if (outputPtr < memory.buffer.byteLength) {
+        // Output pointer should be within a reasonable range
+        // We'll verify the unmarshal works properly
+      }
+
+      // 6. Unmarshal output from WASM memory
+      const output = this.unmarshal(outputPtr, memory);
+
+      return output as O;
+    } finally {
+      // Always clear error state after evaluation, even if an error was thrown.
+      // This prevents stale error state from affecting subsequent evaluations.
+      if (clearLastErrorFn) {
+        clearLastErrorFn();
+      }
+    }
+  }
+
+  /**
+   * Get a human-readable error message for a given error code.
+   *
+   * @param errorCode - The error code from getLastError()
+   * @returns A human-readable error message
+   */
+  private getErrorMessage(errorCode: number): string {
+    // Error codes duplicated from assembly/runtime/errors.ts because WASM cannot export
+    // enum metadata - these must stay synchronized.
+    // NONE = 0, SCHEMA_MISMATCH = 1, NULL_POINTER = 2, INVALID_ACCESS = 3, EVALUATION_ERROR = 4, OUT_OF_MEMORY = 5
+    const errorMessages: Record<number, string> = {
+      0: 'No error',
+      1: 'Schema mismatch: input data does not match expected schema',
+      2: 'Null pointer dereference',
+      3: 'Invalid memory access',
+      4: 'Evaluation error',
+      5: 'Out of memory',
+    };
+
+    return errorMessages[errorCode] ?? `Unknown error code: ${errorCode}`;
+  }
+
+  /**
+   * Get the current WebAssembly memory instance.
+   * This can be useful for debugging or direct memory inspection.
+   *
+   * @returns The WebAssembly.Memory instance (null if not initialized)
+   */
+  getMemory(): WebAssembly.Memory | null {
+    return this.memory;
+  }
+
+  /**
+   * Get the current WebAssembly instance.
+   *
+   * @returns The WebAssembly.Instance instance (null if not initialized)
+   */
+  getInstance(): WebAssembly.Instance | null {
+    return this.instance;
+  }
+
+  /**
+   * Dispose of this CompiledDecision instance.
+   * This clears the WebAssembly instance and allows garbage collection.
+   */
+  dispose(): void {
+    this.instance = null;
+  }
+
+  /**
+   * Get memory usage statistics.
+   *
+   * @returns Object with memory usage information
+   */
+  getMemoryStats(): { current: number; maximum: number; used: number } {
+    // Note: 'used' equals 'current' because WebAssembly.Memory doesn't expose actual heap
+    // usage - tracking used bytes requires instrumentation in AssemblyScript allocator.
+    const currentBytes = this.memory?.buffer.byteLength ?? 0;
+    return {
+      current: currentBytes,
+      maximum: (this.options.maximumMemoryPages ?? DEFAULT_MAX_MEMORY_PAGES) * WASM_PAGE_SIZE_BYTES,
+      used: currentBytes,
+    };
+  }
+
+  /**
+   * Get the input buffer pointer, ensuring sufficient memory is available.
+   *
+   * This method doesn't allocate new buffers on each call - it always returns the
+   * same INPUT_BUFFER_START_OFFSET constant after ensuring the memory can accommodate the
+   * required size. Single-allocation design chosen because: (1) heap is reset between
+   * evaluations so fragmentation isn't an issue, (2) simpler than maintaining a free
+   * list, (3) marshal code controls actual layout in WASM memory. All input data is
+   * marshaled into a single buffer starting at INPUT_BUFFER_START_OFFSET.
+   *
+   * @param required - The required memory size in bytes
+   * @returns The base pointer of the input buffer (always INPUT_BUFFER_START_OFFSET)
+   * @throws {RuntimeError} If memory cannot be grown to accommodate the required size
+   *
+   * @example
+   * ```typescript
+   * const ptr = decision.getInputBuffer(1024); // Ensure 1KB available
+   * ```
+   */
+  getInputBuffer(required: number): number {
+    if (!this.memory) {
+      throw new RuntimeError('Memory not initialized - call evaluate() first', 5);
+    }
+
+    // Ensure enough memory
+    try {
+      ensureMemory(this.memory, required);
+    } catch (error) {
+      throw new RuntimeError(
+        `Memory allocation failed: ${error instanceof Error ? error.message : String(error)}`,
+        5, // OUT_OF_MEMORY error code
+      );
+    }
+
+    // Single-allocation design: return the INPUT_BUFFER_START_OFFSET
+    return INPUT_BUFFER_START_OFFSET;
+  }
+}
+
+/**
+ * Create a CompiledDecision instance from a CompilationResult.
+ *
+ * This is a convenience function that creates the necessary marshal,
+ * unmarshal, and validation functions from the generated code.
+ *
+ * @param result - The compilation result
+ * @param validate - Optional validation function (defaults to generated validation code)
+ * @returns A CompiledDecision instance ready for evaluation
+ *
+ * @example
+ * ```typescript
+ * const result = await compile({
+ *   jdm: myJdm,
+ *   inputSchema: MyInputSchema,
+ *   outputSchema: MyOutputSchema,
+ * });
+ *
+ * const decision = createCompiledDecision(result);
+ * const output = await decision.evaluate({ age: 25 });
+ * ```
+ */
+export async function createCompiledDecision(
+  result: CompilationResult,
+  validate?: ValidateFn,
+): Promise<CompiledDecision> {
+  // Load the marshal and unmarshal functions from the generated code
+  const { marshal, unmarshal } = loadGeneratedMarshaling(result.marshalCode);
+
+  // Load or use provided validation function
+  const validator = validate ?? (await loadGeneratedValidation(result.validationCode));
+
+  return new CompiledDecision({
+    wasm: result.wasm,
+    schemaHash: result.schemaHash,
+    marshal,
+    unmarshal,
+    validate: validator,
+  });
+}
+
+// Re-export compile-time code generation functions for backward compatibility
+export { loadGeneratedMarshaling, loadGeneratedValidation } from './runtime-codegen';
+
+/**
+ * Re-export types from dependencies
+ */
+export type { TSchema } from '@sinclair/typebox';

package/src/compiler/schema.ts

@@ -0,0 +1,245 @@
+import { type TSchema, Kind } from '@sinclair/typebox';
+import type { FlattenedLayout } from './types';
+import { createHash } from 'crypto';
+
+/**
+ * Schema field information for memory layout
+ */
+interface SchemaField {
+  schema: TSchema;
+  path: string;
+  flatName: string;
+}
+
+/**
+ * Flattens a TypeBox schema to a memory layout.
+ *
+ * This function processes a schema and produces a flattened representation
+ * that can be used for direct memory access in WebAssembly.
+ *
+ * Memory structure:
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │ Fixed Fields (numbers, bools, enum indices)                 │
+ * │   customer_age: f64 (8 bytes)                               │
+ * │   customer_tier: i32 (4 bytes) - enum index                 │
+ * ├─────────────────────────────────────────────────────────────┤
+ * │ String/Array Pointers (offset, length pairs)                │
+ * │   order_items_ptr: i32, order_items_len: i32                │
+ * ├─────────────────────────────────────────────────────────────┤
+ * │ Variable-length data (UTF-16 strings, array contents)       │
+ * └─────────────────────────────────────────────────────────────┘
+ *
+ * @param schema - The TypeBox schema to flatten
+ * @param _prefix - Internal parameter for recursive flattening with dotted paths
+ * @returns The flattened memory layout
+ */
+export function flattenSchema(schema: TSchema): FlattenedLayout {
+  const layout: FlattenedLayout = {
+    fields: [],
+  };
+
+  // Collect all fields from the schema
+  const fields: SchemaField[] = collectFields(schema, '');
+
+  // Track current offset for field layout
+  let currentOffset = 0;
+
+  // Process fields: first pass - fixed types
+  for (const field of fields) {
+    const typeInfo = getFieldType(field.schema);
+    if (typeInfo.isFixed) {
+      layout.fields.push({
+        path: field.path,
+        flatName: field.flatName,
+        type: typeInfo.asType,
+        offset: currentOffset,
+        size: typeInfo.size,
+      });
+      currentOffset += typeInfo.size;
+    }
+  }
+
+  // Second pass - variable types (strings, arrays)
+  // These get pointers (2 x i32 = 8 bytes each for offset + length)
+  for (const field of fields) {
+    const typeInfo = getFieldType(field.schema);
+    if (!typeInfo.isFixed) {
+      layout.fields.push({
+        path: field.path,
+        flatName: field.flatName,
+        type: typeInfo.asType,
+        offset: currentOffset,
+        size: -1, // Variable length
+      });
+      currentOffset += 8; // 4 bytes offset + 4 bytes length
+    }
+  }
+
+  return layout;
+}
+
+/**
+ * Collect all fields from a schema recursively
+ */
+function collectFields(schema: TSchema, path: string): SchemaField[] {
+  const fields: SchemaField[] = [];
+
+  const kind = (schema as any)[Kind];
+
+  if (kind === 'Object') {
+    const properties = (schema as any).properties || {};
+    for (const [name, fieldSchema] of Object.entries(properties)) {
+      const fieldPath = path ? `${path}.${name}` : name;
+      const flatName = path ? `${path}_${name}` : name;
+
+      const nestedFields = collectFields(fieldSchema as TSchema, fieldPath);
+      if (nestedFields.length > 0) {
+        fields.push(...nestedFields);
+      } else {
+        fields.push({
+          schema: fieldSchema as TSchema,
+          path: fieldPath,
+          flatName,
+        });
+      }
+    }
+  }
+
+  // For non-objects, return empty array (handled by parent)
+  return fields;
+}
+
+/**
+ * Get type information for a schema field
+ */
+function getFieldType(schema: TSchema): {
+  isFixed: boolean;
+  asType: 'f64' | 'i32' | 'i64' | 'bool' | 'string' | 'array';
+  size: number;
+} {
+  const kind = (schema as any)[Kind];
+
+  switch (kind) {
+    case 'Number':
+      return { isFixed: true, asType: 'f64', size: 8 };
+
+    case 'Integer':
+      return { isFixed: true, asType: 'i32', size: 4 };
+
+    case 'Boolean':
+      // Booleans stored as i32 (4 bytes) to ensure natural alignment and match AssemblyScript's
+      // bool representation
+      return { isFixed: true, asType: 'bool', size: 4 };
+
+    case 'String':
+      return { isFixed: false, asType: 'string', size: -1 };
+
+    case 'Array':
+      return { isFixed: false, asType: 'array', size: -1 };
+
+    case 'Literal':
+      // Literals are stored as i32 indices (for boolean-like or enum-like)
+      return { isFixed: true, asType: 'i32', size: 4 };
+
+    case 'Union':
+      // First, handle unions of Literal types (enum-like) as i32 indices for efficiency
+      const anyOf = (schema as any).anyOf;
+      if (Array.isArray(anyOf) && anyOf.length > 0) {
+        const firstKind = (anyOf[0] as any)[Kind];
+        if (firstKind === 'Literal') {
+          return { isFixed: true, asType: 'i32', size: 4 };
+        }
+      }
+      // Default to string for heterogeneous unions - can represent multiple incompatible types
+      // (e.g., string | number | object)
+      return { isFixed: false, asType: 'string', size: -1 };
+
+    default:
+      // Default to string for unknown types
+      return { isFixed: false, asType: 'string', size: -1 };
+  }
+}
+
+/**
+ * Compute a hash of the input and output schemas for runtime validation.
+ *
+ * This hash is embedded in the compiled WASM module and can be used to
+ * verify that the runtime data matches the expected schema.
+ *
+ * Uses SHA256 to create a canonical hash, then takes the first 8 bytes as u64.
+ *
+ * @param inputSchema - The input schema
+ * @param outputSchema - The output schema
+ * @returns A 64-bit hash value
+ */
+export function computeSchemaHash(inputSchema: TSchema, outputSchema: TSchema): bigint {
+  // Create canonical representation with sorted keys
+  const canonical = JSON.stringify(
+    {
+      input: canonicalizeSchema(inputSchema),
+      output: canonicalizeSchema(outputSchema),
+    },
+    null,
+    2,
+  );
+
+  // Compute SHA256 hash
+  const hash = createHash('sha256').update(canonical).digest();
+
+  // Take first 8 bytes as u64 (little-endian)
+  return hash.readBigUInt64LE(0);
+}
+
+/**
+ * Convert a schema to a canonical form for hashing by sorting keys and normalizing structure
+ */
+function canonicalizeSchema(schema: TSchema): unknown {
+  const kind = (schema as any)[Kind];
+
+  if (kind === 'Object') {
+    const properties = (schema as any).properties || {};
+    const canonical: Record<string, unknown> = {};
+    const keys = Object.keys(properties).sort();
+
+    for (const key of keys) {
+      canonical[key] = canonicalizeSchema(properties[key]);
+    }
+
+    return {
+      type: 'object',
+      properties: canonical,
+      required: ((schema as any).required || []).sort(),
+    };
+  }
+
+  if (kind === 'Array') {
+    return {
+      type: 'array',
+      items: canonicalizeSchema((schema as any).items),
+    };
+  }
+
+  if (kind === 'Enum') {
+    return {
+      type: 'enum',
+      values: ((schema as any).anyOf || []).map((val: TSchema) => (val as any).const).sort(),
+    };
+  }
+
+  if (kind === 'Literal') {
+    return {
+      type: 'literal',
+      value: (schema as any).const,
+    };
+  }
+
+  // For primitive types, return a simple representation
+  const primitiveTypes: Record<string, string> = {
+    Number: 'number',
+    Integer: 'integer',
+    String: 'string',
+    Boolean: 'boolean',
+  };
+
+  return primitiveTypes[kind] || kind;
+}