From 96762fbd479839588c4e0495dc50ba4e2ee22c66 Mon Sep 17 00:00:00 2001 From: ASDAlexander77 Date: Sun, 15 Nov 2026 12:18:40 +0000 Subject: [PATCH] docs: production-readiness plan and Phase 0 results; test_wasm.ps1 uses relative paths Co-Authored-By: Claude Sonnet 5.5 --- docs/how/wasm/test/test_wasm.ps1 | 9 +- docs/production-readiness-phase0.md | 174 ++++++++++++++++++++++++ docs/production-readiness-plan.md | 204 ++++++++++++++++++++++++++++ 3 files changed, 380 insertions(+), 7 deletions(-) create mode 100644 docs/production-readiness-phase0.md create mode 100644 docs/production-readiness-plan.md diff --git a/docs/how/wasm/test/test_wasm.ps1 b/docs/how/wasm/test/test_wasm.ps1 index c7dd099eb..d693ad55d 100644 --- a/docs/how/wasm/test/test_wasm.ps1 +++ b/docs/how/wasm/test/test_wasm.ps1 @@ -1,9 +1,4 @@ -$files = Get-ChildItem -Path C:\dev\TypeScriptCompiler\tslang\test\tester\tests\ -Filter *.ts -Force - -$Env:GC_LIB_PATH="C:\dev\TypeScriptCompiler\__build\gc\msbuild\x64\debug\Debug" -$Env:LLVM_LIB_PATH="C:\dev\TypeScriptCompiler\__build\llvm\msbuild\x64\debug\Debug\lib" -$Env:TSLANG_LIB_PATH="C:\dev\TypeScriptCompiler\__build\tslang\windows-msbuild-debug\lib" -$Env:TSLANG_BIN_PATH="C:\dev\TypeScriptCompiler\__build\tslang\windows-msbuild-debug\bin" +$files = Get-ChildItem -Path ..\..\..\..\..\tslang\test\tester\tests\ -Filter *.ts -Force #foreach ($file in $files) $files | ForEach-Object -Parallel { @@ -13,7 +8,7 @@ $files | ForEach-Object -Parallel { $out += "Compiling $file ... " - $exe = "$Env:TSLANG_BIN_PATH\tslang.exe" + $exe = "tslang.exe" $outFileName = $file.BaseName + ".wasm" $stdOutputFileName = $file.BaseName + ".txt" $errOutputFileName = $file.BaseName + ".err" diff --git a/docs/production-readiness-phase0.md b/docs/production-readiness-phase0.md new file mode 100644 index 000000000..f25ac596a --- /dev/null +++ b/docs/production-readiness-phase0.md @@ -0,0 +1,174 @@ +# Production readiness: Phase 0 results + +Working notes for Phase 0 of the [production-readiness plan](production-readiness-plan.md). +Compiler under test: `main` at `3392fef6`, 2026-11-13, Windows x64. + +## 1. Debug-built compiler suite (Windows) + +`ctest -C Debug -j 8 --timeout 300` on a Debug build of `3392fef6` (no fixes from this document): +**60 of 7,085 tests failed**, none by timeout, in 28 minutes. The library environment variables +(`DEFAULT_LIB_PATH` and the others) were cleared, as in CI, and other builds ran on the machine at +the same time. The Release build of the same commit passes all of them. + +The 60 failures fall into 14 groups. None has been investigated yet. + +| Group | Tests | Variants failing | +| --- | --- | --- | +| `00parse_number_range` | 6 | exe, JIT, rc and none corpus | +| `00class_to_interface_null` | 8 | exe, JIT, rc and none corpus, own | +| `00throw_bool_bigint` | 6 | exe, JIT, rc and none corpus | +| `00throw_f32` | 6 | exe, JIT, rc and none corpus | +| `00cast_to_f32` | 6 | exe, JIT, rc and none corpus | +| `value_missing_niche`, `value_missing_niche_one_field`, `value_missing_ops` | 18 | exe and JIT under gc, rc, none | +| `gc-opt-uncaught-throw_*` (string, class, number, number_shortest) | 4 | exe | +| `symbol-value-error` | 1 | exe | +| `foreign-thread-gc` | 1 | exe | +| `atomic-rc` | 1 | exe | +| `gc-defaultlib-collector` | 1 | exe; may be the cleared library path | +| `borrow-facts-defaultlib` | 1 | may be the cleared library path | +| `test-bindgen-cli` | 1 | | + +`00throw_f32`, `00throw_bool_bigint`, `00cast_to_f32`, `gc-opt-uncaught-throw_*`, `test-bindgen-cli` +and `gc-defaultlib-collector` were already on the 2026-10-01 list. The rest are new since then. +The full log is not kept in the repository. + +## 2. Fatal-error sites + +A search for `llvm_unreachable` and `report_fatal_error` under `tslang/` finds 42 matches in 23 +files. 8 are inside comments, which leaves 34 live sites. This is a first-pass sort by kind; none +has been proven reachable or dead yet. + +In a Release build without assertions, LLVM normally compiles `llvm_unreachable` to an optimizer +hint, not a trap. If the LLVM used here is built that way, a reachable site in groups B and C does +not crash the released compiler: it continues with undefined behaviour. That is worse than a crash +and is the reason to triage these. Not verified for the prebuilt LLVM package. + +### A. Deliberate guards that also fire in Release (8) + +These use `report_fatal_error` with a message. They are internal-consistency or environment checks. + +| Site | Message | +| --- | --- | +| `tslang/tslang/vscode.cpp:209` | error emitting data to file | +| `tslang/include/TypeScript/TypeScriptPassContext.h:35` | lowering-context entry left by a previous function | +| `tslang/lib/TypeScriptExceptionPass/Win32ExceptionPass.cpp:378` | no end found for an exception handling region | +| `tslang/lib/TypeScriptExceptionPass/WasmExceptionPass.cpp:307` | a landing pad reached other than by an invoke | +| `tslang/lib/TypeScriptExceptionPass/CxxThrowCallingConvPass.cpp:173` | `_CxxThrowException` used other than as a direct callee | +| `tslang/include/TypeScript/MLIRLogic/MLIRRTTIHelperVCWin32.h:560` | absolute EH references need 32-bit pointers | +| `tslang/include/TypeScript/LowerToLLVM/LLVMRTTIHelperVCWin32.h:352` | absolute EH references need 32-bit pointers | +| `tslang/include/TypeScript/LowerToLLVM/TypeHelper.h:97` | `getSizeType()` needs the target | + +Proposed handling: keep them, but `vscode.cpp:209` is a user-reachable I/O failure (read-only folder, +full disk) and should be an ordinary error with exit code 1. + +### B. Defaults of switches meant to be exhaustive (6) + +| Site | Message | +| --- | --- | +| `tslang/tslang/TextDiagnostic.cpp:33`, `:55` | invalid diagnostic type | +| `tslang/lib/TypeScript/MLIRGenStatements.cpp:82` | unknown body type | +| `tslang/lib/TypeScript/MLIRGenStatements.cpp:495` | unknown statement type | +| `tslang/lib/TypeScript/MLIRGenImpl.h:4130`, `:4161` | unknown statement | + +Proposed handling: compare the parser's statement kinds with the handled list. Any statement kind +the parser can produce and the switch does not handle is reachable from user code. + +### C. Type and lowering gaps, reachability unknown (20) + +| Site | Message | +| --- | --- | +| `tslang/include/TypeScript/MLIRLogic/MLIRTypeHelper.h:3845` | wrong type | +| `tslang/include/TypeScript/LowerToLLVM/CastLogicHelper.h:1046`, `:1253` | review usage | +| `tslang/include/TypeScript/LowerToLLVM/CodeLogicHelper.h:323` | return op. can't be found | +| `tslang/include/TypeScript/LowerToLLVM/LLVMCodeHelper.h:492` | should be processed in constant with denseattr value | +| `tslang/include/TypeScript/LowerToLLVM/LLVMCodeHelper.h:523`, `:540` | ConstArrayType / ConstTupleType must not be used in array | +| `tslang/include/TypeScript/LowerToLLVM/LLVMCodeHelper.h:762` | not used | +| `tslang/include/TypeScript/LowerToLLVM/LLVMDebugInfo.h:56` | not implemented | +| `tslang/include/TypeScript/LowerToLLVM/UndefLogicHelper.h:200` | bug | +| `tslang/include/TypeScript/LowerToLLVM/UnaryBinLogicalOrHelper.h:47` | not implemented (after an `emitError`) | +| `tslang/lib/TypeScript/LowerToLLVM.cpp:4170` | type mismatch | +| `tslang/lib/TypeScript/LowerToLLVM.cpp:4336`, `:4481`, `:4723` | cast must happen earlier | +| `tslang/lib/TypeScript/LowerToLLVM.cpp:9120` | type usage (IntersectionType) is not implemented | +| `tslang/lib/TypeScript/LowerToAffineLoops.cpp:2609` | missing catch data | +| `tslang/lib/TypeScript/MLIRGenImpl.h:1599` | can't find local variable | +| `tslang/lib/TypeScript/MLIRGenImpl.h:5194` | type predicate can't find parameter index | +| `tslang/lib/TypeScript/MLIRGenImpl.h:10709` | capture or this ref is not resolved | + +Proposed handling, per site: a short repro attempt on the Debug compiler, then a caller trace if +the repro misses. Reachable sites become `emitError` plus failure. `UnaryBinLogicalOrHelper.h:47` +already emits an error first, so only the `llvm_unreachable` after it needs to go. + +### D. Inside comments (8) + +`Win32ExceptionPass.cpp:331`, `:1185`; `MLIRTypeHelper.h:1093`; `CastLogicHelper.h:1265`; +`CodeLogicHelper.h:310`; `MLIRGenTypes.cpp:3116`; `MLIRGenFunctions.cpp:2424`; +`MLIRGenGenerics.cpp:1562`. No action, other than deleting the dead comments when the file is next +touched. + +## 3. Known items not in the tracker + +Candidates came from earlier session notes. Each one marked "reproduced" was re-run today on the +Release compiler (JIT, default options). The rest still need a repro before an issue is filed. + +### Reproduced today + +| # | Item | Result today | Kind | +| --- | --- | --- | --- | +| 1 | A class field typed `(() => number) \| null` cannot be assigned a function: `this.f = t` | `error: invalid cast from () => number to () => number \| null`, then `not a function to call` | Valid TypeScript rejected | +| 2 | `n = b` and `s = b`, where `b` is a `boolean`, `n` a `number`, `s` a `string` | Compiles and prints `1 true`. `tsc` rejects both (TS2322) | Invalid TypeScript accepted | +| 3 | `Symbol("key")` at run time | `error: not a function to call` | Unsupported feature, unclear message | +| 4 | An optional interface field (`label?: string`) implemented by a get/set pair | `error: ... an optional field can't be filled by an accessor` | Unsupported feature, clear message | + +Checked and no longer a bug: an abstract field overridden by a get/set pair, read through the base +class, now returns the right value. + +Items 1 and 2 are fixed on branch `fix-fn-or-null-and-boolean-assign` (uncommitted): + +- **Item 1.** `(() => T) | null` is stored as the function value itself, with no tag: null is a null + code pointer in its first word. A function is now stored in it, `if (f)` and `f !== null` narrow + it, and it is called, under gc, rc, none and own. Test: `00function_or_null.ts`. +- **Item 2.** A boolean given to a number or a string, or a number or string given to a boolean, is + an error in assignments, declarations and arguments. Tests: `assign_boolean_to_number_error.ts`, + `assign_boolean_to_string_error.ts`, `assign_number_to_boolean_error.ts`, + `argument_boolean_to_number_error.ts`. + +Found while fixing them: + +| # | Item | Result today | Kind | +| --- | --- | --- | --- | +| 20 | `-mm=own`: a closure that captures the object it is stored in (`c.onTick = () => { c.seen++ }`) compiled, then crashed with an access violation once the field was cleared. **Fixed on the same branch**: the closure borrows the object, as one capturing `this` in a method does. Test: `00closure_back_reference_local.ts` | Was a crash at run time | Fixed | +| 23 | `-mm=own`: a closure stored in a field owns a *different* object it captured, and frees it when the field is cleared (`c.onTick = null`). A later use of that object compiled and read freed memory. **Fixed on the same branch** by the owner's ruling (2026-11-13): any use of the object after the capture is an error, as a use of a captured variable already was. `00tslang_issues_31_33.ts` lost one assertion that read a captured object. Test: `own_escaping_capture_used_after_error.ts` | Was a silent use-after-free | Fixed | +| 21 | A `fn \| null` value can be called without a null check, as a `C \| null` object's methods can. `tsc` rejects it (TS2721) | Compiles | Invalid TypeScript accepted | +| 22 | The default library has not been compiled against the boolean check | Not run | To verify | + +### Not yet re-verified + +| # | Item | Source | Kind | +| --- | --- | --- | --- | +| 5 | A closure stored in a variable of function type, then passed to a `@cdecl` parameter, loses its captures at run time | `TSLANG_ISSUES.md` | Silent miscompile | +| 6 | `-mm=rc`: fuzz seed 4487 crashes (argument assignment plus try/finally on a global field) | notes, 2026-11-10 | Crash | +| 7 | `-mm=rc`: seeds `review6r1__v1` / `v1b` crash through `f2 as any as (o: Op, ...)` | notes, 2026-10-31 | Crash | +| 8 | Memory-model fuzzer findings R1-R10, O4 and G1 (a gc closure bug) | notes, 2026-10-23 | Mixed; several were fixed in later rounds | +| 9 | With a class declared later in the file: built-in `arr.filter(arrow)` under `--no-default-lib` gives "the condition has no value" | notes | Valid TypeScript rejected | +| 10 | With a class declared later in the file: `assert(g.particles[0].duration == 3.0)` gives "Can't resolve property 'duration' of type any" | notes | Valid TypeScript rejected | +| 11 | `unknownVal` crashes under gc; a cast from `any` to an object type followed by a field write crashes | notes, 2026-10-28 | Crash; may be fixed by #723 | +| 12 | `-mm=own`: a union local narrowed by `instanceof` and walked twice gives a spurious use-after-move | notes, 2026-10-28 | Valid program rejected | +| 13 | `-mm=own`: lazy iterator helpers, `const seq = fibonacci().map(f)`, are refused | notes | Unsupported | +| 14 | `-mm=own`: `f && f(x)` with a callback, and a callback that is stored or captured | notes | Unsupported | +| 15 | `-mm=own`: `const o = {w: (x: number) => x}; apply(o)` | notes | Unsupported | +| 16 | Two-pass lambda parameter inference | notes, 2026-10-28 | Unsupported | +| 17 | `check_declarations` test is flaky: union member order depends on pointer values | notes, 2026-11-10 | Nondeterministic compiler output | +| 18 | `test-compile-00-for-await-yield` (Windows) and `test-compile-00-for-await` (Linux) fail now and then on hosted runners | notes | Flaky test | +| 19 | gc without stack promotion is twice as slow on the ray tracer (136 ms against 71 ms), unexplained | notes, 2026-11-10 | Performance | + +Item 17 matters beyond the test: output that depends on pointer values means builds are not +reproducible. + +## 4. Uncommitted edits on `main` + +| File | What the edit is | Suggested | +| --- | --- | --- | +| `tslang/CMakeLists.txt` | Adds an opt-in `TSLANG_ENABLE_LTCG` option, off by default | Owner's call; earlier measurement found link-time code generation gave no size win | +| `docs/how/wasm/test/test_wasm.ps1` | Replaces hard-coded `C:\dev\...` paths with relative ones | Looks safe to commit | + +Neither was touched. diff --git a/docs/production-readiness-plan.md b/docs/production-readiness-plan.md new file mode 100644 index 000000000..f0aaca644 --- /dev/null +++ b/docs/production-readiness-plan.md @@ -0,0 +1,204 @@ +# Production-readiness plan + +Draft, 2026-11-13. Status: proposal, nothing here is started. + +This plan takes tslang from "pre-alpha that passes its own tests" to a release a stranger can depend +on. It is ordered by phases with exit gates, not dates. Facts are marked **[checked]** (verified in +the repo or on GitHub on 2026-11-13) or **[notes]** (from earlier session notes, to be re-verified). + +## 1. Decisions made in this draft + +These four calls shape everything below. Each one is a proposal and can be overridden. + +| Decision | Proposed | Why | +| --- | --- | --- | +| Positioning | A documented TypeScript subset with listed differences from `tsc`, not a drop-in replacement | Some differences are deliberate: integer literals are typed `s32`, user functions are global symbols that can clash with C library names, and `-mm=own` rejects programs `tsc` accepts **[notes]**. "Full compatibility" cannot be claimed. | +| First production tier (confirmed by the owner, 2026-11-13) | Windows x64 and Linux x64, ahead-of-time executables and shared libraries, `-mm=gc` | It is the default model and the oldest path. The README itself calls `-mm=own` "in development" **[checked]**. | +| Later tiers | Tier 2: JIT, `-mm=rc`, wasm32. Tier 3: `-mm=own`, Android, wasm64, 32-bit x86 | Each is newer or has a known structural limit (rc does not collect cycles). | +| Non-goals for 1.0 | macOS, a language server, npm package resolution, running untyped JavaScript | None is among the README's targets or features; each is a project of its own. | + +"Production-ready" for a tier means all of the following hold: + +1. **No silent miscompiles known.** Every known wrong-output bug is fixed or the construct is rejected + with a diagnostic. +2. **No compiler crashes on valid or invalid input.** Unsupported constructs give an error with a + source location. +3. **The supported subset is written down** and tested against outside code, not only this repo's + tests. +4. **A release can be stayed on.** There is a stable channel, a version policy and a changelog. +5. **Regressions are caught before release** by an assertions-enabled compiler build in CI. + +## 2. Where it stands + +**Strengths [checked]** +- The issue tracker has zero open issues. One PR is open: #435, the LLVM 23 update. +- CI builds the compiler on Windows and Linux and runs the suite as release and debug *programs*, + each as executable and JIT, plus wasm32/wasm64 under Node. A separate workflow runs Android tests + on an x86_64 emulator (API 29). +- The tester corpus holds 865 `.ts` files. The last recorded full run was about 6,600 ctest tests + green **[notes]**. +- Releases are built from a pushed `v*` tag and run the debug-program legs before publishing. +- `LICENSE`, `CODE_OF_CONDUCT.md` and issue templates exist. + +**Gaps [checked]** +- **The compiler itself is only ever built as Release in CI.** Assertions and `llvm_unreachable` are + compiled out, so a whole class of internal errors is invisible there. +- **42 `llvm_unreachable` / `report_fatal_error` sites** remain across 23 files under `tslang/`. Each + is a potential crash instead of a diagnostic. +- **No systematic outside measurement.** The corpus appears to include some cases ported from + TypeScript's own tests (for example `logicalAssignment5_3`, `typeGuardFunction` **[notes]**; not + counted), but there is no run of the full official suite and no third-party code beyond + `native_ts_graphics`. +- **No stable channel.** Every release is a pre-release (alpha127 today, five in four days). +- **Missing files:** `SECURITY.md`, `CONTRIBUTING.md`, `CHANGELOG.md` (not in the root, `.github/` + or `docs/`). +- **No limits documentation.** The docs describe features. There is no supported-subset page and no + differences-from-`tsc` page. The roadmap in `docs/whats-new.md` is three completed items. +- **The scheduled test run is weekly** (Monday 18:30 UTC). The push-to-`main` trigger is commented + out in both test workflows. + +**Gaps [notes], to re-verify** +- The Debug-built compiler had 38 known suite failures on 2026-10-01, including a JIT `--opt` abort + on any program. Not re-run since. +- Known open items that are not in the tracker: + - `-mm=own`: optional accessor fields, capturing callbacks in Map/Set + - memory-model fuzzer findings R1-R10, O4, G1 + - run-time `Symbol` values and `obj[sym]` + - a `(() => T) | null` field cast + - a closure stored in a variable and passed to a `@cdecl` parameter loses its captures (recorded in + `TSLANG_ISSUES.md`) **[checked]** + - flaky tests: `check_declarations` (union order by pointer) and some async tests + +## 3. Phases + +### Phase 0: make the unknowns visible + +Nothing is fixed in this phase. It produces the lists the later phases work through. + +| Step | Output | +| --- | --- | +| Re-run the full suite on a Debug-built compiler, Windows and Linux | Current failure list, replacing the 2026-10-01 number | +| File every known untracked item above as a GitHub issue with a label per tier | The tracker becomes the single backlog | +| Triage the 42 fatal-error sites: reachable, proven dead, or unknown | A table in the tracker; reachable ones become issues | +| Land or drop the uncommitted edits in `tslang/CMakeLists.txt` and `docs/how/wasm/test/test_wasm.ps1` | Clean `main` | + +**Exit gate:** every known defect is an issue, and the Debug failure list is current. + +### Phase 1: external measurement + +The aim is to find what the project's own tests cannot. + +1. **TypeScript conformance triage.** Count the cases already ported into the corpus, then run the + full official TypeScript `tests/cases/conformance` and `compiler` cases through tslang. Classify each as: passes, clean diagnostic, compiler crash, or + wrong output. Publish the totals per language area. The crash and wrong-output buckets are the + work list. The clean-diagnostic bucket becomes the unsupported list in the docs. +2. **Differential runs against Node.** For every test that prints output and uses no tslang-only + types, run the same file under Node and compare. Differences are either bugs or entries for the + differences page. +3. **Real programs.** Port three to five small third-party TypeScript programs with no DOM or Node + dependencies (a JSON parser, a markdown renderer, an algorithm library, a small interpreter). + Record every change the port needed. +4. **Fuzzing beyond memory models.** Extend `tslang/test/fuzz` to generate type-level and + control-flow programs, checked against Node output. +5. **Sanitizers.** Run the suite with an AddressSanitizer build of the compiler on Linux, and run + compiled programs under ASan for the gc and rc models. + +**Exit gate:** conformance totals are published, and every crash and wrong-output result has an issue. + +### Phase 2: tier 1 hardening + +Scope: Windows and Linux x64, AOT, `-mm=gc`. + +1. **Assertions-enabled CI leg.** Add a Windows and a Linux job that builds the compiler with + assertions on (RelWithDebInfo plus `LLVM_ENABLE_ASSERTIONS`, or Debug) and runs the suite. It + starts as allowed-to-fail with the Phase 0 list and becomes required when the list is empty. +2. **Fix the Phase 0 Debug failures.** +3. **Zero reachable fatal errors.** Convert each reachable site from the Phase 0 triage to a + diagnostic with a location. +4. **Fix all tier 1 crash and wrong-output results from Phase 1.** +5. **Diagnostics quality.** Every error has a file, line and column, and where TypeScript has a + matching error code, the same code. Add a test corpus of expected diagnostics. +6. **Garbage-collector soak tests.** Long-running allocation, thread and async workloads (hours, not + seconds) on both platforms, watching for growth and crashes. +7. **Remove flakiness.** Fix or quarantine `check_declarations` and the async tests so a red run + always means a real failure. + +**Exit gate:** the assertions-enabled leg is green and required; zero open tier 1 issues labelled crash +or miscompile; a 24-hour soak passes on both platforms. + +### Phase 3: release engineering and docs + +This can run alongside Phase 2. + +1. **Version policy.** Adopt semantic versioning. State what a minor release may change: language + behaviour, command-line flags, runtime ABI, default library API. +2. **Two channels.** Keep the alpha tag stream as "nightly". Add a stable branch that only receives + fixes, with release candidates before each stable release. +3. **Release gate.** A stable release requires the full matrix green, including the + assertions-enabled leg and the Debug default library check that today is done by hand **[notes]**. +4. **Compiler and runtime compatibility.** The compiler already checks the async runtime's age + before linking a library. Extend this to one version stamp shared by the compiler, runtime and + default library, checked at link time. +5. **LLVM policy.** Pin one LLVM version per stable line. Decide whether #435 (LLVM 23) lands before + or after 1.0. +6. **Project files.** Add `CHANGELOG.md`, `CONTRIBUTING.md` and `SECURITY.md` with a private + reporting address. Remove the stale tracked root files `.travis.yml` and + `build_tslang_release.txt`. +7. **Documentation.** + - `docs/supported-typescript.md`: the subset, by language area, generated from the Phase 1 triage + - `docs/differences-from-tsc.md`: every deliberate difference with a short example + - `docs/status.md`: the tier table, what each tier guarantees and known limitations + - a first-run guide checked on a clean machine for Windows and Linux + - the README quick start leads with `--emit=exe`, and marks the JIT as preview, since the JIT is + outside tier 1 + - a real roadmap in place of the three checked items in `docs/whats-new.md` +8. **Installers.** A Windows zip and Linux tarball exist. Add checksums and, if wanted, signing and a + package-manager entry (winget, apt or Homebrew for Linux). + +**Exit gate:** a release candidate can be installed and used on a clean machine from the docs alone. + +### Phase 4: 1.0 for tier 1 + +1. Publish release candidates and ask for outside testing through GitHub Discussions. +2. Hold a fixed period (for example four weeks) with no new crash or miscompile reports against the + candidate. +3. Publish 1.0 with tier 1 marked stable and tiers 2 and 3 marked preview or experimental in + `docs/status.md`. + +### Phase 5: promote tiers 2 and 3 + +Each tier repeats the Phase 2 gate for its own scope before it is marked stable. + +| Target | Extra work before promotion | +| --- | --- | +| JIT | Fix the Debug `--opt` abort; decide whether the JIT cache format is versioned | +| `-mm=rc` | Document cycles as a limit or add a cycle detector; close the fuzzer rc findings | +| wasm32 | Stable host interface for the JavaScript runtime; browser test run, not only Node | +| `-mm=own` | Close open items (optional accessor fields, capturing callbacks); a written specification of the ownership rules; error messages reviewed by someone new to the model | +| Android, wasm64, x86 | Emulator runs for every ABI on each release; device testing | + +## 4. Order and dependencies + +- Phase 0 comes first and is small. +- Phases 1 and 3 can start together after Phase 0. +- Phase 2 needs the Phase 0 lists and grows as Phase 1 reports arrive. +- Phase 4 needs Phases 2 and 3 complete. +- Phase 5 work may continue throughout, but it must not block the tier 1 release. + +## 5. Risks + +| Risk | Mitigation | +| --- | --- | +| The conformance triage shows a much larger unsupported area than expected | Narrow the documented subset; do not delay 1.0 to widen it | +| One maintainer | `CONTRIBUTING.md`, labelled starter issues, and written design notes for the memory models and exception handling | +| New feature work keeps resetting stability | Feature work lands on `main` only; the stable branch takes fixes only | +| LLVM upgrades change behaviour | One LLVM version per stable line; upgrade only at a minor release with the full matrix | + +## 6. Open questions for the owner + +1. Should the test workflows run on every push to `main`? The trigger is commented out today, which + looks deliberate. +2. Is the "documented subset" positioning acceptable, or is closer `tsc` compatibility a goal? +3. Should LLVM 23 land before 1.0? +4. Is there an outside user or project, besides `native_ts_graphics`, whose needs should set + priorities?