feat(vm): add maxSteps execution budget by Dayifour · Pull Request #2 · darylcecile/jsvm

Dayifour · 2026-05-04T06:49:47Z

Add maxSteps execution budget to VM API

Summary

expose maxSteps in executionRules and per-call options
wire step budget into evaluation contexts and handle calls
document step budgets and add VM tests for step exhaustion

Testing

bun test
bun run typecheck

Dayifour · 2026-05-04T07:06:21Z

@darylcecile Ready for review!

Copilot

Pull request overview

This PR adds a cooperative maxSteps execution budget to the VM’s public API so hosts can limit interpreted work in addition to the existing wall-clock guard. It extends the VM resource-limiting model, updates docs, and adds basic regression coverage.

Changes:

Add maxSteps to VM execution rule types and per-call evaluation/import options.
Thread the step budget into evaluation, import, URL-evaluation, and handle execution contexts.
Document step budgets in the README and add a VM test for step exhaustion.

Show a summary per file

File	Description
`src/vm.ts`	Adds the new `maxSteps` API surface, normalizes it, and passes it into VM execution contexts.
`test/vm.test.ts`	Adds coverage for step-budget exhaustion through `vm.eval(...)`.
`README.md`	Documents `maxSteps` in the VM options and resource-limits sections.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 3/3 changed files
Comments generated: 5

+    expectVMFailure(
+      await overrideVm.eval("let i = 0; while (true) { i += 1; }", { maxSteps: 5 }),


+      const maxSteps = normalizeMaxSteps(
+        options.maxSteps ?? this.#executionRules.maxSteps,
+      );
+      const rootContext = this.#createEvaluationContext(timeLimit, maxSteps);


      return this.evaluate(response.bodyText, {
        sourceType: options.sourceType,
        timeLimit: options.timeLimit,
+        maxSteps: options.maxSteps,


+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new VMError(
+      VMErrorCode.VMRuntimeError,
+      "executionRules.maxSteps must be a non-negative safe integer.",



 Therefore time limits are guardrails, not hard CPU guarantees. A synchronous host capability can still block while it runs, and there is currently no independent memory limit, public instruction counter, scheduler, or deterministic event loop.

+`executionRules.maxSteps` and per-call `evaluate(source, { maxSteps })` provide a cooperative step budget:


darylcecile · 2026-05-04T13:52:59Z

See suggestions from the copilot review above. Also, im not sure VMErrorCode.VMTimeoutError is the right error for maxSteps, something like VMErrorCode.VMStepsExceededError would be better

…n steps-exceeded error, tighten test

Dayifour · 2026-05-06T12:11:30Z

@darylcecile I've integrated the suggestions from Copilot and your feedback.
The new commit includes the VMStepsExceededError code and better validation for URL evaluation. I also fixed the test logic to properly check the budget override. Let me know if everything looks good to you now

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Dayifour · 2026-05-18T22:38:47Z

Hey @darylcecile, had a chance to look at the PR? Everything is up to date on my end

Copilot

Copilot's findings

Comments suppressed due to low confidence (1)

src/vm.ts:1002

Deleting the module record from #moduleGraph on any evaluation failure means a module that throws (or has side effects before throwing) will be reloaded and re-executed on subsequent vm.import() calls, which diverges from typical ES module caching semantics and can cause repeated side effects / extra work. If the goal is specifically to allow retries after budget exhaustion, consider only deleting the record for budget-related failures (e.g. VM_STEPS_EXCEEDED_ERROR / VM_TIMEOUT_ERROR) and caching failures for other runtime errors.

      // If evaluation failed for any reason, remove the partially-created
      // module record from the graph so callers can retry with a different
      // execution budget or after a reset. This avoids permanently
      // caching exhausted/failed module records.
      graph.delete(record.specifier);
      if (record.status !== "evaluated") {
        record.status = "linked";
      }
      throw error;

Files reviewed: 7/7 changed files
Comments generated: 2

darylcecile · 2026-05-19T17:29:30Z

+  // Accept a plain object shape that carries a `code` string to preserve
+  // propagated VM error codes across boundaries where the original class
+  // identity may be lost (for example, when crossing promise boundaries).
+  if (typeof error === "object" && error !== null && "code" in (error as any)) {
+    try {
+      const maybeCode = (error as any).code as string | undefined;
+      const message = (error as any).message ?? String(error);
+      const details = (error as any).details ?? {};
+      if (typeof maybeCode === "string") {
+        return new VMError(maybeCode as VMErrorCode, message, details as any);


@Dayifour lets add a type narrowing helper here

darylcecile · 2026-05-19T17:28:31Z

@@ -795,7 +861,10 @@ export class VM {
        );
      }

-      if (maxBytes !== undefined && utf8ByteLength(response.bodyText) > maxBytes) {
+      if (
+        maxBytes !== undefined &&
+        utf8ByteLength(response.bodyText) > maxBytes
+      ) {
        return failure(
          new VMError(
            VMErrorCode.VMSecurityError,
@@ -808,6 +877,7 @@ export class VM {
      return this.evaluate(response.bodyText, {
        sourceType: options.sourceType,
        timeLimit: options.timeLimit,
+        maxSteps: options.maxSteps,
      });


@Dayifour lets add this in

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 7 comments.

Comments suppressed due to low confidence (1)

README.md:1

Two documentation issues on the updated lines: (1) the example code block mixes tabs and spaces on the new maxSteps line, which breaks alignment in the rendered snippet; and (2) the API snippet states capabilities.executionRules exists while also listing a top-level executionRules alias—please ensure this matches the actual VMOptions shape implemented in src/vm.ts (if capabilities.executionRules is not supported, it should be removed from the README; if it is supported, the implementation should reflect it consistently).

# @catmint-fs/jsvm

+      record.failure = undefined;
    } catch (error) {
-      if (record.status !== "evaluated") {
-        record.status = "linked";
+      const failure = toVMError(error);
+
+      if (isRetryableModuleFailure(failure)) {
+        graph.delete(record.specifier);
+      } else {
+        record.status = "failed";
+        record.failure = failure;
      }
-      throw error;
+
+      throw failure;
    }


+  if (isVMErrorRecord(error)) {
+    return new VMError(error.code, error.message, error.details);
+  }


+function isVMErrorRecord(
+  error: unknown,
+): error is { readonly code: VMErrorCode; readonly message: string; readonly details: VMErrorDetails } {
+  return (
+    isPlainObject(error) &&
+    isVMErrorCode(error.code) &&
+    typeof error.message === "string" &&
+    isPlainObject(error.details)
+  );
+}


+function normalizeMaxSteps(value: number | undefined): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new VMError(
+      VMErrorCode.VMRuntimeError,
+      "maxSteps must be a non-negative safe integer.",
+      { valueType: typeof value },
+    );
+  }
+
+  return value;
+}


+      // Validate maxSteps before any network request
+      if (options.maxSteps !== undefined) {
+        normalizeMaxSteps(options.maxSteps);
+      }
+
      const href = normalizeEvaluateUrl(url);
      const maxBytes = normalizeMaxBytes(options.maxBytes);
      const response = await performHostNetworkRequest(


 interface VMOptions {
  capabilities?: {
-    executionRules?: { timeLimit?: number };
+    executionRules?: { timeLimit?: number; maxSteps?: number };


  // Also accepted as top-level aliases; top-level values override capabilities.*.
-  executionRules?: { timeLimit?: number };
+  executionRules?: { timeLimit?: number; maxSteps?: number };


…tion after budget exhaustion

Dayifour · 2026-05-19T20:33:49Z

Hey @darylcecile, had a chance to look at the PR? Everything is up to date on my end

darylcecile · 2026-05-20T09:36:54Z

hey @Dayifour great job on this - however the extra formatting (likely coming from a formatter extension in your IDE or from your AI tooling) makes reviewing this PR difficult. Any chance you can clean up any extra formatting so that only relevant changes are left? This will also ensure formatting conformance across the rest of the codebase. I have an in-flight PR to add formatting rules to the repo - but for now lets clean this up and then i'll stamp LGTM 🚀

…r/jsvm into feat/vm-max-steps-budget

Dayifour · 2026-05-20T16:11:18Z

Hey @darylcecile, I totally understand that extra formatting noise really does make diffs harder to follow.

I've done my best to clean it up, but I'm struggling to fully isolate where it's coming from. I'll keep investigating on my end. In the meantime, if the remaining changes are clear enough, I'm happy to wait for your formatting PR to land and align with it then. Let me know how you'd like to proceed!

feat(vm): add maxSteps execution budget

9c8d0c1

darylcecile requested a review from Copilot May 4, 2026 13:22

Copilot started reviewing on behalf of darylcecile May 4, 2026 13:22 View session

Copilot AI reviewed May 4, 2026

View reviewed changes

fix : normalize maxSteps error, validate maxSteps for URL eval, retur…

3f2763a

…n steps-exceeded error, tighten test

Dayifour requested a review from Copilot May 6, 2026 12:15

Copilot AI reviewed May 6, 2026

View reviewed changes

Dayifour requested a review from Copilot May 6, 2026 21:14

Copilot AI reviewed May 6, 2026

View reviewed changes

darylcecile requested a review from Copilot May 18, 2026 23:08

Copilot started reviewing on behalf of darylcecile May 18, 2026 23:08 View session

Copilot AI reviewed May 18, 2026

View reviewed changes

feat(vm): harden maxSteps budget handling

12d330b

Dayifour requested review from Copilot and darylcecile May 19, 2026 18:25

Copilot AI reviewed May 19, 2026

View reviewed changes

fix(vm): create fresh lexical environment when retrying module evalua…

17ffb49

…tion after budget exhaustion

Dayifour added 2 commits May 20, 2026 15:41

clean up any extra formatting

45ddbd5

Merge branch 'feat/vm-max-steps-budget' of https://github.com/Dayifou…

02b84dc

…r/jsvm into feat/vm-max-steps-budget

		expectVMFailure(
		await overrideVm.eval("let i = 0; while (true) { i += 1; }", { maxSteps: 5 }),


		Therefore time limits are guardrails, not hard CPU guarantees. A synchronous host capability can still block while it runs, and there is currently no independent memory limit, public instruction counter, scheduler, or deterministic event loop.

		`executionRules.maxSteps` and per-call `evaluate(source, { maxSteps })` provide a cooperative step budget:

Conversation

Dayifour commented May 4, 2026

Add maxSteps execution budget to VM API

Summary

Testing

Uh oh!

Dayifour commented May 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

darylcecile commented May 4, 2026

Uh oh!

Dayifour commented May 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Dayifour commented May 18, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

darylcecile May 19, 2026

Choose a reason for hiding this comment

Uh oh!

darylcecile May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Dayifour commented May 19, 2026

Uh oh!

darylcecile commented May 20, 2026

Uh oh!

Dayifour commented May 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants