space-data-module-sdk 0.8.21 → 0.8.22

package/docs/isomorphic-pthreads.html

@@ -184,6 +184,73 @@ setBrowserWasiThreadWorkerBase("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>
@@ -191,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>
@@ -198,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>
 
@@ -217,6 +295,16 @@ setBrowserWasiThreadWorkerBase(&quot;js/vendor/space-data-module-sdk/src/host/&q
 <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

@@ -333,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
@@ -360,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) —
@@ -371,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.21",
+  "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