space-data-module-sdk 0.8.11 → 0.8.12

package/README.md

@@ -241,6 +241,98 @@ treats that as the explicit "one binary for both" profile. That pair now
 defaults to a shared `single-thread` artifact so the compiled wasm can be loaded
 unchanged by the browser harness and the WasmEdge harness.
 
+### Composed flows derive their targets
+
+A COMPOSED flow artifact (`space-data-module flow compile`) does not declare
+its own `runtimeTargets` — it **derives** them, inside the universe a composed
+artifact can reach at all (`browser` + `wasmedge`; the flow runtime template is
+never a standalone `wasi` command, a `node` package, a `desktop` bundle or an
+`edge` worker). Two things narrow that universe:
+
+1. **Every part's declaration**, tested with `runtimeTargetSatisfies` — THE
+   SAME function every loader uses, so a declaration cannot mean one thing to
+   the compiler and another at the door. A flow runs only where all of its
+   parts run. A part that declares nothing constrains nothing. `wasi` is the
+   strict portability baseline rather than a fourth runtime, so a part
+   declaring it admits both legs — unless that part's own capabilities say
+   otherwise (`pipe` is in both the standalone-WASI subset and the
+   browser-incompatible set).
+2. **The capability union.** A capability in `BrowserIncompatibleCapabilityIds`
+   (`wallet_sign`, `tcp`, `storage_write`, …) drops `browser` regardless of what
+   anything declared, because the composition provably cannot run there. This is
+   the proof-based half: it catches the commonest manifest shape, a plugin that
+   carries such a capability and simply omits `runtimeTargets`.
+
+Outcomes:
+
+- All parts isomorphic, no browser-incompatible capability → the flow keeps
+  `["browser", "wasmedge"]`.
+- One WasmEdge-only part, or one browser-incompatible capability → the flow is
+  `["wasmedge"]`, its `buildArtifacts[].target` says `wasmedge`, and a
+  `narrowed-runtime-targets` warning names what cost it the browser. Losing a
+  runtime is never silent.
+- No shared runtime → `empty-runtime-target-intersection`, a hard error naming
+  the constraining plugins.
+
+This is what makes a host-only capability usable from a flow at all: the
+composed manifest is compliance-validated before the bake, and a
+browser-incompatible capability next to a `browser` target is a hard
+`capability-runtime-conflict`. Deriving the target set keeps that rule intact —
+the conflict still fires whenever a browser target is genuinely claimed — while
+letting the legitimate WasmEdge-only composition exist. `wallet_sign` gates
+`keyslot.unwrap`, so before this the hardcoded pair meant no flow could unwrap a
+host-held key at all.
+
+### Both legs refuse an artifact that is not theirs
+
+A legitimate single-leg artifact now exists, so every loader that stands for a
+runtime leg refuses one that declares itself out of scope — by name, quoting
+the declaration, never a silent skip and never a trap five frames deep inside a
+capability that leg cannot serve. The shared assert is
+`src/host/runtimeTargetGate.js`:
+
+| Loader | Leg |
+| --- | --- |
+| `createBrowserModuleHarness` | `browser` |
+| `createWorkerModuleHarness` | `browser`, checked before any worker is spawned |
+| `createIsomorphicFlowRuntimeHost` | `browser` (it mounts children in the browser harness) |
+| `createFlowRuntimeHost` | stated via `runtimeTarget`; defaults to `browser` in a real browser, ungated elsewhere |
+| `loadModule({runtimeKind: "wasmedge"})` | `wasmedge` |
+
+Both declarations are consulted — the caller-supplied manifest and the
+artifact's own embedded `$PLG` — and **the embedded one wins on conflict**,
+because that is what the artifact's signature covers. The refusal throws a
+`RuntimeTargetError` carrying `declaredTargets`, `leg` and `declarationSource`.
+
+A declaration that names the leg outright is trusted as written; the `wasi`
+baseline, which is an inference the SDK makes on the author's behalf, is
+additionally capability-checked. Declaration → trust the author; inference →
+prove it.
+
+**Consumer migration.** `createFlowRuntimeHost` is runtime-agnostic and only
+detects a real browser. If you drive a composed flow from Node — a flow test, a
+server-side runner — state the leg, or the mirror gate is principle rather than
+fact:
+
+```js
+const host = await createFlowRuntimeHost({
+  wasmSource: bytes,
+  runtimeTarget: "wasmedge",
+});
+```
+
+The tri-runtime parity gate reads the same declaration: a lane the artifact
+declared itself out of is scored `out-of-declared-scope`, skipped before it is
+launched, and recorded as evidence rather than compared. Without that, a
+correct refusal on the browser lane would have been counted as a P1
+cross-runtime divergence.
+
+Scoping is not a way to be certified without being run. An artifact in the
+gate's certified set that scopes itself out of every active lane fails
+(`artifact-out-of-every-lane`), and one that leaves fewer than two lanes to
+compare fails too (`artifact-not-cross-runtime-comparable`) — a single lane
+proves no parity, and one manifest string must never disarm the gate.
+
 ## WasmEdge Pthreads
 
 `space-data-module-sdk` is also the source of truth for module thread-model

package/bin/space-data-module.js

@@ -170,6 +170,28 @@ function parseArgs(argv) {
         });
         break;
       }
+      case "--artifact-lanes": {
+        // --artifact-lanes <id>=<lane,lane> — the GATE'S claim about which
+        // lanes an artifact owes evidence on. Without this the strongest of the
+        // three scoping rules ("the artifact does not pick its examiners") was
+        // reachable only from a gate manifest file, i.e. never for the
+        // cross-repo artifacts injected with --artifact, which are exactly the
+        // ones whose declarations this repo does not own.
+        const spec = requireValue(argv, ++index, value);
+        const eq = spec.indexOf("=");
+        if (eq < 1) {
+          throw new Error(
+            `--artifact-lanes expects <id>=<lane,lane>, got "${spec}"`,
+          );
+        }
+        options.expectedLanesById = options.expectedLanesById ?? {};
+        options.expectedLanesById[spec.slice(0, eq)] = spec
+          .slice(eq + 1)
+          .split(",")
+          .map((lane) => lane.trim())
+          .filter(Boolean);
+        break;
+      }
       case "--require-native-wasmedge":
         options.requireNativeWasmEdge = true;
         break;
@@ -264,6 +286,7 @@ async function runFlow(argv) {
         console.log(`  ${issue.severity.toUpperCase()} ${issue.code}: ${issue.message}`);
       }
       console.log(`  capabilities: [${check.capabilities.join(", ")}]`);
+      console.log(`  runtimeTargets: [${(check.runtimeTargets ?? []).join(", ")}]`);
       for (const node of check.nodes) {
         console.log(`  node ${node.nodeId}: ${node.pluginId}:${node.methodId} (${node.dispatchModel})`);
       }
@@ -307,6 +330,9 @@ async function runFlow(argv) {
   } else {
     console.log(`Wrote ${result.outputs.moduleWasmPath}`);
     console.log(`  capabilities: [${result.check.capabilities.join(", ")}]`);
+    console.log(
+      `  runtimeTargets: [${(result.manifest?.runtimeTargets ?? result.check.runtimeTargets ?? []).join(", ")}]`,
+    );
     for (const node of result.check.nodes) {
       console.log(`  node ${node.nodeId}: ${node.pluginId}:${node.methodId} (${node.dispatchModel})`);
     }
@@ -379,7 +405,13 @@ async function runParityGateCommand(argv) {
   );
   const report = await runParityGate({
     manifestPath: options.gateManifestPath,
-    extraArtifacts: options.extraArtifacts,
+    extraArtifacts: (options.extraArtifacts ?? []).map((artifact) => ({
+      ...artifact,
+      ...(options.expectedLanesById?.[artifact.id]
+        ? { expectedLanes: options.expectedLanesById[artifact.id] }
+        : {}),
+    })),
+    expectedLanesById: options.expectedLanesById,
     lanes: options.lanes,
     timeoutMs: options.timeoutMs,
     chromeBinary: options.chromeBinary,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",
   "types": "./src/index.d.ts",
@@ -55,6 +55,7 @@
       "default": "./src/host/isomorphicLoader.js"
     },
     "./host/browser-module": "./src/host/browserModuleHarness.js",
+    "./host/runtime-target-gate": "./src/host/runtimeTargetGate.js",
     "./host/node-builtin": "./src/host/nodeBuiltinSpecifier.js",
     "./host/worker-module": "./src/host/workerModuleHarness.js",
     "./testing/browser": "./src/testing/browser.js",

package/src/browser.js

@@ -23,10 +23,21 @@ export * from "./host/isomorphicLoaderBrowser.js";
 // Browser module hosts. These are runtime surface and live in src/host/;
 // nothing under src/testing/ is reachable from this entry.
 export {
+  assertBrowserRuntimeTarget,
   createBrowserModuleHarness,
   detectArtifactProfile,
   zeroWasmBytes,
   isSharedArrayBufferLike,
 } from "./host/browserModuleHarness.js";
+// The runtime-target gate is reachable so a consumer can catch the refusal by
+// CLASS (`error instanceof RuntimeTargetError`) rather than by matching a
+// message string, and can ask the same question the loaders ask before it
+// offers a module to a leg.
+export {
+  RuntimeTargetError,
+  runtimeTargetSatisfies,
+  resolveRuntimeTargetRefusal,
+  embeddedRuntimeTargets,
+} from "./host/runtimeTargetGate.js";
 export { createWorkerModuleHarness } from "./host/workerModuleHarness.js";
 export { createModuleFlatBufferStreamPump } from "./host/moduleFlatbufferStreamPump.js";

package/src/capabilities.js

@@ -47,3 +47,42 @@ export const StandaloneWasiCapabilityIds = Object.freeze([
   "filesystem",
   "pipe",
 ]);
+
+/**
+ * Capabilities a PORTABLE artifact may not claim against the canonical browser
+ * runtime target. The browser HOST can route several of these when the
+ * embedder injects an adapter (see BrowserHostSupportedCapabilities) — this
+ * list is the DECLARATION policy, not the dispatch table: a published module
+ * cannot assume its embedder wired one.
+ *
+ * It lives here, beside the other capability vocabularies, rather than inside
+ * the compliance module, because two browser-facing surfaces need it: the flow
+ * compiler (which subtracts `browser` from a composed artifact's derived
+ * runtimeTargets on exactly this list, so the compiler never stamps a target
+ * its own compliance pass would reject) and the runtime-target gate (which
+ * must not admit an artifact to a leg on the `wasi` portability baseline while
+ * it carries a capability that leg cannot serve).
+ */
+export const BrowserIncompatibleCapabilityIds = Object.freeze([
+  "pipe",
+  "network",
+  "tcp",
+  "udp",
+  "mqtt",
+  "tls",
+  "database",
+  "storage_write",
+  "protocol_dial",
+  "protocol_handle",
+  "process_exec",
+  "wallet_sign",
+  "ipfs",
+  "scene_access",
+  "entity_access",
+  "render_hooks",
+]);
+
+/** Which capabilities each runtime leg cannot serve. */
+export const LegIncompatibleCapabilityIds = Object.freeze({
+  browser: BrowserIncompatibleCapabilityIds,
+});

package/src/compliance/index.js

@@ -11,6 +11,7 @@ import {
   validatePluginManifest,
 } from "./pluginCompliance.js";
 import {
+  BrowserIncompatibleCapabilityIds,
   RecommendedCapabilityIds,
   StandaloneWasiCapabilityIds,
 } from "../capabilities.js";
@@ -48,6 +49,7 @@ export async function validateArtifactWithStandards(options = {}) {
 }
 
 export {
+  BrowserIncompatibleCapabilityIds,
   findManifestFiles,
   getWasmExportNames,
   getWasmExportNamesFromFile,

package/src/compliance/pluginCompliance.js

@@ -13,6 +13,7 @@ import {
   RuntimeTarget,
 } from "../runtime/constants.js";
 import {
+  BrowserIncompatibleCapabilityIds,
   RecommendedCapabilityIds,
   StandaloneWasiCapabilityIds,
 } from "../capabilities.js";
@@ -49,24 +50,7 @@ const ExternalInterfaceDirectionSet = new Set(
 const ExternalInterfaceKindSet = new Set(Object.values(ExternalInterfaceKind));
 const ProtocolRoleSet = new Set(Object.values(ProtocolRole));
 const ProtocolTransportKindSet = new Set(Object.values(ProtocolTransportKind));
-const BrowserIncompatibleCapabilitySet = new Set([
-  "pipe",
-  "network",
-  "tcp",
-  "udp",
-  "mqtt",
-  "tls",
-  "database",
-  "storage_write",
-  "protocol_dial",
-  "protocol_handle",
-  "process_exec",
-  "wallet_sign",
-  "ipfs",
-  "scene_access",
-  "entity_access",
-  "render_hooks",
-]);
+const BrowserIncompatibleCapabilitySet = new Set(BrowserIncompatibleCapabilityIds);
 const StandaloneWasiProtocolTransportKindSet = new Set([
   ProtocolTransportKind.WASI_PIPE,
 ]);

package/src/flow/flowCompiler.js

@@ -56,6 +56,7 @@ import {
 } from "../compiler/pthreadArtifactGuard.js";
 import { resolveWasiThreadsToolchain } from "../compiler/wasiThreadsToolchain.js";
 import {
+  BrowserIncompatibleCapabilityIds,
   validateArtifactWithStandards,
   validatePluginManifest,
 } from "../compliance/index.js";
@@ -66,6 +67,7 @@ import {
   payloadSchemaIdentitiesEqual,
 } from "../manifest/index.js";
 import { appendWasmCustomSection } from "../bundle/wasm.js";
+import { runtimeTargetSatisfies } from "../host/runtimeTargetGate.js";
 import { SDS_MANIFEST_SECTION_NAME } from "../bundle/constants.js";
 import { verifyModuleArtifact } from "../bundle/signing.js";
 import { DOMAIN_MODULE_PUBLICATION_V1 } from "../bundle/sigdomain.js";
@@ -162,6 +164,16 @@ export function flowEngineLinkage(flow) {
   );
 }
 
+// The runtimes a COMPOSED flow artifact can possibly reach. The flow runtime
+// template is baked once, as the isomorphic browser/WasmEdge artifact — it is
+// never a standalone `wasi` command, a `node` package, a `desktop` bundle, or
+// an `edge` worker, so those targets are not in the universe a composition can
+// claim. A node's own declaration can only ever SUBTRACT from this set.
+const COMPOSED_FLOW_RUNTIME_TARGET_UNIVERSE = Object.freeze([
+  "browser",
+  "wasmedge",
+]);
+
 const GUEST_LINK_OBJECT_FILENAME = "module-link.o";
 const GUEST_LINK_METADATA_FILENAME = "metadata.json";
 const GUEST_LINK_LINKED_DIRNAME = "guest-link-linked";
@@ -882,7 +894,9 @@ function collectComponentDependencies({ nodePluginIds, dependencies, issues, cap
         "warning",
         "unresolved-component-dependency",
         `Component dependency "${declared.pluginId}" (declared by "${declaredBy}") is not resolvable from the ` +
-          "dependency set; it is propagated into the bundle DEPENDENCIES but its capabilities cannot be verified.",
+          "dependency set; it is propagated into the bundle DEPENDENCIES but neither its capabilities nor its " +
+          "runtimeTargets can be verified — so it constrains neither the flow's capability union nor its " +
+          "derived runtime targets, and the composed artifact may claim a runtime this component cannot reach.",
         "flow.dependencies",
       );
     }
@@ -890,6 +904,174 @@ function collectComponentDependencies({ nodePluginIds, dependencies, issues, cap
   return [...components.values()].sort((a, b) => a.pluginId.localeCompare(b.pluginId));
 }
 
+const BROWSER_RUNTIME_TARGET = "browser";
+const BrowserIncompatibleCapabilitySet = new Set(
+  BrowserIncompatibleCapabilityIds,
+);
+
+function declaredRuntimeTargets(manifest) {
+  const declared = Array.isArray(manifest?.runtimeTargets)
+    ? manifest.runtimeTargets
+        .map((target) => String(target ?? "").trim().toLowerCase())
+        .filter(Boolean)
+    : [];
+  return declared.length > 0 ? declared : null;
+}
+
+/**
+ * collectFlowRuntimeTargets derives the COMPOSED artifact's runtimeTargets from
+ * its constituents instead of asserting a fixed pair.
+ *
+ * A flow runs only where ALL of its parts run, so the composition's target set
+ * is the INTERSECTION of the declared target sets of every node plugin and
+ * every resolved component dependency, taken inside the universe a composed
+ * artifact can reach at all (browser + WasmEdge). A part that declares no
+ * targets is unconstraining — it says nothing, so it subtracts nothing. The
+ * admission test is `runtimeTargetSatisfies`, THE SAME ONE every loader uses,
+ * so a declaration cannot mean one thing to the compiler and another at the
+ * door.
+ *
+ * The CAPABILITY UNION subtracts too. A declared target set is not the only
+ * way a part can be non-browser: a plugin that carries `wallet_sign` and
+ * simply omits `runtimeTargets` says nothing about where it runs, yet the
+ * composition provably cannot run in a browser, because compliance forbids
+ * exactly that capability against a browser target. Deriving only from the
+ * declarations left the commonest manifest shape re-creating the original
+ * defect — the compiler stamping a target its own compliance pass then
+ * rejects. So `browser` is also dropped whenever the flow's capability union
+ * meets `BrowserIncompatibleCapabilityIds`, and the diagnostic names the
+ * capability that cost it.
+ *
+ * This is the difference between a truthful manifest and a wish. The hardcoded
+ * ["browser","wasmedge"] made every composition claim the browser, which made
+ * `capability-runtime-conflict` fire on any flow containing a node with a
+ * browser-incompatible capability (wallet_sign, tcp, storage_write, …) — so a
+ * WasmEdge-only flow was not merely mislabelled, it was IMPOSSIBLE TO BAKE.
+ * Deriving the set keeps the real invariant intact (a browser-incompatible
+ * capability and a browser target still cannot coexist) while letting the
+ * legitimate WasmEdge-only composition exist.
+ */
+function collectFlowRuntimeTargets({
+  resolvedNodes,
+  componentDependencies,
+  dependencies,
+  capabilities,
+  issues,
+}) {
+  let targets = new Set(COMPOSED_FLOW_RUNTIME_TARGET_UNIVERSE);
+  // pluginId -> the declared set, for the diagnostic when nothing survives.
+  const constraints = new Map();
+  // target -> why it is gone. Losing a runtime is never silent.
+  const droppedBecause = new Map();
+
+  const narrow = (allowed, reasonFor) => {
+    for (const target of [...targets]) {
+      if (allowed(target)) continue;
+      targets.delete(target);
+      if (!droppedBecause.has(target)) {
+        droppedBecause.set(target, reasonFor(target));
+      }
+    }
+  };
+
+  const consider = (pluginId, manifest) => {
+    if (!pluginId || constraints.has(pluginId)) return;
+    const declared = declaredRuntimeTargets(manifest);
+    if (!declared) return;
+    constraints.set(pluginId, [...declared].sort());
+    // ONE RULE, shared with the loaders (`runtimeTargetSatisfies`). Two rules
+    // for one field is how a manifest comes to mean different things to the
+    // compiler and to the door: a `["wasi","wasmedge"]` part had the browser
+    // leg stripped from every flow it joined while the browser harness happily
+    // admitted that same declaration. `wasi` is the portability baseline, so
+    // it admits both legs unless the part's own capabilities say otherwise;
+    // proof-based narrowing is the capability-union pass below.
+    narrow(
+      (target) =>
+        runtimeTargetSatisfies(declared, target, manifest?.capabilities),
+      () =>
+        `"${pluginId}" declares runtimeTargets [${[...declared].sort().join(", ")}]`,
+    );
+  };
+
+  for (const entry of resolvedNodes) {
+    if (!entry?.dependency) continue;
+    consider(entry.node?.pluginId, entry.dependency.manifest);
+  }
+  for (const component of componentDependencies ?? []) {
+    if (!component?.resolved) continue;
+    consider(
+      component.pluginId,
+      dependencies.get(component.pluginId)?.manifest,
+    );
+  }
+
+  const browserIncompatible = [...(capabilities ?? [])]
+    .filter((capability) => BrowserIncompatibleCapabilitySet.has(capability))
+    .sort();
+  if (browserIncompatible.length > 0) {
+    narrow(
+      (target) => target !== BROWSER_RUNTIME_TARGET,
+      () =>
+        `the flow's capability union contains ${browserIncompatible
+          .map((capability) => `"${capability}"`)
+          .join(", ")}, which the canonical browser runtime target cannot serve`,
+    );
+  }
+
+  const ordered = COMPOSED_FLOW_RUNTIME_TARGET_UNIVERSE.filter((target) =>
+    targets.has(target),
+  );
+  const reasons = [...droppedBecause.entries()]
+    .map(([target, why]) => `${target} (${why})`)
+    .join("; ");
+  if (ordered.length === 0) {
+    pushIssue(
+      issues,
+      "error",
+      "empty-runtime-target-intersection",
+      "No runtime runs every part of this flow: every candidate target was ruled " +
+        `out — ${reasons}. A composed flow can only target the runtimes shared by ` +
+        "all of its nodes and resolved component dependencies; split the flow, or " +
+        "widen the constraining plugin's runtimeTargets.",
+      "flow.nodes",
+    );
+  } else if (droppedBecause.size > 0) {
+    pushIssue(
+      issues,
+      "warning",
+      "narrowed-runtime-targets",
+      `This flow composes to runtimeTargets [${ordered.join(", ")}] — narrower than ` +
+        `the isomorphic pair. Dropped: ${reasons}. The artifact is still written to ` +
+        "dist/isomorphic/module.wasm, but it is NOT loadable on the dropped runtime " +
+        "and every harness for that leg will refuse it by name.",
+      "flow.nodes",
+    );
+  }
+  return ordered;
+}
+
+/**
+ * Rebuild the derived target set from a check record produced by an older SDK
+ * (one with no `runtimeTargets` field). Issues are discarded here on purpose —
+ * the caller re-raises the only one that matters, an empty result, as a throw.
+ */
+function recomputeFlowRuntimeTargets(check, dependencies) {
+  return collectFlowRuntimeTargets({
+    resolvedNodes: (check?.nodes ?? [])
+      .filter((node) => node.dispatchModel !== "host")
+      .map((node) => ({
+        node,
+        dependency: dependencies.get(node.pluginId) ?? null,
+      }))
+      .filter((entry) => entry.dependency),
+    componentDependencies: check?.componentDependencies,
+    dependencies,
+    capabilities: check?.capabilities ?? [],
+    issues: [],
+  });
+}
+
 /**
  * findFlowCycles returns every elementary cycle reachable in the node graph
  * as { nodeIds, edges } (iterative DFS with back-edge extraction; each cycle
@@ -1773,6 +1955,14 @@ export function checkFlowProgram({ flow, dependencies = new Map() } = {}) {
     capabilities,
   });
 
+  const runtimeTargets = collectFlowRuntimeTargets({
+    resolvedNodes,
+    componentDependencies,
+    dependencies,
+    capabilities,
+    issues,
+  });
+
   const errors = issues.filter((issue) => issue.severity === "error");
   return {
     ok: errors.length === 0,
@@ -1780,6 +1970,7 @@ export function checkFlowProgram({ flow, dependencies = new Map() } = {}) {
     errors,
     warnings: issues.filter((issue) => issue.severity === "warning"),
     capabilities: [...capabilities].sort(),
+    runtimeTargets,
     engineLinkage,
     threadModel,
     componentDependencies,
@@ -1908,6 +2099,23 @@ export function buildFlowModuleManifest({ flow, check, dependencies }) {
   const checkedNodeById = new Map(
     check.nodes.map((node) => [node.nodeId, node]),
   );
+  // `check.runtimeTargets` is the derived intersection. It is absent only when
+  // a caller hands in a check record built by an older SDK; recompute rather
+  // than silently re-asserting the historical pair — and THROW on the empty
+  // intersection instead of swallowing it. A check record has an issue sink;
+  // this path does not, and an artifact that declares no runtime at all is
+  // read as unconstrained by every loader downstream, which is the most
+  // permissive possible answer to the least certain question.
+  const runtimeTargets = Array.isArray(check.runtimeTargets)
+    ? [...check.runtimeTargets]
+    : recomputeFlowRuntimeTargets(check, dependencies);
+  if (runtimeTargets.length === 0) {
+    throw new Error(
+      `Flow "${flow?.programId ?? "(unknown)"}" has no runtime target: no runtime runs ` +
+        "every one of its parts. Refusing to build a manifest that declares nothing — " +
+        "run checkFlowProgram and read the empty-runtime-target-intersection error.",
+    );
+  }
 
   const hostModelNodeIds = new Set(
     check.nodes.filter((node) => node.dispatchModel === "host").map((node) => node.nodeId),
@@ -2032,13 +2240,17 @@ export function buildFlowModuleManifest({ flow, check, dependencies }) {
     externalInterfaces,
     methods,
     schemasUsed,
-    runtimeTargets: ["browser", "wasmedge"],
+    // DERIVED, never asserted: the runtimes shared by every node plugin and
+    // resolved component dependency (see collectFlowRuntimeTargets). A flow of
+    // fully isomorphic nodes keeps both targets; a flow containing one
+    // WasmEdge-only node is a WasmEdge-only flow and says so.
+    runtimeTargets,
     buildArtifacts: [
       {
         artifactId: `${cIdent(flow.programId)}-flow-runtime`,
         kind: "wasm",
         path: "dist/isomorphic/module.wasm",
-        target: "browser,wasmedge",
+        target: runtimeTargets.join(","),
       },
     ],
     flowNodes: nodes.map((node) => {

package/src/flow/flowRuntimeHost.js

@@ -15,6 +15,10 @@
  */
 
 import { createBrowserWasiShim } from "../host/wasiShim.js";
+import {
+  assertArtifactRuntimeTarget,
+  detectBrowserLeg,
+} from "../host/runtimeTargetGate.js";
 import {
   isPayloadSchemaHashValid,
   normalizePayloadSchemaHash,
@@ -211,6 +215,28 @@ export async function createFlowRuntimeHost(options = {}) {
     wasmModule = await WebAssembly.compile(bytes);
   }
 
+  // THE COMPOSED FLOW'S DOOR. A composed artifact now derives its
+  // runtimeTargets from its parts, so a WasmEdge-only flow is a real thing —
+  // and this host is how one gets loaded. It is genuinely runtime-agnostic
+  // (the same function backs the Node/WasmEdge leg), so the leg is stated by
+  // the caller; absent that, a real browser is detected and gated. Passing
+  // runtimeTarget: null opts out explicitly, which is not the same as
+  // forgetting.
+  const declaredLeg =
+    options.runtimeTarget === undefined
+      ? detectBrowserLeg()
+        ? "browser"
+        : null
+      : options.runtimeTarget;
+  if (declaredLeg) {
+    assertArtifactRuntimeTarget({
+      wasmModule,
+      manifest: options.manifest,
+      leg: String(declaredLeg).trim().toLowerCase(),
+      what: "composed flow artifact",
+    });
+  }
+
   const wasi = createBrowserWasiShim({
     args: options.args ?? ["flow-runtime"],
     env: options.env ?? {},

package/src/flow/isomorphicFlowHost.js

@@ -220,6 +220,14 @@ export async function createIsomorphicFlowRuntimeHost(options = {}) {
   );
   const parent = await createFlowRuntimeHost({
     wasmSource: parentArtifactBytes,
+    // UNCONDITIONAL, with no opt-out. This host mounts every isomorphic child
+    // through the BROWSER module harness, whose gate cannot be turned off — so
+    // an escape hatch here would only ever produce an ungated parent with
+    // gated children, and a half-gate is not a gate. There is no legitimate
+    // non-browser use of this host precisely because of that mount; callers
+    // that want the runtime-agnostic host call createFlowRuntimeHost, which
+    // does take a stated leg.
+    runtimeTarget: "browser",
     args: options.args,
     env: options.env,
     logOutput: options.logOutput,

package/src/host/browserModuleHarness.js

@@ -49,6 +49,10 @@ import {
   resolveModuleSignaturePolicy,
   verifyModuleArtifact,
 } from "../bundle/signing.js";
+import {
+  assertArtifactRuntimeTarget,
+  RuntimeTargetError,
+} from "./runtimeTargetGate.js";
 // Artifact byte reduction is an ARTIFACT concern shared by all three runtimes,
 // so it lives on `space-data-module-sdk/bundle`. Re-exported here because a
 // caller loading a module in the browser needs it in the same breath.
@@ -259,6 +263,27 @@ function createImportedMemory(options = {}) {
   return new WebAssembly.Memory(descriptor);
 }
 
+const BROWSER_RUNTIME_TARGET = "browser";
+
+export { RuntimeTargetError };
+
+/**
+ * TRI-RUNTIME ISOMORPHISM, ENFORCED AT THE DOOR.
+ *
+ * This harness IS the browser leg of the tri-runtime contract, wherever the
+ * JavaScript happens to be running — asking it to load an artifact that does
+ * not declare the browser is asking for a divergence. The shared gate in
+ * `runtimeTargetGate.js` does the work; both declarations are consulted and
+ * the artifact's own embedded record wins on conflict.
+ */
+export function assertBrowserRuntimeTarget(wasmModule, manifest) {
+  assertArtifactRuntimeTarget({
+    wasmModule,
+    manifest,
+    leg: BROWSER_RUNTIME_TARGET,
+  });
+}
+
 function resolveManifestSurface(manifest) {
   const surfaces = Array.isArray(manifest?.invokeSurfaces)
     ? manifest.invokeSurfaces
@@ -471,6 +496,7 @@ export async function createBrowserModuleHarness(options = {}) {
   ownedArtifactBytes = null;
   wasmSource = null;
   options.wasmSource = null;
+  assertBrowserRuntimeTarget(wasmModule, options.manifest);
   const moduleImports = WebAssembly.Module.imports(wasmModule);
   const needsHostBridge = moduleImports.some(
     (entry) => entry.module === DEFAULT_HOSTCALL_IMPORT_MODULE,