space-data-module-sdk 0.8.4 → 0.8.6

package/docs/language-runtime-matrix.md

@@ -0,0 +1,82 @@
+# SDN Module System — Language/Runtime Matrix and orbpro-integration Harness Port Plan (WS12.1)
+
+Status: WS12.1 deliverable. Section 1 is the definitive language/runtime matrix. Section 2 is the per-file port/dedupe plan that WS12.2 executes. All source paths verified against the live trees on 2026-07-02, then adversarially fact-checked (two independent review passes); citations below are to the **0.8.5** SDK tree unless marked otherwise.
+
+Source trees referenced:
+
+- Harness under port: `/Users/tj/software/OrbPro/packages/orbpro-integration/sdk/src/runtime/` (10 files, 1789 lines)
+- Port target (canonical SDK): `/Users/tj/software/orbpro-stack/repos/main-packages/OrbPro/packages/space-data-module-sdk` (**v0.8.5**, HEAD `0d53c54`)
+- **Warning:** `/Users/tj/software/OrbPro/packages/space-data-module-sdk` is a **stale v0.8.4** copy (no `src/flow/`, no worker harness, no SAB channel, no timer driver). Do not port into it. sdn-js pins the SDK as a tarball directly at commit `53748bc92bdac04a2372fe4a6dafa0e4a0abd43d` (`sdn-js/package.json:100`) — **one commit behind** HEAD `0d53c54` (the workspace ROOT `space-data-network/package.json:84` carries a separate, older pin at `cfc9b538…`) (the commit that added `src/flow/` and the `"./flow"` export). The frozen-compat surface for sdn-js is therefore the *pinned commit's* exports, which do **not** include `./flow`.
+
+---
+
+## 1. Language/runtime matrix
+
+Framing: **hosts** embed a runtime to execute SDN `.wasm` modules; **guests** are the languages modules are written in. All SDN modules are standalone-WASI wasm compiled from **C/C++ only** (emscripten `em++`/`emcc` selected in `selectCompiler`, `space-data-module-sdk/src/compiler/compileModule.js:78-84`; `STANDALONE_WASM=1` at `compileModule.js:130`). No Rust, AssemblyScript, TinyGo, or Python guests exist anywhere in the codebase.
+
+| Host environment / language | Module runtime used | WasmEdge native? | Status in this codebase | Evidence |
+|---|---|---|---|---|
+| **Go node (`sdn-server`)** — Go | WasmEdge embedded in-process via CGO (`second-state/WasmEdge-go v0.14.0`) | **YES** (in-process, production) | **In use** — the production module runtime | `sdn-server/go.mod:27`; `internal/wasmrt/runtime.go:12,117-130` (`wasmedge.NewVMWithConfig`, THREADS/EXCEPTION_HANDLING/WASI); `internal/modulert/module.go:167-175` |
+| **Browser** — JS/TS (sdn-js UI, OrbPro) | Plain `WebAssembly.instantiate` + pure-JS WASI shim + the `space_data_module_host` hostcall bridge (**the JS harness**) | **NO** — WasmEdge does not exist in browsers | **In use** — `createBrowserModuleHarness`, `createWorkerModuleHarness`, `createFlowRuntimeHost` | `sdn-js/src/ui/runtime/live-delivery.ts:2,204`; SDK `src/host/wasiShim.js:33`, `src/host/abi.js:10` (`DEFAULT_HOSTCALL_IMPORT_MODULE = "space_data_module_host"`, matching Go `internal/modulert/hostbridge.go:28`), `src/testing/browserModuleHarness.js:263,310,353`, `src/flow/flowRuntimeHost.js:36` |
+| **Node.js — JS/TS, subprocess path** | WasmEdge **out-of-process**: `spawn("wasmedge", ...)` CLI, invoke request over stdin/stdout | Yes, but only as an external binary | **In use** (Node harness default for standalone artifacts) | SDK `src/host/isomorphicLoader.js:89,112`; `src/testing/processInvoke.js:111,131` |
+| **Node.js — JS/TS, pure-JS path** | Plain V8 `WebAssembly` + the same browser harness (wasiShim + hostcall bridge) | NO | **In use** (vitest, isomorphic artifacts, no-wasmedge-binary environments) | `wasiShim.js:1-12` ("same .wasm that runs in WasmEdge … instantiated directly"); `browserModuleHarness.js:186,310` |
+| **C** — native test runner | WasmEdge embedded via the C API (`wasmedge/wasmedge.h`) | **YES** (in-process, test-only) | **In use** (pthread module test runner only) | SDK `src/testing/native/wasmedge_emscripten_pthread_runner.c:9`; `src/testing/buildWasmEdgeRunner.js` |
+| **C/C++** — as guest language | n/a (compiles to the wasm modules themselves) | n/a | **In use** — the *only* guest language | All module families (`propagator/*`, `foundation/*`, `comms/*`, closed-modules `*.cpp`); compiler supports exactly `.cpp → em++` / else `emcc` |
+| **Rust** | WasmEdge Rust SDK (`wasmedge-sdk`) exists upstream | Would be native | **N/A — not used** (only vendored emsdk test fixtures contain `.rs`) | Zero `Cargo.toml` outside `deps/emsdk/.../test/rust/` |
+| **Python** | WasmEdge Python SDK exists upstream (experimental) | Would be native | **N/A — not used** | No Python host or guest anywhere |
+| **Java** | `wasmedge-java` exists upstream | Would be native | **N/A — not used** | No Java anywhere |
+| **Node.js napi binding** (`wasmedge-core`) | — | — | **Deliberately not used** — project shells out to the CLI instead | No napi dep in SDK or `sdn-js/package.json` |
+
+### Definitive conclusion
+
+- **Environments that NEED the JS-style harness** (WebAssembly.instantiate + `createBrowserWasiShim` + the `space_data_module_host` hostcall bridge): **the browser, always** (no WasmEdge exists there), and **Node.js** whenever the isomorphic/browser artifact path is used or no `wasmedge` binary is on PATH. This is the entire reason the harness exists and the reason the orbpro-integration runtime mirrors WasmEdge ABI semantics in JS.
+- **Environments that run WasmEdge natively (in-process)**: **Go** (CGO bindings — the only production embedding) and **C** (C API — testing-only pthread runner). Nothing else.
+- **Out-of-process WasmEdge**: Node.js via `spawn("wasmedge")` only.
+- **Rust, Python, Java**: upstream WasmEdge SDKs exist but are not used and no work in this plan targets them. Any future host in those languages would embed WasmEdge natively and would **not** need the JS harness.
+- The JS harness is therefore not a stopgap; it is the permanent execution tier for the browser and the WasmEdge-mirror reference for Node. That is why WS12.2 moves it into `space-data-module-sdk` (the package that already owns the browser/Node execution surface) rather than leaving it in orbpro-integration.
+
+---
+
+## 2. Port/dedupe plan — the 10 `orbpro-integration/sdk/src/runtime/` files
+
+Conventions for WS12.2:
+
+- Target base = the **0.8.5** SDK at `/Users/tj/software/orbpro-stack/repos/main-packages/OrbPro/packages/space-data-module-sdk`.
+- **Generated-code precursor (corrected scope):** the harness imports `../generated/orbpro/{flow,manifest,stream,plugin}.js`. In the 0.8.5 SDK the **manifest namespace is already generated** (`src/generated/orbpro/manifest/plugin-manifest.js`, `PMAN` identifier at lines 30/248). What is **missing** is (a) the **flow namespace entirely** and (b) **`StreamInvokeRequest`/`StreamInvokeResponse` in the plugin namespace** (`src/generated/orbpro/plugin.js` exports only `RawDataPayload`). Regenerate both in the SDK tree as the WS12.2 precursor — do not import across packages. Note the SDK already hand-rolls StreamInvoke flatbuffer classes at `src/testing/streamInvokeCodec.js` (classes at lines 13/67/96): once the generated plugin namespace lands, `flowCodec.js` (#2) and `streamInvokeCodec.js` must converge on ONE implementation (the generated one), with `streamInvokeCodec.js` reduced to a re-export or deleted.
+- The `sdn-flow` github pin: the harness's `sdk/package.json:83` pin is carried by `compiledFlowHost.js:1` and `MethodRegistry.js:1` (plus `tests/CompiledFlowHostSpec.js:4`). See #3/#6 — the pin **cannot be fully dropped in WS12.2** (production consumers of the bound-host API remain in orbpro-integration); the port removes the *SDK's* need for it and leaves a scoped follow-on.
+
+| # | File (lines) | Verdict | Target / action |
+|---|---|---|---|
+| 1 | `bufferLike.js` (28) | **DROP** | Byte-identical twin already exists at SDK `src/runtime/bufferLike.js` (same three exports: `isArrayBufferLike`, `hasByteAddressableBuffer`, `toUint8Array`). Rewrite the two internal consumers (codec, streamBridge) to import from `../runtime/bufferLike.js`. Zero-risk deletion. |
+| 2 | `codec.js` (94) | **PORT (split, with renames)** | The `StreamInvokeRequest/Response` + `FlowProgram` (`"FLOW"`) codecs are a **distinct envelope** from the SDK's existing `PluginInvokeRequest/Response` codec (`src/invoke/codec.js`) — do not conflate them. Port `encode/decodeFlowProgram` and `encode/decodeStreamInvoke{Request,Response}` to new SDK file `src/flow/flowCodec.js` (subsuming `src/testing/streamInvokeCodec.js`, see precursor). **The manifest codec does NOT merge**: the SDK's `encodePluginManifest` (`src/manifest/codec.js:258`) is `encodePlgManifest(legacyManifestToPlg(manifest))` — it emits a **`$PLG`**-identified buffer (`src/manifest/plgCodec.js:37`), consumed by `compileModule.js:830,889` and SDK `embeddedManifest.js:32` — while the harness's codec emits the **`PMAN`**-identified `PluginManifest` buffer that orbpro-integration's `sdk/src/embeddedManifest.js:5` depends on. These are different wire formats; both must exist. Port the PMAN pair with **renamed exports** `encodePluginManifestPman`/`decodePluginManifestPman` (avoids star-export collision with the PLG-flavored names in `src/manifest/index.js:7`/`browser.js:7` re-exported via `src/browser.js:1`), living in `src/flow/flowCodec.js` beside the flow codecs. Internal `toByteBuffer` moves with it. Browser-safe; only dep is `flatbuffers` (already an SDK dep). |
+| 3 | `compiledFlowHost.js` (35) | **MERGE (option) + KEEP compat shim** | `createFlowRuntimeHost` (0.8.5 `src/flow/flowRuntimeHost.js`) already runs the compiled flow `runtime.wasm` with Go-parity ABI. Merge INTO it the one new behavior here: `withLegacyHostImportCompat` — the stub import module `sdn_flow_host` with `dispatch_current_invocation: () => 0` (caller entries win) so legacy artifacts instantiate under plain `WebAssembly.instantiate` — as an instantiate option (`legacyHostImportCompat: true` or an `extraImports` hook). **`bindCompiledFlowRuntimeHost` is NOT deleted**: it has production consumers — `orbpro-integration/default-suite.js:631,738` call `createDefaultPluginCompiledFlowHost` (`defaultRuntimeRegistry.js:164-166` → `bindOrbProCompiledFlowHost`), passing sdn-flow bound-host options and consuming the bound-host API (`host.runEntrypoint`, `host.dispatchNextReadyNodeWithHost`, `host.drainWithHost…`, `default-suite.js:668-700`) that the SDK host does not provide. The wrapper (and its `sdn-flow/host` import) stays in orbpro-integration as a compat adapter; migrating default-suite off the bound-host API onto the SDK flow host is a **follow-on task**, after which the sdk-package sdn-flow pin can go. |
+| 4 | `FlowRuntime.js` (275) | **PORT** to `src/flow/jsFlowRuntime.js` | New capability: a **pure-JS FlowProgram interpreter** (no `runtime.wasm` needed) — the fallback/test-tier scheduler, complementing `flowRuntimeHost.js` which requires the compiled artifact. Port intact but **align contracts with the wasm host**: same backpressure policies (`queue`/`drop-oldest`/`drop-newest`, depth ≥1 or Infinity), same yield semantics (`response.yielded === true` breaks the drain), same default `maxInvocationsPerDrain = 1024`, and make `drain()`'s return shape (`{invocations, idle, queues}`) documented alongside `flowRuntimeHost.drain()`. It must invoke through the registry surface chosen in #6. Export as `space-data-module-sdk/flow` alongside `createFlowRuntimeHost`. Browser-safe; only sibling import is the normalizer (#8). |
+| 5 | `index.js` (35) | **DROP** | The barrel is orbpro-integration packaging, not code. Its **18** names (8 codec fns + `bindOrbProCompiledFlowHost` + `createDependencyStreamBridge` + `MethodRegistry` + `FlowRuntime` + 5 sdnCompat exports + `generateLegacySdnShimSource`) get re-homed: flow pieces + flow/PMAN codecs → `./flow`, registry → `./runtime-host`, compat → new `./compat` (see #7), shim generator → `./compiler` (see #9); `bindOrbProCompiledFlowHost` stays in orbpro-integration (#3). The renamed PMAN exports (#2) prevent barrel collisions with the SDK's existing PLG-flavored `encodePluginManifest`/`decodePluginManifest`. Update the SDK `package.json` `exports` map and `src/browser.js` accordingly. orbpro-integration keeps a thin re-export barrel for back-compat (Section 3). |
+| 6 | `MethodRegistry.js` (40) | **VENDOR sdn-flow's registry; wrapper stays thin** | The file itself is a 40-line wrapper, but the `sdn-flow/runtime` contract behind it is **not** small: at the pinned commit (`4dd28e2`, verified against the local baseline worktree) `sdn-flow/src/runtime/MethodRegistry.js` is 400 lines + `runtime/normalize.js` 506 lines, enforcing duplicate-pluginId and missing-per-method-handler rejection (:231/:245 — `defaultRuntimeRegistry.js:93-120` relies on these throws for its `registration-failed` reporting), required-input-port presence (:330), min/max distinct-stream bounds (:339-347), acceptedTypeSets frame-type rejection (:350-357), undeclared-input-port rejection (:362-367), internal-transport aligned-binary typeRef coercion with capability/interface exception sets (:10-28,:140-172), outputStreamCap overflow errors (:176-179), single-output portId defaulting (:181-188), and drainPolicy defaulting (:370-373). Reimplementing "lookup + call + normalization" would silently drop validation the ported specs assert. Plan: **vendor sdn-flow's `MethodRegistry.js` + `runtime/normalize.js` into the SDK** (`src/runtime-host/methodRegistry.js` + supporting normalize), preserving behavior verbatim (no github pin — vendored source), integrate with `createModuleRegistry` at the seams (manifest-aware `registerPlugin` accepting `PluginManifestT` \| flatbuffer bytes \| plain object via #8's normalizer), and keep the class-shaped `MethodRegistry` export. The five orbpro-integration spec files are the parity gate. |
+| 7 | `sdnCompat.js` (449) | **PORT** to new `src/compat/sdnLegacy.js` (new `./compat` subpath) | No SDK equivalent exists for the legacy SDN metadata JSON envelope (`buildLegacySdnMetadata` — the exact snake_case JSON that `plugin_get_metadata` returns from a WasmEdge-loaded module) or the cron/protocol dispatch adapters (`SdnCompatAdapter.invokeCron/invokeProtocol` with `legacyBridge` context tagging, timer resolution by timerId-or-methodId, default-port stamping). This is the JS twin of the Go host's legacy surface and is consumed by the shim generator (#9). Port whole. Rewrites: generated imports (`manifest`, `stream` namespaces) → SDK generated tree; `decodePluginManifest` import → `decodePluginManifestPman` (#2); registry type → #6. Browser-safe (`TextEncoder` only). **Do not change any field name, enum casing (UPPER_SNAKE), or the BigInt `"<n>ms"` interval formatting — this JSON is a wire contract with the Go host.** |
+| 8 | `sdnFlowAdapter.js` (276) | **PORT (internal)** to `src/flow/normalize.js` | Required by #4 and #6: `normalizeManifestForSdnFlow` / `normalizeProgramForSdnFlow` encode the ABI conventions (numeric flatbuffer enums → kebab-case strings, `maxBatch: 1` / `drain-until-yield` / `queue`/depth-1 defaults, schemaHash typed-array → plain array). Keep it **internal** — not in the exports map, exactly as it is today (never re-exported by the harness barrel). Since #6 vendors sdn-flow's registry (the sdn-flow reference stays meaningful), keep the exported names as-is. Rewrites: generated imports + `decodePluginManifestPman`/`decodeFlowProgram` from their new SDK homes. Browser-safe. |
+| 9 | `sdnShimGenerator.js` (323) | **PORT** to `src/compiler/sdnShimGenerator.js` | The SDK-surface audit's confirmed gap: no hostcall/legacy-ABI codegen exists in the SDK (only build-side `compiler/invokeGlue.js`). This generates the C shim exporting the legacy WasmEdge-host ABI (`plugin_get_metadata` / `plugin_handle_request` / `plugin_cron`, caller-allocated buffers, int32 length-or-negative-error). Port whole into the compiler layer, next to its natural consumer (the build pipeline; orbpro-integration's `sdnArtifacts.js` writes its output as `sdn-compat-shim.c`). **The C template must be moved byte-identically**: error constants `-1..-5`, `EMSCRIPTEN_KEEPALIVE` exports, `\xNN` string escaping, memcmp method dispatch, and the single-protocol-method constraint of `resolveRequestMethodId` are all ABI/behavior contracts. Rewrites: generated manifest import, `decodePluginManifestPman` + `buildLegacySdnMetadata` from their new SDK homes (#2/#7). The file is browser-safe (pure string generation) even though it lives under the Node-leaning `./compiler` subpath — note that in the module docstring so a future browser build tool can import it. |
+| 10 | `streamBridge.js` (234) | **PORT** to `src/flow/dependencyStreamBridge.js` | Fills the other confirmed gap: a flow host that can invoke **dependency wasm modules itself** (guest `malloc`/`free` arena staging, `TypedArenaBufferT` input framing with defaults alignment=8/BORROWED/IMMUTABLE, `invokeRawStream` with the `StreamInvokeRequest` envelope, copy-out of `(offset,size)` outputs via `cloneBytes` so bytes survive memory growth, guaranteed `release()` in `finally`, deduped output-pointer freeing). `flowRuntimeHost.drain()` currently delegates non-linked-direct nodes to caller-supplied JS handlers; this bridge is what turns a dependency descriptor's instantiated module into such a handler. Port whole; wire an optional integration in `flowRuntimeHost` so a caller can pass `{instantiatedDependency}` per dependencyId instead of a raw handler. Merge notes: import `toUint8Array`/`hasByteAddressableBuffer` from SDK `src/runtime/bufferLike.js` (#1), the StreamInvoke codecs from `src/flow/flowCodec.js` (#2), and converge its output-frame shape with `src/invoke/codec.js`'s TypedArenaBuffer materialization where field names differ (`traceToken` vs `traceId` — keep both readable, emit the harness's names for continuity). Do **not** replace it with the browser harness's direct surface: that speaks the *PluginInvokeRequest* envelope to `plugin_invoke_stream`; this speaks *StreamInvokeRequest* to `invokeRawStream`. They are different guest ABIs and both must exist. |
+
+### Summary of verdicts
+
+- **DROP (2):** `bufferLike.js` (identical twin in SDK), `index.js` (packaging only; names re-homed on SDK subpaths, PMAN codecs renamed).
+- **MERGE (1):** `compiledFlowHost.js` → its `withLegacyHostImportCompat` option merges into `src/flow/flowRuntimeHost.js`; the `bindCompiledFlowRuntimeHost` bound-host adapter **remains in orbpro-integration** (production consumers in `default-suite.js`).
+- **VENDOR (1):** `MethodRegistry.js` — vendor sdn-flow's full registry + normalize into `src/runtime-host/` (validation semantics preserved verbatim).
+- **PORT (6):** `codec.js` → `src/flow/flowCodec.js` (flow + StreamInvoke codecs; PMAN manifest codec as renamed `encode/decodePluginManifestPman`), `FlowRuntime.js` → `src/flow/jsFlowRuntime.js`, `sdnCompat.js` → `src/compat/sdnLegacy.js`, `sdnFlowAdapter.js` → `src/flow/normalize.js` (internal), `sdnShimGenerator.js` → `src/compiler/sdnShimGenerator.js`, `streamBridge.js` → `src/flow/dependencyStreamBridge.js`.
+- Net effect: the SDK gains no new external dependencies (only `flatbuffers`, already present; sdn-flow arrives **vendored**, not pinned). The `sdn-flow` github pin at orbpro-integration `sdk/package.json:83` can be dropped only **after** the follow-on default-suite migration (#3); the root `orbpro-integration/package.json:94` pin and the `default-suite.js:99-100` lazy `sdn-flow/auth` + `sdn-flow/deploy` imports are out of scope for WS12.2 entirely.
+
+---
+
+## 3. Risks and constraints for WS12.2
+
+1. **Port into 0.8.5, not 0.8.4.** The copy at `/Users/tj/software/OrbPro/packages/space-data-module-sdk` is stale (v0.8.4, missing `src/flow/`, `workerModuleHarness`, `sabHostcallChannel.js`, `hostcallWire.js`, `timerDriver.js`). All merges above name 0.8.5-only files. Decide early whether the stale OrbPro copy gets synced or retired; do not let the two copies diverge further.
+2. **Do not disturb the existing SDK export surface.** sdn-js pins the SDK tarball directly at `53748bc92bdac04a2372fe4a6dafa0e4a0abd43d` (`sdn-js/package.json:100`; v0.8.5, one commit before `./flow` existed) and imports these subpaths: root, `/compiler`, `/host/timer-driver`, `/licensing`, `/runtime-host`, `/testing`, `/testing/browser`, `/testing/module-flatbuffer-stream-pump`, `/transport`. It does **not** import `./flow`. Additions to the exports map are fine; renames/removals of existing subpaths or `src/browser.js` re-exports are not.
+3. **orbpro-integration consumers must keep working.** Three surfaces depend on the harness today: (a) the public subpath `@orbpro/integration-sdk/runtime` (`sdk/package.json:18`) and the **18** names re-exported by `sdk/index.js:61-80` / `sdk/node.js`; (b) **deep imports** in `orbpro-integration/defaultRuntimeRegistry.js:1-2,12` (`FlowRuntime.js`, `MethodRegistry.js`, lazy `compiledFlowHost.js`); (c) in-SDK consumers `sdk/src/sdnArtifacts.js:3-6` and `sdk/src/embeddedManifest.js:5` (PMAN bytes — see #2). WS12.2 must leave **compat shims at the old file paths** (one-line re-exports from `space-data-module-sdk`) until OrbPro-side callers are migrated — especially the deep-imported files, which the barrel cannot cover.
+4. **Two invoke envelopes coexist; neither may change.** `PluginInvokeRequest/Response` (SDK `src/invoke/codec.js`, used by `plugin_invoke_stream` / `_start` surfaces, the worker harness, and the Go host) vs `StreamInvokeRequest/Response` (flow dependency `invokeRawStream` ABI). Keep them in separate files with distinct names; a unification refactor is out of scope and would break compiled artifacts.
+5. **Two manifest envelopes coexist; neither may change.** The SDK's `encodePluginManifest`/`decodePluginManifest` are **`$PLG`**-flavored (`src/manifest/codec.js:258` via `plgCodec.js`); the harness's are **`PMAN`**-flavored. The ported PMAN pair ships under the renamed `encodePluginManifestPman`/`decodePluginManifestPman` exports; consumers of each keep their exact bytes.
+6. **Wire/ABI contracts that must stay byte-identical:** the `"PMAN"` and `"FLOW"` flatbuffer file identifiers (and the fact that StreamInvoke envelopes have *no* identifier); the legacy metadata JSON field set/casing/`"<n>ms"` BigInt intervals (`buildLegacySdnMetadata`); the generated C shim template including error codes −1…−5 and export names; the `sdn_flow_host` import-module name and `dispatch_current_invocation` stub in the compat option; TypedArenaBuffer staging defaults (alignment 8, BORROWED, IMMUTABLE, generation 0); the `space_data_module_host` hostcall import-module name (`src/host/abi.js:10` = Go `hostbridge.go:28`).
+7. **Vendoring sdn-flow's registry — test parity is the gate.** The vendored `MethodRegistry` + `normalize` (#6) must behave identically to the pin; the five orbpro-integration spec files (`UnifiedRuntimeSpec`, `SdnCompatSpec`, `CompiledFlowHostSpec`, `StreamInvokeBridgeSpec`, `SdnShimGeneratorSpec`) must be ported alongside the code and pass against the SDK build before the shims land. `CompiledFlowHostSpec` imports layout constants from `sdn-flow/host` directly — rewrite those assertions against `flowRuntimeHost.js`'s own struct-layout constants (60/72/48/24/32/24-byte descriptors).
+8. **Browser-graph hygiene.** Everything ported is browser-safe (verified: zero `node:` imports across the 10 files). Keep it that way: `src/compat/sdnLegacy.js` and `src/flow/*` go into `src/browser.js`; the shim generator goes only under `./compiler` (Node-leaning) even though it is technically browser-safe; nothing ported may import `nodeHost.js`, `sdnArtifacts.js`-style `fs`/`path`, or the subprocess loaders.
+9. **Don't re-port what 0.8.5 already finished:** worker/SAB execution (`workerModuleHarness` + `sabHostcallChannel` + `hostcallWire`), cron/timer re-invocation (`timerDriver` + `cron.js`), isomorphic load/inspect (`isomorphicLoader`, `detectArtifactProfile`), and the compiled-flow wasm host's descriptor decoding (`flowRuntimeHost`). The port adds the JS interpreter tier, the dependency stream bridge, legacy compat, and the shim generator — nothing else.
+10. **Naming collision watch:** the SDK already exports `createModuleRegistry`; the vendored `MethodRegistry` must be documented as the flow-tier registry (validating, sdn-flow-derived) vs `createModuleRegistry` (module lifecycle) to avoid a third registry concept. Similarly `jsFlowRuntime` vs `createFlowRuntimeHost` need one doc page distinguishing "interpreter (no runtime.wasm)" from "compiled-artifact host (Go parity)".

package/docs/manifest-structure.svg

@@ -0,0 +1,114 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 440" fill="none">
+  <defs>
+    <linearGradient id="bg2" x1="0" y1="0" x2="900" y2="440" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#0d1117"/>
+      <stop offset="1" stop-color="#161b22"/>
+    </linearGradient>
+    <marker id="arrow2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#484f58"/>
+    </marker>
+    <marker id="arrowBlue" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#58a6ff"/>
+    </marker>
+    <marker id="arrowGreen" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#3fb950"/>
+    </marker>
+  </defs>
+
+  <rect width="900" height="440" rx="12" fill="url(#bg2)"/>
+
+  <!-- Title -->
+  <text x="450" y="35" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="700" fill="#e6edf3">Plugin Manifest &amp; Typed Streaming Ports</text>
+  <text x="450" y="55" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#8b949e">Modules declare typed I/O ports that accept FlatBuffer schemas from spacedatastandards.org</text>
+
+  <!-- Plugin Manifest Box -->
+  <rect x="30" y="75" width="250" height="340" rx="10" fill="#161b22" stroke="#58a6ff" stroke-width="1.5"/>
+  <rect x="30" y="75" width="250" height="30" rx="10" fill="#1f6feb" fill-opacity="0.15"/>
+  <text x="155" y="96" text-anchor="middle" font-family="monospace" font-size="12" font-weight="700" fill="#58a6ff">PluginManifest</text>
+
+  <!-- Manifest fields -->
+  <text x="50" y="128" font-family="monospace" font-size="10" fill="#f0883e">pluginId</text>
+  <text x="175" y="128" font-family="monospace" font-size="10" fill="#8b949e">"com.example.prop"</text>
+  <text x="50" y="148" font-family="monospace" font-size="10" fill="#f0883e">name</text>
+  <text x="175" y="148" font-family="monospace" font-size="10" fill="#8b949e">"Basic Propagator"</text>
+  <text x="50" y="168" font-family="monospace" font-size="10" fill="#f0883e">version</text>
+  <text x="175" y="168" font-family="monospace" font-size="10" fill="#8b949e">"0.1.0"</text>
+  <text x="50" y="188" font-family="monospace" font-size="10" fill="#f0883e">pluginFamily</text>
+  <text x="175" y="188" font-family="monospace" font-size="10" fill="#8b949e">"propagator"</text>
+  <text x="50" y="208" font-family="monospace" font-size="10" fill="#f0883e">capabilities</text>
+  <text x="175" y="208" font-family="monospace" font-size="10" fill="#8b949e">["clock"]</text>
+
+  <line x1="45" y1="220" x2="265" y2="220" stroke="#30363d" stroke-width="1"/>
+
+  <text x="50" y="240" font-family="monospace" font-size="10" fill="#bc8cff">methods[]</text>
+
+  <!-- Method box -->
+  <rect x="50" y="250" width="215" height="60" rx="6" fill="#1c2128" stroke="#bc8cff" stroke-width="1"/>
+  <text x="65" y="270" font-family="monospace" font-size="10" fill="#bc8cff">methodId</text>
+  <text x="155" y="270" font-family="monospace" font-size="10" fill="#8b949e">"propagate"</text>
+  <text x="65" y="290" font-family="monospace" font-size="10" fill="#bc8cff">drainPolicy</text>
+  <text x="155" y="290" font-family="monospace" font-size="10" fill="#8b949e">"drain-to-empty"</text>
+
+  <!-- Method detail: center area -->
+  <rect x="310" y="100" width="280" height="310" rx="10" fill="#161b22" stroke="#bc8cff" stroke-width="1.5"/>
+  <rect x="310" y="100" width="280" height="30" rx="10" fill="#8b5cf6" fill-opacity="0.1"/>
+  <text x="450" y="121" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" font-weight="700" fill="#bc8cff">Method: propagate</text>
+
+  <!-- Input Port -->
+  <text x="330" y="155" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#58a6ff">inputPorts</text>
+
+  <rect x="330" y="165" width="240" height="80" rx="6" fill="#1c2128" stroke="#58a6ff" stroke-width="1"/>
+  <text x="345" y="185" font-family="monospace" font-size="10" fill="#58a6ff">portId: "request"</text>
+  <text x="345" y="205" font-family="monospace" font-size="10" fill="#8b949e">acceptedTypeSets:</text>
+  <rect x="355" y="212" width="200" height="22" rx="4" fill="#0d1117" stroke="#3fb950" stroke-width="1"/>
+  <text x="365" y="228" font-family="monospace" font-size="10" fill="#3fb950">OMM.fbs  $OMM</text>
+
+  <!-- Output Port -->
+  <text x="330" y="270" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#f0883e">outputPorts</text>
+
+  <rect x="330" y="280" width="240" height="80" rx="6" fill="#1c2128" stroke="#f0883e" stroke-width="1"/>
+  <text x="345" y="300" font-family="monospace" font-size="10" fill="#f0883e">portId: "state"</text>
+  <text x="345" y="320" font-family="monospace" font-size="10" fill="#8b949e">acceptedTypeSets:</text>
+  <rect x="355" y="327" width="200" height="22" rx="4" fill="#0d1117" stroke="#3fb950" stroke-width="1"/>
+  <text x="365" y="343" font-family="monospace" font-size="10" fill="#3fb950">CAT.fbs  $CAT</text>
+
+  <!-- Arrow: manifest -> method -->
+  <line x1="265" y1="280" x2="310" y2="230" stroke="#484f58" stroke-width="1.5" marker-end="url(#arrow2)"/>
+
+  <!-- Standards catalog -->
+  <rect x="630" y="100" width="240" height="310" rx="10" fill="#161b22" stroke="#3fb950" stroke-width="1.5"/>
+  <rect x="630" y="100" width="240" height="30" rx="10" fill="#238636" fill-opacity="0.1"/>
+  <text x="750" y="121" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" font-weight="700" fill="#3fb950">spacedatastandards.org</text>
+
+  <!-- Standard entries -->
+  <rect x="650" y="145" width="200" height="35" rx="6" fill="#1c2128" stroke="#3fb950" stroke-width="1"/>
+  <text x="660" y="162" font-family="monospace" font-size="10" font-weight="600" fill="#3fb950">OMM</text>
+  <text x="700" y="162" font-family="monospace" font-size="9" fill="#8b949e">Orbit Mean-Elements Message</text>
+  <text x="660" y="174" font-family="monospace" font-size="9" fill="#484f58">file_identifier: "$OMM"</text>
+
+  <rect x="650" y="190" width="200" height="35" rx="6" fill="#1c2128" stroke="#3fb950" stroke-width="1"/>
+  <text x="660" y="207" font-family="monospace" font-size="10" font-weight="600" fill="#3fb950">CAT</text>
+  <text x="700" y="207" font-family="monospace" font-size="9" fill="#8b949e">Catalog (state vectors)</text>
+  <text x="660" y="219" font-family="monospace" font-size="9" fill="#484f58">file_identifier: "$CAT"</text>
+
+  <rect x="650" y="235" width="200" height="35" rx="6" fill="#1c2128" stroke="#3fb950" stroke-width="1"/>
+  <text x="660" y="252" font-family="monospace" font-size="10" font-weight="600" fill="#3fb950">EPM</text>
+  <text x="700" y="252" font-family="monospace" font-size="9" fill="#8b949e">Ephemeris Message</text>
+  <text x="660" y="264" font-family="monospace" font-size="9" fill="#484f58">file_identifier: "$EPM"</text>
+
+  <rect x="650" y="280" width="200" height="35" rx="6" fill="#1c2128" stroke="#3fb950" stroke-width="1"/>
+  <text x="660" y="297" font-family="monospace" font-size="10" font-weight="600" fill="#3fb950">CDM</text>
+  <text x="700" y="297" font-family="monospace" font-size="9" fill="#8b949e">Conjunction Data Message</text>
+  <text x="660" y="309" font-family="monospace" font-size="9" fill="#484f58">file_identifier: "$CDM"</text>
+
+  <rect x="650" y="325" width="200" height="35" rx="6" fill="#1c2128" stroke="#3fb950" stroke-width="1"/>
+  <text x="660" y="342" font-family="monospace" font-size="10" font-weight="600" fill="#3fb950">PLD</text>
+  <text x="700" y="342" font-family="monospace" font-size="9" fill="#8b949e">Planned Launch Data</text>
+  <text x="660" y="354" font-family="monospace" font-size="9" fill="#484f58">file_identifier: "$PLD"</text>
+
+  <text x="750" y="385" text-anchor="middle" font-family="monospace" font-size="10" fill="#484f58">... 40+ standards</text>
+
+  <!-- Arrows: ports -> standards -->
+  <line x1="555" y1="223" x2="650" y2="162" stroke="#3fb950" stroke-width="1.5" stroke-dasharray="4 3" marker-end="url(#arrowGreen)"/>
+  <line x1="555" y1="338" x2="650" y2="297" stroke="#3fb950" stroke-width="1.5" stroke-dasharray="4 3" marker-end="url(#arrowGreen)"/>
+</svg>

package/docs/module-bundle-runtime-plan.md

@@ -0,0 +1,19 @@
+# Superseded: Single-File Module Bundle Runtime Plan
+
+This document is superseded by:
+
+- [module-publication-standard.md](/Users/tj/software/OrbPro/packages/space-data-module-sdk/docs/module-publication-standard.md)
+- [isomorphic-sdn-runtime-plan.md](/Users/tj/software/OrbPro/packages/space-data-module-sdk/docs/isomorphic-sdn-runtime-plan.md)
+
+The old document is no longer current because:
+
+- the canonical publication model now explicitly allows appended `REC` records carrying `PNM` and `ENC`
+- the canonical runtime discussion has moved to the SDK runtime host model
+- bundle/container concerns and runtime-host concerns are now documented separately
+
+Current rule summary:
+
+- the executable artifact is still canonical `.wasm`
+- single-file bundle metadata is carried by an `MBL` record inside one appended `REC` trailer
+- publication/signature/encryption metadata is carried in that same appended `REC` trailer when present
+- runtime hosting is defined by the SDK runtime host, not by the bundle container itself

package/docs/module-lifecycle.svg

@@ -0,0 +1,70 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 200" fill="none">
+  <defs>
+    <linearGradient id="bg3" x1="0" y1="0" x2="900" y2="200" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#0d1117"/>
+      <stop offset="1" stop-color="#161b22"/>
+    </linearGradient>
+    <marker id="arrow3" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#484f58"/>
+    </marker>
+  </defs>
+
+  <rect width="900" height="200" rx="12" fill="url(#bg3)"/>
+
+  <!-- Step 1: Author -->
+  <rect x="20" y="50" width="130" height="100" rx="10" fill="#161b22" stroke="#8b949e" stroke-width="1.5"/>
+  <circle cx="85" cy="80" r="14" fill="#1c2128" stroke="#8b949e" stroke-width="1.5"/>
+  <text x="85" y="85" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" fill="#8b949e">1</text>
+  <text x="85" y="112" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" font-weight="600" fill="#e6edf3">Author</text>
+  <text x="85" y="130" text-anchor="middle" font-family="monospace" font-size="9" fill="#8b949e">manifest.json</text>
+  <text x="85" y="142" text-anchor="middle" font-family="monospace" font-size="9" fill="#8b949e">+ source code</text>
+
+  <line x1="150" y1="100" x2="175" y2="100" stroke="#484f58" stroke-width="2" marker-end="url(#arrow3)"/>
+
+  <!-- Step 2: Compile -->
+  <rect x="180" y="50" width="130" height="100" rx="10" fill="#161b22" stroke="#f0883e" stroke-width="1.5"/>
+  <circle cx="245" cy="80" r="14" fill="#1c2128" stroke="#f0883e" stroke-width="1.5"/>
+  <text x="245" y="85" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" fill="#f0883e">2</text>
+  <text x="245" y="112" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" font-weight="600" fill="#e6edf3">Compile</text>
+  <text x="245" y="130" text-anchor="middle" font-family="monospace" font-size="9" fill="#8b949e">emcc/em++</text>
+  <text x="245" y="142" text-anchor="middle" font-family="monospace" font-size="9" fill="#8b949e">embed manifest</text>
+
+  <line x1="310" y1="100" x2="335" y2="100" stroke="#484f58" stroke-width="2" marker-end="url(#arrow3)"/>
+
+  <!-- Step 3: Validate -->
+  <rect x="340" y="50" width="130" height="100" rx="10" fill="#161b22" stroke="#3fb950" stroke-width="1.5"/>
+  <circle cx="405" cy="80" r="14" fill="#1c2128" stroke="#3fb950" stroke-width="1.5"/>
+  <text x="405" y="85" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" fill="#3fb950">3</text>
+  <text x="405" y="112" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" font-weight="600" fill="#e6edf3">Validate</text>
+  <text x="405" y="130" text-anchor="middle" font-family="monospace" font-size="9" fill="#8b949e">compliance check</text>
+  <text x="405" y="142" text-anchor="middle" font-family="monospace" font-size="9" fill="#8b949e">+ ABI exports</text>
+
+  <line x1="470" y1="100" x2="495" y2="100" stroke="#484f58" stroke-width="2" marker-end="url(#arrow3)"/>
+
+  <!-- Step 4: Sign -->
+  <rect x="500" y="50" width="130" height="100" rx="10" fill="#161b22" stroke="#d29922" stroke-width="1.5"/>
+  <circle cx="565" cy="80" r="14" fill="#1c2128" stroke="#d29922" stroke-width="1.5"/>
+  <text x="565" y="85" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" fill="#d29922">4</text>
+  <text x="565" y="112" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" font-weight="600" fill="#e6edf3">Sign</text>
+  <text x="565" y="130" text-anchor="middle" font-family="monospace" font-size="9" fill="#8b949e">HD wallet key</text>
+  <text x="565" y="142" text-anchor="middle" font-family="monospace" font-size="9" fill="#8b949e">deploy authz</text>
+
+  <line x1="630" y1="100" x2="655" y2="100" stroke="#484f58" stroke-width="2" marker-end="url(#arrow3)"/>
+
+  <!-- Step 5: Protect -->
+  <rect x="660" y="50" width="130" height="100" rx="10" fill="#161b22" stroke="#f778ba" stroke-width="1.5"/>
+  <circle cx="725" cy="80" r="14" fill="#1c2128" stroke="#f778ba" stroke-width="1.5"/>
+  <text x="725" y="85" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" fill="#f778ba">5</text>
+  <text x="725" y="112" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" font-weight="600" fill="#e6edf3">Protect</text>
+  <text x="725" y="130" text-anchor="middle" font-family="monospace" font-size="9" fill="#8b949e">X25519 encrypt</text>
+  <text x="725" y="142" text-anchor="middle" font-family="monospace" font-size="9" fill="#8b949e">for recipient</text>
+
+  <!-- Checkmark -->
+  <line x1="790" y1="100" x2="815" y2="100" stroke="#484f58" stroke-width="2" marker-end="url(#arrow3)"/>
+
+  <rect x="820" y="60" width="60" height="80" rx="10" fill="#238636" fill-opacity="0.15" stroke="#3fb950" stroke-width="1.5"/>
+  <text x="850" y="107" text-anchor="middle" font-family="system-ui, sans-serif" font-size="26" fill="#3fb950">&#x2713;</text>
+
+  <!-- Bottom label -->
+  <text x="450" y="185" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#484f58">Each step is independently usable via the SDK API or the CLI</text>
+</svg>