diff --git a/packages/codemode/interpreter-support.md b/packages/codemode/interpreter-support.md index a950eaa72fd..e780547fcd0 100644 --- a/packages/codemode/interpreter-support.md +++ b/packages/codemode/interpreter-support.md @@ -4,10 +4,9 @@ This is the checkable support matrix for CodeMode's confined JavaScript interpre 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](#known-semantic-gaps). -- [Intentional exclusions](#intentional-exclusions) are boundaries, not backlog. +- `[ ]` means a concrete compatibility gap remains. +- Checked items do not promise complete ECMAScript edge-case parity; known differences are stated explicitly. +- Intentional boundaries are not listed as compatibility work. When behavior changes, update this file and the tests in the same change. The implementation and tests remain the ultimate source of truth. @@ -19,42 +18,45 @@ ultimate source of truth. TypeScript is transpiled first; the emitted JavaScript must still use the supported subset. - [x] Top-level `await` and `return` through the program's implicit async-function scope. - [x] Explicit `return`, final top-level expression as a REPL-style result, and `null` when no value is produced. -- [x] JSON-like host boundaries with `undefined` and non-finite numbers normalized to `null`. +- [x] Program results use JSON-like boundaries, with `undefined` and non-finite numbers normalized to `null`. Tool + arguments remain subject to their schema and the outbound-handling gap listed below. - [x] Live Date, RegExp, Map, Set, URL, and URLSearchParams values inside CodeMode. - [x] Tool calls through the host-provided `tools` tree only. - [x] The global `search(...)` built-in: synchronous tool discovery that counts as an admitted tool call and is shadowable by program declarations like other globals. - [x] 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 - [x] `null`, `undefined`, booleans, finite and non-finite numbers, and strings. - [x] Array literals, including holes and spread from arrays, strings, Maps, Sets, and URLSearchParams. -- [x] Object literals with shorthand, computed string/number keys, and object spread. +- [x] Object literals with shorthand, computed string/number keys, and spread from plain data objects; `null` and + `undefined` are no-ops, while arrays are rejected. - [x] Template literals with interpolation. - [x] Regular-expression literals. - [x] `NaN` and `Infinity` globals. -- [ ] BigInt literals and values. -- [ ] Symbols. -- [ ] Tagged template literals. -- [ ] Getters and setters in object literals. +- [ ] BigInt literals and in-interpreter BigInt arithmetic; BigInt remains invalid at JSON-like host boundaries. +- [ ] Symbol primitive values and symbol-keyed properties. +- [ ] Tagged-template calls. +- [ ] Getter and setter definitions in object literals. ## Bindings and destructuring - [x] `const`, `let`, and accepted `var` declarations. - [x] Object and array destructuring in declarations, parameters, assignment expressions, and `for...of` bindings. - [x] Nested patterns, defaults, elisions, and rest elements. -- [x] Assignment to identifiers, object fields, array indexes, and writable URL fields. -- [x] Function declarations are hoisted within their interpreted scope. +- [x] Assignment to identifiers, unblocked plain-object fields, non-negative integer array indexes, and writable URL + fields. +- [x] Direct function declarations are hoisted in program and block statement lists. - [x] 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. +- [ ] JavaScript-correct function scoping, hoisting, and redeclaration for accepted `var` declarations. +- [ ] Predeclare `let` and `const` bindings in every lexical scope, including program/block bodies, switch bodies, and + loop headers, so reads before initialization and self- or cross-referential initializers observe the JavaScript + temporal dead zone. +- [ ] Hoist function declarations accepted directly in switch cases. - [ ] 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]`. +- [ ] Array destructuring from supported non-array iterables: strings, Maps, Sets, and URLSearchParams. ## Statements and control flow @@ -69,7 +71,6 @@ ultimate source of truth. - [x] `throw` with arbitrary values. - [ ] Labeled statements, labeled `break`, and labeled `continue`. - [ ] `for await...of` and async iteration. -- [ ] `with` and `debugger` statements. ## Functions and callbacks @@ -90,15 +91,15 @@ ultimate source of truth. like JS. - [x] Tool references and detached `Promise` statics are rejected as callbacks with a hint to wrap them in an arrow function. -- [x] Async string replacement callbacks; replacements are evaluated sequentially. +- [ ] Stop automatically awaiting promise-returning string replacers; match JavaScript's synchronous callback-result + coercion. - [x] The optional `thisArg` of iteration methods is accepted and ignored: CodeMode functions have no `this`, so ignoring it matches JS arrow-function semantics exactly. -- [ ] `this`, `super`, user-defined constructor functions, or function prototype methods such as `call`, `apply`, - and `bind`. +- [ ] `this` in non-arrow CodeMode functions and callbacks. +- [ ] User-defined constructor calls. +- [ ] `Function.prototype.call`, `apply`, and `bind` for CodeMode functions. - [ ] 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. ## Expressions and operators @@ -108,7 +109,7 @@ ultimate source of truth. - [x] Sequence expressions (the comma operator). - [x] `await` for CodeMode promises; a plain value passes through unchanged, though every `await` still defers its continuation one reaction turn. -- [x] `new` for Error types, Date, RegExp, Map, Set, URL, URLSearchParams, and Promise. +- [x] `new` for Array, Object, Error types, Date, RegExp, Map, Set, URL, URLSearchParams, and Promise. - [x] Arithmetic operators: `+`, `-`, `*`, `/`, `%`, and `**`. - [x] Equality and ordering: `==`, `!=`, `===`, `!==`, `<`, `<=`, `>`, and `>=`. - [x] Bitwise operators: `&`, `|`, `^`, `~`, `<<`, `>>`, and `>>>`. @@ -116,8 +117,7 @@ ultimate source of truth. - [x] Unary `+`, unary `-`, `typeof`, `instanceof`, and own-property-only `in`. - [x] Prefix and postfix `++` and `--`. - [x] Plain, arithmetic, bitwise, and logical assignment operators. -- [ ] Unary `void` and `delete`. -- [ ] Arbitrary constructors. +- [ ] Unary `void` and property deletion, including computed forms such as `delete object[key]`. ## Promises and tools @@ -152,8 +152,13 @@ ultimate source of truth. promise itself rejects with a `TypeError`. Resolver callables work anywhere callbacks are accepted, including `.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. +- [ ] Thenable assimilation; objects with a callable `then` field remain plain data. +- [x] Dotted tool names are canonicalized into namespace paths; a path can be both callable and a namespace, and the + last definition supplied for a canonical path wins. +- [x] Tool path segments may be named `constructor`, `prototype`, or `__proto__` because paths use inert Map keys. +- [ ] Reject `undefined` and non-finite numbers in outbound tool arguments before render-only and OpenAPI tools run; + retain null normalization for program results and JSON serialization. +- [ ] Tokenize and case-fold non-ASCII tool paths, descriptions, and queries for tool search. ## Objects and properties @@ -164,19 +169,17 @@ ultimate source of truth. - [x] `Object.keys`, `Object.values`, `Object.entries`, `Object.hasOwn`, `Object.assign`, and `Object.fromEntries`. - [x] `Object.keys` over arrays and tool references. - [x] Object identity is preserved by in-CodeMode Object helpers. -- [x] Blocked access to `__proto__`, `constructor`, and `prototype`. -- [ ] `Object.is`; runtime and tool-reference identity semantics need to be defined first. +- [x] Prototype traversal and mutation through `__proto__`, `constructor`, and `prototype` are blocked. +- [ ] Legal own data fields named `__proto__`, `constructor`, or `prototype` are rejected at JSON/tool boundaries and + cannot be created, read, or written in CodeMode; tool path segments with those names remain supported. +- [ ] `Object.is` for supported data values. - [ ] `Object.groupBy`. -- [ ] Object creation, descriptors, freezing/sealing, prototype APIs, and reflection APIs. -- [ ] A final policy for legal data keys named `__proto__`, `constructor`, or `prototype` (tool path segments - already allow them; see known semantic gaps). ## Arrays -- [x] The `Array` constructor with or without `new`: `Array(a, b)` collects arguments, `Array(n)` creates a - sparse array of that length (invalid lengths throw a `RangeError`). Holes behave like JS in iteration, - spread, join, and JSON; `sort` densifies holes into trailing `undefined`, and results returned to the - host normalize holes to `null`. +- [x] The `Array` constructor with or without `new`: `Array(a, b)` collects arguments and `Array(n)` creates a sparse + array of that length; invalid lengths throw `RangeError`. Iteration, spread, join, and JSON handle holes like + JavaScript, and host results normalize holes to `null`. - [x] Static methods: `Array.isArray`, `Array.of`, and `Array.from`, including the `Array.from` mapper form with `(value, index)` arguments. - [x] Iteration/transformation: `map`, `filter`, `flatMap`, and `forEach`. @@ -190,8 +193,10 @@ ultimate source of truth. - [x] `length`, numeric indexing, index assignment, spread, and `for...of`. - [x] The `thisArg` argument of `Array.from` is accepted and ignored, like JS arrows. - [ ] `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. +- [ ] Canonical array/string index parsing: a key such as `"01"` must remain an ordinary property key rather than + aliasing index `1`. +- [ ] `Array.prototype.sort` and `toSorted` must preserve trailing holes; they currently turn holes into own + `undefined` elements. ## Strings @@ -204,8 +209,8 @@ ultimate source of truth. - [x] `localeCompare`; locale and options arguments are currently ignored. - [x] `toString`, `length`, numeric indexing, spread, and `for...of` by Unicode code point. - [x] 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 argument coercion for supported String methods; for example, `includes(1)` and `slice("1")` currently + reject instead of coercing. - [ ] Native no-argument parity for `match()` and `search()`. ## Numbers and Math @@ -221,20 +226,21 @@ ultimate source of truth. `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. +- [ ] `++` and `--` must use CodeMode numeric coercion and reject opaque runtime references; they currently call host + `Number(...)` directly. +- [ ] Unknown static members must read as `undefined` for feature detection; some currently appear callable or throw + during property access. - [ ] `Math.sumPrecise`. - [ ] Global coercing `isFinite` and `isNaN`. ## JSON and console -- [x] `JSON.parse` and `JSON.stringify`. +- [x] `JSON.parse` and `JSON.stringify` for supported data objects; the blocked data-key gap listed above still applies. - [x] Numeric/string indentation for `JSON.stringify`. - [x] Captured `console.log`, `console.info`, `console.debug`, `console.warn`, and `console.error`. - [x] 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 @@ -250,22 +256,22 @@ ultimate source of truth. - [x] `getTimezoneOffset`, arithmetic, relational comparison, and `instanceof Date`. - [x] 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. +- [ ] `Date.prototype.toUTCString` and its `toGMTString` alias. +- [ ] Native one-argument Date coercion; unsupported boolean/object inputs currently become invalid dates instead of + being coerced. +- [ ] Native Date loose-equality and default primitive-coercion semantics. - [ ] Native `RangeError` branding for invalid `toISOString()` calls. -- [ ] Temporal and Intl date/time APIs. ## Regular expressions - [x] Literal and `RegExp(pattern, flags)` construction, with or without `new`. - [x] `test`, `exec`, and `toString`. - [x] Readable `source`, `flags`, `lastIndex`, `global`, `ignoreCase`, `multiline`, `sticky`, `unicode`, and `dotAll`. -- [x] Captures, named groups, match indexes, and stateful global matching. -- [x] Integration with supported String methods, including async function replacers. +- [x] Captures, safe named groups (blocked member names are omitted), match `.index`, and stateful global matching. +- [x] Integration with supported String methods, including function replacers. - [ ] Writable `lastIndex`. -- [ ] Exposed metadata for the `d` and `v` flags. +- [ ] `hasIndices`, match `indices`, and `unicodeSets` metadata for the `d` and `v` flags. - [ ] `RegExp.escape`. -- [ ] Protection from pathological host-regex backtracking beyond the cooperative execution timeout. ## Map and Set @@ -276,9 +282,8 @@ ultimate source of truth. - [x] Materialized `keys`, `values`, and `entries` arrays for Map and Set. - [x] Spread, `for...of`, `Array.from`, and `Object.fromEntries` integration. - [x] 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. +- [ ] Set composition and relation methods: `union`, `intersection`, `difference`, `symmetricDifference`, `isSubsetOf`, + `isSupersetOf`, and `isDisjointFrom`. ## URL and URI helpers @@ -301,48 +306,12 @@ ultimate source of truth. an all-rejected `Promise.any`. - [x] Error `name`/`message`, error inheritance through `instanceof`, and plain-data serialization. - [x] `instanceof` for Date, RegExp, Map, Set, URL, URLSearchParams, Array, Object, Promise, and Error types. -- [x] Catchable interpreter failures and awaited tool failures. -- [x] Source locations on unsupported-syntax diagnostics when available. +- [x] Catchable user throws, runtime failures raised during interpreted evaluation, awaited tool failures, and awaited + tool-call-limit failures; parse/compile failures, cooperative timeout, and output bounding remain outside program + `catch`. +- [x] Source locations on unsupported-syntax diagnostics for JavaScript-shaped input; TypeScript transpilation may + shift them. - [x] 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. - -- [x] Return real promises from `Promise.all`, `Promise.allSettled`, and `Promise.race`. -- [x] Canonicalize dotted tool names into namespace paths so every advertised dotted path is executable, one - canonical path can be both a callable tool and a namespace, and the last definition supplied for a canonical - path wins. -- [x] Allow blocked member names (`constructor`, `prototype`, `__proto__`) as tool path segments: segments are Map - keys and inert strings, never plain-object property accesses, so every advertised path is executable. Blocked - member access on data values stays rejected. Tool names with empty segments are rejected at construction. -- [ ] 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. -- [x] Make callback acceptance consistent across built-ins: collections, sort, string replacers, `Array.from` - mappers, and promise reactions share one acceptance rule. -- [x] Reject every unsupported callable callback argument explicitly rather than silently ignoring it - (`JSON.stringify` replacers and `JSON.parse` revivers fail loudly). The iteration-method `thisArg` is - accepted and ignored: CodeMode functions have no `this`, so ignoring it matches JS arrow semantics. -- [ ] Make async callback behavior consistent across built-ins; only string replacers settle async callback results - today. -- [ ] 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. +- [ ] Distinguish user-thrown failures from interpreter defects and explicit tool refusals from sanitized internal tool + failures; preserve those categories in caught errors, promise rejection handlers, and `Promise.allSettled` + reasons.