space-data-module-sdk 0.8.3 → 0.8.5

package/docs/gpu-module-abi.md

@@ -0,0 +1,193 @@
+# GPU Module ABI
+
+This document defines the SDK-level standard for modules that can use GPU
+compute acceleration while remaining portable across browser and WasmEdge
+module runtimes.
+
+## Scope
+
+The standard covers:
+
+- the manifest capability used by module authors
+- the host-owned async dispatch boundary used by browsers and native hosts
+- the C/C++ layout header shared by module code, browser adapters, and native
+  Dawn-backed hosts
+- the artifact layout for portable CPU fallback plus optional GPU adapters
+
+It does not add a new SDS FlatBuffer schema or a new `space_data_module_host`
+sync import. GPU dispatch is asynchronous in browser WebGPU and must stay
+outside the current sync guest hostcall bridge.
+
+## Capability
+
+GPU-capable modules declare the coarse capability id:
+
+```json
+{
+  "capability": "gpu_compute",
+  "scope": "webgpu.v1",
+  "required": false,
+  "description": "Optional WebGPU/Dawn compute acceleration."
+}
+```
+
+Use `required: false` unless the module has no correct CPU path. A missing GPU
+adapter must degrade to the module's CPU implementation, not to an incomplete
+result.
+
+The `gpu_compute` id is part of the SDK recommended capability vocabulary. The
+typed PLG `HOST_CAPABILITIES` enum cannot carry a dedicated GPU enum value
+until the canonical standards schema adds one. Until that SDS change lands,
+module manifests should use the string/object capability form above and avoid
+claiming a typed PLG host capability enum for GPU.
+
+## Artifact Layout
+
+The canonical portable artifact remains:
+
+```text
+dist/isomorphic/module.wasm
+```
+
+That artifact must be valid without GPU access. Optional GPU adapters belong
+outside the shared guest binary:
+
+```text
+dist/browser/module.js
+dist/browser/module.wasm
+dist/wasmedge/gpu-host.{so,dylib,dll}
+```
+
+The browser adapter owns the browser `GPUDevice`. The WasmEdge host extension
+owns the native Dawn instance/device. The guest module owns correctness,
+fallback, exact refinement, and final result validation.
+
+## ABI Layers
+
+### 1. Data Layout ABI
+
+The reusable C/C++ header is:
+
+```text
+templates/gpu-module/include/space_data_gpu_abi.h
+```
+
+It defines:
+
+- `SDN_GPU_ABI_VERSION`
+- the `gpu_compute` capability id and `webgpu.v1` scope
+- status codes
+- backend and buffer role enums
+- split `f64` helpers using high/low `f32`
+- packed dispatch/result descriptors
+
+All multi-byte fields are little-endian in serialized buffers. Structs in the
+header are fixed-width and intentionally avoid owning pointers. Pointers are
+runtime-local implementation details and must not appear in durable manifests,
+publication metadata, or cross-process descriptors.
+
+### 2. Host Dispatch ABI
+
+The canonical operation is:
+
+```text
+gpu_compute.dispatch.v1
+```
+
+The host adapter receives:
+
+- an ABI version
+- a stable kernel id
+- storage/uniform buffer descriptors
+- little-endian input bytes
+- requested workgroup counts
+- declared output buffer sizes
+
+The host adapter returns:
+
+- a status code
+- backend metadata (`browser-webgpu`, `dawn-native`, or `cpu-fallback`)
+- output buffer bytes
+- optional counters such as candidates emitted, overflow count, and elapsed
+  device time
+
+Browser and native hosts may expose this through their existing async
+capability adapter registries. A shared browser/WasmEdge guest must not depend
+on raw asynchronous wasm imports for this operation.
+
+### 3. Module-Level API
+
+Module methods should keep the public invoke contract domain-specific. For
+example, a conjunction assessment module should expose conjunction assessment
+request/response ports, not generic WebGPU command buffers.
+
+The GPU dispatch boundary is an implementation detail between the host runtime
+and the module/adapter pair. Hosts may precompute a GPU broadphase and pass
+coarse hits into the guest, or they may let a browser-specific adapter call the
+guest's exact refinement entry points after dispatch.
+
+## Browser Backend
+
+Browser adapters use WebGPU through browser APIs or Emscripten's WebGPU/Dawn
+surface. They must:
+
+- request and cache the `GPUAdapter` and `GPUDevice`
+- validate device limits before accepting a dispatch
+- compile WGSL from a module-owned or SDK-owned source string
+- copy results back through mapped buffers or equivalent browser APIs
+- return a CPU fallback status when WebGPU is unavailable
+
+Browser WebGPU setup and buffer mapping are asynchronous. Do not model them as
+sync `space_data_module_host` calls.
+
+## WasmEdge Backend
+
+WasmEdge deployments that need GPU acceleration should use a native host
+extension linked against Dawn. The native host implements the same
+`gpu_compute.dispatch.v1` operation and uses the same C/C++ layout header.
+
+The shared module artifact should still be loadable without that extension. A
+pure `["wasmedge"]` artifact may choose a higher-capability native host profile,
+but a `["browser", "wasmedge"]` artifact must retain the portable fallback
+contract documented in `docs/browser-wasmedge-isomorphic.md`.
+
+## Numerical Rules
+
+GPU kernels that need double-like position precision should use split high/low
+`f32` values:
+
+```c
+SdnGpuSplitF64 x = sdn_gpu_split_f64(x_km);
+```
+
+For orbital screening, store position components in kilometers unless a module
+contract states otherwise. The high component is the nearest `f32`; the low
+component is the residual:
+
+```text
+hi = f32(value)
+lo = f32(value - f64(hi))
+```
+
+GPU broadphase kernels must be conservative. They may emit extra candidates,
+but they must not drop candidates that the CPU exact path would refine. Exact
+TCA, probability, and final acceptance logic remain in the CPU double-precision
+module path unless a module ships a separately validated exact GPU algorithm.
+
+## Template
+
+Start new GPU-capable modules from:
+
+```text
+templates/gpu-module/
+```
+
+The template contains:
+
+- `include/space_data_gpu_abi.h`: reusable C/C++ ABI layout header
+- `manifest.json`: manifest fragment showing `gpu_compute`
+- `README.md`: integration notes for browser WebGPU and WasmEdge/Dawn hosts
+
+Use the template as a layout and ABI starting point. Real module repos should
+still define domain-specific FlatBuffer request/response schemas and must keep
+their canonical compiled artifact at `dist/isomorphic/module.wasm`.

package/docs/index.html

@@ -0,0 +1,125 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="Space Data Module SDK documentation for building, validating, signing, and deploying WebAssembly modules on the Space Data Network." />
+    <title>Space Data Module SDK</title>
+    <link rel="stylesheet" href="./styles.css" />
+    <!-- SDN_CONSUMER_ASSETS_START -->
+<link rel="stylesheet" href="https://static.spacedatanetwork.org/assets/hd-wallet-ui/2.0.28/sdn-wallet-public-client.c3f68d1cfd88478f10d836a5e829d1dfc6a10157972cf0f7d4d319d0636f2cc4.css" integrity="sha384-fICuhN4I9xqOK1F5vGGzl26opuO+xQIvTZXMSV76lWTBiQ6AfzztMGLLDw8yRT8i" crossorigin="anonymous">
+<script defer src="https://static.spacedatanetwork.org/assets/hd-wallet-ui/2.0.28/sdn-wallet-public-client.f611e7e151a3b5c38384272f8894a4c6634f0a29bf925b0e02e0e27f8db0bfff.js" integrity="sha384-R+QqsKoWJIS7iWrtPmgJ49DVnb1hSGjZokupbLInJd1PLp8RwQhtF/hnaerc33ci" crossorigin="anonymous" data-sdn-wallet-public-client="v1"></script>
+<script defer src="https://static.spacedatanetwork.org/assets/sdn-stack-nav/1.0.0/sdn-stack-nav.52fde607eee38ffa116188201f50258ed50bd18c9f06c1af9678f763147a8fe5.js" integrity="sha384-dgeojhJ8vTszHXIbv7O7nZcEzqD10oUYYJjBmPrV7+kLQEUlXLQD4ek5Q7HOFiO5" crossorigin="anonymous" data-nav-style-url="https://static.spacedatanetwork.org/assets/sdn-stack-nav/1.0.0/sdn-stack-nav.36a36359ce18322185e9ff179f88175bab67d5ad84a14d9c08a54f2ff27267e7.css" data-nav-style-integrity="sha384-c4M8Fg+kYaeOYYtJVr7jJsde24IhSWkWaRyAOHEZU9jozhRck089aw+mnHwxymds" data-wallet-client-url="https://static.spacedatanetwork.org/assets/hd-wallet-ui/2.0.28/sdn-wallet-public-client.f611e7e151a3b5c38384272f8894a4c6634f0a29bf925b0e02e0e27f8db0bfff.js" data-wallet-client-integrity="sha384-R+QqsKoWJIS7iWrtPmgJ49DVnb1hSGjZokupbLInJd1PLp8RwQhtF/hnaerc33ci" data-wallet-style-url="https://static.spacedatanetwork.org/assets/hd-wallet-ui/2.0.28/sdn-wallet-public-client.c3f68d1cfd88478f10d836a5e829d1dfc6a10157972cf0f7d4d319d0636f2cc4.css" data-wallet-style-integrity="sha384-fICuhN4I9xqOK1F5vGGzl26opuO+xQIvTZXMSV76lWTBiQ6AfzztMGLLDw8yRT8i" data-wallet-client-id="sdn-module-sdk-pages-v1" data-wallet-callback-uri="https://digitalarsenal.github.io/space-data-module-sdk/wallet-callback.html" data-wallet-registry-sha256="e1ce6fe903c9700484a8a87d96581c8cad97063dabf63030b4518a31a3bdaa93"></script>
+<!-- SDN_CONSUMER_ASSETS_END -->
+  </head>
+  <body>
+    <sdn-stack-nav active="module-sdk"></sdn-stack-nav>
+    <header class="site-header">
+      <a class="site-brand" href="./">Space Data Module SDK</a>
+      <a class="stack-button" href="#stack">Stack</a>
+    </header>
+
+    <main>
+      <section class="hero" aria-labelledby="page-title">
+        <div class="hero-copy">
+          <p class="eyebrow">Space Data Network</p>
+          <h1 id="page-title">Space Data Module SDK</h1>
+          <p class="lede">
+            Build portable WebAssembly modules with embedded FlatBuffer manifests,
+            standards-aware validation, browser and WasmEdge harnesses, and signed
+            delivery records for SDN hosts.
+          </p>
+          <div class="actions" aria-label="Primary links">
+            <a class="button primary" href="https://github.com/DigitalArsenal/space-data-module-sdk">GitHub</a>
+            <a class="button" href="./module-publication-standard.md">Publication Standard</a>
+            <a class="button" href="./testing-harness.md">Testing Harness</a>
+          </div>
+        </div>
+        <figure class="architecture">
+          <img src="./architecture.svg" alt="Module architecture overview" />
+        </figure>
+      </section>
+
+      <section class="quick-grid" aria-label="SDK capabilities">
+        <article>
+          <h2>Author</h2>
+          <p>Start from the examples and declare module methods, ports, runtime targets, and standards references in one manifest.</p>
+        </article>
+        <article>
+          <h2>Validate</h2>
+          <p>Check manifests and wasm artifacts against the SDK contract, exported ABI symbols, and canonical SDS type names.</p>
+        </article>
+        <article>
+          <h2>Package</h2>
+          <p>Append REC and MBL bundle metadata, attach publication records, and keep module artifacts single-file deployable.</p>
+        </article>
+        <article>
+          <h2>Run</h2>
+          <p>Exercise the same module through browser, Node, process, and WasmEdge harnesses before publishing to SDN hosts.</p>
+        </article>
+      </section>
+
+      <section class="docs-list" aria-labelledby="docs-title">
+        <div class="section-head">
+          <p class="eyebrow">Reference</p>
+          <h2 id="docs-title">Core Documents</h2>
+        </div>
+        <div class="link-list">
+          <a href="./module-publication-standard.md">
+            <span>Module Publication Standard</span>
+            <small>Manifest, REC, MBL, PNM, and ENC publication contract.</small>
+          </a>
+          <a href="./flatsql-streaming-standard.md">
+            <span>FlatSQL Streaming Standard</span>
+            <small>Binary FlatBuffer stream transport and runtime-host storage.</small>
+          </a>
+          <a href="./browser-wasmedge-isomorphic.md">
+            <span>Browser and WasmEdge Isomorphic Runtime</span>
+            <small>One module artifact across browser and server-side execution.</small>
+          </a>
+          <a href="./testing-harness.md">
+            <span>Testing Harness</span>
+            <small>Process, browser, WasmEdge, and module stream test entrypoints.</small>
+          </a>
+          <a href="./protocol-installation.md">
+            <span>Protocol Installation</span>
+            <small>Protocol identity, deployment routing, and installation metadata.</small>
+          </a>
+          <a href="./secrets-capability.md">
+            <span>Credential Lanes</span>
+            <small>Operator-defined secrets lanes, per-lane approval, and plaintext handling rules.</small>
+          </a>
+        </div>
+      </section>
+
+      <section id="stack" class="stack-list" aria-labelledby="stack-title">
+        <div class="section-head">
+          <p class="eyebrow">SDN Stack</p>
+          <h2 id="stack-title">Connected Sites</h2>
+        </div>
+        <div class="link-list">
+          <a href="https://spacedatastandards.org/">
+            <span>Standards</span>
+            <small>Canonical schemas, record contracts, and generated bindings.</small>
+          </a>
+          <a href="https://digitalarsenal.github.io/flatbuffers/">
+            <span>FlatBuffers</span>
+            <small>Binary encoding, schema tooling, and runtime documentation.</small>
+          </a>
+          <a href="https://digitalarsenal.github.io/flatsql/">
+            <span>FlatSQL</span>
+            <small>SQL-style queries over FlatBuffer-backed datasets and streams.</small>
+          </a>
+          <a href="https://spacedatanetwork.org/">
+            <span>SDN</span>
+            <small>Distributed publication, discovery, delivery, and marketplace infrastructure.</small>
+          </a>
+          <a href="https://digitalarsenal.github.io/space-data-module-sdk/" class="active">
+            <span>Module SDK</span>
+            <small>WASM module packaging, validation, and host compatibility tooling.</small>
+          </a>
+        </div>
+      </section>
+    </main>
+  </body>
+</html>

package/docs/isomorphic-pthreads.md

@@ -0,0 +1,188 @@
+# Isomorphic Pthreads: Enforced, Validated wasi-threads Artifacts
+
+`space-data-module-sdk` is the **enforced source of truth** for isomorphic
+pthreads module artifacts. When a module is compiled for the pthreads thread
+model, the SDK guarantees two things that used to be optional and unchecked:
+
+1. The final link **cannot omit** the thread-enabling flags, and it targets the
+   **wasi-threads** toolchain (not Emscripten's browser Web-Worker model).
+2. The emitted `.wasm` is **parsed and validated** to be a real wasi-threads
+   artifact. A module that claims pthreads but does not emit the wasi-threads
+   contract **fails the compile** — it does not ship.
+
+The goal is one compiled `.wasm` that threads in **both** the browser (via
+`SharedArrayBuffer` + a wasi-threads Worker shim) and WasmEdge (via wasi-threads),
+mirroring the `analysis/conjunction-assessment` module's `std::thread` workers.
+
+## Why wasi-threads and NOT Emscripten `-pthread`
+
+This is the load-bearing decision. Emscripten's `-pthread` — even with
+`-s STANDALONE_WASM=1` — emits the **browser-only** thread model:
+
+- it imports `env.__pthread_create_js` and `env._emscripten_*` mailbox /
+  `postMessage` hooks (a JS Web Worker protocol), and
+- it has **no** wasi thread-spawn contract.
+
+That artifact **cannot spawn threads under WasmEdge** — there is no JS runtime to
+satisfy those imports; instantiation fails on the unknown imports, and stubbing
+them would require host-side thread orchestration (which is separately
+forbidden). It has shared memory and atomics, but those are **necessary, not
+sufficient**: a browser-only Emscripten build has them too.
+
+WasmEdge's actual thread mechanism is **wasi-threads**: the guest imports
+`wasi.thread-spawn` and exports `wasi_thread_start` over an imported shared
+memory. Compiling with `clang --target=wasm32-wasip1-threads -pthread`
+(wasi-sdk / wasi-libc + wasi-runtimes threads sysroot) produces exactly that
+contract, which threads under WasmEdge and loads in the browser through a
+wasi-threads shim.
+
+`-mthreads` is likewise never used — it is a MinGW driver flag, invalid for the
+wasm target.
+
+## Thread Models
+
+`ModuleThreadModel` (see `src/compiler/compileModule.js`):
+
+- `single-thread` — portable, no shared memory, no atomics. Default for
+  `runtimeTargets: ["browser"]` and `["browser", "wasmedge"]`. Built with
+  Emscripten (emception, in-process).
+- `emscripten-pthreads` — the isomorphic threaded model (the enum value string
+  is historical; it now compiles to a **wasi-threads** artifact, not an
+  Emscripten Web-Worker build). Default for `runtimeTargets: ["wasmedge"]`.
+  Built with the wasi-threads toolchain.
+
+`resolveThreadModel({ manifest, threadModel })` resolves the model; an explicit
+`threadModel` option always wins over `runtimeTargets` inference.
+
+## 1. Enforced Flags (non-bypassable)
+
+The pthreads final link routes through one flag-assembler (`buildCompilerArgs` in
+`src/compiler/compileModule.js`, backed by `PTHREAD_FINAL_LINK_FLAGS` in
+`src/compiler/pthreadArtifactGuard.js`). For the pthreads model it **always**
+carries the wasm-ld / clang flags:
+
+```
+-pthread -matomics -mbulk-memory -Wl,--import-memory -Wl,--shared-memory -Wl,--max-memory=2147483648
+```
+
+plus the toolchain args resolved by `src/compiler/wasiThreadsToolchain.js`
+(`--target=wasm32-wasip1-threads --sysroot=… -resource-dir=…`). Object files are
+compiled `-matomics -fno-exceptions -pthread` (the wasi-threads libc++ is built
+without exceptions, so throwing code otherwise fails to link).
+
+`buildCompilerArgs` asserts its own output (`assertPthreadFlagsPresent`) so a
+future edit that removes a mandated flag fails loudly. There are deliberately
+**no** Emscripten `-s` settings here — those produce the browser-only build.
+
+The toolchain is resolved with sensible defaults and env overrides
+(`SDN_WASI_CLANG`, `SDN_WASI_CLANGXX`, `SDN_WASI_TARGET`, `SDN_WASI_SYSROOT`,
+`SDN_WASI_RESOURCE_DIR`). If a wasi-threads sysroot is unavailable, the pthreads
+compile fails with a clear, actionable error.
+
+## 2. Validated Artifact (the part that matters most)
+
+After the final `.wasm` is emitted, `compileModuleFromSource` calls
+`assertPthreadArtifact(wasmBytes)` for the pthreads model. It parses the wasm and
+REJECTS the compile unless ALL of the following hold:
+
+- **Shared memory** — an imported or declared memory with the shared limits flag
+  (`flags & 0x02`, i.e. `0x03`/`0x07`).
+- **Atomics usage** — the code section is walked with a real instruction decoder
+  that counts genuine `0xFE`-prefixed atomic instructions. This is **not** a byte
+  scan: a naive scan for `0xFE` false-positives on `i32.const` / LEB128 /
+  memory-offset immediates (memory load/store opcodes `0x28`–`0x3E` carry a
+  memarg). `target_features` is honored when present.
+- **wasi thread-spawn import** — `wasi.thread-spawn` (the host contract WasmEdge
+  invokes to spawn a guest thread).
+- **`wasi_thread_start` export** — the entry a host calls to run a spawned
+  thread.
+- **No Emscripten thread hooks** — the artifact must NOT import
+  `env.__pthread_create_js` or the `env._emscripten_*` mailbox/postMessage hooks.
+  Their presence means it is a browser-only Web-Worker build and it is rejected.
+
+Shared memory + atomics **alone** are necessary but insufficient (the browser-only
+Emscripten build has both), which is exactly why the wasi-threads contract check
+exists. The analysis is returned on the compilation result as
+`result.threadFeatures` (`{ hasSharedMemory, usesAtomics, atomicInstructionCount,
+hasWasiThreadSpawnImport, hasWasiThreadStartExport, emscriptenThreadHooks,
+isIsomorphicPthreads, … }`).
+
+`analyzeWasmThreadFeatures(wasmBytes)` and `assertPthreadArtifact(wasmBytes)` are
+exported from `src/compiler/index.js` (and the package root) for reuse by
+downstream validators, deploy gates, and tests.
+
+Note that the wasi-threads contract (thread-spawn import + `wasi_thread_start`
+export) appears only when the module **actually spawns threads** — the linker
+pulls in that machinery on demand. A module declared `emscripten-pthreads` that
+never spawns a thread will therefore fail this guardrail; such a module should
+use the `single-thread` model instead.
+
+## Guest-link symbol namespacing (collision-proof, metadata-authoritative)
+
+For monolithic flow composition, each module also emits a **guest-link** wasm
+object whose exported method symbols are namespaced by a per-plugin prefix so
+that independently-built modules can be linked together with `wasm-ld -r` without
+symbol clashes. `guestLinkSymbolPrefix(pluginId)` in
+`src/compiler/compileModule.js` produces that prefix as:
+
+```
+sdm_guest_<full-lowercase-hex-of-pluginId-UTF8-bytes>_
+```
+
+The prefix uses the **full** hex encoding of the pluginId — it is **not**
+truncated. Hex encoding is injective, so distinct pluginIds always map to
+distinct prefixes. (A prior `.slice(0, 24)` truncation to 12 bytes collided real
+plugin ids that share a 12-byte stem — e.g. `com.orbpro.iss-source` and
+`com.orbpro.intelsat-source` both collapsed to `hex("com.orbpro.i")`
+`636f6d2e6f726270726f2e69`, which would silently merge/clash their symbols at
+compose time.) Wasm symbol names have no meaningful length limit, so the full hex
+is always safe.
+
+The emitted `symbolPrefix` and the per-method `methodSymbols` map are recorded in
+the guest-link **metadata** (`sds.guest-link`). **That metadata is the sole
+authoritative source consumers read at compose time** — `generateFlowTables` in
+`src/flow/flowCompiler.js` declares and calls
+`dependency.guestLink.metadata.methodSymbols[methodId]` and never re-derives the
+prefix from the pluginId. This keeps already-committed artifacts compatible: an
+object that shipped with a legacy (e.g. truncated) prefix still composes, because
+its own metadata carries the exact symbol names its object bytes define.
+
+## 3. Compile-Time vs. Runtime: an honest boundary
+
+Passing this guardrail proves the **artifact** is a valid wasi-threads
+shared-memory/atomics wasm. It does **not** prove that a given WasmEdge build
+actually spawns and runs guest threads.
+
+> **Rule:** Do not claim WasmEdge thread support until a real runtime invocation
+> spawns threads and runs. Compile-time validation (wasi-threads contract +
+> shared memory + atomics) is necessary but not sufficient; runtime thread-spawn
+> verification is owned by the deploy/benchmark node, not by this SDK.
+
+Record any WasmEdge runtime limitation honestly. An artifact that validates here
+but only compiles — and does not instantiate/spawn threads under the target
+runtime — must be reported as such.
+
+## Tests
+
+- `test/pthreads-artifact-guardrail.test.js` — flag-assembler invariants; a
+  positive compile that emits a validated wasi-threads shared-memory/atomics
+  wasm; a single-thread artifact rejected; a **browser-only Emscripten `-pthread`
+  artifact rejected** (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 `0xFE` immediates.
+- `test/guest-link-symbol-prefix.test.js` — 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
+  `symbolPrefix` / `methodSymbols` as authoritative (never re-derived), keeping a
+  legacy truncated-prefix artifact compatible.
+
+## See also
+
+- [`docs/browser-wasmedge-isomorphic.md`](./browser-wasmedge-isomorphic.md) —
+  the one-artifact browser + WasmEdge loading profile.
+- `.claude/skills/wasmedge-pthreads/Skills.md` — the operating rules.
+- `src/compiler/pthreadArtifactGuard.js` — the flag list + wasm validator.
+- `src/compiler/wasiThreadsToolchain.js` — the wasi-threads toolchain resolver.
+- `src/compiler/compileModule.js` — `ModuleThreadModel`, `buildCompilerArgs`,
+  `compileWithWasiThreads`, `resolveThreadModel`, `compileModuleFromSource`.

package/docs/isomorphic-sdn-runtime-plan.md

@@ -0,0 +1,167 @@
+# Isomorphic SDN Runtime Plan
+
+## Goal
+
+Run the same signed Space Data modules across browser, server, OrbPro, and
+WasmEdge without changing the module contract.
+
+The runtime differences are host differences, not module differences.
+
+## Current Direction
+
+`space-data-module-sdk` is the source of truth for:
+
+- the canonical module artifact
+- the canonical module ABI
+- the canonical dynamic runtime host
+- the canonical WasmEdge/browser/server harness model
+
+Host runtime packages are layered on top of that runtime host as:
+
+- graph/program compiler
+- deployment planner
+- editor/runtime authoring surface
+- optional `emception`-backed build tooling
+
+It is no longer the intended source of truth for a separate runtime model.
+
+## Canonical Identity Model
+
+### Standards Rows
+
+Standards payloads are always addressed by:
+
+- `($SCHEMA_FILE_ID, rowId)`
+
+Rules:
+
+- `rowId` is append-only
+- `rowId` is never reused
+- rows are not individually recycled
+- if a host needs a new retention window, it recreates the mounted table/range
+
+FlatSQL is the only query backend for standards rows.
+
+### Runtime Aligned-Binary Records
+
+High-performance derived runtime state is always addressed by:
+
+- `(regionId, recordIndex)`
+
+Rules:
+
+- the host allocates all regions
+- regions are dynamically requested at runtime
+- regions are fixed-layout aligned-binary memory regions
+- records stay stable for the lifetime of a region
+- regions are not indexed in FlatSQL
+
+### Raw Pointers
+
+Raw pointers are valid only as internal execution details inside a live host or
+module instance.
+
+They are not a durable public contract.
+
+## Host Responsibilities
+
+The canonical SDK runtime host is responsible for:
+
+- installing and loading modules dynamically
+- exposing one canonical module registry for install/load/unload/invoke
+- exposing FlatSQL-backed standards storage
+- exposing canonical streamed FlatBuffer ingest into host-owned rows
+- exposing row-handle resolution
+- allocating aligned-binary runtime regions
+- exposing region-record resolution
+- routing typed invoke traffic across loaded modules
+- hosting the same model in browser, server, and WasmEdge
+
+The recommended outer transport / invoke / storage split is documented in
+[`./flatsql-streaming-standard.md`](./flatsql-streaming-standard.md).
+
+## OrbPro
+
+OrbPro is not a separate storage/runtime architecture.
+
+OrbPro adds a host-side entity/view layer over the same core model:
+
+- standards rows live in FlatSQL
+- WasmEngine owns transient zero-copy render/runtime views
+- workers own query and index work
+- main thread resolves transient shared-memory views for rendering and UI
+- propagators write into host-managed aligned-binary regions
+
+So OrbPro is:
+
+- canonical SDK runtime host
+- plus Cesium-facing entity/view helpers
+
+## Server and Browser Node
+
+Server and browser-node use the same core host model:
+
+- FlatSQL-backed standards rows
+- host-managed runtime regions
+- dynamic module loading
+- typed invoke routing
+
+They do not need the OrbPro entity facade.
+
+## WasmEdge
+
+WasmEdge is a host target for the same runtime model.
+
+The SDK’s WasmEdge runner should evolve from:
+
+- single top-level guest launcher
+
+to:
+
+- dynamic multi-module host
+- FlatSQL row service host
+- runtime-region allocator host
+- typed invoke router
+
+This is a host concern, not a second guest ABI.
+
+## Capability Model
+
+The capabilities that matter most for this runtime model are:
+
+- `database`
+- `storage_query`
+- `storage_write`
+- `filesystem` only when backing FlatSQL to disk
+- `pipe`
+- `http`
+- `network`
+- `timers`
+
+But direct standards-row reads and runtime-region reads should still happen
+through the host’s typed row/region services rather than ad hoc JSON APIs.
+
+## Dynamic Loading vs Compiled Flows
+
+Dynamic module loading is the default runtime model.
+
+Compiled flows remain useful, but only as an optional deployment/build mode:
+
+- freezing a graph into one artifact
+- minimizing moving parts
+- packaging one sealed runtime
+
+Compiled flow output must target the same runtime host contract, not invent a
+parallel execution model.
+
+## Definition of Done
+
+This runtime model is complete when:
+
+- the SDK ships one canonical runtime host surface
+- the SDK host surface exposes row-handle, region, and registry services
+- OrbPro, browser/server SDN nodes, and WasmEdge all consume that same host
+- host runtime packages compile and deploy into that host rather than re-owning runtime behavior
+- standards identity is always `($SCHEMA_FILE_ID, rowId)`
+- aligned-binary runtime identity is always `(regionId, recordIndex)`
+- Aerospace and SOCRATES validation pass on the composed host path