docs(codemode): add interpreter doc (#36026)

packages/codemode/AGENTS.md

@@ -4,6 +4,7 @@
 - Do not add a speculative generic permission or approval policy. A host omits tools it does not expose and enforces domain authorization inside each provided tool.
 - Keep Code Mode unaware of host session, channel, and conversation models. The hosting application supplies trusted execution scope around it.
 - Tool schemas are the model-facing Interface. Keep arguments minimal and natural to the operation; never add unrelated IDs as ambient capability tokens.
+- When interpreter behavior or support changes, update `interpreter-support.md` and direct tests in the same PR. Update `codemode.md` when the package design, integration status, or rationale changes.
 
 ## OpenAPI
 

packages/codemode/README.md

@@ -235,23 +235,21 @@ A host cannot define its own `$codemode` top-level namespace.
 
 ## Supported Programs
 
-CodeMode executes a deliberately bounded JavaScript subset. It supports:
+CodeMode executes a deliberately bounded JavaScript subset. See the
+[interpreter support checklist](./interpreter-support.md) for the complete, checkable language and standard-library
+matrix, known semantic gaps, and intentional exclusions.
 
-- Plain data literals, property access, assignment, destructuring, and sequence expressions (the comma operator, evaluated left to right with the final value returned).
-- `if`, conditional expressions, `switch`, `for`, `for...of` (arrays, strings, Maps, Sets, including assignment-form destructuring such as `for ([key, value] of entries)`), `for...in` (own keys of plain objects, index strings of arrays, and namespace/tool names of `tools` references - anything else is an error suggesting `for...of` or `Object.keys`, rather than real JS's surprising behavior of indices for strings and zero iterations for Maps/Sets), `while`, and `do...while`.
-- Arrow functions and function declarations with closures, defaults, rest parameters, and destructuring.
-- Optional chaining, nullish coalescing, templates, spread (arrays, strings, Maps, Sets), and `try`/`catch`.
-- Common array, string, number, `Object`, `Math`, and `JSON` operations, including primitive-number `valueOf`, the standard non-finite `Number` constants, and host-backed `Math.random`. Mutating array methods include `push`/`pop`/`shift`/`unshift`/`splice` (removes in place and returns the removed elements)/`fill`/`copyWithin`; array `keys`/`values`/`entries` return **arrays** (matching the Map/Set convention) and work with `for...of` and spread. String methods include `localeCompare` (locale/options arguments ignored), `normalize`, and the `trimLeft`/`trimRight` aliases. `Object.keys` also accepts arrays (index strings, as in JS) and tool references: `Object.keys(tools)` lists the top-level namespaces, including `$codemode`, and `Object.keys(tools.ns)` lists the names at that node (a callable tool enumerates as `[]`; an unknown path is an `UnknownTool` diagnostic). `Object.values`/`Object.entries` on a tool reference fail with a pointer at `Object.keys(tools)` and `tools.$codemode.search`.
-- `Date` - `Date.now()`/`Date.parse()`/`Date.UTC()`, `new Date(...)`, the getter methods, and date arithmetic/comparison via the time value. Dates stringify as ISO (`toString` included, for determinism across host timezones).
-- Regular expressions - `/literals/` and `new RegExp(...)` with `test`/`exec` (stateful `lastIndex` for `g`), plus string `match`/`matchAll`/`replace`/`replaceAll`/`split`/`search` with patterns. Match results are arrays carrying `index` and named `groups` as own properties (`input` is omitted). `replace` and `replaceAll` accept function replacers with captures, offset, input, and named groups; callbacks run sequentially, may await tool calls, and have their results coerced to strings. Invalid patterns, invalid flags, and missing-`g` calls fail with catchable errors that say what was wrong and how to fix it (escaping hints, the exact `/pattern/g` to write). Patterns run on the host engine, so pathological backtracking is bounded only by the execution timeout.
-- `Map` and `Set` - construction from entries/arrays/strings, `get`/`set`/`add`/`has`/`delete`/`clear`/`size`/`forEach`, and `keys`/`values`/`entries` returning **arrays** (not iterators).
-- URL helpers - `URL` resolution and mutation, linked `URLSearchParams`, `URL.canParse`/`URL.parse`, URI and URI-component encoding/decoding, and query parameter construction, lookup, mutation, sorting, callbacks, and materialization. URLSearchParams iteration methods return arrays, matching the Map/Set convention.
-- First-class promises - an un-awaited `tools.ns.tool(...)` is a promise value whose call starts immediately on a supervised fiber; `await` resolves it (awaiting a non-promise value is a no-op, and `return tools.ns.tool(...)` resolves like an async-function return). `Promise.all`, `Promise.allSettled`, and `Promise.race` accept any array mixing promises and plain values (built inline, beforehand, or via spread); `Promise.resolve`/`Promise.reject` construct settled promises. `Promise.allSettled` rejection reasons are the same plain `{ name?, message }` data a `catch` binding sees, and `Promise.race` interrupts its losing in-flight calls. At most 8 tool calls run concurrently. When a program completes, still-running un-awaited calls are awaited before the execution ends; a failure from a call that was never awaited surfaces as an unhandled-rejection diagnostic.
-- `throw value` and `throw new Error(message)` for explicit program failure. `Error` (and `TypeError`/`RangeError`/`SyntaxError`/`ReferenceError`/`EvalError`/`URIError`) are real constructors, callable with or without `new`; error values are plain `{ name, message }` data that additionally satisfy `instanceof Error` (a specific type matches itself and `Error`, as in JS). Every caught failure - thrown errors, interpreter runtime errors, and tool failures - is `instanceof Error` in a `catch` block; a thrown non-error value (`throw "text"`) is not, matching JS. Caught failures carry the `name` the equivalent real-JS failure would have - `JSON.parse` and invalid regex patterns produce a `SyntaxError` (satisfying `instanceof SyntaxError`), an unknown identifier a `ReferenceError`, assigning to a constant a `TypeError`, a bad `normalize` form a `RangeError`; failures with no specific analogue (including tool failures) are named `"Error"`. `instanceof` also recognizes `Date`, `RegExp`, `Map`, `Set`, `URL`, `URLSearchParams`, `Array`, `Object`, and `Promise`; any other right-hand side is a catchable error.
+At a high level, it supports:
 
-Inside a program, standard-library values stay live everywhere: the internal data checkpoints (`Object.*` helpers, spread, coercion inputs) preserve the instances, so `Object.values({ d: date })[0].getTime()` and a spread copy of an object holding a Map keep working. Only at the host boundary (final result, tool arguments, `JSON.stringify`) do they serialize exactly as `JSON.stringify` would: Date and URL become strings (an invalid Date becomes `null`), while RegExp, Map, Set, and URLSearchParams become `{}`. Promise values never cross a data boundary: an un-awaited promise in a result or tool argument produces a diagnostic that says to await it, instead of serializing to `{}`.
+- Plain data, property access and assignment, destructuring, functions, conditionals, loops, spread, optional chaining,
+  and structured error handling.
+- Allowlisted Array, String, Number, Object, Math, JSON, console, Date, RegExp, Map, Set, URL, and URLSearchParams APIs.
+- Eager supervised tool promises, direct `await`, and the supported `Promise` combinators for concurrent work.
+- Live standard-library values inside the sandbox and predictable JSON-like serialization at tool/result boundaries.
+- Actionable diagnostics for unsupported syntax, invalid data, tool failures, limits, and execution failures.
 
-It does not expose `eval`, dynamic imports, modules, classes, generators, timers, host globals, prototype mutation, custom promise constructors (`new Promise`), promise chaining (`.then`/`.catch`/`.finally` - `await` with `try`/`catch` is the supported style), or arbitrary method calls. Unsupported syntax returns an `UnsupportedSyntax` diagnostic with a source location when available.
+It does not expose ambient host authority or arbitrary JavaScript execution. Unsupported syntax returns an
+`UnsupportedSyntax` diagnostic with a source location when available.
 
 CodeMode is an orchestration language, not a general JavaScript runtime.
 

packages/codemode/codemode.md

@@ -6,7 +6,8 @@ It records current behavior, intentional boundaries, durable rationale, and mate
 Completed implementation history, branch names, test counts, and closed findings belong in git, not here. Remove
 completed work instead of preserving checked-off chronology.
 
-Detailed package API documentation lives in [README.md](./README.md). OpenAPI-specific follow-ups live in
+Detailed package API documentation lives in [README.md](./README.md), and the checkable language/runtime matrix lives
+in [interpreter-support.md](./interpreter-support.md). OpenAPI-specific follow-ups live in
 [src/openapi/TODO.md](./src/openapi/TODO.md).
 
 ## How CodeMode Works
@@ -140,31 +141,5 @@ represent accurately rather than guessing semantics.
 
 ## Remaining Work
 
-Keep only material unresolved work here. Small isolated defects should be GitHub issues; adapter-only work belongs in
-the adapter TODO. Delete entries when completed.
-
-### DSL expansion
-
-The supported JavaScript subset should grow when common model-generated code improves tool orchestration. These are
-current omissions to implement, not intentional product boundaries.
-
-- [ ] Design proper multi-stage promise pipelines. Supporting `.then`, `.catch`, and `.finally` should preserve promise
-      assimilation, cancellation, failure handling, and concurrent per-item pipelines rather than adding syntax-only
-      shims. Consider `Promise.any` in the same pass.
-- [ ] Support async iteration and `for await...of`. Define behavior first for the runtime's supported promise and
-      collection values, then extend it to bounded host streams when a stream boundary exists.
-- [ ] Support callback-bearing standard-library variants that models commonly generate: the mapper argument to
-      `Array.from(...)` and replacers for `JSON.stringify(...)`, including Effect-aware callbacks where needed.
-- [ ] Add `Object.is` after runtime method and tool references have stable identity semantics.
-- [ ] Add deterministic modern collection conveniences where they improve orchestration: `Object.groupBy`, Set
-      composition methods, and `Array.prototype.toSpliced`.
-- [ ] Decide whether iterable `Math.sumPrecise` belongs in the runtime.
-- [ ] Refine diagnostics so user throws, expected tool failures, unexpected host/tool defects, and genuine interpreter
-      defects are distinguishable without leaking private causes.
-
-### Tool and result contracts
-
-- [ ] Design explicit tagged representations and size rules before allowing Blob, File, ArrayBuffer, typed arrays, or
-      host streams to cross the sandbox boundary.
-- [ ] Define one consistent policy for tool path segments named `__proto__`, `constructor`, or `prototype`. They must
-      either be safely callable, rejected before catalog generation, or use one documented escaping rule.
+The [interpreter support checklist](./interpreter-support.md) owns concrete DSL, standard-library, semantic-correctness,
+diagnostic, and data-boundary work. OpenAPI adapter work remains in [src/openapi/TODO.md](./src/openapi/TODO.md).

packages/codemode/interpreter-support.md

@@ -0,0 +1,296 @@
+# 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](#known-semantic-gaps).
+- [Intentional exclusions](#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
+
+- [x] JavaScript parsed with the latest syntax accepted by Acorn, then restricted by the interpreter allowlist.
+- [x] 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.
+- [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] Live Date, RegExp, Map, Set, URL, and URLSearchParams values inside the sandbox.
+- [x] Tool calls through the host-provided `tools` tree only.
+- [x] Cooperative timeout, tool-call accounting, output bounding, and a maximum of eight concurrent tool calls.
+- [ ] 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] 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.
+
+## 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] 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
+
+- [x] Blocks and empty statements.
+- [x] `if`/`else` and conditional expressions.
+- [x] `switch`, including default clauses and fallthrough.
+- [x] `for`, `while`, and `do...while`.
+- [x] `for...of` over arrays, strings, Maps, Sets, and URLSearchParams.
+- [x] `for...in` over own keys of plain objects, arrays, and tool references.
+- [x] Unlabeled `break` and `continue`.
+- [x] `try`, `catch`, optional catch bindings, and `finally`.
+- [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
+
+- [x] Function declarations, function expressions, and arrow functions.
+- [x] Synchronous and `async` functions.
+- [x] Closures, recursion, default parameters, rest parameters, and destructured parameters.
+- [x] Expression and block function bodies.
+- [x] User callbacks for the supported Array, Map, Set, URLSearchParams, sort, and string-replacement APIs.
+- [x] `Boolean`, `Number`, `String`, `parseInt`, `parseFloat`, and URI helpers as callbacks where applicable.
+- [x] 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
+
+- [x] Property access with dot or computed bracket syntax.
+- [x] Optional property access and optional calls.
+- [x] Function/tool calls and spread arguments.
+- [x] Sequence expressions (the comma operator).
+- [x] `await` for sandbox promises; awaiting a plain value is a no-op.
+- [x] `new` for Error types, Date, RegExp, Map, Set, URL, and URLSearchParams.
+- [x] Arithmetic operators: `+`, `-`, `*`, `/`, `%`, and `**`.
+- [x] Equality and ordering: `==`, `!=`, `===`, `!==`, `<`, `<=`, `>`, and `>=`.
+- [x] Bitwise operators: `&`, `|`, `^`, `~`, `<<`, `>>`, and `>>>`.
+- [x] Logical operators: `&&`, `||`, `??`, and `!`, with short-circuiting.
+- [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 and `new Promise(...)`.
+
+## Promises and tools
+
+- [x] Tool calls start eagerly and return supervised, run-once sandbox promises.
+- [x] Direct `await`, repeated awaits, and implicit resolution when a promise is returned from a function/program.
+- [x] `Promise.resolve` and `Promise.reject`.
+- [x] `Promise.all`, `Promise.allSettled`, and `Promise.race` over supported collections containing promises and plain
+      values.
+- [x] `Promise.all` preserves result order and rejects on the first observed failure.
+- [x] `Promise.allSettled` returns plain fulfilled/rejected outcome records.
+- [x] `Promise.race` interrupts losing in-flight tool calls.
+- [x] Un-awaited calls are drained before execution ends; unhandled failures become diagnostics.
+- [x] `try`/`catch` can handle awaited tool and promise failures.
+- [ ] Real promise values from `Promise.all`, `Promise.allSettled`, and `Promise.race`. These calls currently settle
+      before returning, so separately constructed combinator batches do not overlap as normal JavaScript promises do.
+- [ ] `Promise.any`.
+- [ ] Promise chaining with `.then`, `.catch`, and `.finally`.
+- [ ] Custom promise construction with `new Promise(...)`.
+- [ ] Async iterables, host streams, and stream consumption.
+
+## Objects and properties
+
+- [x] Own-field reads and writes on plain data objects.
+- [x] Computed property names and object spread.
+- [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-sandbox Object helpers.
+- [x] 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
+
+- [x] Static methods: `Array.isArray`, `Array.of`, and `Array.from`.
+- [x] Iteration/transformation: `map`, `filter`, `flatMap`, and `forEach`.
+- [x] Searching/tests: `find`, `findIndex`, `findLast`, `findLastIndex`, `some`, `every`, `includes`, `indexOf`, and
+      `lastIndexOf`.
+- [x] Aggregation: `reduce` and `reduceRight`.
+- [x] Ordering: `sort`, `toSorted`, `reverse`, and `toReversed`.
+- [x] Access/copying: `at`, `slice`, `concat`, `flat`, `with`, and `join`.
+- [x] Mutation: `push`, `pop`, `shift`, `unshift`, `splice`, `fill`, and `copyWithin`.
+- [x] Materialized iteration helpers: `keys`, `values`, and `entries` return arrays rather than iterators.
+- [x] `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.
+- [ ] Correct `findLast` return behavior when its predicate mutates the examined element.
+
+## Strings
+
+- [x] Case/normalization: `toLowerCase`, `toUpperCase`, `normalize`.
+- [x] Trimming: `trim`, `trimStart`, `trimEnd`, `trimLeft`, and `trimRight`.
+- [x] Searching/tests: `includes`, `startsWith`, `endsWith`, `indexOf`, `lastIndexOf`, and `search`.
+- [x] Slicing/access: `slice`, `substring`, `substr`, `at`, `charAt`, `charCodeAt`, and `codePointAt`.
+- [x] Construction/transformation: `split`, `concat`, `repeat`, `padStart`, `padEnd`, `replace`, and `replaceAll`.
+- [x] Regular-expression integration: `match`, materialized `matchAll`, `replace`, `replaceAll`, `split`, and `search`.
+- [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 no-argument parity for `match()` and `search()`.
+
+## Numbers and Math
+
+- [x] Coercion functions: `Number`, `parseInt`, and `parseFloat`.
+- [x] Number predicates/parsers: `Number.isInteger`, `Number.isFinite`, `Number.isNaN`, `Number.isSafeInteger`,
+      `Number.parseInt`, and `Number.parseFloat`.
+- [x] Number formatting: `toFixed`, `toPrecision`, `toExponential`, `toString`, and `valueOf`.
+- [x] Number constants: `MAX_SAFE_INTEGER`, `MIN_SAFE_INTEGER`, `MAX_VALUE`, `MIN_VALUE`, `EPSILON`, `NaN`,
+      `POSITIVE_INFINITY`, and `NEGATIVE_INFINITY`.
+- [x] Math constants: `PI`, `E`, `LN2`, `LN10`, `LOG2E`, `LOG10E`, `SQRT2`, and `SQRT1_2`.
+- [x] 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
+
+- [x] `JSON.parse` and `JSON.stringify`.
+- [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
+
+- [x] `Date.now`, `Date.parse`, and `Date.UTC`.
+- [x] `new Date()` from the current time, epoch milliseconds, a date string, another Date, or local components.
+- [x] `getTime`, `valueOf`, `toISOString`, `toJSON`, and deterministic ISO `toString`.
+- [x] Local getters: `getFullYear`, `getMonth`, `getDate`, `getDay`, `getHours`, `getMinutes`, `getSeconds`, and
+      `getMilliseconds`.
+- [x] UTC getters: `getUTCFullYear`, `getUTCMonth`, `getUTCDate`, `getUTCDay`, `getUTCHours`, `getUTCMinutes`,
+      `getUTCSeconds`, and `getUTCMilliseconds`.
+- [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.
+- [ ] Native `RangeError` branding for invalid `toISOString()` calls.
+- [ ] Temporal and Intl date/time APIs.
+
+## Regular expressions
+
+- [x] Literal and `new RegExp(pattern, flags)` construction.
+- [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.
+- [ ] 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
+
+- [x] `new Map()` from entry arrays or another Map.
+- [x] Map `get`, `set`, `has`, `delete`, `clear`, `size`, and `forEach`.
+- [x] `new Set()` from arrays, strings, or another Set.
+- [x] Set `add`, `has`, `delete`, `clear`, `size`, and `forEach`.
+- [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.
+
+## URL and URI helpers
+
+- [x] `encodeURI`, `encodeURIComponent`, `decodeURI`, and `decodeURIComponent`.
+- [x] `new URL(input, base)`, `URL.canParse`, and `URL.parse`.
+- [x] URL `toString`, `toJSON`, and linked `searchParams`.
+- [x] Readable URL fields: `href`, `origin`, `protocol`, `username`, `password`, `host`, `hostname`, `port`,
+      `pathname`, `search`, and `hash`.
+- [x] Writable URL fields except `origin`.
+- [x] `new URLSearchParams()` from query strings, data objects, pairs, Maps, and URLSearchParams.
+- [x] URLSearchParams `append`, `delete`, `get`, `getAll`, `has`, `set`, `sort`, `forEach`, `keys`, `values`,
+      `entries`, `toString`, and `size`.
+- [x] URL values serialize to their href; URLSearchParams serialize to `{}`.
+
+## Errors and diagnostics
+
+- [x] `Error`, `TypeError`, `RangeError`, `SyntaxError`, `ReferenceError`, `EvalError`, and `URIError`, callable with
+      or without `new`.
+- [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] 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`.
+- [ ] Bound pending tool-call admission/allocation in addition to execution concurrency.
+- [ ] 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.