space-data-module-sdk 0.5.21 → 0.6.0

package/README.md

@@ -176,8 +176,15 @@ This repo currently includes:
 - non-JS bundle reference clients in
   [`examples/single-file-bundle/go`](./examples/single-file-bundle/go) and
   [`examples/single-file-bundle/python`](./examples/single-file-bundle/python)
-- a reference Node host and sync `sdn_host` bridge for the first hostcall
-  surface
+- reference Node and browser hosts plus the legacy sync `sdn_host` bridge for
+  sync-safe guest hostcalls
+
+The current host/runtime contract is two-tiered:
+
+- raw guest `sdn_host` imports stay sync-only
+- generic async capabilities such as filesystem, network, IPFS, and protocol
+  adapters are exposed through `NodeHost`, `BrowserHost`, and the browser/module
+  harness APIs
 
 ## Runtime Targets
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.5.21",
+  "version": "0.6.0",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",
   "types": "./src/index.d.ts",
@@ -51,7 +51,7 @@
   ],
   "scripts": {
     "test": "node --test",
-    "test:host-surfaces": "node --test test/node-host.test.js test/host-abi.test.js",
+    "test:host-surfaces": "node --test test/node-host.test.js test/host-abi.test.js test/browser-host.test.js test/browser-module-harness.test.js test/testing-harness.test.js",
     "test:runtime-matrix": "SPACE_DATA_MODULE_SDK_ENABLE_RUNTIME_MATRIX=1 node --test test/runtime-matrix.test.js",
     "test:stream-ingest": "node --test test/runtime-host-stream-ingest.test.js",
     "test:module-stream": "node --test test/module-flatbuffer-stream-pump.test.js",

package/src/AGENTS.md

@@ -1,9 +1,9 @@
 # AGENTS
 
-Apply the root `AGENTS.md` first. This file routes source edits to the correct
-subsystem.
+Apply the root `AGENTS.md` first. This file is a map for module authors reading
+the SDK source, not a prompt to edit SDK internals by default.
 
-## Source Routing
+## Use `src/` As A Reference Map
 
 - `src/manifest`, `src/compliance`, `src/standards`: manifest shape, type refs,
   standards validation, and compliance warnings/errors.
@@ -23,11 +23,10 @@ subsystem.
 - `src/generated`: generated code. Do not hand-edit unless regeneration is part
   of the task and you update the generation path or fixtures as needed.
 
-## Working Rules
+## Author Rules
 
-- Keep module contracts portable unless the task is explicitly runtime-specific.
-- Prefer changes in the smallest subsystem that owns the behavior.
-- If a change crosses compiler, host, and docs, update each owner explicitly
-  rather than hiding policy in one layer.
-- Add or update tests near the owning subsystem and then wire them into the
-  repo-level verification set in `test/AGENTS.md`.
+- Prefer public APIs and examples over editing `src/*`.
+- Read the nearest child `AGENTS.md` to understand which source files define the
+  contract you are using.
+- Only edit internals here when the task explicitly says to change the SDK
+  standard for everyone.

package/src/auth/AGENTS.md

@@ -1,15 +1,13 @@
 # AGENTS
 
-You are in `src/auth`, which owns deployment authorization, signing helpers,
-and related record handling used by module distribution.
+This directory is the reference implementation for deployment authorization and
+signing helpers used by compliant module distribution.
 
-## Rules
+## What Authors Should Use It For
 
 - Keep signing and authorization flows deterministic and explicit.
 - Do not invent app-local signature records when a repo-level contract belongs
   here.
-- When auth changes affect transport or deployment plans, update the related
-  surfaces together rather than splitting incompatible changes across repos.
 
 ## Related Surfaces
 
@@ -18,8 +16,7 @@ and related record handling used by module distribution.
 - `test/transport-records.test.js`
 - `test/deployment-plan.test.js`
 
-## Check Before You Finish
+## Note
 
-- `npm test`
-- `npm run check:compliance`
-- `node --test test/transport-records.test.js test/deployment-plan.test.js`
+Use the exported helpers here rather than inventing your own signing records.
+Only edit this directory when you are intentionally changing the auth contract.

package/src/bundle/AGENTS.md

@@ -1,21 +1,17 @@
 # AGENTS
 
-You are in `src/bundle`, which owns `sds.bundle` and the wasm custom-section
-packaging rules.
+This directory is the reference implementation for `sds.bundle` and wasm
+custom-section packaging.
 
-## Rules
+## What Authors Should Use It For
 
 - `sds.bundle` is the single-file delivery format.
 - Put bundle data in a wasm custom section; do not append raw bytes after the
   wasm binary.
-- Keep parser, encoder, CLI behavior, vectors, and cross-language fixtures in
-  sync.
-- If the bundle contract changes, regenerate vectors and update the bundle docs
-  and demos in the same change.
+- Use the public bundle helpers and CLI from this repo rather than inventing a
+  custom one-file format.
 
-## Check Before You Finish
+## Note
 
-- `npm test`
-- `npm run check:compliance`
-- `node --test test/module-bundle.test.js test/module-bundle-vectors.test.js test/module-bundle-cli.test.js test/module-bundle-go.test.js test/module-bundle-python.test.js`
-- `npm run generate:vectors` when vectors or the contract changed
+Only edit this directory when you are intentionally changing bundle behavior for
+all consumers.

package/src/compiler/AGENTS.md

@@ -1,13 +1,18 @@
 # AGENTS
 
-Apply the root and `src/AGENTS.md` files first.
+Apply the root and `src/AGENTS.md` files first. This directory tells module
+authors how the compiler behaves.
 
-## Area Ownership
+## What Authors Should Take From This Directory
 
-This directory owns source-to-wasm compile behavior, manifest embedding, runtime
-target inference, toolchain integration, and canonical artifact layout.
+- `compileModuleFromSource(...)` and the CLI are the canonical ways to produce a
+  compliant artifact.
+- Manifest embedding and required exports are generated together with the wasm
+  bytes.
+- Shared browser/WasmEdge artifacts should land at
+  `dist/isomorphic/module.wasm`.
 
-## Compiler Rules
+## Compiler Rules Authors Should Follow
 
 - Preserve the canonical manifest accessor exports and validate them together
   with compiled wasm.
@@ -18,18 +23,15 @@ target inference, toolchain integration, and canonical artifact layout.
   imports.
 - Prefer repo-local Emscripten or `sdn-emception`. Do not assume Homebrew
   toolchains.
-- If you change runtime-target inference, keep the browser/WasmEdge shared path
-  on the standalone profile unless the docs and tests are updated deliberately.
 
-## Key Files
+## Key Files To Read
 
 - `compileModule.js`
 - `compileModuleFromSource.js`
 - `emception*.js`
 - `invokeGlue.js`
 
-## Verification
+## Note
 
-- `node --test test/module-sdk.test.js test/compliance.test.js`
-- `node --test test/browser-harness.test.js test/isomorphic-loader.test.js`
-- `node --test test/compiler-emception-subpath-export.test.js`
+Do not edit compiler internals just to build one module. Only change this
+directory when you are intentionally changing the repo-wide compile contract.

package/src/compliance/AGENTS.md

@@ -1,18 +1,16 @@
 # AGENTS
 
-You are in `src/compliance`, which defines what counts as a compliant module or
+This directory is the reference policy for what counts as a compliant module or
 artifact.
 
-## Rules
+## What Authors Should Use It For
 
-- Treat this directory as policy, not convenience code.
-- When tightening validation, update tests and error messages together so the
-  failure mode is actionable.
-- When relaxing validation, make sure the compiler, docs, and examples still
-  describe the broader contract accurately.
+- Use the CLI and public validation helpers to understand whether a manifest or
+  artifact is compliant.
+- Read this directory when you need to know why a module was rejected.
+- Prefer fixing your module manifest or build output before changing policy here.
 
-## Check Before You Finish
+## Note
 
-- `npm test`
-- `npm run check:compliance`
-- `node --test test/module-sdk.test.js test/compliance.test.js`
+Only edit this directory when you are intentionally changing the compliance
+standard for all module authors.

package/src/host/AGENTS.md

@@ -1,14 +1,17 @@
 # AGENTS
 
-Apply the root and `src/AGENTS.md` files first.
+Apply the root and `src/AGENTS.md` files first. This directory explains the
+host/runtime boundary that compliant modules can rely on.
 
-## Area Ownership
+## What Authors Should Take From This Directory
 
-This directory owns the Node reference host, browser host, browser edge shims,
-WASI shims, the sync `sdn_host` ABI bridge, WasmEdge launch planning, and the
-isomorphic loader path.
+- The portable shared path is standalone WASI, optionally plus `sdn_host`.
+- Browser helpers here are host-side shims and harnesses, not proof that raw
+  WasmEdge-native guest imports are browser-portable.
+- The isomorphic loader and browser harness show how the same artifact is meant
+  to run in both places.
 
-## Host Rules
+## Host Rules Authors Should Follow
 
 - Shared browser/WasmEdge artifacts must stay within standalone WASI plus the
   optional `sdn_host` bridge. Raw WasmEdge-native extension imports are not
@@ -20,7 +23,7 @@ isomorphic loader path.
 - Scope host capabilities tightly: filesystem roots, network allowlists, TLS,
   exec, timers, and crypto should stay explicit.
 
-## Key Files
+## Key Files To Read
 
 - `abi.js`
 - `browserEdgeShims.js`
@@ -29,11 +32,7 @@ isomorphic loader path.
 - `nodeHost.js`
 - `wasiShim.js`
 
-## Verification
+## Note
 
-- `node --test test/node-host.test.js test/host-abi.test.js`
-- `node --test test/browser-harness.test.js test/isomorphic-loader.test.js`
-- `node --test test/process-invoke.test.js`
-- `node --test test/wasmedge-runner-build.test.js`
-- `node --test test/wasmedge-runner-runtime.test.js` when WasmEdge behavior is
-  part of the change
+Prefer using the exported host and harness surfaces rather than editing these
+files unless the task is explicitly to change the SDK host contract.

package/src/host/abi.js

@@ -7,7 +7,7 @@ export const DEFAULT_HOSTCALL_IMPORT_MODULE = "sdn_host";
 export const HOSTCALL_STATUS_OK = 0;
 export const HOSTCALL_STATUS_ERROR = 1;
 
-export const NodeHostSyncHostcallOperations = Object.freeze([
+export const SyncHostcallOperations = Object.freeze([
   "host.runtimeTarget",
   "host.listCapabilities",
   "host.listSupportedCapabilities",
@@ -22,6 +22,7 @@ export const NodeHostSyncHostcallOperations = Object.freeze([
   "schedule.next",
   "filesystem.resolvePath",
 ]);
+export const NodeHostSyncHostcallOperations = SyncHostcallOperations;
 
 function assertNonEmptyString(value, label) {
   const normalized = String(value ?? "").trim();
@@ -149,7 +150,7 @@ function encodeHostcallValue(value) {
   return value;
 }
 
-export function dispatchNodeHostSyncOperation(host, operation, params = null) {
+export function dispatchHostSyncOperation(host, operation, params = null) {
   const normalized = assertNonEmptyString(operation, "Hostcall operation");
   switch (normalized) {
     case "host.runtimeTarget":
@@ -185,12 +186,39 @@ export function dispatchNodeHostSyncOperation(host, operation, params = null) {
   }
 }
 
+export function dispatchNodeHostSyncOperation(host, operation, params = null) {
+  return dispatchHostSyncOperation(host, operation, params);
+}
+
 export function createNodeHostSyncDispatcher(host) {
   if (!host || typeof host !== "object") {
     throw new TypeError("createNodeHostSyncDispatcher requires a host object.");
   }
   return (operation, params = null) =>
-    dispatchNodeHostSyncOperation(host, operation, params);
+    dispatchHostSyncOperation(host, operation, params);
+}
+
+export function createHostSyncDispatcher(host) {
+  return createNodeHostSyncDispatcher(host);
+}
+
+export async function dispatchHostOperation(host, operation, params = null) {
+  if (!host || typeof host !== "object") {
+    throw new TypeError("dispatchHostOperation requires a host object.");
+  }
+  const normalized = assertNonEmptyString(operation, "Host operation");
+  if (typeof host.invoke === "function") {
+    return host.invoke(normalized, params);
+  }
+  return dispatchHostSyncOperation(host, normalized, params);
+}
+
+export function createAsyncHostDispatcher(host) {
+  if (!host || typeof host !== "object") {
+    throw new TypeError("createAsyncHostDispatcher requires a host object.");
+  }
+  return (operation, params = null) =>
+    dispatchHostOperation(host, operation, params);
 }
 
 export function createJsonHostcallBridge(options = {}) {

package/src/host/browserEdgeShims.js

@@ -346,6 +346,10 @@ export function createBrowserEdgeShims(options = {}) {
     WebSocket: options.WebSocket ?? globalThis.WebSocket,
     crypto: options.crypto ?? globalThis.crypto,
     performance: options.performance ?? globalThis.performance,
+    network: options.network ?? null,
+    ipfs: options.ipfs ?? null,
+    protocolHandle: options.protocolHandle ?? null,
+    protocolDial: options.protocolDial ?? null,
     filesystem:
       options.filesystem ??
       createMemoryFilesystemEdgeShim({

package/src/host/browserHost.js

@@ -20,7 +20,11 @@ export const BrowserHostSupportedCapabilities = Object.freeze([
   "schedule_cron",
   "http",
   "websocket",
+  "network",
   "filesystem",
+  "ipfs",
+  "protocol_handle",
+  "protocol_dial",
   "context_read",
   "context_write",
   "crypto_hash",
@@ -39,11 +43,13 @@ export const BrowserHostSupportedOperations = Object.freeze([
   "clock.monotonicNow",
   "clock.nowIso",
   "random.bytes",
+  "timers.delay",
   "schedule.parse",
   "schedule.matches",
   "schedule.next",
   "http.request",
   "websocket.exchange",
+  "network.request",
   "filesystem.resolvePath",
   "filesystem.readFile",
   "filesystem.writeFile",
@@ -53,6 +59,10 @@ export const BrowserHostSupportedOperations = Object.freeze([
   "filesystem.readdir",
   "filesystem.stat",
   "filesystem.rename",
+  "ipfs.invoke",
+  "protocol_handle.register",
+  "protocol_handle.unregister",
+  "protocol_dial.dial",
   "context.get",
   "context.set",
   "context.delete",
@@ -73,6 +83,46 @@ export class BrowserHostCapabilityError extends Error {
   }
 }
 
+function normalizeBrowserNetworkTransport(params = {}) {
+  const explicit = String(
+    params.transport ?? params.kind ?? params.request?.transport ?? "",
+  )
+    .trim()
+    .toLowerCase();
+  if (explicit) {
+    return explicit;
+  }
+  const candidateUrl = params.url ?? params.request?.url ?? null;
+  if (candidateUrl) {
+    const protocol = new URL(candidateUrl, "https://browser-host.invalid")
+      .protocol.toLowerCase();
+    if (protocol === "http:" || protocol === "https:") {
+      return "http";
+    }
+    if (protocol === "ws:" || protocol === "wss:") {
+      return "websocket";
+    }
+  }
+  throw new Error(
+    'network.request requires a transport value such as "http" or "websocket".',
+  );
+}
+
+async function invokeAdapterMethod(adapter, methodName, params, label) {
+  if (!adapter || typeof adapter !== "object") {
+    throw new Error(`${label} adapter is not configured for this host.`);
+  }
+  if (typeof adapter[methodName] === "function") {
+    return adapter[methodName](params);
+  }
+  if (typeof adapter.invoke === "function") {
+    return adapter.invoke(methodName, params);
+  }
+  throw new Error(
+    `${label} adapter does not implement "${methodName}" or invoke().`,
+  );
+}
+
 export class BrowserHost {
   constructor(options = {}) {
     this.runtimeTarget = RuntimeTarget.BROWSER;
@@ -86,6 +136,11 @@ export class BrowserHost {
       WebSocket: options.WebSocket ?? options.edgeShims?.WebSocket,
       crypto: options.crypto ?? options.edgeShims?.crypto,
       performance: options.performance ?? options.edgeShims?.performance,
+      network: options.network ?? options.edgeShims?.network,
+      ipfs: options.ipfs ?? options.edgeShims?.ipfs,
+      protocolHandle:
+        options.protocolHandle ?? options.edgeShims?.protocolHandle,
+      protocolDial: options.protocolDial ?? options.edgeShims?.protocolDial,
       filesystem: options.filesystem ?? options.edgeShims?.filesystem,
       filesystemRoot: options.filesystemRoot ?? options.edgeShims?.filesystemRoot,
     });
@@ -97,6 +152,10 @@ export class BrowserHost {
     const fetchImpl = edgeShims.fetch;
     const WebSocketImpl = edgeShims.WebSocket;
     const filesystem = edgeShims.filesystem;
+    const networkAdapter = edgeShims.network;
+    const ipfsAdapter = edgeShims.ipfs;
+    const protocolHandleAdapter = edgeShims.protocolHandle;
+    const protocolDialAdapter = edgeShims.protocolDial;
 
     this._grantedCapabilities = granted;
     this._contextStore = options.contextStore ?? new Map();
@@ -239,6 +298,73 @@ export class BrowserHost {
       },
     });
 
+    this.network = Object.freeze({
+      request: async (params = {}) => {
+        this.#assertCapability("network", "network.request");
+        const transport = normalizeBrowserNetworkTransport(params);
+        const request = params.request ?? params;
+        if (transport === "http") {
+          return this.http.request(request);
+        }
+        if (transport === "websocket") {
+          return this.websocket.exchange(request);
+        }
+        if (networkAdapter) {
+          return invokeAdapterMethod(networkAdapter, "request", {
+            ...request,
+            transport,
+          }, "network");
+        }
+        throw new Error(
+          `Browser host does not support network transport "${transport}".`,
+        );
+      },
+    });
+
+    this.ipfs = Object.freeze({
+      invoke: async (params = {}) => {
+        this.#assertCapability("ipfs", "ipfs.invoke");
+        const operation = String(params.operation ?? "invoke").trim();
+        if (!operation) {
+          throw new Error("ipfs.invoke requires a non-empty operation.");
+        }
+        return invokeAdapterMethod(ipfsAdapter, operation, params, "ipfs");
+      },
+    });
+
+    this.protocolHandle = Object.freeze({
+      register: async (params = {}) => {
+        this.#assertCapability("protocol_handle", "protocol_handle.register");
+        return invokeAdapterMethod(
+          protocolHandleAdapter,
+          "register",
+          params,
+          "protocol_handle",
+        );
+      },
+      unregister: async (params = {}) => {
+        this.#assertCapability("protocol_handle", "protocol_handle.unregister");
+        return invokeAdapterMethod(
+          protocolHandleAdapter,
+          "unregister",
+          params,
+          "protocol_handle",
+        );
+      },
+    });
+
+    this.protocolDial = Object.freeze({
+      dial: async (params = {}) => {
+        this.#assertCapability("protocol_dial", "protocol_dial.dial");
+        return invokeAdapterMethod(
+          protocolDialAdapter,
+          "dial",
+          params,
+          "protocol_dial",
+        );
+      },
+    });
+
     this.context = Object.freeze({
       get: (scope, key) => {
         this.#assertCapability("context_read", "context.get");
@@ -378,17 +504,125 @@ export class BrowserHost {
   }
 
   hasCapability(capability) {
-    return this._grantedCapabilities.has(capability);
+    const normalized = String(capability ?? "").trim();
+    return (
+      this._grantedCapabilities.has(normalized) ||
+      (this._grantedCapabilities.has("network") &&
+        ["http", "websocket"].includes(normalized))
+    );
   }
 
   assertCapability(capability, operation) {
     this.#assertCapability(capability, operation);
   }
 
+  async invoke(operation, params = {}) {
+    const normalized = String(operation ?? "").trim();
+    switch (normalized) {
+      case "host.runtimeTarget":
+        return this.runtimeTarget;
+      case "host.listCapabilities":
+        return this.listCapabilities();
+      case "host.listSupportedCapabilities":
+        return this.listSupportedCapabilities();
+      case "host.listOperations":
+        return this.listOperations();
+      case "host.hasCapability":
+        return this.hasCapability(params.capability);
+      case "clock.now":
+        return this.clock.now();
+      case "clock.monotonicNow":
+        return this.clock.monotonicNow();
+      case "clock.nowIso":
+        return this.clock.nowIso();
+      case "random.bytes":
+        return this.random.bytes(params.length);
+      case "timers.delay":
+        return this.timers.delay(params.ms ?? params.delayMs ?? 0);
+      case "schedule.parse":
+        return this.schedule.parse(params.expression);
+      case "schedule.matches":
+        return this.schedule.matches(params.expression, params.date);
+      case "schedule.next":
+        return this.schedule.next(params.expression, params.from);
+      case "http.request":
+        return this.http.request(params);
+      case "websocket.exchange":
+        return this.websocket.exchange(params);
+      case "network.request":
+        return this.network.request(params);
+      case "filesystem.resolvePath":
+        return this.filesystem.resolvePath(params.path);
+      case "filesystem.readFile":
+        return this.filesystem.readFile(params.path, {
+          encoding: params.encoding,
+        });
+      case "filesystem.writeFile":
+        return this.filesystem.writeFile(params.path, params.value, {
+          encoding: params.encoding,
+        });
+      case "filesystem.appendFile":
+        return this.filesystem.appendFile(params.path, params.value, {
+          encoding: params.encoding,
+        });
+      case "filesystem.deleteFile":
+        return this.filesystem.deleteFile(params.path);
+      case "filesystem.mkdir":
+        return this.filesystem.mkdir(params.path, {
+          recursive: params.recursive,
+        });
+      case "filesystem.readdir":
+        return this.filesystem.readdir(params.path);
+      case "filesystem.stat":
+        return this.filesystem.stat(params.path);
+      case "filesystem.rename":
+        return this.filesystem.rename(params.fromPath, params.toPath);
+      case "ipfs.invoke":
+        return this.ipfs.invoke(params);
+      case "protocol_handle.register":
+        return this.protocolHandle.register(params);
+      case "protocol_handle.unregister":
+        return this.protocolHandle.unregister(params);
+      case "protocol_dial.dial":
+        return this.protocolDial.dial(params);
+      case "context.get":
+        return this.context.get(params.scope, params.key);
+      case "context.set":
+        return this.context.set(params.scope, params.key, params.value);
+      case "context.delete":
+        return this.context.delete(params.scope, params.key);
+      case "context.listKeys":
+        return this.context.listKeys(params.scope);
+      case "context.listScopes":
+        return this.context.listScopes();
+      case "crypto.sha256":
+        return this.crypto.sha256(params.value ?? params.bytes);
+      case "crypto.sha512":
+        return this.crypto.sha512(params.value ?? params.bytes);
+      case "crypto.aesGcmEncrypt":
+        return this.crypto.aesGcmEncrypt(params);
+      case "crypto.aesGcmDecrypt":
+        return this.crypto.aesGcmDecrypt(params);
+      default:
+        throw new Error(`Unknown browser host operation "${normalized}".`);
+    }
+  }
+
   // --- Private ---
 
   #assertCapability(capability, operation) {
-    if (!this._grantedCapabilities.has(capability)) {
+    const normalized = String(capability ?? "").trim();
+    const networkBackedCapabilities = new Set([
+      "http",
+      "websocket",
+    ]);
+    if (
+      !this._grantedCapabilities.has(normalized) &&
+      !(
+        this._grantedCapabilities.has("network") &&
+        networkBackedCapabilities.has(normalized)
+      )
+    ) {
       throw new BrowserHostCapabilityError(capability, operation);
     }
   }

package/src/host/isomorphicLoader.js

@@ -13,11 +13,25 @@ import {
   createBrowserModuleHarness,
   detectArtifactProfile,
 } from "../testing/browserModuleHarness.js";
+import { dispatchHostOperation } from "./abi.js";
 
 const isBrowser =
   typeof globalThis.window !== "undefined" &&
   typeof globalThis.document !== "undefined";
 
+function attachHostDispatch(harness, host) {
+  if (!host || typeof host !== "object") {
+    return harness;
+  }
+  return {
+    ...harness,
+    host,
+    async callHost(operation, params = {}) {
+      return dispatchHostOperation(host, operation, params);
+    },
+  };
+}
+
 async function createWasmEdgeCommandHarness(options = {}) {
   const [
     { spawn },
@@ -175,14 +189,18 @@ export async function loadModule(options = {}) {
         (inspection.profile === "standalone" || inspection.profile === "sdn-abi") &&
         inspection.exports.includes("_start")
       ) {
-        return createWasmEdgeCommandHarness(options);
+        return attachHostDispatch(
+          await createWasmEdgeCommandHarness(options),
+          options.host ?? null,
+        );
       }
     }
 
-    return createModuleHarness({
-      runtime: {
-        kind: "wasmedge",
-        wasmPath: source,
+    return attachHostDispatch(
+      await createModuleHarness({
+        runtime: {
+          kind: "wasmedge",
+          wasmPath: source,
         wasmEdgeBinary: options.wasmEdgeBinary,
         wasmEdgeRunnerBinary: options.wasmEdgeRunnerBinary,
         enableThreads: options.enableThreads,
@@ -191,23 +209,28 @@ export async function loadModule(options = {}) {
         hostProfile: options.hostProfile,
         modules: options.modules,
         defaultModuleId: options.defaultModuleId,
-        metadata: options.metadata,
-      },
-    });
+          metadata: options.metadata,
+        },
+      }),
+      options.host ?? null,
+    );
   }
 
-  return createModuleHarness({
-    runtime: {
-      kind: runtimeKind,
-      command: options.command ?? runtimeKind,
-      args: options.args ?? [source],
-      env: options.env,
-      cwd: options.cwd,
-      hostProfile: options.hostProfile,
-      modules: options.modules,
-      defaultModuleId: options.defaultModuleId,
-    },
-  });
+  return attachHostDispatch(
+    await createModuleHarness({
+      runtime: {
+        kind: runtimeKind,
+        command: options.command ?? runtimeKind,
+        args: options.args ?? [source],
+        env: options.env,
+        cwd: options.cwd,
+        hostProfile: options.hostProfile,
+        modules: options.modules,
+        defaultModuleId: options.defaultModuleId,
+      },
+    }),
+    options.host ?? null,
+  );
 }
 
 /**

package/src/host/nodeHost.js

@@ -46,10 +46,14 @@ export const NodeHostSupportedCapabilities = Object.freeze([
   "http",
   "websocket",
   "mqtt",
+  "network",
   "filesystem",
   "tcp",
   "udp",
   "tls",
+  "ipfs",
+  "protocol_handle",
+  "protocol_dial",
   "context_read",
   "context_write",
   "crypto_hash",
@@ -75,6 +79,7 @@ export const NodeHostSupportedOperations = Object.freeze([
   "websocket.exchange",
   "mqtt.publish",
   "mqtt.subscribeOnce",
+  "network.request",
   "filesystem.resolvePath",
   "filesystem.readFile",
   "filesystem.writeFile",
@@ -87,6 +92,10 @@ export const NodeHostSupportedOperations = Object.freeze([
   "tcp.request",
   "udp.request",
   "tls.request",
+  "ipfs.invoke",
+  "protocol_handle.register",
+  "protocol_handle.unregister",
+  "protocol_dial.dial",
   "exec.execFile",
   "context.get",
   "context.set",
@@ -229,6 +238,45 @@ function normalizeAllowedPorts(ports, label, { allowZero = false } = {}) {
   return normalized;
 }
 
+function normalizeNetworkTransport(params = {}) {
+  const explicit = String(
+    params.transport ?? params.kind ?? params.request?.transport ?? "",
+  )
+    .trim()
+    .toLowerCase();
+  if (explicit) {
+    return explicit;
+  }
+  const candidateUrl = params.url ?? params.request?.url ?? null;
+  if (candidateUrl) {
+    const protocol = new URL(candidateUrl).protocol.toLowerCase();
+    if (protocol === "http:" || protocol === "https:") {
+      return "http";
+    }
+    if (protocol === "ws:" || protocol === "wss:") {
+      return "websocket";
+    }
+  }
+  throw new Error(
+    'network.request requires a transport value such as "http", "tcp", or "websocket".',
+  );
+}
+
+async function invokeAdapterMethod(adapter, methodName, params, label) {
+  if (!adapter || typeof adapter !== "object") {
+    throw new Error(`${label} adapter is not configured for this host.`);
+  }
+  if (typeof adapter[methodName] === "function") {
+    return adapter[methodName](params);
+  }
+  if (typeof adapter.invoke === "function") {
+    return adapter.invoke(methodName, params);
+  }
+  throw new Error(
+    `${label} adapter does not implement "${methodName}" or invoke().`,
+  );
+}
+
 function normalizeFilesystemRoot(rootPath) {
   return path.resolve(String(rootPath ?? process.cwd()));
 }
@@ -1397,6 +1445,10 @@ export class NodeHost {
     );
     this.fetch = options.fetch ?? globalThis.fetch;
     this.WebSocket = options.WebSocket ?? globalThis.WebSocket;
+    this._networkAdapter = options.network ?? null;
+    this._ipfsAdapter = options.ipfs ?? null;
+    this._protocolHandleAdapter = options.protocolHandle ?? null;
+    this._protocolDialAdapter = options.protocolDial ?? null;
     if (typeof this.fetch !== "function") {
       throw new TypeError(
         "A fetch implementation is required to create a Node host.",
@@ -1550,6 +1602,40 @@ export class NodeHost {
         }),
     });
 
+    this.network = Object.freeze({
+      request: async (params = {}) =>
+        this.#withCapability("network", "network.request", async () => {
+          const transport = normalizeNetworkTransport(params);
+          const request = params.request ?? params;
+          switch (transport) {
+            case "http":
+              return this.http.request(request);
+            case "websocket":
+              return this.websocket.exchange(request);
+            case "mqtt":
+              return request.subscribe === true
+                ? this.mqtt.subscribeOnce(request)
+                : this.mqtt.publish(request);
+            case "tcp":
+              return this.tcp.request(request);
+            case "udp":
+              return this.udp.request(request);
+            case "tls":
+              return this.tls.request(request);
+            default:
+              if (this._networkAdapter) {
+                return invokeAdapterMethod(this._networkAdapter, "request", {
+                  ...request,
+                  transport,
+                }, "network");
+              }
+              throw new Error(
+                `Node host does not support network transport "${transport}".`,
+              );
+          }
+        }),
+    });
+
     this.mqtt = Object.freeze({
       publish: async (mqttOptions = {}) =>
         this.#withCapability("mqtt", "mqtt.publish", async () => {
@@ -1825,6 +1911,56 @@ export class NodeHost {
           this._contextStore.listScopes(),
         ),
     });
+
+    this.ipfs = Object.freeze({
+      invoke: async (params = {}) =>
+        this.#withCapability("ipfs", "ipfs.invoke", async () => {
+          const operation = String(params.operation ?? "invoke").trim();
+          if (!operation) {
+            throw new Error("ipfs.invoke requires a non-empty operation.");
+          }
+          return invokeAdapterMethod(this._ipfsAdapter, operation, params, "ipfs");
+        }),
+    });
+
+    this.protocolHandle = Object.freeze({
+      register: async (params = {}) =>
+        this.#withCapability(
+          "protocol_handle",
+          "protocol_handle.register",
+          async () =>
+            invokeAdapterMethod(
+              this._protocolHandleAdapter,
+              "register",
+              params,
+              "protocol_handle",
+            ),
+        ),
+      unregister: async (params = {}) =>
+        this.#withCapability(
+          "protocol_handle",
+          "protocol_handle.unregister",
+          async () =>
+            invokeAdapterMethod(
+              this._protocolHandleAdapter,
+              "unregister",
+              params,
+              "protocol_handle",
+            ),
+        ),
+    });
+
+    this.protocolDial = Object.freeze({
+      dial: async (params = {}) =>
+        this.#withCapability("protocol_dial", "protocol_dial.dial", async () =>
+          invokeAdapterMethod(
+            this._protocolDialAdapter,
+            "dial",
+            params,
+            "protocol_dial",
+          ),
+        ),
+    });
   }
 
   listCapabilities() {
@@ -1840,11 +1976,26 @@ export class NodeHost {
   }
 
   hasCapability(capability) {
-    return this._grantedCapabilities.has(String(capability ?? "").trim());
+    const normalized = String(capability ?? "").trim();
+    return (
+      this._grantedCapabilities.has(normalized) ||
+      (this._grantedCapabilities.has("network") &&
+        ["http", "websocket", "mqtt", "tcp", "udp", "tls"].includes(
+          normalized,
+        ))
+    );
   }
 
   assertCapability(capability, operation = null) {
     const normalized = assertNonEmptyString(capability, "Capability id");
+    const networkBackedCapabilities = new Set([
+      "http",
+      "websocket",
+      "mqtt",
+      "tcp",
+      "udp",
+      "tls",
+    ]);
     if (!this._supportedCapabilities.has(normalized)) {
       throw new HostCapabilityError(
         `Capability "${normalized}" is not supported by the reference Node host.`,
@@ -1855,7 +2006,13 @@ export class NodeHost {
         },
       );
     }
-    if (!this._grantedCapabilities.has(normalized)) {
+    if (
+      !this._grantedCapabilities.has(normalized) &&
+      !(
+        this._grantedCapabilities.has("network") &&
+        networkBackedCapabilities.has(normalized)
+      )
+    ) {
       throw new HostCapabilityError(
         `Capability "${normalized}" is not granted for this Node host.`,
         {
@@ -1871,6 +2028,16 @@ export class NodeHost {
   async invoke(operation, params = {}) {
     const normalized = assertNonEmptyString(operation, "Host operation");
     switch (normalized) {
+      case "host.runtimeTarget":
+        return this.runtimeTarget;
+      case "host.listCapabilities":
+        return this.listCapabilities();
+      case "host.listSupportedCapabilities":
+        return this.listSupportedCapabilities();
+      case "host.listOperations":
+        return this.listOperations();
+      case "host.hasCapability":
+        return this.hasCapability(params.capability);
       case "clock.now":
         return this.clock.now();
       case "clock.monotonicNow":
@@ -1897,6 +2064,8 @@ export class NodeHost {
         return this.mqtt.publish(params);
       case "mqtt.subscribeOnce":
         return this.mqtt.subscribeOnce(params);
+      case "network.request":
+        return this.network.request(params);
       case "filesystem.resolvePath":
         return this.filesystem.resolvePath(params.path);
       case "filesystem.readFile":
@@ -1929,6 +2098,14 @@ export class NodeHost {
         return this.udp.request(params);
       case "tls.request":
         return this.tls.request(params);
+      case "ipfs.invoke":
+        return this.ipfs.invoke(params);
+      case "protocol_handle.register":
+        return this.protocolHandle.register(params);
+      case "protocol_handle.unregister":
+        return this.protocolHandle.unregister(params);
+      case "protocol_dial.dial":
+        return this.protocolDial.dial(params);
       case "exec.execFile":
         return this.exec.execFile(params);
       case "context.get":

package/src/manifest/AGENTS.md

@@ -1,18 +1,15 @@
 # AGENTS
 
-You are in `src/manifest`, which owns the manifest schema codecs and
-normalization rules.
+This directory is the reference implementation for manifest encoding,
+normalization, and round-trip behavior.
 
-## Rules
+## What Authors Should Use It For
 
 - Keep manifest encode/decode round-trips stable.
 - Prefer canonical SDS schema names and file identifiers; do not add repo-local
   aliases when a standards name already exists.
-- If you change a manifest field or normalization rule, update the compiler,
-  compliance checks, and any affected examples/tests together.
 
-## Check Before You Finish
+## Note
 
-- `npm test`
-- `npm run check:compliance`
-- `node --test test/module-sdk.test.js test/compliance.test.js`
+Use the public manifest helpers from this repo to build manifests. Only edit
+this directory when you are intentionally changing the manifest standard.

package/src/runtime-host/AGENTS.md

@@ -1,12 +1,15 @@
 # AGENTS
 
-Apply the root and `src/AGENTS.md` files first.
+Apply the root and `src/AGENTS.md` files first. This directory shows the
+host-owned storage and ingest path available to module authors.
 
-## Area Ownership
+## What Authors Should Take From This Directory
 
-This directory owns the canonical runtime-host storage model: row handles,
-region handles, FlatSQL-backed storage, and binary FlatBuffer ingest on the host
-side.
+- Host-owned durable identity is `(schemaFileId, rowId)` for rows and
+  `(regionId, recordIndex)` for aligned-binary regions.
+- The canonical ingest path is direct FlatBuffer bytes, not JSON.
+- If the host owns persistence, use these helpers. If a module owns state, keep
+  the stream binary and use the resident-module pump path from `src/testing`.
 
 ## Storage And Streaming Rules
 
@@ -19,14 +22,13 @@ side.
 - If a resident module owns state, keep the stream binary and push into the
   module through the harness/pump path rather than inventing JSON wrappers.
 
-## Key Files
+## Key Files To Read
 
 - `flatbufferStreamIngestor.js`
 - `flatsqlRuntimeStore.js`
 - `index.js`
 
-## Verification
+## Note
 
-- `npm run test:stream-ingest`
-- `node --test test/flatsql-local-node.test.js`
-- `npm run benchmark:stream-1gib` for large-stream changes
+Do not edit this directory just to store data for one module. Use the exported
+helpers unless you are intentionally changing the runtime-host contract.

package/src/runtime-host/index.js

@@ -3,15 +3,71 @@ import { createFlatBufferStreamIngestor } from "./flatbufferStreamIngestor.js";
 import { createRuntimeRegionStore } from "./runtimeRegionStore.js";
 import { createModuleRegistry } from "./moduleRegistry.js";
 
+function normalizeCapabilityId(capability) {
+  const normalized = String(capability ?? "").trim();
+  if (!normalized) {
+    throw new TypeError("Capability id is required.");
+  }
+  return normalized;
+}
+
+function createCapabilityRegistry(capabilities = {}) {
+  const entries =
+    capabilities instanceof Map
+      ? capabilities.entries()
+      : Object.entries(capabilities ?? {});
+  const registry = new Map();
+  for (const [capability, adapter] of entries) {
+    registry.set(normalizeCapabilityId(capability), adapter);
+  }
+  return registry;
+}
+
 export function createRuntimeHost(options = {}) {
   const rows = options.rows ?? createFlatSqlRuntimeStore();
   const regions = options.regions ?? createRuntimeRegionStore();
   const moduleRegistry = options.moduleRegistry ?? createModuleRegistry();
+  const capabilities = createCapabilityRegistry(options.capabilities);
 
   return {
     rows,
     regions,
     moduleRegistry,
+    listCapabilities() {
+      return Array.from(capabilities.keys()).sort();
+    },
+    getCapability(capability) {
+      return capabilities.get(normalizeCapabilityId(capability)) ?? null;
+    },
+    registerCapability(capability, adapter) {
+      const normalized = normalizeCapabilityId(capability);
+      capabilities.set(normalized, adapter);
+      return adapter;
+    },
+    unregisterCapability(capability) {
+      return capabilities.delete(normalizeCapabilityId(capability));
+    },
+    async invokeCapability(operation, params = {}) {
+      const normalized = normalizeCapabilityId(operation);
+      const separator = normalized.indexOf(".");
+      const capabilityId =
+        separator >= 0 ? normalized.slice(0, separator) : normalized;
+      const methodId =
+        separator >= 0 ? normalized.slice(separator + 1) : "invoke";
+      const adapter = capabilities.get(capabilityId);
+      if (!adapter || typeof adapter !== "object") {
+        throw new Error(`Runtime host capability "${capabilityId}" is not registered.`);
+      }
+      if (typeof adapter[methodId] === "function") {
+        return adapter[methodId](params);
+      }
+      if (typeof adapter.invoke === "function") {
+        return adapter.invoke(methodId, params);
+      }
+      throw new Error(
+        `Runtime host capability "${capabilityId}" does not implement "${methodId}" or invoke().`,
+      );
+    },
   };
 }
 

package/src/testing/AGENTS.md

@@ -1,12 +1,15 @@
 # AGENTS
 
-Apply the root and `src/AGENTS.md` files first.
+Apply the root and `src/AGENTS.md` files first. This directory contains the
+author-facing harnesses and streaming helpers.
 
-## Area Ownership
+## What Authors Should Use From Here
 
-This directory owns SDK test harnesses and runtime-facing helper surfaces used
-by examples and downstream consumers: browser harnesses, generic process invoke
-clients, runtime-matrix helpers, and resident-module FlatBuffer pumps.
+- `createBrowserModuleHarness(...)` is the browser-side proof path for shared
+  standalone artifacts.
+- `createModuleHarness(...)` is the generic process-side harness.
+- `createModuleFlatBufferStreamPump(...)` is the canonical no-JSON path for
+  streaming size-prefixed FlatBuffer frames into a resident module instance.
 
 ## Harness Rules
 
@@ -19,15 +22,13 @@ clients, runtime-matrix helpers, and resident-module FlatBuffer pumps.
 - Avoid hiding stateful behavior inside one-off demos; if a harness contract is
   real, test it here.
 
-## Key Files
+## Key Files To Read
 
 - `browserModuleHarness.js`
 - `moduleFlatbufferStreamPump.js`
 - `processInvoke.js`
 
-## Verification
+## Note
 
-- `node --test test/browser-harness.test.js`
-- `node --test test/isomorphic-loader.test.js`
-- `npm run test:module-stream`
-- `node --test test/process-invoke.test.js`
+Use these helpers from your module repo or app harnesses. Only edit them when
+you are intentionally changing the SDK testing/runtime contract.

package/src/testing/browserModuleHarness.js

@@ -16,7 +16,8 @@ import { createBrowserWasiShim, WasiExitError } from "../host/wasiShim.js";
 import { createBrowserHost } from "../host/browserHost.js";
 import {
   createJsonHostcallBridge,
-  createNodeHostSyncDispatcher,
+  createHostSyncDispatcher,
+  dispatchHostOperation,
   DEFAULT_HOSTCALL_IMPORT_MODULE,
 } from "../host/abi.js";
 import {
@@ -90,7 +91,7 @@ async function instantiateBrowserModule(options = {}) {
   let instance = null;
   let bridge = null;
   if (needsHostBridge) {
-    const dispatch = createNodeHostSyncDispatcher(options.host);
+    const dispatch = createHostSyncDispatcher(options.host);
     bridge = createJsonHostcallBridge({
       dispatch,
       getMemory: () => instance.exports.memory,
@@ -238,6 +239,10 @@ export async function createBrowserModuleHarness(options = {}) {
     return decodePluginInvokeResponse(responseBytes);
   }
 
+  async function callHost(operation, params = {}) {
+    return dispatchHostOperation(host, operation, params);
+  }
+
   function readManifest() {
     const getBytesExport =
       instance.exports[DefaultManifestExports.pluginBytesSymbol];
@@ -267,6 +272,7 @@ export async function createBrowserModuleHarness(options = {}) {
     host,
     bridge,
     wasi,
+    callHost,
     invoke,
     invokeRaw,
     readManifest,

package/src/testing/index.js

@@ -120,7 +120,8 @@ const CapabilitySurfaceMatrix = Object.freeze({
     syncHostcall: false,
     nodeHostApi: true,
     notes: [
-      "The coarse network capability maps to host-side HTTP/TCP/UDP/TLS/WebSocket services today.",
+      "The coarse network capability maps to async host-side HTTP/TCP/UDP/TLS/WebSocket services.",
+      "Browser harnesses can await the same capability surface through BrowserHost.invoke().",
       "Pure WASI guests cannot reach that surface through the current sync hostcall ABI.",
       "WasmEdge provides non-blocking socket-oriented extensions that can serve as the standard server-side max-WASI target.",
     ],
@@ -198,6 +199,42 @@ const CapabilitySurfaceMatrix = Object.freeze({
       "WasmEdge TLS support provides a practical no-wrapper server-side target for guest HTTPS/TLS logic.",
     ],
   }),
+  ipfs: Object.freeze({
+    capability: "ipfs",
+    wasi: false,
+    standaloneWasi: false,
+    wasmedge: false,
+    syncHostcall: false,
+    nodeHostApi: true,
+    notes: [
+      "IPFS access is available through async host adapters and browser/module harness dispatch.",
+      "Pure WASM guests cannot reach that surface through the current sync hostcall ABI.",
+    ],
+  }),
+  protocol_handle: Object.freeze({
+    capability: "protocol_handle",
+    wasi: false,
+    standaloneWasi: false,
+    wasmedge: false,
+    syncHostcall: false,
+    nodeHostApi: true,
+    notes: [
+      "Protocol registration is available through async host adapters and browser/module harness dispatch.",
+      "Pure WASM guests cannot reach that surface through the current sync hostcall ABI.",
+    ],
+  }),
+  protocol_dial: Object.freeze({
+    capability: "protocol_dial",
+    wasi: false,
+    standaloneWasi: false,
+    wasmedge: false,
+    syncHostcall: false,
+    nodeHostApi: true,
+    notes: [
+      "Protocol dialing is available through async host adapters and browser/module harness dispatch.",
+      "Pure WASM guests cannot reach that surface through the current sync hostcall ABI.",
+    ],
+  }),
   context_read: Object.freeze({
     capability: "context_read",
     wasi: false,