space-data-module-sdk 0.8.23 → 0.8.25

package/docs/isomorphic-pthreads.html

@@ -156,6 +156,27 @@ node --test test/direct-call-constructors.test.js</code></pre></div>
 <h3 id="guest-thread-faults"><a class="anchor" href="#guest-thread-faults" aria-hidden="true">#</a>Guest thread faults</h3>
 <p>A guest thread that traps never finishes the pthread exit protocol. WasmEdge cancels the whole command. In the browser and Node harnesses the joining thread stays blocked inside the guest and cannot run the worker's error event, so the worker itself writes <code>[wasi-thread] guest thread N trapped: ...</code> to stderr (Node) or the console (browser). The call still does not return.</p>
 <p>V8 (Node 20 to 25) checks bulk memory operations, and every access when the WebAssembly trap handler is off (Node on Linux arm64), against a per-instance copy of a shared memory's size. That copy is refreshed asynchronously after another thread grows the memory, so a thread that writes into memory another thread has just grown can trap with &quot;memory access out of bounds&quot;, even after synchronizing with the growing thread. The guest's allocator uses the heap the artifact was linked with and then grows the memory, so a larger imported initial memory does not prevent it.</p>
+<h3 id="sdk-0825-one-pool-protocol-threads-reused-within-an-invoke-spawns-from-any-thread"><a class="anchor" href="#sdk-0825-one-pool-protocol-threads-reused-within-an-invoke-spawns-from-any-thread" aria-hidden="true">#</a>SDK 0.8.25: one pool protocol; threads reused within an invoke; spawns from any thread</h3>
+<p>A guest runs <code>pthread_create</code> through <code>pthread_join</code> without yielding the spawning thread's event loop, often for a whole invoke that spawns wave after wave of threads (conjunction screening spawns a coarse wave, then a refine wave), and any guest thread may call <code>pthread_create</code>. Through 0.8.24:</p>
+<ul>
+<li>a pooled browser worker was sent each thread by message and went back to idle only when the spawner handled its <code>{t:&quot;exit&quot;}</code> message, which could not happen until the invoke returned. One invoke could spawn at most <code>poolSize</code> threads in total, however few ran at once, and a guest that spawned more got <code>EAGAIN</code> (<code>std::thread</code> aborts with <code>unreachable</code>);</li>
+<li>Node started a worker per spawn. Its live-thread count and the join of a finished worker waited for <code>exit</code> events on the blocked event loop, so an explicit <code>poolSize</code> had the same limit, and a guest that started thousands of threads kept thousands of finished workers;</li>
+<li>a spawn from a guest thread other than the main thread always returned -1.</li>
+</ul>
+<p>From 0.8.25 both runtimes share one pool protocol (<code>src/host/wasiThreadPool.js</code>), a <code>SharedArrayBuffer</code> every thread of the process holds: a tid counter, spawn counters, and per worker a slot (<code>PENDING</code>, <code>IDLE</code>, <code>CLAIMED</code>, <code>ASSIGNED</code>, <code>RUNNING</code>, <code>RETIRED</code>, plus the tid and start argument). A pool worker blocks on its slot between threads. A spawner on any thread claims an <code>IDLE</code> slot with a compare-exchange, writes the tid and argument, marks it <code>ASSIGNED</code> and notifies it. The worker runs <code>wasi_thread_start</code>, then marks the slot <code>IDLE</code> and bumps a release generation that waiting spawners sleep on. No step needs an event loop, so:</p>
+<ul>
+<li>a pool bounds how many threads run <strong>at the same time</strong>, not how many one invoke may start (measured: 14,000 threads in one invoke ran on 7 Node workers);</li>
+<li>every guest thread's own <code>wasi.thread-spawn</code> is the pool's, so a guest thread can start threads of its own;</li>
+<li>Node reuses its workers. With no <code>poolSize</code> it grows the pool to at most 1024 workers; with one, to <code>poolSize</code>. A spawn that finds every worker busy waits up to 2 ms for one to come free, then starts a new worker from the spawning thread, which may itself be a pool worker (a Node worker starts without its parent's event loop). Idle workers do not keep the process alive;</li>
+<li>the browser keeps its pre-started warm pool (a browser worker cannot start while its parent is blocked). Its workers now serve their slots and never return to their event loop after the probe.</li>
+</ul>
+<p>A joined thread's worker is still a few instructions from returning when the joiner wakes, so a wave spawned right after a join can find the pool busy for a moment (measured in headless Chromium: 0 to 30 µs). A spawn that finds every thread busy and cannot grow the pool therefore waits on the generation for up to <code>spawnWaitMs</code> (default 250 ms; harness option <code>wasiThreadSpawnWaitMs</code>) before it is declined. After one wait runs out, later spawns from that thread are declined at once until some thread finishes, so a pool held by long-running threads costs one wait, not one per spawn. The wait uses <code>Atomics.wait</code>, which workers and Node allow; where it is not allowed (a window's main thread) a spawn never waits.</p>
+<p><code>spawnReport()</code> counts spawns from every thread (<code>spawned</code>, <code>waited</code>, and <code>pool-exhausted</code> declines); <code>onSpawnDeclined</code> fires for the owning thread's spawns. A Node worker started by a guest thread reports a guest fault on stderr only; <code>onGuestError</code> covers workers the owning thread started and every browser worker.</p>
+<p>A browser worker that answers the probe without the pool protocol (a worker script from an older SDK) still works: the owning thread sends it its threads by <code>{t:&quot;run&quot;}</code> and frees it on <code>{t:&quot;exit&quot;}</code>, as before, and guest threads never spawn onto it. A worker served from the matching SDK gets the fix.</p>
+<p><code>test/wasi-thread-pool-reuse-guest.test.js</code> compiles a guest that spawns 3 waves of <code>poolSize - 1</code> threads (the main thread runs one stripe), 3 waves of <code>poolSize</code> threads, and 3 waves whose threads a non-main guest thread spawns, in one invoke. It checks the output bytes and spawn counts in Node (explicit pool, no pool, and 14,000 threads on at most 16 workers), in headless Chromium, Firefox and WebKit, and across the three parity lanes:</p>
+<div class="codeblock"><div class="codeblock-head">sh</div><pre><code>SPACE_DATA_MODULE_SDK_ENABLE_BROWSER_THREADS=1 \
+SPACE_DATA_MODULE_SDK_ENABLE_TRI_RUNTIME_PARITY=1 \
+node --test test/wasi-thread-pool-reuse-guest.test.js</code></pre></div>
 <p>The old source path <code>src/testing/browserModuleHarness.js</code> remains a pure compatibility re-export. New browser consumers should use the public <code>space-data-module-sdk/host/browser-module</code> entry point.</p>
 <h2 id="4-integrators-the-browser-worker-anchor-required-when-you-bundle"><a class="anchor" href="#4-integrators-the-browser-worker-anchor-required-when-you-bundle" aria-hidden="true">#</a>4. Integrators: the browser worker anchor (REQUIRED when you bundle)</h2>
 <p>The browser leg of the wasi-threads host runs each guest pthread on a pooled module <code>Worker</code>. That worker is a <strong>served asset</strong>, and the SDK cannot guess where your build published it.</p>
@@ -177,7 +198,7 @@ setBrowserWasiThreadWorkerBase(&quot;js/vendor/space-data-module-sdk/src/host/&q
 <div class="table-wrap"><table><thead><tr><th>Source</th><th>Option / API</th></tr></thead><tbody><tr><td>1. Explicit worker file</td><td><code>browserWorkerUrl</code> / <code>wasiThreadWorkerUrl</code></td></tr><tr><td>2. Explicit directory</td><td><code>browserWorkerBaseUrl</code> / <code>wasiThreadWorkerBaseUrl</code></td></tr><tr><td>3. Process-wide base</td><td><code>setBrowserWasiThreadWorkerBase(base)</code></td></tr><tr><td>4. Packaged sibling</td><td><code>new URL(&quot;./wasiThreadBrowserWorker.mjs&quot;, import.meta.url)</code></td></tr></tbody></table></div>
 <p>Rules that make this contract honest:</p>
 <ul>
-<li><strong>The anchor names a DIRECTORY that serves the WHOLE chain.</strong> <code>wasiThreadBrowserWorker.mjs</code> imports <code>./wasiThreadWorkerRuntime.js</code>. Staging the single <code>.mjs</code> next to your bundle does <strong>not</strong> work.</li>
+<li><strong>The anchor names a DIRECTORY that serves the WHOLE chain.</strong> <code>wasiThreadBrowserWorker.mjs</code> imports <code>./wasiThreadWorkerRuntime.js</code> and <code>./wasiThreadPool.js</code>, which import their own siblings. Staging the single <code>.mjs</code> next to your bundle does <strong>not</strong> work.</li>
 <li><strong>A relative base resolves against the document</strong>; absolute URLs pass through unchanged.</li>
 <li><strong>No consumer-side <code>location</code> sniffing.</strong> Forking worker resolution per consumer is not the contract; you already know your build's layout, so state it.</li>
 <li><strong>No fetch-and-retry probe.</strong> Resolution never touches the network: Node never fetches, and browser thread count may not become a function of network timing.</li>
@@ -188,8 +209,8 @@ setBrowserWasiThreadWorkerBase(&quot;js/vendor/space-data-module-sdk/src/host/&q
 <p>The FlatSQL partition store (stack design <code>docs/architecture/flatsql-partition-store.md</code>, §5.5, §5.6, §18 T9, A7, A36, A38, A39) runs one wasi-threads artifact as a writer instance and reader instances, each with guest threads that call FlatSQL's seven <code>env.flatsql_io_*</code> imports. This section is the SDK half: the thread pool, the I/O channel and workers, the Node provider, link shim v2, the worker bundles and the browser capability probe.</p>
 <h3 id="explicit-pool-size-partial-spawns-supervision-hooks"><a class="anchor" href="#explicit-pool-size-partial-spawns-supervision-hooks" aria-hidden="true">#</a>Explicit pool size, partial spawns, supervision hooks</h3>
 <p><code>createWasiThreadSpawn</code> options added in 0.8.22:</p>
-<div class="table-wrap"><table><thead><tr><th>Option</th><th>Effect</th></tr></thead><tbody><tr><td><code>poolSize</code></td><td>Browser: pre-start exactly this many workers, independent of <code>hardwareConcurrency - 1</code> (pools are sized for isolation: writers + lanes). Node: cap on live guest threads. Arming is partial: workers that fail to start are dropped, the rest serve.</td></tr><tr><td><code>extraImports</code></td><td>Per-worker import objects, as structured-cloneable descriptors (below). Factories run once per worker.</td></tr><tr><td><code>instanceId</code>, <code>onGuestError(instanceId, tid, error)</code></td><td>Called when a guest thread traps or its worker dies (A36). A dead pooled worker leaves the pool.</td></tr><tr><td><code>onSpawnDeclined({ reason, poolSize, declined })</code></td><td>Called for every spawn that returns -1. Reasons: <code>pool-exhausted</code>, <code>pool-not-armed</code>, <code>threads-unavailable</code>, <code>pool-empty</code>, <code>worker-create-failed</code>, <code>dispatch-failed</code>, <code>hostcall-channel-missing</code>, <code>terminated</code>.</td></tr><tr><td><code>probeTimeoutMs</code></td><td>Browser warm-pool probe deadline.</td></tr><tr><td><code>browserWorkerType: &quot;classic&quot;</code></td><td>Spawn classic workers, for the blob bundles below.</td></tr></tbody></table></div>
-<p>The returned host adds <code>spawnReport()</code>: <code>{ poolSize, armed, failedToArm, spawned, declined, declinedByReason, lastDeclineReason, active, idle }</code>. The implicit (no <code>poolSize</code>) path keeps its all-or-nothing arming.</p>
+<div class="table-wrap"><table><thead><tr><th>Option</th><th>Effect</th></tr></thead><tbody><tr><td><code>poolSize</code></td><td>Browser: pre-start exactly this many workers, independent of <code>hardwareConcurrency - 1</code> (pools are sized for isolation: writers + lanes). Node: cap on live guest threads (the pool grows to it on demand; without it, to 1024). Arming is partial: workers that fail to start are dropped, the rest serve.</td></tr><tr><td><code>extraImports</code></td><td>Per-worker import objects, as structured-cloneable descriptors (below). Factories run once per worker.</td></tr><tr><td><code>instanceId</code>, <code>onGuestError(instanceId, tid, error)</code></td><td>Called when a guest thread traps or its worker dies (A36). A dead pooled worker leaves the pool. In Node, for workers the owning thread started.</td></tr><tr><td><code>onSpawnDeclined({ reason, poolSize, declined })</code></td><td>Called for every spawn from the owning thread that returns -1. Reasons: <code>pool-exhausted</code>, <code>pool-not-armed</code>, <code>threads-unavailable</code>, <code>pool-empty</code>, <code>worker-create-failed</code>, <code>dispatch-failed</code>, <code>hostcall-channel-missing</code>, <code>terminated</code>.</td></tr><tr><td><code>probeTimeoutMs</code></td><td>Browser warm-pool probe deadline.</td></tr><tr><td><code>spawnWaitMs</code></td><td>How long a spawn that finds every pool thread busy waits for one to finish before it returns -1 (default 250; 0 never waits). Added in 0.8.25; see &quot;one pool protocol&quot; in §3.</td></tr><tr><td><code>browserWorkerType: &quot;classic&quot;</code></td><td>Spawn classic workers, for the blob bundles below.</td></tr></tbody></table></div>
+<p>The returned host adds <code>spawnReport()</code>: <code>{ poolSize, armed, failedToArm, spawned, waited, declined, declinedByReason, lastDeclineReason, active, idle }</code> (Node adds <code>workers</code>). The counts cover spawns from every thread of the process. The implicit (no <code>poolSize</code>) path keeps its all-or-nothing arming.</p>
 <p><code>extraImports</code> entries (the same descriptors work in the engine worker through <code>resolveExtraImports</code>):</p>
 <div class="table-wrap"><table><thead><tr><th>Descriptor</th><th>Imports</th></tr></thead><tbody><tr><td><code>{ provider: &quot;flatsql-io&quot;, instanceId, channels, mirror?, trace? }</code></td><td><code>env.flatsql_io_*</code> over one SAB I/O channel per I/O worker. Each worker claims its own request slot.</td></tr><tr><td><code>{ provider: &quot;flatsql-io-node&quot;, root, table, instanceId }</code></td><td><code>env.flatsql_io_*</code> over synchronous <code>fs</code> (Node workers).</td></tr><tr><td><code>{ moduleUrl, exportName?, config? }</code></td><td>A factory module (module workers and Node only).</td></tr></tbody></table></div>
 <p>A module that bundles this host into an IIFE or a blob: module worker has no usable <code>import.meta.url</code>. <code>DEFAULT_BROWSER_WORKER_URL</code> is then <code>null</code> instead of a module-evaluation <code>TypeError</code>, and such hosts pass <code>browserWorkerUrl</code>.</p>
@@ -216,7 +237,7 @@ setBrowserWasiThreadWorkerBase(&quot;js/vendor/space-data-module-sdk/src/host/&q
 <p>Store lock (A37): with <code>lock: { name }</code> the I/O worker takes that Web Lock before it opens any handle and releases it only after <code>stop()</code> has closed them, so the lock lives exactly as long as the handles. <code>ifAvailable: true</code> fails the start with <code>lockUnavailable</code> instead of waiting; <code>busyRetry</code> retries a handle a previous leader still holds, with backoff. Measured takeover (holder <code>stop()</code> to successor ready): 5 ms Chromium, 52 ms Firefox, 5 ms WebKit. Leadership, follower proxying and heartbeats are the engine's (sdn-js, T10).</p>
 <p>Head mirror (A7): with <code>mirror: { buffer, suffixes: [&quot;/h.fsh&quot;] }</code>, the writer I/O worker copies every write to a matching path into a seqlock mirror in a SharedArrayBuffer (<code>sabIoMirror.js</code>), and reader imports configured with the same mirror serve reads of those paths from it without a round trip.</p>
 <h3 id="node-synchronous-fs-56"><a class="anchor" href="#node-synchronous-fs-56" aria-hidden="true">#</a>Node synchronous fs (§5.6)</h3>
-<p><code>nodeSyncFsIo.js</code>: synchronous <code>fs</code> in each worker over a shared virtual-handle table in a SharedArrayBuffer (<code>createNodeSyncFsIoTable</code>). A handle is <code>(slot &lt;&lt; 8) | gen</code>; each worker opens its own fd for a slot on first use and drops stale fds when the generation moves. Paths are confined below <code>root</code>, including through symlinked parents. <code>sync</code> is <code>fdatasync</code> (libuv issues <code>F_FULLFSYNC</code> on darwin). <code>revokeNodeSyncFsIoInstance</code> follows A23: it sets the revoked flag and waits for the instance's in-flight calls to drain. Fault injection (§19, 22.3a-7) belongs to FlatSQL's Node host (T4); <code>interpose</code> wraps every syscall for it.</p>
+<p><code>nodeSyncFsIo.js</code>: synchronous <code>fs</code> in each worker over a shared virtual-handle table in a SharedArrayBuffer (<code>createNodeSyncFsIoTable</code>). A handle is <code>(slot &lt;&lt; 8) | gen</code>; each worker opens its own fd for a slot on first use and drops stale fds when the generation moves. Paths are confined below <code>root</code>, including through symlinked parents; a filesystem root (<code>root: &quot;/&quot;</code>) reaches every path under it (through 0.8.24 every such path was <code>ACCESS</code>). <code>sync</code> is <code>fdatasync</code> (libuv issues <code>F_FULLFSYNC</code> on darwin). <code>revokeNodeSyncFsIoInstance</code> follows A23: it sets the revoked flag and waits for the instance's in-flight calls to drain. Fault injection (§19, 22.3a-7) belongs to FlatSQL's Node host (T4); <code>interpose</code> wraps every syscall for it.</p>
 <h3 id="link-shim-v2"><a class="anchor" href="#link-shim-v2" aria-hidden="true">#</a>Link shim v2</h3>
 <p><code>FLATSQL_LINK_SHIM_V2_WASM</code> (<code>src/flow/flatsqlLinkShim.js</code>) is a deterministic module that imports the reader instance's SHARED lane memory as <code>flatsql.memory</code> and gives a linked flow the lane mailbox as direct calls. v1 is unchanged (sha256 <code>8d83e69b…</code>), because today's linked flows use it. v2 sha256: <code>67d5b2d9bc2d1b346a14a253a586fd4d08c8056d54eb62701b48000585ed9613</code>.</p>
 <div class="table-wrap"><table><thead><tr><th>Export</th><th>Result</th></tr></thead><tbody><tr><td><code>mb_submit(mailbox, op, req_ptr, req_len)</code></td><td><code>seq</code>, or -1 when the mailbox holds a request</td></tr><tr><td><code>mb_poll(mailbox, seq)</code></td><td>1 when complete</td></tr><tr><td><code>mb_wait(mailbox, seq, poll_ns: i64, max_polls)</code></td><td>the lane's status, or -110 after <code>max_polls</code> bounded waits (<code>max_polls &lt;= 0</code>: no limit)</td></tr><tr><td><code>mb_release(mailbox, seq)</code></td><td>0, or -1 when not complete</td></tr><tr><td><code>mb_cancel(mailbox, seq)</code></td><td>0; the lane polls the cancel word</td></tr><tr><td><code>load32_acquire</code>, <code>store32_release</code>, <code>peek8/32/64</code>, <code>poke8/32</code>, <code>fnv1a64</code>, <code>count_frames</code></td><td>as in v1, over lane memory</td></tr></tbody></table></div>
@@ -248,7 +269,7 @@ const pool = await createWasiThreadSpawn({
 <p><code>runFlatsqlIoConformance(io)</code> (<code>flatsqlIoConformance.js</code>) is one script for every host (22.3a-6): 15 cases covering statuses, short reads, sparse writes, truncation, EXCL/TRUNC/PROBE/UNLINK/UNLINK_IF_UNUSED/CREATE_PARENTS/ DELETE_ON_CLOSE/OPEN_DEFERRED, access modes, confinement and multi-handle visibility. It passes on the Node sync-fs provider, on the channel over the memory backend (blocking and async clients, both doorbells), on the blob bundle run as a standalone script, and on OPFS and memory in Chromium, Firefox and WebKit. Plain <code>UNLINK</code> of an open path is <code>BUSY</code> in the I/O worker (OPFS cannot remove a file with an open sync handle) and succeeds on POSIX hosts; the script does not test it.</p>
 <h3 id="measured-acceptance-18-t9-a7-a38"><a class="anchor" href="#measured-acceptance-18-t9-a7-a38" aria-hidden="true">#</a>Measured acceptance (§18 T9, A7, A38)</h3>
 <p>Owner's Mac Studio (Apple M3 Ultra, 28 cores, macOS 26.3.1), 2026-09-27, headless, final full run of <code>test/opfs-io-worker.browser.test.js</code>. The machine was shared with other lanes (load average 23-33 on 28 cores). Latencies are guest-observed import calls (<code>trace</code>), in microseconds.</p>
-<div class="table-wrap"><table><thead><tr><th>Item</th><th>Chromium 153</th><th>Firefox 155</th><th>WebKit 26.6</th></tr></thead><tbody><tr><td>#1 8 threads, mixed I/O + 200 async opens + 50 unlinks through 1 I/O worker: errors / lost writes</td><td>0 / 0</td><td>0 / 0</td><td>0 / 0</td></tr><tr><td>same run, 4 KiB read p50 / p99</td><td>50 / 2145</td><td>260 / 8180</td><td>60 / 2660</td></tr><tr><td>same run, message doorbell: errors / lost writes</td><td>0 / 0</td><td>0 / 0</td><td>0 / 0</td></tr><tr><td>A7 lane 4 KiB read p99 during 100 x 4 MiB write+flush, same partition</td><td>790 (active file, shared mode)</td><td>120 (sealed segment)</td><td>40 (sealed segment)</td></tr><tr><td>A7 same, other partition</td><td>45</td><td>120</td><td>40</td></tr><tr><td>A7 writer flush p50 / p99 (4 MiB)</td><td>6365 / 28945</td><td>3540 / 27740</td><td>5260 / 70700</td></tr><tr><td>#2 500 ms open, median of 3 runs: other threads' read p99, baseline / during</td><td>85 / 85</td><td>440 / 400</td><td>60 / 60</td></tr><tr><td>#2 longest other-thread read while the open was pending</td><td>1020</td><td>18500</td><td>320</td></tr><tr><td>A38 OPEN_DEFERRED: open returns in / first write waits (ms)</td><td>3.8 / 504</td><td>28.8 / 511</td><td>5.2 / 755</td></tr><tr><td>#3 <code>poolSize=6</code> on <code>hardwareConcurrency=2</code></td><td>6 workers; 7th spawn -1, reported <code>pool-exhausted</code></td><td>same</td><td>same</td></tr><tr><td>#5 link shim v2 (Node 25): 10,000 calls, lost completions</td><td>0 with a notifying lane, 0 with a lane that never notifies, 0 spinning (<code>poll_ns = 0</code>)</td><td></td><td></td></tr></tbody></table></div>
+<div class="table-wrap"><table><thead><tr><th>Item</th><th>Chromium 153</th><th>Firefox 155</th><th>WebKit 26.6</th></tr></thead><tbody><tr><td>#1 8 threads, mixed I/O + 200 async opens + 50 unlinks through 1 I/O worker: errors / lost writes</td><td>0 / 0</td><td>0 / 0</td><td>0 / 0</td></tr><tr><td>same run, 4 KiB read p50 / p99</td><td>50 / 2145</td><td>260 / 8180</td><td>60 / 2660</td></tr><tr><td>same run, message doorbell: errors / lost writes</td><td>0 / 0</td><td>0 / 0</td><td>0 / 0</td></tr><tr><td>A7 lane 4 KiB read p99 during 100 x 4 MiB write+flush, same partition</td><td>790 (active file, shared mode)</td><td>120 (sealed segment)</td><td>40 (sealed segment)</td></tr><tr><td>A7 same, other partition</td><td>45</td><td>120</td><td>40</td></tr><tr><td>A7 writer flush p50 / p99 (4 MiB)</td><td>6365 / 28945</td><td>3540 / 27740</td><td>5260 / 70700</td></tr><tr><td>#2 500 ms open, median of 3 runs: other threads' read p99, baseline / during</td><td>85 / 85</td><td>440 / 400</td><td>60 / 60</td></tr><tr><td>#2 longest other-thread read while the open was pending</td><td>1020</td><td>18500</td><td>320</td></tr><tr><td>A38 OPEN_DEFERRED: open returns in / first write waits (ms)</td><td>3.8 / 504</td><td>28.8 / 511</td><td>5.2 / 755</td></tr><tr><td>#3 <code>poolSize=6</code> on <code>hardwareConcurrency=2</code> (<code>spawnWaitMs: 0</code> since 0.8.25)</td><td>6 workers; 7th spawn -1, reported <code>pool-exhausted</code></td><td>same</td><td>same</td></tr><tr><td>#5 link shim v2 (Node 25): 10,000 calls, lost completions</td><td>0 with a notifying lane, 0 with a lane that never notifies, 0 spinning (<code>poll_ns = 0</code>)</td><td></td><td></td></tr></tbody></table></div>
 <p>Chromium's same-partition A7 p99 varies with host load: 90, 110, 295 and 790 over four runs with the adaptive spin (below), and 125-1165 over four runs before it. The original #1 target (4 KiB read p99 &lt;= 200 µs under the mixed load) is not met through one I/O worker; A7 replaced #1 with the &lt;= 1 ms lane target, which is met. Firefox and WebKit have no shared handle modes, so their lanes read a partition's sealed segment; per §22.4-6 those browsers get no local store.</p>
 <p>Adaptive waits: an idle I/O worker polls its doorbell for 50 µs, and a blocking client polls for its answer for 20 µs, before sleeping (<code>spinMicros</code>), so back-to-back requests skip a thread wake-up. In the Node channel test this took the fast-thread read p50 from 30-39 µs to 11-12 µs.</p>
 <h2 id="tests"><a class="anchor" href="#tests" aria-hidden="true">#</a>Tests</h2>
@@ -259,6 +280,8 @@ const pool = await createWasiThreadSpawn({
 <li><code>test/guest-link-symbol-prefix.test.js</code> — the guest-link prefix is the full injective hex of the pluginId; two previously-colliding ids now get distinct prefixes; fresh prefixes match the committed modules-branch artifacts byte-for-byte; and the compose path treats the guest-link metadata's <code>symbolPrefix</code> / <code>methodSymbols</code> as authoritative (never re-derived), keeping a legacy truncated-prefix artifact compatible.</li>
 </ul>
 <ul>
+<li><code>test/wasi-thread-pool-reuse.test.js</code> — the pool protocol with no message and no event-loop turn: 3 waves of <code>poolSize - 1</code> and of <code>poolSize</code> spawns, a spawn that blocks until a thread finishes on another thread, a spawn from a thread that is not the owner, the <code>spawnWaitMs</code> bound and the no-second-wait rule, an older worker script and a late <code>{t:&quot;exit&quot;}</code>, a dead worker, <code>terminateAll</code>.</li>
+<li><code>test/wasi-thread-pool-reuse-guest.test.js</code> — the real wave guest in Node, headless Chromium, Firefox and WebKit, and the three parity lanes (the browser and parity runs are env-gated, see §3).</li>
 <li><code>test/wasi-thread-pool-size.test.js</code> — explicit <code>poolSize</code> (6 workers on <code>hardwareConcurrency=2</code>, the 7th spawn -1 and reported), partial arming, extraImports delivery, <code>onGuestError</code>, classic workers.</li>
 <li><code>test/sab-io-channel.test.js</code> — the I/O channel under a real wasi-threads guest (<code>test/support/flatsql-io/ioGuestWasm.mjs</code>): 8 threads of mixed I/O in both doorbell modes, a 500 ms open blocking only its caller, OPEN_DEFERRED, revocation, a dead I/O worker, supervisor restart, 256 KiB steps, the head mirror, scratch vs direct transfers, pre-open, and path-hash routing.</li>
 <li><code>test/node-sync-fs-io.test.js</code> — shared handles across workers, stale handles, CREATE_PARENTS, UNLINK_IF_UNUSED, confinement, A23 revocation.</li>
@@ -294,6 +317,7 @@ const pool = await createWasiThreadSpawn({
 <li><a class="depth-3" href="#sdk-0820-command-hosts">SDK 0.8.20 command hosts</a></li>
 <li><a class="depth-3" href="#sdk-0821-constructors-on-the-direct-surface">SDK 0.8.21: constructors on the direct surface</a></li>
 <li><a class="depth-3" href="#guest-thread-faults">Guest thread faults</a></li>
+<li><a class="depth-3" href="#sdk-0825-one-pool-protocol-threads-reused-within-an-invoke-spawns-from-any-thread">SDK 0.8.25: one pool protocol; threads reused within an invoke; spawns from any thread</a></li>
 <li><a class="depth-2" href="#4-integrators-the-browser-worker-anchor-required-when-you-bundle">4. Integrators: the browser worker anchor (REQUIRED when you bundle)</a></li>
 <li><a class="depth-2" href="#5-flatsql-partition-store-host-io-sdk-0822">5. FlatSQL partition store host I/O (SDK 0.8.22)</a></li>
 <li><a class="depth-3" href="#explicit-pool-size-partial-spawns-supervision-hooks">Explicit pool size, partial spawns, supervision hooks</a></li>

package/docs/isomorphic-pthreads.md

@@ -261,6 +261,83 @@ synchronizing with the growing thread. The guest's allocator uses the heap the
 artifact was linked with and then grows the memory, so a larger imported initial
 memory does not prevent it.
 
+### SDK 0.8.25: one pool protocol; threads reused within an invoke; spawns from any thread
+
+A guest runs `pthread_create` through `pthread_join` without yielding the
+spawning thread's event loop, often for a whole invoke that spawns wave after
+wave of threads (conjunction screening spawns a coarse wave, then a refine
+wave), and any guest thread may call `pthread_create`. Through 0.8.24:
+
+- a pooled browser worker was sent each thread by message and went back to
+  idle only when the spawner handled its `{t:"exit"}` message, which could not
+  happen until the invoke returned. One invoke could spawn at most `poolSize`
+  threads in total, however few ran at once, and a guest that spawned more got
+  `EAGAIN` (`std::thread` aborts with `unreachable`);
+- Node started a worker per spawn. Its live-thread count and the join of a
+  finished worker waited for `exit` events on the blocked event loop, so an
+  explicit `poolSize` had the same limit, and a guest that started thousands of
+  threads kept thousands of finished workers;
+- a spawn from a guest thread other than the main thread always returned -1.
+
+From 0.8.25 both runtimes share one pool protocol (`src/host/wasiThreadPool.js`),
+a `SharedArrayBuffer` every thread of the process holds: a tid counter, spawn
+counters, and per worker a slot (`PENDING`, `IDLE`, `CLAIMED`, `ASSIGNED`,
+`RUNNING`, `RETIRED`, plus the tid and start argument). A pool worker blocks on
+its slot between threads. A spawner on any thread claims an `IDLE` slot with a
+compare-exchange, writes the tid and argument, marks it `ASSIGNED` and notifies
+it. The worker runs `wasi_thread_start`, then marks the slot `IDLE` and bumps a
+release generation that waiting spawners sleep on. No step needs an event loop,
+so:
+
+- a pool bounds how many threads run **at the same time**, not how many one
+  invoke may start (measured: 14,000 threads in one invoke ran on 7 Node
+  workers);
+- every guest thread's own `wasi.thread-spawn` is the pool's, so a guest thread
+  can start threads of its own;
+- Node reuses its workers. With no `poolSize` it grows the pool to at most 1024
+  workers; with one, to `poolSize`. A spawn that finds every worker busy waits
+  up to 2 ms for one to come free, then starts a new worker from the spawning
+  thread, which may itself be a pool worker (a Node worker starts without its
+  parent's event loop). Idle workers do not keep the process alive;
+- the browser keeps its pre-started warm pool (a browser worker cannot start
+  while its parent is blocked). Its workers now serve their slots and never
+  return to their event loop after the probe.
+
+A joined thread's worker is still a few instructions from returning when the
+joiner wakes, so a wave spawned right after a join can find the pool busy for a
+moment (measured in headless Chromium: 0 to 30 µs). A spawn that finds every
+thread busy and cannot grow the pool therefore waits on the generation for up
+to `spawnWaitMs` (default 250 ms; harness option `wasiThreadSpawnWaitMs`) before
+it is declined. After one wait runs out, later spawns from that thread are
+declined at once until some thread finishes, so a pool held by long-running
+threads costs one wait, not one per spawn. The wait uses `Atomics.wait`, which
+workers and Node allow; where it is not allowed (a window's main thread) a spawn
+never waits.
+
+`spawnReport()` counts spawns from every thread (`spawned`, `waited`, and
+`pool-exhausted` declines); `onSpawnDeclined` fires for the owning thread's
+spawns. A Node worker started by a guest thread reports a guest fault on stderr
+only; `onGuestError` covers workers the owning thread started and every browser
+worker.
+
+A browser worker that answers the probe without the pool protocol (a worker
+script from an older SDK) still works: the owning thread sends it its threads by
+`{t:"run"}` and frees it on `{t:"exit"}`, as before, and guest threads never
+spawn onto it. A worker served from the matching SDK gets the fix.
+
+`test/wasi-thread-pool-reuse-guest.test.js` compiles a guest that spawns 3
+waves of `poolSize - 1` threads (the main thread runs one stripe), 3 waves of
+`poolSize` threads, and 3 waves whose threads a non-main guest thread spawns, in
+one invoke. It checks the output bytes and spawn counts in Node (explicit pool,
+no pool, and 14,000 threads on at most 16 workers), in headless Chromium,
+Firefox and WebKit, and across the three parity lanes:
+
+```sh
+SPACE_DATA_MODULE_SDK_ENABLE_BROWSER_THREADS=1 \
+SPACE_DATA_MODULE_SDK_ENABLE_TRI_RUNTIME_PARITY=1 \
+node --test test/wasi-thread-pool-reuse-guest.test.js
+```
+
 The old source path `src/testing/browserModuleHarness.js` remains a pure
 compatibility re-export. New browser consumers should use the public
 `space-data-module-sdk/host/browser-module` entry point.
@@ -312,8 +389,9 @@ participates:
 Rules that make this contract honest:
 
 - **The anchor names a DIRECTORY that serves the WHOLE chain.**
-  `wasiThreadBrowserWorker.mjs` imports `./wasiThreadWorkerRuntime.js`. Staging
-  the single `.mjs` next to your bundle does **not** work.
+  `wasiThreadBrowserWorker.mjs` imports `./wasiThreadWorkerRuntime.js` and
+  `./wasiThreadPool.js`, which import their own siblings. Staging the single
+  `.mjs` next to your bundle does **not** work.
 - **A relative base resolves against the document**; absolute URLs pass through
   unchanged.
 - **No consumer-side `location` sniffing.** Forking worker resolution per
@@ -348,15 +426,17 @@ worker bundles and the browser capability probe.
 
 | Option | Effect |
 | --- | --- |
-| `poolSize` | Browser: pre-start exactly this many workers, independent of `hardwareConcurrency - 1` (pools are sized for isolation: writers + lanes). Node: cap on live guest threads. Arming is partial: workers that fail to start are dropped, the rest serve. |
+| `poolSize` | Browser: pre-start exactly this many workers, independent of `hardwareConcurrency - 1` (pools are sized for isolation: writers + lanes). Node: cap on live guest threads (the pool grows to it on demand; without it, to 1024). Arming is partial: workers that fail to start are dropped, the rest serve. |
 | `extraImports` | Per-worker import objects, as structured-cloneable descriptors (below). Factories run once per worker. |
-| `instanceId`, `onGuestError(instanceId, tid, error)` | Called when a guest thread traps or its worker dies (A36). A dead pooled worker leaves the pool. |
-| `onSpawnDeclined({ reason, poolSize, declined })` | Called for every spawn that returns -1. Reasons: `pool-exhausted`, `pool-not-armed`, `threads-unavailable`, `pool-empty`, `worker-create-failed`, `dispatch-failed`, `hostcall-channel-missing`, `terminated`. |
+| `instanceId`, `onGuestError(instanceId, tid, error)` | Called when a guest thread traps or its worker dies (A36). A dead pooled worker leaves the pool. In Node, for workers the owning thread started. |
+| `onSpawnDeclined({ reason, poolSize, declined })` | Called for every spawn from the owning thread that returns -1. Reasons: `pool-exhausted`, `pool-not-armed`, `threads-unavailable`, `pool-empty`, `worker-create-failed`, `dispatch-failed`, `hostcall-channel-missing`, `terminated`. |
 | `probeTimeoutMs` | Browser warm-pool probe deadline. |
+| `spawnWaitMs` | How long a spawn that finds every pool thread busy waits for one to finish before it returns -1 (default 250; 0 never waits). Added in 0.8.25; see "one pool protocol" in §3. |
 | `browserWorkerType: "classic"` | Spawn classic workers, for the blob bundles below. |
 
 The returned host adds `spawnReport()`: `{ poolSize, armed, failedToArm, spawned,
-declined, declinedByReason, lastDeclineReason, active, idle }`. The implicit
+waited, declined, declinedByReason, lastDeclineReason, active, idle }` (Node adds
+`workers`). The counts cover spawns from every thread of the process. The implicit
 (no `poolSize`) path keeps its all-or-nothing arming.
 
 `extraImports` entries (the same descriptors work in the engine worker through
@@ -461,7 +541,8 @@ same mirror serve reads of those paths from it without a round trip.
 table in a SharedArrayBuffer (`createNodeSyncFsIoTable`). A handle is
 `(slot << 8) | gen`; each worker opens its own fd for a slot on first use and
 drops stale fds when the generation moves. Paths are confined below `root`,
-including through symlinked parents. `sync` is `fdatasync` (libuv issues
+including through symlinked parents; a filesystem root (`root: "/"`) reaches
+every path under it (through 0.8.24 every such path was `ACCESS`). `sync` is `fdatasync` (libuv issues
 `F_FULLFSYNC` on darwin). `revokeNodeSyncFsIoInstance` follows A23: it sets the
 revoked flag and waits for the instance's in-flight calls to drain. Fault
 injection (§19, 22.3a-7) belongs to FlatSQL's Node host (T4); `interpose` wraps
@@ -580,7 +661,7 @@ guest-observed import calls (`trace`), in microseconds.
 | #2 500 ms open, median of 3 runs: other threads' read p99, baseline / during | 85 / 85 | 440 / 400 | 60 / 60 |
 | #2 longest other-thread read while the open was pending | 1020 | 18500 | 320 |
 | A38 OPEN_DEFERRED: open returns in / first write waits (ms) | 3.8 / 504 | 28.8 / 511 | 5.2 / 755 |
-| #3 `poolSize=6` on `hardwareConcurrency=2` | 6 workers; 7th spawn -1, reported `pool-exhausted` | same | same |
+| #3 `poolSize=6` on `hardwareConcurrency=2` (`spawnWaitMs: 0` since 0.8.25) | 6 workers; 7th spawn -1, reported `pool-exhausted` | same | same |
 | #5 link shim v2 (Node 25): 10,000 calls, lost completions | 0 with a notifying lane, 0 with a lane that never notifies, 0 spinning (`poll_ns = 0`) | | |
 
 Chromium's same-partition A7 p99 varies with host load: 90, 110, 295 and 790
@@ -623,6 +704,15 @@ the fast-thread read p50 from 30-39 µs to 11-12 µs.
   `symbolPrefix` / `methodSymbols` as authoritative (never re-derived), keeping a
   legacy truncated-prefix artifact compatible.
 
+- `test/wasi-thread-pool-reuse.test.js` — the pool protocol with no message
+  and no event-loop turn: 3 waves of `poolSize - 1` and of `poolSize` spawns, a
+  spawn that blocks until a thread finishes on another thread, a spawn from a
+  thread that is not the owner, the `spawnWaitMs` bound and the no-second-wait
+  rule, an older worker script and a late `{t:"exit"}`, a dead worker,
+  `terminateAll`.
+- `test/wasi-thread-pool-reuse-guest.test.js` — the real wave guest in Node,
+  headless Chromium, Firefox and WebKit, and the three parity lanes (the
+  browser and parity runs are env-gated, see §3).
 - `test/wasi-thread-pool-size.test.js` — explicit `poolSize` (6 workers on
   `hardwareConcurrency=2`, the 7th spawn -1 and reported), partial arming,
   extraImports delivery, `onGuestError`, classic workers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.8.23",
+  "version": "0.8.25",
   "license": "Apache-2.0",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",