@seljs/runtime 1.0.0 → 1.0.1

package/dist/analysis/round-planner.cjs

@@ -0,0 +1,65 @@
+const require_debug = require("../debug.cjs");
+const require_errors = require("../errors/errors.cjs");
+require("../errors/index.cjs");
+//#region src/analysis/round-planner.ts
+const debug = require_debug.createLogger("analysis:plan");
+/**
+* Plans execution rounds from a dependency graph using topological sorting.
+*
+* Groups independent calls into parallel rounds, ensuring all dependencies
+* of a call are executed in previous rounds. Enforces limits on the number
+* of rounds and total calls to prevent excessive execution.
+*
+* @param graph Dependency graph representing calls and their relationships.
+* @param limits Optional limits for maximum rounds and total calls.
+* @returns Execution plan containing planned rounds, total calls, and maximum depth.
+* @throws ExecutionLimitError If total calls exceed maxCalls or rounds exceed maxRounds.
+*/
+const planRounds = (graph, limits = {}) => {
+	const maxRounds = limits.maxRounds ?? 10;
+	const maxCalls = limits.maxCalls ?? 100;
+	const totalCalls = graph.nodes.size;
+	if (totalCalls > maxCalls) throw new require_errors.ExecutionLimitError(`Execution limit exceeded: ${String(totalCalls)} calls exceeds maxCalls (${String(maxCalls)})`, {
+		limitType: "maxCalls",
+		limit: maxCalls,
+		actual: totalCalls
+	});
+	if (totalCalls === 0) return {
+		rounds: [],
+		totalCalls: 0,
+		maxDepth: 0
+	};
+	const inDegree = /* @__PURE__ */ new Map();
+	for (const nodeId of graph.nodes.keys()) inDegree.set(nodeId, graph.edges.get(nodeId)?.size ?? 0);
+	const rounds = [];
+	const processed = /* @__PURE__ */ new Set();
+	while (processed.size < totalCalls) {
+		const readyNodes = [];
+		for (const [nodeId, degree] of inDegree) if (degree === 0 && !processed.has(nodeId)) readyNodes.push(nodeId);
+		if (readyNodes.length === 0) break;
+		if (rounds.length >= maxRounds) throw new require_errors.ExecutionLimitError(`Execution limit exceeded: requires more than maxRounds (${String(maxRounds)}) rounds`, {
+			limitType: "maxRounds",
+			limit: maxRounds,
+			actual: rounds.length + 1
+		});
+		const round = {
+			roundNumber: rounds.length,
+			calls: readyNodes.map((id) => graph.nodes.get(id)?.call).filter((c) => c !== void 0)
+		};
+		rounds.push(round);
+		for (const nodeId of readyNodes) {
+			processed.add(nodeId);
+			const node = graph.nodes.get(nodeId);
+			if (!node) continue;
+			for (const dependentId of node.dependedOnBy) inDegree.set(dependentId, (inDegree.get(dependentId) ?? 0) - 1);
+		}
+	}
+	debug("planned %d rounds for %d calls (max depth=%d)", rounds.length, totalCalls, rounds.length);
+	return {
+		rounds,
+		totalCalls,
+		maxDepth: rounds.length
+	};
+};
+//#endregion
+exports.planRounds = planRounds;

package/dist/analysis/round-planner.mjs

@@ -0,0 +1,65 @@
+import { createLogger } from "../debug.mjs";
+import { ExecutionLimitError } from "../errors/errors.mjs";
+import "../errors/index.mjs";
+//#region src/analysis/round-planner.ts
+const debug = createLogger("analysis:plan");
+/**
+* Plans execution rounds from a dependency graph using topological sorting.
+*
+* Groups independent calls into parallel rounds, ensuring all dependencies
+* of a call are executed in previous rounds. Enforces limits on the number
+* of rounds and total calls to prevent excessive execution.
+*
+* @param graph Dependency graph representing calls and their relationships.
+* @param limits Optional limits for maximum rounds and total calls.
+* @returns Execution plan containing planned rounds, total calls, and maximum depth.
+* @throws ExecutionLimitError If total calls exceed maxCalls or rounds exceed maxRounds.
+*/
+const planRounds = (graph, limits = {}) => {
+	const maxRounds = limits.maxRounds ?? 10;
+	const maxCalls = limits.maxCalls ?? 100;
+	const totalCalls = graph.nodes.size;
+	if (totalCalls > maxCalls) throw new ExecutionLimitError(`Execution limit exceeded: ${String(totalCalls)} calls exceeds maxCalls (${String(maxCalls)})`, {
+		limitType: "maxCalls",
+		limit: maxCalls,
+		actual: totalCalls
+	});
+	if (totalCalls === 0) return {
+		rounds: [],
+		totalCalls: 0,
+		maxDepth: 0
+	};
+	const inDegree = /* @__PURE__ */ new Map();
+	for (const nodeId of graph.nodes.keys()) inDegree.set(nodeId, graph.edges.get(nodeId)?.size ?? 0);
+	const rounds = [];
+	const processed = /* @__PURE__ */ new Set();
+	while (processed.size < totalCalls) {
+		const readyNodes = [];
+		for (const [nodeId, degree] of inDegree) if (degree === 0 && !processed.has(nodeId)) readyNodes.push(nodeId);
+		if (readyNodes.length === 0) break;
+		if (rounds.length >= maxRounds) throw new ExecutionLimitError(`Execution limit exceeded: requires more than maxRounds (${String(maxRounds)}) rounds`, {
+			limitType: "maxRounds",
+			limit: maxRounds,
+			actual: rounds.length + 1
+		});
+		const round = {
+			roundNumber: rounds.length,
+			calls: readyNodes.map((id) => graph.nodes.get(id)?.call).filter((c) => c !== void 0)
+		};
+		rounds.push(round);
+		for (const nodeId of readyNodes) {
+			processed.add(nodeId);
+			const node = graph.nodes.get(nodeId);
+			if (!node) continue;
+			for (const dependentId of node.dependedOnBy) inDegree.set(dependentId, (inDegree.get(dependentId) ?? 0) - 1);
+		}
+	}
+	debug("planned %d rounds for %d calls (max depth=%d)", rounds.length, totalCalls, rounds.length);
+	return {
+		rounds,
+		totalCalls,
+		maxDepth: rounds.length
+	};
+};
+//#endregion
+export { planRounds };

package/dist/analysis/types.d.cts

@@ -0,0 +1,115 @@
+//#region src/analysis/types.d.ts
+/**
+ * Represents a contract call found in AST traversal.
+ * Contains all information needed to execute the call and track dependencies.
+ */
+interface CollectedCall {
+  /**
+   * Unique identifier: "contract:method:serializedArgs"
+   */
+  id: string;
+  /**
+   * Contract name: e.g., "erc20_usdc"
+   */
+  contract: string;
+  /**
+   * Method name: e.g., "balanceOf"
+   */
+  method: string;
+  /**
+   * Arguments with type and dependency information
+   */
+  args: CallArgument[];
+  /**
+   * Reference to original AST node for error reporting
+   */
+  astNode: unknown;
+}
+/**
+ * Argument to a contract call with type information.
+ * Tracks whether the argument is a literal, variable, or result of another call.
+ */
+interface CallArgument {
+  /**
+   * Type of argument: literal value, variable reference, or call result
+   */
+  type: "literal" | "variable" | "call_result";
+  /**
+   * Literal value (when type is "literal")
+   */
+  value?: unknown;
+  /**
+   * Variable name (when type is "variable")
+   */
+  variableName?: string;
+  /**
+   * Call ID this depends on (when type is "call_result")
+   */
+  dependsOnCallId?: string;
+}
+/**
+ * Dependency graph for all collected calls.
+ * Maps call IDs to their nodes and dependency relationships.
+ */
+interface DependencyGraph {
+  /**
+   * Call ID to graph node mapping
+   */
+  nodes: Map<string, GraphNode>;
+  /**
+   * Call ID to set of call IDs it depends on
+   */
+  edges: Map<string, Set<string>>;
+}
+/**
+ * Single node in the dependency graph.
+ * Tracks both incoming and outgoing dependencies.
+ */
+interface GraphNode {
+  /**
+   * The original collected call
+   */
+  call: CollectedCall;
+  /**
+   * Call IDs this call depends on (must complete first)
+   */
+  dependsOn: string[];
+  /**
+   * Call IDs that depend on this call (will execute after)
+   */
+  dependedOnBy: string[];
+}
+/**
+ * Execution plan with rounds of parallel calls.
+ * Result of topological sorting the dependency graph.
+ */
+interface ExecutionPlan {
+  /**
+   * Rounds of calls to execute in sequence
+   */
+  rounds: ExecutionRound[];
+  /**
+   * Total number of calls across all rounds
+   */
+  totalCalls: number;
+  /**
+   * Number of rounds (maximum dependency depth)
+   */
+  maxDepth: number;
+}
+/**
+ * Single round of calls that can execute in parallel.
+ * All calls in a round have no dependencies on each other.
+ */
+interface ExecutionRound {
+  /**
+   * Round number (0-indexed)
+   */
+  roundNumber: number;
+  /**
+   * Calls that can execute in parallel this round
+   */
+  calls: CollectedCall[];
+}
+//#endregion
+export { CallArgument, CollectedCall, DependencyGraph, ExecutionPlan, ExecutionRound, GraphNode };

package/dist/analysis/types.d.mts

@@ -0,0 +1,115 @@
+//#region src/analysis/types.d.ts
+/**
+ * Represents a contract call found in AST traversal.
+ * Contains all information needed to execute the call and track dependencies.
+ */
+interface CollectedCall {
+  /**
+   * Unique identifier: "contract:method:serializedArgs"
+   */
+  id: string;
+  /**
+   * Contract name: e.g., "erc20_usdc"
+   */
+  contract: string;
+  /**
+   * Method name: e.g., "balanceOf"
+   */
+  method: string;
+  /**
+   * Arguments with type and dependency information
+   */
+  args: CallArgument[];
+  /**
+   * Reference to original AST node for error reporting
+   */
+  astNode: unknown;
+}
+/**
+ * Argument to a contract call with type information.
+ * Tracks whether the argument is a literal, variable, or result of another call.
+ */
+interface CallArgument {
+  /**
+   * Type of argument: literal value, variable reference, or call result
+   */
+  type: "literal" | "variable" | "call_result";
+  /**
+   * Literal value (when type is "literal")
+   */
+  value?: unknown;
+  /**
+   * Variable name (when type is "variable")
+   */
+  variableName?: string;
+  /**
+   * Call ID this depends on (when type is "call_result")
+   */
+  dependsOnCallId?: string;
+}
+/**
+ * Dependency graph for all collected calls.
+ * Maps call IDs to their nodes and dependency relationships.
+ */
+interface DependencyGraph {
+  /**
+   * Call ID to graph node mapping
+   */
+  nodes: Map<string, GraphNode>;
+  /**
+   * Call ID to set of call IDs it depends on
+   */
+  edges: Map<string, Set<string>>;
+}
+/**
+ * Single node in the dependency graph.
+ * Tracks both incoming and outgoing dependencies.
+ */
+interface GraphNode {
+  /**
+   * The original collected call
+   */
+  call: CollectedCall;
+  /**
+   * Call IDs this call depends on (must complete first)
+   */
+  dependsOn: string[];
+  /**
+   * Call IDs that depend on this call (will execute after)
+   */
+  dependedOnBy: string[];
+}
+/**
+ * Execution plan with rounds of parallel calls.
+ * Result of topological sorting the dependency graph.
+ */
+interface ExecutionPlan {
+  /**
+   * Rounds of calls to execute in sequence
+   */
+  rounds: ExecutionRound[];
+  /**
+   * Total number of calls across all rounds
+   */
+  totalCalls: number;
+  /**
+   * Number of rounds (maximum dependency depth)
+   */
+  maxDepth: number;
+}
+/**
+ * Single round of calls that can execute in parallel.
+ * All calls in a round have no dependencies on each other.
+ */
+interface ExecutionRound {
+  /**
+   * Round number (0-indexed)
+   */
+  roundNumber: number;
+  /**
+   * Calls that can execute in parallel this round
+   */
+  calls: CollectedCall[];
+}
+//#endregion
+export { CallArgument, CollectedCall, DependencyGraph, ExecutionPlan, ExecutionRound, GraphNode };

package/dist/debug.cjs

@@ -0,0 +1,17 @@
+const require_runtime = require("./_virtual/_rolldown/runtime.cjs");
+let debug = require("debug");
+debug = require_runtime.__toESM(debug);
+//#region src/debug.ts
+/**
+* Creates a namespaced debug logger for a SEL module.
+*
+* Enable via the `DEBUG` environment variable:
+* - `DEBUG=sel:*`           — all SEL logging
+* - `DEBUG=sel:evaluate`    — only evaluate flow
+* - `DEBUG=sel:execute:*`   — all execution sub-loggers
+*
+* @param namespace - Module namespace (e.g. "evaluate", "execute:round")
+*/
+const createLogger = (namespace) => (0, debug.default)(`sel:${namespace}`);
+//#endregion
+exports.createLogger = createLogger;

package/dist/debug.mjs

@@ -0,0 +1,15 @@
+import createDebug from "debug";
+//#region src/debug.ts
+/**
+* Creates a namespaced debug logger for a SEL module.
+*
+* Enable via the `DEBUG` environment variable:
+* - `DEBUG=sel:*`           — all SEL logging
+* - `DEBUG=sel:evaluate`    — only evaluate flow
+* - `DEBUG=sel:execute:*`   — all execution sub-loggers
+*
+* @param namespace - Module namespace (e.g. "evaluate", "execute:round")
+*/
+const createLogger = (namespace) => createDebug(`sel:${namespace}`);
+//#endregion
+export { createLogger };

package/dist/environment/context.cjs

@@ -0,0 +1,11 @@
+//#region src/environment/context.ts
+const normalizeContextForEvaluation = (context, variableTypes, codecRegistry) => {
+	const normalized = {};
+	for (const [key, value] of Object.entries(context)) {
+		const type = variableTypes.get(key);
+		normalized[key] = codecRegistry.resolve(type ?? "dyn").parse(value);
+	}
+	return normalized;
+};
+//#endregion
+exports.normalizeContextForEvaluation = normalizeContextForEvaluation;

package/dist/environment/context.mjs

@@ -0,0 +1,11 @@
+//#region src/environment/context.ts
+const normalizeContextForEvaluation = (context, variableTypes, codecRegistry) => {
+	const normalized = {};
+	for (const [key, value] of Object.entries(context)) {
+		const type = variableTypes.get(key);
+		normalized[key] = codecRegistry.resolve(type ?? "dyn").parse(value);
+	}
+	return normalized;
+};
+//#endregion
+export { normalizeContextForEvaluation };

package/dist/environment/contract-caller.cjs

@@ -0,0 +1,81 @@
+require("../_virtual/_rolldown/runtime.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");
+let viem_actions = require("viem/actions");
+//#region src/environment/contract-caller.ts
+const debug = require_debug.createLogger("contract-caller");
+/**
+* Tracks total RPC calls (pre-executed + live) across a single evaluation.
+* Create one per `evaluate()` call and pass it through the handler closure.
+*/
+var CallCounter = class {
+	count = 0;
+	constructor(maxCalls, initialCount = 0) {
+		this.maxCalls = maxCalls;
+		this.count = initialCount;
+	}
+	increment(contractName, methodName) {
+		this.count++;
+		if (this.count > this.maxCalls) throw new require_errors.ExecutionLimitError(`Execution limit exceeded: ${String(this.count)} calls exceeds maxCalls (${String(this.maxCalls)})`, {
+			limitType: "maxCalls",
+			limit: this.maxCalls,
+			actual: this.count
+		});
+		debug("call count: %d/%d (%s.%s)", this.count, this.maxCalls, contractName, methodName);
+	}
+};
+const executeContractCall = async (contract, method, args, options) => {
+	const normalizedArgs = options.codecRegistry ? args.map((arg, i) => options.codecRegistry.encode(method.params[i]?.type ?? "dyn", arg)) : args;
+	if (options.executionCache) {
+		const callId = require_replay_cache.createReplayCallId(contract.name, method.name, normalizedArgs);
+		if (options.executionCache.has(callId)) {
+			debug("cache hit: %s.%s", contract.name, method.name);
+			return options.executionCache.get(callId);
+		}
+		debug("cache miss: %s.%s — executing live", contract.name, method.name);
+	}
+	if (!options.client) throw new require_errors.SELContractError("No client provided for contract call. Provide a client in SELRuntime config or evaluate() context.", {
+		contractName: contract.name,
+		methodName: method.name
+	});
+	options.callCounter?.increment(contract.name, method.name);
+	try {
+		return await (0, viem_actions.readContract)(options.client, {
+			address: contract.address,
+			abi: [method.abi],
+			functionName: method.name,
+			args: normalizedArgs
+		});
+	} catch (error) {
+		if (error instanceof require_errors.SELContractError) throw error;
+		throw new require_errors.SELContractError(`Contract call failed: ${contract.name}.${method.name}`, {
+			cause: error,
+			contractName: contract.name,
+			methodName: method.name
+		});
+	}
+};
+const resolveExecutionBlockNumber = async (client) => {
+	const clientWithGetBlockNumber = client;
+	if (typeof clientWithGetBlockNumber.getBlockNumber === "function") return await clientWithGetBlockNumber.getBlockNumber();
+	if (typeof clientWithGetBlockNumber.request === "function") return;
+	return 0n;
+};
+const buildContractInfoMap = (contracts) => {
+	const map = /* @__PURE__ */ new Map();
+	for (const contract of contracts) {
+		const abi = contract.methods.map((m) => m.abi);
+		map.set(contract.name, {
+			abi,
+			address: contract.address
+		});
+	}
+	return map;
+};
+//#endregion
+exports.CallCounter = CallCounter;
+exports.buildContractInfoMap = buildContractInfoMap;
+exports.executeContractCall = executeContractCall;
+exports.resolveExecutionBlockNumber = resolveExecutionBlockNumber;

package/dist/environment/contract-caller.mjs

@@ -0,0 +1,77 @@
+import { createReplayCallId } from "./replay-cache.mjs";
+import { createLogger } from "../debug.mjs";
+import { ExecutionLimitError, SELContractError } from "../errors/errors.mjs";
+import "../errors/index.mjs";
+import { readContract } from "viem/actions";
+//#region src/environment/contract-caller.ts
+const debug = createLogger("contract-caller");
+/**
+* Tracks total RPC calls (pre-executed + live) across a single evaluation.
+* Create one per `evaluate()` call and pass it through the handler closure.
+*/
+var CallCounter = class {
+	count = 0;
+	constructor(maxCalls, initialCount = 0) {
+		this.maxCalls = maxCalls;
+		this.count = initialCount;
+	}
+	increment(contractName, methodName) {
+		this.count++;
+		if (this.count > this.maxCalls) throw new ExecutionLimitError(`Execution limit exceeded: ${String(this.count)} calls exceeds maxCalls (${String(this.maxCalls)})`, {
+			limitType: "maxCalls",
+			limit: this.maxCalls,
+			actual: this.count
+		});
+		debug("call count: %d/%d (%s.%s)", this.count, this.maxCalls, contractName, methodName);
+	}
+};
+const executeContractCall = async (contract, method, args, options) => {
+	const normalizedArgs = options.codecRegistry ? args.map((arg, i) => options.codecRegistry.encode(method.params[i]?.type ?? "dyn", arg)) : args;
+	if (options.executionCache) {
+		const callId = createReplayCallId(contract.name, method.name, normalizedArgs);
+		if (options.executionCache.has(callId)) {
+			debug("cache hit: %s.%s", contract.name, method.name);
+			return options.executionCache.get(callId);
+		}
+		debug("cache miss: %s.%s — executing live", contract.name, method.name);
+	}
+	if (!options.client) throw new SELContractError("No client provided for contract call. Provide a client in SELRuntime config or evaluate() context.", {
+		contractName: contract.name,
+		methodName: method.name
+	});
+	options.callCounter?.increment(contract.name, method.name);
+	try {
+		return await readContract(options.client, {
+			address: contract.address,
+			abi: [method.abi],
+			functionName: method.name,
+			args: normalizedArgs
+		});
+	} catch (error) {
+		if (error instanceof SELContractError) throw error;
+		throw new SELContractError(`Contract call failed: ${contract.name}.${method.name}`, {
+			cause: error,
+			contractName: contract.name,
+			methodName: method.name
+		});
+	}
+};
+const resolveExecutionBlockNumber = async (client) => {
+	const clientWithGetBlockNumber = client;
+	if (typeof clientWithGetBlockNumber.getBlockNumber === "function") return await clientWithGetBlockNumber.getBlockNumber();
+	if (typeof clientWithGetBlockNumber.request === "function") return;
+	return 0n;
+};
+const buildContractInfoMap = (contracts) => {
+	const map = /* @__PURE__ */ new Map();
+	for (const contract of contracts) {
+		const abi = contract.methods.map((m) => m.abi);
+		map.set(contract.name, {
+			abi,
+			address: contract.address
+		});
+	}
+	return map;
+};
+//#endregion
+export { CallCounter, buildContractInfoMap, executeContractCall, resolveExecutionBlockNumber };