@divmain/jdm-asm 0.2.0

package/src/compiler/orchestrator.ts

@@ -0,0 +1,352 @@
+/**
+ * Main compilation orchestrator for JDM decisions.
+ *
+ * This module coordinates the compilation pipeline, bringing together:
+ * - Graph building and topological ordering
+ * - Node compilation
+ * - Switch branch detection
+ * - Result selection
+ * - Memory layout code generation
+ *
+ * The orchestrator itself does minimal work - it delegates to specialized modules
+ * for each concern.
+ */
+
+import type { JDMDecision, JDMNode } from './parser';
+import type { CompilationContext, AssemblyScriptCode } from './types';
+import { buildGraph, getEvaluationOrder } from './graph';
+import { compileInputNode, compileOutputNode } from './nodes/input';
+import { compileDecisionTableNode } from './nodes/decision-table';
+import { compileSwitchNode } from './nodes/switch';
+import { compileDecisionNode } from './nodes/decision';
+import { compileExpressionNode } from './nodes/expression';
+import { compileFunctionNode } from './nodes/function';
+import { sanitizeId } from './utils';
+import { validateAllInputReferences, validateAllOutputReferences } from './compile-time-validation';
+import { generatePassThroughMergeCode, generateNestedPathAssignment } from './code-generators';
+import { findSwitchBranchTargets } from './switch-branch-detection';
+import {
+  selectResultNode,
+  generateResultCode,
+  generateFallbackResultCode,
+} from './result-selection';
+
+// ============================================================================
+// Memory Layout Constants
+// ============================================================================
+
+/**
+ * Custom heap start offset in bytes (512KB).
+ *
+ * The custom heap starts at 512KB to avoid conflicts with:
+ * 1. AssemblyScript's internal runtime heap (~50KB - ~192KB)
+ * 2. Host-written input buffer region (192KB - 512KB, up to 320KB)
+ *
+ * This ensures clear separation of memory regions and prevents
+ * the AS runtime from interfering with our custom heap allocator.
+ * Host must grow memory to at least 768KB to use this layout.
+ */
+const CUSTOM_HEAP_START_BYTES = 512 * 1024;
+
+/**
+ * Compile a JDM decision to AssemblyScript code.
+ *
+ * This function orchestrates compilation of all nodes in the decision graph
+ * and generates the complete AssemblyScript module.
+ *
+ * @param jdm - The parsed JDM decision
+ * @param context - The compilation context
+ * @returns Generated AssemblyScript code
+ */
+export function compileDecision(jdm: JDMDecision, context: CompilationContext): AssemblyScriptCode {
+  // Build the graph
+  const graph = buildGraph(jdm);
+
+  // Get nodes in topological order to ensure dependencies are compiled before dependents
+  const evaluationOrder = getEvaluationOrder(graph);
+
+  // Validate references if enabled
+  if (context.options.validate !== false) {
+    validateAllInputReferences(context);
+    validateAllOutputReferences(context);
+  }
+
+  // Create a node lookup for quick access
+  const nodeMap = new Map(jdm.nodes.map((n) => [n.id, n]));
+
+  // Compile each node based on its type
+  const compiledCode = compileNodes(evaluationOrder, nodeMap, context);
+
+  // Generate helper functions for higher-order operations
+  const helperFunctionsCode = Array.from(context.helperFunctions.values()).join('\n');
+
+  // Find nodes that are switch branch targets (should be skipped in main evaluation)
+  const switchBranchTargets = findSwitchBranchTargets(jdm);
+
+  // Generate evaluation code for each node in topological order
+  const evaluationCode = generateEvaluationCode(evaluationOrder, nodeMap, switchBranchTargets);
+
+  // Find output nodes (nodes with no outgoing edges)
+  const outputNodeIds = findOutputNodeIds(jdm);
+
+  // Find evaluated nodes (excluding input, output, and switch branch targets)
+  const evaluatedNodes = filterEvaluatedNodes(evaluationOrder, nodeMap, switchBranchTargets);
+
+  // Generate result selection code
+  const resultCode = generateResultSelectionCode(nodeMap, evaluatedNodes, outputNodeIds);
+
+  // Generate the complete AssemblyScript module
+  return generateModuleCode(helperFunctionsCode, compiledCode, evaluationCode, resultCode);
+}
+
+/**
+ * Compile all nodes in evaluation order.
+ */
+function compileNodes(
+  evaluationOrder: string[],
+  nodeMap: Map<string, JDMNode>,
+  context: CompilationContext,
+): string {
+  let compiledCode = '';
+
+  for (const nodeId of evaluationOrder) {
+    const node = nodeMap.get(nodeId);
+    if (!node) {
+      continue;
+    }
+
+    const nodeType = node.type;
+
+    switch (nodeType) {
+      case 'inputNode':
+        compiledCode += compileInputNode(node, context);
+        break;
+      case 'decisionTableNode':
+        compiledCode += compileDecisionTableNode(node, context);
+        break;
+      case 'switchNode':
+        compiledCode += compileSwitchNode(node, context);
+        break;
+      case 'decisionNode':
+        compiledCode += compileDecisionNode(node, context);
+        break;
+      case 'outputNode':
+        compiledCode += compileOutputNode(node, context);
+        break;
+      case 'expressionNode':
+        compiledCode += compileExpressionNode(node, context);
+        break;
+      case 'functionNode':
+        compiledCode += compileFunctionNode(node, context);
+        break;
+      default:
+        // Unknown node type - skip
+        break;
+    }
+  }
+
+  return compiledCode;
+}
+
+/**
+ * Generate evaluation code for each node in topological order.
+ * Skips output nodes and switch branch targets.
+ */
+function generateEvaluationCode(
+  evaluationOrder: string[],
+  nodeMap: Map<string, JDMNode>,
+  switchBranchTargets: Set<string>,
+): string {
+  return evaluationOrder
+    .map((nodeId) => {
+      const node = nodeMap.get(nodeId);
+      if (!node || node.type === 'outputNode') {
+        return '';
+      }
+
+      // Skip nodes that are switch branch targets - they'll be evaluated by the switch
+      if (switchBranchTargets.has(nodeId)) {
+        return '';
+      }
+
+      return generateNodeEvaluationCode(node);
+    })
+    .filter(Boolean)
+    .join('\n');
+}
+
+/**
+ * Generate evaluation code for a single node.
+ */
+function generateNodeEvaluationCode(node: JDMNode): string {
+  const sanitizedId = sanitizeId(node.id);
+
+  // Check if this node has passThrough enabled (decision tables and expression nodes)
+  const hasPassThrough = node.content?.passThrough === true;
+
+  // Store node result in context under $nodes.<nodeName>
+  let code = `  ctx.set("$nodes.${node.name}", evaluateNode_${sanitizedId}(ctx));`;
+
+  // Handle outputPath - if specified, store the result at the given path
+  // This is used for collect-style decision tables to place array results at a nested path
+  const outputPath = node.content?.outputPath;
+  if (outputPath) {
+    // Check if it's a simple (non-nested) path or a nested path
+    if (!outputPath.includes('.')) {
+      // Simple path - just set directly in context
+      code += `
+  // Store node output at outputPath: ${outputPath} (simple path)
+  ctx.set("${outputPath}", ctx.get("$nodes.${node.name}"));`;
+    } else {
+      // Nested path - use shared helper to generate nested object structure
+      code += `
+  ${generateNestedPathAssignment(outputPath, `ctx.get("$nodes.${node.name}")`)}`;
+    }
+  }
+
+  // If passThrough is enabled, merge the node's output properties back into the context
+  // This allows subsequent nodes to access the computed values directly
+  if (hasPassThrough) {
+    code += `\n  ${generatePassThroughMergeCode(node.name)}`;
+  }
+
+  return code;
+}
+
+/**
+ * Find output node IDs (nodes with no outgoing edges).
+ */
+function findOutputNodeIds(jdm: JDMDecision): Set<string> {
+  const outputNodeIds = new Set<string>();
+  for (const node of jdm.nodes) {
+    const outgoingEdges = jdm.edges.filter((e) => e.sourceId === node.id);
+    if (outgoingEdges.length === 0) {
+      outputNodeIds.add(node.id);
+    }
+  }
+  return outputNodeIds;
+}
+
+/**
+ * Filter evaluation order to get only nodes that were actually evaluated.
+ */
+function filterEvaluatedNodes(
+  evaluationOrder: string[],
+  nodeMap: Map<string, JDMNode>,
+  switchBranchTargets: Set<string>,
+): string[] {
+  return evaluationOrder.filter((id) => {
+    const node = nodeMap.get(id);
+    if (!node) {
+      return false;
+    }
+    // Exclude input and output nodes
+    if (node.type === 'inputNode' || node.type === 'outputNode') {
+      return false;
+    }
+    // Exclude switch branch targets - they're evaluated by the switch
+    if (switchBranchTargets.has(id)) {
+      return false;
+    }
+    return true;
+  });
+}
+
+/**
+ * Generate code to select and extract the final result.
+ */
+function generateResultSelectionCode(
+  nodeMap: Map<string, JDMNode>,
+  evaluatedNodes: string[],
+  outputNodeIds: Set<string>,
+): string {
+  // Use the result-selection module to determine which node's result to use
+  const resultNode = selectResultNode({
+    nodeMap,
+    evaluatedNodes,
+    switchBranchTargets: new Set(), // Already filtered out
+  });
+
+  if (resultNode) {
+    return generateResultCode(resultNode);
+  }
+
+  return generateFallbackResultCode(outputNodeIds, sanitizeId);
+}
+
+/**
+ * Generate the complete AssemblyScript module code.
+ */
+function generateModuleCode(
+  helperFunctionsCode: string,
+  compiledCode: string,
+  evaluationCode: string,
+  resultCode: string,
+): string {
+  return `
+import { Value } from './values';
+import { Context, ScopedContext } from './context';
+import {
+  addValues,
+  subtractValues,
+  multiplyValues,
+  divideValues,
+  moduloValues,
+  powerValues,
+  negateValue,
+  valuesEqual,
+  compareValues,
+  getProperty,
+  getIndex,
+  valueIn,
+  createInterval,
+  evaluateFunction,
+  makeArgs1,
+  makeArgs2,
+  makeArgs3
+} from './expressions';
+import { SetLastError, SetLastErrorWithMessage, hasError, RuntimeErrorCode, initializeMemoryLayout, resetHeap } from './memory';
+import { readValueMap, writeValue } from './arrays';
+
+${helperFunctionsCode}
+
+${compiledCode}
+
+// Main entry point for the compiled decision
+// Input: pointer to input data in WASM memory (serialized Map<string, Value>)
+// Returns: pointer to output data in WASM memory (serialized Value)
+export function evaluate(inputPtr: usize): usize {
+  // Initialize memory layout for custom heap (used for output marshaling)
+  // Memory regions (from 0):
+  // +--------------------------+
+  // | Static data              | 0 - ~50KB (AS's __heap_base)
+  // +--------------------------+
+  // | AS runtime heap          | ~50KB - ~192KB (grows upward during evaluation)
+  // +--------------------------+
+  // | Input data buffer        | 192KB - 512KB (written by host, up to 320KB)
+  // +--------------------------+
+  // | Custom heap (ours)       | 512KB - (used for writeValue/marshaling)
+  // +--------------------------+
+  // The custom heap starts at 512KB to avoid conflicts with AS's internal heap
+  // and the host-written input buffer. Host must grow memory to at least 768KB.
+  initializeMemoryLayout(${CUSTOM_HEAP_START_BYTES}, 0);
+
+  // Reset heap for fresh evaluation
+  resetHeap();
+
+  // Read input from memory
+  let input = readValueMap(inputPtr);
+
+  // Create context with input data
+  let ctx = new Context(input);
+
+  // Evaluate the decision graph in topological order
+${evaluationCode}
+
+  // Get the final result
+${resultCode}
+  // Write result to output memory and return pointer
+  return writeValue(result);
+}
+`;
+}

package/src/compiler/parser.ts

@@ -0,0 +1,115 @@
+import { CompilationError, ErrorCode } from './errors';
+import { validateFunctionNode } from './nodes/function';
+
+export enum NodeType {
+  INPUT = 'inputNode',
+  OUTPUT = 'outputNode',
+  DECISION_TABLE = 'decisionTableNode',
+  SWITCH = 'switchNode',
+  EXPRESSION = 'expressionNode',
+  DECISION = 'decisionNode',
+  FUNCTION = 'functionNode',
+}
+
+export interface JDMNode {
+  id: string;
+  type: NodeType;
+  name: string;
+  position: { x: number; y: number };
+  content?: any;
+  parsedContent?: any;
+}
+
+export interface JDMEdge {
+  id: string;
+  type: string;
+  sourceId: string;
+  targetId: string;
+  /** Optional source handle for nodes with multiple outputs (e.g., switch statements) */
+  sourceHandle?: string;
+}
+
+export interface JDMDecision {
+  nodes: JDMNode[];
+  edges: JDMEdge[];
+  metadata?: any;
+}
+
+/**
+ * Validate that a node has all required fields.
+ *
+ * All JDM nodes must have: id, name, and type.
+ * Validating early provides clear error messages before processing.
+ *
+ * @param node - The node to validate
+ * @param index - The index of the node in the nodes array (for error reporting)
+ * @throws CompilationError if required fields are missing
+ */
+export function validateNodeStructure(node: any, index: number): void {
+  const missingFields: string[] = [];
+
+  if (typeof node.id !== 'string' || node.id.trim() === '') {
+    missingFields.push('id');
+  }
+
+  if (typeof node.name !== 'string') {
+    missingFields.push('name');
+  }
+
+  if (typeof node.type !== 'string' || node.type.trim() === '') {
+    missingFields.push('type');
+  }
+
+  if (missingFields.length > 0) {
+    const nodeIdentifier = node.id || node.name || `at index ${index}`;
+    throw new CompilationError(
+      `Node "${nodeIdentifier}" is missing required field(s): ${missingFields.join(', ')}`,
+      ErrorCode.INVALID_NODE_STRUCTURE,
+      { nodeId: node.id, nodeName: node.name },
+    );
+  }
+}
+
+/**
+ * Parse and validate JDM JSON.
+ * Function nodes have complex internal structure that needs schema validation and transformation.
+ * Validating early provides better error messages and catches issues before expensive compilation steps.
+ */
+export function parseJDM(jdm: string | JDMDecision | any): JDMDecision {
+  const parsed: JDMDecision = typeof jdm === 'string' ? JSON.parse(jdm) : jdm;
+
+  // Validate basic structure before processing
+  if (!parsed.nodes || !Array.isArray(parsed.nodes)) {
+    throw new CompilationError(
+      "Invalid JDM: missing or invalid 'nodes' array",
+      ErrorCode.INVALID_JSON,
+      { field: 'nodes' },
+    );
+  }
+
+  // Validate each node has required fields before any processing
+  parsed.nodes.forEach((node: any, index: number) => {
+    validateNodeStructure(node, index);
+  });
+
+  // Function nodes have rich content structure (parameters, return type, expressions) requiring special
+  // parsing. Other node types have simpler content handled during codegen.
+  parsed.nodes.forEach((node: any) => {
+    if (node.type === NodeType.FUNCTION) {
+      try {
+        node.parsedContent = validateFunctionNode(node);
+      } catch (error) {
+        if (error instanceof CompilationError) {
+          throw error;
+        }
+        throw new CompilationError(
+          `Failed to parse function node "${node.name}": ${error instanceof Error ? error.message : String(error)}`,
+          ErrorCode.INVALID_NODE_STRUCTURE,
+          { nodeId: node.id, nodeName: node.name },
+        );
+      }
+    }
+  });
+
+  return parsed;
+}

package/src/compiler/result-selection.ts

@@ -0,0 +1,161 @@
+/**
+ * Result selection logic for JDM decisions.
+ *
+ * This module determines how to compute the final result from the evaluation order.
+ * It handles different scenarios:
+ * - Switch nodes that route to different branches
+ * - Decision tables with collect-style hit policies
+ * - PassThrough nodes that accumulate context
+ * - Regular nodes that return their result directly
+ */
+
+import type { JDMNode } from './parser';
+
+/**
+ * Check if a decision table node uses a collect-style hit policy.
+ * Collect-style policies return arrays and need to be wrapped in an object with the node name as key.
+ */
+export function isCollectStyleHitPolicy(node: JDMNode): boolean {
+  if (node.type !== 'decisionTableNode') {
+    return false;
+  }
+  const hitPolicy = node.content?.hitPolicy || 'first';
+  return ['collect', 'ruleOrder', 'outputOrder', 'priority'].includes(hitPolicy);
+}
+
+/**
+ * Options for result code generation.
+ */
+export interface ResultSelectionOptions {
+  /** Map of node IDs to JDMNode objects */
+  nodeMap: Map<string, JDMNode>;
+  /** Ordered list of node IDs that were actually evaluated (not skipped) */
+  evaluatedNodes: string[];
+  /** Set of node IDs that are switch branch targets (skipped in main loop) */
+  switchBranchTargets: Set<string>;
+}
+
+/**
+ * Determine which node's result should be used as the final output.
+ *
+ * Priority order:
+ * 1. If there's a switch node, use its result (it handles routing)
+ * 2. Otherwise, use the last non-input, non-output node result
+ * 3. Fallback to output node or null
+ *
+ * @param options - The selection options
+ * @returns The node to use for the final result, or null if fallback needed
+ */
+export function selectResultNode(options: ResultSelectionOptions): JDMNode | null {
+  const { nodeMap, evaluatedNodes } = options;
+
+  // Check if there's a switch node that routes to different branches
+  // Only switch nodes truly route - decision tables in a linear flow are NOT routing nodes
+  const switchNodes = evaluatedNodes.filter((id) => {
+    const node = nodeMap.get(id);
+    return node && node.type === 'switchNode';
+  });
+
+  // When there are switch nodes, use the switch result since it handles branch evaluation
+  if (switchNodes.length > 0) {
+    // Use the last switch node's result (it handles branch routing to terminal nodes)
+    const lastSwitchNodeId = switchNodes[switchNodes.length - 1];
+    return nodeMap.get(lastSwitchNodeId) || null;
+  }
+
+  // Use the last evaluated node
+  if (evaluatedNodes.length > 0) {
+    const lastNodeId = evaluatedNodes[evaluatedNodes.length - 1];
+    return nodeMap.get(lastNodeId) || null;
+  }
+
+  return null;
+}
+
+/**
+ * Generate AssemblyScript code to extract the final result from a node.
+ *
+ * Handles:
+ * - Collect-style hit policies (return array directly)
+ * - PassThrough nodes (return accumulated context)
+ * - Regular nodes (return node result directly)
+ *
+ * @param node - The node to generate result code for
+ * @returns AssemblyScript code string
+ */
+export function generateResultCode(node: JDMNode): string {
+  // COLLECT-style hit policies return arrays directly (not wrapped in an object with the
+  // node name as key) to match zen-engine behavior where the array IS the result
+  if (isCollectStyleHitPolicy(node)) {
+    return `  let result = ctx.get("$nodes.${node.name}");`;
+  }
+
+  // If the node has passThrough enabled, return the accumulated context
+  // This includes all values from previous nodes that were merged via passThrough
+  //
+  // Both 'no match with passThrough' and 'valid result' return Objects, so we use
+  // the __passthrough marker a marker to distinguish these cases while maintaining
+  // type safety.
+  const hasPassThrough = node.content?.passThrough === true;
+  if (hasPassThrough) {
+    return `  // Check node result for passThrough handling
+  let __nodeResult = ctx.get("$nodes.${node.name}");
+  let result: Value;
+  
+  // Check if this is a "passthrough signal" (no match with passThrough enabled)
+  if (!__nodeResult.isNull() && __nodeResult.isObject()) {
+    let __obj = __nodeResult.asObject();
+    if (__obj.has("__passthrough") && __obj.get("__passthrough").asBool()) {
+      // Node signaled to use passthrough - return accumulated context
+      let __finalResult = new Map<string, Value>();
+      const __ctxKeys = ctx.data.keys();
+      for (let __i = 0; __i < __ctxKeys.length; __i++) {
+        const __key = __ctxKeys[__i];
+        if (!__key.startsWith("$") && __key !== "#" && __key !== "acc") {
+          __finalResult.set(__key, ctx.data.get(__key));
+        }
+      }
+      result = Value.Object(__finalResult);
+    } else {
+      // Valid result - build from accumulated context (passThrough merges input with output)
+      let __finalResult = new Map<string, Value>();
+      const __ctxKeys = ctx.data.keys();
+      for (let __i = 0; __i < __ctxKeys.length; __i++) {
+        const __key = __ctxKeys[__i];
+        if (!__key.startsWith("$") && __key !== "#" && __key !== "acc") {
+          __finalResult.set(__key, ctx.data.get(__key));
+        }
+      }
+      result = Value.Object(__finalResult);
+    }
+  } else if (__nodeResult.isNull()) {
+    // Node returned null (error case) - return null, don't passthrough
+    result = Value.Null();
+  } else {
+    // Non-object result - return as-is
+    result = __nodeResult;
+  }`;
+  }
+
+  return `  let result = ctx.get("$nodes.${node.name}");`;
+}
+
+/**
+ * Generate fallback result code when no suitable node is found.
+ *
+ * @param outputNodeIds - Set of output node IDs
+ * @param sanitizeId - Function to sanitize node IDs for code generation
+ * @returns AssemblyScript code string
+ */
+export function generateFallbackResultCode(
+  outputNodeIds: Set<string>,
+  sanitizeId: (id: string) => string,
+): string {
+  if (outputNodeIds.size > 0) {
+    // Fallback: evaluate output node if no other nodes were evaluated
+    const outputNodeId = Array.from(outputNodeIds)[0];
+    const sanitizedOutputId = sanitizeId(outputNodeId);
+    return `  let result = evaluateNode_${sanitizedOutputId}(ctx);`;
+  }
+  return '  let result = Value.Null();';
+}

package/src/compiler/runtime/index.ts

@@ -0,0 +1,26 @@
+// src/compiler/runtime/index.ts
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Must work in both development (src/compiler/runtime) and installed package (dist/compiler/runtime).
+// Relative path from __dirname traverses up to src/runtime.
+function getAssemblyRuntimePath(): string {
+  // From dist/compiler/runtime -> ../../runtime
+  return resolve(__dirname, '..', '..', 'runtime');
+}
+
+function loadRuntime(filename: string): string {
+  const runtimePath = getAssemblyRuntimePath();
+  return readFileSync(resolve(runtimePath, filename), 'utf-8');
+}
+
+export const RUNTIME_VALUES = loadRuntime('values.ts');
+export const RUNTIME_CONTEXT = loadRuntime('context.ts');
+export const RUNTIME_EXPRESSIONS = loadRuntime('expressions.ts');
+export const RUNTIME_TABLES = loadRuntime('tables.ts');
+export const RUNTIME_MEMORY = loadRuntime('memory.ts');
+export const RUNTIME_STRINGS = loadRuntime('strings.ts');
+export const RUNTIME_ARRAYS = loadRuntime('arrays.ts');