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.
annexBjoins 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
annexBresult is a release gate on the same terms as the other default categories. - A new Annex B surface goes behind an
Engine.Compatibilityflag, off by default, with a matching--compat-*command-line flag and config key. The test262 runner's engine profile inGocciaTest262Runnerturns it on, as it doescfVarandcfNonStrictMode. 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 oneTGocciaCompatibilitymember (Goccia.SourcePipeline.pas) and oneSOURCE_COMPATIBILITY_FLAGSentry (Goccia.CLI.Options.pas), whose option name iscompat-followed by a kebab-case name for the behaviour it enables (cfLabelis--compat-label,cfForInis--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-allmeta-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 inGoccia.Values.StringObjectValue.pas.String.prototype.trimLeftandString.prototype.trimRight(B.2.2.15 and B.2.2.16), which are thetrimStartandtrimEndfunction objects, in the same file.Date.prototype.toGMTString(B.2.3.3), in the Date shim inGoccia.Shims.pas. It is a separate method that returnstoUTCString(), where B.2.3.3 makes it thetoUTCStringfunction object itself; that gap is 0.18.0 work.RegExp.prototype.compile(B.2.4.1), inGoccia.Builtins.GlobalRegExp.pas.- Part of the B.1.2 RegExp pattern grammar, in a pattern without the
uorvflag (Goccia.RegExp.Compiler.pas): identity escapes (\amatchesa,\pmatchesp, and\kmatcheskin a pattern without named groups), an incomplete\xescape 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,\8and\9as identity escapes (both are back references today), an incomplete\uescape (aSyntaxError),\cwithout a control letter (which matchescrather 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.paschecks it, and the only object that has it is the test262 host'sTGocciaTest262IsHTMLDDAValue(Goccia.Test262.Host.pas), which also answerstypeofand 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
iforelseclause (B.3.3), in script source under--compat-functionplus--compat-non-strict-mode(Goccia.Compiler.BlockFunctions). - Labelled function declarations (B.3.1), in non-strict code under
--compat-labelplus--compat-functionplus--compat-non-strict-mode(see ADR 0061). - A
varredeclaring a simple catch parameter (B.3.4), wherever--compat-varallowsvar.
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.
| Area | Pass | Fail | Wrapper-infra |
|---|---|---|---|
built-ins/Array | 1 | 0 | 0 |
built-ins/Date | 2 | 22 | 0 |
built-ins/Function | 1 | 5 | 0 |
built-ins/Object | 0 | 1 | 0 |
built-ins/RegExp | 27 | 35 | 0 |
built-ins/String | 23 | 88 | 0 |
built-ins/TypedArrayConstructors | 1 | 0 | 0 |
built-ins/escape | 0 | 16 | 0 |
built-ins/unescape | 0 | 19 | 0 |
language/comments | 0 | 0 | 8 |
language/eval-code | 397 | 72 | 0 |
language/expressions | 5 | 21 | 0 |
language/function-code | 158 | 1 | 0 |
language/global-code | 153 | 0 | 0 |
language/literals | 3 | 5 | 0 |
language/statements | 16 | 6 | 0 |
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
escapeandunescape(#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
annexBto that run.