docs(threads): publish PR-249 terminal inventory (#428)

Author: chrisbbreuer

README.md

@@ -73,7 +73,7 @@ Run `zig build --help` for the full command list.
 ## What Is Not Implemented
 
 - remaining JSC framework/private and Bun/Home ABI surfaces;
-- 24 dispositioned PR-249 shell/JIT/GC/Wasm cases ([inventory](docs/.data/pr249-reference-inventory.json));
+- 10 optimizing-JIT PR-249 cases remain blocked; 6 JSC-private or incompatible premises have terminal dispositions ([inventory](docs/.data/pr249-reference-inventory.json));
 - automatic/concurrent compaction, a moving nursery, and an optimizing JIT; explicit C/Zig compaction supports quiescent realms and scheduled precise baseline-JIT checkpoints, while age-three parallel minor collection is implemented.
 
 The [release matrix](docs/.data/release-compatibility-matrix.json) tracks [#134](https://github.com/zig-utils/zig-js/issues/134); removal of this section is gated by [#246](https://github.com/zig-utils/zig-js/issues/246).

docs/threads/P6-thread-api.md

@@ -77,9 +77,8 @@ mode is independently shippable and testable; for this engine it is the
    threads-test`) that evaluates each file in an enable_threads Context with
    the shim prelude. Start with `api/thread-basic.js`, `api/lock-basic.js`,
    `api/condition-basic.js`, `atomics/property-load-store.js` and grow.
-   Their `cve/`, `jit/`, `gc-stress/` dirs stay reference-only (target
-   machinery a GIL'd tree-walker structurally lacks); record skips with
-   reasons.
+   Keep growing to the exact inventory; current blockers and terminal premises
+   are verifier-owned rather than directory-wide skips.
 
 ## Order of work (each its own commit)
 

docs/threads/index.md

@@ -41,7 +41,7 @@ rules.
 | `$262.agent` and typed-array `Atomics.wait` / `notify` / `waitAsync` | Implemented in `src/agent.zig` with hooks in the interpreter and VM. | Unit tests and real test262 agent cases. |
 | Structured clone and ArrayBuffer transfer/detach | Implemented in `src/structured_clone.zig`. | Unit tests, workers, and agents. |
 | Embedder `Worker` API | Implemented in `src/worker.zig` with C-API hooks in `src/c_api.zig`. | Worker unit tests, exact host-hook wake coverage, and C-API round trips. |
-| Shared-realm `Thread` API | Implemented in `src/jsthread.zig`, `src/gil.zig`, and `src/context.zig`; parallel by default, GIL opt-out available. | PR-249 green coverage: 235 compatible promoted files out of 259 executable files (233 default `zig build threads-test`, plus 2 `parallel_js`-only witnesses); the [complete inventory](../.data/pr249-reference-inventory.json) checksums all 339 vendored files and assigns dependencies, required hooks, and owners to all 24 reference-only executables. Negative promotion probes, the no-GIL TSan corpus sweep, and fuzzers guard the executable surface. |
+| Shared-realm `Thread` API | Implemented in `src/jsthread.zig`, `src/gil.zig`, and `src/context.zig`; parallel by default, GIL opt-out available. | PR-249 coverage: 243 promoted of 259 executable files (241 default plus 2 `parallel_js`-only); the [inventory](../.data/pr249-reference-inventory.json) checksums all 339 files and distinguishes 10 optimizing-tier blockers from 6 terminal premises. Disposition probes, no-GIL TSan, and fuzzers guard the surface. |
 | Concurrent GC / root safety | GC-managed parallel contexts use thread-safe allocation, write barriers, per-structure locks, precise VM frame roots, and conservative native-stack rooting where applicable. | Unit tests, `parallel_gc` soak, no-GIL corpus TSan, test262-parallel. |
 
 ## Core Rules

docs/threads/limits.md

@@ -4,8 +4,8 @@ The core JavaScript multithreading architecture for issue #1 is implemented:
 isolated agents/workers, shared memory, structured clone, Workers, and
 shared-realm `Thread`s are all present, and shared-realm threads run
 true-parallel by default. The remaining work is production hardening:
-performance, documentation, stress breadth, and promotion of reference-only
-tests as the matching engine features land.
+performance, documentation, stress breadth, and the 10 optimizing-tier PR-249
+cases tracked by #429.
 
 ## Supported Today
 
@@ -708,23 +708,12 @@ Issue #1 remains the umbrella status page.
   race-gated while deeper sanitizer expansion continues. Keep extending it
   toward more teardown ordering, broader cross-realm scheduling, and richer
   cleanup/finalization interleavings.
-- **Reference-only PR-249 files.** Promote only when the engine implements the
-  behavior and the file is reliable under Zig `0.17-dev`, especially the
-  WebAssembly-required files, the incompatible JSC worker-Wasm refusal policy,
-  JIT/shell-hook witnesses, JSC-specific mark-list
-  or the shared-collector `preventCollection` probe, detached-buffer fresh-view
-  reference assumptions, and typed-array race-shape probes.
-  The portable graph/parse/ownership portion of the heap-snapshot case is now
-  covered by `zig build test-private-heap-snapshot`; the JSC-only collector
-  election gate remains explicitly outside that promotion.
-  Run
-  `python3 tools/threads-reference-audit.py --run-probes --expect-current-blockers --probe-timeout 60`
-  to keep the nearest-probe negative baseline honest: it passes only while
-  those files still fail or time out with their documented blocker evidence,
-  and fails when a candidate starts passing or changes failure shape. Use
-  `python3 tools/threads-reference-audit.py --format json` when automation needs
-  the same counts, blocker categories, promotion probes, and expected blocker
-  evidence without scraping human-readable output.
+- **PR-249 tail.** The exact inventory has 243 promoted files, 10
+  optimizing-tier blockers owned by #429, and 6 terminal JSC-private or
+  intentionally incompatible premises. Run
+  `zig build threads-reference-audit threads-reference-probes`; use
+  `python3 tools/threads-reference-audit.py --format json` for automation or
+  `--scan-unpromoted` for a deliberate full tail audit.
 - **TC39 structs tracking.** Keep `proposal-structs` tracking in
   [P8-structs.md](./P8-structs.md) and this issue; do not split it into a
   parallel tracker.

docs/threads/production-readiness.md

@@ -54,13 +54,12 @@ than new correctness architecture.
   the mid-script parallel-GC use-after-free found by the fuzzer.
 - `-Dtest262-parallel-js` runs a broad language-surface slice in GIL-free
   parallel contexts and asserts no new failures versus the baseline.
-- PR-249 coverage contains 235 compatible promoted files out of 259 executable
-  PR-249 files: 233 in normal mode plus 2 `parallel_js`-only witnesses, covered
+- PR-249 coverage contains 243 promoted files out of 259 executable files: 241
+  in normal mode plus 2 `parallel_js`-only witnesses, covered
   by the sharded no-GIL
   ThreadSanitizer corpus gate.
-- The excluded JSC-specific spawned-thread WebAssembly-refusal case conflicts
-  with zig-js's supported worker-Wasm contract; a native unit test covers
-  validation, compilation, instantiation, and execution in both GIL modes.
+- Six JSC-private or intentionally incompatible premises have terminal
+  dispositions; the remaining 10 optimizing-tier cases are owned by #429.
 - The no-GIL `cve/mc-dos-waiter-table-storm.js` focused gate covers property
   `Atomics.waitAsync` tickets removed by a peer while their owning spawned
   thread is closing its stack-local microtask queue; late settlements reroute to
@@ -70,10 +69,9 @@ than new correctness architecture.
   between `asyncJoin` publication and native thread teardown without weakening
   the waiter-root reclamation threshold. Arm labels and failure-only engine
   diagnostics keep future stalls attributable.
-- The reference-only PR-249 tail is checked by
-  `zig build threads-reference-audit`, so unsupported shell hooks, JIT,
-  WebAssembly, and heap-cap/OOM witnesses stay explicit instead of
-  becoming accidental no-op passes.
+- The PR-249 tail is checked by
+  `zig build threads-reference-audit threads-reference-probes`, so blockers and
+  terminal premises cannot become accidental no-op passes.
 
 Remaining: keep widening generated and hand-written stress toward exceptions,
 termination, cleanup, waiters, and cross-thread lifecycle.

docs/threads/testing.md

@@ -13,8 +13,7 @@ zig build threads-test
 zig build threads-test -Dthreads-shard-index=0 -Dthreads-shard-count=4
 zig build threads-test -Dthreads-case=atomics/property-waitasync-timeout.js
 zig build threads-test -Dthreads-parallel-js=true -Dthreads-case=sync/condition-wait-notify.js
-zig build threads-reference-audit
-python3 tools/threads-reference-audit.py --run-probes --expect-current-blockers --probe-timeout 60
+zig build threads-reference-audit threads-reference-probes
 zig build test -Dtsan=true
 zig build test -Dtsan=true -Dtest-filter=parallel_js
 zig build threadfuzz -Dfuzz-iters=20
@@ -161,12 +160,13 @@ world-stopped finish.
 plain command, while a stuck shard prints the active `RUN` case before executing
 it. The required matrix gate is also bounded so a true hang becomes an archived,
 diagnosable failed job instead of an opaque spinner. The current coverage
-contains 235 compatible promoted files out of 259 executable PR-249 files: 233
-in the default `zig build threads-test` allowlist plus 2 `parallel_js`-only
-witnesses. The JSC-specific `api/wasm-refused-sd7.js` case stays reference-only:
-its required refusal conflicts with zig-js intentionally supporting WebAssembly
-inside shared-realm Threads. The native unit suite checks module validation,
-compilation, instantiation, and execution from a Thread in both GIL modes.
+contains 243 promoted files out of 259 executable PR-249 files: 241 in the
+default `zig build threads-test` allowlist plus 2 `parallel_js`-only witnesses.
+Ten optimizing-tier files remain blocked by
+[#429](https://github.com/zig-utils/zig-js/issues/429); six JSC-private or
+intentionally incompatible premises have verifier-enforced terminal
+dispositions. The native unit suite checks WebAssembly validation, compilation,
+instantiation, and execution from a Thread in both GIL modes.
 It covers:
 
 - `api/` and `lifecycle/`: constructor shape, lifecycle, ids, constructor
@@ -528,10 +528,10 @@ baseline arena engine.
 
 `zig build threads-reference-audit` verifies the checked-in [PR-249
 inventory](../.data/pr249-reference-inventory.json): all 339 vendored files are
-checksummed, all 259 executable cases have an explicit state, and every one of
-the 24 reference-only executables names stable dependencies, required hooks,
-and owner issues. The gate rejects file, checksum, allowlist, hook, and
-disposition drift without inflating the green allowlist with no-op passes.
+checksummed and all 259 executable cases are exactly classified as 243
+promoted, 10 blocked, or 6 terminal. The gate rejects file, checksum,
+allowlist, hook, dependency, and disposition drift without inflating the green
+allowlist with no-op passes.
 
 `zig build threads-profile` is not a pass/fail correctness gate. It is the local
 scaling and contention profiler for issue #1. The wall-clock columns compare the
@@ -879,93 +879,45 @@ zig build threadfuzz-bin
 ./zig-out/bin/threadfuzz moduleworkerclose 5 1
 ```
 
-## Remaining Reference-Only Areas
-
-The default corpus is intentionally not a "run every file" mode. Remaining
-PR-249 files stay reference-only for concrete reasons:
-
-- WebAssembly-required CVE files remain out until this engine has the matching
-  WebAssembly construction, compilation, relocation, and grow behavior.
-- `api/wasm-refused-sd7.js` remains out because it requires JSC's v1 policy of
-  throwing `TypeError` for every WebAssembly entry point on a spawned Thread.
-  zig-js deliberately supports that surface; the unit witness `threads:
-  WebAssembly compiles and executes in shared-realm workers` verifies the
-  supported contract under both parallel and serialized/GIL execution.
-- JIT/CVE files that require JSC-specific code artifact hooks, ASAN controls,
-  stop counters, disassembly controls, or retired-artifact machinery remain out
-  until real engine behavior backs those hooks.
-- `cve/mc-df-arraycopy-relabel.js` remains out because it depends on JSC's
-  butterfly verification shell option and a typed-array set length race shape
-  whose current zig-js failure is still the documented `RangeError` blocker.
-  The portable zig-js contract is covered by
-  `TypedArray set snapshots array-like source length` and
-  `parallel_js: TypedArray set snapshots array-like source length under no-GIL grow`:
-  source length is snapshotted once, so growth before the snapshot can reject
-  when it no longer fits the destination, while growth after the snapshot does
-  not extend the copy.
-- `cve/mc-life-creator-thread-dies.js` still depends on a reference-shell
-  detach race that constructs fresh `Int32Array` views after the source
-  `ArrayBuffer` has been transferred. zig-js keeps the normal detached-buffer
-  constructor `TypeError` there instead of weakening `TypedArray` validation.
-  The portable creator-owned storage subset is covered by the unit witness
-  `threads: creator-owned ArrayBuffer storage survives creator exit, GC, resize,
-  and transfer` plus `threadfuzz creatorbuffers`. Together they check
-  child-created `SharedArrayBuffer` / `ArrayBuffer` storage after creator exit,
-  sibling reads, GC pressure, post-creator resize, and post-creator
-  `ArrayBuffer.transfer()`.
-- `dw2-marklistset-storm.js` remains out because it targets JSC's shared-GC
-  mark-list machinery. The portable graph/parse/ownership half of
-  `w16-c1-prevent-collection.js` is promoted by
-  `zig build test-private-heap-snapshot`: both WebKit and V8 forms are parsed
-  across repeated snapshots under Debug, ReleaseSafe, and TSan. The original
-  concurrent `Heap::preventCollection` gate remains reference-only because it
-  is a JSC shared-collector election hook, not a portable snapshot property.
-- Helper/preload files such as `harness.js`, `bench/harness.js`,
-  `scaling/harness.js`, `resources/assert.js`, and
-  `vmstate/resources/workload.js` are not counted as standalone remaining
-  tests.
-
-Promote a reference-only file only when the engine implements the behavior, the
-file passes reliably under Zig `0.17-dev`, and the docs/issue counts are updated
-in the same change.
-
-Run the reference audit after promotion attempts:
+## PR-249 Terminal Inventory
+
+Eight #428 files now run maintained behavior in both serialized and no-GIL
+modes: `congc-t{3,4,5,9,11}`, the weak-global registry race, the buffer-growth
+storm, and the sort/apply marker-pressure storm. `$vm.createGlobalObject()` is
+a real child-realm constructor with fresh intrinsics, VM-shared symbols, and
+collector synchronization.
+
+The 16 unpromoted executables are explicit:
+
+- 10 optimizing-tier cases are blocked by #146/#429.
+- 3 incompatible premises require spawned-thread Wasm refusal, suppress a
+  specification-permitted `TypedArray.set` `RangeError`, or construct a view
+  after transfer detaches its buffer.
+- 3 JSC-private premises require `$vm.sharedHeapTest` or
+  `Heap::preventCollection` internals that zig-js does not pretend to expose.
+
+Six promoted files also record branch-level terminal premises for JSC-private
+diagnostic machinery while their portable stress paths execute normally. Five
+helper/preload files are not standalone tests. The inventory stores every
+reason, required hook, owner issue, and expected default/no-GIL outcome; the
+[exact evidence](../.data/pr249-non-jit-resolution-2026-07-21.json) records the
+28 default/no-GIL release runs plus 8 focused TSan passes.
 
 ```sh
-zig build threads-reference-audit
-python3 tools/threads-reference-audit.py --print-inventory
-python3 tools/threads-reference-audit.py --format markdown
+zig build threads-reference-audit threads-reference-probes
 python3 tools/threads-reference-audit.py --format json
-python3 tools/threads-reference-audit.py --probe-candidates
-python3 tools/threads-reference-audit.py --run-probes --probe-timeout 60
-python3 tools/threads-reference-audit.py --run-probes --expect-current-blockers --probe-timeout 60
-python3 tools/threads-reference-audit.py --scan-reference-only --probe-timeout 20
+python3 tools/threads-reference-audit.py --print-disposition-probes
+python3 tools/threads-reference-audit.py --scan-unpromoted --probe-timeout 60
 ```
 
-`--run-probes` executes the closest reference-only candidates with focused
-`threads-test` commands and returns nonzero on any failure or timeout. A timed
-out or failing probe is not promotion evidence; keep the file reference-only
-until the underlying behavior lands and the focused run passes reliably. Failed
-probes print focused runner evidence before the Zig build tail so the concrete
-JS error, corpus failure, or timeout is visible in one command.
-`--format json` emits the same allowlist counts, reference-only categories,
-closest probe commands, and expected current blocker evidence in a stable
-machine-readable form for CI reports, dashboards, or issue-tracker updates. The
-top-level `promoted_executable`, `executable_total`,
-`reference_only_executable`, and `helper_preload` fields mirror the nested
-sections so simple status scripts can read coverage without understanding the
-full category schema.
-`--expect-current-blockers` flips that maintenance check into a negative gate:
-it succeeds only while the nearest probes still fail or time out with the
-documented blocker evidence. If it starts failing because a probe passes, or
-because the failure shape changed, re-run that single `-Dthreads-case=...`
-probe, promote the file only when the underlying behavior is implemented, and
-update the docs/issue tracker in the same change.
-`--scan-reference-only` is a slower opt-in broom for issue audits: it runs every
-remaining executable reference-only file and fails only if one unexpectedly
-passes. Expected reference-only passes are machine-listed separately for cases
-that are known to skip JSC-only premises or that pass only in serialized mode
-while their no-GIL promotion arm remains too expensive.
+`threads-reference-probes` builds the runner once, then verifies the bounded
+terminal outcomes and their exact error evidence. The slower unpromoted scan is
+for deliberate issue audits, not every local edit.
+
+TSan runs `dw2-marklistset-storm.js` with 2 workers × 18 rounds plus the main
+mutator. Worker seed 0 requests GC at round 16 while the other lanes mutate;
+normal and no-GIL release runs execute the untouched 16 lanes × 120 rounds.
+The exact Debug+TSan CI build completes this profile in 326.285 seconds.
 
 ## Docs Checks