space-data-module-sdk 0.8.14 → 0.8.15

package/bin/space-data-module.js

@@ -42,6 +42,8 @@ async function main(argv) {
       return runParity(rest);
     case "parity-gate":
       return runParityGateCommand(rest);
+    case "conformance":
+      return runConformanceCommand(rest);
     case "protect":
       return runProtect(rest);
     case "sign":
@@ -241,6 +243,9 @@ function printUsage() {
   space-data-module parity-gate                                          (THE isomorphism acceptance gate: certified artifact set x real lanes)
   space-data-module parity-gate --artifact rf-fspl=./dist/isomorphic/module.wasm:module --json
   space-data-module parity-gate --gate-manifest ./parity/negative-control.json --expect-fail   (prove the gate can fail)
+  space-data-module conformance propagator --artifact ./dist/isomorphic/module.wasm             (official-harness conformance: WASM artifacts only)
+  space-data-module conformance propagator --artifact ./dist/isomorphic/module.wasm --vectors ./vectors/vectors.json --json
+  space-data-module conformance propagator --self-test                                          (must exit 0 BY failing: planted defects all caught)
   space-data-module flow check ./flows/my.flow.json --deps ./modules-root
   space-data-module flow compile ./flows/my.flow.json --deps ./modules-root [--out ./flows/my/dist]
   space-data-module protect --manifest ./manifest.json --wasm ./dist/module.wasm --json
@@ -401,6 +406,92 @@ async function runParity(argv) {
   return report.ok ? 0 : 2;
 }
 
+// space-data-module conformance <family> --artifact ./dist/isomorphic/module.wasm
+//   [--vectors ./vectors/vectors.json] [--json]
+//   [--leak-warmup N] [--leak-cycles N] [--leak-entities N]
+// space-data-module conformance <family> --self-test    (must exit 0 BY failing)
+//
+// The official-harness conformance runner (finding
+// graph/findings/official-harness-shapes.md §5): WASM artifacts ONLY, family-
+// dispatched, shipped with its own negative control. PASS / PASS-WITH-GAPS
+// exit 0 (gaps are named); FAIL exits 1. The self-test runs the suite against
+// mock propagators with planted defects — one per real defect class the
+// finding documented — and exits 0 only when every defect is CAUGHT.
+async function runConformanceCommand(argv) {
+  const [family, ...rest] = argv;
+  if (!family || family.startsWith("--")) {
+    throw new Error(
+      "conformance requires a family argument, e.g. `space-data-module conformance propagator ...`",
+    );
+  }
+  const options = { json: false, selfTest: false, leak: {} };
+  for (let index = 0; index < rest.length; index += 1) {
+    const value = rest[index];
+    switch (value) {
+      case "--artifact":
+      case "--wasm":
+        options.artifactPath = path.resolve(requireValue(rest, ++index, value));
+        break;
+      case "--vectors":
+        options.vectorsPath = path.resolve(requireValue(rest, ++index, value));
+        break;
+      case "--json":
+        options.json = true;
+        break;
+      case "--self-test":
+        options.selfTest = true;
+        break;
+      case "--leak-warmup":
+        options.leak.warmupCycles = Number(requireValue(rest, ++index, value));
+        break;
+      case "--leak-cycles":
+        options.leak.measureCycles = Number(requireValue(rest, ++index, value));
+        break;
+      case "--leak-entities":
+        options.leak.entities = Number(requireValue(rest, ++index, value));
+        break;
+      default:
+        throw new Error(`conformance: unknown flag ${value}`);
+    }
+  }
+
+  const conformance = await import("../src/conformance/index.js");
+
+  if (options.selfTest) {
+    if (family !== "propagator") {
+      throw new conformance.UnknownConformanceFamilyError(family);
+    }
+    const outcome = await conformance.runPropagatorSelfTest();
+    if (options.json) {
+      console.log(JSON.stringify(outcome, null, 2));
+    } else {
+      console.log(conformance.formatSelfTestReport(outcome));
+    }
+    return outcome.ok ? 0 : 1;
+  }
+
+  if (!options.artifactPath) {
+    throw new Error("conformance requires --artifact <module.wasm> (or --self-test).");
+  }
+  const report = await conformance.runConformance({
+    family,
+    artifactPath: options.artifactPath,
+    vectorsPath: options.vectorsPath,
+    leak: options.leak,
+  });
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    const text = conformance.formatConformanceReport(report);
+    if (report.verdict === "FAIL") {
+      console.error(text);
+    } else {
+      console.log(text);
+    }
+  }
+  return report.verdict === "FAIL" ? 1 : 0;
+}
+
 // space-data-module parity-gate [--gate-manifest ./parity/gate.json]
 //   [--artifact <id>=<path>[:<surface>]] [--lanes ...] [--json]
 //   [--require-native-wasmedge] [--expect-fail] [--timeout-sec N]

package/docs/conformance.md

@@ -0,0 +1,92 @@
+# Conformance runner
+
+**Status:** v1 — W1.4 of `graph/tasks/official-harness-shapes-program.md`,
+implementing `graph/findings/official-harness-shapes.md` §5. Family kits:
+`propagator` (SHIP 1). Maneuver is Wave 2 (EXPERIMENTAL, fix-then-freeze); OD
+is deferred by ruling. **A family with no kit can never be `CORE`.**
+
+WASM artifacts ONLY (owner ruling 2026-08-10: "No JS propagator!!!! WASM
+ONLY"). The runner instantiates a compiled `dist/isomorphic/module.wasm` and
+drives the family's ABI directly; there is no path that certifies a JavaScript
+object, because JS registries are internal engine plumbing, never a public
+contract.
+
+## Commands
+
+```
+space-data-module conformance propagator --artifact ./dist/isomorphic/module.wasm
+space-data-module conformance propagator --artifact ./dist/isomorphic/module.wasm \
+    --vectors ./vectors/vectors.json --json
+space-data-module conformance propagator --self-test    # must exit 0 BY failing
+```
+
+- `--artifact` — the compiled module. Its sha256 goes in the report; a
+  conformance claim binds to CONTENT, not to a name.
+- `--vectors` — the module's corpus (`vectors.json` + `PROVENANCE.md`, the
+  format proven by the reference module's `vectors/` suite). Default: the
+  runner walks up from the artifact to the package root and takes
+  `vectors/vectors.json`. **The corpus is the module's own**: Tier B anchors
+  are model-specific, so a two-body corpus is never forced onto an SGP4
+  module, and a missing corpus is a NAMED GAP, never a silent pass.
+- `--leak-warmup / --leak-cycles / --leak-entities` — lifecycle-leak window
+  overrides (defaults 20 / 200 / 256, the reference module's proven numbers).
+- Exit codes: `PASS` and `PASS-WITH-GAPS` exit 0 (gaps are listed in the
+  report); `FAIL` exits 1 with the offending check and case named.
+
+Library surface: `space-data-module-sdk/conformance` exports
+`runConformance`, `runPropagatorSuite`, `runPropagatorSelfTest`,
+`computeVerdict`, the ABI driver and the error-code table.
+
+## What is checked
+
+| Tier | Check | Source of authority |
+|---|---|---|
+| 0 | real instantiation + required export set | [propagator-abi.md](propagator-abi.md) §The export set |
+| 0 | cross-runtime byte-identity | **GAP here by design** — the parity gate (`space-data-module parity-gate`) is the Tier 0 authority; this runner never re-certifies half of it |
+| B | corpus anchors reproduced within band | the module's `vectors.json` (tolerance policy `abs + rel * |expected|`); NaN is its own failure class |
+| C | vis-viva closure, period closure | corpus-declared invariants (`conformance.mu` from the corpus; ECEF un-rotation when the module declares frame 3) — run only where the corpus declares them applicable to the model |
+| C | determinism as BYTES, surviving destroy/re-ingest | ABI §Parity envelope |
+| C | frame/flags/reserved declared, corpus-consistent | ABI §Frames — a frame declaration that contradicts the module's own corpus is the silently-wrong-numbers defect |
+| C | batch and single agree exactly | ABI §Threading — the batch path is the same physics |
+| C | typed refusals (NOT_INITIALIZED / BAD_ENTITY_INDEX / unphysical ingest) | ABI §Error codes — the degradation ladder needs distinguishable codes |
+| C | create RETURNS its handle | ABI §Identity — "the entity I just created is count−1" is the race the harness exists to kill (finding §4.4) |
+| 4 | lifecycle leak: zero page growth after warm-up | ABI §Lifetime |
+| 4 | destroy idempotent, refuses typed, comes back cleanly | ABI §Lifetime |
+| 4 | leak-metric negative control | a gate never observed to fail is indistinguishable from one that cannot fail |
+
+## The self-test
+
+`--self-test` runs the SAME suite against mock propagators, each carrying ONE
+planted defect drawn from a real defect class the finding documented live:
+
+| Planted defect | Real-world citation | Must be caught by |
+|---|---|---|
+| `units-km` (1000× error) | the `orbpro_propagator.h` km/meters contradiction (finding §4.1) | `tierB/anchors` |
+| `leaky-destroy` | `destroySource(){}` in both shipped propagators (§4.5) | `tier4/lifecycle-leak` |
+| `confident-nonsense` (accepts e ≥ 1) | the underground phasing orbit (§5) | `tierC/typed-refusals` |
+| `count-fallback` (returns success, not the handle) | three families deriving count−1 (§4.4) | `tierC/create-returns-handle` |
+| `frame-lies` (declares TEME, writes ECEF) | the Δv frame never pinned (§4.3) | `tierC/frame-flags-reserved-declared` |
+| `batch-divergence` | batch path not the same physics | `tierC/batch-single-agreement` |
+| `nondeterministic` | byte-determinism is the parity envelope's floor | `tierC/determinism-byte-identity` |
+| `missing-exports` | destroy was optional once; it is not now | `tier0/instantiation-and-exports` |
+
+The self-test exits 0 only when the conformant baseline mock is clean AND
+every planted defect is caught by the check that owns it. It needs no
+toolchain, no artifact and no network — `npm run conformance:self-test`.
+
+## Receipt & trust (Wave 4, not yet wired)
+
+The conformance receipt travels as a bundle `ATTESTATION` entry
+(publisher-signed under bundle scope); the graduated listing requirement
+(receipt REQUIRED for `CORE`+`ANONYMOUS`, badge for `RECOMMENDED`) and the
+`SDN-CONFORMANCE-RECEIPT-V1` third-party attestor domain are W4.1/W4.2 of the
+program — see the finding §5 "Receipt & trust".
+
+## Reference implementation
+
+`space-data-network-modules propagator/keplerian-reference` is the exemplar
+the kit was generalized from: its `tests/` are the original expression of
+these checks, its `vectors/` suite is the corpus format, and
+`tests/sdk-conformance-runner.test.mjs` proves the runner reaches the same
+verdict on the same artifact — including the corrupted-corpus negative
+control.

package/docs/propagator-abi.md

@@ -28,6 +28,7 @@ test fixture.
 - [Lifetime](#lifetime)
 - [Versioning](#versioning)
 - [Parity envelope](#parity-envelope)
+- [Conformance](#conformance)
 - [Consumer seam](#consumer-seam)
 - [Guest usage](#guest-usage)
 
@@ -339,15 +340,16 @@ and must leave the module usable — a destroyed module refuses to propagate
 (`NOT_INITIALIZED`) rather than reading freed state, and comes back cleanly on
 the next ingest.
 
-> **Known defect, stated so it is not mistaken for the standard.**
-> `destroySource()` is literally `{}` in BOTH shipped first-party propagators,
-> and both therefore FAIL this leak test today. sgp4's `createSourceFromState`
-> additionally re-ingests the whole catalogue and tears down the 120 fps worker
-> pool for a single burn, polluting the identity table with a synthetic NORAD.
-> Fixing them is **W1.5** in `graph/tasks/official-harness-shapes-program.md`;
-> the finding's analysis is §4.5. The reference module passes the leak test
-> today, deliberately — it sets the bar W1.5 brings the first-party
-> propagators up to.
+> **Historical defect, retired 2026-08-12.** `destroySource()` was literally
+> `{}` in BOTH shipped first-party propagators when this ABI was written
+> (finding §4.5), and sgp4's `createSourceFromState` re-ingested the whole
+> catalogue for a single burn. The maneuver program landed the fix on OrbPro
+> `main` (`2db279766c` and `97cc38127e`): both propagators now recycle
+> post-burn source SLOTS — the entity stays resident so no index above it
+> moves, destroy marks the slot free, and creating a source re-points the
+> recycled entity in place. The reference module remains the leak-test bar,
+> now enforced mechanically by
+> `space-data-module conformance propagator` (tier4/lifecycle-leak).
 
 ## Versioning
 
@@ -399,6 +401,23 @@ Run it:
 space-data-module parity-gate --artifact <id>=./dist/isomorphic/module.wasm:module
 ```
 
+## Conformance
+
+What "official" buys a third party: one command, family-dispatched, shipped
+with its own negative control ([docs/conformance.md](conformance.md)):
+
+```
+space-data-module conformance propagator --artifact ./dist/isomorphic/module.wasm
+space-data-module conformance propagator --self-test    # must exit 0 BY failing
+```
+
+The runner adjudicates everything this document specifies that a single lane
+can observe — the export set, the corpus anchors, the invariants with no
+stored expectation, the error-code table, and the leak test — and reports the
+cross-runtime lane honestly as a gap that only the parity gate above closes.
+`PASS` / `PASS-WITH-GAPS` exit 0; `FAIL` exits 1 with the offending check
+named.
+
 ## Consumer seam
 
 Per the pluggable-propagation law (owner, 2026-07-29), **every surface that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.8.14",
+  "version": "0.8.15",
   "license": "Apache-2.0",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",
@@ -32,6 +32,7 @@
     },
     "./include/*": "./include/*",
     "./generated/propagator-abi": "./src/generated/orbpro/propagator-abi.js",
+    "./conformance": "./src/conformance/index.js",
     "./compiler": "./src/compiler/index.js",
     "./compiler/emception": "./src/compiler/emception.js",
     "./bundle": "./src/bundle/index.js",
@@ -67,6 +68,7 @@
       "default": "./src/host/moduleFlatbufferStreamPump.js"
     },
     "./testing": "./src/testing/index.js",
+    "./testing/isomorphic": "./src/testing/isomorphicHarness.js",
     "./standards": {
       "browser": "./src/standards/browser.js",
       "default": "./src/standards/index.js"
@@ -94,6 +96,7 @@
     "test:parity-gate-lanes": "SPACE_DATA_MODULE_SDK_ENABLE_PARITY_GATE=1 node --test test/parity-gate-lanes.test.js",
     "gate:parity": "node ./bin/space-data-module.js parity-gate",
     "gate:parity-negative-control": "node ./bin/space-data-module.js parity-gate --gate-manifest ./parity/negative-control.json --expect-fail",
+    "conformance:self-test": "node ./bin/space-data-module.js conformance propagator --self-test",
     "test:stream-ingest": "node --test test/runtime-host-stream-ingest.test.js",
     "test:module-stream": "node --test test/module-flatbuffer-stream-pump.test.js",
     "benchmark:stream-1gib": "SPACE_DATA_MODULE_SDK_ENABLE_1GB_STREAM_TEST=1 node --test test/runtime-host-stream-ingest.test.js",
@@ -122,4 +125,4 @@
   "engines": {
     "node": ">=20.0.0"
   }
-}
+}

package/src/conformance/abiDriver.js

@@ -0,0 +1,225 @@
+/**
+ * The propagator-family conformance driver: load a WASM artifact and drive the
+ * official OrbPro propagator ABI (docs/propagator-abi.md) from JavaScript.
+ *
+ * Note what this file does NOT contain: a single hard-coded byte offset. Every
+ * read goes through ORBPRO_STATE_VECTOR / ORBPRO_OMM_RECORD, the bindings
+ * GENERATED from the same IDL the C header comes from
+ * (schemas/orbpro/Propagator.fbs -> scripts/generate-propagator-abi.mjs).
+ * The JS reader and the C writer cannot disagree, because neither of them
+ * wrote the layout down.
+ *
+ * This is the generalization of the reference module's test harness
+ * (space-data-network-modules propagator/keplerian-reference/tests/harness.mjs,
+ * the W1.2 exemplar) into the SDK, so `space-data-module conformance` can
+ * target ANY artifact claiming the propagator family — W1.4 of
+ * graph/tasks/official-harness-shapes-program.md.
+ */
+
+import fs from "node:fs/promises";
+
+import {
+  ORBPRO_OMM_RECORD,
+  ORBPRO_STATE_VECTOR,
+  ReferenceFrame,
+  StateFlags,
+} from "../generated/orbpro/propagator-abi.js";
+
+export { ORBPRO_OMM_RECORD, ORBPRO_STATE_VECTOR, ReferenceFrame, StateFlags };
+
+/**
+ * Documented error codes — the ABI "Error codes" table in
+ * docs/propagator-abi.md. Every failure returns its OWN code; a propagator
+ * that answers -1 for everything is unconformable because the host cannot
+ * place the failure on the degradation ladder.
+ */
+export const ErrorCode = Object.freeze({
+  OK: 0,
+  NOT_INITIALIZED: -1,
+  BAD_ENTITY_INDEX: -2,
+  NULL_OUTPUT: -3,
+  BAD_INPUT: -4,
+  NOT_CONVERGED: -5,
+  UNPHYSICAL: -6,
+});
+
+/**
+ * The export set the propagator harness requires. Structural absence of any
+ * of these is a Tier 0 conformance failure with the missing name in the
+ * report — never "not found".
+ */
+export const REQUIRED_ABI_EXPORTS = Object.freeze([
+  "memory",
+  "plugin_alloc",
+  "plugin_free",
+  "plugin_init_omm",
+  "plugin_ingest_omm_one",
+  "plugin_propagate",
+  "plugin_propagate_batch",
+  "plugin_entity_count",
+  "plugin_destroy",
+]);
+
+/**
+ * Instantiate an artifact under WASI preview1 and wrap it in the driver
+ * interface the conformance suite consumes.
+ *
+ * Deliberately NOT calling wasi.start(): SDK-built artifacts declare the
+ * `command` invoke surface, so `_start` is the stdin-driven invoke loop and
+ * blocks forever when driven from a test. The propagator ABI is a set of
+ * directly-callable exports — which is exactly how the engine calls it — so
+ * conformance calls them directly. The command surface is exercised by the
+ * parity gate, which stays the Tier 0 cross-runtime authority.
+ */
+export async function loadPropagatorArtifact(artifactPath) {
+  const { WASI } = await import("node:wasi");
+  const bytes = await fs.readFile(artifactPath);
+  const wasi = new WASI({ version: "preview1", args: ["module"], env: {} });
+  const module = await WebAssembly.compile(bytes);
+  const instance = await WebAssembly.instantiate(module, wasi.getImportObject());
+  return new PropagatorAbiDriver(instance);
+}
+
+export class PropagatorAbiDriver {
+  constructor(instance) {
+    this.instance = instance;
+    this.exports = instance.exports;
+  }
+
+  /** Export names, for the Tier 0 structural check. */
+  exportNames() {
+    return Object.keys(this.exports);
+  }
+
+  get memory() {
+    return this.exports.memory;
+  }
+
+  /** Linear-memory size, the leak test's only honest metric. */
+  memoryBytes() {
+    return this.exports.memory.buffer.byteLength;
+  }
+
+  alloc(byteLength) {
+    const pointer = this.exports.plugin_alloc(byteLength);
+    if (pointer === 0) throw new Error(`plugin_alloc(${byteLength}) returned 0`);
+    return pointer;
+  }
+
+  free(pointer) {
+    this.exports.plugin_free(pointer);
+  }
+
+  /** Pack element sets into the ABI's OrbProOMMRecord layout. */
+  packOmmRecords(records) {
+    const { size, offsets } = ORBPRO_OMM_RECORD;
+    const buffer = new ArrayBuffer(size * records.length);
+    const view = new DataView(buffer);
+    records.forEach((record, index) => {
+      const base = index * size;
+      view.setFloat64(base + offsets.epoch_jd, record.epochJd, true);
+      view.setFloat64(base + offsets.mean_motion, record.meanMotionRevPerDay, true);
+      view.setFloat64(base + offsets.eccentricity, record.eccentricity, true);
+      view.setFloat64(base + offsets.inclination, record.inclinationDeg, true);
+      view.setFloat64(base + offsets.ra_of_asc_node, record.raOfAscNodeDeg, true);
+      view.setFloat64(base + offsets.arg_of_pericenter, record.argOfPericenterDeg, true);
+      view.setFloat64(base + offsets.mean_anomaly, record.meanAnomalyDeg, true);
+      view.setFloat64(base + offsets.bstar, record.bstar ?? 0, true);
+      view.setFloat64(base + offsets.mean_motion_dot, record.meanMotionDot ?? 0, true);
+      view.setFloat64(base + offsets.mean_motion_ddot, record.meanMotionDdot ?? 0, true);
+      view.setUint32(base + offsets.norad_cat_id, record.noradCatId ?? 0, true);
+    });
+    return new Uint8Array(buffer);
+  }
+
+  initFromOmm(records) {
+    const packed = this.packOmmRecords(records);
+    const pointer = this.alloc(packed.byteLength);
+    new Uint8Array(this.memory.buffer).set(packed, pointer);
+    try {
+      return this.exports.plugin_init_omm(pointer, records.length);
+    } finally {
+      this.free(pointer);
+    }
+  }
+
+  ingestOne(record) {
+    const packed = this.packOmmRecords([record]);
+    const pointer = this.alloc(packed.byteLength);
+    new Uint8Array(this.memory.buffer).set(packed, pointer);
+    try {
+      return this.exports.plugin_ingest_omm_one(pointer);
+    } finally {
+      this.free(pointer);
+    }
+  }
+
+  /** Returns {status, state, bytes} — bytes for the byte-identity checks. */
+  propagate(julianDate, entityIndex) {
+    const pointer = this.alloc(ORBPRO_STATE_VECTOR.size);
+    try {
+      const status = this.exports.plugin_propagate(julianDate, entityIndex, pointer);
+      const bytes = new Uint8Array(
+        this.memory.buffer.slice(pointer, pointer + ORBPRO_STATE_VECTOR.size),
+      );
+      return { status, state: decodeStateVector(bytes), bytes };
+    } finally {
+      this.free(pointer);
+    }
+  }
+
+  propagateBatch(julianDate, count) {
+    const pointer = this.alloc(ORBPRO_STATE_VECTOR.size * count);
+    try {
+      const status = this.exports.plugin_propagate_batch(julianDate, pointer, count);
+      const states = [];
+      for (let index = 0; index < count; index += 1) {
+        const start = pointer + index * ORBPRO_STATE_VECTOR.size;
+        states.push(
+          decodeStateVector(
+            new Uint8Array(this.memory.buffer.slice(start, start + ORBPRO_STATE_VECTOR.size)),
+          ),
+        );
+      }
+      return { status, states };
+    } finally {
+      this.free(pointer);
+    }
+  }
+
+  entityCount() {
+    return this.exports.plugin_entity_count();
+  }
+
+  destroy() {
+    this.exports.plugin_destroy();
+  }
+}
+
+/** Decode a state vector using the GENERATED offsets. */
+export function decodeStateVector(bytes) {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const { offsets } = ORBPRO_STATE_VECTOR;
+  return {
+    epoch: view.getFloat64(offsets.epoch, true),
+    position: [
+      view.getFloat64(offsets.position + 0, true),
+      view.getFloat64(offsets.position + 8, true),
+      view.getFloat64(offsets.position + 16, true),
+    ],
+    velocity: [
+      view.getFloat64(offsets.velocity + 0, true),
+      view.getFloat64(offsets.velocity + 8, true),
+      view.getFloat64(offsets.velocity + 16, true),
+    ],
+    referenceFrame: view.getUint8(offsets.reference_frame),
+    // The three IDL-reserved bytes. Read them explicitly: they are part of the
+    // contract, and a writer that skips them leaves the previous call behind.
+    reserved: [
+      view.getUint8(offsets.reference_frame + 1),
+      view.getUint8(offsets.reference_frame + 2),
+      view.getUint8(offsets.reference_frame + 3),
+    ],
+    flags: view.getUint32(offsets.flags, true),
+  };
+}

package/src/conformance/index.js

@@ -0,0 +1,151 @@
+/**
+ * `space-data-module conformance <family>` — the official-harness conformance
+ * runner (finding graph/findings/official-harness-shapes.md §5; W1.4 of the
+ * harness program).
+ *
+ * WASM artifacts ONLY (owner ruling 2026-08-10: "No JS propagator!!!! WASM
+ * ONLY") — the runner instantiates a compiled module and drives the family's
+ * ABI; there is no path that certifies a JS object, because JS registries are
+ * internal engine plumbing, never a public contract.
+ *
+ * Verdict vocabulary matches the gauntlet's: PASS / PASS-WITH-GAPS / FAIL.
+ * A gap is a check that could not be adjudicated HERE (no corpus, or a lane
+ * another command owns) — named, never silent.
+ */
+
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { loadPropagatorArtifact } from "./abiDriver.js";
+import { computeVerdict, runPropagatorSuite } from "./propagatorSuite.js";
+
+export { ErrorCode, REQUIRED_ABI_EXPORTS } from "./abiDriver.js";
+export {
+  computeVerdict,
+  runPropagatorSuite,
+  DEFAULT_LEAK_OPTIONS,
+} from "./propagatorSuite.js";
+export { runPropagatorSelfTest, formatSelfTestReport } from "./selfTest.js";
+
+/**
+ * Families with a conformance kit. The vocabulary is the SDS pluginCategory
+ * projection (W0.3): unknown families are refused BY NAME with the known set,
+ * never coerced — the ANALYSIS fallback was the namespace corruption the
+ * finding killed.
+ */
+export const CONFORMANCE_FAMILIES = Object.freeze(["propagator"]);
+
+export class UnknownConformanceFamilyError extends Error {
+  constructor(family) {
+    super(
+      `no conformance kit for family "${family}" — kits exist for: ` +
+        `${CONFORMANCE_FAMILIES.join(", ")}. A family with no kit can never be CORE ` +
+        "(finding §5); maneuver is Wave 2 (EXPERIMENTAL), OD is deferred by ruling.",
+    );
+    this.name = "UnknownConformanceFamilyError";
+    this.family = family;
+  }
+}
+
+/**
+ * Locate a module's own corpus: <package-root>/vectors/vectors.json, walking
+ * up from the artifact (dist/isomorphic/module.wasm -> package root).
+ */
+export async function resolveCorpusPath(artifactPath) {
+  let dir = path.dirname(path.resolve(artifactPath));
+  for (let depth = 0; depth < 5; depth += 1) {
+    const candidate = path.join(dir, "vectors", "vectors.json");
+    try {
+      await fs.access(candidate);
+      return candidate;
+    } catch {
+      // keep walking
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export async function loadCorpus(vectorsPath) {
+  const raw = await fs.readFile(vectorsPath, "utf8");
+  const corpus = JSON.parse(raw);
+  if (!Array.isArray(corpus.cases)) {
+    throw new Error(`${vectorsPath} has no cases[] — not a conformance corpus`);
+  }
+  return corpus;
+}
+
+/**
+ * Run conformance for one family against one WASM artifact.
+ *
+ * @param {object} options
+ * @param {string} options.family        e.g. "propagator"
+ * @param {string} options.artifactPath  dist/isomorphic/module.wasm
+ * @param {string} [options.vectorsPath] corpus override; default = the
+ *   module's own vectors/vectors.json, found by walking up from the artifact
+ * @param {object} [options.leak]        {warmupCycles, measureCycles, entities}
+ */
+export async function runConformance(options) {
+  const family = String(options.family ?? "").trim().toLowerCase();
+  if (!CONFORMANCE_FAMILIES.includes(family)) {
+    throw new UnknownConformanceFamilyError(options.family);
+  }
+  const artifactPath = path.resolve(options.artifactPath);
+  const artifactBytes = await fs.readFile(artifactPath);
+  const artifactSha256 = crypto
+    .createHash("sha256")
+    .update(artifactBytes)
+    .digest("hex");
+
+  let vectorsPath = options.vectorsPath
+    ? path.resolve(options.vectorsPath)
+    : await resolveCorpusPath(artifactPath);
+  let corpus = null;
+  if (vectorsPath) {
+    corpus = await loadCorpus(vectorsPath);
+  }
+
+  const checks = await runPropagatorSuite(
+    () => loadPropagatorArtifact(artifactPath),
+    { corpus, leak: options.leak },
+  );
+
+  return {
+    family,
+    artifact: { path: artifactPath, sha256: artifactSha256 },
+    corpus: vectorsPath
+      ? {
+          path: vectorsPath,
+          schemaVersion: corpus.schemaVersion ?? null,
+          cases: corpus.cases.length,
+          model: corpus.conformance?.model ?? null,
+        }
+      : null,
+    checks,
+    verdict: computeVerdict(checks),
+  };
+}
+
+export function formatConformanceReport(report) {
+  const lines = [];
+  lines.push(`conformance ${report.family} — ${report.verdict}`);
+  lines.push(`  artifact ${report.artifact.path}`);
+  lines.push(`  sha256   ${report.artifact.sha256}`);
+  if (report.corpus) {
+    lines.push(
+      `  corpus   ${report.corpus.path} (${report.corpus.cases} cases` +
+        `${report.corpus.model ? `, model: ${report.corpus.model}` : ""})`,
+    );
+  } else {
+    lines.push("  corpus   none supplied");
+  }
+  for (const check of report.checks) {
+    const marker =
+      check.status === "pass" ? "PASS" : check.status === "gap" ? "GAP " : "FAIL";
+    lines.push(`  [${marker}] ${check.id} — ${check.detail}`);
+  }
+  return lines.join("\n");
+}