space-data-module-sdk 0.8.20 → 0.8.22

package/docs/isomorphic-pthreads.html

@@ -146,6 +146,16 @@
 <div class="codeblock"><div class="codeblock-head">sh</div><pre><code>SPACE_DATA_MODULE_SDK_ENABLE_WASMEDGE_PARITY=1 \
 SPACE_DATA_MODULE_SDK_ENABLE_TRI_RUNTIME_PARITY=1 \
 node --test test/wasi-threads-command.test.js</code></pre></div>
+<h3 id="sdk-0821-constructors-on-the-direct-surface"><a class="anchor" href="#sdk-0821-constructors-on-the-direct-surface" aria-hidden="true">#</a>SDK 0.8.21: constructors on the direct surface</h3>
+<p>An artifact built with both the <code>direct</code> and the <code>command</code> surface links the WASI command runtime. Its <code>_start</code> sets up the main thread's pthread descriptor, runs the global constructors, then runs <code>main</code>, which reads stdin. A host that serves the direct surface never enters <code>_start</code>. From 0.8.21 such an artifact also exports <code>__wasm_call_ctors</code>: the same descriptor setup and constructors, without <code>main</code>, at most once per instance. Reactors keep <code>_initialize</code>.</p>
+<p>A direct host runs <code>_initialize</code> if the module exports it, otherwise <code>__wasm_call_ctors</code>, once per instance, before the first direct call. The browser harness does this for <code>surface: &quot;direct&quot;</code>; a command instance only enters <code>_start</code>. The wasi-threads runner serves the direct surface of a command artifact with <code>--sdm-direct</code>, selected by <code>createStandaloneHarness(&quot;wasmedge&quot;, path, { surface: &quot;direct&quot; })</code> and by <code>runParityHarness({ surface: &quot;direct&quot; })</code>. The SDN node uses the same order.</p>
+<p>Artifacts built with 0.8.20 or earlier have no such export. On their direct surface the constructors never run, in every runtime, and a threaded artifact's main thread has no pthread descriptor, so a recursive mutex held by the main thread does not exclude other threads. Rebuild them with 0.8.21.</p>
+<div class="codeblock"><div class="codeblock-head">sh</div><pre><code>SPACE_DATA_MODULE_SDK_ENABLE_WASMEDGE_PARITY=1 \
+SPACE_DATA_MODULE_SDK_ENABLE_TRI_RUNTIME_PARITY=1 \
+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>
 <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>
@@ -174,6 +184,73 @@ setBrowserWasiThreadWorkerBase(&quot;js/vendor/space-data-module-sdk/src/host/&q
 <li><strong>An unreachable worker fails LOUD.</strong> When the pooled path was requested (threads enabled + cross-origin isolated + shared memory) and the worker asset at the resolved anchor never loads, <code>createWasiThreadSpawn</code> <strong>throws</strong> <code>WasiThreadWorkerUnreachableError</code> naming the URL it tried. It does not drop quietly to one thread — a silent sequential fallback is how a deployment defect hid behind a passing gate as a pure performance loss.</li>
 </ul>
 <p>Genuine capability negotiation is unaffected and stays soft: a worker that loads and reports it cannot instantiate the module, a probe timeout, a non-isolated context, non-shared memory, or a 1-core host all still disable threading and let the guest run its proven sequential path (<code>wasi.thread-spawn</code> -&gt; <code>-1</code>).</p>
+<h2 id="5-flatsql-partition-store-host-io-sdk-0822"><a class="anchor" href="#5-flatsql-partition-store-host-io-sdk-0822" aria-hidden="true">#</a>5. FlatSQL partition store host I/O (SDK 0.8.22)</h2>
+<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>
+<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>
+<h3 id="flags-and-statuses"><a class="anchor" href="#flags-and-statuses" aria-hidden="true">#</a>Flags and statuses</h3>
+<p>The partition store adds three open flags and one status. They are flags, so the import set stays at seven. flatsql's <code>flatsql_io.h</code> (T1) must carry the same values.</p>
+<div class="table-wrap"><table><thead><tr><th>Name</th><th>Value</th><th>Meaning</th></tr></thead><tbody><tr><td><code>FLATSQL_IO_CREATE_PARENTS</code></td><td><code>0x0100</code></td><td>mkdir -p; sync each new directory's parent, and the parent of a new file. Best effort on OPFS.</td></tr><tr><td><code>FLATSQL_IO_UNLINK_IF_UNUSED</code></td><td><code>0x0200</code></td><td>Unlink, or <code>BUSY</code> while any handle names the path.</td></tr><tr><td><code>FLATSQL_IO_OPEN_DEFERRED</code></td><td><code>0x0400</code></td><td>Return a handle before the open finishes; the first use waits, or fails with the open's status. Synchronous hosts treat it as a plain open.</td></tr><tr><td><code>FLATSQL_IO_ERR_BUSY</code></td><td><code>-7</code></td><td>Path in use, or its lock held elsewhere.</td></tr></tbody></table></div>
+<p>Every SDK host maps <code>EEXIST</code> to <code>GENERIC</code> (the Go host's mapping), a write on a read-only handle and a read on a write-only handle to <code>IO</code>, and <code>..</code> to <code>ACCESS</code>. OPFS errors map as NotFound -&gt; <code>NOENT</code>, NoModificationAllowed -&gt; <code>BUSY</code>, QuotaExceeded -&gt; <code>NOSPACE</code>; WebKit refuses a second sync handle with InvalidStateError (measured), which maps to <code>BUSY</code> during an open.</p>
+<h3 id="the-sab-io-channel-and-the-io-worker"><a class="anchor" href="#the-sab-io-channel-and-the-io-worker" aria-hidden="true">#</a>The SAB I/O channel and the I/O worker</h3>
+<p><code>sabIoChannel.js</code> extends <code>sabHostcallChannel.js</code> to many guest threads and one server:</p>
+<ul>
+<li>A request ring of slots in one SharedArrayBuffer. Each request owns a slot until its result is read, so a guest never queues behind another guest's request and a slow open blocks only its caller. Idle threads hold no slot, so terminating a pool leaks none; <code>reclaimSabIoSlots(buffer, instanceId)</code> frees the slots of requests that were in flight when an instance's threads died.</li>
+<li>Doorbell: <code>Atomics.waitAsync</code> on a header word. The server publishes the mode; in message mode (<code>doorbell: &quot;message&quot;</code>, or no <code>waitAsync</code>) clients also post on a BroadcastChannel. Completions for non-blocking callers without <code>waitAsync</code> arrive the same way (22.3a-5).</li>
+<li>No timeout, no throw (A36). Blocking waits run in 250 ms slices forever. A supervisor that sees the I/O worker die calls <code>failPendingSabIoRequests</code>, which completes every pending slot with <code>IO</code>.</li>
+<li>Data moves directly between the instance's shared memory and the file when the instance's memory is attached to the I/O worker, else through the slot's data area. Paths are always copied out of shared memory before decoding.</li>
+<li>Revocation (A36): <code>revokeSabIoInstance(buffer, id)</code> resolves after the server has closed the instance's handles; later requests get <code>ACCESS</code> and no byte of the instance is written after it resolves.</li>
+</ul>
+<p><code>opfsIoWorker.mjs</code> runs <code>flatsqlIoServer.js</code> over a backend:</p>
+<ul>
+<li><code>opfs</code>: every open is async (<code>getDirectoryHandle</code>, <code>getFileHandle</code>, <code>createSyncAccessHandle</code>) and awaited on the worker's event loop while the requester waits on its slot. One sync handle per path, shared by all virtual handles. Handles open in <code>&quot;readwrite-unsafe&quot;</code> mode where it exists, so a reader I/O worker can read files a writer I/O worker holds (A7). Views over a SharedArrayBuffer go straight to <code>read</code>/<code>write</code>; a user agent that rejects them gets a private scratch copy.</li>
+<li><code>memory</code>: the dashboard window store (§5.5). Nothing reaches OPFS; <code>reset()</code> drops it; <code>memoryMaxBytes</code> is the per-tab budget (<code>NOSPACE</code>).</li>
+</ul>
+<p>Roles (A7): one writer I/O worker per writer holds the writer's active files; reader I/O workers (one, or two when <code>hardwareConcurrency &gt;= 8</code>) hold sealed files. Reads and writes run in steps of at most 256 KiB with the slots rescanned between steps, so a small read never waits for a whole large write. With several reader I/O workers, <code>createFlatsqlIoImports</code> routes each open by a path hash and every later call to the same worker (the worker index rides in handle bits 24-30).</p>
+<p><code>createFlatsqlIoWorker(options)</code> spawns and supervises one I/O worker: <code>attachMemory</code>, <code>revoke</code>, <code>preopen(paths)</code> (A38: open the registry's active files in parallel at start; later guest opens of those paths return at once), <code>releasePreopen</code>, <code>stats</code>, <code>reset</code>, <code>clear</code>, <code>stop</code>, and <code>onError</code> plus <code>restart: true</code> (A36: pending requests fail with <code>IO</code>, a replacement starts on the same channel with the live memories re-attached; handles do not survive).</p>
+<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>
+<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>
+<p>Mailbox, 64 bytes, 8-aligned, little-endian: <code>+0 state</code> (IDLE 0, SUBMITTED 1, CLAIMED 2, DONE 3, SUBMITTING 4), <code>+4 seq</code>, <code>+8 done_seq</code>, <code>+12 op</code>, <code>+16 req_ptr</code>, <code>+20 req_len</code>, <code>+24 status</code>, <code>+28 resp_ptr</code>, <code>+32 resp_len</code>, <code>+36 doorbell</code>, <code>+40 cancel</code>, <code>+44 flags</code>, <code>+48 generation (u64)</code>. A lane waits (bounded) on the doorbell, CASes SUBMITTED -&gt; CLAIMED, writes the result, stores <code>done_seq = seq</code>, stores DONE and notifies the state word.</p>
+<p><code>mb_wait</code> never waits unboundedly: each <code>memory.atomic.wait32</code> lasts <code>poll_ns</code> and every wake re-reads the mailbox. WasmEdge keeps waiters per executor, so a lane's notify may never reach a flow on another executor; a lost notify then costs one poll interval and never a completion. <code>poll_ns = 0</code> polls without executing a wait (contexts that may not block).</p>
+<h3 id="worker-bundles-a39"><a class="anchor" href="#worker-bundles-a39" aria-hidden="true">#</a>Worker bundles (A39)</h3>
+<p>The dashboard is one HTML file under <code>worker-src 'self' blob:</code>. <code>space-data-module-sdk/host/worker-bundles</code> ships the pool worker and the I/O worker as self-contained classic scripts (esbuild IIFE, built by <code>scripts/build-host-worker-bundles.mjs</code> into <code>src/host/hostWorkerBundleSources.js</code>):</p>
+<div class="codeblock"><div class="codeblock-head">js</div><pre><code>import { hostWorkerBundleUrl } from &quot;space-data-module-sdk/host/worker-bundles&quot;;
+import { createWasiThreadSpawn } from &quot;space-data-module-sdk/host/wasi-threads&quot;;
+import { createFlatsqlIoWorker } from &quot;space-data-module-sdk/host/flatsql-io&quot;;
+
+const writerIo = await createFlatsqlIoWorker({
+  workerUrl: hostWorkerBundleUrl(&quot;flatsql-io&quot;), workerType: &quot;classic&quot;,
+  backend: &quot;opfs&quot;, role: &quot;writer&quot;, rootDirectory: &quot;sdn-store&quot;,
+});
+await writerIo.attachMemory(1, writerMemory);
+const pool = await createWasiThreadSpawn({
+  wasmModule, memory: writerMemory, poolSize: 1 + 2, instanceId: 1,
+  enableBrowserThreads: true,
+  browserWorkerUrl: hostWorkerBundleUrl(&quot;wasi-thread-pool&quot;), browserWorkerType: &quot;classic&quot;,
+  extraImports: [{ provider: &quot;flatsql-io&quot;, instanceId: 1, channels: [writerIo.buffer] }],
+  onGuestError: (instanceId, tid, error) =&gt; supervisor.poison(instanceId, tid, error),
+});</code></pre></div>
+<h3 id="browser-capability-matrix"><a class="anchor" href="#browser-capability-matrix" aria-hidden="true">#</a>Browser capability matrix</h3>
+<p><code>probeBrowserCapabilities()</code> probes the page and a blob worker; <code>flatsqlLocalStoreGate(matrix)</code> is the store gate: cross-origin isolation, shared memory, OPFS sync handles in a worker, <code>Atomics.wait</code> in workers, and shared sync-handle modes (§22.4-6: without them there is no local store). Measured 2026-09-27 on the owner's Mac Studio (Apple M3 Ultra, macOS 26.3.1), headless, Playwright 1.63.0, under the dashboard CSP with COOP/COEP:</p>
+<div class="table-wrap"><table><thead><tr><th></th><th>Chromium 153.0.8010.12</th><th>Firefox 155.0</th><th>WebKit 26.6</th></tr></thead><tbody><tr><td><code>crossOriginIsolated</code>, shared wasm memory</td><td>yes</td><td>yes</td><td>yes</td></tr><tr><td><code>Atomics.waitAsync</code> (page and worker)</td><td>yes</td><td>yes</td><td>yes</td></tr><tr><td>OPFS sync access handle in a worker</td><td>yes</td><td>yes</td><td>yes (persistent profile only)</td></tr><tr><td>Second default handle on one file</td><td>NoModificationAllowedError</td><td>NoModificationAllowedError</td><td>InvalidStateError</td></tr><tr><td>Shared modes (<code>readwrite-unsafe</code> x 2)</td><td>yes</td><td>no (mode ignored)</td><td>no (mode ignored)</td></tr><tr><td>SharedArrayBuffer views in <code>read</code>/<code>write</code></td><td>yes</td><td>yes</td><td>yes</td></tr><tr><td>Wasm shared-memory views in <code>read</code></td><td>yes</td><td>yes</td><td>yes</td></tr><tr><td><code>removeEntry</code> of an open file</td><td>NoModificationAllowedError</td><td>NoModificationAllowedError</td><td>NoModificationAllowedError</td></tr><tr><td>Nested blob workers</td><td>yes</td><td>yes</td><td>yes</td></tr><tr><td><code>performance.now()</code> resolution</td><td>5 µs</td><td>20 µs</td><td>20 µs</td></tr><tr><td>Local-store gate</td><td>supported</td><td>no (shared modes)</td><td>no (shared modes)</td></tr></tbody></table></div>
+<p>WebKit refuses OPFS in Playwright's ephemeral context (<code>UnknownError</code>); the suite uses a persistent profile.</p>
+<h3 id="conformance"><a class="anchor" href="#conformance" aria-hidden="true">#</a>Conformance</h3>
+<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>
+<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>
 <ul>
 <li><code>test/wasi-thread-bundled-consumer-anchor.test.js</code> — the <strong>bundled-consumer guardrail</strong>: the host source is run through esbuild into a directory that does not hold the worker chain (the published-bucket geometry), driven by a Worker mock that resolves URLs on the filesystem the way a browser resolves them against an origin. With no anchor the pooled path must throw <code>WasiThreadWorkerUnreachableError</code> (the silent sequential fallback is a HARD failure); with an explicit base — or the process-wide setter — the same bundle arms its pool and spawns threads. Also pins the precedence table and asserts the resolver neither fetches nor sniffs <code>location</code>.</li>
@@ -181,6 +258,16 @@ setBrowserWasiThreadWorkerBase(&quot;js/vendor/space-data-module-sdk/src/host/&q
 <li><code>test/pthreads-artifact-guardrail.test.js</code> — flag-assembler invariants; a positive compile that emits a validated wasi-threads shared-memory/atomics wasm; a single-thread artifact rejected; a <strong>browser-only Emscripten <code>-pthread</code> artifact rejected</strong> (has shared memory + atomics but no wasi-threads contract); a shared-flag-stripped artifact rejected; and a false-positive guard proving the atomics decoder ignores <code>0xFE</code> immediates.</li>
 <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-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>
+<li><code>test/flatsql-io-conformance.test.js</code> — the conformance script on every Node host.</li>
+<li><code>test/host-worker-bundles.test.js</code> — the bundles equal a fresh build, and the I/O worker bundle passes the conformance script standalone.</li>
+<li><code>test/link-shim-v2.test.js</code> — shim v2 bytes, contract, and 10,000 calls against a stub lane with and without notify.</li>
+<li><code>test/opfs-io-worker.browser.test.js</code> — the real-browser suite above (env-gated):</li>
+</ul>
+<div class="codeblock"><div class="codeblock-head">sh</div><pre><code>SPACE_DATA_MODULE_SDK_ENABLE_BROWSER_IO=1 node --test test/opfs-io-worker.browser.test.js</code></pre></div>
 <h2 id="see-also"><a class="anchor" href="#see-also" aria-hidden="true">#</a>See also</h2>
 <ul>
 <li><a href="./browser-wasmedge-isomorphic.html"><code>docs/browser-wasmedge-isomorphic.md</code></a> — the one-artifact browser + WasmEdge loading profile.</li>
@@ -188,6 +275,7 @@ setBrowserWasiThreadWorkerBase(&quot;js/vendor/space-data-module-sdk/src/host/&q
 <li><code>src/host/wasiThreadHost.js</code> — the isomorphic <code>wasi.thread-spawn</code> host: <code>createWasiThreadSpawn</code>, the browser worker anchor (<code>setBrowserWasiThreadWorkerBase</code>, <code>resolveBrowserWorkerUrl</code>), and <code>WasiThreadWorkerUnreachableError</code>.</li>
 <li><code>src/compiler/pthreadArtifactGuard.js</code> — the flag list + wasm validator.</li>
 <li><code>src/compiler/wasiThreadsToolchain.js</code> — the wasi-threads toolchain resolver.</li>
+<li><code>src/host/sabIoChannel.js</code>, <code>src/host/flatsqlIoServer.js</code>, <code>src/host/opfsIoWorker.mjs</code>, <code>src/host/flatsqlIoWorkers.js</code>, <code>src/host/nodeSyncFsIo.js</code>, <code>src/host/sabIoMirror.js</code>, <code>src/host/flatsqlIoConformance.js</code>, <code>src/host/browserCapabilityProbe.js</code>, <code>src/host/hostWorkerBundles.js</code> — the FlatSQL partition store host I/O (§5).</li>
 <li><code>src/compiler/compileModule.js</code> — <code>ModuleThreadModel</code>, <code>buildCompilerArgs</code>, <code>compileWithWasiThreads</code>, <code>resolveThreadModel</code>, <code>compileModuleFromSource</code>.</li>
 </ul>
 
@@ -204,7 +292,19 @@ setBrowserWasiThreadWorkerBase(&quot;js/vendor/space-data-module-sdk/src/host/&q
 <li><a class="depth-2" href="#guest-link-symbol-namespacing-collision-proof-metadata-authoritative">Guest-link symbol namespacing (collision-proof, metadata-authoritative)</a></li>
 <li><a class="depth-2" href="#3-compile-time-vs-runtime-an-honest-boundary">3. Compile-Time vs. Runtime: an honest boundary</a></li>
 <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-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>
+<li><a class="depth-3" href="#flags-and-statuses">Flags and statuses</a></li>
+<li><a class="depth-3" href="#the-sab-io-channel-and-the-io-worker">The SAB I/O channel and the I/O worker</a></li>
+<li><a class="depth-3" href="#node-synchronous-fs-56">Node synchronous fs (§5.6)</a></li>
+<li><a class="depth-3" href="#link-shim-v2">Link shim v2</a></li>
+<li><a class="depth-3" href="#worker-bundles-a39">Worker bundles (A39)</a></li>
+<li><a class="depth-3" href="#browser-capability-matrix">Browser capability matrix</a></li>
+<li><a class="depth-3" href="#conformance">Conformance</a></li>
+<li><a class="depth-3" href="#measured-acceptance-18-t9-a7-a38">Measured acceptance (§18 T9, A7, A38)</a></li>
 <li><a class="depth-2" href="#tests">Tests</a></li>
 <li><a class="depth-2" href="#see-also">See also</a></li></ul></nav>
     </div>

package/docs/isomorphic-pthreads.md

@@ -216,6 +216,51 @@ SPACE_DATA_MODULE_SDK_ENABLE_TRI_RUNTIME_PARITY=1 \
 node --test test/wasi-threads-command.test.js
 ```
 
+### SDK 0.8.21: constructors on the direct surface
+
+An artifact built with both the `direct` and the `command` surface links the
+WASI command runtime. Its `_start` sets up the main thread's pthread descriptor,
+runs the global constructors, then runs `main`, which reads stdin. A host that
+serves the direct surface never enters `_start`. From 0.8.21 such an artifact
+also exports `__wasm_call_ctors`: the same descriptor setup and constructors,
+without `main`, at most once per instance. Reactors keep `_initialize`.
+
+A direct host runs `_initialize` if the module exports it, otherwise
+`__wasm_call_ctors`, once per instance, before the first direct call. The
+browser harness does this for `surface: "direct"`; a command instance only
+enters `_start`. The wasi-threads runner serves the direct surface of a command
+artifact with `--sdm-direct`, selected by
+`createStandaloneHarness("wasmedge", path, { surface: "direct" })` and by
+`runParityHarness({ surface: "direct" })`. The SDN node uses the same order.
+
+Artifacts built with 0.8.20 or earlier have no such export. On their direct
+surface the constructors never run, in every runtime, and a threaded artifact's
+main thread has no pthread descriptor, so a recursive mutex held by the main
+thread does not exclude other threads. Rebuild them with 0.8.21.
+
+```sh
+SPACE_DATA_MODULE_SDK_ENABLE_WASMEDGE_PARITY=1 \
+SPACE_DATA_MODULE_SDK_ENABLE_TRI_RUNTIME_PARITY=1 \
+node --test test/direct-call-constructors.test.js
+```
+
+### Guest thread faults
+
+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 `[wasi-thread] guest thread N trapped: ...` to stderr
+(Node) or the console (browser). The call still does not return.
+
+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 "memory access out of bounds", 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.
+
 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.
@@ -288,6 +333,269 @@ and reports it cannot instantiate the module, a probe timeout, a non-isolated
 context, non-shared memory, or a 1-core host all still disable threading and let
 the guest run its proven sequential path (`wasi.thread-spawn` -> `-1`).
 
+## 5. FlatSQL partition store host I/O (SDK 0.8.22)
+
+The FlatSQL partition store (stack design `docs/architecture/flatsql-partition-store.md`,
+§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 `env.flatsql_io_*` 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.
+
+### Explicit pool size, partial spawns, supervision hooks
+
+`createWasiThreadSpawn` options added in 0.8.22:
+
+| 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. |
+| `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`. |
+| `probeTimeoutMs` | Browser warm-pool probe deadline. |
+| `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
+(no `poolSize`) path keeps its all-or-nothing arming.
+
+`extraImports` entries (the same descriptors work in the engine worker through
+`resolveExtraImports`):
+
+| Descriptor | Imports |
+| --- | --- |
+| `{ provider: "flatsql-io", instanceId, channels, mirror?, trace? }` | `env.flatsql_io_*` over one SAB I/O channel per I/O worker. Each worker claims its own request slot. |
+| `{ provider: "flatsql-io-node", root, table, instanceId }` | `env.flatsql_io_*` over synchronous `fs` (Node workers). |
+| `{ moduleUrl, exportName?, config? }` | A factory module (module workers and Node only). |
+
+A module that bundles this host into an IIFE or a blob: module worker has no
+usable `import.meta.url`. `DEFAULT_BROWSER_WORKER_URL` is then `null` instead of
+a module-evaluation `TypeError`, and such hosts pass `browserWorkerUrl`.
+
+### Flags and statuses
+
+The partition store adds three open flags and one status. They are flags, so the
+import set stays at seven. flatsql's `flatsql_io.h` (T1) must carry the same
+values.
+
+| Name | Value | Meaning |
+| --- | --- | --- |
+| `FLATSQL_IO_CREATE_PARENTS` | `0x0100` | mkdir -p; sync each new directory's parent, and the parent of a new file. Best effort on OPFS. |
+| `FLATSQL_IO_UNLINK_IF_UNUSED` | `0x0200` | Unlink, or `BUSY` while any handle names the path. |
+| `FLATSQL_IO_OPEN_DEFERRED` | `0x0400` | Return a handle before the open finishes; the first use waits, or fails with the open's status. Synchronous hosts treat it as a plain open. |
+| `FLATSQL_IO_ERR_BUSY` | `-7` | Path in use, or its lock held elsewhere. |
+
+Every SDK host maps `EEXIST` to `GENERIC` (the Go host's mapping), a write on a
+read-only handle and a read on a write-only handle to `IO`, and `..` to
+`ACCESS`. OPFS errors map as NotFound -> `NOENT`, NoModificationAllowed ->
+`BUSY`, QuotaExceeded -> `NOSPACE`; WebKit refuses a second sync handle with
+InvalidStateError (measured), which maps to `BUSY` during an open.
+
+### The SAB I/O channel and the I/O worker
+
+`sabIoChannel.js` extends `sabHostcallChannel.js` to many guest threads and one
+server:
+
+- A request ring of slots in one SharedArrayBuffer. Each request owns a slot
+  until its result is read, so a guest never queues behind another guest's
+  request and a slow open blocks only its caller. Idle threads hold no slot, so
+  terminating a pool leaks none; `reclaimSabIoSlots(buffer, instanceId)` frees
+  the slots of requests that were in flight when an instance's threads died.
+- Doorbell: `Atomics.waitAsync` on a header word. The server publishes the mode;
+  in message mode (`doorbell: "message"`, or no `waitAsync`) clients also post
+  on a BroadcastChannel. Completions for non-blocking callers without
+  `waitAsync` arrive the same way (22.3a-5).
+- No timeout, no throw (A36). Blocking waits run in 250 ms slices forever. A
+  supervisor that sees the I/O worker die calls `failPendingSabIoRequests`,
+  which completes every pending slot with `IO`.
+- Data moves directly between the instance's shared memory and the file when the
+  instance's memory is attached to the I/O worker, else through the slot's data
+  area. Paths are always copied out of shared memory before decoding.
+- Revocation (A36): `revokeSabIoInstance(buffer, id)` resolves after the server
+  has closed the instance's handles; later requests get `ACCESS` and no byte of
+  the instance is written after it resolves.
+
+`opfsIoWorker.mjs` runs `flatsqlIoServer.js` over a backend:
+
+- `opfs`: every open is async (`getDirectoryHandle`, `getFileHandle`,
+  `createSyncAccessHandle`) and awaited on the worker's event loop while the
+  requester waits on its slot. One sync handle per path, shared by all virtual
+  handles. Handles open in `"readwrite-unsafe"` mode where it exists, so a
+  reader I/O worker can read files a writer I/O worker holds (A7). Views over a
+  SharedArrayBuffer go straight to `read`/`write`; a user agent that rejects
+  them gets a private scratch copy.
+- `memory`: the dashboard window store (§5.5). Nothing reaches OPFS;
+  `reset()` drops it; `memoryMaxBytes` is the per-tab budget (`NOSPACE`).
+
+Roles (A7): one writer I/O worker per writer holds the writer's active files;
+reader I/O workers (one, or two when `hardwareConcurrency >= 8`) hold sealed
+files. Reads and writes run in steps of at most 256 KiB with the slots rescanned
+between steps, so a small read never waits for a whole large write. With
+several reader I/O workers, `createFlatsqlIoImports` routes each open by a path
+hash and every later call to the same worker (the worker index rides in handle
+bits 24-30).
+
+`createFlatsqlIoWorker(options)` spawns and supervises one I/O worker:
+`attachMemory`, `revoke`, `preopen(paths)` (A38: open the registry's active
+files in parallel at start; later guest opens of those paths return at once),
+`releasePreopen`, `stats`, `reset`, `clear`, `stop`, and `onError` plus
+`restart: true` (A36: pending requests fail with `IO`, a replacement starts on
+the same channel with the live memories re-attached; handles do not survive).
+
+Store lock (A37): with `lock: { name }` the I/O worker takes that Web Lock
+before it opens any handle and releases it only after `stop()` has closed them,
+so the lock lives exactly as long as the handles. `ifAvailable: true` fails the
+start with `lockUnavailable` instead of waiting; `busyRetry` retries a handle a
+previous leader still holds, with backoff. Measured takeover (holder `stop()` to
+successor ready): 5 ms Chromium, 52 ms Firefox, 5 ms WebKit. Leadership,
+follower proxying and heartbeats are the engine's (sdn-js, T10).
+
+Head mirror (A7): with `mirror: { buffer, suffixes: ["/h.fsh"] }`, the writer
+I/O worker copies every write to a matching path into a seqlock mirror in a
+SharedArrayBuffer (`sabIoMirror.js`), and reader imports configured with the
+same mirror serve reads of those paths from it without a round trip.
+
+### Node synchronous fs (§5.6)
+
+`nodeSyncFsIo.js`: synchronous `fs` in each worker over a shared virtual-handle
+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
+`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
+every syscall for it.
+
+### Link shim v2
+
+`FLATSQL_LINK_SHIM_V2_WASM` (`src/flow/flatsqlLinkShim.js`) is a deterministic
+module that imports the reader instance's SHARED lane memory as
+`flatsql.memory` and gives a linked flow the lane mailbox as direct calls. v1 is
+unchanged (sha256 `8d83e69b…`), because today's linked flows use it. v2 sha256:
+`67d5b2d9bc2d1b346a14a253a586fd4d08c8056d54eb62701b48000585ed9613`.
+
+| Export | Result |
+| --- | --- |
+| `mb_submit(mailbox, op, req_ptr, req_len)` | `seq`, or -1 when the mailbox holds a request |
+| `mb_poll(mailbox, seq)` | 1 when complete |
+| `mb_wait(mailbox, seq, poll_ns: i64, max_polls)` | the lane's status, or -110 after `max_polls` bounded waits (`max_polls <= 0`: no limit) |
+| `mb_release(mailbox, seq)` | 0, or -1 when not complete |
+| `mb_cancel(mailbox, seq)` | 0; the lane polls the cancel word |
+| `load32_acquire`, `store32_release`, `peek8/32/64`, `poke8/32`, `fnv1a64`, `count_frames` | as in v1, over lane memory |
+
+Mailbox, 64 bytes, 8-aligned, little-endian: `+0 state` (IDLE 0, SUBMITTED 1,
+CLAIMED 2, DONE 3, SUBMITTING 4), `+4 seq`, `+8 done_seq`, `+12 op`,
+`+16 req_ptr`, `+20 req_len`, `+24 status`, `+28 resp_ptr`, `+32 resp_len`,
+`+36 doorbell`, `+40 cancel`, `+44 flags`, `+48 generation (u64)`. A lane waits
+(bounded) on the doorbell, CASes SUBMITTED -> CLAIMED, writes the result,
+stores `done_seq = seq`, stores DONE and notifies the state word.
+
+`mb_wait` never waits unboundedly: each `memory.atomic.wait32` lasts `poll_ns`
+and every wake re-reads the mailbox. WasmEdge keeps waiters per executor, so a
+lane's notify may never reach a flow on another executor; a lost notify then
+costs one poll interval and never a completion. `poll_ns = 0` polls without
+executing a wait (contexts that may not block).
+
+### Worker bundles (A39)
+
+The dashboard is one HTML file under `worker-src 'self' blob:`.
+`space-data-module-sdk/host/worker-bundles` ships the pool worker and the I/O
+worker as self-contained classic scripts (esbuild IIFE, built by
+`scripts/build-host-worker-bundles.mjs` into `src/host/hostWorkerBundleSources.js`):
+
+```js
+import { hostWorkerBundleUrl } from "space-data-module-sdk/host/worker-bundles";
+import { createWasiThreadSpawn } from "space-data-module-sdk/host/wasi-threads";
+import { createFlatsqlIoWorker } from "space-data-module-sdk/host/flatsql-io";
+
+const writerIo = await createFlatsqlIoWorker({
+  workerUrl: hostWorkerBundleUrl("flatsql-io"), workerType: "classic",
+  backend: "opfs", role: "writer", rootDirectory: "sdn-store",
+});
+await writerIo.attachMemory(1, writerMemory);
+const pool = await createWasiThreadSpawn({
+  wasmModule, memory: writerMemory, poolSize: 1 + 2, instanceId: 1,
+  enableBrowserThreads: true,
+  browserWorkerUrl: hostWorkerBundleUrl("wasi-thread-pool"), browserWorkerType: "classic",
+  extraImports: [{ provider: "flatsql-io", instanceId: 1, channels: [writerIo.buffer] }],
+  onGuestError: (instanceId, tid, error) => supervisor.poison(instanceId, tid, error),
+});
+```
+
+### Browser capability matrix
+
+`probeBrowserCapabilities()` probes the page and a blob worker;
+`flatsqlLocalStoreGate(matrix)` is the store gate: cross-origin isolation,
+shared memory, OPFS sync handles in a worker, `Atomics.wait` in workers, and
+shared sync-handle modes (§22.4-6: without them there is no local store).
+Measured 2026-09-27 on the owner's Mac Studio (Apple M3 Ultra, macOS 26.3.1),
+headless, Playwright 1.63.0, under the dashboard CSP with COOP/COEP:
+
+| | Chromium 153.0.8010.12 | Firefox 155.0 | WebKit 26.6 |
+| --- | --- | --- | --- |
+| `crossOriginIsolated`, shared wasm memory | yes | yes | yes |
+| `Atomics.waitAsync` (page and worker) | yes | yes | yes |
+| OPFS sync access handle in a worker | yes | yes | yes (persistent profile only) |
+| Second default handle on one file | NoModificationAllowedError | NoModificationAllowedError | InvalidStateError |
+| Shared modes (`readwrite-unsafe` x 2) | yes | no (mode ignored) | no (mode ignored) |
+| SharedArrayBuffer views in `read`/`write` | yes | yes | yes |
+| Wasm shared-memory views in `read` | yes | yes | yes |
+| `removeEntry` of an open file | NoModificationAllowedError | NoModificationAllowedError | NoModificationAllowedError |
+| Nested blob workers | yes | yes | yes |
+| `performance.now()` resolution | 5 µs | 20 µs | 20 µs |
+| Local-store gate | supported | no (shared modes) | no (shared modes) |
+
+WebKit refuses OPFS in Playwright's ephemeral context (`UnknownError`); the suite
+uses a persistent profile.
+
+### Conformance
+
+`runFlatsqlIoConformance(io)` (`flatsqlIoConformance.js`) 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 `UNLINK` of an open path is `BUSY` 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.
+
+### Measured acceptance (§18 T9, A7, A38)
+
+Owner's Mac Studio (Apple M3 Ultra, 28 cores, macOS 26.3.1), 2026-09-27,
+headless, final full run of `test/opfs-io-worker.browser.test.js`. The machine
+was shared with other lanes (load average 23-33 on 28 cores). Latencies are
+guest-observed import calls (`trace`), in microseconds.
+
+| Item | Chromium 153 | Firefox 155 | WebKit 26.6 |
+| --- | --- | --- | --- |
+| #1 8 threads, mixed I/O + 200 async opens + 50 unlinks through 1 I/O worker: errors / lost writes | 0 / 0 | 0 / 0 | 0 / 0 |
+| same run, 4 KiB read p50 / p99 | 50 / 2145 | 260 / 8180 | 60 / 2660 |
+| same run, message doorbell: errors / lost writes | 0 / 0 | 0 / 0 | 0 / 0 |
+| A7 lane 4 KiB read p99 during 100 x 4 MiB write+flush, same partition | 790 (active file, shared mode) | 120 (sealed segment) | 40 (sealed segment) |
+| A7 same, other partition | 45 | 120 | 40 |
+| A7 writer flush p50 / p99 (4 MiB) | 6365 / 28945 | 3540 / 27740 | 5260 / 70700 |
+| #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 |
+| #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
+over four runs with the adaptive spin (below), and 125-1165 over four runs
+before it. The original #1 target (4 KiB read p99 <= 200 µs under the mixed
+load) is not met through one I/O worker; A7 replaced #1 with the <= 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.
+
+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 (`spinMicros`), 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.
+
 ## Tests
 
 - `test/wasi-thread-bundled-consumer-anchor.test.js` — the **bundled-consumer
@@ -315,6 +623,28 @@ the guest run its proven sequential path (`wasi.thread-spawn` -> `-1`).
   `symbolPrefix` / `methodSymbols` as authoritative (never re-derived), keeping a
   legacy truncated-prefix artifact compatible.
 
+- `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.
+- `test/sab-io-channel.test.js` — the I/O channel under a real wasi-threads
+  guest (`test/support/flatsql-io/ioGuestWasm.mjs`): 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.
+- `test/node-sync-fs-io.test.js` — shared handles across workers, stale handles,
+  CREATE_PARENTS, UNLINK_IF_UNUSED, confinement, A23 revocation.
+- `test/flatsql-io-conformance.test.js` — the conformance script on every Node host.
+- `test/host-worker-bundles.test.js` — the bundles equal a fresh build, and the
+  I/O worker bundle passes the conformance script standalone.
+- `test/link-shim-v2.test.js` — shim v2 bytes, contract, and 10,000 calls
+  against a stub lane with and without notify.
+- `test/opfs-io-worker.browser.test.js` — the real-browser suite above
+  (env-gated):
+
+```sh
+SPACE_DATA_MODULE_SDK_ENABLE_BROWSER_IO=1 node --test test/opfs-io-worker.browser.test.js
+```
+
 ## See also
 
 - [`docs/browser-wasmedge-isomorphic.md`](./browser-wasmedge-isomorphic.md) —
@@ -326,5 +656,10 @@ the guest run its proven sequential path (`wasi.thread-spawn` -> `-1`).
   `WasiThreadWorkerUnreachableError`.
 - `src/compiler/pthreadArtifactGuard.js` — the flag list + wasm validator.
 - `src/compiler/wasiThreadsToolchain.js` — the wasi-threads toolchain resolver.
+- `src/host/sabIoChannel.js`, `src/host/flatsqlIoServer.js`,
+  `src/host/opfsIoWorker.mjs`, `src/host/flatsqlIoWorkers.js`,
+  `src/host/nodeSyncFsIo.js`, `src/host/sabIoMirror.js`,
+  `src/host/flatsqlIoConformance.js`, `src/host/browserCapabilityProbe.js`,
+  `src/host/hostWorkerBundles.js` — the FlatSQL partition store host I/O (§5).
 - `src/compiler/compileModule.js` — `ModuleThreadModel`, `buildCompilerArgs`,
   `compileWithWasiThreads`, `resolveThreadModel`, `compileModuleFromSource`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.8.20",
+  "version": "0.8.22",
   "license": "Apache-2.0",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",
@@ -62,6 +62,10 @@
     "./host/runtime-target-gate": "./src/host/runtimeTargetGate.js",
     "./host/node-builtin": "./src/host/nodeBuiltinSpecifier.js",
     "./host/worker-module": "./src/host/workerModuleHarness.js",
+    "./host/wasi-threads": "./src/host/wasiThreadHost.js",
+    "./host/flatsql-io": "./src/host/flatsqlIo.js",
+    "./host/flatsql-io/node": "./src/host/nodeSyncFsIo.js",
+    "./host/worker-bundles": "./src/host/hostWorkerBundles.js",
     "./testing/browser": "./src/testing/browser.js",
     "./testing/module-flatbuffer-stream-pump": {
       "types": "./src/index.d.ts",
@@ -129,7 +133,8 @@
   },
   "devDependencies": {
     "esbuild": "^0.28.0",
-    "express": "^4.21.2"
+    "express": "^4.21.2",
+    "playwright-core": "1.63.0"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/browser.js

@@ -41,7 +41,13 @@ export {
   resolveBrowserWorkerUrl,
   DEFAULT_BROWSER_WORKER_URL,
   WasiThreadWorkerUnreachableError,
+  createWasiThreadSpawn,
+  isWasiThreadsModule,
 } from "./host/wasiThreadHost.js";
+// FlatSQL partition store host I/O (T9): the SAB I/O channel, the I/O worker
+// controller, OPFS and memory backends, and the capability probe. The worker
+// bundles for blob: spawning are on the "./host/worker-bundles" subpath.
+export * from "./host/flatsqlIo.js";
 // The runtime-target gate is reachable so a consumer can catch the refusal by
 // CLASS (`error instanceof RuntimeTargetError`) rather than by matching a
 // message string, and can ask the same question the loaders ask before it