VM budgets: fuel, memory and boundary limits

AJS runs untrusted code, often code a model wrote, inside your JavaScript process. Its budgets are therefore security promises, not tuning knobs: a run may use only the work, memory and boundary traffic you allowed it, and when it reaches a limit it fails as a value instead of taking the host down.

Two words recur. The guest is the AJS program and every value it holds: its variables, its arguments, what its atoms return to it. The host is your JavaScript process: the code that calls vm.run, the capabilities it passes in, and the atoms it registers.

What to read:

• Embedding the VM: The budgets, When a budget refuses and Why not ask the runtime.
• Writing agents: Refused, not charged and Exact operand types.
• Writing custom atoms: What this means for your atoms.
• Changing the VM: The doors and everything after it, which lists every place a guest program can allocate and how each is checked.

How to call vm.run and pass capabilities is covered in Hosting the VM; this chapter covers what the budget options mean.

The budgets

Every option is set per run, in the third argument to vm.run.

maxSourceBytes belongs to the parser, not the run. The deprecated vm.run(source), Eval and SafeFunction apply it at 8KB by default; transpile applies it only when you pass it (transpile(source, { maxSourceBytes })), so set it wherever the source comes from someone else. See Safe Eval.

What fuel costs:

• an atom call: its cost, 1 for most atoms;
• an expression node (an operator, a name, a member read): 0.01;
• an allocation: 1 per 20,000 bytes;
• the run's arguments: 1 per 8,000 bytes. Copying them in visits every value, and that walk is charged per node at the rate binding the same data costs, which works out higher than a flat allocation.

For sizing: one pass of a small while loop that updates two variables costs about half a unit, so the default 1,000 runs about 2,000 such iterations. Measure your own agents with fuelUsed (below) and set the budget with headroom.

Fuel and the heap ceiling answer different questions. Fuel bounds how much a program does over its lifetime; it says nothing about how much it holds at any moment. A run that builds a 4MB string pays about 200 fuel for it, well inside a generous budget, and could still be more memory than you want one agent to hold. So the two are separate limits:

import { transpile } from 'tjs-lang/lang'
import { AgentVM } from 'tjs-lang/vm-ast'

const { ast } = transpile(`
  function big({ n = 1000 }) {
    const s = 'x'.repeat(n)
    return { len: s.length }
  }
`)
const vm = new AgentVM()

const run = await vm.run(ast, { n: 2_000_000 }, {
  fuel: 100_000,
  maxHeapBytes: 1024 * 1024, // 1MB
})
run.error.message
// 'Heap limit exceeded: guest state holds ~4MB, limit 1MB. Fuel bounds total work;
//  this bounds peak memory. Raise it with the maxHeapBytes run option if the workload
//  genuinely needs it.'
run.error.op // 'expr.repeat'

The refusal happens before the string exists. repeat computes the size of its result from its arguments (two million UTF-16 characters, about 4MB) and is refused at the gate: the check, made before anything is built, that charges fuel for that size and tests it against the heap ceiling. The figure in the message is what guest state would hold if the allocation went ahead: current holdings plus the request.

Nothing is thrown into your code. vm.run resolves to { result, error, fuelUsed, … }. On success error is undefined and result is what the agent returned. On failure both are the error value, { $error: true, message, op }, where op names the operation that was refused, and fuelUsed is what the run spent.

Arguments are checked before the run begins. A five-million-character string argument, against the default argsMaxBytes, returns Capability boundary rejected the run arguments: the value exceeds the 4194304-byte membrane budget. The membrane is the copier every value crossing between host and guest goes through, and the limit in this message is argsMaxBytes: raise that, not membraneMaxBytes. A 100,000-character argument with fuel: 10 returns Out of Fuel, because the run cannot pay to copy it.

When a budget refuses

Some refusals are a value the agent can catch with try/catch; others end the run, even inside a try. In AJS a caught error is a string (its message, capped), not an Error object, which is why the examples below assign err directly.

The first example above ends the run only because nothing caught the refusal. The language guide explains the rule behind this split under "Catchable, and run-ending".

Three promises

The budgets rest on three invariants. Tests and source comments refer to them as I1, I2 and I3.

I1. Nothing allocates before it is charged. An operation whose allocation depends on runtime data computes an upper bound from its inputs first, charges fuel for it, and passes the heap gate. Only then does it allocate. A limit checked afterwards would be too late: 'x'.repeat(5e8) is one synchronous native call that asks for 1GB, and no timeout or memory reading can interrupt it once it starts.

The one bounded exception is a value crossing the capability boundary. The membrane builds its copy as it reads, so that what it checked is exactly what it forwards, which means the copy's size is known only once it exists. Instead the copy is built inside a budget fixed in advance, and charged when complete:

• Inbound (an IO atom's return coming into the VM): the budget is membraneMaxBytes.
• Outbound (an atom's input going out to a capability): membraneMaxBytes, or what the remaining fuel can pay, whichever is smaller.

So a crossing can allocate up to membraneMaxBytes before it is charged, and no more. Run arguments are the same, capped by argsMaxBytes and the fuel.

I2. Every byte that outlives its step is charged where it becomes reachable. A step is one node of the program the VM executes: a statement, an atom call. A byte becomes reachable at a bind (const x = …), an in-place insertion (push, fill, adding to a Set), a memoize store, and when an atom adds to a container it holds (the results array of the map atom, which runs a body once per item).

I3. Everything that holds guest values while guest code runs is a heap root. To measure memory, the VM starts from a known list of holders, the roots, and follows every reference from them; anything held elsewhere is invisible to it. The roots are scope variables, memo caches, run arguments, and the containers loop atoms keep while they run their bodies. A holder that is not a root is memory the ceiling cannot see.

Refused, not charged: implicit coercion

JavaScript converts an object to a string or a number wherever it wants a primitive: arr < 5, arr * 2, obj[arr], 'abc'.includes(arr), Math.max(arr), a sort's default comparator. For an array that conversion is its whole string form, built recursively, and each of those sites was an allocation the budget did not see. AJS refuses them instead of estimating them. No agent program means them, and refusing keeps the list of places that allocate short enough to check.

function tagLine({ tags = ['red', 'green'] }) {
  let refused = ''
  try {
    const attempt = 'tags: ' + tags // refused: tags is an array
  } catch (err) {
    refused = err
  }
  return { refused, line: 'tags: ' + tags.join(', ') }
}

refused is '+' needs a string, number, boolean or null, not an array — convert it explicitly (e.g. arr.join(','), JSON.stringify(obj)), and line is 'tags: red, green'. This error is catchable; uncaught, it ends the run with that message.

The rules:

• Operators (+ - * / % ** < > <= >=, unary + and -) take strings, numbers, booleans and null. Equality (==, ===) never converts in AJS, so it may compare objects, by identity: arr == arr is true and arr == [1, 2] is false.
• Computed keys (obj[k]) are primitives.
• Method arguments are primitives, except where the method uses an argument as a value: it stores it, compares it by identity, or copies it. arr.includes(obj), arr.concat(other) and Object.keys(obj) take objects; 's'.includes(arr) and Math.max(arr) do not. The one object a string method accepts is a regex, as a search pattern.
• A sort with no comparator compares string forms, so its elements must be primitives: [3, 1, 2].sort() works, [[3], [1]].sort() is refused.

Say what you mean instead: arr.join(','), JSON.stringify(obj), n.toString() or `${n}` for a number. (String(n) as a function call is not available in AJS; the String namespace, String.fromCharCode, is.)

Exact operand types

'x'.repeat('1e8'): as a string, the count '1e8' is three characters long, and repeat reads it as one hundred million. A budget computed from one reading of an operand, while the method reads it another way, is no budget. So every method declares, for each receiver kind (the type of the value before the dot: string, array, object, number, Set, Date), the exact type of each argument, and its bound is computed from those same checked values.

function stars({ count = 3 }) {
  const ok = '*'.repeat(count)
  let asText = ''
  let extra = ''
  try {
    const bad = '*'.repeat(count.toString())
  } catch (err) {
    asText = err
  }
  try {
    const bad = 'stars'.slice(0, 1, 2)
  } catch (err) {
    extra = err
  }
  return { ok, asText, extra }
}

Returns { ok: '***', asText: "repeat()'s argument 1 must be a number", extra: 'slice() takes at most 2 argument(s)' }.

• A count is a number. 'x'.repeat('3') is refused, not converted.
• Arguments past the method's signature are refused.
• A method of one kind is not callable on another: ['x'].toUpperCase() is 'toUpperCase' is not a function.
• A method with no entry in the VM's table is not callable at all (see The method table below).

What the heap ceiling counts

The VM keeps a running estimate of live memory and checks it at every gated allocation.

• Bound values. Binds, insertions and memo stores add to the estimate. Nothing subtracts from it, so it is never below what is actually held.
• In-flight values. Each executing step has an allocation frame for the intermediates it builds, which no variable holds yet. The frame is released when the step ends, or cleared when the step binds its result. The result is then counted as bound, and counting it in flight as well would double it, refusing a value just over half the ceiling.
• Reconcile. When the estimate plus in-flight bytes crosses the ceiling, the VM walks every root once, counting shared objects once, and replaces the estimate with that measurement. The run fails only if the measurement, plus in-flight bytes and the request, is over the ceiling, and the error reports that total. The walk is charged as fuel, so a program that hovers near the ceiling and keeps reallocating fails by fuel rather than hanging.

What it over-counts, on purpose (it fails closed):

• A long string held under several names counts once per name. A shared string cannot be told apart from an equal copy, and counting by value would let distinct equal strings count once.
• A concatenation counts its result in full, although JavaScript engines such as V8 build a rope (a lazy concatenation that points at its parts instead of copying them). The engine may flatten the rope later, copying it while the parts are still held, and that copy happens outside any gate. So s = s.slice(1) + 'a' can peak at about twice the string in real memory, which is why the VM counts the full result.
• Printing counts a value as a tree: see tree bounds. A structure that shares sub-arrays is small in memory and enormous when joined, and the join's bound is the printed size.

What it does not count: garbage. A value no root reaches and no running step holds belongs to the JavaScript collector. The promise is about peak reachable memory.

What this means for your atoms

Atoms you define with defineAtom run host code, outside the guarantees above unless you keep them. How to define and register atoms is in Capabilities and Custom Atoms; these are the budget rules.

An IO atom (the default, effects: 'io') needs nothing beyond a declared input schema. Its input is copied out through the membrane and validated against that schema; its return is copied in, capped by membraneMaxBytes, then charged at the bind like any other value. Return JSON data plus Date, nothing else. defineAtom refuses an IO atom with no input schema (use s.object({}) for none), and refuses pattern or patternProperties in it, because those would run the host's regex engine on guest strings.

An oversized return is caused by the outside world, not by a bug in the agent, so the agent can catch it. (s is from tosijs-schema, which tjs-lang/schema re-exports. The atoms option lets the transpiler check calls to your atoms: a misspelled input name fails at transpile time instead of in the run.)

import { transpile } from 'tjs-lang/lang'
import { AgentVM, defineAtom } from 'tjs-lang/vm-ast'
import { s } from 'tosijs-schema'

const fetchRows = defineAtom(
  'fetchRows',
  s.object({ count: s.number }),
  s.any,
  async ({ count }, ctx) => ctx.capabilities.rows.list(count)
)
const vm = new AgentVM({ fetchRows })
const rows = {
  list: async (n) => Array.from({ length: n }, (_, i) => ({ id: i, name: `row ${i}` })),
}

const { ast } = transpile(
  `function getRows({ count = 10 }) {
    try {
      const rows = fetchRows({ count })
      return { n: rows.length }
    } catch (err) {
      return { refused: err }
    }
  }`,
  { atoms: vm.atoms }
)
const run = await vm.run(ast, { count: 100_000 }, {
  fuel: 100_000,
  capabilities: { rows },
  membraneMaxBytes: 1024 * 1024,
})
run.result.refused
// "Capability boundary rejected the return of 'fetchRows': the value exceeds the
//  1048576-byte membrane budget"

A pure atom that builds a value from its inputs must charge first. With effects: 'pure' there is no membrane, so your atom's allocation is unguarded, like repeat's, until it charges. Compute an upper bound in bytes from the inputs (two bytes per string character) and pass it to allocate before you build anything. allocate charges fuel, checks the heap ceiling, and throws the run's error if either refuses:

import { AgentVM, allocate, defineAtom } from 'tjs-lang/vm-ast'
import { s } from 'tosijs-schema'

const repeatText = defineAtom(
  'repeatText',
  s.object({ text: s.string, times: s.number }),
  s.string,
  async ({ text, times }, ctx) => {
    allocate(ctx, text.length * times * 2, 'repeatText') // before, not after
    return text.repeat(times)
  },
  { effects: 'pure' }
)

Called as repeatText({ text: 'ab', times: 1e8 }) under maxHeapBytes: 1024 * 1024, the run fails with Heap limit exceeded: guest state holds ~381MB, limit 1MB. … and the string is never built. Allocate the full size of what you build. allocate pays for building the value (I1); when the agent binds the result, the bind pays for keeping it (I2). Those are two different costs, and every value pays both.

An atom that runs guest steps must not hold guest values where the heap walk cannot see them. An atom that takes steps as input (a body to run, like map's) runs them through createChildScope(ctx) and seq. Anything it keeps in a JavaScript local while those steps run is invisible to the measurement (I3). Keep it in a variable of the guest scope, or accumulate nothing until the steps finish.

Why not ask the runtime how much memory is in use?

process.memoryUsage() and its browser cousins cannot do this job:

• It is after the fact. 'x'.repeat(5e8) is one synchronous native call. There is no moment between asking for 1GB and having it when a reading could intervene. Only a bound computed from the inputs, before the call, can refuse it (I1).
• It is the whole process, not this run. A server running many agents, or a page hosting the VM, has one heap. A per-run budget cannot be read from it.
• It counts garbage. Dead objects stay in the figure until the collector runs, and forcing a collection stops the world.
• It is not portable. AJS runs in Node, Bun, Deno, workers and browsers, and browsers expose almost nothing (performance.memory is non-standard; measureUserAgentSpecificMemory is asynchronous, slow, and needs cross-origin isolation).

The engine's own limit is the backstop beneath these budgets. A host running untrusted code at scale should also give each run an isolation boundary with a hard limit, such as a Node Worker with resourceLimits: { maxOldGenerationSizeMb }. The engine enforces that limit, so it holds even where an estimate is wrong, but it cannot fail gracefully: the worker dies. maxHeapBytes fails the run, with an error naming the operation, and leaves the host intact. Use both. The planned native VM merges the two, because a wasm instance's linear memory is a hard, synchronous, per-run cap.

The doors

Every place a guest program can allocate, and what guards it. A v2 AST is what the transpiler writes today; v1 ASTs come from older code and the fluent builder (see Atoms: fewer, thinner).

The method table

Every method guest code may call, on every receiver kind (string, array, object, number, the guest Set and Date, and the namespaces Array, Object, JSON, String, Math, Number), declares an allocation class:

• none: allocates nothing proportional to data (includes, indexOf, Math.max, and in-place mutators, whose growth I2 charges).
• const: the result is bounded by a constant (toFixed, a number's toString(2)).
• shallow: the result is at most a constant times the shallow size of the receiver and arguments (slice, concat, trim, toUpperCase, split, Object.keys). Where arguments select a range they are used: slice(0, 10) of a long string is charged ten characters.
• tree: printers and flatteners (join, JSON.stringify, flat, an array's toString, Schema-from-example) are bounded by the value's size as a tree. Every path to a node counts, because printing visits every path.
• bound(fn): an explicit bound for amplifiers and products (repeat, padStart, padEnd, join, replace, replaceAll, Array.from, Array.of, String.fromCharCode).

join is in both of the last two because its result is the printed tree plus one separator per element, and a long separator can be the larger part.

A guest Set is held as an array of its items (the VM keeps its membership index). To an agent it behaves as a Set for has, add and size, and Array.isArray(set) is true and JSON.stringify(set) prints the items as an array.

Bounds dispatch on the receiver kind wherever one name means different things on different kinds.

The tree class is why this program is refused, although its data is a few hundred bytes:

function wide({ depth = 6 }) {
  let row = ['abcdefghij', 'abcdefghij', 'abcdefghij', 'abcdefghij']
  let i = 0
  while (i < depth) {
    row = [row, row, row, row, row, row, row, row, row, row]
    i = i + 1
  }
  try {
    return { depth, joined: row.join(',').length }
  } catch (err) {
    return { depth, refused: err }
  }
}

Each level holds ten references to the level below, so memory grows by ten pointers per level while the printed form grows tenfold. At depth 6 join would print 44 million characters (10⁶ copies of the four-string row, 11 characters each with its comma; about 88MB), and the run returns refused: 'Heap limit exceeded: …' under the default 64MB ceiling. At depth 2 it returns joined: 4399. Getting to the refusal costs about 3,000 fuel, which the doc site provides; under vm.run's default of 1,000 the run ends with Out of Fuel first, which is the other budget doing its job.

A method with no entry is not callable. The list used to be "every method on these prototypes", which admitted amplifiers by default. Now a method is callable only once its bound is declared.

Checked by probing. vm-budgets.test.ts calls every entry on receivers and arguments at several scales, including the amplifying ones (large counts, long separators, long replacements, nested arrays), and fails if any result exceeds its declared bound. A table checked only against itself proves nothing.

The VM's own regex engine

Guest regexes run on the VM's own engine, never the host's. What that means for an agent:

• It supports classes, ., anchors, \b, groups (capturing, non-capturing, named), alternation and every quantifier, greedy and lazy, with flags gimsuy. It refuses backreferences, lookaround, \p{…} and the d and v flags.
• A match cannot hang. Shapes that hang a backtracking engine, exponential ((a+)+$) and polynomial (a*a*c), are ordinary work, charged as fuel.
• replace, replaceAll, match, search and split are implemented by the VM over it and charge exactly what they build.
• Regex is deprecated in AJS in favour of Pattern.

The engine (src/vm/regex.ts) is a Pike VM: instead of trying one path and backtracking, it advances every possible match in lockstep and merges duplicates at each position, so a match takes time proportional to input × pattern whatever the pattern. A test runs it and native RegExp on the same inputs and requires the same answers.

A schema's pattern keyword would run on the host's engine when the schema validates, so a guest-supplied one is refused.

Other closed doors

• Guest values are data. A guest value is JSON-shaped: a Set is an array of its items (its membership index is held by the VM), a Date or regex a frozen plain object of its fields. No guest value is a host function or carries a method; method calls dispatch on the receiver's kind. This is checked where values enter guest state, inside the same walk that charges binds, and an insertion is checked before it happens, so a refused value is never left inside a structure.
• A declared inputSchema is validated before the run, on a capped budget. The transpiler derives an agent's inputSchema from its parameter examples. Validation runs before the run's timer exists, so it is capped at 1M argument paths and 1e8 (schema nodes × paths) steps, about 0.6s, whatever the fuel. Past either, the run is refused with Arguments too large to validate against the inputSchema …: validate in the host, or pass smaller arguments.
• Guest schemas are data in a closed dialect. Schema.* returns plain JSON schemas, never a library builder whose methods are host closures, and a member read never returns a host function. A guest schema may use only admitted keywords, each with exactly its value type, and is size-capped. Validation is charged as schema nodes × data nodes before it runs.
• Only trusted predicate source runs. A $predicate is a JSON-Schema keyword whose value is predicate source, a check written as code. A predicate compiles to native JavaScript, which no syntactic check makes safe against hostile code, so the $predicate paths run only sources the host registered with trustPredicate.

Atoms: fewer, thinner

Data atoms (split, join, push, keys, pick, omit, merge, template, len, …) used to duplicate what the expression evaluator does with method calls, and the transpiler emitted one or the other depending on syntax: arr.push(x) as a statement was an atom, inside an expression a method call. Two implementations meant two gates to get right, and the atom form escaped maxHeapBytes.

• v2 ASTs (what the transpiler writes) emit method calls. One implementation, one gate, and JavaScript's semantics.
• v1 ASTs (built with the fluent Agent builder, or saved by older versions and stored as procedures) keep their op: 'split' steps, as thin wrappers over the same gated primitives.
• Atoms remain for what only an atom can do: control flow, scopes, IO and capabilities, and VM services: memoize (keep a result in memory), cache (keep a result in the store, with a time limit), agentRun (run another agent) and runCode (run AJS source through the host's code capability).

So costOverrides and quotas keyed on a data op such as split apply to v1 ASTs only. In v2 code a method call is an expression and costs what the evaluator charges.

Checked by

This section and the next are for VM contributors.

• src/vm/vm-budgets.test.ts: the method-table probe; every guest-callable method has an entry; the I1 rows (each must fail before it allocates, under a tiny fuel or heap budget).
• src/vm/rc2-rereview-4.test.ts: the atom ratchet. Every atom that runs nested steps is listed with what it holds.
• src/vm/heap-reconcile.test.ts, src/vm/heap-roots.test.ts, src/vm/heap-mutation.test.ts: I2, I3 and the list of mutating methods, through transpile() output.
• src/vm/cost-invariant.test.ts: every step charges fuel of at least a constant times its work.
• src/vm/egress-doors.test.ts, src/vm/io-atom-schema.test.ts, src/vm/membrane-halt.test.ts: every IO atom crosses the outbound membrane, its schema is admitted at definition, and an outbound refusal ends the run.
• src/vm/guest-values.test.ts, src/vm/guest-fuzz.test.ts: every known route by which a host function could become a guest value, and generated programs checked against the invariants (vm.run never throws, no function reaches a result or a capability, wall time tracks fuel).