space-data-module-sdk 0.8.12 → 0.8.13

package/src/manifest/normalize.js

@@ -15,7 +15,16 @@ import {
 import { FlatBufferTypeRefT } from "../generated/orbpro/stream/flat-buffer-type-ref.js";
 import { ProtocolRole, ProtocolTransportKind } from "../runtime/constants.js";
 
-const pluginFamilyByName = Object.freeze({
+/**
+ * The manifest-string → PluginFamily vocabulary. This is the WHOLE vocabulary:
+ * anything not in here is refused by name, never coerced.
+ *
+ * `datasource` is the ONE alias, kept because manifests in the field spell it
+ * both ways. Do not add aliases casually — an alias is a second spelling of a
+ * family, and every one of them is a place two modules can disagree about what
+ * they are.
+ */
+export const pluginFamilyByName = Object.freeze({
   sensor: PluginFamily.SENSOR,
   propagator: PluginFamily.PROPAGATOR,
   renderer: PluginFamily.RENDERER,
@@ -28,8 +37,89 @@ const pluginFamilyByName = Object.freeze({
   infrastructure: PluginFamily.INFRASTRUCTURE,
   flow: PluginFamily.FLOW,
   bridge: PluginFamily.BRIDGE,
+  maneuver: PluginFamily.MANEUVER,
+  orbit_determination: PluginFamily.ORBIT_DETERMINATION,
+  foundation: PluginFamily.FOUNDATION,
+  parser: PluginFamily.PARSER,
+  validator: PluginFamily.VALIDATOR,
+  exporter: PluginFamily.EXPORTER,
+  publisher: PluginFamily.PUBLISHER,
+  basilisk: PluginFamily.BASILISK,
 });
 
+/** Every accepted family string, sorted — the vocabulary a refusal names. */
+export const PluginFamilyNames = Object.freeze(
+  Object.keys(pluginFamilyByName).sort(),
+);
+
+/**
+ * SDK family → authoritative SDS `pluginCategory` member name.
+ *
+ * SDS (spacedatastandards.org `schema/PLG/main.fbs`) is the source of truth for
+ * what families exist; this SDK enum is a projection of it. The two DO NOT
+ * share ordinals — they diverge from index 5 (SDK `COMMS = 5`, SDS `EW = 5`) —
+ * so this mapping is BY NAME and must stay explicit. Never convert one enum to
+ * the other numerically.
+ *
+ * Two entries have no 1:1 SDS member and are recorded honestly rather than
+ * hidden. Both are filed in graph/tasks/sds-plugin-category-projection-gaps.md:
+ *   - ORBIT_DETERMINATION → Analysis (SDS has no OD category yet)
+ *   - SDF, BRIDGE         → Analysis / Infrastructure (SDK-local concepts)
+ */
+export const sdsPluginCategoryByFamily = Object.freeze({
+  [PluginFamily.SENSOR]: "Sensor",
+  [PluginFamily.PROPAGATOR]: "Propagator",
+  [PluginFamily.RENDERER]: "Renderer",
+  [PluginFamily.ANALYSIS]: "Analysis",
+  [PluginFamily.DATA_SOURCE]: "DataSource",
+  [PluginFamily.COMMS]: "Comms",
+  [PluginFamily.SHADER]: "Shader",
+  [PluginFamily.SDF]: "Analysis",
+  [PluginFamily.INFRASTRUCTURE]: "Infrastructure",
+  [PluginFamily.FLOW]: "Flow",
+  [PluginFamily.BRIDGE]: "Infrastructure",
+  [PluginFamily.MANEUVER]: "Maneuver",
+  [PluginFamily.ORBIT_DETERMINATION]: "Analysis",
+  [PluginFamily.FOUNDATION]: "Foundation",
+  [PluginFamily.PARSER]: "Parser",
+  [PluginFamily.VALIDATOR]: "Validator",
+  [PluginFamily.EXPORTER]: "Exporter",
+  [PluginFamily.PUBLISHER]: "Publisher",
+  [PluginFamily.BASILISK]: "Basilisk",
+});
+
+const PluginFamilyValues = Object.freeze(
+  new Set(Object.values(pluginFamilyByName)),
+);
+
+/**
+ * Thrown when a manifest declares a family the SDK does not know.
+ *
+ * It is a THROW and not a fallback on purpose. The old code returned
+ * `PluginFamily.ANALYSIS` for anything unrecognized, which is why 19
+ * first-party modules shipped mislabelled and family-typed resolution only
+ * ever worked for propagators: a typo and a deliberate new family were
+ * indistinguishable, and both were silent.
+ *
+ * Ruling: graph/findings/official-harness-shapes.md §4.7 / §8.3
+ */
+export class UnknownPluginFamilyError extends Error {
+  constructor(value) {
+    super(
+      `Unknown pluginFamily ${JSON.stringify(value)}. ` +
+        `The manifest vocabulary is: ${PluginFamilyNames.join(", ")}. ` +
+        `Families are NOT invented in a manifest — the SDK enum ` +
+        `(schemas/PluginManifest.fbs PluginFamily) is a projection of the ` +
+        `authoritative SDS pluginCategory vocabulary, and a new family is ` +
+        `appended there first.`,
+    );
+    this.name = "UnknownPluginFamilyError";
+    this.code = "unknown-plugin-family";
+    this.value = value;
+    this.validFamilies = PluginFamilyNames;
+  }
+}
+
 const drainPolicyByName = Object.freeze({
   "single-shot": ManifestDrainPolicy.SINGLE_SHOT,
   "drain-until-yield": ManifestDrainPolicy.DRAIN_UNTIL_YIELD,
@@ -145,14 +235,33 @@ function normalizeUnsignedInteger(value, fallback = 0) {
   return Math.max(0, Math.trunc(normalized));
 }
 
-function normalizePluginFamily(value) {
+/**
+ * Resolve a manifest `pluginFamily` to its enum value, or REFUSE.
+ *
+ * There is no fallback. See {@link UnknownPluginFamilyError} for why.
+ *
+ * @param {string|number} value
+ * @returns {number} a PluginFamily member
+ * @throws {UnknownPluginFamilyError} on an unknown string, an out-of-range
+ *   number, or a missing/blank value.
+ */
+export function normalizePluginFamily(value) {
   if (typeof value === "number") {
+    // A numeric family still has to BE one. An out-of-range ordinal is the
+    // same defect as an unknown string, and used to sail straight through.
+    if (!PluginFamilyValues.has(value)) {
+      throw new UnknownPluginFamilyError(value);
+    }
     return value;
   }
-  const normalized = String(value ?? "analysis")
+  const normalized = String(value ?? "")
     .trim()
     .toLowerCase();
-  return pluginFamilyByName[normalized] ?? PluginFamily.ANALYSIS;
+  const resolved = pluginFamilyByName[normalized];
+  if (resolved === undefined) {
+    throw new UnknownPluginFamilyError(value);
+  }
+  return resolved;
 }
 
 function normalizeDrainPolicy(value) {

package/src/scaffold/copyTemplate.js

@@ -0,0 +1,71 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { substituteTokens } from "./tokens.js";
+
+/**
+ * Refuse to scaffold into a non-empty directory unless `force` is set. Never
+ * deletes anything — `force` only lifts the refusal, it does not clear the
+ * directory first, so pre-existing unrelated files are left alone and
+ * template files land on top of (overwrite) any same-named files.
+ */
+export async function ensureWritableOutputDir(outDir, force) {
+  let entries;
+  try {
+    entries = await fs.readdir(outDir);
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+  if (entries.length > 0 && !force) {
+    throw new Error(
+      `Refusing to scaffold into non-empty directory ${outDir} ` +
+        `(${entries.length} existing ${entries.length === 1 ? "entry" : "entries"}). ` +
+        `Pass --force to scaffold into it anyway.`,
+    );
+  }
+}
+
+/**
+ * Copy every file under `templateDir` into `outDir`, applying token
+ * substitution to BOTH file contents and file/directory names. Every
+ * template file is treated as UTF-8 text — correct for this SDK's templates
+ * (JSON/JS/C/C++/Markdown), and deliberate: a template that ever needs a
+ * binary asset is a signal to reconsider, not something this copier should
+ * silently support.
+ *
+ * Returns the sorted list of output-relative (posix-style) file paths that
+ * were written.
+ */
+export async function copyTemplateTree(templateDir, outDir, tokens) {
+  const created = [];
+
+  async function walk(currentTemplateDir, currentOutDir) {
+    const entries = await fs.readdir(currentTemplateDir, {
+      withFileTypes: true,
+    });
+    for (const entry of entries) {
+      const destName = substituteTokens(entry.name, tokens);
+      const srcPath = path.join(currentTemplateDir, entry.name);
+      const destPath = path.join(currentOutDir, destName);
+      if (entry.isDirectory()) {
+        await fs.mkdir(destPath, { recursive: true });
+        await walk(srcPath, destPath);
+      } else if (entry.isFile()) {
+        await fs.mkdir(path.dirname(destPath), { recursive: true });
+        const raw = await fs.readFile(srcPath, "utf8");
+        await fs.writeFile(destPath, substituteTokens(raw, tokens), "utf8");
+        created.push(
+          path.relative(outDir, destPath).split(path.sep).join("/"),
+        );
+      }
+    }
+  }
+
+  await fs.mkdir(outDir, { recursive: true });
+  await walk(templateDir, outDir);
+  created.sort();
+  return created;
+}

package/src/scaffold/index.js

@@ -0,0 +1,150 @@
+/**
+ * `space-data-module init` — scaffold a new SDN WASM module skeleton from a
+ * family template under `templates/<family>-module/`.
+ *
+ * Family resolution deliberately mirrors `normalizePluginFamily`
+ * (`src/manifest/normalize.js`): an unrecognized value is a THROW, never a
+ * silent fallback to a generic template. Two checks apply, in order:
+ *
+ *   1. Is `--family` even a name in the SDK's plugin-family vocabulary
+ *      (the same vocabulary `pluginFamily` in a manifest is validated
+ *      against)? If not, `normalizePluginFamily` itself throws
+ *      `UnknownPluginFamilyError`, naming the offender and the whole
+ *      vocabulary.
+ *   2. Does that family have an init TEMPLATE (`templates/<family>-module/
+ *      plugin-manifest.json`)? Most families do not — only `propagator`
+ *      ships one today. If not, `ScaffoldFamilyTemplateError` names the
+ *      offender and lists the families that DO have a template.
+ *
+ * Both refusals name the value and the valid vocabulary; neither ever
+ * degrades into "pick the closest template" or "use a blank template".
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { normalizePluginFamily } from "../manifest/normalize.js";
+import { copyTemplateTree, ensureWritableOutputDir } from "./copyTemplate.js";
+import { buildTokenMap } from "./tokens.js";
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+export const packageRoot = path.resolve(moduleDir, "..", "..");
+export const templatesRoot = path.join(packageRoot, "templates");
+
+const TEMPLATE_DIR_SUFFIX = "-module";
+/** The file every real init-scaffold template must have at its root. This is
+ * what distinguishes a scaffold template (propagator-module) from the
+ * pre-existing ABI-header-only reference dirs under templates/
+ * (gpu-module, provider-access-module) that ship no plugin-manifest.json and
+ * are not meant to be scaffolded from. */
+const TEMPLATE_MANIFEST_FILE = "plugin-manifest.json";
+
+/**
+ * Thrown when `--family` names a value that does not have an init template,
+ * even if it IS a recognized `pluginFamily` string. Distinct from
+ * `UnknownPluginFamilyError` (which fires first, for values that are not a
+ * recognized family AT ALL) — this one fires for real-but-template-less
+ * families such as "sensor" today.
+ */
+export class ScaffoldFamilyTemplateError extends Error {
+  constructor(value, availableFamilies) {
+    const list =
+      availableFamilies.length > 0
+        ? availableFamilies.join(", ")
+        : "(none — no templates/*-module directory has a plugin-manifest.json yet)";
+    super(
+      `No init template for family ${JSON.stringify(value)}. ` +
+        `Families with an init template: ${list}.`,
+    );
+    this.name = "ScaffoldFamilyTemplateError";
+    this.code = "unknown-scaffold-family-template";
+    this.value = value;
+    this.availableFamilies = availableFamilies;
+  }
+}
+
+/** List family names (e.g. `["propagator"]`) that have a real init template. */
+export function listScaffoldFamilies() {
+  let entries;
+  try {
+    entries = fs.readdirSync(templatesRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  const families = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.endsWith(TEMPLATE_DIR_SUFFIX)) {
+      continue;
+    }
+    const manifestPath = path.join(
+      templatesRoot,
+      entry.name,
+      TEMPLATE_MANIFEST_FILE,
+    );
+    if (fs.existsSync(manifestPath)) {
+      families.push(entry.name.slice(0, -TEMPLATE_DIR_SUFFIX.length));
+    }
+  }
+  return families.sort();
+}
+
+/**
+ * Resolve `--family` to a template directory, or throw loudly. See the
+ * module docstring for the two-stage refusal shape.
+ */
+export function resolveScaffoldTemplateDir(family) {
+  // Stage 1: is this even a real plugin family? Throws UnknownPluginFamilyError
+  // (naming the value + the FULL manifest vocabulary) if not.
+  normalizePluginFamily(family);
+
+  const normalized = String(family).trim().toLowerCase();
+  const available = listScaffoldFamilies();
+  if (!available.includes(normalized)) {
+    // Stage 2: real family, but no init template ships for it (yet).
+    throw new ScaffoldFamilyTemplateError(family, available);
+  }
+  return path.join(templatesRoot, `${normalized}${TEMPLATE_DIR_SUFFIX}`);
+}
+
+/**
+ * Scaffold a new module skeleton.
+ *
+ * @param {object} options
+ * @param {string} options.family - e.g. "propagator". Must have an init
+ *   template (see {@link resolveScaffoldTemplateDir}).
+ * @param {string} options.name - kebab-case module name, e.g. "my-propagator".
+ * @param {string} [options.outDir] - defaults to `./<name>` under cwd.
+ * @param {string} [options.pluginId] - defaults to
+ *   `com.orbpro.<name-with-dots>`.
+ * @param {boolean} [options.force] - allow scaffolding into a non-empty
+ *   `outDir`.
+ * @returns {Promise<{ok: true, family: string, name: string, pluginId: string, outDir: string, files: string[]}>}
+ */
+export async function scaffoldModule({
+  family,
+  name,
+  outDir,
+  pluginId,
+  force = false,
+} = {}) {
+  const templateDir = resolveScaffoldTemplateDir(family);
+  const tokens = buildTokenMap({ name, pluginId });
+  const resolvedOutDir = path.resolve(outDir ?? path.join(process.cwd(), name));
+
+  await ensureWritableOutputDir(resolvedOutDir, force === true);
+  const files = await copyTemplateTree(templateDir, resolvedOutDir, tokens);
+
+  return {
+    ok: true,
+    family: String(family).trim().toLowerCase(),
+    name,
+    pluginId: tokens.PLUGIN_ID,
+    outDir: resolvedOutDir,
+    files,
+  };
+}
+
+export { defaultPluginId } from "./tokens.js";

package/src/scaffold/tokens.js

@@ -0,0 +1,90 @@
+/**
+ * Token vocabulary for `space-data-module init`.
+ *
+ * These are the ONLY tokens the scaffold engine substitutes. They are matched
+ * as whole `__NAME__` runs so a token can never partially match inside a
+ * longer identifier that happens to share a prefix.
+ */
+export const SCAFFOLD_TOKEN_NAMES = Object.freeze([
+  "MODULE_NAME",
+  "PLUGIN_ID",
+  "MODULE_NAME_SNAKE",
+  "MODULE_NAME_CAMEL",
+]);
+
+const TOKEN_PATTERN = new RegExp(
+  `__(${SCAFFOLD_TOKEN_NAMES.join("|")})__`,
+  "g",
+);
+
+const MODULE_NAME_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+/**
+ * Validate a `--name` value against the kebab-case shape every derived token
+ * assumes. Refuses loudly rather than silently mangling an unexpected name
+ * into something that merely looks plausible.
+ */
+export function assertValidModuleName(name) {
+  if (typeof name !== "string" || name.trim().length === 0) {
+    throw new Error("--name is required and must be a non-empty string.");
+  }
+  if (!MODULE_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `--name ${JSON.stringify(name)} is not valid. Module names must be ` +
+        `lowercase kebab-case: start with a letter, then letters, digits, or ` +
+        `single hyphens (e.g. "keplerian-reference").`,
+    );
+  }
+}
+
+/** `foo-bar` -> `foo_bar` */
+export function toSnakeCase(name) {
+  return name.replace(/-/g, "_");
+}
+
+/** `foo-bar` -> `fooBar` */
+export function toCamelCase(name) {
+  return name
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map((part, index) =>
+      index === 0
+        ? part.toLowerCase()
+        : part.charAt(0).toUpperCase() + part.slice(1).toLowerCase(),
+    )
+    .join("");
+}
+
+/**
+ * `com.orbpro.<module-name-with-dots>` — the documented default `--plugin-id`
+ * when the author does not supply one. Hyphens become dots so the plugin id
+ * reads as reverse-DNS-style segments, matching how the SDK's own examples
+ * namespace multi-word module ids.
+ */
+export function defaultPluginId(name) {
+  return `com.orbpro.${name.replace(/-/g, ".")}`;
+}
+
+/**
+ * Build the full token -> replacement-string map for one scaffold run.
+ */
+export function buildTokenMap({ name, pluginId }) {
+  assertValidModuleName(name);
+  const resolvedPluginId =
+    typeof pluginId === "string" && pluginId.trim().length > 0
+      ? pluginId.trim()
+      : defaultPluginId(name);
+  return {
+    MODULE_NAME: name,
+    PLUGIN_ID: resolvedPluginId,
+    MODULE_NAME_SNAKE: toSnakeCase(name),
+    MODULE_NAME_CAMEL: toCamelCase(name),
+  };
+}
+
+/** Substitute every `__TOKEN__` occurrence in `text` using `tokens`. */
+export function substituteTokens(text, tokens) {
+  return text.replace(TOKEN_PATTERN, (match, key) =>
+    key in tokens ? tokens[key] : match,
+  );
+}

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
+}