@divmain/jdm-asm 0.2.0 → 0.2.3

package/src/compiler/runtime.ts

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

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