@divmain/jdm-asm 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,996 @@
+import { TSchema } from '@sinclair/typebox';
+export { TSchema } from '@sinclair/typebox';
+import { DirectedGraph } from 'graphology';
+
+declare enum NodeType {
+    INPUT = "inputNode",
+    OUTPUT = "outputNode",
+    DECISION_TABLE = "decisionTableNode",
+    SWITCH = "switchNode",
+    EXPRESSION = "expressionNode",
+    DECISION = "decisionNode",
+    FUNCTION = "functionNode"
+}
+interface JDMNode {
+    id: string;
+    type: NodeType;
+    name: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    content?: any;
+    parsedContent?: any;
+}
+interface JDMEdge {
+    id: string;
+    type: string;
+    sourceId: string;
+    targetId: string;
+    /** Optional source handle for nodes with multiple outputs (e.g., switch statements) */
+    sourceHandle?: string;
+}
+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
+ */
+declare function validateNodeStructure(node: any, index: number): void;
+/**
+ * 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.
+ */
+declare function parseJDM(jdm: string | JDMDecision | any): JDMDecision;
+
+/**
+ * No-match behavior options for decision tables and switch nodes.
+ *
+ * This is a discriminated union to ensure type safety:
+ * - returnNull and throwError don't require additional data
+ * - returnDefault requires a value at type level
+ */
+type NoMatchBehavior = {
+    type: 'returnNull';
+} | {
+    type: 'throwError';
+} | {
+    type: 'returnDefault';
+    value: unknown;
+};
+/**
+ * Context passed through compilation phases.
+ */
+interface CompilationContext {
+    /** The parsed JDM */
+    jdm: JDMDecision;
+    /** Input schema (TypeBox) */
+    inputSchema: TSchema;
+    /** Output schema (TypeBox) */
+    outputSchema: TSchema;
+    /** Flattened input memory layout */
+    inputLayout: FlattenedLayout;
+    /** Flattened output memory layout */
+    outputLayout: FlattenedLayout;
+    /** Schema hash for runtime validation */
+    schemaHash: bigint;
+    /** Compiler options */
+    options: CompilerOptions;
+    /** Parse an expression string to AST */
+    parseExpression(expr: string): any;
+    /** Parse an expression in unary mode */
+    parseUnaryExpression(expr: string): any;
+    /** Get unique identifier for generated code */
+    getUniqueId(prefix: string): string;
+    /** Loader function to load sub-decision JDM files by reference key */
+    loadDecision(key: string): JDMDecision;
+    /** Cache of compiled sub-decisions (key -> compiled code) */
+    compiledSubDecisions: Map<string, AssemblyScriptCode>;
+    /** Track the current decision path for cycle detection */
+    decisionPath: string[];
+    /** Generated helper functions for higher-order operations */
+    helperFunctions: Map<string, string>;
+    /** Function node sources for JavaScript bridge (node ID -> JavaScript source code) */
+    functionSources?: Map<string, string>;
+}
+/**
+ * Flattened schema layout for direct memory access.
+ */
+interface FlattenedLayout {
+    fields: Array<{
+        path: string;
+        flatName: string;
+        type: 'f64' | 'i32' | 'i64' | 'bool' | 'string' | 'array';
+        offset: number;
+        size: number;
+    }>;
+}
+/**
+ * Compiler options.
+ */
+interface CompilerOptions {
+    optimize?: boolean;
+    debug?: boolean;
+    validate?: boolean;
+    /** How to handle cases where no rules match in decision tables/switches */
+    noMatchBehavior?: NoMatchBehavior;
+    /** Optional loader function to load sub-decision JDM files */
+    loadDecision?: (key: string) => JDMDecision;
+    /** Optional testDataRoot path for default loader to search */
+    testDataRoot?: string;
+    /**
+     * Optional path to write debug AssemblyScript files on compilation failure.
+     *
+     * When compilation fails, the generated AssemblyScript code is written to disk
+     * to aid debugging. This option controls where these files are written:
+     *
+     * - `undefined` (default): No debug files are written
+     * - `string`: Files are written to a secure temporary directory under this path
+     * - Environment variable `JDM_ASM_DEBUG_OUTPUT`: Falls back to this path if option not set
+     *
+     * **Filesystem Side Effects:**
+     * - Creates temporary directories with random names (e.g., `jdm-asm-debug-XXXXXX`)
+     * - Writes `.ts` files with 0o600 permissions (owner read/write only)
+     * - Files are NOT automatically cleaned up and may accumulate
+     *
+     * **Security:**
+     * - Uses `fs.mkdtempSync()` to create secure temporary directories
+     * - Files are created with restricted permissions (0o600)
+     * - Temporary directories have random names to prevent conflicts
+     */
+    debugOutputPath?: string;
+}
+/**
+ * Result of compilation.
+ */
+interface CompilationResult {
+    /** Compiled WASM binary */
+    wasm: Uint8Array;
+    /** Schema hash for runtime validation */
+    schemaHash: bigint;
+    /** Generated marshaling code (JS) */
+    marshalCode: string;
+    /** Generated validation code (JS) */
+    validationCode: string;
+    /** WAT text format (if debug enabled) */
+    wat?: string;
+    /** Generated AssemblyScript source (if debug enabled) */
+    assemblyScript?: string;
+}
+/**
+ * Alias for generated AssemblyScript code strings.
+ */
+type AssemblyScriptCode = string;
+
+type JDMGraph = DirectedGraph<JDMNode, JDMEdge>;
+declare function buildGraph(jdm: JDMDecision): JDMGraph;
+declare function validateGraph(graph: JDMGraph): void;
+/**
+ * Get nodes in topological order for evaluation.
+ * This ensures dependencies are evaluated before dependents.
+ */
+declare function getEvaluationOrder(graph: JDMGraph): string[];
+/**
+ * Get all nodes that feed into a given node.
+ */
+declare function getInputNodes(graph: JDMGraph, nodeId: string): JDMNode[];
+/**
+ * Get all nodes that a given node feeds into.
+ */
+declare function getOutputNodes(graph: JDMGraph, nodeId: string): JDMNode[];
+
+/**
+ * Error handling infrastructure for the JDM compiler.
+ *
+ * This module provides:
+ * - CompilationError: The main error class for all compilation failures
+ * - ErrorCode: A comprehensive enumeration of all possible error types
+ * - SourceLocation: Detailed location information for error reporting
+ * - ErrorCollector: Aggregates non-fatal expression errors for batch reporting
+ */
+/**
+ * Detailed source location for error reporting.
+ */
+interface SourceLocation {
+    /** ID of the node where the error occurred */
+    nodeId?: string;
+    /** Name of the node where the error occurred */
+    nodeName?: string;
+    /** Field name within the node */
+    field?: string;
+    /** Line number in source JDM */
+    line?: number;
+    /** Column number in source JDM */
+    column?: number;
+}
+/**
+ * Enumeration of all possible compilation error codes.
+ *
+ * Errors are categorized into three types:
+ * - Structural errors: Critical JDM structure issues that fail compilation immediately
+ * - Feature errors: Unsupported features that cannot be handled
+ * - Expression errors: Issues in expression parsing that can be collected and reported together
+ */
+declare enum ErrorCode {
+    INVALID_JSON = "INVALID_JSON",
+    INVALID_NODE_STRUCTURE = "INVALID_NODE_STRUCTURE",
+    MISSING_INPUT_NODE = "MISSING_INPUT_NODE",
+    MISSING_OUTPUT_NODE = "MISSING_OUTPUT_NODE",
+    MULTIPLE_INPUT_NODES = "MULTIPLE_INPUT_NODES",
+    CYCLE_DETECTED = "CYCLE_DETECTED",
+    INVALID_EDGE = "INVALID_EDGE",
+    UNSUPPORTED_FUNCTION_NODE = "UNSUPPORTED_FUNCTION_NODE",
+    UNSUPPORTED_EXPRESSION = "UNSUPPORTED_EXPRESSION",
+    PARSE_ERROR = "PARSE_ERROR",
+    UNKNOWN_FUNCTION = "UNKNOWN_FUNCTION",
+    TYPE_MISMATCH = "TYPE_MISMATCH",
+    UNKNOWN_FIELD = "UNKNOWN_FIELD",
+    SCHEMA_MISMATCH = "SCHEMA_MISMATCH",
+    INVALID_SCHEMA = "INVALID_SCHEMA"
+}
+/**
+ * Custom error class for compilation failures.
+ *
+ * Provides structured error information including error code, source location,
+ * and additional context for debugging.
+ */
+declare class CompilationError extends Error {
+    readonly code: ErrorCode;
+    readonly location?: SourceLocation | undefined;
+    readonly context?: Record<string, unknown> | undefined;
+    readonly name = "CompilationError";
+    constructor(message: string, code: ErrorCode, location?: SourceLocation | undefined, context?: Record<string, unknown> | undefined);
+    /**
+     * Get a formatted error message with location information.
+     */
+    getFormattedMessage(): string;
+}
+/**
+ * Collector for non-fatal errors during expression parsing.
+ *
+ * This allows the parser to continue and collect multiple errors rather than
+ * failing on the first one, providing a better user experience by reporting
+ * all issues at once.
+ *
+ * @example
+ * const collector = new ErrorCollector();
+ * collector.add(new CompilationError('Undefined variable', ErrorCode.UNKNOWN_FIELD, { nodeName: 'AgeCheck' }));
+ * collector.add(new CompilationError('Type mismatch', ErrorCode.TYPE_MISMATCH, { nodeName: 'AgeCheck' }));
+ * collector.throwIfErrors(); // Throws with aggregated message
+ */
+declare class ErrorCollector {
+    private errors;
+    /**
+     * Add an error to the collector.
+     */
+    add(error: CompilationError): void;
+    /**
+     * Check if any errors have been collected.
+     */
+    hasErrors(): boolean;
+    /**
+     * Throw if there are any collected errors.
+     *
+     * Single errors throw directly to preserve original context and stack trace. Multiple
+     * errors are aggregated into one with numbered list, so developers see all problems at
+     * once instead of fixing issues one-by-one through repeated compile attempts.
+     */
+    throwIfErrors(): void;
+}
+/**
+ * Type guard to check if an error is a CompilationError.
+ */
+declare function isCompilationError(error: unknown): error is CompilationError;
+/**
+ * Type guard to check if an error code is a structural error.
+ */
+declare function isStructuralError(code: ErrorCode): boolean;
+/**
+ * Type guard to check if an error code is a feature error.
+ */
+declare function isFeatureError(code: ErrorCode): boolean;
+/**
+ * Type guard to check if an error code is an expression error.
+ */
+declare function isExpressionError(code: ErrorCode): boolean;
+
+/**
+ * Union type of all expression AST nodes.
+ */
+type ExpressionAST = NumberLiteral | StringLiteral | BooleanLiteral | NullLiteral | Identifier | DollarRef | HashRef | BinaryOp | UnaryOp | TernaryOp | MemberAccess | IndexAccess | FunctionCall | Interval | TemplateLiteral | ArrayLiteral | ObjectLiteral;
+interface NumberLiteral {
+    type: 'NumberLiteral';
+    value: number;
+}
+interface StringLiteral {
+    type: 'StringLiteral';
+    value: string;
+}
+interface BooleanLiteral {
+    type: 'BooleanLiteral';
+    value: boolean;
+}
+interface NullLiteral {
+    type: 'NullLiteral';
+}
+interface Identifier {
+    type: 'Identifier';
+    name: string;
+}
+/**
+ * Dollar reference - used in unary mode to refer to the current value.
+ * Represents `$` in decision table cell expressions.
+ */
+interface DollarRef {
+    type: 'DollarRef';
+}
+/**
+ * Hash reference - used in higher-order functions to refer to current element.
+ * Represents `#` in expressions like `filter(items, # > 5)`.
+ */
+interface HashRef {
+    type: 'HashRef';
+}
+interface BinaryOp {
+    type: 'BinaryOp';
+    op: BinaryOperator;
+    left: ExpressionAST;
+    right: ExpressionAST;
+}
+type BinaryOperator = '+' | '-' | '*' | '/' | '%' | '^' | '==' | '!=' | '<' | '>' | '<=' | '>=' | 'and' | 'or' | '??' | 'in' | 'not in';
+interface UnaryOp {
+    type: 'UnaryOp';
+    op: UnaryOperator;
+    operand: ExpressionAST;
+}
+type UnaryOperator = 'not' | '-';
+interface TernaryOp {
+    type: 'TernaryOp';
+    condition: ExpressionAST;
+    consequent: ExpressionAST;
+    alternate: ExpressionAST;
+}
+interface MemberAccess {
+    type: 'MemberAccess';
+    object: ExpressionAST;
+    property: string;
+}
+interface IndexAccess {
+    type: 'IndexAccess';
+    object: ExpressionAST;
+    index: ExpressionAST;
+}
+interface FunctionCall {
+    type: 'FunctionCall';
+    callee: ExpressionAST;
+    args: ExpressionAST[];
+}
+interface Interval {
+    type: 'Interval';
+    start: ExpressionAST;
+    end: ExpressionAST;
+    startInclusive: boolean;
+    endInclusive: boolean;
+}
+interface TemplateLiteral {
+    type: 'TemplateLiteral';
+    parts: Array<{
+        text: string;
+    } | {
+        expr: ExpressionAST;
+    }>;
+}
+interface ArrayLiteral {
+    type: 'ArrayLiteral';
+    elements: ExpressionAST[];
+}
+interface ObjectLiteral {
+    type: 'ObjectLiteral';
+    properties: Array<{
+        key: string;
+        value: ExpressionAST;
+    }>;
+}
+
+/**
+ * Optimization Pipeline for JDM to WebAssembly Compilation
+ *
+ * This module defines the interface for optimization passes and the runner
+ * that applies them sequentially to transform the compiled AST into an
+ * optimized form before code generation.
+ */
+
+/**
+ * Cache for parsed expression ASTs.
+ * Maps expression strings to their parsed AST nodes to avoid redundant parsing.
+ */
+type ExpressionCache = Map<string, ExpressionAST>;
+/**
+ * Compiled AST - the intermediate representation after parsing.
+ *
+ * JDMDecision structure is simple enough for in-place transformation, avoiding the
+ * complexity and memory overhead of building a separate intermediate representation.
+ */
+type CompiledAST = JDMDecision;
+/**
+ * Interface for an optimization pass.
+ *
+ * Each optimization pass receives the compiled AST and returns a
+ * potentially modified/optimized AST.
+ */
+interface OptimizationPass {
+    /** Human-readable name of the optimization pass */
+    name: string;
+    /**
+     * Run the optimization pass on the given AST.
+     *
+     * @param ast - The compiled AST to optimize
+     * @returns The optimized AST
+     */
+    run(ast: CompiledAST): CompiledAST;
+}
+/**
+ * Ordered list of optimization passes.
+ *
+ * Passes have dependencies - one pass may create opportunities for the next. For example,
+ * constant folding might convert "if (2 > 3)" to "if (false)", then dead code elimination
+ * removes the unreachable branch. Running DCE before folding would miss this optimization.
+ */
+declare const optimizer: OptimizationPass[];
+/**
+ * Run all optimization passes sequentially on the given AST.
+ *
+ * @param ast - The compiled AST to optimize
+ * @returns The fully optimized AST
+ */
+declare function runOptimizations(ast: CompiledAST): CompiledAST;
+/**
+ * Get the expression cache for a node, creating it if it doesn't exist.
+ */
+declare function getExpressionCache(node: JDMNode): ExpressionCache;
+/**
+ * Clear the expression cache for a node.
+ * Should be called when the node's expressions are modified.
+ */
+declare function clearExpressionCache(node: JDMNode): void;
+
+/**
+ * Fold constant expressions at compile time.
+ *
+ * This pass traverses expression ASTs and evaluates them at compile time
+ * when possible. Examples:
+ *   - Replace (2 + 3) with 5
+ *   - Replace true and false with false
+ *   - Replace "hello" + " world" with "hello world"
+ *
+ * @param ast - The compiled AST to optimize
+ * @returns The AST with folded constants
+ */
+declare function constantFolding(ast: CompiledAST): CompiledAST;
+/**
+ * Remove unreachable code.
+ *
+ * This pass identifies and removes branches that can never be reached.
+ * Examples:
+ *   - Remove if branches with constant false conditions
+ *   - Remove decision table rows with always-false conditions
+ *   - Remove decision table rows that can never match after previous rows
+ *
+ * @param ast - The compiled AST to optimize
+ * @returns The AST with dead code removed
+ */
+declare function deadCodeElimination(ast: CompiledAST): CompiledAST;
+/**
+ * Inline small expressions.
+ *
+ * This pass replaces function calls with evaluated results for pure functions.
+ * Examples:
+ *   - Inline small arithmetic operations in decision table cells
+ *   - Pre-evaluate expressions that don't depend on runtime values
+ *
+ * @param ast - The compiled AST to optimize
+ * @returns The AST with inlined expressions
+ */
+declare function expressionInlining(ast: CompiledAST): CompiledAST;
+/**
+ * Build index structures for efficient table lookup.
+ *
+ * This pass transforms linear search structures into more efficient alternatives.
+ * Examples:
+ *   - Convert decision table rows with equality checks to index-based lookup
+ *   - Mark tables that are good candidates for switch statement generation
+ *
+ * Table indexing converts O(n) linear search to O(1) hash lookup when all rules check
+ * equality on a single column with unique values - this is common in lookup tables
+ * (e.g., pricing tiers by customer type) and can improve evaluation time by 10-100x
+ * for large tables.
+ *
+ * @param ast - The compiled AST to optimize
+ * @returns The AST with optimized table lookups
+ */
+declare function tableIndexing(ast: CompiledAST): CompiledAST;
+
+/**
+ * JavaScript Validation Code Generation
+ *
+ * This module generates JavaScript code for validating input data against
+ * TypeBox schemas before marshaling. The generated code performs:
+ *
+ * - Type checking for primitives (string, number, boolean)
+ * - Required field validation
+ * - Nested object validation
+ * - Array element validation
+ * - Union type validation
+ * - Literal value validation
+ *
+ * The generated validators are standalone JavaScript code that doesn't
+ * require runtime schema compilation, making validation fast and predictable.
+ */
+
+/**
+ * Generate JavaScript validation code.
+ *
+ * This function generates JavaScript code that validates input data
+ * against the TypeBox schema before marshaling.
+ *
+ * Generates custom validation code that checks types and required fields
+ * without requiring runtime schema compilation.
+ *
+ * @param schema - The TypeBox schema to validate against
+ * @returns Generated validation code as a string
+ */
+declare function generateValidationCode(schema: TSchema): string;
+
+/**
+ * Type definitions for marshal and unmarshal functions.
+ */
+type MarshalFn = (data: Record<string, unknown>, memory: WebAssembly.Memory) => number;
+type UnmarshalFn = (ptr: number, memory: WebAssembly.Memory) => Record<string, unknown>;
+type ValidateFn = (data: unknown) => void;
+/**
+ * Load generated marshaling code as executable functions.
+ *
+ * @internal This function uses Function constructor to execute generated code.
+ * The code is generated by the compiler and is trusted, but users should be
+ * aware that this executes arbitrary JavaScript in the current context.
+ *
+ * @param code - The generated marshaling code
+ * @returns Object with marshal and unmarshal functions
+ */
+declare function loadGeneratedMarshaling(code: string): {
+    marshal: MarshalFn;
+    unmarshal: UnmarshalFn;
+};
+/**
+ * Load generated validation code as executable function.
+ *
+ * @param code - The generated validation code
+ * @returns Validation function
+ */
+declare function loadGeneratedValidation(code: string): Promise<ValidateFn>;
+
+/**
+ * Error type for runtime evaluation errors.
+ */
+declare class RuntimeError extends Error {
+    readonly code: number;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, code?: number, context?: Record<string, unknown> | undefined);
+}
+/**
+ * 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
+ * ```
+ */
+declare function ensureMemory(memory: WebAssembly.Memory, required: number): void;
+
+/**
+ * Options for creating a CompiledDecision instance.
+ */
+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' });
+ * ```
+ */
+declare class CompiledDecision {
+    private options;
+    private instance;
+    private memory;
+    private module;
+    private marshal;
+    private unmarshal;
+    private validate?;
+    constructor(options: CompiledDecisionOptions);
+    /**
+     * Initialize the WebAssembly instance.
+     * This is done lazily on first evaluation, or can be called explicitly.
+     */
+    private initialize;
+    /**
+     * 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)
+     */
+    evaluate<I = Record<string, unknown>, O = Record<string, unknown>>(input: I): Promise<O>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Get the current WebAssembly instance.
+     *
+     * @returns The WebAssembly.Instance instance (null if not initialized)
+     */
+    getInstance(): WebAssembly.Instance | null;
+    /**
+     * Dispose of this CompiledDecision instance.
+     * This clears the WebAssembly instance and allows garbage collection.
+     */
+    dispose(): void;
+    /**
+     * Get memory usage statistics.
+     *
+     * @returns Object with memory usage information
+     */
+    getMemoryStats(): {
+        current: number;
+        maximum: number;
+        used: number;
+    };
+    /**
+     * 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;
+}
+/**
+ * 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 });
+ * ```
+ */
+declare function createCompiledDecision(result: CompilationResult, validate?: ValidateFn): Promise<CompiledDecision>;
+
+/**
+ * Compile-time validation for decision models.
+ *
+ * This module provides functions to perform static analysis of JDM structure
+ * and references at compile time. These checks detect missing references,
+ * undeclared identifiers, and unassigned outputs before code generation.
+ *
+ * These functions operate on ASTs and CompilationContext - they do NOT
+ * execute at runtime. For runtime data validation, see runtime-validation-codegen.ts.
+ */
+
+/**
+ * Collect all identifier references from an expression AST.
+ *
+ * This function walks the AST and collects all variable/field references
+ * that need to be resolved from the context. It handles:
+ * - Simple identifiers: `age`, `name`
+ * - Member access: `customer.age`, `order.items[0].price`
+ *
+ * @param ast - The expression AST to analyze
+ * @returns Set of all identifier names referenced in the expression
+ */
+declare function collectIdentifiers(ast: ExpressionAST): Set<string>;
+/**
+ * Validate that all referenced identifiers exist in the input schema.
+ *
+ * This function checks that all input references in expressions are declared
+ * in the input schema. It builds a set of expected input fields from the
+ * flattened layout and compares it against the identifiers used in expressions.
+ *
+ * @param referencedIdentifiers - Set of identifiers used in expressions
+ * @param context - The compilation context containing the input schema
+ * @param location - Source location for error reporting
+ * @throws CompilationError if any referenced input is not declared
+ */
+declare function validateInputReferences(referencedIdentifiers: Set<string>, context: CompilationContext, location?: SourceLocation): void;
+/**
+ * Collect all output assignments from a decision.
+ *
+ * This function walks through all nodes in the decision and collects
+ * the output paths that are assigned by expression nodes and decision table nodes.
+ *
+ * @param context - The compilation context
+ * @returns Set of all output paths assigned by the decision
+ */
+declare function collectOutputAssignments(context: CompilationContext, errorCollector?: ErrorCollector): Set<string>;
+/**
+ * Validate that all expected outputs from the schema are assigned.
+ *
+ * This function checks that all output fields defined in the output schema
+ * are actually assigned by the decision logic. It builds a set of expected
+ * output fields from the flattened layout and compares it against the
+ * outputs that are assigned by expression nodes and decision table nodes.
+ *
+ * @param assignedOutputs - Set of output paths assigned by the decision
+ * @param context - The compilation context containing the output schema
+ * @param location - Source location for error reporting
+ * @throws CompilationError if any expected output is not assigned
+ */
+declare function validateOutputReferences(assignedOutputs: Set<string>, context: CompilationContext, location?: SourceLocation): void;
+/**
+ * Validate output assignments for all nodes in a decision.
+ *
+ * This is a convenience function that validates that all expected outputs
+ * from the output schema are actually assigned by the decision logic.
+ *
+ * @param context - The compilation context
+ * @throws CompilationError if any expected output is not assigned or if errors occur during collection
+ */
+declare function validateAllOutputReferences(context: CompilationContext): void;
+/**
+ * Validate input references for all expression nodes in a decision.
+ *
+ * This is a convenience function that validates all expressions in the decision
+ * at once, collecting all errors before throwing.
+ *
+ * @param context - The compilation context
+ * @throws CompilationError if any expression references an undeclared input or contains parse errors
+ */
+declare function validateAllInputReferences(context: CompilationContext): void;
+
+/**
+ * Runtime validation code generation for decision models.
+ *
+ * This module provides functions that generate or perform validation code
+ * that executes at runtime. These functions validate actual data against
+ * schemas when the decision is evaluated.
+ *
+ * For compile-time static analysis (checking references exist, etc.),
+ * see compile-time-validation.ts.
+ */
+
+/**
+ * Validation error containing field path, expected type, and actual value.
+ */
+interface ValidationError {
+    /** The field path (e.g., "customer.age") */
+    path: string;
+    /** Error message describing the issue */
+    message: string;
+    /** The expected type */
+    expected?: string;
+    /** The actual value that failed validation */
+    actual?: unknown;
+}
+/**
+ * Result of runtime validation.
+ */
+interface ValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Array of validation errors (empty if valid) */
+    errors: ValidationError[];
+}
+/**
+ * Validate runtime input data against the input schema.
+ *
+ * This function checks that all required input fields from the schema
+ * are present in the provided input data AND that they have correct types.
+ * It returns a list of validation errors including missing fields and
+ * type mismatches.
+ *
+ * Security note: This validation prevents malformed input with wrong types
+ * (string instead of number, object instead of array) from being marshaled
+ * to WASM, which could cause runtime errors or unexpected behavior.
+ *
+ * @param inputData - Runtime input data as a JavaScript object
+ * @param inputLayout - Flattened layout from the input schema
+ * @returns Array of missing/invalid input field paths (empty if all valid)
+ */
+declare function validateRuntimeInputs(inputData: Record<string, any>, inputLayout: FlattenedLayout): string[];
+/**
+ * Validate runtime input data with detailed error information.
+ *
+ * This function performs comprehensive validation including:
+ * - Presence checking: All required fields must be present
+ * - Type checking: Values must match expected types
+ * - Range checking: Numbers must be finite (not NaN/Infinity unless intended)
+ *
+ * @param inputData - Runtime input data as a JavaScript object
+ * @param inputLayout - Flattened layout from the input schema
+ * @returns Detailed validation result with errors
+ */
+declare function validateRuntimeInputsDetailed(inputData: Record<string, any>, inputLayout: FlattenedLayout): ValidationResult;
+/**
+ * Validate runtime output data against the output schema.
+ *
+ * This function checks that all required output fields from the schema
+ * are present in the provided output data AND that they have correct types.
+ * It returns a list of validation errors including missing fields and
+ * type mismatches.
+ *
+ * @param outputData - Runtime output data as a JavaScript object
+ * @param outputLayout - Flattened layout from the output schema
+ * @returns Array of missing/invalid output field paths (empty if all valid)
+ */
+declare function validateRuntimeOutputs(outputData: Record<string, any>, outputLayout: FlattenedLayout): string[];
+/**
+ * Validate runtime output data with detailed error information.
+ *
+ * This function performs comprehensive validation including:
+ * - Presence checking: All required output fields must be present
+ * - Type checking: Values must match expected types
+ *
+ * @param outputData - Runtime output data as a JavaScript object
+ * @param outputLayout - Flattened layout from the output schema
+ * @returns Detailed validation result with errors
+ */
+declare function validateRuntimeOutputsDetailed(outputData: Record<string, any>, outputLayout: FlattenedLayout): ValidationResult;
+
+/**
+ * Get the cache directory path
+ * Exposes where compiled WASM modules are stored on disk
+ */
+declare function getCacheDirectory(): string;
+/**
+ * Get cache health diagnostics
+ * Returns information about cache status, any issues, and recent operations
+ */
+declare function getCacheHealth(): {
+    enabled: boolean;
+    directory: string;
+    directoryExists: boolean;
+    accessible: boolean;
+    stats: {
+        entries: number;
+        totalSize: number;
+        oldestEntry: number | null;
+        newestEntry: number | null;
+    };
+    issues: string[];
+};
+/**
+ * Clear the entire cache
+ */
+declare function clearCache(): void;
+/**
+ * Get cache statistics
+ */
+declare function getCacheStats(): {
+    entries: number;
+    totalSize: number;
+    oldestEntry: number | null;
+    newestEntry: number | null;
+};
+/**
+ * Prune old cache entries (keep most recent N entries or entries younger than maxAge)
+ */
+declare function pruneCache(options?: {
+    maxEntries?: number;
+    maxAgeMs?: number;
+}): number;
+/**
+ * Check if caching is enabled
+ * Can be disabled via JDM_ASM_NO_CACHE=1 environment variable
+ */
+declare function isCacheEnabled(): boolean;
+
+/**
+ * Main entry point: Compile JDM to WASM with schema-driven marshaling.
+ *
+ * @example
+ * const result = await compile({
+ *   inputSchema: InputSchema,
+ *   outputSchema: OutputSchema,
+ *   jdm: jdmJson,
+ *   optimize: true,
+ * });
+ */
+declare function compile(options: {
+    inputSchema: TSchema;
+    outputSchema: TSchema;
+    jdm: string | JDMDecision;
+    optimize?: boolean;
+    debug?: boolean;
+    /** How to handle cases where no rules match in decision tables/switches */
+    noMatchBehavior?: NoMatchBehavior;
+    /** Optional loader function to load sub-decision JDM files */
+    loadDecision?: CompilerOptions['loadDecision'];
+    /** Optional testDataRoot path for default loader to search */
+    testDataRoot?: string;
+}): Promise<CompilationResult>;
+
+export { type AssemblyScriptCode, type CompilationContext, CompilationError, type CompilationResult, type CompiledAST, CompiledDecision, type CompiledDecisionOptions, type CompilerOptions, ErrorCode, ErrorCollector, type FlattenedLayout, type JDMDecision, type JDMEdge, type JDMGraph, type JDMNode, type MarshalFn, type NoMatchBehavior, NodeType, type OptimizationPass, RuntimeError, type SourceLocation, type UnmarshalFn, type ValidateFn, type ValidationError, type ValidationResult, buildGraph, clearCache, clearExpressionCache, collectIdentifiers, collectOutputAssignments, compile, constantFolding, createCompiledDecision, deadCodeElimination, ensureMemory, expressionInlining, generateValidationCode, getCacheDirectory, getCacheHealth, getCacheStats, getEvaluationOrder, getExpressionCache, getInputNodes, getOutputNodes, isCacheEnabled, isCompilationError, isExpressionError, isFeatureError, isStructuralError, loadGeneratedMarshaling, loadGeneratedValidation, optimizer, parseJDM, pruneCache, runOptimizations, tableIndexing, validateAllInputReferences, validateAllOutputReferences, validateGraph, validateInputReferences, validateNodeStructure, validateOutputReferences, validateRuntimeInputs, validateRuntimeInputsDetailed, validateRuntimeOutputs, validateRuntimeOutputsDetailed };