Browse documentation

0177 - Annex B is part of the test262 conformance target, and new Annex B surfaces sit behind a compatibility flag

Date: 2026-11-05 Area: language, test262, embedding Issue: #2063 Supersedes: ADR 0085 Related: ADR 0061, ADR 0046, #853, #2069, #1535, #1116

Context

ADR 0085 deferred broad ECMA-262 Annex B support until after 1.0, kept annexB out of the default test262 categories, and treated its pass rate as informational. It argued from a sandbox-first, non-browser product direction.

The conformance target has since changed. It is now 100% of test262 in every mode test262 requires, strict and non-strict, with Annex B and staging included. 0.18.0 is the release that reaches 100%, and 1.0 requires it. GocciaScript is primarily an engine for embedding, with sensible defaults that a host can easily change. Annex B does not stop being legacy behaviour: ECMA-262 (ES2026, Annex B introduction) still says implementations are "discouraged from implementing these features unless the implementation is part of a web browser or is required to run the same legacy ECMAScript code that web browsers encounter". An embedder that runs legacy library code is that second case, and test262 measures all of it. ADR 0085 would have a contributor turn down work the release now needs.

Decision

Annex B is part of GocciaScript's conformance target.

  • annexB joins the default test262 categories and counts toward the published pass rate. Making the runner and CI run it by default, after the two runner defects below are fixed, is #2069.
  • From 0.18.0 the annexB result is a release gate on the same terms as the other default categories.
  • A new Annex B surface goes behind an Engine.Compatibility flag, off by default, with a matching --compat-* command-line flag and config key. The test262 runner's engine profile in GocciaTest262Runner turns it on, as it does cfVar and cfNonStrictMode. The default profile keeps its modern shape, and a host that needs the legacy surface turns on one flag. The 0.18.0 Annex B work introduces the flag; this ADR does not add it.
  • The flag follows the existing naming rule. Each --compat-* flag is one TGocciaCompatibility member (Goccia.SourcePipeline.pas) and one SOURCE_COMPATIBILITY_FLAGS entry (Goccia.CLI.Options.pas), whose option name is compat- followed by a kebab-case name for the behaviour it enables (cfLabel is --compat-label, cfForIn is --compat-for-in-loop). The config key is the same name. The one member outside that rule, cfExperimentalJSModuleSource, is an experimental proposal flag (--experimental-js-module-source), not a compatibility path. No existing flag is named after a spec annex, so the spelling is left to the issue that adds the flag. Like every other compatibility flag, it is listed by name wherever it is needed: ADR 0046 removed the --compat-all meta-flag, and nothing brings it back.
  • Annex B surfaces that already ship stay as they are, always on or behind the flags they already have. They are not moved behind the new flag.

Surfaces that already ship

Always on, in every profile:

  • String.prototype.substr (B.2.2.1), a native method in Goccia.Values.StringObjectValue.pas.
  • String.prototype.trimLeft and String.prototype.trimRight (B.2.2.15 and B.2.2.16), which are the trimStart and trimEnd function objects, in the same file.
  • Date.prototype.toGMTString (B.2.3.3), in the Date shim in Goccia.Shims.pas. It is a separate method that returns toUTCString(), where B.2.3.3 makes it the toUTCString function object itself; that gap is 0.18.0 work.
  • RegExp.prototype.compile (B.2.4.1), in Goccia.Builtins.GlobalRegExp.pas.
  • Part of the B.1.2 RegExp pattern grammar, in a pattern without the u or v flag (Goccia.RegExp.Compiler.pas): identity escapes (\a matches a, \p matches p, and \k matches k in a pattern without named groups), an incomplete \x escape matched as literal characters, a lone {, } or ] as a pattern character, and a quantified lookahead such as (?=a)*. The rest of B.1.2 is not implemented yet or is incomplete. Examples: legacy octal escapes, \8 and \9 as identity escapes (both are back references today), an incomplete \u escape (a SyntaxError), \c without a control letter (which matches c rather than \c), and a class range with a class escape such as [\d-a] (accepted, but it does not match -).
  • The [[IsHTMLDDA]] slot of B.3.6. IsLooselyEqual in Goccia.Arithmetic.pas checks it, and the only object that has it is the test262 host's TGocciaTest262IsHTMLDDAValue (Goccia.Test262.Host.pas), which also answers typeof and ToBoolean itself. A normal host has no such object, so the check changes nothing for it.

Also always on, and Annex B until ES2021: the legacy Object.prototype accessor methods __proto__, __defineGetter__, __defineSetter__, __lookupGetter__ and __lookupSetter__, shims in Goccia.Shims.pas. ES2022 moved them into the main body (ES2026 §20.1.3.8 and §20.1.3.9), and their test262 tests are under built-ins/Object/prototype, not annexB.

Behind existing compatibility flags:

  • Block-level function declarations (B.3.2) and function declarations as an if or else clause (B.3.3), in script source under --compat-function plus --compat-non-strict-mode (Goccia.Compiler.BlockFunctions).
  • Labelled function declarations (B.3.1), in non-strict code under --compat-label plus --compat-function plus --compat-non-strict-mode (see ADR 0061).
  • A var redeclaring a simple catch parameter (B.3.4), wherever --compat-var allows var.

Baseline

Measured at GocciaScript 7c6c8225 (origin/main) against the pinned test262 suite 91c70759363c46557b694792bf34a2551a7af5ba (scripts/test262-suite-sha.txt), with GocciaTest262Runner --categories=annexB at the runner's defaults (4 jobs, 20 s per-test timeout, 2 GiB per-test heap): 1086 tests run, 787 pass, 291 fail, 8 wrapper-infra, 0 timeouts.

AreaPassFailWrapper-infra
built-ins/Array100
built-ins/Date2220
built-ins/Function150
built-ins/Object010
built-ins/RegExp27350
built-ins/String23880
built-ins/TypedArrayConstructors100
built-ins/escape0160
built-ins/unescape0190
language/comments008
language/eval-code397720
language/expressions5210
language/function-code15810
language/global-code15300
language/literals350
language/statements1660

Two groups of results at 7c6c8225 came from the runner. The 20 failures with SyntaxError: Identifier 'IsHTMLDDA' has already been declared are a runner defect: its own harness declares the name; #2069 fixes it. The 8 wrapper-infra results are the HTML-like comment tests (B.1.1). Those are an engine gap, because the parser does not accept HTML-like comments yet, but the runner misreported them as wrapper-infra. Since ADR 0175 (#2067) the runner grades them as failures. This table is a measurement snapshot; README and website figures stay live-sourced from the published run (#1116).

Consequences

  • Annex B work is in scope from 0.18.0. A missing Annex B surface is a conformance gap like any other, for example escape and unescape (#1535), which go behind the new flag.
  • The default profile does not change. A host gets the new Annex B surfaces only by turning the flag on.
  • Copy that says Annex B is "not a pre-1.0 target" or "deferred" is wrong and is updated with this ADR. Copy that describes the published run as excluding Annex B stays true until #2069 adds annexB to that run.