sandboxedjs 0.2.11 → 0.2.12

package/docs/agent/STATE.md

@@ -0,0 +1,93 @@
+# Execution state
+
+Keep under roughly 120 lines. Replace stale detail instead of appending.
+
+## Status
+
+- Phase: `complete`
+- Blocker: none
+- User decision required: none outstanding
+
+## Repository layout (restructured)
+
+    src/
+      kernel/ fs/ net/ shell/     the linux-mimicking core
+      node/      module shims, commonjs engine, esm transform
+      python/    cpython, syscalls, pip, resolver, worker, abi, local-builder
+      worker/    pods, sync channel, worker host
+      tools/     esbuild, rolldown, ffmpeg hosts
+      container/ pkg/ agent/ preview/ hosting/
+    docs/        every markdown file: agent/, python/, handoff.md
+    python-runtime/  the Python build pipeline (Makefile, scripts, recipes)
+
+`src/runtime/` is gone. Moves were done with `git mv` and every relative import
+recomputed programmatically. Four references were strings rather than import
+specifiers -- two `dist/` paths whose depth changed, a `/src/runtime/python/`
+check in config.ts, and a test allowlist -- and those caused 79 failures until
+found. There was no dead code to remove: 2 of 130 source files are unreferenced
+and both are ambient `.d.ts` files tsconfig loads implicitly.
+
+## Packages: nothing to pre-build any more
+
+`pip install <anything>` now builds a wheel when the index has none.
+
+- `scripts/auto_recipe.py` writes a recipe from what PyPI and the source
+  already state: identity, verified sdist, and the declared PEP 517 backend.
+  Backends with no adapter are refused by name. Build requirements the lock has
+  never seen are pinned at that moment rather than dropped.
+- `src/python/local-builder.ts` runs the pipeline; `bin/sandboxedjs-build-wheels.mjs`
+  serves the index and builds on request, for browsers that have no compiler.
+- Opt-in, defaulting on only in Node from a checkout. Submit-and-poll, because
+  a connection held open for a minutes-long build reads as an unreachable
+  service.
+- Verified: `pip install ujson` with no recipe -> generated, built, indexed,
+  installed, imported, both locally and through the service.
+
+## Two real defects found and fixed
+
+- The browser's default wheel index was filtered to the wheels whose bytes are
+  inlined in the bundle, so every other built wheel was invisible -- `pip
+  install numpy` reported no usable distribution while numpy sat unreferenced
+  beside the interpreter. The index now lists all built wheels, served from
+  next to the interpreter, with the inlined bytes as an overlay keyed by
+  filename.
+- The post-build index read went through pip's memoizing cache and returned the
+  pre-build copy, so a package was built twice.
+
+## Pre-existing failures, verified not caused by this work
+
+11 tests, reproduced identically in a clean worktree at HEAD: `python-syscalls`
+(5), `cpython` (2), `python-abi/baseline` (3), `python-runtime/asyncio` (1).
+Also: pytest's default output capture fails in the container
+(`OSError: [Errno 8] Bad file descriptor`), so upstream suites need
+`--capture=no`.
+
+## Unverified
+
+`import numpy` in a browser. The embedded browser used for testing blocks
+nested module workers loaded over HTTP, which the runtime needs to start Python
+at all -- `python3 --version` times out there too, and so does a trivial nested
+worker. `pip install numpy` was verified in that browser and returns 0.
+
+## Last evidence
+
+`npx vitest run`: 610 passed, 24 skipped, 12 failed (the 11 above plus one
+PyPI-network flake that passes in isolation). `npm run typecheck`: pass.
+`npm run build`: pass. All 16 wheels byte-identical across rebuilds.
+
+## Compact checkpoint template## Compact checkpoint template## Compact checkpoint template## Compact checkpoint template## Compact checkpoint template## Compact checkpoint template## Compact checkpoint template## Compact checkpoint template## Compact checkpoint template
+
+Replace the sections above after each meaningful loop:
+
+```text
+Phase: <name>
+Current task: <path>
+Last completed task: <path or none>
+Blocker: <one sentence or none>
+User decision required: <yes/no and exact decision>
+Last evidence:
+- <command>: <pass/fail and decisive result>
+Next action: <one concrete action>
+Files changed this loop: <paths>
+```
+

package/docs/agent/tasks/00-verify-inherited-work.md

@@ -0,0 +1,36 @@
+# Task 00: verify inherited generic cross-build work
+
+## Purpose
+
+Establish that the staged setuptools/Cython work is real and reproducible
+before building new layers on it. Do not expand scope in this task.
+
+## Procedure
+
+1. Inspect `git status --short`, `git diff --cached --check`, and the staged
+   diff limited to the files listed in `STATE.md`.
+2. Confirm recipes cannot provide ABI compiler or linker flags.
+3. Confirm generated artifacts are checked for WebAssembly, `dylink`, and the
+   derived `PyInit_*` symbol.
+4. Run the setuptools and Cython fixture builds. Rebuild the wheel index after
+   any wheel output changes.
+5. Run `npm run build` only if runtime bundles required by the acceptance test
+   are absent or older than relevant inputs.
+6. Run `npx vitest run test/python-runtime/extensions.test.ts`.
+7. Run `npm run typecheck`.
+
+## Exit gate
+
+- Staged diff check passes.
+- Setuptools C, Cython, and PyO3 wheels install and execute native behavior in
+  the owned runtime.
+- Pydantic acceptance remains green.
+- No test passed by weakening or skipping an ABI assertion.
+- `STATE.md` contains exact passing commands and points to task 01.
+
+## If it fails
+
+Use `DECISION-TREE.md`. Fix only regressions within the inherited work. After
+three failed evidence-driven attempts on the same class, prepare an escalation
+packet instead of redesigning the ABI.
+

package/docs/agent/tasks/01-authoritative-metadata.md

@@ -0,0 +1,34 @@
+# Task 01: authoritative wheel metadata
+
+## Problem
+
+The current builder synthesizes `METADATA` from recipe fields. That duplicates
+the package's dependency declarations and can create a wheel that installs but
+resolves the wrong environment.
+
+## Deliverable
+
+Generate distribution metadata using the package's build metadata path under
+the controlled build environment. Preserve upstream `Name`, `Version`,
+`Requires-Dist`, extras, Python requirements, entry points, licenses, and other
+install-relevant files. SandboxedJS should add only its wheel tag, generator,
+and `Build-ABI` assertion.
+
+Recipe constraints may explicitly override a target-inapplicable dependency,
+but every override must be visible, justified, and tested.
+
+## Required tests
+
+- A fixture declares a conditional and an extra dependency upstream; neither
+  is copied into the recipe.
+- The resulting wheel and generated `index.json` contain the authoritative
+  requirements.
+- The resolver respects at least one marker/extras case.
+- A disagreement between recipe identity and upstream identity fails loudly.
+- Existing extension runtime tests remain green.
+
+## Exit gate
+
+No generic setuptools fixture needs handwritten `requires` metadata, and the
+index is provably derived from the wheel produced from upstream metadata.
+

package/docs/agent/tasks/02-native-dependencies.md

@@ -0,0 +1,35 @@
+# Task 02: native target dependencies and sysroot
+
+## Problem
+
+Extensions that name libraries or include their headers cannot currently
+declare, build, locate, or link those target dependencies generically.
+
+## Design requirement
+
+Represent native target dependencies separately from Python runtime
+dependencies and host build requirements. Each dependency must identify a
+pinned source, hash, build recipe, output markers, license/provenance, and ABI
+profile. The dynamic profile uses `out/sysroot-dynamic`; incompatible profiles
+must never share object archives.
+
+Add sysroot include and library search paths through generated cross-build
+configuration, not ad hoc recipe flags.
+
+## Reduced acceptance fixture
+
+Before attempting a large external library, create a tiny static target library
+with a header and one function. Build/install it through the dependency system,
+then build a setuptools extension that declares the library normally and calls
+it. The wheel must install and execute the function in the owned runtime.
+
+After the reduced fixture passes, add one small real native library already
+compatible with the project architecture. Do not begin with BLAS or NumPy.
+
+## Exit gate
+
+- Dependency closure is deterministic and cycle/error aware.
+- Rebuilds are skipped only when validated output markers match inputs/profile.
+- Missing dependency and wrong-profile reuse have focused negative tests.
+- Reduced and real-library extensions import and run in owned CPython.
+

package/docs/agent/tasks/03-reproducible-inputs.md

@@ -0,0 +1,27 @@
+# Task 03: reproducible inputs, patches, and provenance
+
+## Deliverable
+
+Unify source archives, build-tool wheels, native dependencies, and package
+patches under verified acquisition. No release artifact may depend on an
+unpinned `pip install setuptools wheel ...` result.
+
+Define a visible patch layout. A patch records package/version, upstream source
+hash, reason, target fact being substituted, and a test. Patch application must
+fail on drift rather than fuzzily succeeding against another source version.
+
+Record enough provenance in build output or adjacent index metadata to answer:
+
+- which source hash produced this wheel;
+- which build tools and target libraries were used;
+- which ABI ID and recipe revision were used;
+- which patches were applied.
+
+## Exit gate
+
+- Offline rebuild succeeds from a populated verified cache.
+- A changed hash, unpinned build tool, or drifting patch fails before compile.
+- Two identical clean builds produce equivalent wheel contents, allowing only
+  explicitly documented archive timestamp normalization until deterministic
+  ZIP output is implemented.
+

package/docs/agent/tasks/04-build-frontends.md

@@ -0,0 +1,27 @@
+# Task 04: build frontend interface
+
+## Purpose
+
+Turn the current kinds into a stable backend interface rather than accumulating
+branches in `build_extension.py`.
+
+## Required interface
+
+Each backend receives verified source, host tools, target configuration,
+declared native dependencies, staging directory, and ABI contract. It returns a
+wheel tree or wheel plus build evidence. It cannot mutate the ABI.
+
+Retain proven setuptools/Cython and PyO3 behavior. Add another frontend only
+when a selected cohort package requires it; likely candidates include PEP 517
+wheel hooks, Meson, or scikit-build/CMake. Do not implement all frontends
+speculatively.
+
+Keep package quirks in patches/recipes and backend mechanics in adapters.
+
+## Exit gate
+
+- Backend selection is explicit and schema-validated.
+- The generic orchestrator has no package-name checks.
+- Existing fixtures pass through the interface.
+- One pyproject-only package runs through a real isolated PEP 517 path.
+

package/docs/agent/tasks/05-registry-integration.md

@@ -0,0 +1,27 @@
+# Task 05: registry and installer integration
+
+## Deliverable
+
+Produce an immutable wheel repository that the existing SandboxedJS `pip`
+resolver can consume. Define schema versioning, atomic publication layout,
+digest verification, ABI partitioning, and dependency metadata.
+
+The browser runtime remains an installer, not a compiler. A missing native
+wheel should return a structured, actionable classification that a host may use
+later to request a build. It must not perform an implicit remote mutation.
+
+## Required tests
+
+- Correct ABI wheel wins over incompatible and host-native candidates.
+- Wrong ABI and wrong digest are refused before installation.
+- A failed graph leaves no partial site-packages state.
+- A newly built test wheel can be indexed, served, installed, imported, and
+  exercised through the ordinary container command.
+- Index publication cannot expose a wheel before its metadata and content are
+  complete.
+
+## Exit gate
+
+A clean consumer needs only a runtime plus index URL/object; no local source
+tree or compiler is required for supported packages.
+

package/docs/agent/tasks/06-package-cohorts.md

@@ -0,0 +1,42 @@
+# Task 06: representative package cohorts
+
+## Purpose
+
+Measure generality without allowing one package to define the architecture.
+
+## Selection method
+
+Choose small packages first, pin exact versions and hashes, and record why each
+adds a new capability. Select at least one from each applicable cohort:
+
+1. pure wheel control case;
+2. setuptools C extension without external target libraries;
+3. generated C/Cython extension;
+4. Rust/PyO3 extension;
+5. extension using a separately built native target library;
+6. package requiring a visible cross-compilation patch;
+7. pyproject/PEP 517 backend not already covered;
+8. scientific-stack stress case, eventually including NumPy.
+
+Do not count existing probes as real-package cohort evidence, but retain them as
+reduced regression tests.
+
+## Compatibility report
+
+For every attempted package, record exactly one status:
+
+- `supported-generic`;
+- `supported-recipe`;
+- `blocked-platform-capability`;
+- `blocked-toolchain`;
+- `not-yet-attempted`.
+
+Record build command, source hash, wheel hash, ABI ID, test behavior, peak size
+or memory when material, and the earliest unsupported assumption on failure.
+
+## Exit gate
+
+At least five independent real packages across four native/build shapes pass
+runtime behavior tests, and failures produce reusable classifications instead
+of package-specific branches.
+

package/docs/agent/tasks/07-build-on-miss-boundary.md

@@ -0,0 +1,31 @@
+# Task 07: external build-on-miss boundary
+
+## Purpose
+
+Specify the seam that can later connect the installer to a trusted build
+service without deploying that service or placing a toolchain in the browser.
+
+## Deliverable
+
+Define versioned request/status/result schemas. A request includes normalized
+requirement, source/index evidence, target ABI ID, policy/recipe revision, and
+an idempotency key. A result includes immutable wheel/index locations, hashes,
+provenance, logs summary, compatibility classification, and terminal state.
+
+States should cover queued, resolving, building host tools, building target
+dependencies, building wheel, testing, published, unsupported, failed, and
+cancelled. Repeated identical requests must converge on one cached artifact.
+
+Security requirements include source allowlists/policy, resource limits,
+network isolation, no untrusted artifact publication before runtime tests,
+digest verification, and auditability.
+
+## Exit gate
+
+- Schemas and a local fake implementation are tested.
+- Installer/host integration can report a buildable miss without automatically
+  triggering external work.
+- Cached success, unsupported result, transient failure, cancellation, and ABI
+  rollover are covered.
+- No cloud service is deployed without explicit user authorization.
+

package/docs/browser-runtime-architecture.md

@@ -0,0 +1,142 @@
+# Browser runtime architecture
+
+The current implementation is a JavaScript/POSIX compatibility runtime with
+CPython compiled to WebAssembly. It is not a Linux kernel or an x86 emulator.
+Keep this distinction in the public API and product claims.
+
+## Existing execution paths
+
+- JavaScript: the module engine and worker pods implement a subset of Node APIs.
+- Python: CPython runs in a process worker and calls the shared virtual kernel.
+- WASI: compiled wasm32-wasi programs use the existing WASI host.
+- Browser preview: a service worker routes HTTP into the virtual network.
+- Native Linux ELF executables and native Node addons: unsupported by these paths.
+
+Browser execution needs suitable worker URLs and, for blocking worker calls,
+SharedArrayBuffer and cross-origin isolation. Static hosting is still needed to
+serve application and runtime assets. It is not a computation backend.
+Python build-on-miss is different: its local builder requires Node/toolchains,
+and its remote builder uses another machine. Prebuilt compatible wheels avoid
+that backend. Not every PyPI package has such a wheel.
+
+## Changes in this pass
+
+The npm installer now overlaps up to six sibling package downloads while keeping
+filesystem mutations ordered. Installers created through `forCwd` share their
+metadata, archive and platform-detail caches within that installer family.
+Transient metadata/archive failures are evicted so retries can recover.
+An extracted package no longer hides an incomplete dependency tree, and optional
+dependencies override duplicate required entries.
+
+Python startup now cleans resources after worker creation or message-send
+failures, and honors cancellation that arrives before or during worker creation.
+
+Caches remain in memory; there is no persistent offline package store, lockfile
+implementation, global hoisting, or measured real-project performance claim.
+Browser bundling and the static import guard are checks of build compatibility,
+not substitutes for interactive browser acceptance testing.
+
+## Native Linux direction (not implemented)
+
+Use a separately loaded browser machine emulator with its own Linux kernel and
+disk image if running unchanged Linux packages is required. Keep it optional:
+ordinary JavaScript/Python projects should not download an entire Linux image.
+Expose the same high-level exec, filesystem transfer and preview operations, but
+report the selected backend and its limitations explicitly. The emulator owns
+its filesystem; transfer files explicitly instead of pretending it shares the
+JavaScript runtime's synchronous in-memory volume.
+
+This requires choosing the CPU architecture, emulator, kernel/root filesystem,
+network bridge and image distribution terms. Native addon compatibility then
+comes from running actual Node inside the guest Linux system. It brings larger
+assets and different startup/performance tradeoffs, and does not promise every
+Linux package will work. No such backend is included in this change.
+
+MIT licensing of this project can avoid a runtime subscription. It does not
+promise free CDN hosting, registry availability or third-party services forever.
+Audit the separate distribution terms of any kernel, disk image and packages
+before redistributing them.
+
+## Extension implementation
+
+The subsequent implementation adds ELF dispatch, external WASI command packs,
+three ordered backend tiers, a translator output cache, and optional local Git
+and embedded SQL adapters. See [Developer tool packs](developer-tool-packs.md)
+for the working APIs and explicit limits. Translation and emulator engines
+remain external and are not included.
+
+## Verified behaviour, and the gaps that remain
+
+A verification harness in the browser test project (`npm run verify`, driving
+real Chrome over the published package) exercises the container boot, Node,
+CPython, an npm install from the registry, both x86-64 ELF tiers, WASI command
+packs, Git, PostgreSQL, an in-container HTTP server, and the frontend
+automation subset. All of it passes in a real browser.
+
+One gap is closed and one remains.
+
+## Outbound HTTP for Python
+
+A browser cannot open a raw TCP socket, so nothing inside the container can
+speak TLS to a real server: outbound traffic has to leave at the HTTP layer,
+through the page's `fetch`. The container therefore serves a loopback HTTP
+endpoint, advertised to the guest as `SBX_HTTP_EGRESS`, which takes an
+*absolute* URL in the request line the way a proxy does and performs the
+transfer on the guest's behalf. `https://` targets are named in that request
+line rather than tunnelled with CONNECT, precisely so the guest never begins a
+TLS handshake it cannot finish; the real request leaves the page over HTTPS.
+
+The startup hook points `urllib.request` and `http.client` at it, so the
+standard library reaches the network without changes to a program. The same
+outbound policy every other exit applies is applied here, and because a refusal
+comes back as a real HTTP response it carries the reason -- a guest is told that
+outbound access is disabled and where to enable it, rather than being handed an
+errno it renders as "connection refused".
+
+Libraries that manage their own TLS rather than going through `http.client` --
+`urllib3`, and so `requests` -- still cannot egress. Their sockets would need to
+carry a TLS handshake this transport cannot terminate. A page's `fetch` is also
+subject to CORS, so a cross-origin target must send the headers that let the
+page read the response; that is a browser rule, not a container policy.
+
+## Blocking syscalls stop every thread
+
+Threads in this runtime are real and run in parallel: a worker thread happily
+burns CPU while the main thread sits in `time.sleep`, which releases the GIL.
+What they cannot do is make a syscall while another thread is inside one.
+
+The cause is in the interpreter image, not in this package. It is built with
+`-sPROXY_TO_PTHREAD` over a JavaScript-backed filesystem, so every syscall made
+on a thread is forwarded to the single thread that owns that filesystem -- the
+generated glue is full of `if (ENVIRONMENT_IS_PTHREAD) return
+proxyToMainThread(...)`. That thread answers a host call by blocking in
+`Atomics.wait`. While it is blocked it cannot service anybody else's proxied
+syscall, so one thread parked in a blocking read freezes every other thread's
+I/O until it returns.
+
+`asyncio.to_thread` is the case that meets this head-on: the loop parks in a
+blocking `select`, and waking it requires the worker thread to make a syscall
+that the parked thread would have to service. Neither completes.
+`to_thread` now raises immediately, naming the limitation, instead of hanging
+until the process is killed. That is a mitigation, not a fix.
+
+Three earlier explanations of this were wrong and are recorded here so the next
+person does not re-derive them: it is not a single control slot in the transport
+(threads do run concurrently), it is not the file-scope statics in `sbx_call`
+(they are downstream of the proxying), and it is not a missing per-thread
+channel on its own (a channel per thread does nothing while the syscalls are
+still funnelled to one thread).
+
+Fixing it is a change to how the runtime image is built, and there are two
+routes, neither small:
+
+- Stack switching. Suspend the wasm stack on a blocking call and return to the
+  event loop, instead of holding the thread in `Atomics.wait`. This is what the
+  Pyodide backend did through `run_sync`, and it is why that backend did not
+  have this problem. It needs JSPI and a transport rewritten around suspension.
+- Unproxied per-thread syscalls. Give each thread its own channel and host
+  server and stop routing syscalls through one thread. This fights the
+  JavaScript filesystem the image is built on, since that filesystem lives on
+  one thread by construction.
+
+Both are runtime-image work measured in days, not a patch plus a rebuild.

package/docs/compatibility-implementation-plan.md

@@ -0,0 +1,98 @@
+# Compatibility implementation plan
+
+## Decisions and evidence
+
+Keep the owned JavaScript runtime and CPython WebAssembly distribution. No
+Nodepod, Pyodide, v86, or replacement VM is required for the first milestones.
+The timeout, missing Node APIs and Python syscall deadlock are separate issues.
+
+The extension acceptance suite serves local wheels using node:http. In the
+restricted development environment listen(127.0.0.1) fails with EPERM. Its
+setup promise previously had no error handler, so setup waited for the hook
+timeout. The test now rejects immediately and teardown handles failed startup.
+With loopback listening permitted, all 12 extension acceptance tests passed in
+34.19 seconds of test execution (37.26 seconds total). This includes C, Cython,
+Rust/PyO3, Meson and Pydantic's compiled core. This establishes the Node-hosted
+fixture path, not browser acceptance or arbitrary PyPI compatibility.
+
+The Python build uses PROXY_TO_PTHREAD. backend.ts sets SBX_SERIAL_HOST_CALLS
+and refuses asyncio.to_thread because proxied blocking syscalls serialize the
+filesystem-owning thread. Removing the refusal alone is not a fix.
+
+## Alternatives
+
+| Approach | Useful for | Main constraint | Decision |
+| --- | --- | --- | --- |
+| Owned JavaScript builtins | Node utility and lifecycle APIs | Must reproduce observable semantics | First choice |
+| Compile source to Wasm | C/C++/Rust extensions and tools | ABI, dependencies and host calls must match | Preferred native-code route |
+| JSPI suspension | Freeing the worker event loop during a blocking host call | Runtime support, suspension boundaries, dynamic modules and pthread interaction | Prototype before adopting |
+| Asyncify | Suspension where JSPI is unavailable | Instrumentation cost and dynamic-module compatibility | Compare as fallback |
+| Per-thread syscall channels | Concurrent Python I/O | Must also remove synchronous proxy bottleneck and preserve fd semantics | Prototype alongside suspension |
+| WasmFS integration | Moving filesystem work away from JS-only ownership | Existing virtual FS needs a backend; not a flag-only change | Assess with thread prototype |
+| Host-native executables | Compatible tools on Node servers | Host OS/architecture, process permissions, unavailable in browsers | Optional explicit host capability |
+| Owned instruction interpreter | Selected binaries without source | ISA, loader, syscalls, linking, signals and threads | Defer until a concrete binary needs it |
+| Binary-to-Wasm translation | Repeated execution of supported binaries | Same ABI needs plus translation correctness and cache invalidation | Later, reuse existing backend interface |
+
+## Ordered implementation milestones
+
+### 1. Make extension acceptance trustworthy
+
+Run the complete local wheel suite with working loopback networking. Separate
+setup, download, install, link, import and execution failures. Fix each observed
+failure with a focused regression. Preserve failures; do not raise timeouts to
+make deadlocks disappear. Repeat in the browser using static fixture hosting.
+
+Exit: ordinary imports execute compiled C/C++/Rust fixtures; missing/incompatible
+artifacts produce actionable failures, and shutdown releases all resources.
+
+### 2. Replace Node stubs in dependency order
+
+Inventory actual package imports. Start with diagnostics_channel and utility
+APIs, followed by worker_threads backed by guest workers, then virtual network
+APIs. Separate virtual TCP from external browser networking. cluster/domain,
+http2, tls, inspector, v8 and vm each need an explicit supported surface rather
+than a catch-all function that pretends to implement them. A JS vm substitute
+must not claim a security boundary it does not provide.
+
+Exit per module: native-Node differential tests, error/cancellation tests,
+cross-guest isolation, and a real package that consumes that API in Node and
+browser hosts. Mark unsupported operations explicitly.
+
+### 3. Prove concurrent Python I/O before rebuilding production
+
+Build a minimal C/pthread fixture against the same Emscripten toolchain. One
+thread blocks on a host read while another writes; add cancellation and a
+timer on the owning JS worker. Compare an asynchronous proxy/suspension path
+with unproxied per-thread host calls. Channels alone cannot repair serialized
+proxy dispatch. Feature-detect JSPI; test fallback behavior explicitly.
+
+Measure idle CPU, wakeup latency, memory, download size and throughput for each
+variant. Select only after the fixture passes. Then rebuild CPython and all
+affected extension fixtures, preserving one shared descriptor authority.
+
+Exit: asyncio.to_thread, run_in_executor, concurrent socket read/write,
+cancellation, subprocess interaction and dynamic extensions work together.
+Remove the current guard only after these pass in supported browsers and Node.
+
+### 4. Expand portable binaries
+
+Use source builds targeting the existing Wasm ABI first. Track toolchain and
+ABI fingerprints in artifacts. If an essential source-unavailable binary
+remains, define one ISA and a static executable subset for an owned interpreter;
+reject unsupported instructions and syscalls deterministically. Bound memory,
+execution and cancellation. Do not start with dynamic Linux package parity.
+
+Exit: selected real binaries have reproducible correctness tests and measured
+startup, memory and throughput. Translation caching follows correctness.
+
+## Sources for the suspension prototypes
+
+- Emscripten pthread proxying and blocking rules:
+  https://emscripten.org/docs/porting/pthreads.html
+- Emscripten Asyncify and JSPI integration:
+  https://emscripten.org/docs/porting/asyncify.html
+- V8 JSPI boundary model:
+  https://v8.dev/blog/jspi-newapi
+
+These sources describe mechanisms; they do not establish that this CPython
+image or its extensions already support them. The prototypes are required.