space-data-module-sdk 0.8.11 → 0.8.13

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

@@ -34,6 +34,8 @@ async function main(argv) {
       return runCheck(rest);
     case "compile":
       return runCompile(rest);
+    case "init":
+      return runInit(rest);
     case "flow":
       return runFlow(rest);
     case "parity":
@@ -98,6 +100,18 @@ function parseArgs(argv) {
       case "--out":
         options.outputPath = path.resolve(requireValue(argv, ++index, value));
         break;
+      case "--family":
+        options.family = requireValue(argv, ++index, value);
+        break;
+      case "--name":
+        options.name = requireValue(argv, ++index, value);
+        break;
+      case "--plugin-id":
+        options.pluginId = requireValue(argv, ++index, value);
+        break;
+      case "--force":
+        options.force = true;
+        break;
       case "--recipient-public-key":
         options.recipientPublicKeyHex = requireValue(argv, ++index, value);
         break;
@@ -170,6 +184,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;
@@ -197,6 +233,8 @@ function printUsage() {
   space-data-module check --repo-root .
   space-data-module check --manifest ./manifest.json --wasm ./dist/module.wasm
   space-data-module compile --manifest ./manifest.json --source ./src/module.c --out ./dist/module.wasm
+  space-data-module init --family propagator --name my-propagator
+  space-data-module init --family propagator --name my-propagator --out ./modules/my-propagator [--plugin-id com.orbpro.my.propagator] [--force] [--json]
   space-data-module parity --wasm ./dist/isomorphic/module.wasm --fixture ./fixtures/parity/basic.json
   space-data-module parity --wasm ./dist/isomorphic/module.wasm --fixture ./f.json --lanes browser,wasmedge,docker-wasmedge [--json]
   space-data-module parity ... --self-test-divergence docker-wasmedge   (fire drill: prove the diff fails loudly)
@@ -264,6 +302,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 +346,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 +421,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,
@@ -500,6 +548,42 @@ async function runCompile(argv) {
   return result.report.ok ? 0 : 1;
 }
 
+// space-data-module init --family propagator --name <module-name>
+//   [--out <dir>] [--plugin-id <id>] [--force] [--json]
+//
+// Scaffolds a new SDN WASM module skeleton from templates/<family>-module/.
+// An unrecognized --family FAILS LOUDLY (see src/scaffold/index.js) — there
+// is no generic fallback template.
+async function runInit(argv) {
+  const options = parseArgs(argv);
+  if (!options.family) {
+    throw new Error("init requires --family <family> (e.g. --family propagator).");
+  }
+  if (!options.name) {
+    throw new Error("init requires --name <module-name>.");
+  }
+  const { scaffoldModule } = await import("../src/scaffold/index.js");
+  const result = await scaffoldModule({
+    family: options.family,
+    name: options.name,
+    outDir: options.outputPath ?? undefined,
+    pluginId: options.pluginId,
+    force: options.force === true,
+  });
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(
+      `Scaffolded ${result.family} module "${result.name}" into ${result.outDir}`,
+    );
+    console.log(`  pluginId=${result.pluginId}`);
+    for (const file of result.files) {
+      console.log(`  created ${file}`);
+    }
+  }
+  return result.ok ? 0 : 1;
+}
+
 async function runProtect(argv) {
   const options = parseArgs(argv);
   if (!options.manifestPath || !options.wasmPath) {

package/docs/module-publication-standard.md

@@ -128,7 +128,9 @@ instantiates and the node's capability policy identifies by content hash.
 
 The domain prefix exists because the node's publisher key is the NODE key, and
 that one bonded key signs several unrelated kinds of statement (dataset
-publications, module artifacts, and — reserved — update manifests). If every
+publications, module artifacts, update SIGNALS — the advisory pub/sub nudge a
+publisher pushes so every install upgrades itself in place, which has a live
+producer — and, still reserved, update manifests). If every
 statement were a bare SHA-256 digest, a caller who could reach the node's
 signing endpoint could submit the bytes of one kind of document and staple the
 returned signature onto another. An ASCII domain label, a `NUL` that cannot
@@ -137,8 +139,10 @@ in a disjoint message space with no length ambiguity anywhere in the preimage.
 
 The domain registry is **closed**: a verifier refuses any label that is not
 registered, and a module verifier additionally refuses any registered label
-other than `SDN-MODULE-PUBLICATION-V1` — so a signature minted for a signed
-update can never be replayed into a module trailer. Adding a domain is a
+other than `SDN-MODULE-PUBLICATION-V1` — so a signature minted for an update
+manifest or an update signal can never be replayed into a module trailer, which
+the shared vectors pin as `foreign-registered-domain` and
+`update-signal-domain-is-refused-for-a-module`. Adding a domain is a
 reviewed change in every implementation at once
 (`src/bundle/sigdomain.js` here; `internal/sigdomain` and its kubo twin in the
 node), never a request parameter.