@seljs/runtime 1.0.0 → 1.0.1

package/dist/environment/environment.cjs

@@ -0,0 +1,254 @@
+require("../_virtual/_rolldown/runtime.cjs");
+const require_context = require("./context.cjs");
+const require_replay_cache = require("./replay-cache.cjs");
+const require_debug = require("../debug.cjs");
+const require_errors = require("../errors/errors.cjs");
+require("../errors/index.cjs");
+const require_contract_caller = require("./contract-caller.cjs");
+const require_error_wrapper = require("./error-wrapper.cjs");
+const require_call_collector = require("../analysis/call-collector.cjs");
+const require_dependency_analyzer = require("../analysis/dependency-analyzer.cjs");
+const require_round_planner = require("../analysis/round-planner.cjs");
+const require_multi_round_executor = require("../execution/multi-round-executor.cjs");
+let _seljs_checker = require("@seljs/checker");
+let _seljs_common = require("@seljs/common");
+//#region src/environment/environment.ts
+/**
+* Core SEL runtime that bridges CEL expression evaluation with EVM contract reads.
+*
+* Manages a CEL runtime extended with Solidity primitive types (uint256, address, bool, etc.),
+* registered smart contracts whose view functions become callable in expressions, and typed
+* variables that are supplied at evaluation time. Contract calls are automatically batched
+* via multicall3 and executed in dependency-ordered rounds.
+*/
+const debug = require_debug.createLogger("environment");
+var SELRuntime = class {
+	env;
+	client;
+	schema;
+	variableTypes = /* @__PURE__ */ new Map();
+	maxRounds;
+	maxCalls;
+	multicallOptions;
+	contractBindings;
+	codecRegistry;
+	/**
+	* Per-evaluation mutable state.
+	*
+	* These fields are set before CEL evaluation and cleared in `finally`.
+	* They exist because the contract call handler closure (created in the
+	* constructor) needs access to per-evaluation context, but CEL's
+	* `Environment.parse()` returns a function that doesn't accept extra
+	* parameters beyond the variable bindings.
+	*
+	* Thread safety: The `mutex` field serializes concurrent `evaluate()`
+	* calls, ensuring these fields are never accessed concurrently.
+	*
+	* TODO: Consider refactoring to pass an EvaluationContext object through
+	* the handler closure instead of mutating instance state. This would
+	* eliminate the need for the mutex and make the code more testable.
+	* See .omc/drafts/context-object-spike.md for preliminary analysis.
+	*/
+	currentCache;
+	currentClient;
+	currentCallCounter;
+	/** Mutex to serialize concurrent evaluate() calls (protects current* fields) */
+	mutex = Promise.resolve();
+	/**
+	* Creates a new immutable SEL runtime with Solidity types pre-registered.
+	*
+	* Initializes the underlying CEL runtime, registers all Solidity primitive types,
+	* and processes any contracts and variables from the schema. After construction,
+	* the environment is fully configured and immutable.
+	*
+	* @param config - Configuration containing the SEL schema, optional viem client,
+	*   multicall settings, and CEL/execution limits (maxRounds defaults to 10, maxCalls to 100)
+	*/
+	constructor(config) {
+		const limits = config.limits;
+		const celLimits = limits ? {
+			maxAstNodes: limits.maxAstNodes,
+			maxDepth: limits.maxDepth,
+			maxListElements: limits.maxListElements,
+			maxMapEntries: limits.maxMapEntries,
+			maxCallArguments: limits.maxCallArguments
+		} : void 0;
+		this.maxRounds = limits?.maxRounds ?? 10;
+		this.maxCalls = limits?.maxCalls ?? 100;
+		this.multicallOptions = config.multicall;
+		this.client = config.client;
+		this.schema = config.schema;
+		const handler = (contractName, methodName, args) => {
+			const contract = this.findContract(contractName);
+			if (!contract) throw new require_errors.SELContractError(`Unknown contract "${contractName}"`, { contractName });
+			const method = contract.methods.find((m) => m.name === methodName);
+			if (!method) throw new require_errors.SELContractError(`Unknown method "${contractName}.${methodName}"`, {
+				contractName,
+				methodName
+			});
+			return require_contract_caller.executeContractCall(contract, method, args, {
+				executionCache: this.currentCache,
+				client: this.currentClient ?? this.client,
+				codecRegistry: this.codecRegistry,
+				callCounter: this.currentCallCounter
+			});
+		};
+		const { env, contractBindings, codecRegistry } = (0, _seljs_checker.createRuntimeEnvironment)(this.schema, handler, {
+			limits: celLimits,
+			unlistedVariablesAreDyn: true
+		});
+		this.env = env;
+		this.contractBindings = contractBindings;
+		this.codecRegistry = codecRegistry;
+		for (const v of this.schema.variables) this.variableTypes.set(v.name, v.type);
+	}
+	/**
+	* Type-checks an expression against registered variables and contract methods.
+	*
+	* @param expression - A CEL expression string to type-check
+	* @returns The type-check result containing validity, inferred type, and any errors
+	* @throws {@link SELTypeError} If the expression contains unrecoverable type errors
+	*/
+	check(expression) {
+		try {
+			return this.env.check(expression);
+		} catch (error) {
+			throw require_error_wrapper.wrapError(error);
+		}
+	}
+	/**
+	* Evaluates a SEL expression, executing any embedded contract calls on-chain.
+	*
+	* When contract calls are present, the full pipeline runs:
+	* 1. Parse the expression and collect contract calls from the AST
+	* 2. Type-check against registered variables and contract methods
+	* 3. Build a dependency graph and plan execution rounds
+	* 4. Execute contract calls via multicall3 batching at a pinned block number
+	* 5. Evaluate the CEL expression with resolved contract results and context values
+	* 6. Unwrap Solidity wrapper types back to native JS values (BigInt, string, etc.)
+	*
+	* @param expression A CEL expression string
+	* @param context Variable bindings for evaluation
+	* @param options Optional client override
+	* @returns An {@link EvaluateResult} containing the value and optional execution metadata
+	* @throws {@link SELParseError} If the expression has invalid syntax
+	* @throws {@link SELTypeError} If type-checking fails
+	* @throws {@link SELContractError} If a contract call fails or no client is available
+	* @throws {@link SELEvaluationError} If CEL evaluation fails
+	*/
+	async evaluate(expression, context, options) {
+		let release;
+		const prev = this.mutex;
+		this.mutex = new Promise((resolve) => {
+			release = resolve;
+		});
+		await prev;
+		try {
+			return await this.doEvaluate(expression, context, options);
+		} finally {
+			release();
+		}
+	}
+	planExecution(expression, evaluationContext) {
+		const parseResult = this.env.parse(expression);
+		const collectedCalls = require_call_collector.collectCalls(parseResult.ast, { get: (name) => this.findContract(name) });
+		debug("evaluate: collected %d calls", collectedCalls.length);
+		const normalizedContext = Object.keys(evaluationContext).length ? require_context.normalizeContextForEvaluation(evaluationContext, this.variableTypes, this.codecRegistry) : void 0;
+		const executionVariables = Object.keys(evaluationContext).length ? evaluationContext : {};
+		const typeCheckResult = parseResult.check();
+		if (!typeCheckResult.valid) throw new _seljs_common.SELTypeError(typeCheckResult.error?.message ?? "Type check failed", { cause: typeCheckResult.error });
+		return {
+			parseResult,
+			collectedCalls,
+			normalizedContext,
+			executionVariables,
+			typeCheckResult
+		};
+	}
+	async executeContractCalls(collectedCalls, executionVariables, resolvedClient) {
+		debug("evaluate: calls to execute — %o", collectedCalls.map((c) => `${c.contract}.${c.method}`));
+		const plan = require_round_planner.planRounds(require_dependency_analyzer.analyzeDependencies(collectedCalls), {
+			maxRounds: this.maxRounds,
+			maxCalls: this.maxCalls
+		});
+		const executor = new require_multi_round_executor.MultiRoundExecutor(resolvedClient, require_contract_caller.buildContractInfoMap(this.schema.contracts), this.multicallOptions);
+		let executionResult;
+		try {
+			executionResult = await executor.execute(plan, executionVariables, await require_contract_caller.resolveExecutionBlockNumber(resolvedClient));
+		} catch (error) {
+			let failedCall = collectedCalls[0];
+			if (error instanceof require_errors.MulticallBatchError) {
+				if (error.contractName && error.methodName) {
+					const contractName = error.contractName;
+					const methodName = error.methodName;
+					failedCall = {
+						...failedCall ?? {
+							id: "",
+							contract: contractName,
+							method: methodName,
+							args: [],
+							astNode: void 0
+						},
+						contract: contractName,
+						method: methodName
+					};
+				} else if (typeof error.failedCallIndex === "number") failedCall = collectedCalls[error.failedCallIndex] ?? failedCall;
+			}
+			if (!failedCall) throw error;
+			throw new require_errors.SELContractError(`Contract call failed: ${failedCall.contract}.${failedCall.method}`, {
+				cause: error,
+				contractName: failedCall.contract,
+				methodName: failedCall.method
+			});
+		}
+		return {
+			executionMeta: executionResult.meta,
+			executionCache: require_replay_cache.buildExecutionReplayCache(collectedCalls, executionResult.results, executionVariables, this.codecRegistry, (contract, method) => {
+				return (this.findContract(contract)?.methods.find((m) => m.name === method))?.params.map((p) => p.type) ?? [];
+			})
+		};
+	}
+	async doEvaluate(expression, context, options) {
+		debug("evaluate: %s", expression);
+		const resolvedClient = options?.client ?? this.client;
+		try {
+			const { parseResult, collectedCalls, normalizedContext, executionVariables, typeCheckResult } = this.planExecution(expression, context ?? {});
+			let executionMeta;
+			let executionCache;
+			if (collectedCalls.length > 0) {
+				if (!resolvedClient) throw new require_errors.SELContractError("No client provided for contract call. Provide a client in SELRuntime config or evaluate() options.", {
+					contractName: collectedCalls[0]?.contract,
+					methodName: collectedCalls[0]?.method
+				});
+				({executionMeta, executionCache} = await this.executeContractCalls(collectedCalls, executionVariables, resolvedClient));
+			}
+			this.currentCache = executionCache;
+			this.currentClient = resolvedClient;
+			this.currentCallCounter = new require_contract_caller.CallCounter(this.maxCalls, executionMeta?.totalCalls ?? 0);
+			let result;
+			try {
+				result = await parseResult({
+					...normalizedContext,
+					...this.contractBindings
+				});
+			} finally {
+				this.currentCache = void 0;
+				this.currentClient = void 0;
+				this.currentCallCounter = void 0;
+			}
+			const value = typeCheckResult.type ? this.codecRegistry.encode(typeCheckResult.type, result) : result;
+			debug("evaluate: result type=%s", typeof value);
+			return executionMeta ? {
+				value,
+				meta: executionMeta
+			} : { value };
+		} catch (error) {
+			throw require_error_wrapper.wrapError(error);
+		}
+	}
+	findContract(name) {
+		return this.schema.contracts.find((c) => c.name === name);
+	}
+};
+//#endregion
+exports.SELRuntime = SELRuntime;

package/dist/environment/environment.d.cts

@@ -0,0 +1,84 @@
+import { SELRuntimeConfig } from "./types.cjs";
+import { EvaluateOptions, EvaluateResult } from "../execution/types.cjs";
+import { TypeCheckResult } from "@marcbachmann/cel-js";
+
+//#region src/environment/environment.d.ts
+declare class SELRuntime {
+  private readonly env;
+  private readonly client?;
+  private readonly schema;
+  private readonly variableTypes;
+  private readonly maxRounds;
+  private readonly maxCalls;
+  private readonly multicallOptions?;
+  private readonly contractBindings;
+  private readonly codecRegistry;
+  /**
+   * Per-evaluation mutable state.
+   *
+   * These fields are set before CEL evaluation and cleared in `finally`.
+   * They exist because the contract call handler closure (created in the
+   * constructor) needs access to per-evaluation context, but CEL's
+   * `Environment.parse()` returns a function that doesn't accept extra
+   * parameters beyond the variable bindings.
+   *
+   * Thread safety: The `mutex` field serializes concurrent `evaluate()`
+   * calls, ensuring these fields are never accessed concurrently.
+   *
+   * TODO: Consider refactoring to pass an EvaluationContext object through
+   * the handler closure instead of mutating instance state. This would
+   * eliminate the need for the mutex and make the code more testable.
+   * See .omc/drafts/context-object-spike.md for preliminary analysis.
+   */
+  private currentCache?;
+  private currentClient?;
+  private currentCallCounter?;
+  /** Mutex to serialize concurrent evaluate() calls (protects current* fields) */
+  private mutex;
+  /**
+   * Creates a new immutable SEL runtime with Solidity types pre-registered.
+   *
+   * Initializes the underlying CEL runtime, registers all Solidity primitive types,
+   * and processes any contracts and variables from the schema. After construction,
+   * the environment is fully configured and immutable.
+   *
+   * @param config - Configuration containing the SEL schema, optional viem client,
+   *   multicall settings, and CEL/execution limits (maxRounds defaults to 10, maxCalls to 100)
+   */
+  constructor(config: SELRuntimeConfig);
+  /**
+   * Type-checks an expression against registered variables and contract methods.
+   *
+   * @param expression - A CEL expression string to type-check
+   * @returns The type-check result containing validity, inferred type, and any errors
+   * @throws {@link SELTypeError} If the expression contains unrecoverable type errors
+   */
+  check(expression: string): TypeCheckResult;
+  /**
+   * Evaluates a SEL expression, executing any embedded contract calls on-chain.
+   *
+   * When contract calls are present, the full pipeline runs:
+   * 1. Parse the expression and collect contract calls from the AST
+   * 2. Type-check against registered variables and contract methods
+   * 3. Build a dependency graph and plan execution rounds
+   * 4. Execute contract calls via multicall3 batching at a pinned block number
+   * 5. Evaluate the CEL expression with resolved contract results and context values
+   * 6. Unwrap Solidity wrapper types back to native JS values (BigInt, string, etc.)
+   *
+   * @param expression A CEL expression string
+   * @param context Variable bindings for evaluation
+   * @param options Optional client override
+   * @returns An {@link EvaluateResult} containing the value and optional execution metadata
+   * @throws {@link SELParseError} If the expression has invalid syntax
+   * @throws {@link SELTypeError} If type-checking fails
+   * @throws {@link SELContractError} If a contract call fails or no client is available
+   * @throws {@link SELEvaluationError} If CEL evaluation fails
+   */
+  evaluate<T = unknown>(expression: string, context?: Record<string, unknown>, options?: EvaluateOptions): Promise<EvaluateResult<T>>;
+  private planExecution;
+  private executeContractCalls;
+  private doEvaluate;
+  private findContract;
+}
+//#endregion
+export { SELRuntime };

package/dist/environment/environment.d.mts

@@ -0,0 +1,84 @@
+import { SELRuntimeConfig } from "./types.mjs";
+import { EvaluateOptions, EvaluateResult } from "../execution/types.mjs";
+import { TypeCheckResult } from "@marcbachmann/cel-js";
+
+//#region src/environment/environment.d.ts
+declare class SELRuntime {
+  private readonly env;
+  private readonly client?;
+  private readonly schema;
+  private readonly variableTypes;
+  private readonly maxRounds;
+  private readonly maxCalls;
+  private readonly multicallOptions?;
+  private readonly contractBindings;
+  private readonly codecRegistry;
+  /**
+   * Per-evaluation mutable state.
+   *
+   * These fields are set before CEL evaluation and cleared in `finally`.
+   * They exist because the contract call handler closure (created in the
+   * constructor) needs access to per-evaluation context, but CEL's
+   * `Environment.parse()` returns a function that doesn't accept extra
+   * parameters beyond the variable bindings.
+   *
+   * Thread safety: The `mutex` field serializes concurrent `evaluate()`
+   * calls, ensuring these fields are never accessed concurrently.
+   *
+   * TODO: Consider refactoring to pass an EvaluationContext object through
+   * the handler closure instead of mutating instance state. This would
+   * eliminate the need for the mutex and make the code more testable.
+   * See .omc/drafts/context-object-spike.md for preliminary analysis.
+   */
+  private currentCache?;
+  private currentClient?;
+  private currentCallCounter?;
+  /** Mutex to serialize concurrent evaluate() calls (protects current* fields) */
+  private mutex;
+  /**
+   * Creates a new immutable SEL runtime with Solidity types pre-registered.
+   *
+   * Initializes the underlying CEL runtime, registers all Solidity primitive types,
+   * and processes any contracts and variables from the schema. After construction,
+   * the environment is fully configured and immutable.
+   *
+   * @param config - Configuration containing the SEL schema, optional viem client,
+   *   multicall settings, and CEL/execution limits (maxRounds defaults to 10, maxCalls to 100)
+   */
+  constructor(config: SELRuntimeConfig);
+  /**
+   * Type-checks an expression against registered variables and contract methods.
+   *
+   * @param expression - A CEL expression string to type-check
+   * @returns The type-check result containing validity, inferred type, and any errors
+   * @throws {@link SELTypeError} If the expression contains unrecoverable type errors
+   */
+  check(expression: string): TypeCheckResult;
+  /**
+   * Evaluates a SEL expression, executing any embedded contract calls on-chain.
+   *
+   * When contract calls are present, the full pipeline runs:
+   * 1. Parse the expression and collect contract calls from the AST
+   * 2. Type-check against registered variables and contract methods
+   * 3. Build a dependency graph and plan execution rounds
+   * 4. Execute contract calls via multicall3 batching at a pinned block number
+   * 5. Evaluate the CEL expression with resolved contract results and context values
+   * 6. Unwrap Solidity wrapper types back to native JS values (BigInt, string, etc.)
+   *
+   * @param expression A CEL expression string
+   * @param context Variable bindings for evaluation
+   * @param options Optional client override
+   * @returns An {@link EvaluateResult} containing the value and optional execution metadata
+   * @throws {@link SELParseError} If the expression has invalid syntax
+   * @throws {@link SELTypeError} If type-checking fails
+   * @throws {@link SELContractError} If a contract call fails or no client is available
+   * @throws {@link SELEvaluationError} If CEL evaluation fails
+   */
+  evaluate<T = unknown>(expression: string, context?: Record<string, unknown>, options?: EvaluateOptions): Promise<EvaluateResult<T>>;
+  private planExecution;
+  private executeContractCalls;
+  private doEvaluate;
+  private findContract;
+}
+//#endregion
+export { SELRuntime };

package/dist/environment/environment.mjs

@@ -0,0 +1,252 @@
+import { normalizeContextForEvaluation } from "./context.mjs";
+import { buildExecutionReplayCache } from "./replay-cache.mjs";
+import { createLogger } from "../debug.mjs";
+import { MulticallBatchError, SELContractError, SELTypeError } from "../errors/errors.mjs";
+import "../errors/index.mjs";
+import { CallCounter, buildContractInfoMap, executeContractCall, resolveExecutionBlockNumber } from "./contract-caller.mjs";
+import { wrapError } from "./error-wrapper.mjs";
+import { collectCalls } from "../analysis/call-collector.mjs";
+import { analyzeDependencies } from "../analysis/dependency-analyzer.mjs";
+import { planRounds } from "../analysis/round-planner.mjs";
+import { MultiRoundExecutor } from "../execution/multi-round-executor.mjs";
+import { createRuntimeEnvironment } from "@seljs/checker";
+//#region src/environment/environment.ts
+/**
+* Core SEL runtime that bridges CEL expression evaluation with EVM contract reads.
+*
+* Manages a CEL runtime extended with Solidity primitive types (uint256, address, bool, etc.),
+* registered smart contracts whose view functions become callable in expressions, and typed
+* variables that are supplied at evaluation time. Contract calls are automatically batched
+* via multicall3 and executed in dependency-ordered rounds.
+*/
+const debug = createLogger("environment");
+var SELRuntime = class {
+	env;
+	client;
+	schema;
+	variableTypes = /* @__PURE__ */ new Map();
+	maxRounds;
+	maxCalls;
+	multicallOptions;
+	contractBindings;
+	codecRegistry;
+	/**
+	* Per-evaluation mutable state.
+	*
+	* These fields are set before CEL evaluation and cleared in `finally`.
+	* They exist because the contract call handler closure (created in the
+	* constructor) needs access to per-evaluation context, but CEL's
+	* `Environment.parse()` returns a function that doesn't accept extra
+	* parameters beyond the variable bindings.
+	*
+	* Thread safety: The `mutex` field serializes concurrent `evaluate()`
+	* calls, ensuring these fields are never accessed concurrently.
+	*
+	* TODO: Consider refactoring to pass an EvaluationContext object through
+	* the handler closure instead of mutating instance state. This would
+	* eliminate the need for the mutex and make the code more testable.
+	* See .omc/drafts/context-object-spike.md for preliminary analysis.
+	*/
+	currentCache;
+	currentClient;
+	currentCallCounter;
+	/** Mutex to serialize concurrent evaluate() calls (protects current* fields) */
+	mutex = Promise.resolve();
+	/**
+	* Creates a new immutable SEL runtime with Solidity types pre-registered.
+	*
+	* Initializes the underlying CEL runtime, registers all Solidity primitive types,
+	* and processes any contracts and variables from the schema. After construction,
+	* the environment is fully configured and immutable.
+	*
+	* @param config - Configuration containing the SEL schema, optional viem client,
+	*   multicall settings, and CEL/execution limits (maxRounds defaults to 10, maxCalls to 100)
+	*/
+	constructor(config) {
+		const limits = config.limits;
+		const celLimits = limits ? {
+			maxAstNodes: limits.maxAstNodes,
+			maxDepth: limits.maxDepth,
+			maxListElements: limits.maxListElements,
+			maxMapEntries: limits.maxMapEntries,
+			maxCallArguments: limits.maxCallArguments
+		} : void 0;
+		this.maxRounds = limits?.maxRounds ?? 10;
+		this.maxCalls = limits?.maxCalls ?? 100;
+		this.multicallOptions = config.multicall;
+		this.client = config.client;
+		this.schema = config.schema;
+		const handler = (contractName, methodName, args) => {
+			const contract = this.findContract(contractName);
+			if (!contract) throw new SELContractError(`Unknown contract "${contractName}"`, { contractName });
+			const method = contract.methods.find((m) => m.name === methodName);
+			if (!method) throw new SELContractError(`Unknown method "${contractName}.${methodName}"`, {
+				contractName,
+				methodName
+			});
+			return executeContractCall(contract, method, args, {
+				executionCache: this.currentCache,
+				client: this.currentClient ?? this.client,
+				codecRegistry: this.codecRegistry,
+				callCounter: this.currentCallCounter
+			});
+		};
+		const { env, contractBindings, codecRegistry } = createRuntimeEnvironment(this.schema, handler, {
+			limits: celLimits,
+			unlistedVariablesAreDyn: true
+		});
+		this.env = env;
+		this.contractBindings = contractBindings;
+		this.codecRegistry = codecRegistry;
+		for (const v of this.schema.variables) this.variableTypes.set(v.name, v.type);
+	}
+	/**
+	* Type-checks an expression against registered variables and contract methods.
+	*
+	* @param expression - A CEL expression string to type-check
+	* @returns The type-check result containing validity, inferred type, and any errors
+	* @throws {@link SELTypeError} If the expression contains unrecoverable type errors
+	*/
+	check(expression) {
+		try {
+			return this.env.check(expression);
+		} catch (error) {
+			throw wrapError(error);
+		}
+	}
+	/**
+	* Evaluates a SEL expression, executing any embedded contract calls on-chain.
+	*
+	* When contract calls are present, the full pipeline runs:
+	* 1. Parse the expression and collect contract calls from the AST
+	* 2. Type-check against registered variables and contract methods
+	* 3. Build a dependency graph and plan execution rounds
+	* 4. Execute contract calls via multicall3 batching at a pinned block number
+	* 5. Evaluate the CEL expression with resolved contract results and context values
+	* 6. Unwrap Solidity wrapper types back to native JS values (BigInt, string, etc.)
+	*
+	* @param expression A CEL expression string
+	* @param context Variable bindings for evaluation
+	* @param options Optional client override
+	* @returns An {@link EvaluateResult} containing the value and optional execution metadata
+	* @throws {@link SELParseError} If the expression has invalid syntax
+	* @throws {@link SELTypeError} If type-checking fails
+	* @throws {@link SELContractError} If a contract call fails or no client is available
+	* @throws {@link SELEvaluationError} If CEL evaluation fails
+	*/
+	async evaluate(expression, context, options) {
+		let release;
+		const prev = this.mutex;
+		this.mutex = new Promise((resolve) => {
+			release = resolve;
+		});
+		await prev;
+		try {
+			return await this.doEvaluate(expression, context, options);
+		} finally {
+			release();
+		}
+	}
+	planExecution(expression, evaluationContext) {
+		const parseResult = this.env.parse(expression);
+		const collectedCalls = collectCalls(parseResult.ast, { get: (name) => this.findContract(name) });
+		debug("evaluate: collected %d calls", collectedCalls.length);
+		const normalizedContext = Object.keys(evaluationContext).length ? normalizeContextForEvaluation(evaluationContext, this.variableTypes, this.codecRegistry) : void 0;
+		const executionVariables = Object.keys(evaluationContext).length ? evaluationContext : {};
+		const typeCheckResult = parseResult.check();
+		if (!typeCheckResult.valid) throw new SELTypeError(typeCheckResult.error?.message ?? "Type check failed", { cause: typeCheckResult.error });
+		return {
+			parseResult,
+			collectedCalls,
+			normalizedContext,
+			executionVariables,
+			typeCheckResult
+		};
+	}
+	async executeContractCalls(collectedCalls, executionVariables, resolvedClient) {
+		debug("evaluate: calls to execute — %o", collectedCalls.map((c) => `${c.contract}.${c.method}`));
+		const plan = planRounds(analyzeDependencies(collectedCalls), {
+			maxRounds: this.maxRounds,
+			maxCalls: this.maxCalls
+		});
+		const executor = new MultiRoundExecutor(resolvedClient, buildContractInfoMap(this.schema.contracts), this.multicallOptions);
+		let executionResult;
+		try {
+			executionResult = await executor.execute(plan, executionVariables, await resolveExecutionBlockNumber(resolvedClient));
+		} catch (error) {
+			let failedCall = collectedCalls[0];
+			if (error instanceof MulticallBatchError) {
+				if (error.contractName && error.methodName) {
+					const contractName = error.contractName;
+					const methodName = error.methodName;
+					failedCall = {
+						...failedCall ?? {
+							id: "",
+							contract: contractName,
+							method: methodName,
+							args: [],
+							astNode: void 0
+						},
+						contract: contractName,
+						method: methodName
+					};
+				} else if (typeof error.failedCallIndex === "number") failedCall = collectedCalls[error.failedCallIndex] ?? failedCall;
+			}
+			if (!failedCall) throw error;
+			throw new SELContractError(`Contract call failed: ${failedCall.contract}.${failedCall.method}`, {
+				cause: error,
+				contractName: failedCall.contract,
+				methodName: failedCall.method
+			});
+		}
+		return {
+			executionMeta: executionResult.meta,
+			executionCache: buildExecutionReplayCache(collectedCalls, executionResult.results, executionVariables, this.codecRegistry, (contract, method) => {
+				return (this.findContract(contract)?.methods.find((m) => m.name === method))?.params.map((p) => p.type) ?? [];
+			})
+		};
+	}
+	async doEvaluate(expression, context, options) {
+		debug("evaluate: %s", expression);
+		const resolvedClient = options?.client ?? this.client;
+		try {
+			const { parseResult, collectedCalls, normalizedContext, executionVariables, typeCheckResult } = this.planExecution(expression, context ?? {});
+			let executionMeta;
+			let executionCache;
+			if (collectedCalls.length > 0) {
+				if (!resolvedClient) throw new SELContractError("No client provided for contract call. Provide a client in SELRuntime config or evaluate() options.", {
+					contractName: collectedCalls[0]?.contract,
+					methodName: collectedCalls[0]?.method
+				});
+				({executionMeta, executionCache} = await this.executeContractCalls(collectedCalls, executionVariables, resolvedClient));
+			}
+			this.currentCache = executionCache;
+			this.currentClient = resolvedClient;
+			this.currentCallCounter = new CallCounter(this.maxCalls, executionMeta?.totalCalls ?? 0);
+			let result;
+			try {
+				result = await parseResult({
+					...normalizedContext,
+					...this.contractBindings
+				});
+			} finally {
+				this.currentCache = void 0;
+				this.currentClient = void 0;
+				this.currentCallCounter = void 0;
+			}
+			const value = typeCheckResult.type ? this.codecRegistry.encode(typeCheckResult.type, result) : result;
+			debug("evaluate: result type=%s", typeof value);
+			return executionMeta ? {
+				value,
+				meta: executionMeta
+			} : { value };
+		} catch (error) {
+			throw wrapError(error);
+		}
+	}
+	findContract(name) {
+		return this.schema.contracts.find((c) => c.name === name);
+	}
+};
+//#endregion
+export { SELRuntime };