opencode/packages/codemode/interpreter-support.md

CodeMode Interpreter Support

This is the checkable support matrix for CodeMode's confined JavaScript interpreter. It tracks the language and standard-library surface that programs can use today, plus concrete gaps that may be implemented later.

• [x] means the feature is implemented at the scope described here.
• [ ] means the feature is unavailable, incomplete, or intentionally divergent as described.
• A checked item does not promise complete ECMAScript edge-case parity. Known differences are listed next to the supported surface or under Known semantic gaps.
• Intentional exclusions are boundaries, not backlog.

When behavior changes, update this file and the tests in the same change. The implementation and tests remain the ultimate source of truth.

Source and execution model

• JavaScript parsed with the latest syntax accepted by Acorn, then restricted by the interpreter allowlist.
• Erasable TypeScript syntax, including type annotations, type declarations, assertions, and non-null assertions. TypeScript is transpiled first; the emitted JavaScript must still use the supported subset.
• Top-level await and return through the program's implicit async-function scope.
• Explicit return, final top-level expression as a REPL-style result, and null when no value is produced.
• JSON-like host boundaries with undefined and non-finite numbers normalized to null.
• Live Date, RegExp, Map, Set, URL, and URLSearchParams values inside CodeMode.
• Tool calls through the host-provided tools tree only.
• The global search(...) built-in: synchronous tool discovery that counts as an admitted tool call and is shadowable by program declarations like other globals.
• Cooperative timeout, an optional total tool-call limit, output bounding, and unrestricted tool-call concurrency.
• Full JavaScript or TypeScript compatibility. CodeMode is a bounded orchestration language.

Values and literals

• null, undefined, booleans, finite and non-finite numbers, and strings.
• Array literals, including holes and spread from arrays, strings, Maps, Sets, and URLSearchParams.
• Object literals with shorthand, computed string/number keys, and object spread.
• Template literals with interpolation.
• Regular-expression literals.
• NaN and Infinity globals.
• BigInt literals and values.
• Symbols.
• Tagged template literals.
• Getters and setters in object literals.

Bindings and destructuring

• const, let, and accepted var declarations.
• Object and array destructuring in declarations, parameters, assignment expressions, and for...of bindings.
• Nested patterns, defaults, elisions, and rest elements.
• Assignment to identifiers, object fields, array indexes, and writable URL fields.
• Function declarations are hoisted within their interpreted scope.
• Parameter defaults observe a temporal dead zone for later parameters.
• JavaScript-correct var function scope, hoisting, and redeclaration. Accepted var currently behaves like a lexical declaration; prefer let or const.
• Complete let/const temporal-dead-zone and declaration-hoisting semantics.
• Computed object destructuring keys such as const { [field]: value } = record.
• Object destructuring from arrays, such as const { length } = values.
• Iterable array destructuring from Map, Set, string, or URLSearchParams values.
• Dynamic property deletion with delete object[key].

Statements and control flow

• Blocks and empty statements.
• if/else and conditional expressions.
• switch, including default clauses and fallthrough.
• for, while, and do...while.
• for...of over arrays, strings, Maps, Sets, and URLSearchParams.
• for...in over own keys of plain objects, arrays, and tool references.
• Unlabeled break and continue.
• try, catch, optional catch bindings, and finally.
• throw with arbitrary values.
• Labeled statements, labeled break, and labeled continue.
• for await...of and async iteration.
• with and debugger statements.

Functions and callbacks

• Function declarations, function expressions, and arrow functions.
• Synchronous and async functions.
• Closures, recursion, default parameters, rest parameters, and destructured parameters.
• Expression and block function bodies.
• User callbacks for the supported Array, Map, Set, URLSearchParams, sort, and string-replacement APIs.
• Boolean, Number, String, parseInt, parseFloat, and URI helpers as callbacks where applicable.
• Async string replacement callbacks; replacements are evaluated sequentially.
• this, super, constructor functions, or function prototype methods such as call, apply, and bind.
• Classes and private fields.
• Generator functions and yield.
• Async predicates, reducers, and comparators with automatic awaiting. Async mapping can be joined explicitly with Promise.all, but a promise is not a meaningful predicate or sort result.
• General built-in callable references as callbacks, such as values.map(Math.abs) or records.map(JSON.stringify).

Expressions and operators

• Property access with dot or computed bracket syntax.
• Optional property access and optional calls.
• Function/tool calls and spread arguments.
• Sequence expressions (the comma operator).
• await for CodeMode promises; a plain value passes through unchanged, though every await still defers its continuation one reaction turn.
• new for Error types, Date, RegExp, Map, Set, URL, URLSearchParams, and Promise.
• Arithmetic operators: +, -, *, /, %, and **.
• Equality and ordering: ==, !=, ===, !==, <, <=, >, and >=.
• Bitwise operators: &, |, ^, ~, <<, >>, and >>>.
• Logical operators: &&, ||, ??, and !, with short-circuiting.
• Unary +, unary -, typeof, instanceof, and own-property-only in.
• Prefix and postfix ++ and --.
• Plain, arithmetic, bitwise, and logical assignment operators.
• Unary void and delete.
• Arbitrary constructors.

Promises and tools

• Tool calls start eagerly and return supervised, run-once CodeMode promises.
• Direct await, repeated awaits, and implicit resolution when a promise is returned from a function/program.
• Promise.resolve and Promise.reject.
• Promise.all, Promise.allSettled, Promise.race, and Promise.any over supported collections containing promises and plain values.
• Promise.all preserves result order and rejects on the first observed failure without cancelling siblings.
• Promise.allSettled returns plain fulfilled/rejected outcome records.
• Promise.race settles from the first result without cancelling losers at settlement time.
• Real promise values from Promise.all, Promise.allSettled, and Promise.race; separately constructed combinator batches overlap as in normal JavaScript.
• Promise chaining with .then, .catch, and .finally: handlers run deferred in attach order, returned promises are adopted, handler throws reject the derived promise, .finally preserves the original settlement unless its cleanup fails, and direct self-resolution rejects with a TypeError.
• Every await (including of plain values and already-settled promises) defers its continuation one reaction turn, so concurrent async functions interleave at await points as in JavaScript.
• Combinators settle one reaction turn after their deciding member (V8-observable ordering): reactions already attached to members run first, and an aggregate cannot beat a plain value settling in the same turn into a Promise.race. Exact microtask-count parity beyond this observable ordering is not a documented guarantee.
• All still-pending work (race losers, fail-fast Promise.all stragglers, and un-awaited calls alike) is interrupted when the program returns; rejections that settled un-awaited become Success.warnings diagnostics. A combinator abandoned inside its final settlement turn counts as pending and is interrupted without a warning.
• try/catch can handle awaited tool and promise failures.
• Promise.any: first fulfillment wins; all-rejected rejects with an AggregateError whose errors array holds the catch-normalized reasons in input order, and empty input rejects with an empty AggregateError.
• new Promise((resolve, reject) => ...): the executor runs synchronously and receives first-class resolve/reject callables that settle the promise exactly once (they may escape the executor and settle later); an executor throw rejects unless the promise already settled, resolving with a promise adopts it, and resolving with the promise itself rejects with a TypeError. Resolver callables work as .then/.catch handlers and collection callbacks but remain opaque references that cannot cross the data boundary.
• Thenable assimilation (objects with a then method are plain data, not promises).
• Async iterables, host streams, and stream consumption.

Objects and properties

• Own-field reads and writes on plain data objects.
• Computed property names and object spread.
• Object.keys, Object.values, Object.entries, Object.hasOwn, Object.assign, and Object.fromEntries.
• Object.keys over arrays and tool references.
• Object identity is preserved by in-CodeMode Object helpers.
• Blocked access to __proto__, constructor, and prototype.
• Object.is; runtime and tool-reference identity semantics need to be defined first.
• Object.groupBy.
• Object creation, descriptors, freezing/sealing, prototype APIs, and reflection APIs.
• A final policy for legal data/tool keys named __proto__, constructor, or prototype.

Arrays

• Static methods: Array.isArray, Array.of, and Array.from.
• Iteration/transformation: map, filter, flatMap, and forEach.
• Searching/tests: find, findIndex, findLast, findLastIndex, some, every, includes, indexOf, and lastIndexOf.
• Aggregation: reduce and reduceRight.
• Ordering: sort, toSorted, reverse, and toReversed.
• Access/copying: at, slice, concat, flat, with, and join.
• Mutation: push, pop, shift, unshift, splice, fill, and copyWithin.
• Materialized iteration helpers: keys, values, and entries return arrays rather than iterators.
• length, numeric indexing, index assignment, spread, and for...of.
• The mapper and thisArg forms of Array.from.
• Array.prototype.toSpliced.
• Canonical index handling: a key such as "01" must not alias index 1.
• Complete sparse-array parity. Promise combinators do consume holes as undefined members, as in JS.

Strings

• Case/normalization: toLowerCase, toUpperCase, normalize.
• Trimming: trim, trimStart, and trimEnd.
• Searching/tests: includes, startsWith, endsWith, indexOf, lastIndexOf, and search.
• Slicing/access: slice, substring, at, charAt, charCodeAt, and codePointAt.
• Construction/transformation: split, concat, repeat, padStart, padEnd, replace, and replaceAll.
• Regular-expression integration: match, materialized matchAll, replace, replaceAll, split, and search.
• localeCompare; locale and options arguments are currently ignored.
• toString, length, numeric indexing, spread, and for...of by Unicode code point.
• Static String.fromCharCode and String.fromCodePoint.
• Locale/options-aware localeCompare and locale formatting APIs.
• Exact native coercion across every string method; CodeMode often requires explicit strings/numbers.
• Native no-argument parity for match() and search().

Numbers and Math

• Coercion functions: Number, parseInt, and parseFloat.
• Number predicates/parsers: Number.isInteger, Number.isFinite, Number.isNaN, Number.isSafeInteger, Number.parseInt, and Number.parseFloat.
• Number formatting: toFixed, toPrecision, toExponential, toString, and valueOf.
• Number constants: MAX_SAFE_INTEGER, MIN_SAFE_INTEGER, MAX_VALUE, MIN_VALUE, EPSILON, NaN, POSITIVE_INFINITY, and NEGATIVE_INFINITY.
• Math constants: PI, E, LN2, LN10, LOG2E, LOG10E, SQRT2, and SQRT1_2.
• Math methods: random, max, min, abs, acos, acosh, asin, asinh, atan, atan2, atanh, floor, ceil, round, trunc, sign, sqrt, cbrt, pow, hypot, cos, cosh, sin, sinh, tan, tanh, log, log2, log10, log1p, exp, expm1, f16round, fround, clz32, and imul.
• Native zero-argument behavior for Number() and String(); they currently do not produce 0 and "".
• Safe interpreter coercion for ++ and -- rather than host Number(...) coercion.
• Reliable feature detection for unknown static members.
• Math.sumPrecise.
• Global coercing isFinite and isNaN.

JSON and console

• JSON.parse and JSON.stringify.
• Numeric/string indentation for JSON.stringify.
• Captured console.log, console.info, console.debug, console.warn, and console.error.
• Captured console.dir and console.table.
• JSON.parse reviver callbacks.
• JSON.stringify function/array replacers.
• Other console methods, timers, counters, groups, and host console access.

Date

• Date.now, Date.parse, and Date.UTC.
• new Date() from the current time, epoch milliseconds, a date string, another Date, or local components.
• getTime, valueOf, toISOString, toJSON, and deterministic ISO toString.
• Local getters: getFullYear, getMonth, getDate, getDay, getHours, getMinutes, getSeconds, and getMilliseconds.
• UTC getters: getUTCFullYear, getUTCMonth, getUTCDate, getUTCDay, getUTCHours, getUTCMinutes, getUTCSeconds, and getUTCMilliseconds.
• getTimezoneOffset, arithmetic, relational comparison, and instanceof Date.
• Date values serialize to ISO strings; invalid dates serialize to null.
• Date setters.
• toUTCString, locale methods, and other Date formatting methods.
• Exact native constructor coercion, local-time, and loose-equality semantics.
• Native RangeError branding for invalid toISOString() calls.
• Temporal and Intl date/time APIs.

Regular expressions

• Literal and new RegExp(pattern, flags) construction.
• test, exec, and toString.
• Readable source, flags, lastIndex, global, ignoreCase, multiline, sticky, unicode, and dotAll.
• Captures, named groups, match indexes, and stateful global matching.
• Integration with supported String methods, including async function replacers.
• Writable lastIndex.
• Exposed metadata for the d and v flags.
• RegExp.escape.
• Protection from pathological host-regex backtracking beyond the cooperative execution timeout.

Map and Set

• new Map() from entry arrays or another Map.
• Map get, set, has, delete, clear, size, and forEach.
• new Set() from arrays, strings, or another Set.
• Set add, has, delete, clear, size, and forEach.
• Materialized keys, values, and entries arrays for Map and Set.
• Spread, for...of, Array.from, and Object.fromEntries integration.
• Map and Set values serialize to {} at host/JSON boundaries.
• Set composition methods such as union, intersection, difference, and relation predicates.
• WeakMap and WeakSet.
• Native iterator objects and custom iterators.

URL and URI helpers

• encodeURI, encodeURIComponent, decodeURI, and decodeURIComponent.
• new URL(input, base), URL.canParse, and URL.parse.
• URL toString, toJSON, and linked searchParams.
• Readable URL fields: href, origin, protocol, username, password, host, hostname, port, pathname, search, and hash.
• Writable URL fields except origin.
• new URLSearchParams() from query strings, data objects, pairs, Maps, and URLSearchParams.
• URLSearchParams append, delete, get, getAll, has, set, sort, forEach, keys, values, entries, toString, and size.
• URL values serialize to their href; URLSearchParams serialize to {}.

Errors and diagnostics

• Error, TypeError, RangeError, SyntaxError, ReferenceError, EvalError, and URIError, callable with or without new.
• AggregateError with the (errors, message?) signature and an own errors array, constructed directly or by an all-rejected Promise.any.
• Error name/message, error inheritance through instanceof, and plain-data serialization.
• instanceof for Date, RegExp, Map, Set, URL, URLSearchParams, Array, Object, Promise, and Error types.
• Catchable interpreter failures and awaited tool failures.
• Source locations on unsupported-syntax diagnostics when available.
• Sanitized model-visible diagnostics and explicit safe ToolError messages.
• Distinct public categories for user throws, tool refusal, tool internal failure, invalid returned data, compile failures, and genuine interpreter defects.
• Preservation of detailed recoverable failure categories inside catch and Promise.allSettled.

Known semantic gaps

These are actionable implementation items. Check them off only when behavior and direct tests land.

• Return real promises from Promise.all, Promise.allSettled, and Promise.race.
• Guarantee every advertised tool path is executable, including dotted and blocked path segments.
• Define safe outbound handling for non-finite numbers and undefined so invalid values cannot silently become null in render-only or OpenAPI tool calls.
• Make regular-expression execution genuinely timeout-safe, or narrow the timeout guarantee explicitly.
• Complete lexical declaration and destructuring semantics listed above.
• Make callback acceptance and async callback behavior consistent across built-ins.
• Reject every unsupported callback argument explicitly rather than silently ignoring it.
• Resolve the built-in correctness gaps listed in the Array, String, Number, Date, and RegExp sections.
• Make tool search tokenization Unicode-aware.
• Design explicit tagged representations and size limits before adding binary values or streams.

Intentional exclusions

These constraints preserve CodeMode's confinement and host-neutral scope. They are not TODO items.

• Ambient filesystem, process, environment, credential, network, or application access.
• fetch, timers, crypto, or other host globals unless a future host explicitly supplies a bounded capability.
• Static imports, dynamic imports, modules, npm packages, and module loading.
• eval, Function(...), arbitrary host execution, and prototype mutation.
• Generic permission prompts, authorization policy, persistence, replay, or exactly-once side effects.
• Arbitrary method dispatch outside the documented allowlists.
• Automatic parsing of text tool results as JSON.
• Full browser, Node.js, Bun, or ECMAScript runtime compatibility.