@divmain/jdm-asm 0.2.1 → 0.2.3

package/src/compiler/orchestrator.ts

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

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

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

@@ -1,26 +0,0 @@
-// 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');