space-data-module-sdk 0.8.14 → 0.8.16

package/schemas/orbpro/reference-frame-crosswalk.json

@@ -0,0 +1,108 @@
+{
+  "note": "Every ReferenceFrame-shaped vocabulary that crosses a seam with the orbpro.propagator ABI enum, and how each of its members maps ONTO that enum BY NAMED TOKEN. Numeric identity is never asserted across repositories: ECI==0, TEME==0 and FIXED==0 all collide, and ECEF is 1 in orbpro.plugins but 3 in the ABI. scripts/check-reference-frame-uniqueness.mjs holds this file and schemas/orbpro/Propagator.fbs to each other, and re-reads any listed source that is present on disk.",
+  "authority": "schemas/orbpro/Propagator.fbs :: enum ReferenceFrame",
+  "vocabularies": [
+    {
+      "id": "orbpro.plugins",
+      "description": "PropagatorState.fbs / \"PRST\" \u2014 the wire the compiled sgp4, hpop, conjunction-assessment and sensor-shader modules already emit. Its values are FROZEN by artifacts in the field; collapsing it into the ABI enum is a wire break, tracked as sdk-reference-frame-enum-unification.",
+      "repo": "space-data-network-modules",
+      "source": "propagator/sgp4/schemas/PropagatorState.fbs",
+      "members": {
+        "ECI": "ICRF",
+        "ECEF": "ECEF",
+        "TEME": "TEME",
+        "ICRF": "ICRF"
+      }
+    },
+    {
+      "id": "orbpro.engine",
+      "description": "The OrbPro engine's ReferenceFrame.js. NINE members, not the two this SDK's comment block claimed until 2026-08-30. FIXED/INERTIAL are INVERTED against the ABI's 0/1 \u2014 a live semantic difference, not a numbering accident \u2014 and reconciling that is sdk-reference-frame-enum-unification's job, not this crosswalk's. The four local orbital triads collapse onto OBJECT_REFERENCED with an axes spec.",
+      "repo": "OrbPro",
+      "source": "packages/engine/Source/Core/ReferenceFrame.js",
+      "members": {
+        "FIXED": "ECEF",
+        "INERTIAL": "ICRF",
+        "TEME": "TEME",
+        "VVLH": "OBJECT_REFERENCED",
+        "ENU": "TOPOCENTRIC",
+        "NED": "TOPOCENTRIC",
+        "NEU": "TOPOCENTRIC",
+        "RIC": "OBJECT_REFERENCED",
+        "LVLH": "OBJECT_REFERENCED"
+      }
+    },
+    {
+      "id": "orbpro.conjunction",
+      "description": "ConjunctionCommon.fbs, carried by the conjunction module.",
+      "repo": "space-data-network-modules",
+      "source": "analysis/conjunction-assessment/schemas/ConjunctionCommon.fbs",
+      "members": {
+        "UNKNOWN": null,
+        "ECI": "ICRF",
+        "ECEF": "ECEF",
+        "TEME": "TEME",
+        "ICRF": "ICRF"
+      }
+    },
+    {
+      "id": "modules.foundation.frames",
+      "description": "foundation/frames AxisType, mirroring SDS rfmAxisType. It is an ORIENTATION RULE roster and carries no origin, so it is not a ReferenceFrame; the mapping below is the axis half only, and a consumer still needs the RFMOrigin to have a coordinate system.",
+      "repo": "space-data-network-modules",
+      "source": "foundation/frames/src/axis_engine.hpp",
+      "members": {
+        "UNSPECIFIED": null,
+        "MJ2000EQ": "J2000",
+        "MJ2000EC": "MJ2000EC",
+        "ICRF": "ICRF",
+        "TEME": "TEME",
+        "MOD": "MOD",
+        "TOD": "TOD",
+        "MOE": "MOE",
+        "TOE": "TOE",
+        "BODY_FIXED": "BODY_FIXED",
+        "BODY_INERTIAL": "BODY_INERTIAL",
+        "OBJECT_REFERENCED": "OBJECT_REFERENCED",
+        "LOCAL_ALIGNED_CONSTRAINED": "LOCAL_ALIGNED_CONSTRAINED",
+        "EQUATOR": "EQUATOR",
+        "GSE": "GSE",
+        "GSM": "GSM",
+        "TOPOCENTRIC": "TOPOCENTRIC",
+        "BODY_SPIN_SUN": "BODY_SPIN_SUN",
+        "SPICE_DEFINED": "SPICE_DEFINED",
+        "MOD_FK5": "MOD_FK5",
+        "TOD_FK5": "TOD_FK5",
+        "ITRF": "ECEF"
+      }
+    },
+    {
+      "id": "modules.hpop.coords",
+      "description": "The HPOP propagator's internal chain vocabulary.",
+      "repo": "space-data-network-modules",
+      "source": "propagator/hpop/lib/coords_types.h",
+      "members": {
+        "TEME": "TEME",
+        "GCRF": "ICRF",
+        "ITRF": "ECEF",
+        "J2000": "J2000",
+        "ECEF": "ECEF",
+        "TOD": "TOD",
+        "MOD": "MOD"
+      }
+    }
+  ],
+  "rtnConvention": {
+    "abiMember": "OBJECT_REFERENCED",
+    "note": "The three live RTN triads collapse to ONE ABI member plus an axes spec. RIC, RSW and RTN name the SAME triad (x radial, z orbit normal, y completing); LVLH and VVLH are relabellings of it produced by naming a different primary. None of them is a separate ReferenceFrame, and adding a second RTN-named ABI member is a defect this check refuses.",
+    "aliases": [
+      "RIC",
+      "RSW",
+      "RTN",
+      "LVLH",
+      "VVLH",
+      "QSW",
+      "NTW",
+      "TNW",
+      "UVW"
+    ]
+  }
+}

package/schemas/orbpro/reference-frame.lock.json

@@ -0,0 +1,98 @@
+{
+  "note": "The committed numbering of the ONE ReferenceFrame enum that crosses the ABI seam. scripts/check-reference-frame-uniqueness.mjs holds schemas/orbpro/Propagator.fbs to this file: values 0-5 are FROZEN and no member may ever be renamed, renumbered or removed. Appending a member means appending a row here in the same commit.",
+  "frozenThrough": 5,
+  "members": [
+    {
+      "name": "TEME",
+      "value": 0
+    },
+    {
+      "name": "J2000",
+      "value": 1
+    },
+    {
+      "name": "ICRF",
+      "value": 2
+    },
+    {
+      "name": "ECEF",
+      "value": 3
+    },
+    {
+      "name": "MCI",
+      "value": 4
+    },
+    {
+      "name": "MCMF",
+      "value": 5
+    },
+    {
+      "name": "MJ2000EC",
+      "value": 6
+    },
+    {
+      "name": "MOD",
+      "value": 7
+    },
+    {
+      "name": "TOD",
+      "value": 8
+    },
+    {
+      "name": "MOE",
+      "value": 9
+    },
+    {
+      "name": "TOE",
+      "value": 10
+    },
+    {
+      "name": "BODY_FIXED",
+      "value": 11
+    },
+    {
+      "name": "BODY_INERTIAL",
+      "value": 12
+    },
+    {
+      "name": "OBJECT_REFERENCED",
+      "value": 13
+    },
+    {
+      "name": "LOCAL_ALIGNED_CONSTRAINED",
+      "value": 14
+    },
+    {
+      "name": "EQUATOR",
+      "value": 15
+    },
+    {
+      "name": "GSE",
+      "value": 16
+    },
+    {
+      "name": "GSM",
+      "value": 17
+    },
+    {
+      "name": "TOPOCENTRIC",
+      "value": 18
+    },
+    {
+      "name": "BODY_SPIN_SUN",
+      "value": 19
+    },
+    {
+      "name": "SPICE_DEFINED",
+      "value": 20
+    },
+    {
+      "name": "MOD_FK5",
+      "value": 21
+    },
+    {
+      "name": "TOD_FK5",
+      "value": 22
+    }
+  ]
+}

package/src/browser.js

@@ -29,6 +29,19 @@ export {
   zeroWasmBytes,
   isSharedArrayBufferLike,
 } from "./host/browserModuleHarness.js";
+// The wasi-threads BROWSER WORKER ANCHOR. A bundling consumer MUST tell the SDK
+// where its build serves the host worker chain from — `import.meta.url` inside a
+// bundle points at the bundle, not at the package layout, and the worker 404s
+// (fail-loud: WasiThreadWorkerUnreachableError). Either call
+// `setBrowserWasiThreadWorkerBase(...)` once in the host shim, or pass
+// `wasiThreadWorkerBaseUrl` to `createBrowserModuleHarness`.
+export {
+  setBrowserWasiThreadWorkerBase,
+  getBrowserWasiThreadWorkerBase,
+  resolveBrowserWorkerUrl,
+  DEFAULT_BROWSER_WORKER_URL,
+  WasiThreadWorkerUnreachableError,
+} from "./host/wasiThreadHost.js";
 // The runtime-target gate is reachable so a consumer can catch the refusal by
 // CLASS (`error instanceof RuntimeTargetError`) rather than by matching a
 // message string, and can ask the same question the loaders ask before it

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");
+}