space-data-module-sdk 0.8.11 → 0.8.13

package/src/testing/parityGate.js

@@ -58,6 +58,8 @@ import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 
 import { toLoadableWasmBytes } from "../bundle/artifactBytes.js";
+import { locateEmbeddedPlgManifest } from "../compliance/index.js";
+import { runtimeTargetSatisfies } from "../host/runtimeTargetGate.js";
 import {
   classifyArtifactImports,
   describeClassification,
@@ -110,8 +112,56 @@ export const ContractVerdict = Object.freeze({
   ShimGap: "shim-gap",
   /** The lane could not run at all. */
   Unavailable: "lane-unavailable",
+  /**
+   * The artifact DECLARES that it does not run on this lane's runtime target.
+   * Not a pass, not a divergence, not a trap: a scope statement the artifact
+   * itself makes, recorded as evidence. Composed flows derive their
+   * runtimeTargets from their parts, so a WasmEdge-only flow is legitimate —
+   * and without this class its (correct, loud) refusal by the browser harness
+   * scored as a P1 cross-runtime divergence, which would have made the gate
+   * fail exactly the artifacts this SDK just taught the compiler to emit.
+   */
+  OutOfDeclaredScope: "out-of-declared-scope",
 });
 
+/** Which runtime target each parity lane stands for. */
+export const LANE_RUNTIME_TARGET = Object.freeze({
+  browser: "browser",
+  "wasmedge-native": "wasmedge",
+  "wasmedge-docker": "wasmedge",
+});
+
+/**
+ * The artifact's own declared runtimeTargets, read from its embedded `$PLG`.
+ * An artifact that declares none is unconstrained — every lane is in scope,
+ * which is the historical behaviour and stays the default.
+ */
+export function declaredRuntimeTargets(loadableBytes) {
+  try {
+    const located = locateEmbeddedPlgManifest(loadableBytes);
+    const declared = located?.decoded?.runtimeTargets;
+    return Array.isArray(declared)
+      ? declared.map((t) => String(t ?? "").trim().toLowerCase()).filter(Boolean)
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+export function declaredCapabilities(loadableBytes) {
+  try {
+    const located = locateEmbeddedPlgManifest(loadableBytes);
+    return located?.decoded?.capabilities ?? [];
+  } catch {
+    return [];
+  }
+}
+
+export function laneIsInDeclaredScope(laneName, targets, capabilities) {
+  const leg = LANE_RUNTIME_TARGET[laneName];
+  return leg ? runtimeTargetSatisfies(targets, leg, capabilities) : true;
+}
+
 // --- Manifest ------------------------------------------------------------------
 
 /**
@@ -181,6 +231,16 @@ export async function loadGateManifest(manifestPath = DEFAULT_GATE_MANIFEST) {
           ? path.resolve(path.dirname(resolved), String(spec.fixture))
           : null,
         required: spec.required !== false,
+        // The GATE'S claim about which lanes this artifact owes evidence on.
+        // Authority for that belongs to the manifest, not to the artifact's
+        // own `$PLG`: an artifact must not be able to reduce what it is
+        // examined on by editing its own declaration. Omitted means "every
+        // active lane its declaration admits".
+        expectedLanes: Object.freeze(
+          Array.isArray(spec.expectedLanes)
+            ? spec.expectedLanes.map((lane) => String(lane))
+            : [],
+        ),
         note: spec.note ? String(spec.note) : null,
         negativeControl: spec.negativeControl === true,
       }),
@@ -205,6 +265,11 @@ export function makeExternalArtifact(spec) {
     profile: String(spec.profile ?? "library"),
     fixture: spec.fixture ? path.resolve(String(spec.fixture)) : null,
     required: spec.required !== false,
+    expectedLanes: Object.freeze(
+      Array.isArray(spec.expectedLanes)
+        ? spec.expectedLanes.map((lane) => String(lane))
+        : [],
+    ),
     note: spec.note ? String(spec.note) : "injected by caller (external artifact)",
     negativeControl: spec.negativeControl === true,
   });
@@ -690,7 +755,49 @@ export function deriveContractVerdict({
  * under the bare WasmEdge CLI is NOT a divergence, and the report says so in
  * those words rather than pretending the lanes matched.
  */
+/**
+ * The P1 cross-runtime divergences among the lanes that ACTUALLY RAN.
+ *
+ * Extracted and exported so a test can drive the real comparison instead of
+ * re-implementing it: a test that hand-rolls this loop passes whether or not
+ * the shipped one is correct, which is precisely how the defect below survived
+ * its own regression test.
+ *
+ * Pass the COMPARED lanes — the ones not `out-of-declared-scope`. This used to
+ * pivot on `lanes[0]`, which is the BROWSER lane, and for a WasmEdge-only
+ * artifact that entry is `out-of-declared-scope`, which agrees with everything.
+ * Pivoting on it silently stopped comparing wasmedge-native against
+ * wasmedge-docker: the gate reported such an artifact adequately gated on two
+ * lanes while comparing nothing at all, defeating the very rule
+ * `certified-on-a-single-lane` states. Scoping a lane out must remove that LANE
+ * from the comparison, never the comparison itself.
+ *
+ * @param {Array<{lane: string, contractVerdict: string, reason?: string|null}>} comparedLanes
+ * @returns {string[]} one message per divergence
+ */
+export function laneDivergences(comparedLanes) {
+  const messages = [];
+  for (let index = 1; index < (comparedLanes?.length ?? 0); index += 1) {
+    const pivot = comparedLanes[0];
+    const other = comparedLanes[index];
+    if (lanesAgree(pivot.contractVerdict, other.contractVerdict)) continue;
+    messages.push(
+      `P1 cross-runtime divergence: ${pivot.lane}=${pivot.contractVerdict} vs ` +
+        `${other.lane}=${other.contractVerdict} (${other.reason ?? "-"})`,
+    );
+  }
+  return messages;
+}
+
 export function lanesAgree(a, b) {
+  // A lane the artifact declared itself out of cannot disagree with anything:
+  // there is no behaviour to compare, only a scope statement.
+  if (
+    a === ContractVerdict.OutOfDeclaredScope ||
+    b === ContractVerdict.OutOfDeclaredScope
+  ) {
+    return true;
+  }
   const equivalence = (verdict) =>
     verdict === ContractVerdict.RunnerCannotSupplyCapability
       ? ContractVerdict.Satisfied
@@ -786,6 +893,10 @@ export async function runParityGate(options = {}) {
   // --- resolve + load artifacts
   const artifacts = [];
   const failures = [];
+  // A caller may state the lanes an artifact owes from OUTSIDE the manifest
+  // file (`--artifact-lanes`), which is the only way to bind a cross-repo
+  // injected artifact whose declaration this repo does not own.
+  const expectedLanesById = options.expectedLanesById ?? {};
   for (const spec of declared) {
     try {
       const rawBytes = new Uint8Array(await readFile(spec.artifactPath));
@@ -797,6 +908,11 @@ export async function runParityGate(options = {}) {
         artifactSha256: sha256Hex(rawBytes),
         moduleSha256: sha256Hex(loadableBytes),
         structural: classifyArtifactImports(loadableBytes, spec.surface),
+        declaredRuntimeTargets: declaredRuntimeTargets(loadableBytes),
+        declaredCapabilities: declaredCapabilities(loadableBytes),
+        ...(expectedLanesById[spec.id]
+          ? { expectedLanes: expectedLanesById[spec.id] }
+          : {}),
       });
     } catch (error) {
       if (spec.required) {
@@ -877,10 +993,25 @@ export async function runParityGate(options = {}) {
   // --- Tier A: real instantiation probes
   const laneProbes = new Map(); // lane -> Map(artifactId -> probe)
 
-  if (activeLanes.includes("browser") && artifacts.length > 0) {
+  // SCOPE BEFORE PROBING. An artifact that declares it does not run on a lane
+  // has nothing to learn from being launched there; probing anyway costs a
+  // Chrome start or a WasmEdge spawn per artifact for evidence the verdict
+  // then discards, and leaves the (expected) trap in the log as noise the
+  // report says was out of scope.
+  const inScopeArtifacts = (lane) =>
+    artifacts.filter((artifact) =>
+      laneIsInDeclaredScope(
+        lane,
+        artifact.declaredRuntimeTargets,
+        artifact.declaredCapabilities,
+      ),
+    );
+
+  const browserArtifacts = inScopeArtifacts("browser");
+  if (activeLanes.includes("browser") && browserArtifacts.length > 0) {
     const probes = new Map();
     try {
-      const results = await runBrowserProbeLane(context, artifacts);
+      const results = await runBrowserProbeLane(context, browserArtifacts);
       for (const result of results) {
         probes.set(result.id, {
           outcome: result.outcome,
@@ -890,7 +1021,9 @@ export async function runParityGate(options = {}) {
           crossOriginIsolated: result.crossOriginIsolated === true,
         });
       }
-      const missing = artifacts.filter((artifact) => !probes.has(artifact.id));
+      const missing = browserArtifacts.filter(
+        (artifact) => !probes.has(artifact.id),
+      );
       for (const artifact of missing) {
         probes.set(artifact.id, {
           outcome: "lane-unavailable",
@@ -899,7 +1032,7 @@ export async function runParityGate(options = {}) {
         });
       }
     } catch (error) {
-      for (const artifact of artifacts) {
+      for (const artifact of browserArtifacts) {
         probes.set(artifact.id, {
           outcome: "lane-unavailable",
           detail: error?.message ?? String(error),
@@ -917,7 +1050,7 @@ export async function runParityGate(options = {}) {
 
   for (const lane of wasmedgeLanes) {
     const probes = new Map();
-    for (const artifact of artifacts) {
+    for (const artifact of inScopeArtifacts(lane)) {
       const staged = await stageArtifact(artifact);
       try {
         const probe =
@@ -942,26 +1075,105 @@ export async function runParityGate(options = {}) {
   const artifactReports = [];
   for (const artifact of artifacts) {
     const lanes = [];
-    for (const lane of laneProbes.keys()) {
-      const probe = laneProbes.get(lane).get(artifact.id) ?? {
+    // Iterate the ACTIVE lanes, not the probed ones: a lane with no in-scope
+    // artifact is never launched, and its scoping still has to appear in the
+    // report. A skipped lane is evidence; a missing row is silence.
+    for (const lane of activeLanes) {
+      const probe = laneProbes.get(lane)?.get(artifact.id) ?? {
         outcome: "lane-unavailable",
         detail: "no probe recorded",
         missingImport: null,
       };
-      const derived = deriveContractVerdict({
-        laneSuppliesCapabilities: lane === "browser",
-        probe,
-        structural: artifact.structural,
-      });
+      const inScope = laneIsInDeclaredScope(
+        lane,
+        artifact.declaredRuntimeTargets,
+        artifact.declaredCapabilities,
+      );
+      const derived = inScope
+        ? deriveContractVerdict({
+            laneSuppliesCapabilities: lane === "browser",
+            probe,
+            structural: artifact.structural,
+          })
+        : {
+            verdict: ContractVerdict.OutOfDeclaredScope,
+            reason:
+              `the artifact declares runtimeTargets ` +
+              `[${artifact.declaredRuntimeTargets.join(", ")}], which does not include ` +
+              `"${LANE_RUNTIME_TARGET[lane]}" — this lane is out of its declared scope, ` +
+              "so its refusal here is the contract working, not a divergence",
+          };
       lanes.push({
         lane,
-        evidence: LANE_EVIDENCE[lane] ?? "unlabelled lane",
-        outcome: probe.outcome,
-        missingImport: probe.missingImport ?? null,
-        detail: probe.detail ?? null,
+        evidence: inScope
+          ? (LANE_EVIDENCE[lane] ?? "unlabelled lane")
+          : "artifact's own embedded runtimeTargets declaration",
+        outcome: inScope ? probe.outcome : "out-of-declared-scope",
+        missingImport: inScope ? (probe.missingImport ?? null) : null,
+        detail: inScope ? (probe.detail ?? null) : derived.reason,
         contractVerdict: derived.verdict,
         reason: derived.reason,
-        crossOriginIsolated: probe.crossOriginIsolated,
+        crossOriginIsolated: inScope ? (probe.crossOriginIsolated ?? null) : null,
+        declaredRuntimeTargets: artifact.declaredRuntimeTargets,
+      });
+    }
+
+    // THE ARTIFACT DOES NOT PICK ITS EXAMINERS.
+    //
+    // Scoping a lane out is a legitimate statement about where an artifact
+    // runs; it is not a way to be certified without being run. An artifact in
+    // the gate's own certified set that scopes ITSELF out of every lane — or
+    // out of all but one, leaving nothing to compare — has not been gated at
+    // all, and `lanesAgree` returning true pairwise must never stand in for
+    // "two lanes were compared". One manifest string would otherwise disarm
+    // the negative control.
+    const comparedLanes = lanes.filter(
+      (entry) => entry.contractVerdict !== ContractVerdict.OutOfDeclaredScope,
+    );
+    const comparedLaneNames = comparedLanes.map((entry) => entry.lane);
+    if (comparedLanes.length === 0) {
+      failures.push({
+        artifact: artifact.id,
+        kind: "artifact-out-of-every-lane",
+        message:
+          `declares runtimeTargets [${artifact.declaredRuntimeTargets.join(", ")}], ` +
+          `which admits none of the active lanes [${activeLanes.join(", ")}] — ` +
+          "it cannot be certified by a gate that never ran it",
+      });
+    } else if (activeLanes.length > 1 && comparedLanes.length < 2) {
+      // NO ARTIFACT IS CERTIFIED ON THE EVIDENCE OF A SINGLE LANE. The rule is
+      // about evidence, not about the artifact's shape: one lane is one
+      // execution, and one execution is not parity. A WasmEdge-only artifact
+      // still clears this — native host vs pinned container at one pin is a
+      // real comparison, and those pins bump together by law. A browser-only
+      // artifact does not, until the second browser lane (sequential vs
+      // worker-pool, owed by browser-worker-topology) exists to compare it to.
+      failures.push({
+        artifact: artifact.id,
+        kind: "certified-on-a-single-lane",
+        message:
+          `only lane "${comparedLanes[0].lane}" of [${activeLanes.join(", ")}] compared it ` +
+          `(it declares runtimeTargets [${artifact.declaredRuntimeTargets.join(", ")}]) — ` +
+          "one execution is not parity, so no artifact is certified on the evidence of a " +
+          "single lane",
+      });
+    }
+    // The manifest's claim outranks the artifact's declaration: an artifact
+    // may not shrink the set of lanes it is examined on by editing its own
+    // `$PLG`.
+    const owed = (artifact.expectedLanes ?? []).filter((lane) =>
+      activeLanes.includes(lane),
+    );
+    const unmet = owed.filter((lane) => !comparedLaneNames.includes(lane));
+    if (unmet.length > 0) {
+      failures.push({
+        artifact: artifact.id,
+        kind: "expected-lane-not-compared",
+        message:
+          `the gate manifest requires lanes [${owed.join(", ")}] for this artifact, but ` +
+          `[${unmet.join(", ")}] produced no comparison — its own declaration ` +
+          `[${artifact.declaredRuntimeTargets.join(", ")}] cannot narrow what the gate ` +
+          "claims to certify",
       });
     }
 
@@ -990,14 +1202,8 @@ export async function runParityGate(options = {}) {
       }
     }
 
-    for (let index = 1; index < lanes.length; index += 1) {
-      if (!lanesAgree(lanes[0].contractVerdict, lanes[index].contractVerdict)) {
-        failures.push({
-          artifact: artifact.id,
-          kind: "lane-divergence",
-          message: `P1 cross-runtime divergence: ${lanes[0].lane}=${lanes[0].contractVerdict} vs ${lanes[index].lane}=${lanes[index].contractVerdict} (${lanes[index].reason ?? "-"})`,
-        });
-      }
+    for (const message of laneDivergences(comparedLanes)) {
+      failures.push({ artifact: artifact.id, kind: "lane-divergence", message });
     }
 
     artifactReports.push({
@@ -1008,6 +1214,7 @@ export async function runParityGate(options = {}) {
       artifactSha256: artifact.artifactSha256,
       moduleSha256: artifact.moduleSha256,
       byteLength: artifact.loadableBytes.length,
+      declaredRuntimeTargets: artifact.declaredRuntimeTargets,
       structural: {
         verdict: artifact.structural.verdict,
         summary: describeClassification(artifact.structural),
@@ -1025,7 +1232,50 @@ export async function runParityGate(options = {}) {
   const behavioral = [];
   for (const artifact of artifacts) {
     if (!artifact.fixture) continue;
-    const harnessLanes = ["browser", ...(wasmedgeLanes.includes("wasmedge-native") ? ["wasmedge"] : []), "docker-wasmedge"];
+    // Behavioral lanes are scoped by the artifact's OWN declaration too: a
+    // WasmEdge-only artifact has no browser behaviour to compare, and running
+    // it there would score the harness's (correct) refusal as a divergence.
+    // The scoping is RECORDED — a skipped lane is evidence, never silence.
+    const harnessLanes = [
+      "browser",
+      ...(wasmedgeLanes.includes("wasmedge-native") ? ["wasmedge"] : []),
+      "docker-wasmedge",
+    ].filter((laneName) =>
+      laneIsInDeclaredScope(
+        laneName === "wasmedge"
+          ? "wasmedge-native"
+          : laneName === "docker-wasmedge"
+            ? "wasmedge-docker"
+            : laneName,
+        artifact.declaredRuntimeTargets,
+        artifact.declaredCapabilities,
+      ),
+    );
+    const outOfScopeLanes = ["browser", "wasmedge", "docker-wasmedge"].filter(
+      (laneName) => !harnessLanes.includes(laneName),
+    );
+    if (harnessLanes.length < 2) {
+      // An artifact that declared a FIXTURE asked to be compared. If its own
+      // declaration leaves nothing to compare it against, that is a defect in
+      // the certified set, not a free pass.
+      const message =
+        `behavioral parity needs two comparable lanes; this artifact declares ` +
+        `runtimeTargets [${artifact.declaredRuntimeTargets.join(", ")}] and only ` +
+        `${harnessLanes.length} lane(s) remain in scope`;
+      behavioral.push({
+        artifact: artifact.id,
+        ok: false,
+        outOfDeclaredScope: outOfScopeLanes,
+        declaredRuntimeTargets: artifact.declaredRuntimeTargets,
+        note: message,
+      });
+      failures.push({
+        artifact: artifact.id,
+        kind: "behavioral-not-comparable",
+        message,
+      });
+      continue;
+    }
     try {
       const report = await runParityHarness({
         wasmPath: artifact.artifactPath,
@@ -1037,7 +1287,17 @@ export async function runParityGate(options = {}) {
         timeoutMs: context.timeoutMs,
         log,
       });
-      behavioral.push({ artifact: artifact.id, ok: report.ok, report });
+      behavioral.push({
+        artifact: artifact.id,
+        ok: report.ok,
+        report,
+        ...(outOfScopeLanes.length > 0
+          ? {
+              outOfDeclaredScope: outOfScopeLanes,
+              declaredRuntimeTargets: artifact.declaredRuntimeTargets,
+            }
+          : {}),
+      });
       if (!report.ok) {
         for (const failure of report.failures) {
           failures.push({

package/templates/propagator-module/README.md

@@ -0,0 +1,99 @@
+# __MODULE_NAME__
+
+Scaffolded by `space-data-module init --family propagator --name __MODULE_NAME__`
+from space-data-module-sdk's `templates/propagator-module/` template.
+
+This is a **minimal but building** skeleton of an SDN propagator module: every
+ABI obligation is already implemented — exports, wire layout, units, frames,
+identity, threading discipline, error codes, lifetime — and the orbital
+mechanics are a placeholder. It compiles and passes the SDK's own compliance
+checks as-is; it just doesn't propagate anything real yet.
+
+## Files
+
+- `plugin-manifest.json` — the module manifest. `pluginId` defaults to
+  `com.orbpro.<name-with-dots>`; `pluginFamily` is `propagator`; declares one
+  invoke method (`ingest_omm`) plus the propagator ABI exports below.
+- `src/__MODULE_NAME_SNAKE__.cpp` — the module source. Search for
+  `TODO: your propagation goes here` — there are two spots (element adoption
+  in `adopt_omm()`, and the actual propagation in `propagate_entity()`).
+  Everything else in the file is ABI plumbing; you should not need to touch
+  export names, signatures, error codes, or the state-vector write pattern.
+- `build.js` — compiles through `compileModuleFromSource` (the SDK compiler
+  lane). Inlines the generated `orbpro_propagator_abi.h` from your pinned
+  `space-data-module-sdk` dependency — never hand-copy that header.
+- `tests/module.build.test.mjs` — manifest shape check (always runs) plus
+  compliance/export checks that skip until you've built the module.
+- `package.json` — `"sdn-module"` points at the canonical isomorphic
+  artifact; `space-data-module-sdk` is a normal npm dependency.
+
+## Naming
+
+This module was scaffolded with `--name __MODULE_NAME__`. `space-data-module
+init` substituted four spellings of that name into this tree; if you need to
+introduce your own file or identifier later, reuse the same shapes rather
+than inventing a fifth:
+
+| Spelling             | This module's value | Used for                                  |
+| --------------------- | -------------------- | ------------------------------------------ |
+| kebab-case             | `__MODULE_NAME__`       | display text, kebab-case filenames          |
+| reverse-DNS plugin id  | `__PLUGIN_ID__`         | `plugin-manifest.json`'s `pluginId`         |
+| snake_case              | `__MODULE_NAME_SNAKE__` | C/C++ file and symbol names                 |
+| camelCase                | `__MODULE_NAME_CAMEL__` | a JS-safe identifier (e.g. a bindings key) |
+
+## Next steps
+
+1. `npm install` (pulls `space-data-module-sdk` and its `spacedatastandards.org`
+   dependency).
+2. Fill in the physics: replace the two `TODO: your propagation goes here`
+   blocks in `src/__MODULE_NAME_SNAKE__.cpp`. Keep every export, error code,
+   and the "zero the struct, set frame explicitly, set VALID last" write
+   pattern — those are the ABI contract, not style.
+3. `npm run build` — writes `dist/isomorphic/module.wasm` +
+   `dist/plugin-manifest.json`. The build fails loudly if the compiled
+   artifact does not pass the SDK's own manifest/artifact validation.
+4. `npm test` — the manifest-shape test always runs; the compliance and
+   export-surface tests turn on once step 3 has produced a wasm artifact.
+5. Replace the TODO test at the bottom of `tests/module.build.test.mjs` with
+   a real assertion once you have physics to check (ingest a known OMM,
+   propagate to a known epoch, compare against an independent reference —
+   e.g. another propagator or published ephemeris).
+6. Update `description` in `plugin-manifest.json` and `package.json` — both
+   still say "TODO" / a generic scaffold description.
+
+## The ABI, in one paragraph
+
+A propagator module exports `plugin_init`, `plugin_init_omm`,
+`plugin_ingest_omm_one`, `plugin_propagate`, `plugin_propagate_batch`,
+`plugin_entity_count`, and `plugin_destroy` against the generated
+`OrbProStateVector` / `OrbProOMMRecord` / `OrbProOrbitalElements` structs
+(`orbpro/orbpro_propagator_abi.h` in your pinned `space-data-module-sdk`,
+generated from `schemas/orbpro/Propagator.fbs` — never hand-retype these
+structs, that is the exact drift this generated header exists to end).
+Position/velocity output is always METERS / METERS-PER-SECOND with an
+explicit `reference_frame`; identity is carried by `NORAD_CAT_ID`, never
+derived from array position; every failure returns a named negative code;
+`plugin_destroy` must actually free, not no-op.
+
+**Threading.** This module declares `threadModel: "wasi-sequential"` — it
+never spawns a thread of its own, which is the *strong default* for a
+propagator: propagation is embarrassingly parallel across entities but
+sequential within one, and the ABI puts the sharding decision on the HOST
+(e.g. a frame-worker pool), not the module. `build.js` passes
+`threadModel: manifest.threadModel` to the compiler EXPLICITLY — do not
+remove that. `resolveThreadModel` reads the compile option, not
+`manifest.threadModel`, and otherwise infers the model from
+`runtimeTargets`, where `"wasmedge"` infers the OTHER model
+(`emscripten-pthreads`, which in this SDK means the clang
+`wasm32-wasip1-threads` / wasi-threads contract — never `emcc -pthread`,
+which cannot thread under WasmEdge at all). Passing `threadModel` in
+`build.js` sidesteps that inference and is what keeps this manifest's
+declared model and the compiled artifact in agreement — `build.js` also
+asserts they agree after compiling. See `docs/propagator-abi.md`
+"Threading" if you ever need the other model.
+
+The one SDN invoke method, `ingest_omm`, is separate from the propagator ABI
+exports above: it is how a flow graph feeds this module SDS `$OMM` records
+over the generic invoke surface, while `plugin_propagate` /
+`plugin_propagate_batch` are called directly by a host that has already
+linked this module as a propagator.

package/templates/propagator-module/build.js

@@ -0,0 +1,103 @@
+/**
+ * Build __MODULE_NAME__ through the SDK compiler lane.
+ *
+ * `compileModuleFromSource` takes ONE translation unit, so the generated
+ * OrbPro propagator ABI header is INLINED into the source before compiling.
+ * That inlining is mechanical and one-directional: the header is read from
+ * the pinned `space-data-module-sdk` package, never copied into this repo.
+ * If the SDK's ABI changes, this build picks it up on the next `npm run
+ * build` — do not hand-vendor a copy of the header beside this file.
+ *
+ * Thread model: the manifest declares `threadModel: "wasi-sequential"` (see
+ * plugin-manifest.json's `sequentialJustification`) — this module never
+ * spawns a thread, which is the strong default for a propagator (sharding a
+ * batch belongs to the HOST, not the module; see docs/propagator-abi.md
+ * "Threading"). Both `wasi-sequential` and the threaded `emscripten-pthreads`
+ * model compile through the SAME clang `wasm32-wasip1-threads` toolchain —
+ * never `emcc -pthread`, which is browser-only and cannot thread under
+ * WasmEdge — they differ only in which link-time contract the SDK's
+ * post-link artifact guard then validates against the emitted wasm.
+ */
+
+import fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compileModuleFromSource } from "space-data-module-sdk/compiler";
+
+const require = createRequire(import.meta.url);
+const packageRoot = fileURLToPath(new URL(".", import.meta.url));
+const manifestPath = path.join(packageRoot, "plugin-manifest.json");
+const sourcePath = path.join(packageRoot, "src", "__MODULE_NAME_SNAKE__.cpp");
+const distRoot = path.join(packageRoot, "dist");
+const outputPath = path.join(distRoot, "isomorphic", "module.wasm");
+
+const standardsRoot = path.dirname(
+  require.resolve("spacedatastandards.org/package.json"),
+);
+process.env.SPACE_DATA_STANDARDS_ROOT ??= `${standardsRoot}${path.sep}`;
+
+/** The ONE source of the ABI, resolved from the pinned SDK package. */
+const abiHeaderPath = require.resolve(
+  "space-data-module-sdk/include/orbpro/orbpro_propagator_abi.h",
+);
+
+const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+const abiHeader = await fs.readFile(abiHeaderPath, "utf8");
+const rawSource = await fs.readFile(sourcePath, "utf8");
+
+const INCLUDE_LINE = '#include "orbpro/orbpro_propagator_abi.h"';
+if (!rawSource.includes(INCLUDE_LINE)) {
+  throw new Error(
+    `${path.relative(packageRoot, sourcePath)} no longer includes the generated ABI header. ` +
+      `A propagator module must build against the ONE generated ABI, not a local copy.`,
+  );
+}
+
+const sourceCode = rawSource.replace(
+  INCLUDE_LINE,
+  [
+    `// --- BEGIN INLINED ${path.basename(abiHeaderPath)} (from ${manifest.pluginId}'s pinned SDK) ---`,
+    abiHeader,
+    `// --- END INLINED ${path.basename(abiHeaderPath)} ---`,
+  ].join("\n"),
+);
+
+await fs.rm(distRoot, { recursive: true, force: true });
+await fs.mkdir(path.dirname(outputPath), { recursive: true });
+
+const compilation = await compileModuleFromSource({
+  manifest,
+  sourceCode,
+  language: "c++",
+  outputPath,
+  // PASSED EXPLICITLY ON PURPOSE. `resolveThreadModel` reads the compile
+  // OPTION, not `manifest.threadModel`, and otherwise infers the model from
+  // `runtimeTargets` — where "wasmedge" infers pthreads. A manifest that
+  // declares `wasi-sequential` and does not pass it here would be silently
+  // compiled under the OTHER model and then rejected by the post-link
+  // artifact guard for not spawning a thread it never claimed to spawn.
+  // Filed as `sdk-manifest-threadmodel-silently-ignored`; keep this explicit
+  // until that lands.
+  threadModel: manifest.threadModel,
+});
+
+if (compilation.threadModel !== manifest.threadModel) {
+  throw new Error(
+    `threadModel drift: the manifest declares ${manifest.threadModel} but the ` +
+      `compiler resolved ${compilation.threadModel}.`,
+  );
+}
+
+await fs.copyFile(manifestPath, path.join(distRoot, "plugin-manifest.json"));
+
+if (!compilation.report?.ok) {
+  const issues = JSON.stringify(compilation.report?.issues ?? [], null, 2);
+  throw new Error(`Compiled __MODULE_NAME__ artifact failed SDK validation:\n${issues}`);
+}
+
+console.log(
+  `Built ${path.relative(packageRoot, outputPath)} ` +
+    `(${compilation.compiler}, threadModel=${compilation.threadModel})`,
+);

package/templates/propagator-module/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "space-data-network-module-propagator-__MODULE_NAME__",
+  "version": "0.1.0",
+  "description": "__MODULE_NAME__ — an SDN propagator module scaffolded from the space-data-module-sdk propagator-module template.",
+  "type": "module",
+  "sdn-module": "./dist/isomorphic/module.wasm",
+  "exports": {
+    "./plugin-manifest.json": "./plugin-manifest.json",
+    "./dist/*": "./dist/*"
+  },
+  "scripts": {
+    "build": "node build.js",
+    "test": "node --test tests/*.test.mjs"
+  },
+  "dependencies": {
+    "space-data-module-sdk": "^0.8.12"
+  },
+  "private": true
+}